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
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 |