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

# Databases

> Managed databases that Nubo runs for you

A managed database is a database we run and keep alive for you. You pick an engine and a size, and Nubo hands back a connection string. No server to set up, no backups script to babysit, no version to compile. It shows up next to your apps as a [Frame](/frames), so it starts, stops, and shows logs like everything else.

Nubo runs managed **PostgreSQL**, **MySQL**, **MongoDB**, and **Redis**. Postgres is the default and handles most jobs well, so it's a good pick if you're not sure yet.

Each database gets its own storage that sticks around. Restart it, redeploy your app, roll back: the data stays put.

## Create a database

From the dashboard:

1. Open a Project and pick the Space you want the database in.
2. Hit **New Frame** and choose **Database**.
3. Give it a name, pick an engine and version, and set a size between 1 GB and 1024 GB.
4. Click **Deploy**.

It provisions in the background and flips to **online** once it's ready, usually in under a minute.

Via API:

```bash theme={null}
curl -X POST https://shuttle.withnubo.com/v2/projects/<project_id>/spaces/<space_id>/databases \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "primary",
    "engine": "postgres",
    "storage_gb": 10
  }'
```

`engine` accepts `postgres`, `mysql`, `mongodb`, or `redis`, and defaults to `postgres` if you leave it out. Each engine has a sensible default version (`16` for Postgres, `8` for MySQL, `7` for MongoDB, `7` for Redis); pass a `version` string like `"15"` to pin a specific one.

## Get your connection details

Once the database is online, open it in the dashboard and you'll see its credentials and a ready-to-paste connection string. There's a copy button on each field, and the password stays hidden until you ask for it.

Via API:

```bash theme={null}
curl https://shuttle.withnubo.com/v2/projects/<project_id>/spaces/<space_id>/frames/<frame_id>/connection \
  -H "Authorization: Bearer <your-token>"
```

You get back the username, password, database name, and a full connection string:

```json theme={null}
{
  "engine": "postgres",
  "user": "nubo",
  "password": "••••••••",
  "database": "nubo",
  "database_url": "postgres://nubo:••••••••@db-<frame_id>-svc.<space_id>.svc.cluster.local:5432/nubo"
}
```

The `database_url` scheme matches the engine (`postgres://`, `mysql://`, `mongodb://`, or `redis://`). Redis connection strings carry only the password, with no username or database name.

The connection string is the quickest way in. A database is reachable from your apps in the same Project over the private network. It isn't exposed to the public internet, which is what you want for a database.

## Use it from your app

Most libraries take a single connection string, so the easiest path is to drop the database's URL into an [environment variable](/environment-variables) on the app that needs it.

Nubo can wire that up for you. From the database, point it at the app Frame and Nubo copies the connection string in as a variable (it uses `DATABASE_URL` unless you pick another name):

```bash theme={null}
curl -X POST https://shuttle.withnubo.com/v2/projects/<project_id>/spaces/<space_id>/frames/<db_frame_id>/inject \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "target_frame_id": "<app_frame_id>",
    "env_key": "DATABASE_URL"
  }'
```

The next time the app deploys, it picks up the variable and connects. Prefer to do it by hand? Copy the connection string and add it as a variable yourself.

## Storage

Every database is backed by a [volume](/volumes), which is the part that makes your data survive restarts and redeploys. You set the size when you create the database. The data is yours and it stays on that volume until you delete the database.

## Delete a database

Deleting a database removes it and the storage behind it. This erases the data, so take a dump first if you want to keep anything.

```bash theme={null}
curl -X DELETE https://shuttle.withnubo.com/v2/projects/<project_id>/spaces/<space_id>/frames/<frame_id> \
  -H "Authorization: Bearer <your-token>"
```

Nubo automatically removes any variable it injected from this database when you delete it, so an injected connection string cleans itself up. If you copied the connection string into an app by hand, remember to remove that variable yourself so a later deploy doesn't try to reach a database that's gone.

## Plans and limits

A database's size can be anywhere from 1 GB to 1024 GB. How much total storage you can use depends on your plan. See [Plans](/plans) for the current limits.

## Managed Nubo vs self-hosted agents

* **Managed Nubo**: managed databases work as described here. We run the engine and the storage, and you just use the connection string.
* **Self-hosted agents**: there's no managed database, but you can run your own. Deploy the database as a Frame and attach a [volume](/volumes) for its data. It lives on your hardware, so remember to back it up.

## Related

<Card title="Volumes" icon="hard-drive" href="/volumes">
  The persistent storage behind every database
</Card>

<Card title="Environment variables" icon="key" href="/environment-variables">
  Where your connection string lives in your app
</Card>

<Card title="Frames" icon="square-dashed" href="/frames">
  Databases run as Frames, like your apps
</Card>