The DATABASE_URL environment variable is a standardized way to specify database connection details in Password Pusher. It follows the RFC 3986 URI standard and is commonly used across various deployment environments and hosting platforms.

Overview

Password Pusher supports two database backends:

  1. SQLite3 (default) - File-based database with persistent storage via Docker volumes, perfect for single-server deployments
  2. PostgreSQL - Robust relational database for distributed or high-availability setups

The DATABASE_URL contains a URL string with all information needed to connect to your database, including the database type, host, port, database name, and authentication credentials.

Important: Remember to replace the placeholders in these examples (e.g., username, password, hostname, port, database_name) with your actual credentials and database information.

Note: Additional connection options can be provided by adding query parameters to the URL: ?option1=value1&option2=value2

SQLite3

SQLite3 is the default database backend. If DATABASE_URL is not specified, Password Pusher will automatically use SQLite3. When using the provided docker-compose.yml, the database is stored in a persistent volume and will persist across container restarts.

Format

For SQLite3, the DATABASE_URL format is:

sqlite3:///path/to/database/file.sqlite3

or the shorter format:

sqlite3:path/to/database/file.sqlite3
  • sqlite3:// or sqlite3: is the protocol
  • The path can be absolute or relative to the application root
  • Use three slashes (///) for absolute paths or two slashes (//) for relative paths

Examples

Absolute path (recommended for Docker):

sqlite3:///opt/PasswordPusher/db/production.sqlite3

Relative path:

sqlite3:db/db.sqlite3

Default (when DATABASE_URL is not set):

The application defaults to sqlite3:db/db.sqlite3 if DATABASE_URL is not specified.

Persistence

SQLite3 databases are stored in persistent volumes by default when using the provided docker-compose.yml file. The database will persist across container restarts and updates.

Using Docker volumes (default in docker-compose.yml):

volumes:
  - pwpush-db:/opt/PasswordPusher/db

volumes:
  pwpush-db:

Using bind mounts:

If you prefer to use a host directory instead of a Docker-managed volume:

volumes:
  - /host/path/to/db:/opt/PasswordPusher/db

Note: If you’re running Password Pusher without Docker volumes (e.g., using docker run without volume mounts), the database will be stored in the container’s filesystem and will be lost when the container is removed. Always use volumes for production deployments.

When to Use SQLite3

SQLite3 is ideal for:

  • Single-server deployments
  • Development and testing environments
  • Small to medium-sized installations
  • Scenarios where simplicity is preferred over scalability

For production deployments requiring high availability, multiple servers, or advanced features, consider PostgreSQL instead.

PostgreSQL

PostgreSQL is a robust, production-ready database backend suitable for distributed deployments, high-availability setups, and environments requiring advanced database features.

Format

For PostgreSQL, the DATABASE_URL follows this format:

postgres://username:password@hostname:port/database_name

Components:

  • postgres:// - The protocol identifier
  • username:password - Your PostgreSQL authentication credentials
  • hostname - The host where your PostgreSQL server is running (can be a hostname, IP address, or Docker service name)
  • port - The port number (default is 5432)
  • database_name - The name of your PostgreSQL database

Examples

Local PostgreSQL server:

postgres://myuser:mypassword@localhost:5432/pwpush_db

Remote PostgreSQL server:

postgres://myuser:mypassword@db.example.com:5432/pwpush_db

Docker Compose (using service name):

postgres://pwpush_user:pwpush_passwd@postgres:5432/pwpush_db

With SSL connection:

postgres://myuser:mypassword@db.example.com:5432/pwpush_db?sslmode=require

Important Notes

Hostname Restrictions: Hostname values with underscores (_) are not supported due to RFC 3986 URI standards. Use hyphens (-) instead. See issue #1602 for details.

Special Characters in Passwords: If your password contains special characters that conflict with URI encoding (such as %, ^, #, :, etc.), you may need to URL-encode them. See the Valid Characters section below.

When to Use PostgreSQL

PostgreSQL is recommended for:

  • Production deployments requiring high availability
  • Multi-server or distributed setups
  • Environments with high traffic or large datasets
  • Scenarios requiring database replication or backups
  • When using the separate worker container (pglombardo/pwpush-worker)

Configuration Examples

Docker Compose

Using SQLite3 with persistent volume:

services:
  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    environment:
      # SQLite3 is the default, but you can explicitly set it:
      # DATABASE_URL: sqlite3:///opt/PasswordPusher/db/production.sqlite3
    volumes:
      - pwpush-db:/opt/PasswordPusher/db

volumes:
  pwpush-db:

Using PostgreSQL:

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: pwpush_user
      POSTGRES_PASSWORD: pwpush_passwd
      POSTGRES_DB: pwpush_db
    volumes:
      - postgres-data:/var/lib/postgresql/data

  pwpush:
    image: docker.io/pglombardo/pwpush:stable
    depends_on:
      - postgres
    environment:
      DATABASE_URL: postgres://pwpush_user:pwpush_passwd@postgres:5432/pwpush_db

volumes:
  postgres-data:

Environment Variables

Set DATABASE_URL as an environment variable:

export DATABASE_URL="postgres://myuser:mypassword@localhost:5432/pwpush_db"

Or in a .env file:

DATABASE_URL=postgres://myuser:mypassword@localhost:5432/pwpush_db

Valid Characters and URL Encoding

The DATABASE_URL follows the RFC 3986 URI standard, which restricts certain characters that can be used in URI components.

Restricted Characters

The following characters are not allowed in usernames, passwords, hostnames, or database names without URL encoding:

% ^ # _ :

Common Issues and Solutions

Underscores in hostnames: Hostnames with underscores (_) are not supported. Use hyphens (-) instead.

Example:

  • ❌ db_server.example.com (not supported)
  • ✅ db-server.example.com (supported)

Special characters in passwords: If your password contains special characters like %, ^, #, :, you need to URL-encode them:

Character URL-Encoded
% %25
^ %5E
# %23
: %3A

Example:

  • Original password: my#pass:word
  • URL-encoded: my%23pass%3Aword
  • Full DATABASE_URL: postgres://user:my%23pass%3Aword@localhost:5432/db

Tip: Use this regex tool to test your DATABASE_URL string for RFC 3986 compliance.

Note: This is an internet standard (RFC 3986), not a limitation introduced by Password Pusher. Most modern applications and deployment platforms follow this standard.

Troubleshooting

Common Issues

Database connection fails:

  • Verify the database server is running and accessible
  • Check that the hostname, port, username, password, and database name are correct
  • Ensure network connectivity between the application and database server
  • For Docker Compose, use the service name as the hostname

“Hostname with underscores not supported” error:

  • Replace underscores (_) with hyphens (-) in hostnames
  • This is a limitation of the URI standard, not Password Pusher

Password with special characters fails:

  • URL-encode special characters in your password
  • Consider using a password without special characters if possible
  • Use environment files or Docker secrets instead of command-line arguments

SQLite database not persisting:

  • Verify that volumes are properly configured in your docker-compose.yml or docker run command
  • Check volume mount permissions
  • Ensure the path exists and is writable
  • For Docker Compose, verify the volume is defined in both the service and the top-level volumes section

See Also

Updated: