Databases

Dokploy provides built-in support for popular database systems, making it easy to deploy and manage databases alongside your applications. Each database runs as a containerized service with automated backups, monitoring, and management.

Supported Databases

Dokploy supports five major database systems:

PostgreSQL

Full-featured relational database with advanced features and excellent performance.

MySQL

Popular open-source relational database, ideal for web applications.

MariaDB

MySQL-compatible database with enhanced features and performance improvements.

MongoDB

Document-oriented NoSQL database for flexible, schema-less data storage.

Redis

In-memory data store for caching, session management, and real-time applications.

Creating a Database

Databases are created within environments, similar to applications. Each database type requires specific configuration:

Common Configuration

All databases share these common properties:

name

string

required

Display name for your database (shown in the UI)

appName

string

required

Unique internal identifier (auto-generated if not provided)

description

string

Optional description to help identify the database’s purpose

dockerImage

string

required

Docker image to use (e.g., postgres:16, mysql:8, mongo:7, redis:7)

environmentId

string

required

The environment where this database will be deployed

PostgreSQL

PostgreSQL is a powerful, open-source relational database system.

Configuration

databaseName

string

required

Name of the database to create

databaseUser

string

required

Username for database access

databasePassword

string

required

Password for the database user (stored securely)

dockerImage

string

default:"postgres:16"

PostgreSQL version to use

Example Configuration

{
  name: "Main Database",
  databaseName: "myapp_production",
  databaseUser: "myapp_user",
  databasePassword: "secure_password_here",
  dockerImage: "postgres:16",
  environmentId: "env_123"
}

Connection String

postgresql://myapp_user:secure_password_here@postgres-appname:5432/myapp_production

The hostname uses the internal Docker network name. From your applications, use the appName as the hostname.

Schema Reference

PostgreSQL databases are stored with this structure:

interface Postgres {
  postgresId: string;
  name: string;
  appName: string;
  databaseName: string;
  databaseUser: string;
  databasePassword: string;
  description?: string;
  dockerImage: string;
  command?: string;
  env?: string;
  externalPort?: number;
  applicationStatus: "idle" | "running" | "done" | "error";
  environmentId: string;
  serverId?: string;
}

MySQL

MySQL is one of the most popular open-source relational databases.

Configuration

databaseName

string

required

Name of the database to create

databaseUser

string

required

Username for database access

databasePassword

string

required

Password for the database user

databaseRootPassword

string

required

Root password for MySQL (administrative access)

dockerImage

string

default:"mysql:8"

MySQL version to use

Connection String

mysql://myapp_user:secure_password_here@mysql-appname:3306/myapp_production

MariaDB

MariaDB is a MySQL-compatible database with enhanced features.

Configuration

MariaDB uses the same configuration structure as MySQL:

databaseName

string

required

Database name

databaseUser

string

required

Database username

databasePassword

string

required

User password

databaseRootPassword

string

required

Root password

dockerImage

string

default:"mariadb:11"

MariaDB version to use

Connection String

mysql://myapp_user:secure_password_here@mariadb-appname:3306/myapp_production

MongoDB

MongoDB is a document-oriented NoSQL database.

Configuration

databaseName

string

required

Name of the MongoDB database

databaseUser

string

required

Username with access to the database

databasePassword

string

required

Password for the database user

dockerImage

string

default:"mongo:7"

MongoDB version to use

Connection String

mongodb://myapp_user:secure_password_here@mongo-appname:27017/myapp_production

Authentication Database

By default, MongoDB uses the database name for authentication. If you need to use a different auth database:

mongodb://myapp_user:secure_password_here@mongo-appname:27017/myapp_production?authSource=admin

Redis

Redis is an in-memory data structure store used as a database, cache, and message broker.

Configuration

databasePassword

string

required

Password for Redis authentication

dockerImage

string

default:"redis:7"

Redis version to use

Redis doesn’t use traditional database names or users. It uses a single password for authentication.

Connection String

redis://:secure_password_here@redis-appname:6379

Or for Redis clients that support separate auth:

Host: redis-appname
Port: 6379
Password: secure_password_here

Resource Management

All databases support resource allocation controls:

memoryReservation

string

Minimum memory guaranteed (e.g., “512m”, “1g”)

memoryLimit

string

Maximum memory the database can use (e.g., “2g”, “4g”)

cpuReservation

string

Minimum CPU guaranteed (e.g., “0.5”, “1.0”)

cpuLimit

string

Maximum CPU the database can use (e.g., “2.0”, “4.0”)

Always set memory limits for databases to prevent them from consuming all available system memory. Databases like PostgreSQL and MongoDB can be memory-intensive.

Persistence & Mounts

Databases typically require persistent storage to preserve data across container restarts:

Volume Mounts

// Example: PostgreSQL data volume
{
  type: "volume",
  volumeName: "postgres-data",
  mountPath: "/var/lib/postgresql/data"
}

Common Mount Paths

PostgreSQL: /var/lib/postgresql/data
MySQL: /var/lib/mysql
MariaDB: /var/lib/mysql
MongoDB: /data/db
Redis: /data

Dokploy automatically creates and manages volumes for your databases. You can also configure additional mounts for custom configuration files.

Backups

Dokploy provides automated backup functionality for all databases:

Configuring Backups

schedule

string

required

Cron expression for backup schedule (e.g., 0 2 * * * for daily at 2 AM)

enabled

boolean

default:true

Enable or disable the backup schedule

destinationId

string

required

Storage destination for backups (S3, local storage, etc.)

Backup Destinations

Backups can be stored in:

Local filesystem
AWS S3
S3-compatible storage (MinIO, DigitalOcean Spaces, etc.)
Remote servers via SFTP

Example Backup Configuration

{
  postgresId: "db_123",
  schedule: "0 2 * * *",     // Daily at 2 AM
  enabled: true,
  prefix: "prod-backup",
  databaseType: "postgres",
  destinationId: "dest_456"
}

Manual Backups

You can also trigger backups manually through the UI or API:

POST /api/backup.create
{
  "postgresId": "db_123",
  "destinationId": "dest_456"
}

External Access

By default, databases are only accessible within the internal Docker network. To expose a database externally:

externalPort

number

Port to expose on the host machine (e.g., 5432, 3306, 27017, 6379)

Exposing databases to the internet is a security risk. Only expose databases when absolutely necessary and ensure you:

Use strong passwords
Configure firewall rules
Enable SSL/TLS when possible
Limit access by IP address

Environment Variables

Custom environment variables can be added to databases:

# PostgreSQL example
PGDATA=/var/lib/postgresql/data/pgdata
POSTGRES_INITDB_ARGS=--encoding=UTF8 --locale=en_US.utf8

# MySQL example
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci

# MongoDB example
MONGO_INITDB_DATABASE=myapp

# Redis example
REDIS_MAXMEMORY=256mb
REDIS_MAXMEMORY_POLICY=allkeys-lru

Advanced Configuration

Custom Commands

Override the default container command:

// PostgreSQL with custom config
command: "postgres -c max_connections=200 -c shared_buffers=256MB"

// MySQL with custom settings
command: "mysqld --max_connections=200 --innodb_buffer_pool_size=256M"

// Redis with custom config
command: "redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru"

Configuration Files

Mount custom configuration files:

// PostgreSQL postgresql.conf
{
  type: "file",
  filePath: "/etc/postgresql/postgresql.conf",
  content: `
    max_connections = 200
    shared_buffers = 256MB
    work_mem = 4MB
  `
}

// MySQL my.cnf
{
  type: "file",
  filePath: "/etc/mysql/my.cnf",
  content: `
    [mysqld]
    max_connections = 200
    innodb_buffer_pool_size = 256M
  `
}

Swarm Configuration

For Docker Swarm deployments, databases support additional configuration:

Replicas

replicas

number

default:1

Number of database replicas (use with caution - most databases require special configuration for replication)

Setting replicas > 1 for databases requires proper replication setup. Don’t increase replicas without configuring database replication first.

Health Checks

healthCheckSwarm: {
  test: ["CMD-SHELL", "pg_isready -U myapp_user"],
  interval: "30s",
  timeout: "10s",
  retries: 3,
  startPeriod: "60s"
}

Placement Constraints

placementSwarm: {
  constraints: [
    "node.role==worker",
    "node.labels.database==true"
  ]
}

Monitoring & Logs

Container Logs

Access database logs through:

Real-time log streaming in the UI
Historical log viewing
Export logs for analysis

Performance Metrics

Monitor database performance:

CPU usage
Memory consumption
Disk I/O
Network traffic

Health Status

Dokploy tracks database health:

Container running status
Connection availability
Resource usage alerts

Connecting Applications

To connect your applications to databases:

Internal Network (Recommended)

Use the database’s internal hostname:

# Format: {appName}:{default-port}
DATABASE_URL=postgresql://user:pass@postgres-abc123:5432/mydb

Service Discovery

Dokploy automatically handles service discovery within the Docker network. Applications in the same environment can connect using the appName as the hostname.

Example Connection Strings

DATABASE_URL=postgresql://myapp_user:password@postgres-main:5432/myapp_production

Best Practices

Use Strong Passwords

Always use strong, unique passwords for database access. Consider using a password manager to generate and store them securely.

Regular Backups

Configure automated backups and test restoration periodically. Store backups in a different location than your database.

Resource Limits

Always set appropriate memory and CPU limits based on your database’s workload and available system resources.

Monitor Performance

Regularly check database performance metrics and logs to identify issues before they become critical.

Keep Images Updated

Regularly update database images to get security patches and performance improvements.

Separate Environments

Use different database instances for production, staging, and development environments.

Overview

Getting Started

Core Concepts

Deployments

Monitoring & Observability

Advanced Features

Configuration

CLI & Automation

Community & Support

​Supported Databases

PostgreSQL

MySQL

MariaDB

MongoDB

Redis

​Creating a Database

​Common Configuration

​PostgreSQL

​Configuration

​Example Configuration

​Connection String

​Schema Reference

​MySQL

​Configuration

​Connection String

​MariaDB

​Configuration

​Connection String

​MongoDB

​Configuration

​Connection String

​Authentication Database

​Redis

​Configuration

​Connection String

​Resource Management

​Persistence & Mounts

​Volume Mounts

​Common Mount Paths

​Backups

​Configuring Backups

​Backup Destinations

​Example Backup Configuration

​Manual Backups

​External Access

​Environment Variables

​Advanced Configuration

​Custom Commands

​Configuration Files

​Swarm Configuration

​Replicas

​Health Checks

​Placement Constraints

​Monitoring & Logs

​Container Logs

​Performance Metrics

​Health Status

​Connecting Applications

​Internal Network (Recommended)

​Service Discovery

​Example Connection Strings

​Best Practices

​Next Steps

Applications

Backups

Build docs developers (and LLMs) love

Supported Databases

Creating a Database

Common Configuration

PostgreSQL

Configuration

Example Configuration

Connection String

Schema Reference

MySQL

Configuration

Connection String

MariaDB

Configuration

Connection String

MongoDB

Configuration

Connection String

Authentication Database

Redis

Configuration

Connection String

Resource Management

Persistence & Mounts

Volume Mounts

Common Mount Paths

Backups

Configuring Backups

Backup Destinations

Example Backup Configuration

Manual Backups

External Access

Environment Variables

Advanced Configuration

Custom Commands

Configuration Files

Swarm Configuration

Replicas

Health Checks

Placement Constraints

Monitoring & Logs

Container Logs

Performance Metrics

Health Status

Connecting Applications

Internal Network (Recommended)

Service Discovery

Example Connection Strings

Best Practices

Next Steps