How to Set Up a Development Database for OpenMetadata: PostgreSQL and MySQL Guide

OpenMetadata provides ready-to-use Docker Compose configurations that automatically provision either PostgreSQL or MySQL as your development database with a single command.

Setting up a reliable development database is essential when contributing to OpenMetadata. The open-source repository includes automated scripts and containerized configurations that eliminate manual database installation and configuration. This guide walks through the exact process used by the OpenMetadata maintainers to spin up development environments, referencing the actual source files and helper scripts from the open-metadata/OpenMetadata repository.

Choose Your Database Type: PostgreSQL or MySQL

OpenMetadata supports two primary database backends for development. The run_local_docker.sh helper script in /docker/run_local_docker.sh handles the selection logic through its -d flag:

# Lines 13-18 from run_local_docker.sh

while getopts "d:" opt; do
  case $opt in
    d) db_type="$OPTARG";;
    *) echo "Usage: $0 [-d mysql|postgresql]" >&2; exit 1;;
  esac
done

The script maps your choice to the appropriate Compose file:

• MySQL: docker/development/docker-compose.yml
• PostgreSQL: docker/development/docker-compose-postgres.yml

Start the Full Development Stack

The fastest way to set up a development database for OpenMetadata is running the helper script with your database preference.

PostgreSQL (Recommended Default)

# From repository root

./docker/run_local_docker.sh -d postgresql

This command executes docker compose -f docker/development/docker-compose-postgres.yml up -d, which provisions:

Service	Purpose
postgresql	Development database with health checks
opensearch	Search and indexing backend
execute-migrate-all	One-time migration runner
openmetadata-server	Main application server

MySQL Alternative

./docker/run_local_docker.sh -d mysql

Uses docker/development/docker-compose.yml with equivalent MySQL service definitions.

Understanding the Database Container Configuration

The PostgreSQL development database configuration in docker/development/docker-compose-postgres.yml (lines 19-44) defines:

postgresql:
  build:
    context: ../../
    dockerfile: docker/postgresql/Dockerfile_postgres
  hostname: postgresql
  environment:
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: password
  healthcheck:
    test: ["CMD", "psql", "-U", "postgres", "-c", "SELECT 1"]
    interval: 15s
    timeout: 10s
    retries: 10

Key implementation details:

• Custom Dockerfile: docker/postgresql/Dockerfile_postgres extends the official Postgres image with OpenMetadata-specific configuration
• Default credentials: postgres / password (change for production deployments)
• Health verification: Container reports healthy only when psql connections succeed

Database Connection and Migration Process

OpenMetadata automatically handles schema creation through the execute-migrate-all service (lines 70-78 in docker-compose-postgres.yml):

execute-migrate-all:
  image: openmetadata/server:1.2.0
  command: ./bootstrap/openmetadata-ops.sh migrate
  environment:
    DB_USER: openmetadata_user
    DB_PASSWORD: openmetadata_password
    DB_HOST: postgresql
    DB_PORT: 5432
  depends_on:
    postgresql:
      condition: service_healthy

Critical behavior:

• Conditional startup: Migration runs only after postgresql healthcheck passes
• Environment variables: The same DB_* variables are injected into the openmetadata-server service (lines 77-86), ensuring consistent connectivity

Run Database Only for IDE Development

Many contributors prefer launching the OpenMetadata server directly from IntelliJ while keeping the database containerized. Start only the PostgreSQL service:

docker compose -f docker/development/docker-compose-postgres.yml up -d postgresql

Then launch OpenMetadataApplication from your IDE. The environment variables exported by the Compose file (DB_USER, DB_HOST, DB_PORT, etc.) are automatically available when running through Docker Desktop's environment integration.

Verify Your Development Database

Confirm the database is operational:

# Check container status

docker ps --filter "name=postgresql"

# Test database connection

docker exec -it openmetadata_postgresql psql -U postgres -c "SELECT version();"

# List OpenMetadata databases

docker exec -it openmetadata_postgresql psql -U postgres -l

Troubleshooting Common Issues

Symptom	Cause	Solution
postgresql container exits immediately	Port 5432 already bound	Stop local PostgreSQL: sudo systemctl stop postgresql
Migration fails with connection refused	Database not yet healthy	Wait 30 seconds; container healthcheck runs every 15s
run_local_docker.sh: command not found	Script not executable	Run: chmod +x docker/run_local_docker.sh

Summary

• Use run_local_docker.sh -d postgresql (or mysql) for the fastest development database setup
• Database containers include automatic health checks and environment variable exports for seamless server connectivity
• Schema migrations run automatically via execute-migrate-all once the database reports healthy
• IDE development works by starting only the database container with docker compose up -d postgresql
• Key files: docker/run_local_docker.sh, docker/development/docker-compose-postgres.yml, docker/postgresql/Dockerfile_postgres

Frequently Asked Questions

What database versions does OpenMetadata support for development?

OpenMetadata development configurations use PostgreSQL 14+ or MySQL 8.0+. The Dockerfile_postgres in docker/postgresql/ extends the official Postgres image, while the MySQL Compose file references mysql:8.0 directly. Both receive regular testing in CI pipelines.

Can I use an existing local database instead of Docker?

Yes, though it requires manual configuration. Set the DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, and DB_DATABASE environment variables to point to your existing PostgreSQL or MySQL instance, then run migrations with ./bootstrap/openmetadata-ops.sh migrate. The Docker approach remains recommended for consistency across contributor environments.

How do I reset the development database to a clean state?

Run docker compose -f docker/development/docker-compose-postgres.yml down -v to stop containers and remove the named volume containing database data. Then restart with run_local_docker.sh -d postgresql to recreate a fresh database with migrations applied automatically. The -v flag is critical—without it, Docker preserves the volume and your data persists.

Why does the migration service fail to start?

The execute-migrate-all service has a strict dependency: condition: service_healthy on the postgresql service. If the database container fails its healthcheck (configured in docker-compose-postgres.yml lines 39-44), the migration never runs. Check docker logs openmetadata_postgresql for startup errors—common causes include port conflicts, insufficient disk space, or corrupted volume data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}