Crate puerto_sqlx 

The Postgres adapter every Puerto project with a database shares (ADR-0017): the connection pool, migrations at startup, the readiness ping and the one mapping from driver errors to RepositoryError.

The migrations are the project’s own: sqlx::migrate! embeds a directory at compile time, so the project declares its Migrator and hands it over. A generated infrastructure/src/db.rs is

pub use puerto_sqlx::*;

pub static MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate!("./migrations");

and its repositories call crate::db::map_sqlx_error.

A project with domain events (ADR-0018) also uses uow::PgTransaction in its generated units of work, and its worker the outbox, the db transport and the dead-letter sink in events. Their tables are OUTBOX_MIGRATION, which puerto new --events writes into the project.

A worker that sends mail (ADR-0020) keeps what it sent in mail::PgSentMails, over SENT_MAILS_MIGRATION.

A project with local accounts (ADR-0021 § 2) keeps their passwords and sessions in auth::PgCredentials and auth::PgSessions, over USERS_MIGRATION and AUTH_MIGRATION.

Modules

auth

Local accounts (ADR-0021 § 2): the sessions login opens and the password hashes it checks. Their tables are crate::USERS_MIGRATION and crate::AUTH_MIGRATION, which puerto new --auth local writes into the project.

events

The Postgres side of domain events (ADR-0018 § 4): the outbox the relay reads, the db transport (event_deliveries) and the dead-letter sink every transport writes to. The tables are migrations/outbox.sql, which puerto new --events writes into the project.

mail

The sent-mail log (ADR-0020): which mails a worker consumer already sent for which event. Its table is crate::SENT_MAILS_MIGRATION, which the first puerto generate mail --on writes into the project.

uow

The Postgres side of a generated unit of work (ADR-0018 § 2): one transaction that saves an aggregate and records its events in the outbox. A generated Pg{Entity}UnitOfWork wraps a PgTransaction and only writes its entity’s upsert, through PgTransaction::tx.

Enums

DatabaseError

Why the database could not be used at startup — read by the person starting the process, so it says where and why, never the password.

Constants

AUTH_MIGRATION

The credentials and sessions of local accounts (migrations/auth.sql), after USERS_MIGRATION. Puerto’s CLI ships a byte-for-byte copy of it as a project migration.

OUTBOX_MIGRATION

The outbox, delivery and dead-letter tables (migrations/outbox.sql). Puerto’s CLI ships a byte-for-byte copy of it as a project migration.

SENT_MAILS_MIGRATION

The sent-mail log (migrations/sent_mails.sql). Puerto’s CLI ships a byte-for-byte copy of it as a project migration.

USERS_MIGRATION

The users every auth project has (migrations/users.sql): auth::PgSessions reads it, so its schema is part of this crate’s contract. Puerto’s CLI ships a byte-for-byte copy of it as a project migration.

Functions

create_postgres_pool

map_sqlx_error

The one place that knows Postgres error codes: a driver error, as the repository port speaks it. The caller logs it first, with its own context.

ping

Whether the database answers a trivial query — what /health/ready reports.

run_migrations

Applies the project’s pending migrations — migrator is its sqlx::migrate!("./migrations").