sql: add sql grammar for inspect command

bghal · bghal · commit 8ffc5bf707cd · 2025-09-03T18:25:16.000-04:00
The `INSPECT` commands are being added to support data consistency validation. These new statements require new SQL grammar. The grammar is added in this change and the implementations will be added in future PRs. Epic: CRDB-30356 Part of: #148272 Release note (sql change): Introduces the `INSPECT TABLE` and `INSPECT DATABASE` statements that are unimplemented. The new `enable_inspect_command` cluster setting feature flag configures access to the new features as they're implemented.
diff --git a/docs/generated/sql/bnf/BUILD.bazel b/docs/generated/sql/bnf/BUILD.bazel
@@ -174,6 +174,9 @@ FILES = [
     "index_def",
     "insert_rest",
     "insert_stmt",
+    "inspect_stmt",
+    "inspect_database_stmt",
+    "inspect_table_stmt",
     "iso_level",
     "joined_table",
     "legacy_begin_stmt",
diff --git a/docs/generated/sql/bnf/inspect_database_stmt.bnf b/docs/generated/sql/bnf/inspect_database_stmt.bnf
@@ -0,0 +1,2 @@
+inspect_database_stmt ::=
+	'INSPECT' 'DATABASE' db_name opt_as_of_clause opt_inspect_options_clause
diff --git a/docs/generated/sql/bnf/inspect_stmt.bnf b/docs/generated/sql/bnf/inspect_stmt.bnf
@@ -0,0 +1,3 @@
+inspect_stmt ::=
+	inspect_table_stmt
+	| inspect_database_stmt
diff --git a/docs/generated/sql/bnf/inspect_table_stmt.bnf b/docs/generated/sql/bnf/inspect_table_stmt.bnf
@@ -0,0 +1,2 @@
+inspect_table_stmt ::=
+	'INSPECT' 'TABLE' table_name opt_as_of_clause opt_inspect_options_clause
diff --git a/docs/generated/sql/bnf/preparable_stmt.bnf b/docs/generated/sql/bnf/preparable_stmt.bnf
@@ -9,6 +9,7 @@ preparable_stmt ::=
 	| explain_stmt
 	| import_stmt
 	| insert_stmt
+	| inspect_stmt
 	| pause_stmt
 	| reset_stmt
 	| restore_stmt
diff --git a/docs/generated/sql/bnf/stmt_block.bnf b/docs/generated/sql/bnf/stmt_block.bnf
@@ -49,6 +49,7 @@ preparable_stmt ::=
 	| explain_stmt
 	| import_stmt
 	| insert_stmt
+	| inspect_stmt
 	| pause_stmt
 	| reset_stmt
 	| restore_stmt
@@ -246,6 +247,10 @@ insert_stmt ::=
 	opt_with_clause 'INSERT' 'INTO' insert_target insert_rest returning_clause
 	| opt_with_clause 'INSERT' 'INTO' insert_target insert_rest on_conflict returning_clause
 
+inspect_stmt ::=
+	inspect_table_stmt
+	| inspect_database_stmt
+
 pause_stmt ::=
 	pause_jobs_stmt
 	| pause_schedules_stmt
@@ -753,6 +758,12 @@ on_conflict ::=
 	| 'ON' 'CONFLICT' 'ON' 'CONSTRAINT' constraint_name 'DO' 'NOTHING'
 	| 'ON' 'CONFLICT' 'ON' 'CONSTRAINT' constraint_name 'DO' 'UPDATE' 'SET' set_clause_list opt_where_clause
 
+inspect_table_stmt ::=
+	'INSPECT' 'TABLE' table_name opt_as_of_clause opt_inspect_options_clause
+
+inspect_database_stmt ::=
+	'INSPECT' 'DATABASE' db_name opt_as_of_clause opt_inspect_options_clause
+
 pause_jobs_stmt ::=
 	'PAUSE' 'JOB' a_expr
 	| 'PAUSE' 'JOB' a_expr 'WITH' 'REASON' '=' string_or_placeholder
@@ -1260,6 +1271,7 @@ unreserved_keyword ::=
 	| 'INJECT'
 	| 'INPUT'
 	| 'INSERT'
+	| 'INSPECT'
 	| 'INSTEAD'
 	| 'INTO_DB'
 	| 'INVERTED'
@@ -2044,6 +2056,13 @@ insert_column_item ::=
 kv_option_list ::=
 	( kv_option ) ( ( ',' kv_option ) )*
 
+opt_inspect_options_clause ::=
+	'WITH' 'OPTIONS' inspect_option_list
+	| 
+
+db_name ::=
+	db_object_name
+
 session_var ::=
 	'identifier'
 	| 'identifier' session_var_parts
@@ -2940,6 +2959,9 @@ kv_option ::=
 	| 'SCONST' '=' string_or_placeholder
 	| 'SCONST'
 
+inspect_option_list ::=
+	( inspect_option ) ( ( ',' inspect_option ) )*
+
 session_var_parts ::=
 	( '.' 'identifier' ) ( ( '.' 'identifier' ) )*
 
@@ -3579,6 +3601,10 @@ only_signed_fconst ::=
 db_object_name_list ::=
 	( db_object_name ) ( ( ',' db_object_name ) )*
 
+inspect_option ::=
+	'INDEX' 'ALL'
+	| 'INDEX' '(' table_index_name_list ')'
+
 virtual_cluster_name ::=
 	'VIRTUAL_CLUSTER_NAME'
 
@@ -4163,6 +4189,7 @@ bare_label_keywords ::=
 	| 'INPUT'
 	| 'INSENSITIVE'
 	| 'INSERT'
+	| 'INSPECT'
 	| 'INSTEAD'
 	| 'INT'
 	| 'INTEGER'
diff --git a/pkg/gen/bnf.bzl b/pkg/gen/bnf.bzl
@@ -174,6 +174,9 @@ BNF_SRCS = [
     "//docs/generated/sql/bnf:index_def.bnf",
     "//docs/generated/sql/bnf:insert_rest.bnf",
     "//docs/generated/sql/bnf:insert_stmt.bnf",
+    "//docs/generated/sql/bnf:inspect_database_stmt.bnf",
+    "//docs/generated/sql/bnf:inspect_stmt.bnf",
+    "//docs/generated/sql/bnf:inspect_table_stmt.bnf",
     "//docs/generated/sql/bnf:iso_level.bnf",
     "//docs/generated/sql/bnf:joined_table.bnf",
     "//docs/generated/sql/bnf:legacy_begin_stmt.bnf",
diff --git a/pkg/gen/diagrams.bzl b/pkg/gen/diagrams.bzl
@@ -174,6 +174,9 @@ DIAGRAMS_SRCS = [
     "//docs/generated/sql/bnf:index_def.html",
     "//docs/generated/sql/bnf:insert.html",
     "//docs/generated/sql/bnf:insert_rest.html",
+    "//docs/generated/sql/bnf:inspect.html",
+    "//docs/generated/sql/bnf:inspect_database.html",
+    "//docs/generated/sql/bnf:inspect_table.html",
     "//docs/generated/sql/bnf:iso_level.html",
     "//docs/generated/sql/bnf:joined_table.html",
     "//docs/generated/sql/bnf:legacy_begin.html",
diff --git a/pkg/gen/docs.bzl b/pkg/gen/docs.bzl
@@ -184,6 +184,9 @@ DOCS_SRCS = [
     "//docs/generated/sql/bnf:index_def.bnf",
     "//docs/generated/sql/bnf:insert_rest.bnf",
     "//docs/generated/sql/bnf:insert_stmt.bnf",
+    "//docs/generated/sql/bnf:inspect_database_stmt.bnf",
+    "//docs/generated/sql/bnf:inspect_stmt.bnf",
+    "//docs/generated/sql/bnf:inspect_table_stmt.bnf",
     "//docs/generated/sql/bnf:iso_level.bnf",
     "//docs/generated/sql/bnf:joined_table.bnf",
     "//docs/generated/sql/bnf:legacy_begin_stmt.bnf",
diff --git a/pkg/sql/BUILD.bazel b/pkg/sql/BUILD.bazel
@@ -141,6 +141,7 @@ go_library(
         "information_schema.go",
         "insert.go",
         "insert_fast_path.go",
+        "inspect_node.go",
         "instrumentation.go",
         "internal.go",
         "internal_result_channel.go",
diff --git a/pkg/sql/exec_util.go b/pkg/sql/exec_util.go
@@ -4378,6 +4378,10 @@ func (m *sessionDataMutator) SetEnableScrubJob(val bool) {
 	m.data.EnableScrubJob = val
 }
 
+func (m *sessionDataMutator) SetEnableInspectCommand(val bool) {
+	m.data.EnableInspectCommand = val
+}
+
 func (m *sessionDataMutator) SetInitialRetryBackoffForReadCommitted(val time.Duration) {
 	m.data.InitialRetryBackoffForReadCommitted = val
 }
diff --git a/pkg/sql/inspect_node.go b/pkg/sql/inspect_node.go
@@ -0,0 +1,81 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+package sql
+
+import (
+	"context"
+
+	"github.com/cockroachdb/cockroach/pkg/sql/catalog"
+	"github.com/cockroachdb/cockroach/pkg/sql/privilege"
+	"github.com/cockroachdb/cockroach/pkg/sql/sem/tree"
+	"github.com/cockroachdb/cockroach/pkg/util/errorutil/unimplemented"
+	"github.com/cockroachdb/errors"
+)
+
+type inspectNode struct {
+	zeroInputPlanNode
+
+	n *tree.Inspect
+}
+
+// Inspect checks the database.
+// Privileges: INSPECT on table or database.
+func (p *planner) Inspect(ctx context.Context, n *tree.Inspect) (planNode, error) {
+	var desc catalog.Descriptor
+	switch n.Typ {
+	case tree.InspectTable:
+		tableName := n.Table.ToTableName()
+		_, tableDesc, err := p.ResolveMutableTableDescriptor(ctx, &tableName, true /* required */, tree.ResolveRequireTableDesc)
+		if err != nil {
+			return nil, err
+		}
+
+		desc = tableDesc
+	case tree.InspectDatabase:
+		dbDesc, err := p.Descriptors().ByName(p.txn).Get().Database(ctx, n.Database.ToUnresolvedName().String())
+		if err != nil {
+			return nil, err
+		}
+
+		desc = dbDesc
+	default:
+		return nil, errors.AssertionFailedf("unexpected INSPECT type received, got: %v", n.Typ)
+	}
+
+	if err := p.CheckPrivilege(ctx, desc, privilege.INSPECT); err != nil {
+		return nil, err
+	}
+
+	return &inspectNode{n: n}, nil
+}
+
+func (n *inspectNode) startExec(params runParams) error {
+	switch n.n.Typ {
+	case tree.InspectTable:
+		if !params.p.extendedEvalCtx.SessionData().EnableInspectCommand {
+			return unimplemented.New("INSPECT TABLE", "INSPECT TABLE requires the enable_inspect_command setting to be enabled")
+		}
+	case tree.InspectDatabase:
+		if !params.p.extendedEvalCtx.SessionData().EnableInspectCommand {
+			return unimplemented.New("INSPECT DATABASE", "INSPECT DATABASE requires the enable_inspect_command setting to be enabled")
+		}
+	default:
+		return errors.AssertionFailedf("unexpected INSPECT type received, got: %v", n.n.Typ)
+	}
+
+	return nil
+}
+
+func (n *inspectNode) Next(params runParams) (bool, error) {
+	return false, nil
+}
+
+func (n *inspectNode) Values() tree.Datums {
+	return nil
+}
+
+func (n *inspectNode) Close(ctx context.Context) {
+}
diff --git a/pkg/sql/logictest/testdata/logic_test/information_schema b/pkg/sql/logictest/testdata/logic_test/information_schema
@@ -4011,6 +4011,7 @@ enable_implicit_fk_locking_for_serializable                      off
 enable_implicit_select_for_update                                on
 enable_implicit_transaction_for_batch_statements                 on
 enable_insert_fast_path                                          on
+enable_inspect_command                                           off
 enable_multiple_modifications_of_table                           off
 enable_multiregion_placement_policy                              off
 enable_scrub_job                                                 off
diff --git a/pkg/sql/logictest/testdata/logic_test/inspect b/pkg/sql/logictest/testdata/logic_test/inspect
@@ -53,3 +53,58 @@ statement ok
 DROP TABLE t1;
 
 subtest end
+
+# inspect and scrub are converging so for now tests on INSPECT live here
+subtest inspect
+
+statement ok
+CREATE TABLE foo (c1 INT);
+
+statement error INSPECT TABLE requires the enable_inspect_command setting to be enabled
+INSPECT TABLE foo;
+
+statement error INSPECT DATABASE requires the enable_inspect_command setting to be enabled
+INSPECT DATABASE test;
+
+statement ok
+SET enable_inspect_command = true;
+
+statement ok
+INSPECT TABLE foo;
+
+statement ok
+INSPECT TABLE foo WITH OPTIONS INDEX (bar.public.biz);
+
+statement ok
+INSPECT TABLE foo AS OF SYSTEM TIME 1 WITH OPTIONS INDEX (bar,biz);
+
+# test permissions
+statement ok
+CREATE USER testuser2;
+
+user testuser2
+
+statement error user testuser2 does not have INSPECT privilege on relation foo
+INSPECT TABLE foo;
+
+statement error user testuser2 does not have INSPECT privilege on database test
+INSPECT DATABASE test;
+
+user root
+
+statement ok
+GRANT INSPECT ON TABLE foo TO testuser2;
+GRANT INSPECT ON DATABASE test TO testuser2;
+
+user testuser2
+
+statement ok
+SET enable_inspect_command = true;
+
+statement ok
+INSPECT TABLE foo;
+
+statement ok
+INSPECT DATABASE test;
+
+subtest end
diff --git a/pkg/sql/logictest/testdata/logic_test/pg_catalog b/pkg/sql/logictest/testdata/logic_test/pg_catalog
@@ -3024,6 +3024,7 @@ enable_implicit_fk_locking_for_serializable                      off
 enable_implicit_select_for_update                                on                  NULL      NULL        NULL        string
 enable_implicit_transaction_for_batch_statements                 on                  NULL      NULL        NULL        string
 enable_insert_fast_path                                          on                  NULL      NULL        NULL        string
+enable_inspect_command                                           off                 NULL      NULL        NULL        string
 enable_multiple_modifications_of_table                           off                 NULL      NULL        NULL        string
 enable_multiregion_placement_policy                              off                 NULL      NULL        NULL        string
 enable_scrub_job                                                 off                 NULL      NULL        NULL        string
@@ -3268,6 +3269,7 @@ enable_implicit_fk_locking_for_serializable                      off
 enable_implicit_select_for_update                                on                  NULL  user     NULL      on                  on
 enable_implicit_transaction_for_batch_statements                 on                  NULL  user     NULL      on                  on
 enable_insert_fast_path                                          on                  NULL  user     NULL      on                  on
+enable_inspect_command                                           off                 NULL  user     NULL      off                 off
 enable_multiple_modifications_of_table                           off                 NULL  user     NULL      off                 off
 enable_multiregion_placement_policy                              off                 NULL  user     NULL      off                 off
 enable_scrub_job                                                 off                 NULL  user     NULL      off                 off
@@ -3500,6 +3502,7 @@ enable_implicit_fk_locking_for_serializable                      NULL    NULL
 enable_implicit_select_for_update                                NULL    NULL     NULL     NULL        NULL
 enable_implicit_transaction_for_batch_statements                 NULL    NULL     NULL     NULL        NULL
 enable_insert_fast_path                                          NULL    NULL     NULL     NULL        NULL
+enable_inspect_command                                           NULL    NULL     NULL     NULL        NULL
 enable_multiple_modifications_of_table                           NULL    NULL     NULL     NULL        NULL
 enable_multiregion_placement_policy                              NULL    NULL     NULL     NULL        NULL
 enable_scrub_job                                                 NULL    NULL     NULL     NULL        NULL
diff --git a/pkg/sql/logictest/testdata/logic_test/show_source b/pkg/sql/logictest/testdata/logic_test/show_source
@@ -101,6 +101,7 @@ enable_implicit_fk_locking_for_serializable                      off
 enable_implicit_select_for_update                                on
 enable_implicit_transaction_for_batch_statements                 on
 enable_insert_fast_path                                          on
+enable_inspect_command                                           off
 enable_multiple_modifications_of_table                           off
 enable_multiregion_placement_policy                              off
 enable_scrub_job                                                 off
diff --git a/pkg/sql/opaque.go b/pkg/sql/opaque.go
@@ -235,6 +235,8 @@ func planOpaque(ctx context.Context, p *planner, stmt tree.Statement) (planNode,
 		return p.Grant(ctx, n)
 	case *tree.GrantRole:
 		return p.GrantRole(ctx, n)
+	case *tree.Inspect:
+		return p.Inspect(ctx, n)
 	case *tree.MoveCursor:
 		return p.FetchCursor(ctx, &n.CursorStmt)
 	case *tree.ReassignOwnedBy:
@@ -402,6 +404,7 @@ func init() {
 		&tree.FetchCursor{},
 		&tree.Grant{},
 		&tree.GrantRole{},
+		&tree.Inspect{},
 		&tree.MoveCursor{},
 		&tree.ReassignOwnedBy{},
 		&tree.RefreshMaterializedView{},
diff --git a/pkg/sql/parser/help_test.go b/pkg/sql/parser/help_test.go
@@ -623,6 +623,10 @@ func TestContextualHelp(t *testing.T) {
 		{`ALTER POLICY p1 on t1 RENAME ??`, `ALTER POLICY`},
 		{`DROP POLICY ??`, `DROP POLICY`},
 		{`SHOW POLICIES ??`, `SHOW POLICIES`},
+
+		{`INSPECT ??`, `INSPECT`},
+		{`INSPECT TABLE ??`, `INSPECT TABLE`},
+		{`INSPECT DATABASE ??`, `INSPECT DATABASE`},
 	}
 
 	// The following checks that the test definition above exercises all
diff --git a/pkg/sql/parser/sql.y b/pkg/sql/parser/sql.y
diff --git a/pkg/sql/parser/testdata/inspect b/pkg/sql/parser/testdata/inspect
diff --git a/pkg/sql/plan_names.go b/pkg/sql/plan_names.go
diff --git a/pkg/sql/scrub.go b/pkg/sql/scrub.go
diff --git a/pkg/sql/sem/tree/BUILD.bazel b/pkg/sql/sem/tree/BUILD.bazel
diff --git a/pkg/sql/sem/tree/inspect.go b/pkg/sql/sem/tree/inspect.go
diff --git a/pkg/sql/sem/tree/stmt.go b/pkg/sql/sem/tree/stmt.go
diff --git a/pkg/sql/sessiondatapb/local_only_session_data.proto b/pkg/sql/sessiondatapb/local_only_session_data.proto
diff --git a/pkg/sql/vars.go b/pkg/sql/vars.go

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+inspect_database_stmt ::=`
	`2`	`+ 'INSPECT' 'DATABASE' db_name opt_as_of_clause opt_inspect_options_clause`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+inspect_stmt ::=`
	`2`	`+ inspect_table_stmt`
	`3`	`+ \| inspect_database_stmt`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+inspect_table_stmt ::=`
	`2`	`+ 'INSPECT' 'TABLE' table_name opt_as_of_clause opt_inspect_options_clause`