---
title: "Databases"
description: "Create and manage app databases for persistent state."
---

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

# Databases

Databases give StackMachine apps durable application state for records, user data, queues, and product workflows. Create a database for an app, and StackMachine automatically exposes its connection details to that app as environment variables.

## Connect from your app

When you create a database linked to an app, StackMachine configures these environment variables for the app:

| Environment variable | Value |
| --- | --- |
| `DB_NAME` | The name of the database. |
| `DB_USERNAME` | The username used to authenticate to the database. |
| `DB_PASSWORD` | The password used to authenticate to the database. |
| `DB_HOST` | The hostname of the database, **without the port**. |
| `DB_PORT` | The port of the database. |

Read these variables in your app's server code and pass them to your database driver. You don't need to copy the credentials into the app environment manually. Environment variable values are strings, so convert `DB_PORT` to a number if your driver requires it.

```javascript
const databaseConfig = {
  database: process.env.DB_NAME,
  user: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  host: process.env.DB_HOST,
  port: Number(process.env.DB_PORT),
};
```

```python
import os

database_config = {
    "database": os.environ["DB_NAME"],
    "user": os.environ["DB_USERNAME"],
    "password": os.environ["DB_PASSWORD"],
    "host": os.environ["DB_HOST"],
    "port": int(os.environ["DB_PORT"]),
}
```

Keep database credentials in server code; don't expose them in browser bundles or logs.

## Features

### Per-app databases

Create databases against an app ID and list the databases attached to that app. The SDK returns host, port, username, and explorer URLs where available.

### Engine selection

The SDK accepts `POSTGRES`, `MYSQL`, or `SQLITE` as database engines. Use the engine that matches your application runtime and migration workflow.

### Credentials returned once

Creation and rotation return a plaintext password once for clients connecting outside the app. Store it securely. The linked app receives its credentials through the environment variables above.

### Credential rotation

Rotate database credentials from the SDK when replacing secrets or handing ownership to another environment.

## Common workflow

1. Create the database with the app ID, engine, and name.
2. Connect from the app using `DB_NAME`, `DB_USERNAME`, `DB_PASSWORD`, `DB_HOST`, and `DB_PORT`.
3. List databases to verify the attachment and inspect connection details.
4. Rotate credentials when access should change.

## SDK examples

### Create, list, and rotate credentials

Create a Postgres database for an app, inspect the connection fields, list databases, and rotate credentials. The linked app receives its connection details as environment variables automatically.

```javascript
const { database, password } = await client.apps.databases.create({
  app: "da_XYZ",
  dbEngine: "POSTGRES",
  name: "primary",
});

// The app receives DB_NAME, DB_USERNAME, DB_PASSWORD, DB_HOST, and DB_PORT.
// Store password securely if a client outside the app needs to connect.
console.log(database.host, database.port, database.username);

const databases = await client.apps.databases
  .list({ app: "da_XYZ", limit: 10 })
  .autoPagingToArray({ limit: 25 });
console.log(databases.map((item) => item.name));

const rotated = await client.apps.databases.rotateCredentials(database.id);
// Store rotated.password securely for external clients; never log it.
```

```python
from itertools import islice

result = client.apps.databases.create(
    app="da_XYZ", db_engine="POSTGRES", name="primary",
)
database = result.database
# The app receives DB_NAME, DB_USERNAME, DB_PASSWORD, DB_HOST, and DB_PORT.
# Store result.password securely if an external client needs to connect.
print(database.host, database.port, database.username)

databases = list(islice(client.apps.databases.list(app="da_XYZ", limit=10), 25))
print([item.name for item in databases])

rotated = client.apps.databases.rotate_credentials(database.id)
# Store rotated.password securely for external clients; never log it.
```

## Related docs

- [Deploy with env vars](/apps/deployments/from-files)
- [Get app by ID](/apps/get-by-id)

> Source: [stackmachine/sdks](https://github.com/stackmachine/sdks/tree/main) examples.

Source: https://docs.stackmachine.com/databases/index.mdx