How to deploy Laravel app with a PostgreSQL using Laravel Forge?

So recently I needed to improve the performance of my production Laravel app. The app was already deployed using Laravel Forge, but it was using a Neon database, which was causing significant performance issues.

After weighing our options, my team and I decided to switch to Laravel Forge's managed database feature, which would install the database on the same server as the app, eliminating latency problems and drastically improving performance.

However the Laravel Forge UI left me scratching my head, as I couldn't seem to locate the PostgreSQL database option when creating a new server. This frustrating experience inspired me to write this article, with the aim of saving other developers valuable time and headaches when deploying a Laravel app with a PostgreSQL database using Laravel Forge.

In this step-by-step guide, I'll walk you through the process of setting up your Laravel app with a managed PostgreSQL database, ensuring that you can take full advantage of the performance benefits without the confusion I initially faced.

Setup New Server

First, go to your Laravel Forge dashboard page and click the "Create Server" button. Ensure that you select the App type as "App Server" so that Forge includes the database when setting up the server.

Next click button "Advanced Settings".

By default, Laravel Forge sets up new app servers with MySQL as the database. To use PostgreSQL instead, you need to manually change the database selection option.

In this case I choose the latest version which is PostgreSQL 16.

Create database

After the server creation is complete, it's better for us to manually create a new database with custom credentials. This way, we can use those credentials in our .env configuration file.

On your Laravel Forge dashboard, click on your server, and then navigate to the "Database" section on the left sidebar.

Now you can hit button create and you good to go.

Import Database

The final step in migrating from the Neon database to the Laravel Forge-managed PostgreSQL database is to import the data from Neon to Forge.

1. Navigate to the project directory:

   cd /home/forge/<your-app-name>/current
   

2. Install the Laravel Backup package:

   COMPOSER_ALLOW_SUPERUSER=1 composer require spatie/laravel-backup
   

3. Create a backup of the Neon database:

   DATABASE_URL="your neon db connection string" php artisan backup:run --only-db
   

4. Locate the backup file:

   FILE=$(ls storage/app/<your-app-name>/)
   

   You can get the your-app-name from your .env config for APP_NAME.

5. Unzip the backup file:

   unzip $(pwd)/storage/app/<your-app-name>/$FILE 
   

6. Import the data into the Forge PostgreSQL database:

   PGPASSWORD='secret' psql -U forge -d forge -f db-dumps/postgresql-forge.sql
   

The full script would be like this.

cd /home/forge/<your-app-name>/current
COMPOSER_ALLOW_SUPERUSER=1 composer require spatie/laravel-backup
DATABASE_URL="your neon db connection string" php artisan backup:run --only-db
FILE=$(ls storage/app/<your-app-name>/)
unzip $(pwd)/storage/app/<your-app-name>/$FILE 
PGPASSWORD='secret' psql -U forge -d forge -f db-dumps/postgresql-forge.sql