SQLite bundles #

This page is for bundlers who ship Exponential on SQLite 3, the default database. SQLite removes the database server from the bundle: nothing to install, start, secure or update separately.

Contents #

1. Why SQLite suits bundles
2. What the driver adds
3. Files and permissions
4. The one-host rule
5. Backups
6. When to offer a server instead

Why SQLite suits bundles #

• "SQLite 3 is the default. The setup wizard preselects it, exp:install uses it when no --db is given, and the kickstarter's template names it first. It needs no database server: the whole content repository is one file" (Database support).
• "With the driver Exponential ships it is a full production database for a site served from one machine."
• exp:install without options installs on SQLite with the file exponential.db (Install in one command).

What the driver adds #

From 1. SQLite 3, the default:

• write-ahead logging, "so page views keep reading while an editor publishes";
• connection PRAGMAs chosen for a web server;
• since 6.0.15, a write queue: "every transaction takes an exclusive lock on <database>.writer-lock and then runs BEGIN IMMEDIATE, so concurrent publishes wait their turn (up to SQLiteTransactionWait seconds, default 25)".

Files and permissions #

"The database is four files: the database, -wal, -shm and .writer-lock. Every process that uses the site (the web server's PHP, Velocity's workers, cronjobs, console commands) must be able to write the directory and the files; give them one common group, the directory mode 2775 and a umask of 0002. Never serve the directory over HTTP (the shipped rewrite rules do not)."

For a bundle:

• To do: var/storage/sqlite3/ exists and belongs to the site's user (or the common group) in the image.
• To do: The installer runs as that user.
• To do: Cron and console commands run as that user.
• To do: The web server configuration you ship keeps the routing of the shipped rules (Web server examples).

The one-host rule #

"Choose a database server instead when more than one machine must write the database (WAL needs shared memory on one host, so a network file system is not a substitute)". For containers: "With SQLite, run one container that writes" (Containers).

A bundle on SQLite should say so plainly in its documentation, so nobody scales it to three replicas on a shared volume.

Backups #

The backup set of any installation is "the database and var/storage, settings/override and settings/siteaccess" (Containers). For SQLite, back up the database consistently rather than copying a file in the middle of a write; the methods are in SQLite for hosts: Backup and restore and Chapter 9.2.

When to offer a server instead #

A bundle can offer both: SQLite by default, PostgreSQL by option (--db=pgsql), with the switch documented. Changing the database engine covers moving later.

Related pages #

• Database choices for bundles
• SQLite for hosts
• Education and demo bundles
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.