Skip to main content

Metabase Database Connection Setup

This document describes how to connect Metabase to the postgres_dev database in the flowpos-workspace.

Overview​

Metabase is configured in docker-compose.yml and runs on the same Docker network as the postgres_dev service, ensuring seamless database connectivity.

Access Metabase at: http://localhost:3002

Connection Details​

For Metabase (Running in Docker)​

When configuring the database connection in Metabase UI, use these settings:

  • Host: postgres_dev (Docker service name)
  • Port: 5432 (Container's internal port)
  • Database name: flowpos_dev
  • Username: flowpos
  • Password: flowpos
  • SSL: Disabled (for local development)

For Direct psql Connection (From Host Machine)​

When connecting directly from your host machine using psql:

  • Host: localhost or 127.0.0.1
  • Port: 5435 (Host-mapped port)
  • Database: flowpos_dev
  • Username: flowpos
  • Password: flowpos

Example:

psql -h localhost -p 5435 -U flowpos -d flowpos_dev

Docker Network Setup​

Current Setup (docker-compose.yml)​

Metabase is now configured in docker-compose.yml, which automatically places it on the same network as postgres_dev. No manual network configuration is needed.

Legacy Setup (Standalone Container)​

If you're running Metabase as a standalone container (not via docker-compose), you'll need to connect it to the docker-compose network:

Problem: Standalone containers default to the bridge network, while postgres_dev runs on flowpos-workspace_default. Containers on different networks cannot communicate using service names.

Solution:

docker network connect flowpos-workspace_default metabase

Verify Connection:

# Test ping
docker exec metabase ping -c 2 postgres_dev

# Test port connectivity
docker exec metabase sh -c "nc -zv postgres_dev 5432"

Persistent Setup​

Important: If you restart the Metabase container, it will lose the network connection. You'll need to reconnect it:

docker network connect flowpos-workspace_default metabase

Metabase in docker-compose.yml​

Metabase has been added to docker-compose.yml for persistent network connectivity. The service is configured as follows:

metabase:
  image: metabase/metabase:latest
  ports:
    - "127.0.0.1:3002:3000" # Accessible at http://localhost:3002
  volumes:
    - metabase_data:/metabase-data
  environment:
    - MB_DB_TYPE=h2
    - MB_DB_FILE=/metabase-data/metabase.db

Key points:

  • Port: 3002 (to avoid conflict with web_app on port 3000)
  • Access URL: http://localhost:3002
  • Data persistence: Metabase data is stored in the metabase_data volume
  • Network: Automatically on the same network as postgres_dev
  • Metadata Database: Uses H2 (embedded database) for Metabase's own metadata, so no startup dependency on postgres_dev is needed
  • Application Database: Connection to postgres_dev is configured at runtime through Metabase UI, not at startup

Starting Metabase:

# Start Metabase with postgres_dev
docker compose up -d metabase postgres_dev

# Or start all services
docker compose up -d

Note: If you were previously running Metabase as a standalone container on port 3000, you'll need to stop it first:

docker stop metabase
docker rm metabase

Troubleshooting​

Connection Error: "Hmm, we couldn't connect to the database"​

Symptoms:

  • Error message: "check your host settings" and "check your port settings"
  • Connection fails even with correct credentials

Causes:

  1. Metabase is not on the same Docker network as postgres_dev
  2. Using localhost or 127.0.0.1 instead of postgres_dev as the host
  3. Using port 5435 instead of 5432 (host port vs container port)

Solutions:

  1. Connect Metabase to the docker-compose network:

    docker network connect flowpos-workspace_default metabase

  2. Verify network connection:

    docker network inspect flowpos-workspace_default | grep -A 5 metabase

  3. Ensure you're using:

    • Host: postgres_dev (not localhost)
    • Port: 5432 (not 5435)

Check Container Status​

Verify both containers are running:

docker ps | grep -E "(metabase|postgres_dev)"

Check Network Membership​

Verify Metabase is on the correct network:

docker inspect metabase --format '{{range $key, $value := .NetworkSettings.Networks}}{{$key}} {{end}}'

You should see flowpos-workspace_default in the output.

Connection String Format​

JDBC Connection String (for reference)​

jdbc:postgresql://postgres_dev:5432/flowpos_dev

PostgreSQL Connection String​

postgresql://flowpos:flowpos@postgres_dev:5432/flowpos_dev

Additional Resources​

Summary​

Key Points:

  • Metabase Access: http://localhost:3002 (configured in docker-compose.yml)
  • Database Host: Use postgres_dev (Docker service name), not localhost
  • Database Port: Use 5432 (container port), not 5435 (host port)
  • Network: Metabase is automatically on the same network as postgres_dev via docker-compose
  • Start Metabase: pnpm metabase or docker compose up -d metabase postgres_dev