Initial commit

docs/library-decisions/2026-05-14-@payloadcms/db-postgres.md

@@ -0,0 +1,85 @@
+---
+package: "@payloadcms/db-postgres"
+version: "^3.14.0"
+tier: core
+decision: approved
+date: 2026-05-14
+deciders: [Danijel Martinek]
+adr: null
+filter-results:
+  license: MIT
+  types: native
+  maintenance: active
+  boundary-fit: pass
+  shadow-check: pass
+  eu-residency: self-hostable
+  cve-scan: clean
+  named-consumer: pass
+  socketRisk: clean
+verification-commands:
+  - npm view @payloadcms/db-postgres license
+  - npm view @payloadcms/db-postgres version
+  - pnpm audit --audit-level=moderate
+accepted-cves: []
+---
+
+## Filter: license
+
+<!-- Result: MIT -->
+
+`npm view @payloadcms/db-postgres license` returns `MIT`. MIT is on the allowlist.
+
+## Filter: types
+
+<!-- Result: native -->
+
+`@payloadcms/db-postgres` is part of the Payload CMS monorepo, authored in TypeScript, and ships its own `.d.ts` declaration files.
+
+## Filter: maintenance
+
+<!-- Result: active -->
+
+Maintained as part of the Payload CMS project. Versioned and released together with the `payload` core package; receives the same release cadence.
+
+## Filter: boundary-fit
+
+<!-- Result: pass -->
+
+`@payloadcms/db-postgres` is the PostgreSQL database adapter for Payload CMS, used exclusively in `@repo/core-cms` to configure the Payload instance. Feature packages do not reference this package directly. This is the correct placement for a CMS-layer infrastructure adapter.
+
+## Filter: shadow-check
+
+<!-- Result: pass -->
+
+`@payloadcms/db-postgres` is the sole database adapter in the workspace. No competing Payload database adapter (MongoDB, SQLite, etc.) is present.
+
+## Filter: eu-residency
+
+<!-- Result: self-hostable -->
+
+`@payloadcms/db-postgres` connects to a self-hosted PostgreSQL instance (configured via `DATABASE_URI`). No data is transmitted to Payload-controlled or third-party-controlled endpoints. EU residency is determined by the PostgreSQL host deployment environment.
+
+## Filter: cve-scan
+
+<!-- Result: clean -->
+
+`pnpm audit --audit-level=moderate` reports no advisories against `@payloadcms/db-postgres` at the time of this trace.
+
+## Filter: named-consumer
+
+<!-- Result: pass -->
+
+`@repo/core-cms` uses `@payloadcms/db-postgres` as the database adapter in the Payload configuration. Named, non-hypothetical consumer exists today.
+
+## Prompt: replaces
+
+`@payloadcms/db-postgres` replaces the need for a separate ORM (Prisma, Drizzle, etc.) alongside Payload — Payload's built-in adapter unifies the data access layer and admin UI schema in one package.
+
+## Prompt: migration-cost-out
+
+Hard. The PostgreSQL adapter is tightly coupled to the Payload schema definitions in `core-cms`. Migrating to a different adapter (e.g., MongoDB) would require reshaping all collection definitions and potentially the database migration history. The Payload interface boundary limits exposure to `core-cms` only.
+
+## Prompt: alternatives-considered
+
+1. **`@payloadcms/db-mongodb`** — Not applicable for this deployment target; the infrastructure uses PostgreSQL (ADR-015 references the database stack).
+2. **Prisma + separate Payload adapter** — Rejected: Payload's integrated adapter eliminates the N+1 problem of maintaining two data access layers for the same database.