Struct PgBackend 

pub struct PgBackend { /* private fields */ }

A PostgreSQL database behind an sqlx pool.

Implementations

impl PgBackend

pub async fn migrate( &self, migrations: &[Migration], ) -> Result<MigrateReport, MigrateError>

Apply migrations in version order, skipping those already applied, in the ledger _sqlx_migrations of the connection’s current schema. See Migrates::migrate.

pub async fn verify_fresh( &self, migrations: &[Migration], ) -> Result<MigrateReport, MigrateError>

Prove that migrations install on an empty schema, in order, and leave nothing behind.

A scratch schema with a unique name is created, the migrations run in it on a pool of one connection whose search_path is that schema (so the ledger is the scratch schema’s own), and the schema is dropped afterwards, whether the run passed or failed. The report lists every version as applied. The database being installed to is never touched: not its ledger, not its tables.

Limits: a migration that names another schema explicitly, or creates an extension, role or other cluster-wide object, escapes the scratch schema; that is not detected. This is the PostgreSQL driver only.

pub async fn fresh_catalog( &self, migrations: &[Migration], ) -> Result<Snapshot, MigrateError>

As verify_fresh, and read the scratch schema’s catalog before it is dropped: the schema migrations produce, from migrations and a server, without touching the target. The snapshot is stamped with the versions and checksums it was derived from.

pub async fn applied_versions(&self) -> Result<Vec<i64>, MigrateError>

The versions the ledger says succeeded, ascending; empty if there is no ledger yet.

pub async fn applied_checksums( &self, ) -> Result<Vec<(i64, Vec<u8>)>, MigrateError>

The ledger’s rows that succeeded, (version, checksum) ascending; empty if there is no ledger yet. Reads the same rows Migrates::migrate checks against, so a caller can compare a directory of migrations with a database without applying anything.

impl PgBackend

pub async fn connect_with( secret: &ConnectionSecret, options: &ConnectOptions, ) -> Result<Self, RelError>

Connect with an explicit TLS policy and pool bounds, to a connection string held as a ConnectionSecret (resolved here, never printed).

pub async fn connection_is_encrypted(&self) -> Result<bool, RelError>

Whether the connection this backend uses is encrypted, as the server reports it (pg_stat_ssl), not as the client was asked.

impl PgBackend

pub async fn connect(url: &str) -> Result<Self, RelError>

Connect with default pool settings and read the server version.

Prefer PgBackend::connect_secret: a &str URL is one Debug print from a log file.

pub async fn connect_secret(secret: &ConnectionSecret) -> Result<Self, RelError>

Connect with a connection string held as a persistant_relational::ConnectionSecret: resolved here, never printed, never part of an error.

pub async fn from_pool(pool: PgPool) -> Result<Self, RelError>

Wrap an existing pool (a program that already owns one keeps it).

pub fn pool(&self) -> &PgPool

The concrete pool: for sqlx::query! and anything this layer does not carry.

Trait Implementations

impl Clone for PgBackend

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PgBackend

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

Formats the value using the given formatter.

impl Migrates for PgBackend

async fn migrate( &self, migrations: &[Migration], ) -> Result<MigrateReport, MigrateError>

Apply migrations in version order, skipping those already applied. Each migration runs in its own transaction where the database can; refuses (applying nothing further) if an applied migration’s text has changed, if the database has applied a version the program does not know, or if a migration is recorded as dirty.

async fn applied_versions(&self) -> Result<Vec<i64>, MigrateError>

The versions the ledger says succeeded, ascending; empty if there is no ledger yet.

impl RelationalBackend for PgBackend

type Tx<'a> = PgTx<'a>

A transaction on this backend. Dropping it without commit rolls it back.

fn backend(&self) -> &str

The backend’s name as it appears in matrix rows (postgres).

fn version(&self) -> &str

The server version string as it appears in matrix rows (16.15).

fn dialect(&self) -> Dialect

The dialect statements must be written in.

async fn execute(&self, sql: &str, params: &[Value]) -> Result<u64, RelError>

Run a statement that returns no rows; the result is the number of rows affected.

async fn query(&self, sql: &str, params: &[Value]) -> Result<Vec<Row>, RelError>

Run a statement and return its rows.

async fn begin(&self, isolation: Isolation) -> Result<PgTx<'_>, RelError>

Begin a transaction at (at least) isolation.

fn call_bound(&self) -> Option<Duration>

The per-call timeout this backend enforces, if one is configured; None (the default) means a call waits as long as the server does. Every call that takes longer returns RelError::Timeout.

fn with_lock_held<'a>( &'a self, lock_sql: &'a str, at_most: Duration, during: Pin<Box<dyn Future<Output = ()> + Send + 'a>>, ) -> impl Future<Output = Result<(), RelError>> + Send

Test support for kv.bounded_call: take lock_sql (a statement that locks a row) in a transaction of its own, drive during while that lock is held, then roll back. during is dropped, unfinished, after at_most, so a broken bound cannot hang the test. A backend that enforces no bound returns RelError::Unsupported.