---
title: Databases
description: base_create_database, base_list_databases, base_drop_database, and what a slug actually provisions.
---

# Databases

The seven `base_*` tools, at a glance:

| Tool | What it does |
| --- | --- |
| `base_create_database` | Provision a new database (a dedicated database and role) |
| `base_list_databases` | List your databases |
| `base_run_sql` | Run one SQL statement against a database, as its own role |
| `base_drop_database` | Permanently drop a database — irreversible |
| `base_enable_api` | Enable the Data API for a database created before it existed |
| `base_rotate_secret` | Rotate a database's Data API secret key |
| `base_reload_schema` | Reload the Data API's schema cache after DDL run outside `base_run_sql` |

This page covers create, list, and drop. The Data API tools have their
own pages: [enable on older databases](/sherbase/enable-on-older-databases)
and [reload schema and rotate secret](/sherbase/reload-schema-and-rotate-secret).

## What a slug is

`base_create_database({ slug, project })` takes a URL-safe slug — 3 to
30 lowercase letters, digits, or underscores, and it can't start with
`pg_` (Postgres reserves that prefix). The slug names both the database
(`base_<slug>`) and a role of the same name; `project` is optional and
defaults to the calling key's home Project.

The response includes the database name, role name, a password, and a
connection string — the password is shown exactly once and can't be
retrieved again, so save it immediately. If the Data API provisioned
cleanly (it does by default), the response also carries `api_url`,
`publishable_key`, and a one-time `secret_key` — see
[the Data API](/sherbase/the-data-api).

## Listing and dropping

`base_list_databases({ project })` lists every database in a Project,
each with the same Supabase-shaped fields `base_create_database`
returns: `ref` (the slug), `status`, `database: { host, port, version }`,
and the Data API fields above (`api_url`/`publishable_key` are `null`
together whenever the Data API isn't enabled).

`base_drop_database({ slug, confirm })` permanently drops the database,
its role, and its registry row. `confirm` must exactly match `slug`, or
the call fails before anything is dropped.

## Next

[Connection strings](/sherbase/connection-strings).