Skip to main content

Upgrade from Early Access

This guide shows you how to migrate your Prisma Postgres Early Access (EA) database to the now official Prisma Postgres General Availability (GA) database. Prisma Postgres Early Access was introduced to allow early adopters to test Prisma’s new managed PostgreSQL service. As we move to GA, it's crucial to safely migrate data from your EA database to the new GA database.

Prisma will not automatically migrate your data to ensure its integrity. Instead, this process must be done manually. You can accomplish this in three main steps:

  1. Back up your EA database via pg_dump.
  2. Create a new GA database.
  3. Import your backup into the GA database via pg_restore.

We will be using the @prisma/ppg-tunnel package to securely connect to both databases. This tool sets up a secure proxy tunnel, eliminating the need for manual credential handling.

You can learn more about Prisma Postgres on this page.

Prerequisites​

Before you begin, make sure you have:

  • Node.js installed (version 16 or higher).
  • PostgreSQL CLI Tools (pg_dump, pg_restore) for creating and restoring backups.
  • A Database connection string for your Prisma Postgres database.

1. Back up the EA database​

1.1. Installing PostgreSQL utilities​

To create and restore backups, ensure you have the PostgreSQL command-line tools installed. Run the following commands based on your operating system:

brew install postgresql@16
which pg_dump
which pg_restore
tip

If you installed PostgreSQL but still see a “command not found” error for pg_dump or pg_restore, ensure your installation directory is in your system’s PATH environment variable.

1.2. Connecting to the EA database directly with @prisma/ppg-tunnel​

In your terminal, run npx @prisma/ppg-tunnel to establish a secure tunnel to your Early Access database.

Set environment variable (with your actual EA database URL):

export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."

Run the tunnel:

npx @prisma/ppg-tunnel --host 127.0.0.1  --port 5432

You should see output similar to:

Prisma Postgres auth proxy listening on 127.0.0.1:5432 🚀

Your connection is authenticated using your Prisma Postgres API key.
...

==============================
hostname:  127.0.0.1
port:      5432
username:  <anything>
password:  <none>
==============================
note

Please note that the port you will see in your output will be a randomly assigned port which may be different from the one mentioned here. Also, Keep this terminal window open so the tunnel remains active! If you close it, the tunnel disconnects.

  1. Copy the port number from the terminal output, you’ll need it in the next step for the pg_dump command.

1.3. Creating the Backup with pg_dump​

With the tunnel running, you can now dump the EA database by running the following command:

PGSSLMODE=disable \
pg_dump \
  -h 127.0.0.1 \
  -p 5432 \
  -Fc \
  -v \
  -d postgres \
  -f ./mydatabase.bak \
&& echo "-complete-"

PGSSLMODE=disable indicates SSL is not required locally because the tunnel already encrypts the connection.

`-h` is the host (127.0.0.1)
`-p` is the port, which should match the one from the tunnel output.
`-Fc` uses the custom format for backups, recommended for pg_restore.
`-d` postgres is the default database name used in Prisma Postgres.
`-f` ./mydatabase.bak specifies the backup file name and location.
`-v` runs pg_dump in verbose mode.

This should create your backup file named mydatabase.bak in the current directory. We will use this backup file for importing in next steps.

2. Create a new GA database​

Next, create your GA (General Availability) database:

  1. Visit and sign in (or create an account).
  2. Create a Prisma Postgres database in the region of your choice.
  3. Copy the Database URL for later use.

Prisma Postgres GA uses PostgreSQL 17, so you’ll be restoring your EA backup into this new environment.

3. Import the backup into the GA database​

3.1. Connecting to the GA Database with @prisma/ppg-tunnel​

Open a new terminal (or stop the previous tunnel) and connect to your GA database:

Set environment variables for the new GA database:

export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."

Run the tunnel:

npx @prisma/ppg-tunnel --host 127.0.0.1 --port 5432

You should see output similar to:

Prisma Postgres auth proxy listening on 127.0.0.1:52604 🚀

Your connection is authenticated using your Prisma Postgres API key.
...

==============================
hostname:  127.0.0.1
port:      52604
username:  <anything>
password:  <none>
==============================
note

Again, keep this tunnel process running to maintain the connection!

3.2. Restoring the Backup with pg_restore​

Use the backup file from Step 1 to restore data into your GA database with pg_restore by running this command:

PGSSLMODE=disable \
pg_restore \
  -h 127.0.0.1 \
  -p 5432 \
  -v \
  -d postgres \
  ./mydatabase.bak \
&& echo "-complete-"

Also, in this case the database name is postgres. You can replace it with your desired database name. It does not matter what you name your database as you will be able to use Prisma Postgres as usual. The backup file name (mydatabase.bak in our example) should match the one you created in Step 1.

This command restores the backup into the GA database. If successful, you should see -complete- in the terminal.

Next steps​

Connect with your favorite Database IDE or Prisma Client to confirm all tables, rows, and schemas match your old EA environment.

Congratulations! You have successfully migrated your Prisma Postgres Early Access database to Prisma Postgres GA. If you encounter any issues, please reach out to our support team.