lancedb/docs/web/sql/ddl/database.mdx

---
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}

<CodeGroup>
```sql SQL icon="database"
SHOW DATABASES
```
</CodeGroup>

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 {#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>