Merge pull request #8273 from cockroachdb/user-defined-schemas

User-defined schemas

_includes/sidebar-data-v20.2.json

@@ -1038,6 +1038,12 @@
     		      "/${VERSION}/alter-role.html"
     		    ]
     		  },
+    		  {
+    		    "title": "<code>ALTER SCHEMA</code>",
+    		    "urls": [
+    		      "/${VERSION}/alter-schema.html"
+    		    ]
+    		  },
     		  {
     		    "title": "<code>ALTER SEQUENCE</code>",
     		    "urls": [
@@ -1150,6 +1156,12 @@
     		    "title": "<code>CREATE SCHEDULE FOR BACKUP</code>",
     		    "urls": [
     		      "/${VERSION}/create-schedule-for-backup.html"
+            ]
+          },
+          {
+    		    "title": "<code>CREATE SCHEMA</code>",
+    		    "urls": [
+    		      "/${VERSION}/create-schema.html"
     		    ]
     		  },
     		  {
@@ -1240,6 +1252,12 @@
     		    "title": "<code>DROP SCHEDULES</code>",
     		    "urls": [
     		      "/${VERSION}/drop-schedules.html"
+            ]
+          },
+          {
+    		    "title": "<code>DROP SCHEMA</code>",
+    		    "urls": [
+    		      "/${VERSION}/drop-schema.html"
     		    ]
     		  },
     		  {

v19.2/sql-feature-support.md

@@ -162,6 +162,7 @@ table tr td:nth-child(2) {
  Column families | ✓ | CockroachDB Extension | [Column Families documentation](column-families.html)
  Interleaved tables | ✓ | CockroachDB Extension | [Interleaved Tables documentation](interleave-in-parent.html)
  Information Schema | ✓ | Standard | [Information Schema documentation](information-schema.html)
+ User-defined Schemas | ✗ | Standard | Create, drop, and modify user-defined schemas.
  Views | ✓ | Standard | [Views documentation](views.html)
  Window functions | ✓ | Standard | [Window Functions documentation](window-functions.html)
  Common Table Expressions | Partial | Common Extension | [Common Table Expressions documentation](common-table-expressions.html)

v19.2/sql-name-resolution.md

@@ -29,6 +29,10 @@ The schema name for all stored objects in any given database is always
 objects because CockroachDB only supports a two-level storage
 structure.
 
+{{site.data.alerts.callout_info}}
+CockroachDB versions < v20.2 do not support user-defined schemas.
+{{site.data.alerts.end}}
+
 In addition to `public`, CockroachDB also supports a fixed set of
 virtual schemas, available in every database, that provide ancillary, non-stored
 data to client applications. For example,

v20.1/sql-feature-support.md

@@ -163,6 +163,7 @@ table tr td:nth-child(2) {
  Column families | ✓ | CockroachDB Extension | [Column Families documentation](column-families.html)
  Interleaved tables | ✓ | CockroachDB Extension | [Interleaved Tables documentation](interleave-in-parent.html)
  Information Schema | ✓ | Standard | [Information Schema documentation](information-schema.html)
+ User-defined Schemas | Planned | Standard | Create, drop, and modify user-defined schemas.
  Views | ✓ | Standard | [Views documentation](views.html)
  Window functions | ✓ | Standard | [Window Functions documentation](window-functions.html)
  Common Table Expressions | Partial | Common Extension | [Common Table Expressions documentation](common-table-expressions.html)

v20.1/sql-name-resolution.md

@@ -35,6 +35,10 @@ data to client applications. For example,
 [`information_schema`](information-schema.html) is provided for
 compatibility with the SQL standard.
 
+{{site.data.alerts.callout_info}}
+CockroachDB versions < v20.2 do not support user-defined schemas.
+{{site.data.alerts.end}}
+
 The list of all databases can be obtained with [`SHOW
 DATABASES`](show-databases.html). The list of all schemas for a given
 database can be obtained with [`SHOW SCHEMAS`](show-schemas.html). The

v20.2/alter-schema.md

@@ -0,0 +1,213 @@
+---
+title: ALTER SCHEMA
+summary: The ALTER SCHEMA statement modifies a user-defined schema in a database.
+toc: true
+---
+
+<span class="version-tag">New in v20.2:</span> The `ALTER SCHEMA` [statement](sql-statements.html) modifies a user-defined [schema](sql-name-resolution.html#logical-schemas-and-namespaces) in the current database. CockroachDB currently supports changing the name of the schema and the owner of the schema.
+
+## Syntax
+
+~~~
+ALTER SCHEMA ... RENAME TO <newschemaname>
+ALTER SCHEMA ... OWNER TO {<newowner> | CURRENT_USER | SESSION_USER }
+~~~
+
+### Parameters
+
+Parameter | Description
+----------|------------
+`RENAME TO ...` | Rename the schema. The new schema name must be unique within the current database and follow these [identifier rules](keywords-and-identifiers.html#identifiers).
+`OWNER TO ...` | Change the owner of the schema. You can specify the new owner by name or with the [`CURRENT_USER` or `SESSION_USER` keywords](functions-and-operators.html#special-syntax-forms).
+
+## Required privileges
+
+- To rename a schema, the user must be the owner of the schema.
+- To change the owner of a schema, the user must be the current owner of the schema and a member of the new owner [role](authorization.html#roles). The new owner role must also have the `CREATE` [privilege](authorization.html#assign-privileges) on the database to which the schema belongs.
+
+## Example
+
+### Rename a schema
+
+Suppose that you access the [SQL shell](cockroach-sql.html) as user `root`, and [create a new user](create-user.html) `max` and [a schema](create-schema.html) `org_one` with `max` as the owner:
+
+{% include copy-clipboard.html %}
+~~~ sql
+> CREATE USER max;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> CREATE SCHEMA org_one AUTHORIZATION max;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> SHOW SCHEMAS;
+~~~
+
+~~~
+     schema_name
+----------------------
+  crdb_internal
+  information_schema
+  org_one
+  pg_catalog
+  pg_extension
+  public
+(6 rows)
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> SELECT
+  nspname, usename
+FROM
+  pg_catalog.pg_namespace
+  LEFT JOIN pg_catalog.pg_user ON pg_namespace.nspowner = pg_user.usesysid
+WHERE
+  nspname LIKE 'org_one';
+~~~
+
+~~~
+  nspname | usename
+----------+----------
+  org_one | max
+(1 row)
+~~~
+
+Now, suppose you want to rename the schema:
+
+{% include copy-clipboard.html %}
+~~~ sql
+> ALTER SCHEMA org_one RENAME TO org_two;
+~~~
+
+~~~
+ERROR: must be owner of schema "org_one"
+SQLSTATE: 42501
+~~~
+
+Because you are executing the `ALTER SCHEMA` command as a non-owner of the schema (i.e., `root`), CockroachDB returns an error.
+
+[Drop the schema](drop-schema.html) and create it again, this time with with `root` as the owner.
+
+{% include copy-clipboard.html %}
+~~~ sql
+> DROP SCHEMA org_one;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> CREATE SCHEMA org_one;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> SELECT
+  nspname, usename
+FROM
+  pg_catalog.pg_namespace
+  LEFT JOIN pg_catalog.pg_user ON pg_namespace.nspowner = pg_user.usesysid
+WHERE
+  nspname LIKE 'org_one';
+~~~
+
+~~~
+  nspname | usename
+----------+----------
+  org_one | root
+(1 row)
+~~~
+
+As its owner, you can rename the schema:
+
+{% include copy-clipboard.html %}
+~~~ sql
+> ALTER SCHEMA org_one RENAME TO org_two;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> SHOW SCHEMAS;
+~~~
+
+~~~
+     schema_name
+----------------------
+  crdb_internal
+  information_schema
+  org_two
+  pg_catalog
+  pg_extension
+  public
+(6 rows)
+~~~
+
+### Change a schema's owner
+
+Suppose that you access the [SQL shell](cockroach-sql.html) as user `root`, and [create a new schema](create-schema.html) named `org_one`:
+
+{% include copy-clipboard.html %}
+~~~ sql
+> CREATE SCHEMA org_one;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> SELECT
+  nspname, usename
+FROM
+  pg_catalog.pg_namespace
+  LEFT JOIN pg_catalog.pg_user ON pg_namespace.nspowner = pg_user.usesysid
+WHERE
+  nspname LIKE 'org_one';
+~~~
+
+~~~
+  nspname | usename
+----------+----------
+  org_one | root
+(1 row)
+~~~
+
+Now, suppose that you want to change the owner of the schema `org_one` to an existing user named `max`. To change the owner of a schema, the current owner must belong to the role of the new owner (in this case, `max`), and the new owner must have `CREATE` privileges on the database.
+
+{% include copy-clipboard.html %}
+~~~ sql
+> GRANT max TO root;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> GRANT CREATE ON DATABASE defaultdb TO max;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> ALTER SCHEMA org_one OWNER TO max;
+~~~
+
+{% include copy-clipboard.html %}
+~~~ sql
+> SELECT
+  nspname, usename
+FROM
+  pg_catalog.pg_namespace
+  LEFT JOIN pg_catalog.pg_user ON pg_namespace.nspowner = pg_user.usesysid
+WHERE
+  nspname LIKE 'org_one';
+~~~
+
+~~~
+  nspname | usename
+----------+----------
+  org_one | max
+(1 row)
+~~~
+
+## See also
+
+- [`CREATE SCHEMA`](create-schema.html)
+- [`SHOW SCHEMAS`](show-schemas.html)
+- [`DROP SCHEMA`](drop-schema.html)