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 for major CockroachDB versions. Users are asked to 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.

Interface	Policy	Versioning	Notes	Availability
	Stable	Versioned concurrently with CockroachDB.	Compatible with PostgreSQL version 13.	All products
	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
	Stable	Versioned concurrently with CockroachDB.		All products
	Stable	Versioned concurrently with CockroachDB.		All products
	Stable	Versioned concurrently with CockroachDB.		All products
	Reserved	Versioned concurrently with CockroachDB.	A is stable.	All products
	Mixed	Versioned concurrently with CockroachDB.	Any built-in functions prefixed with crdb_internal are reserved.	All products
	Mixed	Versioned concurrently with CockroachDB.	Stability considerations for cockroach sql are described in the following row.	All products
	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
	Stable	No new versions forthcoming.		All products
	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 CockroachDB Dedicated, CockroachDB CockroachDB
	Mixed		For information on supported endpoints, see .	CockroachDB CockroachDB Dedicated, CockroachDB CockroachDB
	Unstable	N/A	For stable access to the information present in this tool, use the .	CockroachDB CockroachDB Dedicated, CockroachDB CockroachDB
	Mixed	Versioned concurrently with CockroachDB.	Stability varies by . Structured events are stable and unstructured events are unstable.	CockroachDB CockroachDB Dedicated, CockroachDB CockroachDB
	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 CockroachDB Cloud
	Stable	Versioned independently from CockroachDB.		CockroachDB CockroachDB Cloud
CockroachDB CockroachDB Cloud Console	Unstable	N/A		CockroachDB CockroachDB Cloud
	Reserved	N/A		N/A

See also