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