Prisma Postgres TCP Tunnel

[!WARNING]
This package has been deprecated in favor of direct TCP connections, please use those if you want to interact with Prisma Postgres with another library/tool than Prisma ORM.

@prisma/ppg-tunnel is an authentication proxy for Prisma Postgres. It uses a Prisma Data Platform API key to connect to a secure proxy while opening a local TCP server for client connections. This enables secure connections from local tools while automatically routing traffic to and authenticating with the correct Prisma Postgres instance.

Usage

Standard mode

In this mode, the tunnel opens a connection to the database and waits for client tooling to connect.

The tunnel expects either a PDP_API_KEY or DATABASE_URL environment variable to be set. PDP_API_KEY is expected to be a Prisma Data Platform API key. DATABASE_URL is expected to be Prisma Postgres connection string. If both are set, PDP_API_KEY has precedence.

To start the proxy server, run the following command:

npx @prisma/ppg-tunnel

This will start the tunnel on a randomly assigned TCP port for client connections. The proxy handles authentication for you, so any database credentials are allowed. The tunnel will also handle encryption of traffic, so clients should be set to not require SSL.

By default, the tunnel will listen on 127.0.0.1 and a randomly assigned port. Since the tunnel provides access to your Prisma Postgres database, it should only be exposed to a trusted network. You can override the default host and port bindings with the --host and --port flags:

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

Interactive mode

This mode can help upgrade a Prisma Postgres Early Access database to a fresh Prisma Postgres General Availability database:

npx @prisma/ppg-tunnel migrate-from-ea

The tunnel will ask for a DATABASE_URL or API key, then use pg_dump to download the early-access database to a file in the current working directory. When the dump is finished, the tunnel will ask for an API key for the new Prisma Postgres database, and use pg_restore to migrate the dump file.

Interactive mode does not accept arguments or read API keys from the environment. It requires version 16 of the PostgreSQL client tools. You can read more about migrating from an early-access database in the official documentation.