sqlite::connection

A sqlite::connection is the one-stop RAII wrapper around a raw sqlite3* handle. Opening or closing a database, checking the last inserted rowid, attaching extra files, or tweaking the shared statement cache all flow through this type. The wrapper enforces the project’s threading guideline: keep a connection bound to a single thread unless you explicitly opt into connection_pool.

Use cases

• Guarantees the handle is closed in the destructor, even if you forget to call close.
• Implements the “open modes” (read-only, existing-only, create, always-create) so failures are surfaced as rich database_exception variants.
• Owns the LRU statement cache; higher-level helpers such as query and execute reuse prepared statements by default.
• Provides attach/detach utilities that mirror SQLite’s SQL primitives but still honor filesystem adapters and error handling.

Example usage

sqlite::connection db{"/var/data/app.db",
                        sqlite::open_mode::open_or_create};

// Guarded by the destructor: transactions roll back when scope exits.
sqlite::transaction tx{db, sqlite::transaction_type::immediate};

sqlite::execute ddl{db, R\"SQL(
    CREATE TABLE IF NOT EXISTS settings(key TEXT PRIMARY KEY, value TEXT)
)SQL\", true};

sqlite::execute upsert{db, "INSERT OR REPLACE INTO settings VALUES(?, ?)"};
upsert % "timezone" % "UTC";
upsert();

tx.commit();

In tests I usually flip to open_mode::always_create and hand in a temp filesystem adapter so every run starts from an empty file.

enum class open_mode

• open_readonly — open an existing database for reads.
• open_existing — fail if the database is missing.
• open_or_create — create the database if it does not exist.
• always_create — remove any existing file before creating a new database.

Constructors & basic operations

Statement cache