Files
lancedb/docs/web/sql/ddl/database.mdx
T
Jack Ye e8a8dd1b2a feat(sql): use server-issued catalog listing tokens (#5026)
Migrates SQL-backed catalog listing APIs to `LIMIT ... FROM
'<page-token>'` and server-issued Arrow continuation metadata.
Namespace-specific APIs send an explicit `IN` schema clause, including
`IN "public"` for root, so raw SQL can default to all namespaces.

```sql
SHOW VIEWS LIMIT 100;
SHOW VIEWS IN team$ml LIMIT 100;
SHOW VIEWS IN team$ml LIMIT 100 FROM '<page-token>';
SHOW VIEWS IN other_db.team$ml LIMIT 100;
```

SDK clients forward opaque tokens unchanged, preserve empty
continuations, and decode identifier columns by name. Removes legacy
cursor reconstruction and updates the SQL reference and Python Flight
fixture. Public docs cover optional direct schema paths, all-namespace
defaults, and the shared pagination syntax across every catalog listing.
2026-11-15 08:55:42 +08:00

163 lines
6.2 KiB
Plaintext

---
title: "Database"
sidebarTitle: "Database"
description: "Create, describe, list, attach, and drop databases with SQL."
icon: database
keywords: ["database", "create database", "describe database", "show databases", "drop database", "attach database", "sql"]
availability:
embedded: unavailable
enterprise: available
---
A database is the catalog's top-level container: it holds
[namespaces](/sql/ddl/namespace), 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 {#create}
<CodeGroup>
```sql SQL icon="database"
CREATE DATABASE analytics
CREATE DATABASE IF NOT EXISTS "team/search"
```
</CodeGroup>
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.
<Note>
`WITH` options are unsupported on `CREATE DATABASE`. Use `ATTACH DATABASE`
[below](#attach) to register a database at an existing location. The
`system` database and reserved storage names cannot be created.
</Note>
## DESCRIBE DATABASE {#describe}
<CodeGroup>
```sql SQL icon="database"
DESCRIBE DATABASE analytics
DESC DATABASE "team/search"
```
</CodeGroup>
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 {#show}
```sql
SHOW DATABASES LIMIT 100;
SHOW DATABASES LIMIT 100 FROM '<page-token>';
```
Returns one non-null `name` column, sorted by database name and filtered to
databases the caller has `USAGE` on, including `system` when permitted.
Databases are above namespaces, so this command does not accept `IN` or
return a `namespace_path` column.
Page through results using `LIMIT n [FROM '<page-token>']`. Read the opaque
`lancedb.next_page_token` from the Arrow result schema metadata and pass it back
unchanged with the same object type and scope. Stop when no token is returned;
a short or empty page can still carry a continuation. See
[catalog listing pagination](/sql/pagination).
## ATTACH DATABASE {#attach}
<CodeGroup>
```sql SQL icon="database"
ATTACH DATABASE analytics WITH (location = 'analytics')
ATTACH DATABASE IF NOT EXISTS analytics WITH (location = 'analytics')
ATTACH DATABASE analytics WITH (location = 's3://customer-bucket/raw/analytics/')
ATTACH DATABASE analytics WITH (location = 'az://customer-data@customeraccount.blob.core.windows.net/raw/analytics')
```
</CodeGroup>
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](/sql/ddl/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.
<Warning>
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.
</Warning>
`IF NOT EXISTS` makes the statement a no-op rather than an error when the
database is already attached.
<Note>
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.
</Note>
## DROP DATABASE {#drop}
<CodeGroup>
```sql SQL icon="database"
DROP DATABASE analytics
DROP DATABASE IF EXISTS analytics RESTRICT
DROP DATABASE analytics CASCADE
```
</CodeGroup>
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.
<Note>
`ALTER DATABASE` is unsupported.
</Note>
## What to read next {#next}
<CardGroup cols={2}>
<Card title="Namespace" icon="folder-tree" href="/sql/ddl/namespace">
CREATE SCHEMA inside an attached database.
</Card>
<Card title="Table" icon="table" href="/sql/ddl/table">
Creating tables once a database and namespace exist.
</Card>
<Card title="Database" icon="database" href="/management/database">
The SDK equivalent, and connection settings.
</Card>
</CardGroup>