PostgreSQL is a concrete implementation choice hidden behind an architecture label such as “database.” Naming it makes the box searchable, verifiable, and connected to the code that uses it. section 9.4
Document PostgreSQL as a component with three facts:
- Plain English: explain what the database does for the product. section 9.4
- Under the hood: identify PostgreSQL as the relational storage system and describe the surrounding libraries, protocols, or services. section 9.4
- Confirmation: record the file path and line number where PostgreSQL is defined or used. section 9.4
Replace the vague database label
Instead of documenting “the queue,” identify a PostgreSQL Task table that a cron route drains, retries each row up to three times, and uses as the concrete implementation behind the architecture node. section 9.4
Table 9.4 Common database choices and the trade-offs they lock in
|
Database
|
Built for
|
Consistency
promise
|
Scaling
story
|
When it
breaks
|
|
Postgres
|
Relational
ACID, complex queries, mature ecosystem
|
Linearizable
on primary; replica lag on reads
|
Vertical
first, then read replicas, then sharding (Citus)
|
Single-writer
ceiling; replica lag breaks read-your-writes
|
|
MySQL
|
Same as
Postgres; stronger replication tooling
|
Same as
Postgres
|
Same plus
Vitess / PlanetScale for managed sharding
|
Same as
Postgres
|
|
MongoDB
|
Flexible
schema, document model
|
Eventual on
secondaries; tunable per query
|
Auto-sharding
by shard key
|
Hot
partition if shard key is wrong; cross-document transactions are slow
|
|
DynamoDB
|
Always-on,
predictable performance, no operators
|
Eventually
consistent reads by default (strong reads cost 2× RCU)
|
Horizontal
by hash partitioning
|
Hot-key
skew; cost spikes from unbounded queries
|
|
Cassandra /
ScyllaDB
|
Write-heavy
LSM workloads
|
Tunable per
query (ONE, QUORUM, ALL)
|
Horizontal
by design
|
No joins
ever; secondary-index limits; tombstone problem
|
|
SQLite
|
Embedded,
single-writer
|
Linearizable
|
None,
single file
|
Concurrent
writes; no network access
|
Compare PostgreSQL with other database choices by consistency promises, scaling paths, and the operational limits each choice creates. section 9.4












