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:

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:

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.

Upgrading errors with no tracking label nor Github issue link

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.