Reference¶
Scope
Look-up facts for CockroachDB: release and support matrix, license tiers, feature availability by version, default zone-configuration and cluster-setting values, ports, vector index parameters, security feature tables, published benchmark results, and a hardening checklist. For why things work the way they do, see Explanation. For step-by-step tasks, see How-to Guides.
Release and Support Matrix¶
CockroachDB ships one major version per quarter (vYY.R). Major versions alternate between Regular and Innovation releases (since 2024). Dates below come from the official docs data file (versions.csv) that drives the Release Support Policy page, checked 2026-09-25.
| Version | Type | Initial release | Maintenance support ends | Assistance support ends | LTS (first LTS patch, date) | Status on 2026-09-25 |
|---|---|---|---|---|---|---|
| v26.3 | Innovation | 2026-08-19 | 2027-02-19 | none (EOL at maintenance end) | none | Supported (newest) |
| v26.2 | Regular | 2026-04-27 | 2027-04-27 | 2027-10-27 | not yet designated | Supported (newest Regular) |
| v26.1 | Innovation | 2026-02-02 | 2026-08-02 | none | none | Unsupported |
| v25.4 | Regular | 2025-11-03 | 2027-05-03 (LTS) | 2028-05-03 (LTS) | 25.4.10, 2026-05-03 | Supported, LTS |
| v25.3 | Innovation | 2025-08-04 | 2026-02-04 | none | none | Unsupported |
| v25.2 | Regular | 2025-05-09 | 2026-12-17 (LTS) | 2027-12-17 (LTS) | 25.2.10, 2025-12-17 | Supported, LTS |
| v25.1 | Innovation | 2025-02-18 | 2025-08-18 | none | none | Unsupported |
| v24.3 | Regular | 2024-11-18 | 2026-05-05 (LTS) | 2027-05-05 (LTS) | 24.3.12, 2025-05-05 | Assistance support, LTS |
| v24.2 | Innovation | 2024-08-12 | 2025-02-12 | none | none | Unsupported |
| v24.1 | Regular | 2024-05-20 | 2025-10-21 (LTS) | 2026-10-21 (LTS) | 24.1.6, 2024-10-21 | Assistance support, ends soon |
| v23.2 | Regular | 2024-02-05 | 2025-07-08 (LTS) | 2026-07-08 (LTS) | 23.2.7, 2024-07-08 | Unsupported |
Release dates differ by channel
New versions reach selected CockroachDB Cloud organizations first. Self-hosted x.y.0 binaries follow about two weeks later, and patch binaries about one week later (Releases overview). For example, the v26.1.0 release notes are dated 2026-02-18 while the support table uses 2026-02-02. The v26.3.0 release-data entry is dated 2026-07-27 while the support table uses 2026-08-19.
Latest Patch Releases¶
| Series | Latest production patch in docs release data | Date | Newer git tags seen (endoflife.date) |
|---|---|---|---|
| v26.3 | v26.3.0 | 2026-07-27 | v26.3.1 listed as a testing build (2026-08-21) |
| v26.2 | v26.2.6 | 2026-08-21 | v26.2.7 (tagged 2026-09-21) |
| v25.4 | v25.4.16 | 2026-09-02 | v25.4.17 (tagged 2026-09-15) |
| v25.2 | v25.2.23 | 2026-08-21 | v25.2.24 (tagged 2026-09-02) |
| v24.3 | v24.3.36 | 2026-08-26 | none |
| v24.1 | v24.1.33 | 2026-08-26 | none |
Support Rules¶
| Rule | Regular release | Innovation release |
|---|---|---|
| Maintenance support | 365 days from the .0 GA release |
180 days from the .0 GA release |
| Assistance support | 180 days after maintenance ends | none. EOL when maintenance ends |
| LTS extension | Later patches can be designated LTS: maintenance runs 365 days from the first LTS patch, then 365 days of assistance | Never LTS |
| Can be skipped on upgrade | No. Every Regular release is a required upgrade step | Yes (optional) |
| CockroachDB Cloud | All plans | Advanced only (Basic and Standard get Regular releases only) |
License Tiers¶
Since v24.3.0 (2024-11-18), all new CockroachDB releases, plus patch releases of v23.1 to v24.2 made after that date, ship under the proprietary CockroachDB Software License (CSL). The free "CockroachDB Core" option is retired. Every self-hosted cluster now needs a license key. The only exception is a single-node development cluster.
| License | Cost | Who qualifies | Telemetry | Term | Support |
|---|---|---|---|---|---|
| Enterprise | Paid | Anyone | Not required | Annual or negotiated. Production, Pre-production, or Development types | Enterprise or Essential |
| Enterprise Free | Free | Businesses with under $10M total annual revenue (parent and affiliates combined). Government entities do not qualify | Required. Throttled after 7 days without telemetry | Renew annually | Community (docs, forum, Slack) |
| Enterprise Trial | Free | Anyone. 30-day self-service, at most one new trial per day | Required | 30 days | Community |
| Evaluation | Negotiated | Via sales, for extended evaluation | Negotiable | Negotiated | Enterprise level |
| No key | n/a | cockroach start-single-node and cockroach demo |
n/a | n/a | n/a |
| Throttling trigger | Effect |
|---|---|
| No license key 7 days after cluster init (multi-node) | Throttled to 5 concurrent open SQL transactions |
| Enterprise Free or Trial with no telemetry for 7 days | Throttled |
| Expired Enterprise Free | Throttled 30 days after expiry |
| Expired Enterprise Trial | Throttled 7 days after expiry |
| Expired paid Enterprise | Never throttled |
| Patch upgrade from a former "Core" build to a CSL build | 30-day grace period, then throttled |
Sources: Licensing FAQs and repo README "Licensing". The two disagree slightly on the v23.2 patch boundary: the docs name v23.2.15, the README names v23.2.16.
Enterprise Free deployment scope
An Enterprise Free license covers only your own hardware or your own public-cloud accounts. Running CockroachDB inside a customer's environment requires a paid Enterprise license. Offering CockroachDB as a service to third parties is not allowed without a license.
CockroachDB Cloud Plans¶
| Plan | Major-version upgrades | Innovation releases | Notes |
|---|---|---|---|
| Basic | Automatic | Unavailable | Serverless-style. Replaced the former "Serverless" name in 2024 |
| Standard | Automatic (default) or customer-initiated | Unavailable | Provisioned compute on multi-tenant infrastructure |
| Advanced | Customer-initiated | Optional | Dedicated clusters. Replaced the former "Dedicated" name. Supports PCI DSS and HIPAA environments |
All Cloud clusters have a valid Enterprise license automatically. See Cloud upgrade policy. Pricing: TBD. Consumption- and capacity-based pricing changes often; check cockroachlabs.com/pricing.
Feature Availability by Version¶
| Feature | Introduced | Status (as of v26.2 docs) |
|---|---|---|
| PL/pgSQL, stored procedures | v23.2 | GA |
READ COMMITTED isolation |
Preview v23.2 | GA since v24.1. Enabled by default (sql.txn.read_committed_isolation.enabled = true) |
| Physical cluster replication (PCR) | Preview v23.2 | GA since v24.1 |
VECTOR data type (pgvector-compatible) |
Preview v24.2 | GA since v25.4 |
SQL triggers (BEFORE/AFTER) |
Preview v24.3 | GA in v26.2 |
| Logical data replication (LDR, active-active) | Preview v24.3 | GA in v25.2 |
| LDAP authentication | v24.3 | Parts in preview |
| Leader leases | v25.2 | Default lease type since v25.2 (replication layer) |
| Row-level security | v25.2 | Available |
Vector indexes (CREATE VECTOR INDEX) |
Preview v25.2 | GA in v25.4 |
| JSONPath queries | Preview v25.2 | Preview |
--tls-cipher-suites restriction flag |
v25.2 | Available |
LTREE data type |
Preview v25.4 | Preview |
| JWT/OIDC group-claim role synchronization | Preview v25.4 | Preview |
Stable SQL introspection API (limits on crdb_internal) |
v25.4 | Available |
Disable root user, FIPS 140-3 readiness (Go native module) |
Preview v26.1 | Preview |
| Buffered writes | v26.2 GA | GA |
| Hash-sharded indexes with prefix shard columns | v26.2 | GA |
Post-quantum TLS 1.3 key exchange (X25519MLKEM768) |
Preview v26.2 | Preview |
| Active Session History (ASH) | Preview v26.2 | Preview, disabled by default |
| Role-based and table-based SQL audit logging | Earlier releases | Listed under "preview" on the feature-availability page |
| Multi-metric allocator (MMA) on by default | v26.3 | Per GitHub issue #169411. The v26.3 release notes are not yet published to the docs repo. Unverified |
Sources: release notes for v26.2, v26.1, v25.4, v25.2, and Feature availability.
Zone Configuration Variables¶
| Variable | Default | Meaning |
|---|---|---|
range_min_bytes |
134217728 (128 MiB) | Ranges below this size merge with a neighbor |
range_max_bytes |
536870912 (512 MiB) | Ranges above this size split |
gc.ttlseconds |
14400 (4 hours) | Retention of overwritten MVCC versions before garbage collection (older releases defaulted to 90000 = 25 h. The v23.1 docs already show 4 hours) |
num_replicas |
3 (5 for system database, meta, liveness and system ranges) |
Replication factor (voters plus non-voters) |
num_voters |
= num_replicas unless set |
Voting replicas. The rest are non-voting read replicas |
constraints / voter_constraints |
none | Required or prohibited locality attributes, for example +region=us-east1 |
lease_preferences |
none | Ordered preferred localities for the leaseholder |
global_reads |
false | Non-blocking transactions for GLOBAL tables |
Source: Replication zone variables.
Key Configuration Knobs¶
Cluster-setting defaults below come from the generated settings table in the cockroach repo (docs/generated/settings/settings.html, release-26.2 and master branches).
| Setting | Default | Impact |
|---|---|---|
kv.snapshot_rebalance.max_rate |
32 MiB | Rate limit for rebalance and up-replication snapshots |
server.time_until_store_dead |
5m0s | How long without gossip before a store is considered dead and its replicas are re-replicated |
kv.transaction.max_intents_bytes |
4194304 (4 MiB) | Memory budget for tracking a transaction's locks. It is not a transaction size limit |
kv.transaction.max_intents_and_locks |
0 (disabled) | Optional hard cap on writes or locks per transaction |
kv.range.range_size_hard_cap |
8.0 GiB | Writes to a range that cannot split are blocked beyond this size |
kv.range_split.by_load.enabled |
true | Load-based splitting |
kv.range_split.load_cpu_threshold |
500ms | CPU-per-second threshold for load-based splits |
kv.rangefeed.enabled |
false | Must be set to true before creating changefeeds on self-hosted clusters |
kv.allocator.load_based_rebalancing |
leases and replicas (v26.2). auto value added on master |
Load-based rebalancing mode |
kv.raft_log.disable_synchronization_unsafe |
false | Disables Raft log fsync. Risks data loss or corruption. Never enable in production |
storage.max_sync_duration |
20s | Disk operations slower than this log a warning or crash the node |
storage.max_sync_duration.fatal.enabled |
true | Crash the process on a disk stall instead of serving from a stuck disk |
sql.defaults.distsql |
auto | Distributed SQL execution mode (kept for backward compatibility) |
feature.vector_index.enabled |
true (v26.2). Had to be enabled manually in v25.2 preview | Allows vector indexes |
server.user_login.password_encryption |
scram-sha-256 | Password hash method |
enterprise.license |
empty | License key |
kv.range.max_bytes is not a cluster setting
Range size is set per zone with range_max_bytes (see above). Earlier versions of this note listed a kv.range.max_bytes cluster setting and a kv.raft_log.disable_fsync setting. Neither exists.
Default Ports¶
| Port | Use |
|---|---|
| 26257 | SQL (PostgreSQL wire protocol) and inter-node RPC (--listen-addr). --sql-addr can split SQL onto its own port |
| 8080 | DB Console and HTTP API (--http-addr) |
Vector Index Parameters¶
| Parameter | Default | Range / notes |
|---|---|---|
| Opclass | vector_l2_ops |
Also vector_cosine_ops (<=>) and vector_ip_ops (<#>). L2 uses <-> |
min_partition_size |
16 | 1 to 1024 |
max_partition_size |
128 | At least 4 x min_partition_size, up to 4096 |
build_beam_size |
8 | Not recommended to change |
vector_search_beam_size (session) |
32 | Partitions explored per k-means tree level. Higher values give better recall but more CPU and latency |
Known limitations (v26.2): IMPORT INTO is not supported on tables with vector indexes. vector_l1_ops, bit_hamming_ops, and bit_jaccard_ops are not implemented. Filters are accelerated only when they match prefix columns. No index recommendations are made for vector indexes. Backfilling a vector index on a non-empty table blocks writes to that table. Source: Vector indexes.
Privilege Hierarchy¶
| Level | Grantable Privileges |
|---|---|
| System | CREATEROLE, CREATELOGIN, CREATEDB, CONTROLJOB, VIEWACTIVITY, MODIFYCLUSTERSETTING (and others) |
| Database | ALL, CREATE, DROP, CONNECT, EXTERNALCONNECTION |
| Schema | ALL, CREATE, DROP, USAGE |
| Table | ALL, SELECT, INSERT, UPDATE, DELETE, DROP, ALTER |
Security Feature Matrix¶
| Capability | Mechanism | License needed (self-hosted) |
|---|---|---|
| Inter-node encryption | Mutual TLS with node certificates from the cluster CA | Any |
| Client encryption | TLS. TLS 1.3 recommended, with post-quantum hybrid key exchange in preview (v26.2) | Any |
| Client authentication | Certificates (CN or, in preview, SAN mapping), SCRAM-SHA-256 passwords, GSSAPI/Kerberos, JWT cluster SSO, LDAP | Any valid key (Enterprise, Free, or Trial) |
| DB Console SSO | OIDC | Any valid key |
| Certificate revocation | OCSP (no CRL support) | Any valid key |
| Encryption at rest | AES-CTR on Pebble files. 128-, 192- or 256-bit store keys; data keys rotate automatically | Any valid key |
| Audit logging | Role-based (sql.log.user_audit) and table-based (EXPERIMENTAL_AUDIT) |
Any valid key |
| Access control | RBAC, row-level security (v25.2+) | Any |
| Host-based authentication | server.host_based_authentication.configuration (pg_hba syntax) |
Any |
Since the Core license was retired, "Enterprise-only" features are available to every licensed cluster, including Enterprise Free and Trial. See Security overview.
Security Best Practices¶
Production Security Checklist
- Use mutual TLS for all inter-node and client-to-node communication. Never run production clusters with
--insecure. - Generate node and client certificates from a dedicated cluster CA (not a public CA). Rotate CA and node certificates before expiry and monitor certificate-expiry metrics.
- Prefer TLS 1.3 for client connections (enables PQC key exchange where supported).
- Enable encryption at rest for data subject to regulatory requirements, and keep store keys outside the data directory.
- Create dedicated SQL users per application. Never use
rootfor application workloads. Consider disablingroot(preview in v26.1). - Grant least-privilege roles. If
SELECTis enough, do not grantALL. Use row-level security for tenant isolation. - Enable role-based audit logging for privileged roles and route the
SENSITIVE_ACCESSlog channel to durable storage. - Restrict network access with host-based authentication rules, firewalls, or private connectivity (PrivateLink, VPC peering) on Cloud.
- Keep license telemetry flowing on Enterprise Free or Trial clusters. Throttling to 5 concurrent transactions is an availability risk.
Benchmarks¶
Published TPC-C Results¶
Vendor-run results from the v23.1 Performance page. These are the latest TPC-C figures Cockroach Labs publishes in its docs. They are not audited TPC results.
| Metric | CockroachDB 19.2 | CockroachDB 21.1 |
|---|---|---|
| Max warehouses at max efficiency | 100,000 | 140,000 |
| Max throughput (tpmC) | 1,245,462 | 1,684,437 |
| Efficiency (%) | 98.81 | 95.45 |
| Max rows (billion) | 49.8 | 69.7 |
| Max unreplicated data (TB) | 8 | 11.2 |
| Number of nodes | 81 | 81 |
Latency and Scale¶
| Dimension | Published figure | Source / caveat |
|---|---|---|
| Single-row read, single AZ | ~1 ms | v23.1 Performance page |
| Single-row write, single AZ | ~2 ms | v23.1 Performance page |
| Cross-zone / cross-region | Dominated by network RTT. A write needs a Raft quorum, so it pays at least one RTT to the nearest voter quorum | Architecture docs. No published fixed numbers |
| Linear scaling | Near-linear KV95 throughput from 16 to 256 nodes (AWS c5d.4xlarge) |
v23.1 Performance page |
| Range size | 512 MiB default max, 8 GiB hard cap | Zone config and settings docs |
| Per-transaction lock tracking budget | 4 MiB (kv.transaction.max_intents_bytes) |
Settings table. Larger transactions still work but fall back to coarser range-level tracking |
Plan capacity with your own tests
The published numbers are vendor benchmarks on specific hardware and older versions. Run cockroach workload (TPC-C, KV, YCSB) against your own hardware, schema and topology before you size a cluster.