YugabyteDB

1. A genuinely distributed PostgreSQL: reuses the PG query-layer C code What it really is: YSQL isn't "wire-protocol compatible" — it directly reuses PostgreSQL's parser/optimizer/executor code, so psql, JDBC, most ORMs, and migration tools connect with zero changes, and PG DBAs' existing knowledge (execution plans, pg_stat, tuning methodology) largely transfers. This is its hardest differentiator vs. CockroachDB (self-built Go SQL layer, protocol-compatible only): the "texture" of compatibility is different. Edge truth: the same query layer is not the same semantics — the storage engine changed, and forks lurk at every edge (see deep-dive 4: DDL inside transactions, advisory locks, deferrable constraints, exclusion constraints, sequence behavior). "'PG syntax runs' and 'PG behaves the same' are two different things; migration testing must be redone against YSQL's own gap list rather than borrowing PG's test conclusions just because 'both are PG dialects'."
2. Flexible multi-region data placement (geo-partitioning + follower reads + xCluster) What it really is: a single cluster spans AZs/regions/clouds with Raft synchronous replication; geo-partitioning pins tables/partitions to designated regions via tablespaces for "write localization"; follower reads let reads be served from local replicas; xCluster provides one-way async replication for active-active/DR. Among strongly consistent cross-region options, this is one of the most complete. Edge truth: synchronous cross-region writes can't escape the speed-of-light tax (one transoceanic RTT per commit); placing the leader in the wrong region doubles latency; unplanned xCluster failover is a manual process (stop the app → pause replication → PITR restore → switch connections), and RTO depends on application traffic-switching speed, not the database; the bill for 3 regions × RF is very real. If you only did HA on the database side without traffic switching on the app side, you only did half the job.
3. Apache 2.0 core with no feature crippling (the licensing watershed) What it really is: since July 2019 the core database has been 100% Apache 2.0, with former enterprise features (backup, encryption, read replicas, CDC) all merged into open source — no enterprise-only features at the database level. Against the backdrop of CockroachDB taking new versions private in 2026, this is currently the hardest watershed between the two: one is moving more open, the other more closed. Edge truth: the license has flipped more than once (dual CE/EE versions before 2019), so long-term thinkers' anxiety about "what if it changes again" is reasonable; the Anywhere control plane is Polyform (not OSI open source), so "full-stack open source" doesn't hold; the Jepsen correctness test was vendor-paid 厂商口径. Verify per legal counsel; don't use one vendor's marketing to argue about the other.
4. Smart Drivers + built-in Connection Manager (a distributed answer to PG's connection model) What it really is: the official smart driver reads the topology from cluster metadata and connects clients directly to each tserver; load_balance=true + topology_keys give no-external-LB, AZ-local routing, and client-side retry on failure; the YSQL Connection Manager (Odyssey-based, on :5433) multiplexes thousands of client connections onto a few backend connections, and the vendor explicitly stated in 2026.1 that "no external PgBouncer is needed." This is a systematic answer to "one process per PG connection" amplified by distribution. Edge truth: it only works within the official smart-driver ecosystem — plain PG drivers/poolers get none of this; community field experience has dug up pitfalls: the Node driver's topology cache is a class-level static shared across the process — switching pools without resetting inherits a stale topology; pools must be manually warmed up to spread across all nodes; on non-peered VPCs the driver first probes unreachable nodes, adding latency. Using third-party drivers means forfeiting this benefit.

Deep-dive 1 (storage engine): DocDB — one RocksDB per tablet; tablet count is the ceiling that arrives first

• Mechanism: each tablet maps to an independent RocksDB instance (LSM-tree); each YSQL tablet is actually two RocksDBs — regular for committed data, intents for transaction provisional records; tablet splits are triggered via a Raft-log split record; after split-apply, the old tablet rejects all new reads/writes, and the new tablet only becomes RUNNING after electing a new leader; HLC timestamps; --max_clock_skew_usec defaults to 500000 (500ms), and the vendor recommends setting it to 2× your expected max clock skew; MVCC history retention timestamp_history_retention_interval_sec defaults to 15 minutes.
• Pushed to the edge: when SST files pile up to the limit → DocDB throttles writes directly (observable metrics: majority_sst_files_rejections, rocksdb_stall_micros, intentsdb_rocksdb_stall_micros) — for write-heavy workloads with tight IO, this ceiling arrives before CPU does; tablet count: the official deployment checklist gives an empirical ceiling of ~530 tablet replicas per 8 GiB node — clusters with many tables/indexes/high RF eat memory and management budget first; if any node's clock skew exceeds max_clock_skew → it crashes directly to protect correctness — a misconfigured NTP doesn't slow you down, it drops nodes; reads landing inside the "uncertainty window" get a 40001 read-restart and must retry; long queries/transactions running past the retention period → snapshot_too_old (SQLSTATE 72000), which is not retryable — opening a new transaction for a fresh snapshot is the only way out; enabling PITR or CDC before-image raises the retention period, and a lagging CDC stream makes disk usage grow linearly with retained data — consumer lag on the CDC side converts directly into a source-side disk bill.
• What it means for selection: write-heavy workloads must leave disk/IO headroom for compaction and monitor stall metrics; NTP and clock-skew monitoring are mandatory; reporting-style long queries should either raise the retention period (trading disk for it) or handle snapshot_too_old at the application layer; tablet counts need upfront planning (YugabyteDB tablets only split by size and never auto-merge — the count only grows).
• Sources: official design docs (tablet splitting), official deployment checklist (tablet ceiling/clock config), third-party monitoring docs (stall metrics, community-tested), official blog (clock skew/retention, vendor claim)

Deep-dive 2 (transactions & time): the tax of distributed transactions — provisional records, read restarts, retry scaffolding

• Mechanism: multi-tablet writes first land as provisional records on each participating tablet; the coordinator writes the commit timestamp into a decentralized transaction-status table, then they become real MVCC versions (Percolator-style); conflict handling is fail-on-conflict / wait-on-conflict + background distributed deadlock detection; single-row/single-shard transactions take the fast path (no transaction-status-table write).
• Pushed to the edge: every write waits for a Raft quorum — standalone PG's sub-millisecond writes becoming millisecond-level on YB is inherent to the architecture (the official FAQ acknowledges the trade-off; community tests measured 465ms for a DO block inserting one row into each of three tables, 801ms under Read Committed); multi-tablet reads must wait for the read timestamp to become safe on every tablet; clock skew near the threshold triggers read retries — a misconfigured NTP shows up directly as jitter; under Serializable, conflicts surface as 40001 and the application must write a retry loop — retry scaffolding is needed on both sides (YB/CRDB); only the default isolation level differs (YSQL defaults to Read Committed).
• What it means for selection: sub-millisecond write-latency-sensitive workloads are out; the application layer must implement idempotent retries; POCs must be load-tested with the real transaction model — single-table point-lookup benchmarks will severely understate distributed-transaction cost.
• Sources: official architecture docs (distributed-txns / concurrency-control / single-row-transactions), official FAQ, community tests (dev.to)

Deep-dive 3 (SQL layer): YSQL vs YCQL dual APIs — data islands and tilted investment

• Mechanism: YSQL reuses the PG query layer (rebased to PG 15 since v2025.1), wire-protocol compatible; YCQL is compatible with Cassandra CQL v3.4; the two APIs are completely isolated at the data plane — writes on one side are invisible to the other (even reading YCQL from YSQL via FDW only exists as roadmap issue #830).
• Pushed to the edge: the vendor has not announced a YCQL deprecation (no deprecation statement found — to-be-verified), but the tilted-investment signals are real: gRPC CDC doesn't support YCQL tables (issue #11320); new clusters' default memory configuration is optimized for YSQL; the new API the vendor added in July 2025 is MongoDB (positioned as "multi-modal" alongside YSQL/YCQL); the official FAQ positions YCQL narrowly: no FK/JOIN needed, sub-millisecond single-row latency, TTL, connecting Spark/KSQL. Running two APIs on one cluster = two sets of monitoring, two sets of tuning knobs, data islands — the ops cost is multiplicative, not additive.
• What it means for selection: new users should default to YSQL; only consider YCQL for legacy Cassandra migrations that hit the four scenarios the vendor lists; weigh YCQL's feature-investment trajectory before betting new workloads on it.
• Sources: official FAQ (compatibility), official CDC docs, official deployment checklist, BusinessWire press release (MongoDB API, vendor claim)

Deep-dive 4 (compatibility/migration): the PG compatibility gap list — "syntax runs" ≠ "semantics match" (as of 2026-09-29)

• Foreign keys: supported, but foreign keys referencing partitioned tables are not supported; deferrable UNIQUE is not supported (issue #1709), deferrable FK is supported.
• DDL transactionality: DDL is non-transactional by default — after BEGIN; CREATE TABLE; ROLLBACK; the table still exists (issue #1404); transactional DDL is an early-access flag (v2025.2) and is mutually exclusive with CDC; a plain CREATE INDEX builds online and cannot be placed inside an explicit transaction block (issue #6240).
• Advisory locks: errored out directly before 2025.1; supported since 2025.1 (requires a preview flag); the silent-error flag was deprecated in 2025.2 — migrations on pre-2025.1 versions must change the application.
• LISTEN/NOTIFY: early-access, off by default; listed as unsupported by the official voyager assessment tool.
• Triggers/stored procedures: officially claimed supported, but AFTER UPDATE triggers on partitioned tables were once incorrect; exclusion constraints are not supported (issue #3944), and the official workaround is "simulate them with triggers" — semantics downgraded from a constraint to best-effort.
• Sequences: minimum cache of 100 enforced; sequences live in a distributed system table, and node add/remove/reconnect all produce gaps — don't use sequences if you need gapless numbering.
• Other hard gaps: system columns xmin/xmax/ctid, large objects lo, PREPARE TRANSACTION (two-phase commit), table inheritance INHERITS, and multi-column GIN indexes are all unsupported; fixed and closable: UNLOGGED tables (2024.2+/2025.1+), GENERATED ALWAYS columns (2.25/2025.1+), adding a primary key to a partitioned table after creation (2024.1+).
• What it means for selection: before migrating, run the yb-voyager assess-migration gap scan, and audit five spots in particular — deferrable constraints, exclusion constraints, DDL inside transactions, advisory locks, LISTEN/NOTIFY — which are common in PG but either error or silently change semantics in YSQL. v2025.1 (the PG15 rebase) is the compatibility watershed; most compatibility complaints about earlier versions are already partially fixed.
• Sources: official voyager known-issues (postgresql.md), official migration docs, GitHub issues (#1404/#1709/#3944/#6240/#830/#11320), third-party compatibility tests (pg-boss)

Deep-dive 5 (replication & DR): multi-region — the speed-of-light tax, leader placement, manual failover

• Mechanism: geo-partitioning pins tables/partitions to designated regions via tablespaces + placement blocks; follower reads require read-only transactions + yb_read_from_followers=on, at the cost of bounded staleness yb_follower_read_staleness_ms (default 30000ms) — set it too small (<2× the Raft heartbeat) and reads bounce back to the leader; read replicas serve remote read-only; xCluster is one-way async replication between two universes — planned switchover achieves RPO=0 (wait for the target to catch up), unplanned failover has non-zero RPO and manual steps: stop the app → pause two-way replication → PITR restore to the latest consistent point → switch connections; xCluster DDL auto-replication went GA in v2025.2.1, but failover itself remains manual.
• Pushed to the edge: synchronous cross-region writes can't escape physics (third-party comparison: US→EU 50–100ms, US→Asia 100–200ms, to-be-verified); if all tablet leaders sit in the preferred region, that region's failure leaves every tablet leaderless in an instant — re-election takes ~3 seconds, but application traffic switching (LB/connection strings) is on you; follower reads are fundamentally "trade 30 seconds of staleness for local latency" — fine for reports, intolerable for transactions, and must be toggled explicitly at session level when mixed.
• What it means for selection: write-heavy cross-region → accept the latency or use geo-partitioning to localize writes; read-heavy → follower reads/read replicas are the right answer; DR drills must cover the full manual flow of "xCluster over and back" plus application connection switching — RTO depends on application traffic-switching speed, not the database.
• Sources: official tserver config docs, official DR design docs, official Aeon DR docs, third-party comparison (sesamefs, community consensus)

Deep-dive 6 (cost/licensing): the license evolution — from dual versions to 100% open source, and the fork from CockroachDB

• Mechanism: 2016–2019.7 dual versions (CE open source + EE commercial closed source) → official blog on 2019-07-16 announced 100% open source (distributed backup, encryption, read replicas, CDC merged into Apache 2.0 from v1.3) → to this day the core (src/yb/ + src/postgres/ + client libraries) is Apache 2.0, with no enterprise-only features at the database level; the Anywhere control plane (managed/ directory) is Polyform Free Trial.
• Pushed to the edge: compare with CockroachDB: Apache 2.0 (2017–2019) → BSL (2019–2024) → Software License (2024–present) → new versions moved to a private repository in 2026. Licensing is currently the hardest watershed between the two: one moves more open, the other more closed. "Self-hostable and portable" ≠ "independently controllable" — after CRDB's 2026 move there's no source to read and no community core PRs for new versions; if a kernel-level bug hits production, your options are limited to waiting for the vendor to fix it or buying support; on the YB side, "will it change again" is a reasonable long-term anxiety (it has flipped before) — verify per legal counsel and don't use one vendor's marketing materials to argue about the other.
• What it means for selection: for teams sensitive to licensing (信创 xìnchuàng / financial compliance / long-term independent control), this is YB's structural advantage over CRDB — but the advantage only holds as long as "core 100% open source" keeps holding; scrutinize versions and clauses in the contract, not the blog headlines.
• Sources: Yugabyte official blog (2019 license change / 2025 blog), repo LICENSE.md (independently verified, no CRDB-side materials cited); CRDB side: this profile repository's cockroachdb.md (2024 licensing update, 2026 source-code-protection official blogs)

1. Migration smoothness from PG compatibility
   • Why it's real: YSQL directly reuses the PG query-layer C code and is wire-protocol compatible; psql/JDBC/most ORMs connect without changes, and the vendor ships the YugabyteDB Voyager migration tool; PG DBA Franck Pachot's field tests recommend "start with YB for OLTP if you may need to scale later," on the grounds that it's PG-compatible and you can always move back to PG.
   • Edge & limits: "compatible" ≠ "is PG" — table-rewriting ALTER TABLE ... ALTER COLUMN TYPE errored outright before v2025.1 (this once broke an Ory Kratos migration); it was added after the PG15 rebase but exclusions remain; the vendor maintains a list of "unsupported PG features."
   • Sources: official docs + community-tested. Observed version: v2025.1/v2025.2
2. Horizontal scale-out
   • Why it's real: tablets can auto-split and the rebalancer moves them automatically — adding nodes scales out and the vendor says no downtime is needed; this is the most-recognized advantage of "natively distributed" over PG primary-replica/Citus-style setups.
   • Edge & limits: it scales capacity and throughput, not single-point latency; tablet bloat has real cost (~530 tablet replicas + a 65 physical-PG-connection ceiling per 8GiB node) — too many amplify leader-balancing and metadata pressure; the 3-node × 4vCPU production floor is seen by the community as overkill for small workloads.
   • Sources: official docs + community consensus. Observed version: v2025.2
3. Multi-region active-active / synchronous replication
   • Why it's real: a single cluster spans AZs/regions/clouds with Raft synchronous replication preserving strong consistency; geo-partitioning places data near users; xCluster does two-way replication; third-party community comparisons place it alongside CRDB in the "strongly consistent cross-region" tier.
   • Edge & limits: writes must wait for a Raft quorum, and cross-region write latency is hard-bounded by physical distance; a misplaced leader doubles latency; the 3-region × RF resource bill is very real. Vendor claims (Kroger 5000+ cores, <10ms latency) are to-be-verified and do not enter the verdict.
   • Sources: official docs + third-party comparison. Observed version: v2025.2
4. Smart Drivers (cluster/topology-aware drivers)
   • Why it's real: the official smart driver reads topology from cluster metadata and connects clients straight to each tserver; load_balance=true + topology_keys deliver no-external-LB, AZ-local routing, and client-side retry on failure — field tests confirmed traffic spreads evenly across nodes.
   • Edge & limits: only works inside the official smart-driver ecosystem; community field pitfalls: the Node driver's topology cache is statically shared at class level — switching pools without resetting inherits a stale topology; pools need manual warm-up; on non-peered VPCs the driver probes unreachable nodes first, adding latency.
   • Sources: official docs + community-tested. Observed version: v2025.2 / v2026.1
5. Open-source reputation (100% Apache 2.0 core)
   • Why it's real: the core is 100% Apache 2.0 (the 2019 HN discussion was positive), more thorough than CRDB (BSL→private) and TiDB's commercial-edition boundaries; it passed Jepsen correctness testing.
   • Edge & limits: the license has flipped multiple times in history, and long-term thinkers worry about "what if it changes again"; the Anywhere control plane is Polyform, not OSI open source; the Jepsen test was vendor-paid 厂商口径.
   • Sources: HN discussion (2019), Jepsen report. Observed version: all versions

• One-line positioning: For teams that want to "write in PG dialect and run at distributed scale" and care deeply about license openness, YugabyteDB is the most genuinely PG-compatible of the NewSQL crowd — but every cent of the distributed tax (latency, RF3 resources, ops complexity) still has to be paid.
• Good for: OLTP needing the PG ecosystem + horizontal write scale (start on PG, keep scale-out in reserve); multi-region active-active / same-city dual-active strong-consistency scenarios; legacy Cassandra migrations to YCQL; teams sensitive to licensing that require a core that is 100% open source with no crippling (contrast with CRDB going private in 2026).
• Not for: single-region small workloads (RF3 resource floor + ops complexity don't pay off — start with PG+Patroni); scenarios where write latency is sensitive down to sub-milliseconds; teams deeply dependent on PG niche features (PostGIS, exclusion constraints, LISTEN/NOTIFY, old-version advisory locks, PREPARE TRANSACTION) that won't change their application; teams with high Chinese-language-support needs, no dedicated DBA, and a "install and forget" expectation.
• Migration cost: PostgreSQL → low-to-medium (protocol-compatible + yb-voyager assess-migration, but a gap scan is mandatory and long-tail gaps must be verified one by one; pre-v2025.1 versions have more compatibility pitfalls); MySQL → medium (first clear the PG compatibility layer, then talk); Cassandra → low (YCQL); Oracle → high (no Oracle compatibility — application-layer rework).

• Version info: official releases page (v2026.1.1.2 STS 2026-09-10; v2025.2 LTS; v2025.2.6.0→2026.1 upgrade restriction)
• Architecture: official architecture docs (docdb-replication/raft, transactions/distributed-txns, concurrency-control, single-row-transactions, docdb-sharding/tablet-splitting), official design docs (tablet splitting, DR)
• Security: official docs (encryption-at-rest, tls-encryption, audit-logging-ysql/ycql)
• Backup/upgrades: official docs (schedule-data-backups, PITR, upgrade-deployment per version), official yugabytedb-skills
• Compatibility: official voyager known-issues (postgresql.md), official migration docs, official FAQ (compatibility)
• Licensing: official blog (2019-07-16 license change), repo LICENSE.md (independently verified); CRDB comparison: this profile repository's cockroachdb.md
• Reputation: GitHub issues (#830/#1404/#1709/#3944/#6240/#11320, ory/kratos#715, ory/hydra#2156), HN (2019 license-change discussion), dev.to field tests, community comparisons (pidgeiot, sesamefs), yb-doctor/base-14 monitoring docs
• Next review: track the v2026.2 LTS release (planned end of 2026), the PG rebase cadence, and YCQL investment direction