{
    "title": "Why flat files outlive databases",
    "uri": "notes/why-flat-files",
    "url": "/notes/why-flat-files",
    "template": "note",
    "date": "2026-02-14T00:00:00+00:00",
    "description": "A database is a promise about the future that most projects cannot keep. A folder of text files is a much smaller promise.",
    "tags": [
        "architecture",
        "content"
    ],
    "html": "<p>Ask anyone who has migrated a ten-year-old site and they will describe the same afternoon: an export that half worked, entities that meant something in 2016, and a foreign key nobody remembers adding.</p>\n<h2 id=\"the-failure-mode-is-silence\">The failure mode is silence</h2>\n<p>Databases fail quietly. A dropped column does not raise an alarm; it simply stops appearing. A folder of text files fails loudly and locally — you open the file and the paragraph is either there or it isn&#039;t.</p>\n<h2 id=\"what-you-actually-give-up\">What you actually give up</h2>\n<p>Being honest about it, flat files cost you three things:</p>\n<ol>\n<li><strong>Relational queries.</strong> If your content is genuinely a graph, use a database.</li>\n<li><strong>Concurrent writes at scale.</strong> Two editors saving the same page in the same second is a real problem — file locks help, but they are not a transaction log.</li>\n<li><strong>Full-text search over millions of rows.</strong> Below a few thousand pages, scanning is fast enough. Above that, index externally.</li>\n</ol>\n<blockquote><p>If none of those three describe your project — and for a portfolio, a magazine or a documentation site they usually don&#039;t — the database is a dependency you are carrying for someone else&#039;s problem.</p></blockquote>\n<h2 id=\"what-you-get-back\">What you get back</h2>\n<p>Version control that means something. <code>git diff</code> on a paragraph reads like a paragraph, not like a binary blob. Backups that are a <code>cp -r</code>. Staging that is a second folder.</p>\n<p>And the thing nobody advertises: you can hand the content to a person who does not use your CMS, and they can still read it.</p>",
    "text": "Ask anyone who has migrated a ten-year-old site and they will describe the same afternoon: an export that half worked, entities that meant something in 2016, and a foreign key nobody remembers adding.\n\n## The failure mode is silence\n\nDatabases fail quietly. A dropped column does not raise an alarm; it simply stops appearing. A folder of text files fails loudly and locally — you open the file and the paragraph is either there or it isn't.\n\n## What you actually give up\n\nBeing honest about it, flat files cost you three things:\n\n1. **Relational queries.** If your content is genuinely a graph, use a database.\n2. **Concurrent writes at scale.** Two editors saving the same page in the same second is a real problem — file locks help, but they are not a transaction log.\n3. **Full-text search over millions of rows.** Below a few thousand pages, scanning is fast enough. Above that, index externally.\n\n> If none of those three describe your project — and for a portfolio, a magazine or a documentation site they usually don't — the database is a dependency you are carrying for someone else's problem.\n\n## What you get back\n\nVersion control that means something. `git diff` on a paragraph reads like a paragraph, not like a binary blob. Backups that are a `cp -r`. Staging that is a second folder.\n\nAnd the thing nobody advertises: you can hand the content to a person who does not use your CMS, and they can still read it.",
    "cover": {
        "filename": "cover.jpg",
        "url": "/media/notes/why-flat-files/cover.jpg",
        "type": "image",
        "size": 98288,
        "niceSize": "96 KB",
        "width": 1600,
        "height": 900,
        "alt": "Indigo gradient suggesting layered strata"
    },
    "files": [
        {
            "filename": "cover.jpg",
            "url": "/media/notes/why-flat-files/cover.jpg",
            "type": "image",
            "size": 98288,
            "niceSize": "96 KB",
            "width": 1600,
            "height": 900,
            "alt": "Indigo gradient suggesting layered strata"
        }
    ],
    "children": []
}