# Connecting to your database (/docs/postgres/database/connecting-to-your-database)

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

Choose the right Prisma Postgres connection string for your runtime, tool, and workload.

Location: Postgres > Database > Connecting to your database

Every Prisma Postgres database has two connection strings: **pooled** for application traffic, **direct** for migrations and admin tooling. This page covers how to get them, where each one goes, and the recommended setup for common runtimes.

For pooling behavior, limits, and timeouts, see [Connection pooling](https://www.prisma.io/docs/postgres/database/connection-pooling).

## Get your connection strings [#get-your-connection-strings]

1. Open your project in the [Prisma Console](https://console.prisma.io/?utm_source=docs\&utm_medium=content\&utm_content=postgres).
2. Select your database.
3. Click **Connect to your database**.
4. Click **Generate new connection string**.
5. Copy both the **pooled** and **direct** connection strings.

![Animated walkthrough of generating a connection string in Prisma Console: navigating to the database, clicking Connect, generating a new connection string, and copying the result.](https://www.prisma.io/img/postgres/connection-string.gif)

## Connection string format [#connection-string-format]

Both strings share the same credentials. The only difference is the hostname:

```bash title=".env"
# Pooled — routes through the connection pooler
DATABASE_URL="postgres://USER:PASSWORD@pooled.db.prisma.io:5432/postgres?sslmode=require"

# Direct — connects straight to the database
DIRECT_URL="postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require"
```

| Part       | Description                                               |
| ---------- | --------------------------------------------------------- |
| `USER`     | Database user (generated in Console)                      |
| `PASSWORD` | Database password (generated in Console)                  |
| Host       | `pooled.db.prisma.io` (pooled) or `db.prisma.io` (direct) |
| Port       | `5432`                                                    |
| `sslmode`  | Always `require` - SSL is mandatory                       |

## Access and permissions [#access-and-permissions]

Clicking **Generate new connection string** creates a new password for the database, and Console shows it to you inside two connection strings, pooled and direct. This page calls that password a *credential*. Console lists credentials under **Connection strings** in the database's sidebar, and the CLI and the REST API call them *connections*.

The `USER` part is the same in every credential for a database, and you can't change it. Only the `PASSWORD` differs between credentials.

Every credential has the same full access to its database. You can't make a credential read-only or limit it to certain tables, schemas, or PostgreSQL roles.

Generating a new credential doesn't remove the old ones. Give each app or service its own credential, so you can delete one app's password without breaking the others. Console names every credential it creates `console-connection-string`, and the **Connection strings** list tells them apart by the last four characters of each password. To give a credential your own name, create it with the REST API, which takes a `name` in [`POST /v1/connections`](https://www.prisma.io/docs/rest-api/endpoints/connections/post-connections).

If you move a database from another PostgreSQL server, the roles from that server don't exist in Prisma Postgres. Restore with `pg_restore --no-owner --no-privileges` so the ownership and grant statements that name those roles are skipped, as shown in [Migrate a local Postgres database to Prisma Postgres](https://www.prisma.io/docs/postgres/import-from-existing-database).

## Which connection to use [#which-connection-to-use]

| If you are...                                                                               | Use        | Why                                                                  |
| ------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------- |
| Running application queries (API handlers, workers, functions)                              | **Pooled** | Safer under concurrency. Reuses a small set of database connections. |
| Running migrations, introspection, `pg_dump`, `pg_restore`, Prisma Studio, or admin tooling | **Direct** | These workflows need session continuity or should bypass the pooler. |
| Using `LISTEN/NOTIFY` or session-level `SET` commands                                       | **Direct** | The pooler does not preserve session state across transactions.      |
| Running queries or jobs that may exceed 10 minutes                                          | **Direct** | Pooled connections enforce a 10-minute query timeout.                |

If you swap them, the failure modes are asymmetric. Using the pooled string for migrations produces obvious errors (lock failures, prepared statement errors). Using the direct string for application traffic works at low concurrency but silently exhausts connections under production load. See [Connection pooling](https://www.prisma.io/docs/postgres/database/connection-pooling) for details.

## Recommended setups [#recommended-setups]

### Prisma ORM in Node.js [#prisma-orm-in-nodejs]

Set `DATABASE_URL` to the pooled string for runtime queries. Set `DIRECT_URL` to the direct string so the Prisma CLI (migrations, introspection, Studio) bypasses the pooler.

```bash title=".env"
DATABASE_URL="postgres://USER:PASSWORD@pooled.db.prisma.io:5432/postgres?sslmode=require"
DIRECT_URL="postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require"
```

```ts title="prisma.config.ts"
import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: {
    url: env("DIRECT_URL"),
  },
});
```

```ts title="src/db.ts"
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "./generated/prisma/client";

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });

export const prisma = new PrismaClient({ adapter });
```

This gives you pooled runtime traffic for application queries and direct CLI access for migrations, introspection, and schema changes.

### Serverless and edge runtimes [#serverless-and-edge-runtimes]

For serverless runtimes that support PostgreSQL over TCP, use the same setup as above but wrap the client in a singleton. Without this, each warm invocation creates a new client and a new connection, which can exhaust your plan's pooled connection limit.

```ts title="src/db.ts"
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "./generated/prisma/client";

const globalForPrisma = globalThis as unknown as {
  prisma?: PrismaClient;
};

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    adapter: new PrismaPg({
      connectionString: process.env.DATABASE_URL,
    }),
  });

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}
```

**When TCP is not a good fit:** If your runtime is short-lived, globally distributed, or does not support PostgreSQL TCP connections well, use the [serverless driver (`@prisma/ppg`)](https://www.prisma.io/docs/postgres/database/serverless-driver) instead. It communicates over HTTP and WebSockets rather than TCP and has built in connection pooling. See the [serverless driver docs](https://www.prisma.io/docs/postgres/database/serverless-driver) for setup.

> [!NOTE]
> The serverless driver uses the **direct** connection string but does **not** open a TCP connection to the database. The direct hostname is used for routing only, the transport is HTTP/WebSocket, not PostgreSQL wire protocol.

### PostgreSQL tools and other ORMs [#postgresql-tools-and-other-orms]

Use the **direct** connection string with `psql`, `pg_dump`, `pg_restore`, and GUI tools (TablePlus, DataGrip, DBeaver, Postico):

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

The same direct string is where `pg_restore` loads an existing database; see [Migrate a local Postgres database to Prisma Postgres](https://www.prisma.io/docs/postgres/import-from-existing-database) for the three steps.

For non-Prisma ORMs, see the getting-started guides for [Drizzle](https://www.prisma.io/docs/prisma-postgres/quickstart/drizzle-orm), [Kysely](https://www.prisma.io/docs/prisma-postgres/quickstart/kysely), or [TypeORM](https://www.prisma.io/docs/prisma-postgres/quickstart/typeorm).

## Rotate or delete a credential [#rotate-or-delete-a-credential]

If a password leaks, replace it: create a new credential, switch your app to it, and then delete the old one. Rotating isn't enough, because after a rotate the old password can keep working.

### Replace a leaked password [#replace-a-leaked-password]

1. Create a new credential, as described in [Get your connection strings](#get-your-connection-strings).
2. Put its pooled and direct connection strings in your app's environment variables and redeploy.
3. Delete the old credential.
4. Try the old connection string once. The attempt should fail:

   ```bash
   psql "postgres://USER:OLD_PASSWORD@db.prisma.io:5432/postgres?sslmode=require"
   ```

   If it still connects, contact [support@prisma.io](mailto\:support@prisma.io).

Sessions opened with the leaked password before the delete may keep running. If you think one could still be open, contact [support@prisma.io](mailto\:support@prisma.io).

### Delete a credential [#delete-a-credential]

After a delete succeeds, nobody can sign in with that password. Database sessions that were already open when you deleted it may keep running. If a delete fails, nothing has changed: run it again, and if it keeps failing, contact [support@prisma.io](mailto\:support@prisma.io).

Delete a credential from Console, the CLI, or the REST API:

* **Console**: open **Connection strings** in the database's sidebar and find the credential by the last four characters of its password. Delete it, and type its name to confirm, which is `console-connection-string` for credentials Console created.

* **CLI**: sign in with `npx prisma auth login`. Find the database's id with `npx prisma postgres list`, list its credentials to find the one you want, then delete it. The CLI asks you to confirm the id.

  
    

#### bun

```bash
bunx prisma postgres list
bunx prisma postgres connection list <database-id>
bunx prisma postgres connection delete <connection-id>
```

#### pnpm

```bash
pnpm prisma postgres list
pnpm prisma postgres connection list <database-id>
pnpm prisma postgres connection delete <connection-id>
```

#### yarn

```bash
yarn prisma postgres list
yarn prisma postgres connection list <database-id>
yarn prisma postgres connection delete <connection-id>
```

#### npm

```bash
npx prisma postgres list
npx prisma postgres connection list <database-id>
npx prisma postgres connection delete <connection-id>
```
  

* **REST API**: [`GET /v1/connections`](https://www.prisma.io/docs/rest-api/endpoints/connections/get-connections) with the `databaseId` query parameter lists credentials and their ids, and [`DELETE /v1/connections/{id}`](https://www.prisma.io/docs/rest-api/endpoints/connections/delete-connections-by-id) deletes one. See [REST API](https://www.prisma.io/docs/rest-api) for the base URL and how to authenticate.

See the [`postgres` CLI reference](https://www.prisma.io/docs/cli/postgres) for every command.

### Rotate a credential [#rotate-a-credential]

Rotate gives a credential a new password. Prisma then tries to remove the old password, but if that fails you aren't told, so the old password can keep working. Use rotate for routine password changes, and delete the credential when you need to be sure the old password no longer works. Console has no rotate button. Rotate from the CLI or with [`POST /v1/connections/{id}/rotate`](https://www.prisma.io/docs/rest-api/endpoints/connections/post-connections-by-id-rotate):

  

#### bun

```bash
bunx prisma postgres connection rotate <connection-id>
```

#### pnpm

```bash
pnpm prisma postgres connection rotate <connection-id>
```

#### yarn

```bash
yarn prisma postgres connection rotate <connection-id>
```

#### npm

```bash
npx prisma postgres connection rotate <connection-id>
```

The CLI shows the new connection string only this one time, so save it. The REST API returns both the pooled and the direct connection string, as `endpoints.pooled.connectionString` and `endpoints.direct.connectionString`. The two strings are identical except for the host, `pooled.db.prisma.io` or `db.prisma.io`, so if you have one you can write the other. Then put the new strings in your app's environment variables and redeploy.

### Databases created through Vercel [#databases-created-through-vercel]

If you created the database through the Vercel Marketplace, Vercel created its first credential and stores it in your Vercel project's environment variables. Rotate that one from Vercel, as described in [Rotating your Prisma integration secrets in Vercel](https://www.prisma.io/docs/guides/postgres/vercel#rotating-your-prisma-integration-secrets-in-vercel). Because Vercel manages that password in your environment variables, rotating it from Vercel is the way to replace it, even after a leak. After a leak, also contact [support@prisma.io](mailto\:support@prisma.io) to confirm the old password no longer works. A rotation in Vercel doesn't change the credentials you created in Console.

## Regions and latency [#regions-and-latency]

You choose a database's region when you create it, and you can't change it afterwards. The **Connect to your database** dialog in Console shows the region next to the database's name. For the list of regions, see [What regions is Prisma Postgres available in?](https://www.prisma.io/docs/postgres/faq#what-regions-is-prisma-postgres-available-in).

Every query travels from your app to the database's region and back, so run your app in or near that region.

To move a database to another region, create a new database in the target region. Stop your app from writing to the old database before you copy anything, because writes made after `pg_dump` starts are not copied. Then copy the data: run `pg_dump` with the old database's direct connection string, and `pg_restore` with the new database's direct connection string. The commands and flags are in [Migrate a local Postgres database to Prisma Postgres](https://www.prisma.io/docs/postgres/import-from-existing-database). The new database has its own credentials, so put its connection strings in your app's environment variables and redeploy. Let your app write again only once it is using the new database.

## Troubleshooting [#troubleshooting]

### Migrations or db push fail with lock or prepared statement errors [#migrations-or-db-push-fail-with-lock-or-prepared-statement-errors]

The pooled connection string is being used where the direct string is required. Check that `prisma.config.ts` points at `DIRECT_URL` (`db.prisma.io`), not `DATABASE_URL`.

### "Too many connections" [#too-many-connections]

Your application is exceeding the connection limit for your plan. See the [Connection pooling troubleshooting](https://www.prisma.io/docs/postgres/database/connection-pooling#too-many-connections-or-connection-limit-errors) for specific causes and fixes.

### Connection refused or timeout on first connect [#connection-refused-or-timeout-on-first-connect]

Check that your connection string includes `sslmode=require` and uses port `5432`. If you are behind a corporate firewall or VPN that blocks outbound PostgreSQL traffic, you may need to allowlist `*.db.prisma.io` on port 5432, or use the [serverless driver](https://www.prisma.io/docs/postgres/database/serverless-driver) which operates over HTTPS.

## Related pages [#related-pages]

* [Connection pooling](https://www.prisma.io/docs/postgres/database/connection-pooling)
* [Serverless driver](https://www.prisma.io/docs/postgres/database/serverless-driver)
* [Backups](https://www.prisma.io/docs/postgres/database/backups)

## Related pages

- [`Backups`](https://www.prisma.io/docs/postgres/database/backups): Manage and restore database backups in Prisma Postgres
- [`Connect to Prisma Postgres without Accelerate`](https://www.prisma.io/docs/postgres/database/switch-from-accelerate): Replace a hosted Prisma Postgres Accelerate connection without moving your database or data
- [`Connection pooling`](https://www.prisma.io/docs/postgres/database/connection-pooling): Use Prisma Postgres connection pooling for concurrent application traffic.
- [`Extensions`](https://www.prisma.io/docs/postgres/database/postgres-extensions): Enable and use standard PostgreSQL extensions with Prisma Postgres.
- [`Query Insights`](https://www.prisma.io/docs/postgres/database/query-insights): Inspect slow queries, connect Prisma calls to SQL, and apply focused fixes with Prisma Postgres.