Was this page helpful?
Caution
You're viewing documentation for an unstable version of ScyllaDB Manual. Switch to the latest stable version.
DESCRIBE SCHEMA¶
When using ScyllaDB, you may want to back up your data. In case something unexpected happens, you will be able to restore it. However, you cannot insert data into the void; because of that, you need to first restore the schema.
That is the main motivation for an introduced statement in ScyllaDB: DESCRIBE SCHEMA, which is
responsible for producing a sequence of CQL commands that can be executed in order to recreate the schema.
Aside from elements of schema, like keyspaces and tables, it also allows for restoring entities such as roles and service levels.
For more context, see the articles covering backing up and restoring the schema.
Syntax and semantics¶
DESCRIBE SCHEMA comes in three forms that differ in semantics. We will refer to those forms as “tiers”.
DESCRIBE [FULL] SCHEMA: describe elements of the non-system schema: keyspaces, tables, views, UDTs, etc. When FULL is used, it also includes the elements of the system schema, e.g. system tables. If any cluster-scope configuration overrides are stored (seeALTER CLUSTER), the correspondingALTER CLUSTER WITH ...statements lead the output, before any keyspace.DESCRIBE [FULL] SCHEMA WITH INTERNALS: in addition to the output of the previous tier, the statement also describes authentication and authorization, as well as service levels. The statements corresponding to restoring roles do not contain any information about their passwords. Aside from that, additional information about tables, materialized views, and secondary indices may be provided, e.g. the ID of a table. Cluster configuration overrides stored at any scope (cluster, keyspace, or table) are not part of theCREATEstatements; they are described by separate rows of typecluster_config,keyspace_config, ortable_config, holdingALTER CLUSTER,ALTER KEYSPACE, orALTER TABLEstatements, which follow all keyspaces. See Cluster configuration.DESCRIBE [FULL] SCHEMA WITH INTERNALS AND PASSWORDS: aside from the information retrieved as part of the previous tier, the statements corresponding to restoring roles do contain information about their passwords; namely—their hashed passwords. For more information regarding hashed passwords, see the relevant section below.
Instead of DESCRIBE, you can use its shortened form: DESC.
Output¶
As a result of the query, you will obtain a set of rows, each of which consists of four values:
keyspace_name: the name of the keyspace the entity is part of,type: the type of the entity,name: the name of the entity,create_statement: the statement that can be used to restore the entity.
All of those values are always present and represent strings using UTF-8 encoding.
The value keyspace_name can be equal to null if the corresponding entity is not part of any keyspace,
e.g. in the case of a role or a service level.
Entity types¶
The type column takes one of the following values. A tool processing the output, e.g. to restore only a
part of it, should select rows by keyspace_name, type and name rather than by parsing
create_statement.
|
|
|
|
|---|---|---|---|
|
the keyspace |
the keyspace |
|
|
the keyspace |
the user-defined type |
|
|
the keyspace |
the function |
|
|
the keyspace |
the aggregate |
|
|
the keyspace |
the table |
|
|
the keyspace |
the index |
|
|
the keyspace |
the materialized view |
|
|
|
|
The cluster configuration overrides stored at cluster scope, one |
|
the keyspace |
the keyspace |
The cluster configuration overrides stored at keyspace scope, one |
|
the keyspace |
the table |
The cluster configuration overrides stored at table scope, one |
|
|
the role |
|
|
|
the granted role |
|
|
|
the role the permission is granted to |
|
|
|
the service level |
|
|
|
the service level |
|
The rows of type keyspace_config, table_config, role, grant_role, grant_permission,
service_level and service_level_attachment are emitted only with WITH INTERNALS. The rows of the three
*_config types are the cluster configuration; they can be selected or skipped as a group, e.g. to apply the
configuration only after the data is restored.
Every create_statement in the output can be executed. Objects that ScyllaDB creates automatically are not
listed: the materialized view backing a secondary index (restored by restoring the index), the CDC log table
(created with its base table, and followed by an ALTER TABLE statement restoring its properties) and the paxos
tables. A direct DESCRIBE of such an object returns its statement as an informational CQL comment, which must
not be executed.
The rows are emitted in an order in which the statements can be executed one after the other:
without
WITH INTERNALSonly: the cluster-scopecluster_configrow,for each keyspace, in alphabetical order: the keyspace, its user-defined types (each after the types it depends on), functions, aggregates and tables; each table is followed by its indexes, its materialized views and the
ALTER TABLEstatement of its CDC log table,with
WITH INTERNALSonly: thecluster_configrow, then thekeyspace_configandtable_configrows, in keyspace order, each keyspace’s row before its tables’ rows,with
WITH INTERNALSonly: roles, role grants, permission grants, service levels and service level attachments.
Required permissions¶
No permissions are necessary to execute the first two tiers. However, executing the last tier requires that the user performing the query be a superuser.
Restoring the schema by executing the consecutive statements returned by DESCRIBE SCHEMA should be conducted by
a superuser—some of the statements may require that status. It’s advised to use the default superuser and not modify
the schema, roles, permissions, or service levels beforehand.
Restoring process and its side effects¶
When a resource is created, the current role is always granted full permissions to that resource. As a consequence, the role used to restore the backup will gain permissions to all of the resources that will be recreated. That’s one of the reasons why using a superuser to restore the schema is advised—a superuser has full access to all resources anyway.
cqlsh support¶
Statement
Required version of cqlsh
DESCRIBE [FULL] SCHEMA6.0.19
DESCRIBE [FULL] SCHEMA WITH INTERNALS6.0.19
DESCRIBE [FULL] SCHEMA WITH INTERNALS AND PASSWORDS6.0.23
Appendix I, hashed passwords¶
A hashed password is an encrypted form of a password stored by ScyllaDB to authenticate roles. The statements returned
by DESCRIBE [FULL] SCHEMA WITH INTERNALS AND PASSWORDS corresponding to recreating the roles will be of the
following form:
CREATE ROLE [IF NOT EXISTS] <role_name> WITH HASHED PASSWORD = '<hashed_password>' AND LOGIN = <boolean> AND SUPERUSER = <boolean>
The semantics of this statement is analogous to the regular CREATE ROLE statement except that it circumvents
the encryption phase of the execution and inserts the hashed password directly into the database.
See the article on authorization in ScyllaDB to learn more about it.