Skip to content

Commit 72b597d

Browse files
authored
docs: Correct production DB target - CockroachDB not Postgres (#2129)
* docs: Correct production database target in data model doc The previous version stated Meridian's deployment target was Postgres 16, which was incorrect. Production targets CockroachDB; Postgres is used in develop and demo only. Migrations and runtime SQL are written to the common subset of both, which is why the compatibility rules in ADR-0003 are binding for all new migrations, not historical artefacts. * docs: Add Mermaid ER diagrams to data model reference Adds per-service ER diagrams and a cross-service logical reference flowchart so the data model can be read visually. Covers platform tier, party, identity, current/internal account, position-keeping, financial accounting, reference data, payment order and billing, market information, reconciliation, and operational gateway. * docs: Address review feedback on data model doc - Clarify that Atlas validates against Postgres 16, so CockroachDB compatibility is enforced by developer discipline and code review rather than automated tooling (coderabbitai, claude[bot]) - Correct party_type_definition field names: party_type, attribute_schema, validation_cel, eligibility_cel (not code/json_schema/cel_expression) - Correct current_account.account field names: account_id and account_identification are the identifier columns, not account_number - Correct lien field names: amount_cents (bigint) and payment_order_reference (varchar), not decimal amount and uuid FK - Update cross-service flow label accordingly * docs: Fill ER diagram attribute blocks with canonical schema Every entity referenced in an ER diagram now has an attribute block so there are no empty boxes. Column names and types are taken from the canonical Atlas migrations in services/<service>/migrations/ - the source of truth for what develop/demo will look like once deployed. Also cross-validated against the live demo Postgres where tables are present (demo is currently lagging develop for some reference-data and control-plane tables, so migrations remain authoritative). Each block shows the ~8-10 most meaningful columns; housekeeping columns (created_at, updated_at, created_by, version, etc.) are omitted unless they carry domain meaning (e.g. valid_from/valid_to on bi-temporal market data, revoked_at on api_key). * docs: Apply internal-account rename + fix cross-service flow labels Missed two migrations in the prior schema pass (claude[bot] review): - PR-era 2026-02-25: internal_bank_account renamed to internal_account, internal_bank_account_status_history to internal_account_status_history, correspondent_bank_* to counterparty_* - PR-era 2026-03-06: internal-account lien.currency renamed to instrument_code Also fix cross-service flowchart edge labels that referred to columns that do not exist (balance_ref, counterparty_party_id) or used renamed names (account_type_code, asset_code, dataset). Replace balance_ref with account_id and drop the IBA to party edge since internal_account holds a varchar counterparty identifier, not a direct party FK. * docs: Fix Mermaid parse error - invalid PK_FK constraint Mermaid erDiagram supports only one constraint per attribute (PK, FK, or UK). Used PK with a descriptive comment instead of the invalid combined PK_FK token, which was breaking GitHub's Mermaid renderer. --------- Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>
1 parent 7964e77 commit 72b597d

2 files changed

Lines changed: 768 additions & 12 deletions

File tree

docs/adr/0003-database-schema-migrations.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ Database: meridian_current_account
153153
└── Tables: account, lien, audit_log, audit_outbox
154154
```
155155

156-
- Each service has its own PostgreSQL database
156+
- Each service has its own database (PostgreSQL in develop/demo, CockroachDB in production)
157157
- Each organization gets its own schema within each service database
158158
- The search_path is set transactionally via `SET LOCAL search_path TO org_<id>` by `shared/platform/db/gorm_tenant_scope.go`
159159
- Queries use unqualified table names; PostgreSQL resolves via `search_path`
@@ -485,11 +485,11 @@ If migrating from golang-migrate:
485485
* Maintain migration history (no need to replay all migrations)
486486
* Continue using immutability principles
487487

488-
### CockroachDB Compatibility Considerations (Historical)
488+
### CockroachDB Compatibility Considerations
489489

490-
> **Note:** Meridian now targets PostgreSQL 16 exclusively. The constraints below are retained because existing migrations were authored under CockroachDB compatibility rules and continue to follow them (no PL/pgSQL, split column-add from partial-index-add, explicit timestamp columns instead of range types). New migrations should follow the same conventions for consistency, but the underlying runtime is Postgres. See [data-model.md](../architecture/data-model.md) for the current topology and [docs/reports/cockroachdb-migration-audit.md](../reports/cockroachdb-migration-audit.md) for historical context.
490+
> **Production target:** Meridian's production deployment target is **CockroachDB**. The `develop` and `demo` environments currently run PostgreSQL 16 (faster local boot, wire-compatible), but every migration and runtime SQL path must work unchanged on CockroachDB. The constraints below are binding for all new migrations. See [data-model.md](../architecture/data-model.md) for the current topology and [docs/reports/cockroachdb-migration-audit.md](../reports/cockroachdb-migration-audit.md) for the compatibility audit.
491491
492-
While CockroachDB is PostgreSQL-compatible, some PostgreSQL features are **not supported**:
492+
While CockroachDB is PostgreSQL wire-compatible, some PostgreSQL features are **not supported**:
493493

494494
| Feature | PostgreSQL | CockroachDB | Workaround |
495495
|---------|------------|-------------|------------|

0 commit comments

Comments
 (0)