Marking features as "not yet implemented"

Owned by Raphael ‘kena’ Poss (Deactivated)
Last updated: Aug 07, 2022 by Ken Liu
3 min read

Unimplemented errors occur when CRDB recognizes a SQL feature but it is not yet supported. These unimplemented errors can be used by the product team to help prioritize the roadmap. These errors are also useful to customers when they provide links to Github issues which detail the problem as well as potential workarounds. However, to this point, CRDB does not always effectively distinguish SQL entry errors from unimplemented features and does not reliably link unimplemented feature errors to Github issues. The fact a feature is not implemented pops us as follows in CockroachDB:

  • The feature requires syntax that CRDB does not recognize at all. This causes a parse error indistinguishable from a mistake client-side.

  • The feature requires syntax that CRDB recognizes but immediately reports with an error clearly marked as "unimplemented feature." Some of these are already linked to a Github issue, some are tagged with a textual label aimed to surface in reported usage metrics, and some are not linked to any label/issue visible to PM.

This document focuses on increasing the ability of PM to track unimplemented features as well as increase the information available to customers attempting to use unimplemented features.

Process changes for new implementation work

For many reasons, CRDB may choose to not include the entirety of a SQL feature within a given release. Recent examples include CTEs or Timetz. Each time a feature is implemented partially, or an engineer is aware that there may be user demand for more than what is being implemented, the error reported should include:

  • At the very least, a marker that the feature is unsupported with a tracking label.

  • As much as possible, a link to a GitHub issue where the user can discover an explanation and possible workarounds.

  • The engineer implementing the feature should create GitHub issues as needed.

  • The Github issue should be labeled with "docs-todo" and "known-limitation."

  • Add the label X-anchored-telemetry if the issue is referenced from the product (see below), so as to prevent closure due to inactivity.

The marker that a feature is unimplemented should be placed with pgerror.UnimplementedWithIssue() (preferred) or pgerror.Unimplemented() (otherwise), so it can be recognized as an unimplemented feature error by the tracking logic that sends these messages to the reporting server (currently via (sql.Server).recordError or (*Executor).RecordError).

In some rare cases, errors may be produced on a code path that cannot propagate the error to the client. In that case, the principle outlined above still applies: the error should be registered internally inside the CockroachDB process in a place where the reporting loop can find it. The existing facility ((sql.Server).recordError or (Executor).RecordError) is suitable for this purpose. The error should also be logged (log.Errorf).

Upgrading errors with tracking labels to Github issues

Multiple places in the code already mark issues as unimplemented with a tracking label. Although this is sufficient to track attempts to use these features, it is not sufficient for users to understand the known limitation and learn about workarounds. For this purpose, the source code should be audited, and errors that only carry a reporting label should be upgraded to a link to a Github issue (including "docs-todo" and "known-limitation") that explains the limitation, provides some example of the unsupported forms, and if possible, examples of workarounds.

Multiple places in the code produce errors containing the text "unsupported" or "unimplemented" but not actually marked as an unsupported feature error that can be recognized by error tracking. For example:

alter_table.go: return errors.Errorf( "dropping %s constraint %q unsupported", details.Kind, t.Constraint) conn_io.go: panic("unimplemented")

These must be audited throughout the SQL code base and replaced by errors with suitable Github issue links (or tracking markers). See the two previous subsections for details.

Copyright (C) Cockroach Labs.
Attention: This documentation is provided on an "as is" basis, without warranties or conditions of any kind, either express or implied, including, without limitation, any warranties or conditions of title, non-infringement, merchantability, or fitness for a particular purpose.