Database Configuration

Supported Databases

Documenso requires PostgreSQL 14 or later. No other databases are supported.

PostgreSQL provides the reliability, performance, and feature set required for document signing workflows, including:

• ACID compliance for transaction integrity
• JSON support for flexible metadata storage
• Full-text search capabilities
• Robust backup and replication options

Connection String Format

PostgreSQL connection strings follow this format:

postgresql://[user]:[password]@[host]:[port]/[database]?[parameters]

Components

Examples

Local development:

postgresql://documenso:password@localhost:5432/documenso

Remote server with SSL:

postgresql://documenso:password@db.example.com:5432/documenso?sslmode=require

With special characters in password:

URL-encode special characters in passwords. For example, p@ss#word becomes p%40ss%23word:

postgresql://documenso:p%40ss%23word@localhost:5432/documenso

Environment Variables

Documenso uses two database connection variables:

Basic Configuration

When not using a connection pooler, set both variables to the same value:

NEXT_PRIVATE_DATABASE_URL=postgresql://user:password@host:5432/documenso
NEXT_PRIVATE_DIRECT_DATABASE_URL=postgresql://user:password@host:5432/documenso

Automatic Detection

Documenso automatically detects common database environment variable formats used by hosting providers:

If your hosting provider sets these variables, Documenso will use them automatically.

Connection Pooling

Connection pooling improves performance by reusing database connections instead of creating new ones for each request.

When to Use Pooling

Use connection pooling when:

• Running multiple application instances
• Deploying to serverless environments
• Handling high concurrent request volumes
• Your database has connection limits

PgBouncer Configuration

When using PgBouncer or similar poolers, configure two connection strings:

1. Pooled connection for application queries
2. Direct connection for migrations (bypasses the pooler)

# Pooled connection (through PgBouncer)
NEXT_PRIVATE_DATABASE_URL=postgresql://user:password@pooler-host:6432/documenso?pgbouncer=true

# Direct connection (bypasses PgBouncer)
NEXT_PRIVATE_DIRECT_DATABASE_URL=postgresql://user:password@db-host:5432/documenso

Prisma Connection Pool

Documenso uses Prisma, which maintains its own connection pool. Configure pool size with connection string parameters:

postgresql://user:password@host:5432/documenso?connection_limit=10&pool_timeout=30

SSL/TLS Connections

Enabling SSL

Add SSL parameters to your connection string:

postgresql://user:password@host:5432/documenso?sslmode=require

SSL Modes

For production, use require at minimum. Use verify-full when your CA certificate is available.

Custom Certificates

When connecting to databases with self-signed or private CA certificates:

postgresql://user:password@host:5432/documenso?sslmode=verify-full&sslrootcert=/path/to/ca.crt

For Docker deployments, mount the certificate file:

docker run -d \
  -v /path/to/ca.crt:/etc/ssl/certs/db-ca.crt:ro \
  -e NEXT_PRIVATE_DATABASE_URL="postgresql://user:password@host:5432/documenso?sslmode=verify-full&sslrootcert=/etc/ssl/certs/db-ca.crt" \
  documenso/documenso:latest

Running Migrations

Database migrations update your schema when upgrading Documenso.

Automatic Migrations

When running Documenso via Docker, migrations run automatically on container startup. No manual intervention is required.

Manual Migrations

For manual deployments or troubleshooting:

# Apply pending migrations
npm run prisma:migrate-deploy

# Or using npx directly
npx prisma migrate deploy

Migration Commands

Troubleshooting Migrations

Managed Database Services

Backup Recommendations

Backup Strategies

PostgreSQL Backup Commands

Create a logical backup:

pg_dump -h host -U user -d documenso -F c -f documenso_backup.dump

Restore from backup:

pg_restore -h host -U user -d documenso -c documenso_backup.dump

Managed Service Backups

Most managed database services provide automated backups:

Performance Tuning

PostgreSQL Configuration

Key parameters for Documenso workloads:

Connection Limits

Calculate your connection limit:

max_connections = (application_instances × connection_pool_size) + admin_overhead

Example: 3 app instances with pool size 10 = (3 × 10) + 10 = 40 connections minimum.

Indexing

Documenso includes necessary indexes by default. Additional indexes may help for:

• Custom reporting queries
• High-volume document searches
• Audit log analysis

Check for slow queries:

SELECT query, calls, mean_time, total_time
FROM pg_stat_statements
ORDER BY total_time DESC
LIMIT 10;

Monitoring

Monitor these metrics:

Troubleshooting

See Also

• Environment Variables - Complete configuration reference
• Storage Configuration - Set up document storage
• Backups - Backup strategies and procedures
• Upgrades - Upgrade procedures and migration handling