# ADR 0003: Ent application persistence with pgx bulk ingestion - Status: Accepted - Date: 2026-08-20 ## Context The backend requires an ORM-backed relational model with explicit entity relationships and a repeatable path from schema definitions to an ERD. The source archive contains more than 2.2 million payment-attempt rows, making row-by-row ORM insertion unsuitable for ingestion. Production schema changes must remain reviewable and reversible rather than occurring implicitly at process startup. ## Decision Use Ent for application persistence, relationship modeling, and type-safe access within capability adapters. Keep Ent-generated artifacts and the schema definitions that produce them in Git according to the future scaffold specification. Use pgx directly for the importer’s PostgreSQL staging boundary. Feed `CopyFrom` with a streaming `CopyFromSource` (or equivalent bounded batches) so decompressed CSV rows are not accumulated in memory. Validate and promote staged data through explicit transactions/steps described by the import spec; bulk loading must not bypass reconciliation or data-quality rules. Use versioned SQL migrations generated/planned from the reviewed schema and committed to Git. Apply them through a dedicated migration command or deployment step. Ent automatic schema creation is allowed only in disposable development/test contexts if the later implementation spec permits it; it must never run as part of production application startup. ## Consequences - Domain-oriented code gains typed entities, edges, predicates, and compile-time feedback. - Engineers must still inspect generated SQL, query plans, indexes, transaction boundaries, and possible N+1 behavior; the ORM is not a performance or correctness boundary. - The importer owns a deliberate lower-level pgx path and cannot reuse ordinary Ent writes for convenience. - Both Ent and pgx require compatible pool/transaction ownership and context propagation; adapters must not hide unbounded work. - Migration generation tooling and the migration runner remain to be selected in the implementation spec. Versioned migration files—not runtime diffs—are the production contract. ## References - Ent versioned migrations: - pgx v5 `CopyFrom`: