Enum Database 

pub enum Database {
    Sqlite(Pool<Sqlite>),
    Postgres(Pool<Postgres>),
}

The connection pool, and the only way to reach it.

The pool is private to this crate: everything else goes through a table module, Database::transaction or Database::pool_stats. That is what keeps SQL — and the dialect it is written in — in one crate.

Variants

Sqlite(Pool<Sqlite>)

Postgres(Pool<Postgres>)

Implementations

impl Database

pub fn dialect(&self) -> Dialect

Which dialect this database speaks.

pub fn exec(&self) -> Exec<'_>

This database as a target for one statement.

pub async fn transaction(&self) -> Result<Tx, Error>

Begins a transaction.

pub async fn write_transaction(&self) -> Result<Tx, Error>

Begins a transaction that holds the write lock from its first statement (BEGIN IMMEDIATE), for one that reads and then writes on what it read while another process may be writing.

A plain transaction is deferred: it takes a read snapshot at its first SELECT and asks for the write lock only at its first write. In WAL mode, if another connection committed in between, that upgrade fails at once with SQLITE_BUSY_SNAPSHOT — busy_timeout cannot help, since waiting would not make the snapshot current. Taking the lock up front makes the transaction wait its turn under busy_timeout instead, and then read what it writes against.

pub fn pool_stats(&self) -> PoolStats

The pool’s size and idle count, read now rather than tracked.

pub async fn close(&self)

Closes the pool: every later query fails with PoolClosed.

Waits for checked-out connections to be returned. Also how a test simulates the database going away underneath a running server.

pub async fn open(url: &str) -> Result<Database, Error>

Opens the database at url, whose scheme picks the backend. Does not migrate.

sqlite: creates the file if it is not there yet, and pins the two pragmas the schema depends on. postgres:/postgresql: expects the database to exist — creating one is a privileged act an operator performs, not something a server does to a cluster it was pointed at. Any other scheme is refused by name here, rather than as a driver error several frames down.

Applying the schema is a separate, named act: migrate, acme-proxy migrate, or the worker role at startup. It used to happen here, which meant every subcommand — audit list, completions, a health check — silently upgraded the schema of whatever database it was pointed at, and two processes starting together raced MIGRATOR::run with no lock between them (SQLite gives sqlx none; PostgreSQL does, an advisory lock, so there the one-owner rule is belt and braces).

A caller that needs the schema present asks pending_migrations and refuses by name, or uses connect_and_migrate.

pub async fn connect_and_migrate(url: &str) -> Result<Database, Error>

open followed by migrate.

For the two callers that own the schema — acme-proxy migrate and acme-proxy init — and for tests over a file-backed database, which want the same thing in one step.

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

Applies every embedded migration that has not run yet.

Idempotent: sqlx tracks each file by version and checksum, so running this against an up-to-date database does nothing.

pub async fn pending_migrations(&self) -> Result<Vec<i64>, Error>

The versions of the embedded migrations this database has not applied.

Empty means the schema is current. What the roles that must not migrate check before serving, so an unmigrated database stops them by name rather than failing later as a missing table.

A database with no _sqlx_migrations table has applied nothing — that is a freshly created file, not an error.

pub async fn connect_in_memory() -> Result<Database, Error>

Builds a throwaway in-memory database with migrations applied. Pinned to a single connection so the whole test shares one in-memory database (each SQLite connection otherwise gets its own).

impl Database

pub async fn transfer_to( &self, target: &Database, ) -> Result<TransferReport, Error>

Copies every row of this database into target.

The whole copy is one transaction on the target, so a failure anywhere leaves it exactly as it was rather than half-populated. The source is only read.

The caller is responsible for the two things this cannot check: that target’s schema is current (ask Database::pending_migrations) and that nothing is writing to the source. See the module doc.

Trait Implementations

impl<'a> From<&'a Database> for Exec<'a>

fn from(database: &'a Database) -> Self

Converts to this type from the input type.