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:

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.

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),
};

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

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.

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
• Get app by ID

Source: stackmachine/sdks examples.