Skip to main content

Direct connections

Overview​

Prisma Postgres is the perfect choice for your applications, whether you connect to it via Prisma ORM or any other ORM, database library / tool of your choice. If you use it with Prisma ORM, Prisma Postgres comes with built-in connection pooling and an integrated caching layer (powered by Prisma Accelerate).

If you connect to it via another tool, you can do so with a direct connection string following the conventional PostgreSQL format.

note

Direct TCP access previously was possible via a TCP tunnel. This method has been deprecated in favor of direct TCP connections which are covered on this page.

How to connect to Prisma Postgres via direct TCP​

In order to get a direct connection string, you need to:

  1. open a project in your account (or create a new one)
  2. navigate to a environment with an active Prisma Postgres instance
  3. click the API Keys tab in the project's sidenav
  4. click the Create API key button
  5. in the popup, provide a Name for the API key and click Create
  6. copy the connection string starting with postgres://, this is your direct connection string

Connection string​

Format​

When you connect to Prisma Postgres via direct TCP, your connection string looks as follows:

DATABASE_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require"

The USER and PASSWORD values are provided when you generate credentials for your Prisma Postgres instance in the . Here is an example with sample values:

DATABASE_URL="postgres://2f9881cc7eef46f094ac913df34c1fb441502fe66cbe28cc48998d4e6b20336b:sk_QZ3u8fMPFfBzOID4ol-mV@db.prisma.io:5432/?sslmode=require"

SSL mode​

SSL mode is required when connecting to Prisma Postgres via direct TCP, so you need to append sslmode=require to your TCP connection string.

Temporary limitations​

Closing idle connections​

Prisma Postgres closes idle connections after an extended period of time. If that happens in your application, you can re-open a new connection. (Most database clients re-connect automatically.)

Connection limit​

While direct connections are in Early Access, the following connection limits apply:

Starter (Free)ProBusiness
Connection limitMax 20Max 20Max 20

Query and transaction timeouts​

While direct connections are in Early Access, the following timeouts apply:

Starter (Free)ProBusiness
Query timeoutUp to 10 secondsUp to 10 secondsUp to 10 seconds
Interactive transactions timeoutUp to 15 secondsUp to 15 secondsUp to 15 seconds

Limited user permissions​

User permissions are limited to read, write and schema changes. It is not possible to create separate databases, manage users and roles, or perform other administrative actions.

TCP tunnel (Deprecated)​

warning

The TCP tunnel is deprecated in favor of direct TCP connections.

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 a 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. If you are running the tunnel command from your project where an .env file has DATABASE_URL already set, you can skip this step as the tunnel will automatically pick it up.

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 or DataGrip. 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, DataGrip, 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.