Skip to main content
PostgreSQL is a powerful, open-source relational database system with a strong reputation for reliability, feature robustness, and performance.

​
Creating a PostgreSQL Database

1

Navigate to Databases

In your Dokploy dashboard, select your environment and click Add Database > PostgreSQL.
2

Configure Basic Settings

Fill in the required information:
  • Name: Display name for the database (e.g., “Production DB”)
  • App Name: Internal DNS name (e.g., postgres-prod)
  • Description: Optional notes about the database
  • Docker Image: PostgreSQL version (default: postgres:18)
3

Set Database Credentials

Configure the initial database and user:
Database Name: myapp
Database User: appuser
Database Password: <strong-password>
Passwords cannot contain: $ ! ' " \ / or spaces
4

Deploy

Click Create to deploy your PostgreSQL database. Dokploy will:
  • Pull the PostgreSQL Docker image
  • Create a data volume at the appropriate mount path
  • Start the container with your credentials

​
Connection Information

Once deployed, you can connect to your PostgreSQL database using these credentials.
Applications in the same environment connect via internal DNS:
Host: <app-name>  # e.g., postgres-prod
Port: 5432
Database: myapp
Username: appuser
Password: <your-password>
Connection String Example:
postgresql://appuser:password@postgres-prod:5432/myapp

​
Configuration

​
Environment Variables

Customize PostgreSQL behavior by adding environment variables: 
# Performance tuning
POSTGRES_MAX_CONNECTIONS=200
POSTGRES_SHARED_BUFFERS=256MB
POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
POSTGRES_WORK_MEM=4MB

# Logging
POSTGRES_LOG_STATEMENT=all
POSTGRES_LOG_DURATION=on

# Timezone
TZ=America/New_York
Environment variables are set during container creation. Changes require redeploying the database.

​
Resource Limits

Allocate resources based on your workload:
ResourceRecommended for SmallRecommended for Large
Memory Reservation256MB2GB
Memory Limit512MB4GB
CPU Reservation0.251.0
CPU Limit0.52.0

​
Custom Docker Image

Use specific PostgreSQL versions or Alpine variants: 
# Official versions
postgres:18          # Latest version 18
postgres:16          # Version 16
postgres:15-alpine   # Version 15 with Alpine Linux

# With specific tag
postgres:16.1-alpine

​
Database Operations

​
Start and Stop

Control database availability through the UI:
  • Start: Brings the database online (status: done)
  • Stop: Gracefully shuts down the database (status: idle)
  • Reload: Restarts the container to apply changes
Stopping a database does not delete data. All data persists in the volume.

​
Rebuild Database

Completely rebuild the database container while preserving data:
  1. Navigate to Settings > Rebuild
  2. Confirm the rebuild operation
  3. Wait for the container to rebuild and restart
Rebuild operations cause downtime. Schedule during maintenance windows.

​
Volume Management

PostgreSQL data is stored in a Docker volume automatically created with the pattern: 
Volume Name: {appName}-data
Mount Path: Varies by PostgreSQL version
The mount path is automatically determined based on the Docker image version. Common paths include:
  • /var/lib/postgresql/data (most versions)
  • Version-specific paths for compatibility

​
Backup Volume Data

See the Database Backups page for automated backup configuration.

​
Advanced Configuration

​
Custom Command and Arguments

Override PostgreSQL startup configuration: Command: 
postgres
Arguments: 
-c max_connections=200
-c shared_buffers=256MB
-c effective_cache_size=1GB
-c maintenance_work_mem=128MB
-c checkpoint_completion_target=0.9

​
Health Checks

Configure Docker Swarm health checks for automatic recovery: 
{
  "test": ["CMD-SHELL", "pg_isready -U appuser"],
  "interval": 30000000000,
  "timeout": 5000000000,
  "retries": 3
}

​
Restart Policy

Ensure PostgreSQL restarts automatically on failure: 
{
  "condition": "on-failure",
  "delay": 5000000000,
  "maxAttempts": 3
}

​
Common Use Cases

Standard configuration for web applications:
# Configuration
Docker Image: postgres:16-alpine
Memory Limit: 512MB
CPU Limit: 0.5

# Environment
POSTGRES_MAX_CONNECTIONS=100
POSTGRES_SHARED_BUFFERS=128MB

​
Monitoring and Logs

View PostgreSQL logs in the Dokploy dashboard:
  1. Navigate to your PostgreSQL service
  2. Click Logs tab
  3. View real-time container output
Common log patterns: 
# Successful startup
LOG: database system is ready to accept connections

# Connection established
LOG: connection received: host=172.x.x.x port=xxxxx

# Query performance
LOG: duration: 45.123 ms statement: SELECT ...

​
Troubleshooting

Check the container logs for errors:
  1. Navigate to Logs tab
  2. Look for initialization errors
  3. Common issues:
    • Invalid credentials format
    • Insufficient permissions on volume
    • Port conflicts (if using external port)
Try rebuilding the database if logs show persistent errors.
Verify connection settings:
  • Internal: Use app name (e.g., postgres-prod) not localhost
  • External: Ensure external port is configured and deployed
  • Check that the database status is done (running)
  • Verify firewall rules allow connections
PostgreSQL may be using more memory than allocated:
  1. Increase Memory Limit in settings
  2. Adjust PostgreSQL memory settings: 
    POSTGRES_SHARED_BUFFERS=<lower-value>
POSTGRES_WORK_MEM=<lower-value>
  3. Redeploy the database
Optimize PostgreSQL configuration:
  1. Increase memory allocation
  2. Tune environment variables: 
    POSTGRES_EFFECTIVE_CACHE_SIZE=<higher-value>
POSTGRES_WORK_MEM=<higher-value>
  3. Consider upgrading to a faster disk (SSD recommended)

​
Next Steps

Setup Backups

Configure automated PostgreSQL backups

MySQL

Deploy a MySQL database

Build docs developers (and LLMs) love

Get started for freeTalk to us