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

> Easily set up PostgreSQL or MySQL as your OpenMetadata development database using simple Docker Compose commands. Get your environment ready in minutes with this quick guide.

- Repository: [OpenMetadata/OpenMetadata](https://github.com/open-metadata/OpenMetadata)
- Tags: how-to-guide
- Published: 2026-04-23

---

**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`](https://github.com/open-metadata/OpenMetadata/blob/main/run_local_docker.sh) helper script in [`/docker/run_local_docker.sh`](https://github.com/open-metadata/OpenMetadata/blob/main//docker/run_local_docker.sh) handles the selection logic through its `-d` flag:

```bash

# 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`](https://github.com/open-metadata/OpenMetadata/blob/main/docker/development/docker-compose.yml)
- **PostgreSQL**: [`docker/development/docker-compose-postgres.yml`](https://github.com/open-metadata/OpenMetadata/blob/main/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)

```bash

# 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

```bash
./docker/run_local_docker.sh -d mysql

```

Uses [`docker/development/docker-compose.yml`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/docker/development/docker-compose-postgres.yml) (lines 19-44) defines:

```yaml
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`](https://github.com/open-metadata/OpenMetadata/blob/main/docker-compose-postgres.yml)):

```yaml
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:

```bash
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:

```bash

# 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`](https://github.com/open-metadata/OpenMetadata/blob/main/docker/run_local_docker.sh), [`docker/development/docker-compose-postgres.yml`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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.