How to Set Up PostgreSQL with Docker Compose for Laravel

Still using MySQL for your Laravel project?

This guide explains how to set up PostgreSQL with Docker Compose for Laravel so your database setup can run consistently across different machines.

Why PostgreSQL and Docker Work Well with Laravel

PostgreSQL is a powerful database system that works well for complex queries, JSON data, and large-scale applications. Many production Laravel applications use PostgreSQL.

Docker makes the setup easier because you don’t need to install PostgreSQL directly on your machine. It also helps avoid version conflicts and allows your team to use the same database setup.

Before starting, make sure you have Docker Desktop installed and a Laravel project ready.

Step 1: Create the Docker Compose File

In the root directory of your Laravel project, create a file called:

docker-compose.yml

This file defines the PostgreSQL container.

A basic PostgreSQL service can be configured with the following settings:

services:
  postgres:
    image: postgres:16
    container_name: laravel-postgres
    environment:
      POSTGRES_DB: your_database
      POSTGRES_USER: your_username
      POSTGRES_PASSWORD: your_password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

This configuration uses PostgreSQL 16.

The container_name gives the container a name that can be easily referenced.

The environment variables define the database name, username, and password.

Port 5432 is the standard PostgreSQL port.

The volume keeps your database data available even when the container is restarted.

Step 2: Start the Container

Open your terminal in the Laravel project root and run:

docker compose up -d

The -d flag runs the container in the background, so it doesn’t block your terminal.

Docker will download the PostgreSQL image and start the container. The first startup may take some time.

Step 3: Confirm the Container Is Running

To check whether the PostgreSQL container is running, use:

docker ps

You should see the PostgreSQL container in the list with an Up status.

If something doesn’t look right, you can check the container logs with:

docker logs laravel-postgres

Step 4: Connect Laravel to PostgreSQL

Open the .env file in your Laravel project.

Update the database configuration so it matches the values defined in docker-compose.yml.

The main change is the database connection:

DB_CONNECTION=pgsql

Then update the remaining database settings to match your PostgreSQL configuration:

DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

Save the .env file after making the changes.

Step 5: Run the Laravel Migration

Now it’s time to test the database connection.

Run the Laravel migration command:

php artisan migrate

If the migration completes without errors and the tables are created successfully, your Laravel application is connected to PostgreSQL running inside Docker.

Verify the Tables Inside PostgreSQL

You can also verify that the migration tables were created inside the PostgreSQL container.

First, open a shell inside the container:

docker exec -it laravel-postgres bash

Then connect to PostgreSQL and list the tables.

Inside the PostgreSQL terminal, use:

\dt

This will display the tables created by your Laravel migrations, including tables such as migrations, users, cache, and jobs.

Recap

The complete setup can be summarized in five steps:

1. Create a docker-compose.yml file with a PostgreSQL service.
2. Start PostgreSQL with docker compose up -d.
3. Confirm the container is running with docker ps.
4. Update your Laravel .env file to use pgsql.
5. Run php artisan migrate and verify the tables inside the PostgreSQL container.

That’s it. Your Laravel project is now connected to PostgreSQL running through Docker Compose.

This setup makes it easier to maintain a consistent database environment across machines and development teams.
watch step by step process on youtube