> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Database

> Create, describe, list, attach, and drop databases with SQL.

**Applies to:** Embedded ❌, Enterprise ✅

A database is the catalog's top-level container: it holds
[namespaces](https://docs.lancedb.com/sql/ddl/namespace.md), 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

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
CREATE DATABASE analytics
CREATE DATABASE IF NOT EXISTS "team/search"
```

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.

## DESCRIBE DATABASE

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
DESCRIBE DATABASE analytics
DESC DATABASE "team/search"
```

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

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
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

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
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')
```

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](https://docs.lancedb.com/sql/ddl/storage-integration.md) 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.

`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.

## DROP DATABASE

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
DROP DATABASE analytics
DROP DATABASE IF EXISTS analytics RESTRICT
DROP DATABASE analytics CASCADE
```

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.

## What to read next

> [card] [Namespace](https://docs.lancedb.com/sql/ddl/namespace.md)
>
> CREATE SCHEMA inside an attached database.

> [card] [Table](https://docs.lancedb.com/sql/ddl/table.md)
>
> Creating tables once a database and namespace exist.

> [card] [Database](https://docs.lancedb.com/management/database.md)
>
> The SDK equivalent, and connection settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.