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
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 Standard, CockroachDB Advanced, self-hosted CockroachDB |
| Mixed | Versioned independently from CockroachDB | For information on supported endpoints, versioning, and stability, refer to . | CockroachDB Advanced, self-hosted CockroachDB |
| Unstable | N/A | For stable access to the information present in this tool, use the . | CockroachDB Advanced, self-hosted CockroachDB |
| Mixed | Versioned concurrently with CockroachDB | Stability varies by . Structured events are stable and unstructured events are unstable. | CockroachDB Standard, CockroachDB Advanced, self-hosted 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 Cloud |
| Stable | Versioned independently from CockroachDB | | CockroachDB Cloud |
| Unstable | N/A | | CockroachDB Cloud |
| Reserved | N/A | | N/A |
See also
