Skip to main content

​
Overview

The PostgreSQL API allows you to create, manage, deploy, and monitor PostgreSQL database instances. PostgreSQL databases run as Docker containers and support automatic backups, external port configuration, and environment variable management.

​
Create PostgreSQL Database

curl -X POST https://your-dokploy-instance.com/api/postgres.create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-db",
    "appName": "prod-postgres",
    "databaseName": "myapp",
    "databaseUser": "admin",
    "databasePassword": "securePassword123!",
    "dockerImage": "postgres:18",
    "environmentId": "env_123456",
    "description": "Production PostgreSQL database"
  }'

{
  "postgresId": "pg_abc123",
  "name": "production-db",
  "appName": "prod-postgres",
  "databaseName": "myapp",
  "databaseUser": "admin",
  "dockerImage": "postgres:18",
  "applicationStatus": "idle",
  "createdAt": "2024-02-28T12:00:00Z"
}

​
Request Body

​
name
string
required
Display name for the PostgreSQL database
​
appName
string
required
Unique application name used for Docker container naming
​
databaseName
string
required
Name of the PostgreSQL database to create
​
databaseUser
string
required
Username for database authentication
​
databasePassword
string
required
Password for database authentication. Must match pattern: ^[a-zA-Z0-9@#%^&*()_+\-=[\]{}|;:,.<>?~]*$`
​
environmentId
string
required
ID of the environment where the database will be deployed
​
dockerImage
string
default:"postgres:18"
Docker image to use for PostgreSQL (e.g., postgres:18, postgres:16)
​
description
string
Optional description for the database instance
​
serverId
string
ID of the server where the database should be deployed (required in cloud environments)

​
Get PostgreSQL Database

Retrieve details about a specific PostgreSQL database instance. 
curl -X GET "https://your-dokploy-instance.com/api/postgres.one?postgresId=pg_abc123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Query Parameters

​
postgresId
string
required
Unique identifier of the PostgreSQL database

​
Deploy PostgreSQL Database

Deploy or redeploy a PostgreSQL database container. 
curl -X POST https://your-dokploy-instance.com/api/postgres.deploy \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123"
  }'

​
Request Body

​
postgresId
string
required
ID of the PostgreSQL database to deploy

​
Start PostgreSQL Database

Start a stopped PostgreSQL database container. 
curl -X POST https://your-dokploy-instance.com/api/postgres.start \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123"
  }'

​
Stop PostgreSQL Database

Stop a running PostgreSQL database container. 
curl -X POST https://your-dokploy-instance.com/api/postgres.stop \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123"
  }'

​
Reload PostgreSQL Database

Reload (restart) a PostgreSQL database container. 
curl -X POST https://your-dokploy-instance.com/api/postgres.reload \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123",
    "appName": "prod-postgres"
  }'

​
Request Body

​
postgresId
string
required
ID of the PostgreSQL database to reload
​
appName
string
required
Application name of the PostgreSQL database

​
Update PostgreSQL Database

Update PostgreSQL database configuration, including credentials, resources, and Docker image. 
curl -X POST https://your-dokploy-instance.com/api/postgres.update \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123",
    "name": "production-db-updated",
    "databasePassword": "newSecurePassword456!",
    "memoryLimit": "2g",
    "cpuLimit": "1.5"
  }'

​
Request Body

​
postgresId
string
required
ID of the PostgreSQL database to update
​
name
string
Updated display name
​
appName
string
Updated application name
​
databaseName
string
Updated database name
​
databaseUser
string
Updated database username
​
databasePassword
string
Updated database password
​
dockerImage
string
default:"postgres:18"
Updated Docker image version
​
memoryReservation
string
Memory reservation (e.g., “512m”, “1g”)
​
memoryLimit
string
Memory limit (e.g., “1g”, “2g”)
​
cpuReservation
string
CPU reservation (e.g., “0.5”, “1.0”)
​
cpuLimit
string
CPU limit (e.g., “1.0”, “2.0”)
​
command
string
Custom command to run in the container
​
args
array
Command line arguments for the PostgreSQL server
​
externalPort
number
External port to expose PostgreSQL

​
Save Environment Variables

Update environment variables for the PostgreSQL database container. 
curl -X POST https://your-dokploy-instance.com/api/postgres.saveEnvironment \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123",
    "env": "POSTGRES_MAX_CONNECTIONS=200\nPOSTGRES_SHARED_BUFFERS=256MB"
  }'

​
Request Body

​
postgresId
string
required
ID of the PostgreSQL database
​
env
string
Environment variables in KEY=VALUE format, separated by newlines

​
Save External Port

Configure external port mapping for the PostgreSQL database. 
curl -X POST https://your-dokploy-instance.com/api/postgres.saveExternalPort \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123",
    "externalPort": 5432
  }'

​
Request Body

​
postgresId
string
required
ID of the PostgreSQL database
​
externalPort
number
required
Port number to expose PostgreSQL externally. Set to null to remove external port mapping.

​
Change Status

Manually update the application status of a PostgreSQL database. 
curl -X POST https://your-dokploy-instance.com/api/postgres.changeStatus \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123",
    "applicationStatus": "done"
  }'

​
Request Body

​
postgresId
string
required
ID of the PostgreSQL database
​
applicationStatus
string
required
New status. Options: idle, running, done, error

​
Move PostgreSQL Database

Move a PostgreSQL database to a different environment. 
curl -X POST https://your-dokploy-instance.com/api/postgres.move \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123",
    "targetEnvironmentId": "env_789xyz"
  }'

​
Request Body

​
postgresId
string
required
ID of the PostgreSQL database to move
​
targetEnvironmentId
string
required
ID of the destination environment

​
Rebuild PostgreSQL Database

Rebuild the PostgreSQL database container from scratch. 
curl -X POST https://your-dokploy-instance.com/api/postgres.rebuild \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123"
  }'

​
Request Body

​
postgresId
string
required
ID of the PostgreSQL database to rebuild

​
Remove PostgreSQL Database

Delete a PostgreSQL database and all associated resources, including backups and scheduled jobs.
This action is irreversible. All database data and backups will be permanently deleted.
curl -X POST https://your-dokploy-instance.com/api/postgres.remove \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "postgresId": "pg_abc123"
  }'

​
Request Body

​
postgresId
string
required
ID of the PostgreSQL database to remove

​
Backup Operations

For backup and restore operations, see the Backup API documentation.
  • Create automated backups: backup.create
  • Manual backup: backup.manualBackupPostgres
  • Restore from backup: backup.restoreBackupWithLogs

Build docs developers (and LLMs) love

Get started for freeTalk to us