Skip to main content

Crate puerto_sqlx

Crate puerto_sqlx 

Source
Expand description

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 ErrorRepositorio.

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 project’s migrador crate is

ⓘ
pub static MIGRADOR: sqlx::migrate::Migrator = sqlx::migrate!("../migraciones");

and its repositories call puerto_sqlx::mapear_error_sqlx.

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

A worker that sends mail (ADR-0020) keeps what it sent in correo::CorreosEnviadosPostgres, over MIGRACION_CORREOS_ENVIADOS.

A project with local accounts (ADR-0021 § 2) keeps their passwords and sessions in auth::CredencialesPostgres and auth::SesionesPostgres, over MIGRACION_USUARIOS and MIGRACION_AUTH.

Modules§

auth
Local accounts (ADR-0021 § 2): the sessions login opens and the password hashes it checks. Their tables are crate::MIGRACION_USUARIOS and crate::MIGRACION_AUTH, which puerto new --auth local writes into the project.
correo
The sent-mail log (ADR-0020): which mails a worker consumer already sent for which event. Its table is crate::MIGRACION_CORREOS_ENVIADOS, which the first puerto generate correo --on writes into the project.
eventos
The Postgres side of domain events (ADR-0018 § 4): the outbox the relay reads, the db transport (entregas_eventos) and the dead-letter sink every transport writes to. The tables are migrations/outbox.sql, which puerto new --eventos 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 TransaccionPostgres and only writes its entity’s upsert, through TransaccionPostgres::tx.

Structs§

ClaveForanea
A foreign key a repository writes through: the constraint’s name in the migration and the field it checks (ADR-0022).

Enums§

ErrorBaseDatos
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§

MIGRACION_AUTH
The credentials and sessions of local accounts (migrations/auth.sql), after MIGRACION_USUARIOS. Puerto’s CLI ships a byte-for-byte copy of it as a project migration.
MIGRACION_CORREOS_ENVIADOS
The sent-mail log (migrations/sent_mails.sql). Puerto’s CLI ships a byte-for-byte copy of it as a project migration.
MIGRACION_OUTBOX
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.
MIGRACION_USUARIOS
The users every auth project has (migrations/users.sql): auth::SesionesPostgres 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§

crear_pool_postgres
ejecutar_migraciones
Applies the project’s pending migrations — migrator is its sqlx::migrate!("./migrations").
mapear_error_sqlx
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. An entity with references converts with mapear_error_sqlx_con instead.
mapear_error_sqlx_con
mapear_error_sqlx, knowing the entity’s foreign keys: a violation of one of them is ErrorRepositorio::ReferenciaInexistente with its field. One the list does not name is Unavailable — nothing can tell the caller which input was wrong.
ping
Whether the database answers a trivial query — what /health/ready reports.