Managed PostgreSQL on Dockup: Complete Guide

Managed PostgreSQL gives an application a provisioned database with lifecycle operations that are separate from the service container. Dockup supports creation, start and stop, logs, size inspection, backups, restore through the platform, read-only users, node migration, and private networking.

The key operating principle is separation: the application image is disposable, the PostgreSQL data is durable, credentials are secrets, and database recovery must be tested independently from application rollback.

How do you create a managed PostgreSQL database?

Select the intended workspace, then create the database:

dockup db create \
  --name main-db \
  --type postgresql \
  --json

List databases to confirm the exact slug and status:

dockup db list --json

Database operations use project/db targets:

dockup db size production/main-db --json

Wait until provisioning is complete before attaching an application. Do not guess the hostname, port, username, or password from the database name.

The Free plan allows three databases in one workspace and includes $2.50 starting credit. Paid plans—Hobby at $5, Go at $20, and Pro at $35 per month—allow unlimited databases, workspaces, and deployments. CPU, RAM, and disk consumption are measured per minute against the included usage balance.

How do you connect an application securely?

Retrieve the database connection details from Dockup’s database interface and treat the connection string as a secret. Do not paste it into the repository or agent transcript.

Set it on the service:

dockup env set DATABASE_URL="$DATABASE_URL" \
  --secret \
  -s production/api \
  --json

dockup deploy production/api --wait --json

The redeploy is required because the running process received its environment at startup. The stored value is masked when environment configuration is read.

Configure application connection pooling deliberately. Too many application workers with large pools can exhaust database connections even when CPU and memory look healthy. Set pool size from workload and database capacity, not from the maximum number accepted by a framework.

Test a fresh connection after deployment. A health endpoint may confirm that the HTTP process is alive without proving that a new database session can be established.

The environment variables and secrets guide covers credential rotation and masked output.

How does private networking protect PostgreSQL traffic?

Enable a project-private network:

dockup network enable production --json

Services and managed databases in that project receive stable <slug>.internal hostnames. Redeploy the application to receive the injected internal connection variables.

To remove the database’s public listener and make it private-only:

dockup db private production/main-db --json

Restore public plus private access when required:

dockup db private production/main-db --off --json

Making the database private-only recreates its container while preserving data. Schedule and verify the change as a database operation, not as a harmless DNS edit.

Private networking controls the route, while PostgreSQL credentials control identity and authorization. Keep both. Separate projects cannot reach each other because each project has its own network.

The private networking and internal domains article provides the full topology.

How do PostgreSQL backups and restore work?

List existing backups:

dockup db backups production/main-db --json

Start a server-side backup:

dockup db backup production/main-db --json

The backup command creates a database-aware backup rather than a hot copy of the raw volume. Record the backup ID, creation time, database version, and reason.

Dockup supports restoring managed database backups through the platform. The current CLI reference does not document a dockup db restore command, so this guide does not invent one. Perform the restore from the supported Dockup interface, select the exact backup, obtain production approval, and verify the result.

A restore plan should include:

1. Recovery point and expected lost-write window.
2. Application write freeze or maintenance behavior.
3. Database and extension compatibility.
4. Fresh backup of current state when useful.
5. Restore owner and approval.
6. Application reconnection and smoke test.
7. Audit and incident record.

Backups are not proven until a restore drill succeeds. Use a non-production database or approved recovery environment to test the procedure.

Retain backups according to an approved policy. Remove obsolete recovery points only through the supported database interface after verifying that no recovery or compliance requirement still depends on them.

How do read-only PostgreSQL users work?

Additional read-only users are useful for analytics, support investigation, preview deployments, and tools that must query without writing.

List users:

dockup db users production/main-db --json

Create one with a label:

dockup db user-add production/main-db \
  --label analytics \
  --json

Capture the generated credential securely during creation and do not reproduce it in an agent response. Revoke the additional user through the supported database user-management interface when its purpose ends.

Read-only at the database permission layer is stronger than telling a query tool “do not write.” It still permits access to readable production data, so privacy and least-privilege rules apply.

Dockup automatically creates a read-only database user for a PR or branch preview in a private-networking project. The preview can reach the same production database at <slug>.internal and read data without obtaining write permission.

How do you monitor size, logs, and placement?

Inspect on-disk size:

dockup db size production/main-db --json

Review application runtime logs for connection failures without exposing passwords or full connection strings:

dockup logs production/api --json

Database maintenance can make dependent services unavailable. Schedule state-changing operations, require explicit operational approval, and communicate the impact before acting.

Move a database between nodes with a target node ID:

dockup db migrate production/main-db \
  --node <nodeId> \
  --json

Migration is a stateful operation. Confirm backup status, maintenance expectations, private-network connections, and post-move application checks.

Managed PostgreSQL production checklist

A complete runbook records:

Area	Required evidence
Identity	Exact project/db target
Connectivity	Secret connection string and tested fresh session
Network	Public, private, or private-only policy
Access	Application role and labeled read-only users
Capacity	Current size and growth review
Backups	Recent backup IDs and retention
Recovery	Successful restore drill
Operations	Start, stop, restart, and migration approval
Audit	Database mutations traceable to an actor

Application deployment rollback does not restore PostgreSQL. Database restore does not automatically roll back application code. Coordinate both only when schema compatibility requires it.

For broader scaling decisions, read database scaling strategies. For exact commands, use the Dockup CLI reference.

Design schema migrations for deploy and rollback

Application deployment and database schema change happen on different timelines. A safe migration is usually backward compatible for at least one release window: add a nullable column before requiring it, deploy code that can handle both schemas, backfill in a controlled process, and remove old structure later.

Do not make a health check perform a long migration. If the application starts several replicas, ensure only one migration runner can own the change. The PRO container exec command can run a one-shot command and propagate its real exit code:

dockup exec "npm run migrate" \
  -s production/api \
  --json

Use it only when the migration command is reviewed and the service is running on the supported main server. Capture stdout, stderr, and exit code. A successful application deploy does not imply a failed migration can be ignored.

Rotate database credentials without an outage

Create the new credential or read-only user, update the consuming service secret, redeploy, and verify a fresh connection before revoking the old credential. Existing connection pools may hide a bad new password until they reconnect.

For the primary application credential, use the supported Dockup interface and database policy. For an additional analytical user, create a labeled read-only account and distribute it only to the approved consumer.

The rotation record should list the user label, consuming services, deployment IDs, verification query, revocation time, and audit event—never the password.

Observe growth before scaling

Database size is one signal:

dockup db size production/main-db --json

Combine it with application query latency, connection count, cache behavior, backup duration, and storage growth. A larger CPU or memory allocation may not fix missing indexes or unbounded queries.

Review database scaling strategies before moving nodes or increasing resources. Managed PostgreSQL reduces provisioning work, but schema and query design remain application responsibilities.

Separate availability from correctness

A running database container proves that PostgreSQL is available, not that application queries are correct. Include a low-risk fresh connection and representative read in post-deploy verification. For a write test, use a dedicated transaction or test record that can be removed safely.

The managed PostgreSQL runbook should also state whether replicas, analytics users, previews, or background workers create additional connection pressure.

Review PostgreSQL access regularly

List extra users, confirm each label has an active owner, and remove obsolete accounts. This simple review keeps managed PostgreSQL read access from accumulating after previews, analytics projects, or support investigations end.

Start with a verifiable deployment

Create a non-production PostgreSQL database, connect a test service through a masked secret, take a backup, and complete a restore drill before production cutover.

Start free at app.dockup.ai. The Free plan is $0 per month, includes $2.50 in starting credit, and supports one workspace, three databases, and three deployments.

FAQ

Which managed database types does Dockup support?

Dockup supports PostgreSQL, MySQL, MongoDB, and Redis managed databases.

How should an application receive its PostgreSQL connection string?

Treat the connection string as a secret environment variable, set it on the exact service, and redeploy so the new container receives it.

Can Dockup create a read-only PostgreSQL user?

Yes. The database user-add command creates an additional read-only user and returns its password once at creation.

Is there a documented dockup db restore CLI command?

The current CLI reference does not document one. Dockup supports backup restore through the platform interface, so use that supported path rather than inventing a flag or command.

Does application rollback restore the PostgreSQL database?

No. Application deployment history and database backup history are separate recovery systems and must be coordinated when schema changes require both.