API Support Policy

On this page Carat arrow pointing down

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

Type Description Guarantees
Stable Supported 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.
Unstable Supported for consumption by humans. Not supported for automation. Backward-incompatible changes may be introduced in new major and patch versions.
Reserved Intended for use by CockroachDB developers. Not supported for public use. N/A

Backward-incompatible changes to stable APIs are highlighted in the release notes 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, built-in function, cluster setting, 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 built-in function without fixing a bug or PostgreSQL incompatibility.
  • Removal or renaming of possible values in an ENUM session variable or cluster setting.
  • Change in non-interactive cockroach sql shell input or output.
  • Change in behavior of a structured log event type, including the logging channel it is emitted on.
  • Renaming of a structured log event 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 logging channel.

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

Note:

A mixed API includes both stable and unstable features.

Interface Policy Versioning Notes Availability
PostgreSQL wire protocol Stable Versioned concurrently with CockroachDB Compatible with PostgreSQL version 13. All products
SQL syntax Mixed Versioned concurrently with CockroachDB Best-effort policy to add and not remove SQL syntax. All SHOW statements are unstable, as described in the following row. All products
SHOW SQL statements Unstable Versioned concurrently with CockroachDB This includes all documented SQL SHOW statements, which display unstable output. All products
information_schema system catalog Stable Versioned concurrently with CockroachDB All products
pg_catalog system catalog Stable Versioned concurrently with CockroachDB All products
pg_extension system catalog Stable Versioned concurrently with CockroachDB All products
crdb_internal system catalog Reserved Versioned concurrently with CockroachDB A subset of the crdb_internal system catalog is stable. All products
Built-in functions Mixed Versioned concurrently with CockroachDB Any built-in functions prefixed with crdb_internal are reserved. All products
cockroach commands Mixed Versioned concurrently with CockroachDB Stability considerations for cockroach sql are described in the following row. All products
cockroach sql shell Mixed Versioned concurrently with CockroachDB When 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 endpoints Stable No new versions forthcoming. All products
Prometheus endpoint Stable No 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, self-hosted CockroachDB
Cluster API Mixed Versioned independently from CockroachDB For information on supported endpoints, versioning, and stability, refer to Cluster API. CockroachDB Advanced, self-hosted CockroachDB
DB Console Unstable N/A For stable access to the information present in this tool, use the Cluster API. CockroachDB Advanced, self-hosted CockroachDB
Logging Mixed Versioned concurrently with CockroachDB Stability varies by event type. Structured events are stable and unstructured events are unstable. CockroachDB Standard, CockroachDB Advanced, self-hosted CockroachDB
ccloud CLI Mixed Versioned independently from CockroachDB Default output is unstable. Specify the –json argument in the CLI for stable output that follows the versioning scheme. CockroachDB Cloud
CockroachDB Cloud API Stable Versioned independently from CockroachDB CockroachDB Cloud
CockroachDB Cloud Console Unstable N/A CockroachDB Cloud
Advanced Debug endpoints Reserved N/A N/A

See also


Yes No
On this page

Yes No