Databases
create_database, attach_database, detach_database, get_database, list_databases and delete_database — managed databases for your apps, provisioned on demand.
A database is a managed addon for an app: a real PostgreSQL, MySQL, or Redis instance that agenthost provisions and runs for you. Databases are opt-in — they are never created automatically. You ask for one when an app needs it, and agenthost wires it in.
You never handle the connection string
The database is private (reachable only by your app, on the internal network). Its connection
string — including the auto-generated password — is injected into your app as an environment
variable, server-side. You never see or paste the password: you just read the variable the tool
tells you about (DATABASE_URL, or REDIS_URL for redis) from process.env in your app code.
The flow
create_databasean app needs a database → provision one (optionally attaching it to the app in the same call withapp_id).- Read the returned variable name (e.g.
DATABASE_URL) and use it in your app code:const db = new Pool({ connectionString: process.env.DATABASE_URL }). - Deploy the app. The variable is already set — no credentials in your source.
An app plus the databases it relies on is its ApplicationSet — get_app lists them, and
get_database lists the apps wired to it.
create_database
Provision a managed database inside a project, on demand.
| Parameter | Type | Description |
|---|---|---|
project_id | uuid, required | Project the database belongs to. |
name | string, required | Database name, unique within the project. |
engine | enum, required | postgresql, mysql, or redis. |
image | string | Optional explicit image/version, e.g. postgres:16. A sensible default is used otherwise. |
app_id | uuid | Optional app to wire the database into immediately (must be in the same project). |
env_var | string | Env var name to inject the connection string as when attaching. Defaults to DATABASE_URL / REDIS_URL. |
Provisioning is asynchronous — poll get_database for running.
attach_database
Wire an existing database into an app. Its connection string is injected into the app as an environment variable (server-side) and the app is restarted to pick it up. Returns the variable name the app should read. The app and database must be in the same project.
| Parameter | Type | Description |
|---|---|---|
database_id | uuid, required | Database to connect. |
app_id | uuid, required | App to inject the connection string into. |
env_var | string | Env var name for the connection string. Defaults to DATABASE_URL / REDIS_URL. |
detach_database
Remove the recorded link between an app and a database. The injected variable is left on the app; redeploy the app without it to fully remove.
| Parameter | Type | Description |
|---|---|---|
database_id | uuid, required | Database id. |
app_id | uuid, required | App id. |
get_database
Fetch a database by id, refreshing its live status. Includes the apps wired to it and the variable each reads.
| Parameter | Type | Description |
|---|---|---|
database_id | uuid, required | Database id. |
list_databases
List your databases, optionally filtered to one project.
| Parameter | Type | Description |
|---|---|---|
project_id | uuid | Optional project filter. |
delete_database
Tear down a database and delete it. Any apps still wired to it lose their connection; the result lists them.
| Parameter | Type | Description |
|---|---|---|
database_id | uuid, required | Database id. |
This cannot be undone
Deleting a database removes all of its data. Apps that still read its variable will fail to connect until you attach a replacement.
A database is part of what an app costs
Databases need a plan that includes apps — an account with nothing to attach one to cannot create one. They are never counted or billed on their own: "€4 a month, database included" means exactly that, so adding a database to an app you already pay for changes nothing on the invoice. See Plans & billing.