CRDB interface stability docs

- Overview of CockroachDB Interfaces - Interface Types - Stability Guarantees - The Lifecycle of Experimental, Beta, and Stable Features This commit is a modified version of @knz's API stability doc (#4326)
cockroachdb · Oct 3, 2019 · 10c9fc3 · 10c9fc3
1 parent def7fed
commit 10c9fc3
Show file tree

Hide file tree

Showing 5 changed files with 273 additions and 0 deletions.
diff --git a/_includes/sidebar-data-v19.2.json b/_includes/sidebar-data-v19.2.json
@@ -1879,6 +1879,35 @@
             ]
           }
         ]
+      },
+      {
+          "title": "Programming Interfaces",
+          "items": [
+			  {
+				  "title": "Overview",
+				  "urls": [
+					  "/${VERSION}/overview-of-apis-and-interfaces.html"
+				  ]
+			  },
+			  {
+				  "title": "Interface types",
+				  "urls": [
+					  "/${VERSION}/interface-types.html"
+				  ]
+			  },
+			  {
+				  "title": "Stability Guarantees",
+				  "urls": [
+					  "/${VERSION}/compatibility-and-programmability-guarantees.html"
+				  ]
+			  },
+			  {
+			  	  "title": "Feature lifecycle",
+			  	  "urls": [
+			  		  "/${VERSION}/experimental-feature-lifecycle.html"
+			  	  ]
+			  }
+		   ]
       }
     ]
   },

diff --git a/v19.2/compatibility-and-programmability-guarantees.md b/v19.2/compatibility-and-programmability-guarantees.md
@@ -0,0 +1,127 @@
+---
+title: Stability Guarantees
+summary: Stability commitment of various APIs throughout the lifecycle of CockroachDB.
+toc: true
+---
+
+This page outlines the stability guarantees for CockroachDB's [interfaces](overview-of-apis-and-interfaces.html) around CockroachDB's lifecycle.
+
+## Overview
+
+### Interface stability in CockroachDB's lifecycle
+
+Cockroach Labs pushes bug fixes and other updates as patch revisions to CockroachDB, with the goal that the changes will not break user applications.
+For programmable interfaces, we provide an API stability guarantee across patch revisions.
+
+Note that users are required to step through intermediate major
+versions when migrating to a newer version, as major
+changes are only introduced in major version releases. This process reduces the internal complexity of CockroachDB around live
+upgrades.
+
+### New interfaces
+
+When introducing new features or changes to CockroachDB,
+Cockroach Labs reserves a period of time to process and incorporate feedback
+from users. During these [intermediate **experimental** and **beta**
+stages](experimental-feature-lifecycle.html), changes to new interfaces can be larger and more frequent.
+
+### Interface updates
+
+In the presence of serious concerns about the behavior of a public interface, Cockroach Labs might need to update the interface.
+Updates to stable interfaces are rare, and typically occur in cases of security vulnerabilities, or cases where CockroachDB's behavior is
+incompatible with 3rd-party PostgreSQL client applications or frameworks.
+To introduce API changes, we use patch revisions that preserve compatibility with
+existing CockroachDB client applications. We enumerate the [**exceptions
+to the stability guarantees**](#exceptions-to-stability-guarantees) below.
+
+## Version and patch definitions
+
+Major versions are identified by the first two numbers in the full
+version string, and patch revisions are identified by the last number
+in the string.
+
+For example:
+
+| Version string | Major version | Patch revision |
+|----------------|---------------|----------------|
+| 2.1            | 2.1           | 0              |
+| 2.1.4          | 2.1           | 4              |
+| 19.1           | 19.1          | 0              |
+| 19.1.2         | 19.1          | 2              |
+
+## Exceptions to stability guarantees
+
+Cockroach Labs attempts to preserve compatibility between a CockroachDB major version *N* and existing applications built on major versions *N*, *N*+1, and later. There are four main exceptions to this rule: [Implementation errors](#implementation-errors) (bugs), [Incompatibility with PostgreSQL](#compatibility-with-postgresql), [Architectural changes](#architectural-changes), and [Product changes](#product-changes).
+
+| Issue in “stable” phase of major version *N*                  | Earliest version where change can occur, if backward-compatible with existing apps | Earliest version where change can occur, when backward-incompatible |
+|-----------------------------------------------------------------|------------------------------------------------------------------------------------|---------------------------------------------------------------------|
+| Implementation errors (bugs)          | *N*.(X+1)  (patch revision)                                                          | *N*.(X+1) or *N*+1 depending on severity                                |
+| Incompatibility with PostgreSQL | *N*.(X+1)  (patch revision)                                                          | *N*.(X+1) opt-in<br>*N*+1 opt-out<br>*N*+2  definitive                    |
+| Architectural changes                | *N*+1                                                                                | *N*+2                                                                 |
+| Product changes                      | *N*+1                                                                                | *N*+2                                                                 |
+
+Examples:
+
+- A bug is found in version 19.1.2. A bug fix is available, which does
+  not require changes to client apps. This fix may be implemented in
+  version 19.1.3.
+- A minor bug is found in version 19.1.3. A bug fix is available, but
+  requires minor changes to client apps or a cluster configuration
+  variable. This fix may be implemented no earlier than version 19.2.
+
+### Implementation errors
+
+If a public interface does not behave as expected, this interface may be fixed
+in a subsequent patch revision.
+
+For example, the check for SQL access privileges, or the
+output of a SQL built-in function on edge case inputs, can be
+corrected across patch revisions.
+
+Cockroach Labs uses extensive testing to ensure that existing
+clients and tools are not negatively impacted by bug fixes.
+Note that bug fixes are worked into patch releases with no consideration for
+tooling that relies on mis-behaving interfaces.
+
+### Compatibility with PostgreSQL
+
+Cockroach Labs might determine that a CockroachDB feature needs to be updated to behave like PostgreSQL if:
+
+- The feature is supported by both CockroachDB and PostgreSQL.
+- The feature has a programmable interface.
+- The feature's behavior differs between CockroachDB and PostgreSQL.
+- There are well-known or sufficiently-widely used 3rd-party tools built for PostgreSQL that do not work well with existing CockroachDB behavior.
+- Changing the feature to behave more like PostgreSQL would not be overly disruptive to existing CockroachDB-specific applications or features.
+
+For example, the rules to derive data types for intermediate results in complex [SQL scalar expressions](scalar-expressions.html) might be subject to change in order to behave more like PostgreSQL.
+
+Changes for PostgreSQL compatibility may occur in a new patch revision if there is a way to make the
+change without disrupting existing CockroachDB applications or features. If the change also requires changing
+existing CockroachDB applications or features, after the change is
+prepared by Cockroach Labs, it will be finalized and published at the
+latest in major version *N*+2.
+
+During an update's development period,
+compatibility with PostgreSQL may also be configurable with other CockroachDB interfaces,
+such as [session variables](set-vars.html) or [cluster settings](cluster-settings.html).
+
+### Architectural changes
+
+If a feature is based on an architectural choice inside CockroachDB,
+and the architecture of CockroachDB changes in such a way that the
+feature is no longer needed, that feature might be changed or removed in the next major release.
+
+For example, the output of the [`EXPLAIN` statement](explain.html) has changed significantly across major versions of
+CockroachDB due to the evolution of the [query optimizer](cost-based-optimizer.html).
+
+### Product changes
+
+When Cockroach Labs decides to change CockroachDB to better match the needs of users, some existing public interfaces may change. In such cases, existing clients will continue to work for patch revisions in the current major version and next, but may need to change in version *N*+2.
+
+For example, the features and data output of [`cockroach` commands](cockroach-commands.html) have changed across releases.
+
+## See also
+
+- [Interface Types](interface-types.html)
+- [The Lifecycle of Experimental, Beta, and Stable Features](experimental-feature-lifecycle.html)
+- [Overview of CockroachDB Interfaces](overview-of-apis-and-interfaces.html)
diff --git a/v19.2/experimental-feature-lifecycle.md b/v19.2/experimental-feature-lifecycle.md
@@ -0,0 +1,40 @@
+---
+title: The Lifecycle of Experimental, Beta, and Stable Features
+summary: The expected lifecycle of features initially marked as "experimental".
+toc: true
+---
+
+Cockroach Labs works with users and customers to design and prototype features such that the initial release of a new feature in a new major
+version of CockroachDB can be considered stable and ready for use. Some features, however, require a longer trial periods in which Cockroach Labs can gather and incorporate feedback from users in real-world scenarios.
+
+As features are released with varying levels of stability, we document all features that are not stable for production environments as “experimental” or "beta". After extensive testing, [experimental features](experimental-features.html) might be marked as “beta”. Then, after patch revisions from user feedback and design iterations have stabilized the feature, it can be considered stable.
+
+These three stages correspond to different levels of commitment from Cockroach Labs to provide support and guarantee forward
+compatibility for feature-specific APIs:
+
+| Guarantee                                                                               | Experimental | Beta              | Stable          |
+|-----------------------------------------------------------------------------------------|--------------|-------------------|-----------------|
+| Client/app built on patch revision *N*.X works on revision *N*.X+1                          | No guarantee | Yes (best effort) | Yes             |
+| Client/app built on major version *N* works on version *N*+1 with only configuration change | No guarantee | Yes (best effort) | Yes             |
+| Client/app built on major version *N* works on version *N*+1 without any changes            | No guarantee | No guarantee      | Yes (see below) |
+| Client/app built on major version *N* works on version *N*+2 with only configuration change | No guarantee | No guarantee      | Yes (see below) |
+| Client/app built on major version *N* works on version *N*+2 without any changes            | No guarantee | No guarantee      | Yes (see below) |
+
+Stable features are linked to [stronger API stability and forward compatibility guarantees](compatibility-and-programmability-guarantees.html).
+
+## Experimental markers in the SQL syntax
+
+In addition to mentioning the “experimental” or “beta” status in the documentation, a feature may be marked as such directly in its API:
+
+- By including the prefix `experimental_` in the name of an
+  identifier, for example in [session variables](show-vars.html) or
+  [built-in functions](functions-and-operators.html).
+- By including the keyword `EXPERIMENTAL` in the SQL syntax,
+  for example in [SQL statements](sql-statements.html).
+
+## See also
+
+- [The Lifecycle of Experimental, Beta, and Stable Features](experimental-features.html)
+- [Interface Types](interface-types.html)
+- [Stability Guarantees](compatibility-and-programmability-guarantees.html)
+- [Overview of CockroachDB Interfaces](overview-of-apis-and-interfaces.html)
diff --git a/v19.2/interface-types.md b/v19.2/interface-types.md
@@ -0,0 +1,51 @@
+---
+title: Interface Types
+summary: Programmable, non-programmable and reserved interfaces in CockroachDB.
+toc: true
+---
+
+To offer stability for tooling and automation, we separate CockroachDB interfaces into two stability categories: [**programmable**](#public-and-programmable-interfaces) interfaces, which are suitable for automation, testing, and other tooling, and [**non-programmable**](#public-and-non-programmable-interfaces) interfaces, which are meant for human consumption.
+
+To enable the rapid development and improvement of CockroachDB features, our [API stability and forward compatibility guarantees](compatibility-and-programmability-guarantees.html) are limited to **programmable** interfaces.
+
+Some CockroachDB features were created for the engineers who develop CockroachDB. These internal features are not meant to be consumed by users, but are often discovered through exposed interfaces. To prevent users from relying on unstable internal interfaces, we do not document how to use these features, and we refer to them as [**reserved**](#reserved-interfaces) interfaces.
+
+## Programmable interfaces
+
+Programmable interfaces are meant for interfacing with automated third-party tools. For example, the output of a [`SELECT`](selection-queries.html) query is programmable, as its output is stable across releases and ready for consumption by automated tooling.
+
+For programmable interfaces, an application or client that works with major version *N* is
+expected to work with [all releases of CockroachDB](compatibility-and-programmability-guarantees.html#version-and-patch-definitions). Compatibility with version
+*N*+1 and later depends on the stability phase, as detailed in
+[Experimental feature lifecycle](experimental-feature-lifecycle.html).
+
+Cockroach Labs is committed to documenting all programmable interfaces over time, but some interfaces might not yet be documented. If there is a programmable feature that you believe should be documented, please open a GitHub issue in our [open-source documentation repo](https://github.com/cockroachdb/docs/issues/new).
+
+## Non-programmable interfaces
+
+Non-programmable interfaces are meant to be consumed by humans and are not suitable for automation. For example, the output of a SQL [`SHOW`](show-vars.html)
+statement is exposed and documented, but non-programmable, as the output it meant to be read, but it may change significantly across minor releases.
+
+Although Cockroach Labs aims for stable input/output formats for these interfaces, the stability guarantees for non-programmable interfaces are as follows:
+
+- The data format of the inputs and outputs may change across patch
+  revisions.
+- The data format of the inputs and outputs are likely to change
+  across major versions.
+
+Not all of the non-programmable interfaces are documented. If you have a question or request regarding the usage of a non-programmable interface, please let us know on [the CockroachDB forum](https://forum.cockroachlabs.com/), or open a GitHub issue in our [open-source documentation repo](https://github.com/cockroachdb/docs/issues/new).
+
+## Reserved interfaces
+
+Reserved interfaces are meant for use by CockroachDB developers and are not suitable for any other use. These interfaces contrast with other programmable and non-programmable public interfaces. All other interfaces that are not explicitly documented as programmable or non-programmable, public features should be considered reserved. For example, some tables in the `crdb_internal` SQL virtual schema are reserved.
+
+For reserved interfaces, the stability guarantees are as follows:
+
+- The particular data format of inputs or outputs may change between
+  patch revisions.
+- We cannot guarantee accurate and up-to-date documentation.
+
+## See also
+
+- [Stability Guarantees](compatibility-and-programmability-guarantees.html)
+- [Overview of APIs and interfaces](overview-of-apis-and-interfaces.html)
diff --git a/v19.2/overview-of-apis-and-interfaces.md b/v19.2/overview-of-apis-and-interfaces.md
@@ -0,0 +1,26 @@
+---
+title: Overview of CockroachDB Interfaces
+summary: High-level list of interfaces to CockroachDB.
+toc: true
+---
+
+Interfaces to CockroachDB include:
+
+- The [command-line interface](cockroach-commands.html), which consists of the `cockroach` commands.
+- The [SQL interface](sql-feature-support.html), which includes standard SQL with CockroachDB and PostgreSQL extensions.
+
+    The CockroachDB SQL interface also includes:
+  - The client-server protocol for SQL clients. CockroachDB uses a subset of PostgreSQL's low level client-server byte protocol, called [pgwire](https://godoc.org/github.com/cockroachdb/cockroach/pkg/sql/pgwire), for data flow between CockroachDB clients and nodes.
+  - SQL [session variables](show-vars.html), which configure a SQL session.
+  - SQL introspection interfaces, as exposed by the `information_schema`, `pg_catalog` and `crdb_internal` schemas.
+- The [Admin UI](admin-ui-overview.html), which consists of an in-browser cluster visualization and management panel.
+- The [HTTP status endpoints](monitoring-and-alerting.html), which provide access to CockroachDB status variables.
+- The [RPC endpoints](https://github.com/cockroachdb/cockroach/blob/master/pkg/server/serverpb/admin.proto), which provide access to CockroachDB internal status and APIs.
+- The [cluster settings](cluster-settings.html), which configure nodes in a cluster.
+
+Each interface has parts that are programmable and non-programmable. For more information about the stability categories of interfaces for programmability, see [Interface Types](interface-types.html).
+
+## See also
+
+- [Interface Types](interface-types.html)
+- [Stability Guarantees](compatibility-and-programmability-guarantees.html)