Troubleshooting PostgreSQL Database Initialization in Self-Hosted Stack

When self-hosting Formance components using Docker Compose, you may encounter issues with database initialization, particularly regarding missing ledger roles or databases. Here's how to resolve these common setup issues.

Common Symptoms

• Errors about missing "ledger" role in PostgreSQL logs

• Errors about missing "ledger" database

• Database schema migrations not running

Resolution

The most common cause of these issues is incorrect file paths in your Docker Compose configuration. Ensure that:

1. The PostgreSQL initialization scripts path is correctly specified relative to your Docker Compose context

2. If your docker-compose.yml file is in the root directory, update the postgres service volume path to:

services:
  postgres:
    volumes:
      - ./.include/postgres:/docker-entrypoint-initdb.d/

For Ledger Version 2.2+

After ensuring correct database initialization, you should also set the AUTO_UPGRADE environment variable in your docker-compose.yml for the ledger service to handle schema migrations automatically:

services:
  ledger:
    environment:
      - AUTO_UPGRADE=true