Skip to main content
Cockroach Labs exposes various application programming interfaces (APIs). The vast majority of changes to these interfaces are seamless additions of new functionality. However, some changes are backward-incompatible and may require you to adjust your integration. Changes to an API are introduced according to its support policy. This page includes the following information:

​
Support policies

TypeDescriptionGuarantees
StableSupported for interfacing with third-party automated tools.Backward-incompatible changes may be introduced in new major versions.
Backward-compatible changes may be introduced in new patch versions.
UnstableSupported for consumption by humans. Not supported for automation.Backward-incompatible changes may be introduced in new major and patch versions.
ReservedIntended for use by CockroachDB developers. Not supported for public use.N/A
Backward-incompatible changes to stable APIs are highlighted in the for major CockroachDB versions. Users are asked to consider backward-incompatible changes before upgrading to a new CockroachDB version.

​
Backward-incompatible changes

A change is backward-incompatible when existing automation requires an update in order to continue working. These changes are also known as “breaking changes”:
  • Removal or renaming of an endpoint, , , or session variable.
  • Removal or renaming of a SQL statement or syntax.
  • Addition, removal, or renaming of a mandatory command-line flag or HTTP field.
  • Removal or renaming of an optional command-line flag or HTTP field.
  • Change in behavior of a without fixing a bug or PostgreSQL incompatibility.
  • Removal or renaming of possible values in an ENUM session variable or .
  • Change in non-interactive shell input or output.
  • Change in behavior of a type, including the it is emitted on.
  • Renaming of a type or payload field.

​
Backward-compatible changes

A change is backward-compatible when existing automation continues to work without updates. The following list is not exhaustive:
  • Addition of an optional command-line flag or HTTP field.
  • Removal or change of any functionality documented as Preview or otherwise not fully supported.
  • Marking functionality as deprecated via in-line documentation, hints, or warnings without removing it altogether.
  • Addition or removal of a metric.
  • Addition of a structured log event type or payload field.
  • Addition of a new .

​
Versioning

A stable API may be assigned a new version number in two situations:
  • When changes are introduced to the API.
  • When a new CockroachDB version is released.

​
APIs

A mixed API includes both stable and unstable features.
InterfacePolicyVersioningNotesAvailability
PostgreSQL wire protocolStableVersioned concurrently with CockroachDBCompatible with PostgreSQL version 13.All products
SQL syntaxMixedVersioned concurrently with CockroachDBBest-effort policy to add and not remove SQL syntax. All SHOW statements are unstable, as described in the following row.All products
SHOW SQL statementsUnstableVersioned concurrently with CockroachDBThis includes all documented SQL SHOW statements, which display unstable output.All products
information_schema system catalogStableVersioned concurrently with CockroachDBAll products
pg_catalog system catalogStableVersioned concurrently with CockroachDBAll products
pg_extension system catalogStableVersioned concurrently with CockroachDBAll products
crdb_internal system catalogReservedVersioned concurrently with CockroachDBA subset of the crdb_internal system catalog is stable.All products
Built-in functionsMixedVersioned concurrently with CockroachDBAny built-in functions prefixed with crdb_internal are reserved.All products
cockroach commandsMixedVersioned concurrently with CockroachDBStability considerations for cockroach sql are described in the following row.All products
cockroach sql shellMixedVersioned concurrently with CockroachDBWhen used non-interactively, cockroach sql is stable unless your usage relies on unstable input or output. Any cockroach sql output prefixed by # is unstable. When used interactively, cockroach sql is unstable.All products
Health endpointsStableNo new versions forthcoming.All products
Prometheus endpointStableNo new versions forthcoming.Although this endpoint is not versioned, individual metrics may be added or removed in each CockroachDB release. No changes are expected to response format.CockroachDB Standard, CockroachDB Advanced, CockroachDB CockroachDB
Cluster APIMixedVersioned independently from CockroachDBFor information on supported endpoints, versioning, and stability, refer to Cluster API.CockroachDB Advanced, CockroachDB CockroachDB
DB ConsoleUnstableN/AFor stable access to the information present in this tool, use the Cluster API.CockroachDB Advanced, CockroachDB CockroachDB
LoggingMixedVersioned concurrently with CockroachDBStability varies by event type. Structured events are stable and unstructured events are unstable.CockroachDB Standard, CockroachDB Advanced, CockroachDB CockroachDB
ccloud CLIMixedVersioned independently from CockroachDBDefault output is unstable. Specify the –json argument in the CLI for stable output that follows the versioning scheme.CockroachDB Cloud
CockroachDB Cloud APIStableVersioned independently from CockroachDBCockroachDB Cloud
CockroachDB Cloud ConsoleUnstableN/ACockroachDB Cloud
Advanced Debug endpointsReservedN/AN/A

​
See also