API Support Policy

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:

• Our API support policies.
• Our definitions of backward-incompatible and backward-compatible changes.
• A summary of APIs that CockroachDB makes available.

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

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 Dedicated, CockroachDB self-hosted
Cluster API	Mixed	Versioned independently from CockroachDB.	For information on supported endpoints, see Cluster API.	CockroachDB Dedicated, CockroachDB self-hosted
DB Console	Unstable	N/A	For stable access to the information present in this tool, use the Cluster API.	CockroachDB Dedicated, CockroachDB self-hosted
Logging	Mixed	Versioned concurrently with CockroachDB.	Stability varies by event type. Structured events are stable and unstructured events are unstable.	CockroachDB Dedicated, CockroachDB self-hosted
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

• Release Support Policy
• Monitoring and Alerting