{"canonical_url":"https://engineer.company/glossary/sqlite/","content_markdown":"# SQLite\n\n## What it is\n\nSQLite is an SQL database engine that runs inside the program using it, as a\nlibrary, with no server process, no network port and no administrator, and keeps\nits tables, indexes, triggers and views together in one ordinary file on disk.\nThe name also appears as `sqlite3`: that is what the command-line shell is\ncalled and the prefix every function in its C interface carries. The one C\nsource file the project ships is named `sqlite3.c`. The project's own summary\nis that it is self-contained, serverless, zero-configuration and transactional,\nand it asks to be compared with `fopen()` rather than with Oracle. What it\nreplaces is the home-made data file, not the database server.\n\nThe project began on 9 May 2000, and the code is in the public domain, so there\nis no licence to clear before shipping it inside a product. The file format is\npart of the bargain. A database written on a 32-bit machine can be copied to a\n64-bit one, or between big-endian and little-endian processors, and opened\nunchanged. The developers say they intend to support SQLite through the year\n2050, and the US Library of Congress lists its files as a recommended format for\nkeeping data. With every feature enabled the library can be smaller than 900KiB,\nwhich is why it sits inside phones, cars, watches and desktop applications as\nwell as on servers.\n\nInside, it is a complete SQL engine: joins, subqueries, views, triggers, and\ntransactions that stay atomic, consistent, isolated and durable even when the\npower fails halfway through a write. Two design choices set it\napart from server databases. The first is concurrency. Any number of\nconnections may read at once, but only one may write at any instant, and the\nlock covers the whole file. The second is typing. A column's declared type is a\npreference, which SQLite calls affinity, and the type actually belongs to each\nvalue, so a column declared `INTEGER` will accept text that does not look like a\nnumber.\n\nAgainst the alternatives, the line is clean. PostgreSQL, MySQL and SQL Server\nare shared services that many machines talk to over a network. SQLite is a\nprivate store for one application on one host. Against CSV or JSON files, it\nadds a query language, indexes, constraints and transactions, at the price of\none dependency that most languages already bundle.\n\n## Why it matters\n\nFor a large share of software the hard question about a database is not how\nfast it is, but who runs it. A server needs installing, upgrading, securing,\nmonitoring and backing up, and somebody has to be paid to do all of that.\nSQLite removes the whole category. Opening a database is opening a file, a\nbackup is a copy of that file, taken through the backup API while it is in use,\nand a test suite can give every test a fresh database of its own.\n\nIt also changes what a file can be. A program that would otherwise invent a\nformat, write a parser for it and hope that a crash never lands mid-save can\nstore its state in SQLite and get atomic saves for free. The project names this\nuse directly: as an application file format, as a container for moving data\nbetween systems, where the receiver runs SQL instead of writing a parser, and\nas a scratch database for sorting and summarising data that arrived in some\nother shape.\n\nThe decision that matters is narrow, and it can be checked before a line of\ncode is written: how many processes write, and on how many machines? One\nprogram on one host, writing in short bursts, is SQLite's home ground, and\nplenty of websites with low to medium traffic run on it comfortably. Several\nservers writing to the same data, or a workload where many users write at\nevery moment, belong on a client-server database. Size is rarely what decides\nit, since one file can hold up to 281 terabytes. The writer count is.\n\nThere are costs to weigh even inside that home ground. `ALTER TABLE` supports\nonly renaming a table or a column and adding or dropping a column, so most\nother changes to a table's shape mean building a new table, copying the rows\nacross and swapping the names. Foreign keys are switched off until each\nconnection switches them on. And loose typing lets bad data in quietly, unless\na table is declared to refuse it.\n\n## What it looks like in practice\n\nAt the documented development stage, twenty-three tables in one SQLite file,\nfrom achievements and companies to profiles and references, were the source of\ntruth for a generator of CVs, reference sheets, portfolios and cover letters.\n[One command turned an empty SQLite file into that database](/portfolio/built-a-database-driven-cv-generator/)\nin nineteen ordered steps, and because each step could safely run twice, a\nrebuild over a database that already existed added no duplicate rows. The six\noutput formats came from 41 Python modules of 10,580 lines that read that one\nfile, with exactly two runtime dependencies. A document aimed at one kind of\nreader was a query over the achievements, chosen by a profile, rather than an\nedited copy. The price was plain: the system had become the only way to produce\na document.\n\nAt the documented export stage, the same database was also a build input,\nbecause this website's own portfolio was generated from it.\n[An exporter opened the SQLite file read-only and wrote 495 pages](/portfolio/generated-495-pages-from-a-sqlite-export/)\nin three languages, using only Python's standard library, and the output was\ncommitted so the site could build without the generator's environment. Page\naddresses were stored as rows, one per address per achievement, so rewording a\nsentence no longer moved a page. That work also turned up the trap described in\nthe next section: a period comparison against a text column matched all\nthirty-two rows.\n\nThe smallest role, a place to look at results, is also the most typical. A\npipeline that turned raw electricity readings into hourly consumption per zone\nwrote its results either as CSV or\n[into a lightweight SQLite database for inspection](/portfolio/a-month-of-meter-readings-in-180-milliseconds/),\nand the Python version processed a day of data in 34ms and thirty days in\n180ms. A database used that way needs no setup at all: anyone with the\n`sqlite3` shell can open the file and query it.\n\n## Where it goes wrong\n\nMost SQLite trouble comes from treating it as a small PostgreSQL. It is a\ndifferent machine with different edges.\n\n**A filter on the year matches every row.** SQLite converts a value before a\ncomparison only when one side carries an affinity. A function result such as\n`substr()` carries none, and neither does a bare number, so SQLite compares the\ntext `'2019'` with the integer `2025` as they stand, and in its sort order every\nnumber comes before every piece of text:\n\n```sql\nCREATE TABLE stint (period TEXT, hours TEXT);\nINSERT INTO stint VALUES\n  ('2019-03', '9'), ('2024-11', '10'), ('2026-01', '42');\n\nSELECT count(*) FROM stint\nWHERE substr(period, 1, 4) \u003e= 2025;                   -- 3\n\nSELECT count(*) FROM stint\nWHERE CAST(substr(period, 1, 4) AS INTEGER) \u003e= 2025;  -- 1\n```\n\nCast explicitly wherever text meets a number. For new tables, declare real\ntypes and add the `STRICT` keyword, available since version 3.37.0: a strict\n`INTEGER` column still accepts `'42'` and stores it as a number, and it rejects\n`'ten'` with an error instead of storing it.\n\n**Writes start failing with “database is locked”.** One connection is holding\nthe write lock, and a second writer either waits or gives up at once. The cause\nis usually a long transaction, or a reader in the default rollback-journal mode\nholding up a writer. Switch the database to write-ahead logging, where readers\nand the writer stop blocking each other, keep write transactions short, and set\na busy timeout so a writer waits briefly instead of erroring. If the writers\nare genuinely many and constant, that is the signal to move to a server.\n\n**The file corrupts on a shared drive.** SQLite depends on the operating\nsystem's file locks, and many network filesystems implement those locks with\nbugs, so two machines can end up writing the same part of the file at once.\nWrite-ahead logging does not work over a network filesystem at all, because\nevery process using the database has to share memory on one host. Keep the\ndatabase on a disk local to the one program that writes it, and put a server in\nfront of it if other machines need the data.\n\n**A row outlives the parent it points at.** Foreign key constraints are\ndeclared in the schema but stay inactive until each connection runs\n`PRAGMA foreign_keys = ON`, so a delete in a connection that skipped the pragma\nleaves orphans behind without complaint. Set the pragma wherever the\napplication opens a connection, in the one place that does so, and test that\nit is on.\n\n## Further reading\n\n- [About SQLite](https://sqlite.org/about.html)\n  — the project's own description: in-process, serverless, public domain,\n  one cross-platform file.\n- [Datatypes In SQLite](https://sqlite.org/datatype3.html)\n  — storage classes, type affinity and the comparison rules behind the trap\n  above.\n- [STRICT Tables](https://sqlite.org/stricttables.html)\n  — how to make a table enforce its declared column types.\n- [Write-Ahead Logging](https://sqlite.org/wal.html)\n  — readers and a writer in parallel, and why it stays on one host.\n- [Appropriate Uses For SQLite](https://sqlite.org/whentouse.html)\n  — where it fits, where a client-server database fits better, and a checklist.\n- [SQLite Foreign Key Support](https://sqlite.org/foreignkeys.html)\n  — why constraints are off by default and how to switch them on.\n\n\u003chttps://engineer.company/glossary/sqlite/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"SQLite swaps a database server for a library and a file: the right call for one writer on one host, with loose typing that can quietly mislead.","formats":{"gemtext":"https://engineer.company/glossary/sqlite/index.gmi","gopher":"https://engineer.company/glossary/sqlite/gophermap","html":"https://engineer.company/glossary/sqlite/","json":"https://engineer.company/glossary/sqlite/index.json","markdown":"https://engineer.company/glossary/sqlite/index.md","pdf":"https://engineer.company/glossary/sqlite/index.pdf"},"kind":"page","language":"en","title":"What is SQLite?","url":"https://engineer.company/glossary/sqlite/","version":1}