Skip to main content
Applies to: Embedded ❌, Enterprise ✅ A database is the catalog’s top-level container: it holds namespaces, which hold tables, views and other objects. Database statements name one database, independently of the session’s current database. Database creation uses the deployment’s native catalog and storage settings.

​
CREATE DATABASE

Creates a persistent database. Requires CREATE DATABASE on the system, and ownership of the database name if it already has an owner. The caller becomes the owner of a new name, following the same rules as the REST API. The result has operation, name, and status columns. Status is created, or already_exists with IF NOT EXISTS. Without that clause, an existing database is an error. Creation never overwrites an existing database.
WITH options are unsupported on CREATE DATABASE. Use ATTACH DATABASE below to register a database at an existing location. The system database and reserved storage names cannot be created.

​
DESCRIBE DATABASE

Requires USAGE on the database. Returns one row with name and properties. Properties are the catalog’s metadata encoded as a JSON object; a database without metadata returns {}, and a database mid CASCADE drop reports a transient property marking it as dropping. A missing database is an error. DESCRIBE DATABASE system returns empty properties and requires system USAGE.

​
SHOW DATABASES

Returns a sorted name column containing the databases the caller has USAGE on, including system when permitted. LIKE and WHERE filters are unsupported.

​
ATTACH DATABASE

Registers an existing database at a path relative to the catalog’s storage root, or at an external S3, GCS or Azure location, instead of creating a new one. location is the only supported option — naming a storage integration explicitly is refused. For an external location, the deployment automatically binds the most specific storage integration whose prefix covers it; one must already exist. An Azure location must be account-qualified (az://container@account.blob.core.windows.net/path); a bare az://container/path is refused. ATTACH DATABASE requires the same creation privileges as CREATE DATABASE. For an external location, it also requires USAGE on the storage integration that binds it, and on that integration’s own database and namespace; the integration itself must live in a native, root-backed database under the catalog root. Attaching writes Enterprise’s own tracking metadata into the location to bring it under management — it does not rewrite, move, or re-encode any existing table’s data.
A relative-path location never accepts an absolute path (/tmp/db), a file:// URI, a Windows path (C:/db), a .. segment, an empty string, or a doubled slash (sub//db). An S3 or GCS location must be a concrete prefix, not a bare scheme (s3://) on its own.
IF NOT EXISTS makes the statement a no-op rather than an error when the database is already attached.
A quoted name reaches characters a bare identifier cannot, such as ATTACH DATABASE "team/search" WITH (location = 'team-search'). Removing an externally attached database with DROP DATABASE unregisters the attachment and releases its storage-integration reference, without deleting the underlying data.

​
DROP DATABASE

Requires USAGE and OWNERSHIP on the database. The default, RESTRICT, refuses a database that still contains objects. CASCADE refuses new objects in the database, revokes every grant in it, and starts a job that drops its contents; deployments without cascade support reject it. An externally attached database cannot be dropped with CASCADE. RESTRICT returns operation, name, and status columns: dropped, or not_found with IF EXISTS for a missing database. CASCADE returns operation, job_id, and status columns: the job’s id with dropping, or an empty job_id with not_found. The name stays taken until the job finishes and the dropped storage is cleaned up. The system database and federated databases cannot be dropped.
ALTER DATABASE is unsupported.

​
What to read next

Namespace

CREATE SCHEMA inside an attached database.

Table

Creating tables once a database and namespace exist.

Database

The SDK equivalent, and connection settings.