ADR-0001: Railway PostgreSQL over Neon¶
Status: Accepted Date: 2026-03-10 Session: 6
Context¶
Curaway's FastAPI backend needs a relational database for storing patient cases, EHR records, conversation history, consent artifacts, and event logs. The backend is deployed on Railway, so the database choice affects networking topology, cost, and operational complexity.
Two leading managed PostgreSQL options were evaluated: Railway's built-in PostgreSQL plugin and Neon, a serverless Postgres provider with branching capabilities. Both offer managed backups, but they differ significantly in networking and pricing models.
Decision¶
Use Railway's built-in PostgreSQL service as the primary relational database for all Curaway backend data.
Rationale¶
- Internal networking. Railway PostgreSQL runs on the same internal private network as the FastAPI container. Connections use Railway's internal DNS (
postgres.railway.internal), eliminating cross-cloud data transfer costs and reducing query latency to sub-millisecond. - Single platform. Keeping the application and database on the same platform simplifies deployment, environment variable management, and monitoring. One bill, one dashboard, one set of credentials.
- No cold starts. Railway Postgres is always-on, unlike Neon's serverless model which can have cold-start latency on the free tier. For a healthcare application where users expect immediate responses, cold starts are unacceptable.
- Predictable costs. Railway charges based on resource usage (CPU, memory, disk) rather than per-query compute units, making costs easier to forecast for a startup.
Alternatives Considered¶
| Alternative | Pros | Cons | Verdict |
|---|---|---|---|
| Neon | Serverless scaling, database branching for dev/preview, generous free tier | Cross-cloud latency from Railway to Neon, cold starts on free tier, adds a second platform to manage | Rejected |
| Supabase | Bundled auth, realtime subscriptions, REST API out of the box | Opinionated stack (own auth, own API layer) that overlaps with FastAPI; cross-cloud networking | Rejected |
| PlanetScale | Proven horizontal scaling, branching workflows | MySQL-only (not PostgreSQL), incompatible with SQLAlchemy/asyncpg stack and pgvector extension | Eliminated early |
Consequences¶
- Positive: Zero-latency database access from the API container. Single platform reduces operational overhead. No cross-cloud egress charges.
- Positive: Railway Postgres supports pgvector extension if we ever need vector search collocated with relational data.
- Negative: No database branching for preview environments (Neon's killer feature). Migrations must be tested manually or in a staging environment.
- Negative: Tied to Railway's infrastructure. If Railway has an outage, both app and database are affected simultaneously.
- Accepted risk: Railway's PostgreSQL is less feature-rich than dedicated database platforms, but the operational simplicity outweighs the missing features at this stage.