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.

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.

note

Please make sure that you are installing Postgresql version 16. Other versions may cause errors during the backup and restore process.

Option A: Interactive approach​

This approach is recommended if you prefer a guided, one-command solution. In this mode, the @prisma/ppg-tunnel CLI:

  1. Prompts you for your Early Access (EA) database API key (or DATABASE_URL).
  2. Uses pg_dump behind the scenes to back up your EA database to a file in the current directory.
  3. Prompts you for your new GA database URL or API Key.
  4. Uses pg_restore to import the backup file into your GA database.

Interactive mode does not accept any CLI arguments or read API keys from the environment. You must provide them interactively.

Steps​

  1. Open a terminal and run:
npx @prisma/ppg-tunnel migrate-from-ea

  1. When prompted, paste your Early Access database key or connection string. The CLI will create a .bak file in the current directory.

  2. When prompted again, paste your GA database key or connection string. The CLI will automatically restore the .bak file into the new GA database.

  3. Once complete, connect with your favorite Database IDE to verify your data in the GA database.

Option B: Manual backup-and-restore approach​

If you prefer or need finer control over the migration process (or to pass environment variables directly), follow these manual steps. The migration involves three main parts:

  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 still be using the @prisma/ppg-tunnel package to securely connect to both databases.

1. Back up the EA database​

1.1. 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.

If you already have a .env file in your current directory with DATABASE_URL set, the tunnel CLI will automatically pick it up—no need to manually export it. However, if you haven't set up a .env file, you'll need to set the DATABASE_URL environment variable explicitly.

To set environment variable (with your actual EA database URL):

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

If you explicitly set DATABASE_URL in your terminal, that value will take precedence over the one in your .env file.

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.

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

1.2. 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.