Database containers for local development in Docker - Commands & Configuration

Introduction

Running a database inside a container on your computer helps you test and develop apps without installing the database directly. It keeps your main system clean and lets you start or stop the database easily.

When you want to try out a new database version without changing your main system

When you need a database for your app but don't want to install it permanently

When you want to share the same database setup with your team easily

When you want to reset the database quickly by restarting the container

When you want to run multiple databases on one machine without conflicts

Config File - docker-compose.yml

docker-compose.yml

version: '3.8'
services:
  postgres-db:
    image: postgres:15
    restart: always
    environment:
      POSTGRES_USER: user123
      POSTGRES_PASSWORD: pass123
      POSTGRES_DB: myappdb
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

This file tells Docker to run a PostgreSQL database container.

services: defines the database container named postgres-db.

image: uses the official PostgreSQL version 15 image.

environment: sets the username, password, and database name inside the container.

ports: maps the container's port 5432 to your computer's port 5432 so apps can connect.

volumes: keeps database data safe even if the container stops or restarts.

Commands

This command starts the PostgreSQL database container in the background so it runs without blocking your terminal.

Terminal

docker-compose up -d

Expected Output

Creating network "default" with the default driver

Creating volume "pgdata" with default driver

Creating postgres-db ... done

→

-d - Run containers in detached mode (in the background)

This command lists running containers so you can check if the database container is up and running.

Terminal

docker ps

Expected Output

CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                    NAMES

abcdef123456   postgres:15    "docker-entrypoint.s…"   10 seconds ago   Up 9 seconds    0.0.0.0:5432->5432/tcp   postgres-db

This command shows the logs of the database container to verify it started correctly without errors.

Terminal

docker logs postgres-db

Expected Output

PostgreSQL Database directory appears to contain a database; skipping initialization

2024-06-01 12:00:00.000 UTC [1] LOG:  starting PostgreSQL 15 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 12.2.0, 64-bit

2024-06-01 12:00:00.001 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432

2024-06-01 12:00:00.002 UTC [1] LOG:  listening on IPv6 address "::", port 5432

2024-06-01 12:00:00.003 UTC [1] LOG:  database system is ready to accept connections

This command stops and removes the database container and network when you no longer need the database running.

Terminal

docker-compose down

Expected Output

Stopping postgres-db ... done

Removing postgres-db ... done

Removing network default

Key Concept

If you remember nothing else from this pattern, remember: running a database in a container lets you develop and test safely without installing the database on your main system.

Common Mistakes

Not mapping the container port to the host port

Your app cannot connect to the database because the port is not accessible outside the container.

Always use the ports section in docker-compose.yml to map container port 5432 to host port 5432.

Not setting environment variables for user, password, and database

The database will use default credentials or fail to start properly, causing connection errors.

Set POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB in the environment section.

Not using a volume for database data

Data will be lost when the container stops or is removed.

Use a named volume to persist database data across container restarts.

Summary

Use docker-compose.yml to define a PostgreSQL database container with user, password, and database name.

Start the database container in the background with 'docker-compose up -d'.

Check the container status with 'docker ps' and logs with 'docker logs postgres-db'.

Stop and remove the container with 'docker-compose down' when done.