zarinpal-analytics-backend/docs/decisions/0003-ent-pgx-data-access.md

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: https://entgo.io/docs/versioned/intro/
• pgx v5 CopyFrom: https://pkg.go.dev/github.com/jackc/pgx/v5#Conn.CopyFrom