PostgreSQL databases

Create a database

1. As a team owner or admin, open Settings → Database in your project.
2. Select the environment that will use the database.
3. Choose an available tier and size, then click Create database.
4. Wait for the database to become ready, then redeploy the application.

Arvumi manages an encrypted DATABASE_URL variable for that environment. If you already have a user-defined variable with that name, remove it before creating the managed database. Managed variables cannot be overwritten as ordinary environment variables.

Connect from your application

Read DATABASE_URL from the server environment using your PostgreSQL driver. For standalone functions, add DATABASE_URL to the route’s environment allowlist. Keep connection strings out of browser code, logs, and source control.

The default application connection is pooled. Use the session connection for migrations or operations that require session locks. Select the connection type in the database settings.

One database per environment

Production, Preview, and each custom environment have separate databases and credentials. Preview deployments share the preview database. Creating a database does not copy production data or run your application’s migrations.

Tiers and connection behavior

The dashboard shows the current available sizes and capacity. Free databases use a resource-limited cluster for the team. All databases on that cluster, including production, sleep after 15 minutes without activity. A new connection wakes the cluster; allow up to two minutes and reconnect or retry when needed.

Paid databases use a dedicated, always-on cluster. Failover can briefly interrupt connections, so clients should reconnect. Query and transaction timeouts depend on the database tier and configured service limits, including migrations and remote access. Default query/transaction timeouts are 30/60 seconds for Free and 300/600 seconds for paid databases.

Connect from your computer

Database connections stay private. Team owners and admins can use the CLI to open a temporary tunnel, then connect with a SQL client or GUI:

arvumi db connect your-project --environment production

Keep the command running. It prints temporary credentials and local connection instructions. The default local address is 127.0.0.1:15432; sessions are read-only by default and last up to 30 minutes. Follow the printed client connection settings. The CLI carries remote traffic over an authenticated encrypted connection.

Run a migration

Request write access explicitly:

arvumi db connect your-project --environment production --write

Use the printed SET ROLE statement in the migration connection so new objects belong to the permanent database owner. Run your migration tool against this connection. Arvumi does not automatically run migrations for you.

Press Ctrl-C to close the tunnel and revoke its session. To inspect or revoke a remaining session:

arvumi db sessions your-project --environment production
arvumi db disconnect SESSION_UUID --project your-project

Troubleshooting

• If connection fails after inactivity, allow the free cluster to wake and retry.
• If a function cannot connect, check its environment scope, DATABASE_URL allowlist, and deployment date.
• If credentials changed, redeploy after they are reset.
• If a migration needs locks, use a session connection and explicit write access.
• If capacity, quota, or provisioning blocks access, check the database status and contact support.