Struct Postgres 

pub struct Postgres { /* private fields */ }

Implementations

impl Postgres

pub async fn tenant_status( &self, tenant: &str, ) -> Result<Option<TenantStatus>, DbError>

The status the registry records for tenant, or None when there is no row.

A status this binary does not know reads as TenantStatus::Degraded here: TenantStatus::parse is fail-closed on purpose, and this read inherits that — an unknown word is a refusal at request time, not a guess.

Errors

DbError when the read fails (including when the registry has not been bootstrapped yet).

impl Postgres

pub async fn apply_migrations( &self, module: &str, migrations: &[SqlMigration], ) -> Result<(), DbError>

Applies a module’s unapplied migrations in id order, tracked under <module>/<id> in a harness_migrations table; each migration runs in its own transaction so a failure rolls back atomically and re-running is idempotent. Mirrors SqliteDatabase::apply_migrations exactly.

Errors

DbError::Batch when the tracking DDL or a migration’s SQL fails, or when the bookkeeping insert cannot be rendered.

pub async fn apply_harness_migrations( &self, harness: &Harness, ) -> Result<(), DbError>

Applies every module’s migrations for a whole harness, in lock order: modules in harness (config) order, each set by zero-padded migration id — the order fz migrations collect pins in .harness-lock.json. For each module the postgres set applies when shipped, else the sqlite set when it passes the portable lint (select_set).

Errors

DbError::Batch when a module’s sqlite set fails the lint or any migration fails to apply.

impl Postgres

pub async fn bootstrap_registry(&self) -> Result<(), DbError>

Creates the harness_tenants registry on the control database, idempotently. Boot calls this first; a failure here aborts the boot (there is no registry to read, no DSN to resolve).

Errors

DbError when the DDL fails.

pub async fn register_tenant( &self, tenant: &str, dsn: &str, ) -> Result<(), DbError>

Registers (or re-points) a tenant: upsert the DSN and reset the status to provisioning — the next boot’s reconciliation is what promotes it to active.

An archived tenant is never re-registered. Archiving means the database was dropped and the data keys destroyed (docs/TENANT-ONBOARDING.md §2); re-registering the same id would mint a tenant that the registry says is the old one and that no export can reconstitute. The guard is the WHERE on the conflict branch, so it is decided by the database and not by a read the caller might race.

Errors

DbError when the write fails, and DbError::Execute naming the tenant when the row is archived.

pub async fn tenants(&self) -> Result<Vec<TenantRecord>, DbError>

Every tenant in the registry, newest DSN wins. The values come from the control database and include the DSN: callers log or serve with them, never print them.

Errors

DbError when the read fails.

pub async fn set_tenant_status( &self, tenant: &str, status: TenantStatus, ) -> bool

Records a tenant’s status, if the lifecycle allows the move.

Answers whether the row changed. Best-effort by design (RECONCILIATION.md §6): a write that fails mid-boot still leaves the tenant refused at request time, because its pool was never registered. The answer is for the caller that wants to say so — false covers both “the database would not take it” and “the lifecycle does not allow it”, which are the same thing to a caller: the tenant is not in the status it just asked for.

The legal previous statuses are TenantStatus::admits, so archived stays terminal (it admits nothing, itself included) and an offboarding tenant cannot be flipped back to active by a reconciler while its keys are being shredded.

pub async fn reconcile_tenant( &self, record: &TenantRecord, harness: &Harness, ) -> Result<TenantReport, DbError>

Reconciles one tenant: take the advisory lock, then apply every module’s migrations to the tenant’s database in depends_on order. On any failure the tenant is marked degraded in the control database (best-effort) and the error is returned; the caller decides whether that aborts the boot (strict).

The tenant DSN is never part of any error message: connection strings carry credentials.

Errors

DbError when the tenant’s database is unreachable or a migration fails.

pub async fn reconcile_fleet( &self, harness: &Harness, parallelism: usize, ) -> Result<Vec<TenantReport>, DbError>

Reconciles every tenant in the registry whose status is active or provisioning, at most parallelism at a time (default 8; #30 §10 keeps the right number a measured question). A degraded tenant is left for the retry timer, not re-flown this boot; an offboarding or archived one is never flown again at all.

This is what boot calls. The control database drives everything: if it cannot be bootstrapped or read, the error returns and the boot aborts — there is nothing useful to serve without a registry. A tenant that fails is marked degraded and every other tenant serves; the same with strict semantics is the caller’s decision (any Degraded in the reports).

Errors

DbError when the control database cannot be bootstrapped or read. Per-tenant failures never abort the fleet.

pub async fn reconcile_plan( &self, record: &TenantRecord, harness: &Harness, ) -> Result<TenantPlan, DbError>

What would be applied, per module, for one tenant. Takes the same advisory lock, so the answer is not a guess about a moving target (RECONCILIATION.md §8), and applies nothing.

Errors

DbError when the tenant’s database is unreachable.

impl Postgres

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

Opens a pool and establishes at least one connection, failing fast on an unreachable server or bad credentials.

Uses PoolLimits::default. A multi-tenant deployment wants Postgres::connect_with instead: one pool per tenant with no cap is how one busy tenant takes every connection on a shared cluster.

Errors

DbError::Execute when the pool cannot connect.

pub async fn connect_with( url: &str, limits: PoolLimits, ) -> Result<Self, DbError>

Opens a pool with explicit limits (TENANT-ROUTING.md §4).

sqlx caps and times out per pool, which is exactly the per-tenant boundary: a pool belongs to one tenant. The total across pools is not something sqlx can express, so it is not pretended to here — it needs a semaphore held by whatever owns the pools, acquired around every execute, query and batch. A config key that silently did nothing would be worse than its absence.

Errors

DbError::Execute when the pool cannot connect.

pub async fn close(&self) -> Result<(), DbError>

Closes the pool: waits for in-flight queries, then closes every connection. Dropping the adapter eventually closes the pool too; close makes shutdown deterministic for the parity kit and the native runtime.

Errors

DbError::Execute when the pool cannot be closed.

Trait Implementations

impl Clone for Postgres

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Database for Postgres

fn batch_atomic<'life0, 'life1, 'async_trait>( &'life0 self, stmts: &'life1 [Statement], ) -> Pin<Box<dyn Future<Output = Result<(), DbError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Runs all statements in one transaction (atomic on Postgres).

fn execute<'life0, 'life1, 'async_trait>( &'life0 self, stmt: &'life1 Statement, ) -> Pin<Box<dyn Future<Output = Result<u64, DbError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn query<'life0, 'life1, 'async_trait>( &'life0 self, stmt: &'life1 Statement, ) -> Pin<Box<dyn Future<Output = Result<Rows, DbError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

impl TenantLifecycle for Postgres

fn create<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, tenant: &'life1 str, dsn: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), TenantLifecycleError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Registers a tenant: the row is inserted, or an existing non-archived row is re-pointed at dsn, and the status lands on TenantStatus::Provisioning — the next reconciliation is what promotes it.

fn status<'life0, 'life1, 'async_trait>( &'life0 self, tenant: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<TenantStatus, TenantLifecycleError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The status the registry records for tenant.

fn tenants<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<TenantSummary>, TenantLifecycleError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Every row of the registry, as TenantSummarys — no DSNs.

fn set_status<'life0, 'life1, 'async_trait>( &'life0 self, tenant: &'life1 str, next: TenantStatus, ) -> Pin<Box<dyn Future<Output = Result<(), TenantLifecycleError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Moves the tenant’s status, if TenantStatus::can_become allows the move.

fn begin_erasure<'life0, 'life1, 'async_trait>( &'life0 self, tenant: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<ErasureStep>, TenantLifecycleError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Begins an erasure: moves the tenant to TenantStatus::Offboarding and returns the steps of docs/TENANT-ONBOARDING.md §2 still outstanding, in order, so the caller can work down the list without keeping its own copy of the table.

fn complete_erasure<'life0, 'life1, 'async_trait>( &'life0 self, tenant: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), TenantLifecycleError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Completes an erasure: records TenantStatus::Archived.