Connecting Laravel to PostgreSQL on Ubuntu: A Beginner's Guide

If you're building your first Laravel application and trying to connect it to PostgreSQL, you might run into an error like this:

SQLSTATE[08006] [7] connection to server at "127.0.0.1", port 5432 failed:
FATAL: password authentication failed for user "postgres"

I ran into this while setting up a fresh Laravel application on Linux.

At first, I thought the problem was with Laravel, but the error actually tells us something useful: Laravel can reach PostgreSQL, but PostgreSQL is rejecting the database credentials.

In this article, I'll walk through how to connect Laravel to PostgreSQL on Ubuntu, create a dedicated database user, configure Laravel, and troubleshoot authentication errors.

Prerequisites

Before starting, make sure you have the following installed:

• PHP
• Composer
• Laravel
• PostgreSQL

You can check your PHP installation with:

php -v

Check Composer:

composer -V

And check PostgreSQL:

psql --version

You can also check whether PostgreSQL is running:

sudo systemctl status postgresql

If PostgreSQL isn't running, start it with:

sudo systemctl start postgresql

Create a Laravel Project

If you don't already have a Laravel project, you can create one using Composer:

composer create-project laravel/laravel example-app

Then move into the project:

cd example-app

Laravel stores environment-specific configuration in the .env file.

Configure Laravel for PostgreSQL

Open your .env file:

nano .env

For PostgreSQL, your database configuration should look like this:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=laravel
DB_USERNAME=laravel_user
DB_PASSWORD=your_password

There are a few important things to notice here.

PostgreSQL uses port 5432

PostgreSQL normally runs on:

5432

MySQL commonly uses:

3306

So don't use 3306 if you're connecting Laravel to PostgreSQL.

Laravel uses pgsql

For PostgreSQL, Laravel expects:

DB_CONNECTION=pgsql

Not:

DB_CONNECTION=postgres

What Does the Authentication Error Mean?

When I first tested the connection, I used:

psql -h 127.0.0.1 -U postgres -d postgres -W

PostgreSQL returned:

FATAL: password authentication failed for user "postgres"

This can be confusing when you're new to PostgreSQL.

The important thing is that PostgreSQL is actually responding.

The problem isn't that PostgreSQL can't be found.

Instead, PostgreSQL is saying:

I found the server and the user, but the password provided for that user is incorrect.

So changing the host or port won't fix this particular error.

Create a Dedicated PostgreSQL User

Rather than using the PostgreSQL administrator account for Laravel, I decided to create a separate user specifically for the application.

This is a better approach because your application doesn't need to connect using a PostgreSQL superuser.

First, access PostgreSQL through the system postgres account:

sudo -u postgres psql

You should see something similar to:

postgres=#

You're now inside the PostgreSQL command-line interface.

Create the Laravel User

Create a new PostgreSQL user:

CREATE USER laravel_user WITH PASSWORD 'your_secure_password';

For example:

CREATE USER laravel_user WITH PASSWORD 'myStrongPassword123';

For a real application, use a strong password and don't commit it to Git.

Create the Laravel Database

Now create the database and make the new user its owner:

CREATE DATABASE laravel OWNER laravel_user;

You can check your databases with:

\l

You should see the laravel database in the list.

Grant Permissions

Connect to the Laravel database:

\c laravel

Then grant the user access to the public schema:

GRANT ALL ON SCHEMA public TO laravel_user;

You can also grant privileges on existing tables and sequences:

GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO laravel_user;

GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO laravel_user;

For future tables and sequences, you can set default privileges:

ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT ALL ON TABLES TO laravel_user;

ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT ALL ON SEQUENCES TO laravel_user;

When you're finished, exit PostgreSQL:

\q

Test the PostgreSQL Connection

Before going back to Laravel, it's a good idea to test the database connection directly.

Run:

psql -h 127.0.0.1 -U laravel_user -d laravel -W

Enter the password you created earlier.

If the credentials are correct, you should get:

laravel=>

This is an important troubleshooting step.

If the connection works here, you know PostgreSQL is correctly configured and you can focus on Laravel if another problem occurs.

Update Laravel's .env

Now configure Laravel with the new PostgreSQL user:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=laravel
DB_USERNAME=laravel_user
DB_PASSWORD=myStrongPassword123

Replace the password with the one you actually created.

Clear Laravel's Configuration Cache

Laravel may still have the old database configuration cached.

Run:

php artisan config:clear

You should see something similar to:

INFO  Configuration cache cleared successfully.

Run the Migrations

Now run:

php artisan migrate

If everything is configured correctly, Laravel should connect to PostgreSQL and create its migration tables.

You should see output similar to:

INFO  Preparing database.

Creating migration table ................................ DONE

INFO  Running migrations.

0001_01_01_000000_create_users_table .................... DONE
0001_01_01_000001_create_cache_table .................... DONE
0001_01_01_000002_create_jobs_table ..................... DONE

At this point, Laravel is successfully connected to PostgreSQL.

Understanding the Setup

The final setup looks like this:

Laravel Application
        |
        | PostgreSQL connection
        ↓
127.0.0.1:5432
        |
        ↓
PostgreSQL
        |
        ↓
laravel_user
        |
        ↓
laravel database

And your .env contains:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=laravel
DB_USERNAME=laravel_user
DB_PASSWORD=your_password

Common Mistakes

1. Using the MySQL port

Don't use:

DB_PORT=3306

for PostgreSQL.

Use:

DB_PORT=5432

2. Using the wrong connection name

Don't use:

DB_CONNECTION=postgres

Use:

DB_CONNECTION=pgsql

3. Using root as the PostgreSQL username

If you're coming from MySQL, you might be used to:

DB_USERNAME=root

PostgreSQL commonly has an administrative user called:

postgres

However, your Laravel application doesn't need to use the administrator account.

A dedicated user such as:

laravel_user

is a better choice.

4. Forgetting to clear Laravel's configuration

If you change your .env file and Laravel continues using the old configuration, run:

php artisan config:clear

Then try:

php artisan migrate

5. Not testing PostgreSQL separately

If Laravel gives you a database connection error, test PostgreSQL directly first:

psql -h 127.0.0.1 -U laravel_user -d laravel -W

If this fails, the problem is probably with PostgreSQL, the username, password, database, or permissions.

If it succeeds, then you can focus on Laravel's configuration.

Troubleshooting Checklist

Before running:

php artisan migrate

make sure:

• PostgreSQL is running
• The laravel database exists
• laravel_user exists
• The password is correct
• The user has access to the database
• PostgreSQL is running on port 5432
• DB_CONNECTION=pgsql
• Laravel's configuration cache has been cleared

Then run:

php artisan config:clear
php artisan migrate

Final Thoughts

Connecting Laravel to PostgreSQL for the first time can be confusing because there are several different pieces involved: Laravel, PHP, PostgreSQL, users, passwords, databases, ports, permissions, and environment variables.

The biggest lesson I learned from this setup is that understanding the error is better than randomly changing configuration until something works.

For example, when you see:

FATAL: password authentication failed for user "postgres"

you already know that PostgreSQL is reachable. The problem is authentication.

From there, you can test PostgreSQL independently, create a dedicated application user, verify the credentials, and then connect Laravel.

Hopefully this guide helps another beginner who is setting up Laravel and PostgreSQL on Ubuntu for the first time.