Skip to content

ADR-024: Database hosting — Neon serverless Postgres
Status Superseded
Date 2026-04-10
Deciders CTO, Head of Platform Engineering
Affects repos bank-core, bank-kyc, bank-aml, bank-payments, bank-credit, bank-risk-platform, bank-platform
Superseded by ADR-052

⚠️ This ADR has been superseded by ADR-052.

Partially superseded. ADR-052 corrects the Neon database naming convention (adding the bank_ prefix; renaming bank_fincrime to bank_aml). All other decisions in this ADR remain in force — Neon as the hosting platform, ap-southeast-2 region, branch-per-environment model, PgBouncer connection pooling, and one database per domain.

ADR-024: Database hosting — Neon serverless Postgres

Status

Superseded (partially) — 2026-05-01 (by ADR-052 — naming convention only)

Context

ADR-001 established Postgres as the OLTP operational store. The hosting of that Postgres must now be decided. The serverless execution model (ADR-022) creates a specific requirement: the database must handle Lambda's connection pattern — many short-lived connections from functions that scale independently — without exhausting connection limits. It must also align with the zero-operational-overhead goal at the build phase, where the bank is not yet generating revenue.

Decision

Neon serverless Postgres. Single Neon project, ap-southeast-2 (Sydney). One database per system domain.

Concern Decision
Hosting Neon — neon.com
Region ap-southeast-2 — Sydney (confirmed available)
Project structure One Neon project for the bank; eight databases within it, one per system domain
Connection pooling Neon built-in PgBouncer — handles Lambda cold-start connection exhaustion without RDS Proxy
Scale-to-zero Neon computes scale to zero on inactivity — zero cost in dev/test outside active use
Branching Neon database branches used for dev and UAT environments — instant, copy-on-write, no separate instances
Evolution path Neon → managed Postgres (Snowflake Postgres, AWS RDS, Aurora Serverless v2, or self-hosted) when scale or compliance requirements justify it. Interface is standard Postgres — migration is a hosting change, not an application change

Database structure (AP-010 domain alignment)

Database System domain Repo
core SD01 Core Banking bank-core
kyc SD02 KYC Platform bank-kyc
fincrime SD03 AML Monitoring bank-aml
payments SD04 Payments bank-payments
credit SD05 Credit bank-credit
risk SD06 Risk Platform bank-risk-platform
platform SD07 Data Platform bank-platform

Cross-domain queries are not permitted inline. Data shared across domains is published via EventBridge events (ADR-029, superseded by ADR-051; see ADR-051 for current EventBridge bus naming convention) or explicit read APIs under published contracts, consistent with AP-010.

Connection pooling note

Lambda functions must connect via Neon's pooled connection string (PgBouncer endpoint), not the direct connection string. Direct connections are for migrations only and run from the CI/CD pipeline, not from Lambda functions.

Consequences

Positive: - Scale-to-zero eliminates database cost during development and low-traffic periods - Built-in PgBouncer solves the Lambda connection exhaustion problem without additional infrastructure - Neon branching makes per-PR database environments trivial — each PR gets its own branch at near-zero cost - Sydney region satisfies AU data residency (CPS 234); NZ data residency via Sydney under DPAs consistent with ADR-023 - Standard Postgres interface means no Neon-specific application code — evolution path is clean

Negative: - Neon is a managed third-party service — a new vendor dependency. Mitigated by standard Postgres interface (no lock-in at application layer) - Neon's SLA and uptime guarantees must be reviewed against NFR-019 (RTO ≤ 4h / RPO ≤ 1h for Tier 1 services) before production launch - Performance under high sustained load is less proven than RDS — performance tests (NFR-012, NFR-013) against UAT must pass before prod promotion

Alternatives considered

AWS Aurora Serverless v2: Good AWS-native option. Scales close to zero (not true zero). More expensive at low utilisation. No branching. Would be the natural migration target if Neon is outgrown.

AWS RDS Postgres: Reliable, well-understood. Always-on compute — significant cost during pre-revenue development. No serverless scaling. Appropriate for post-scale hosting.

Supabase: Similar to Neon (serverless Postgres, PgBouncer, Sydney region). Adds more product surface area (Auth, Storage) that overlaps with other decisions. Neon is more focused.

Self-hosted Postgres on EC2/EKS: Maximum control, maximum operational overhead. Not appropriate at this stage.

Signoff record

Date Name Role Status
2026-04-10 Ross Millen CTO Approved
2026-04-10 Ross Millen Head of Architecture Approved
2026-04-10 Ross Millen Head of Data Approved

Capabilities

Capability Description Relationship
CAP-033 Tenant data isolation enabled — one database per system domain enforces domain isolation at Postgres level
ADR Title Relationship
ADR-001 Postgres as the OLTP operational store this ADR is the hosting decision for ADR-001
ADR-003 CDC pipeline — Neon Postgres to Snowflake via Firehose and Apache Iceberg Neon-specific WAL constraints documented in ADR-003
ADR-022 CI/CD and deployment strategy Neon branching enables per-PR database environments
ADR-023 Cloud provider and region strategy region constraint (ap-southeast-2) confirmed for Neon

All ADRs Compiled 2026-05-22 from source/entities/adrs/ADR-024.yaml