Skip to main content

TCP tunnel

Prisma Postgres can be accessed securely via a TCP tunnel using the @prisma/ppg-tunnel package, an authentication proxy designed for local database workflows. This package establishes a secure connection to Prisma Postgres through a local TCP server, enabling secure access while automatically handling traffic routing and authentication.

note

This is an Early Access feature of Prisma Postgres. It is not recommended for production use and is not intended for application-level access.

While in Early Access, usage of the TCP tunnel will be free of charge.

Prerequisites​

  • Node.js installed on your machine
  • A Prisma Postgres database connection string set as an environment variable called DATABASE_URL

Exporting environment variables​

The tunnel expects you to have the following DATABASE_URL environment variable set to the connection URL of your Prisma Postgres instance.

To export the DATABASE_URL environment variable temporarily in a terminal session:

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

Replace the API_KEY placeholder with the API key value of your Prisma Postgres instance.

Starting the TCP tunnel​

To start the proxy server, run the following command:

npx @prisma/ppg-tunnel
Show CLI results
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>
==============================

This will start the tunnel on a randomly assigned TCP port. The proxy automatically handles authentication, so any database credentials are accepted. The tunnel also encrypts traffic, meaning clients should be set to not require SSL.

You can now connet to your Prisma Postgres editor using your favorite PostgreSQL client, e.g. psql or a GUI like TablePlus. To do so, you only need to provide the host and port from the output above. The TCP tunnel will handle authentication via the API key in your Prisma Postgres connection URL, so you can omit the values for username and password.

Customizing host and port​

By default, the tunnel listens on 127.0.0.1 and assigns a random port. Since it provides access to your Prisma Postgres database, it should only be exposed within a trusted network. You can specify a custom host and port using the --host and --port flags:

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

Next steps​

The local tunnel enables you to access Prisma Postgres from 3rd party database editors such as Postico, TablePlus and pgAdmin. Learn more in this section.

Security considerations​

When using the TCP tunnel, keep the following in mind:

  • The tunnel does not support schema management (i.e., DDL queries outside of Prisma Migrate).
  • The tunnel should not be exposed to untrusted networks.
  • Always store API keys securely and avoid hardcoding them.
  • Ensure that only necessary users have direct access to the Prisma Postgres database.