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
loginopens and the password hashes it checks. Their tables arecrate::MIGRACION_USUARIOSandcrate::MIGRACION_AUTH, whichpuerto new --auth localwrites 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 firstpuerto generate correo --onwrites into the project. - eventos
- The Postgres side of domain events (ADR-0018 § 4): the outbox the relay reads, the
dbtransport (entregas_eventos) and the dead-letter sink every transport writes to. The tables aremigrations/outbox.sql, whichpuerto new --eventoswrites 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}UnitOfWorkwraps aTransaccionPostgresand only writes its entity’s upsert, throughTransaccionPostgres::tx.
Structs§
- Clave
Foranea - A foreign key a repository writes through: the constraint’s name in the migration and the field it checks (ADR-0022).
Enums§
- Error
Base Datos - 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), afterMIGRACION_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::SesionesPostgresreads 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 —
migratoris itssqlx::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_coninstead. - mapear_
error_ sqlx_ con mapear_error_sqlx, knowing the entity’s foreign keys: a violation of one of them isErrorRepositorio::ReferenciaInexistentewith its field. One the list does not name isUnavailable— nothing can tell the caller which input was wrong.- ping
- Whether the database answers a trivial query — what
/health/readyreports.