Struct Database 

pub struct Database {
    pool: SqlitePool,
    db_path: PathBuf,
    db_dir: Option<PathBuf>,
}

Database handle providing synchronous API over async SQLx operations. Uses a bridge pattern with RUNTIME.block_on() to maintain synchronous interface for compatibility with existing single-threaded event loop.

Fields

pool: SqlitePool

db_path: PathBuf

The path to the database file.

db_dir: Option<PathBuf>

The directory containing the database file.

Will be empty if the database path is in-memory or has no parent directory.

Implementations

impl Database

pub fn new<P: AsRef<Path> + Debug>(path: P) -> Result<Self, Error>

Create a new database connection pool.

Does not run any migrations — call Database::init after construction.

Arguments

• path - Path to the SQLite database file (will be created if it doesn’t exist)

Returns

• Ok(Database) - Successfully connected database
• Err(Error) - Connection failure

pub fn close(&self)

Close all connections in the pool, checkpointing WAL and releasing file handles.

After calling this, no further database operations should be performed. This must be called before unmounting the filesystem that contains the database file, to ensure SQLite releases all file descriptors and flushes any pending WAL data.

pub fn pool(&self) -> &SqlitePool

Returns a reference to the SQLite connection pool.

pub fn migration_runner(&self) -> MigrationRunner

Returns a MigrationRunner bound to this database’s pool.

Use this to execute all registered runtime migrations after the database is initialized.

pub fn init(&mut self, backup_retention: usize) -> Result<(), Error>

Initialises the database for use by the application.

Performs, in order:

1. Integrity check (PRAGMA quick_check).
2. Version gate — detects upgrades, downgrades, and fresh installs.
3. Restore from backup if corruption or downgrade is detected.
4. Schema and runtime migrations.
5. Version stamp update.
6. Post-migration backup (when the version changes).

Must be called once after Database::new before the database is used. Intended for use in the synchronous startup path.

async fn restore_if_needed( &mut self, app_version: &GitVersion, ) -> Result<(), Error>

Checks integrity and the version gate, restoring a backup when either fails.

Corruption and downgrade are treated identically: close the pool, restore the best available backup for app_version, and reopen the pool so the caller can continue with migrations against a known-good database.

Returns an error if a restore is needed but no backup directory or compatible backup exists.

Invariant

db_path is always a real file path at the point where the pool is reopened. This is guaranteed because db_dir is None only for :memory: databases, which return early before reaching that point.

async fn create_version_backup( &self, app_version: &GitVersion, retention: usize, ) -> Result<(), Error>

Creates a versioned backup after migrations on every startup.

Skipped in test builds, when the database is in-memory (no db_dir), or when retention is zero.

async fn migrate(&mut self) -> Result<(), Error>

Runs schema migrations (sqlx) followed by runtime migrations.

async fn check_integrity(&self) -> Result<(), Error>

Runs a lightweight SQLite integrity check.

Checkpoints the WAL first so that any WAL corruption is caught and all WAL pages are flushed into the main file before PRAGMA quick_check runs. Without this, a corrupt WAL would be invisible to quick_check.

PRAGMA wal_checkpoint returns nullable integer columns (busy, log, checkpointed) that sqlx typed macros cannot map, so an untyped [sqlx::query()] with .execute() is used — only the success or failure of the checkpoint matters here.

Returns Ok(()) if both the checkpoint and PRAGMA quick_check succeed. On failure, logs the error and returns it so the caller can decide whether to restore.

Trait Implementations

impl Clone for Database

fn clone(&self) -> Database

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Database

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.