Quickstart
Create a database, connect your app to it and run your first query.
You need a Helipod API key with Database API enabled. To set the variable on your app in step 3, the key also needs Container API.
export HELIPOD_KEY=hel_your_key
export API=https://api.helipod.io/apiFind your project
curl $API/containers/projects -H "Authorization: Bearer $HELIPOD_KEY"Take the project id (and the environment ids, if you will branch later).
export PROJECT=3b0cd5ac-ac26-4012-9b28-17466f73788cCreate the database
curl -X POST $API/databases \
-H "Authorization: Bearer $HELIPOD_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: create-db-shop" \
-d "{ \"projectId\": \"$PROJECT\" }"{
"success": true,
"data": {
"id": "9a41c0de-52b1-4f0e-9d0b-3f6c7e2a1b88",
"projectId": "3b0cd5ac-ac26-4012-9b28-17466f73788c",
"name": "my-shop",
"status": "running",
"postgresVersion": 17,
"region": "Singapore",
"databaseName": "helipod_db",
"user": "helipod_db_owner",
"plan": { "code": "FREE", "name": "Free", "tier": "free", "computeHoursIncluded": null, "computeHoursRemaining": null, "storageGbIncluded": null, "storageGbRemaining": null },
"compute": { "minCu": 0.25, "maxCu": 0.25, "suspendTimeoutSeconds": null },
"branches": [
{ "environmentId": "e1d4a0f2-6c11-4a9e-8a0e-5f2b7d1c9a33", "environmentName": "production", "name": "production", "isPrimary": true, "status": "ready", "createdAt": "2026-10-16T08:00:00.000Z" }
],
"createdAt": "2026-10-16T08:00:00.000Z"
}
}If the project already has a database, you get that one back. The call is safe to repeat.
export DB=9a41c0de-52b1-4f0e-9d0b-3f6c7e2a1b88Connect your app
Get the connection string and store it as a secret variable on your service:
URI=$(curl -s $API/databases/$DB/connection -H "Authorization: Bearer $HELIPOD_KEY" | jq -r .data.uri)
curl -X PUT $API/containers/services/$SERVICE/variables \
-H "Authorization: Bearer $HELIPOD_KEY" -H "Content-Type: application/json" \
-d "{ \"variables\": { \"DATABASE_URL\": \"$URI\" }, \"secrets\": [\"DATABASE_URL\"] }"Redeploy the service to pick up the variable. See Connection for drivers and pooling.
Create a table and query it
Writes need allowWrite: true:
curl -X POST $API/databases/$DB/query \
-H "Authorization: Bearer $HELIPOD_KEY" -H "Content-Type: application/json" \
-d '{ "sql": "create table todos (id serial primary key, title text not null)", "allowWrite": true }'
curl -X POST $API/databases/$DB/query \
-H "Authorization: Bearer $HELIPOD_KEY" -H "Content-Type: application/json" \
-d '{ "sql": "select * from todos where id > $1", "params": [0] }'{ "success": true, "data": { "readOnly": true, "command": "select", "fields": ["id", "title"], "rows": [], "rowCount": 0, "truncated": false } }Next
- Give staging its own copy of the data: Branches.
- More compute, more storage, no limits on idle time: Plans and scaling.