supabase/apps/docs/pages/guides/database/connecting-to-postgres.mdx

import Layout from '~/layouts/DefaultGuideLayout'
import StepHikeCompact from '~/components/StepHikeCompact'

export const meta = {
  id: 'connecting-to-postgres',
  title: 'Connecting to your database',
  description: 'Explore the options for connecting to your Postgres database.',
}

Supabase provides several options for programmatically connecting to your Postgres database:

1. Direct connections using Postgres' standard connection system
2. Connection pooling using PgBouncer
3. Programmatic access using the [Serverless APIs](/docs/guides/api)

## Serverless APIs

Supabase provides auto-updating [APIs](/docs/guides/database/api). This is the easiest way to get started if you are managing data (fetching, inserting, updating). We provide several types of API to suit your preferences:

- [REST](/docs/guides/api#rest-api-overview): interact with your database through a REST interface.
- [GraphQL](/docs/guides/api#graphql-api-overview): interact with your database through a GraphQL interface.
- [Realtime](/docs/guides/api#realtime-api-overview): listen to database changes over websockets.

## Direct connections

Every Supabase project provides a full Postgres database. You can connect to the database using [any tool which supports Postgres](#integrations). You can find the connection string in the [Database settings](https://supabase.com/dashboard/project/_/settings/database) inside the dashboard:

1. Go to the `Settings` section.
2. Click `Database`.
3. Find your Connection Info and Connection String. Direct connections are on port `5432`.

<video width="99%" muted playsInline controls={true}>
  <source
    src="https://xguihxuzqibwxjnimxev.supabase.co/storage/v1/object/public/videos/docs/postgres-connection.mp4"
    type="video/mp4"
  />
</video>

## Connection Pooler

Every Supabase project comes with PgBouncer for connection pooling. A connection pooler is useful for managing a large number of _temporary_ connections. For example, if you are using [Prisma](/partners/integrations/prisma), Drizzle, Kysely, or anything deployed to a Serverless environment (AWS Lambdas or Edge Functions). You can find the connection pool config in the [Database settings](https://supabase.com/dashboard/project/_/settings/database) inside the dashboard:

1. Go to the `Settings` section.
2. Click `Database`.
3. Find your Connection Info and Connection String. Connection pooling is on port `6543`.

<video width="99%" muted playsInline controls={true}>
  <source
    src="https://xguihxuzqibwxjnimxev.supabase.co/storage/v1/object/public/videos/docs/connection-pool-config.mp4"
    type="video/mp4"
  />
</video>

## Supavisor

<Admonition type="note">

Supavisor is currently in beta and is slowly being made available to all projects. [Contact support](https://supabase.com/dashboard/support/new) if you'd like to request early access.

</Admonition>

Supavisor is a new connection pooler by Supabase. It can provide a more scalable connection pool than PgBouncer, and runs on a high-availability cluster segregated from your database.

This can free up some CPU cycles for your database to use for queries. It also makes connecting to Postgres in a serverless environment much easier.

We're building compatibility with PgBouncer, and application changes will not be required to switch from PgBouncer to Supavisor. When a project is switched from PgBouncer to Supavisor, the appropriate connection string will be made available under the Connection Pooling section on [Database settings](https://supabase.com/dashboard/project/_/settings/database). Note that while PgBouncer remains accessible for use, it will no longer be available for configuration from the dashboard. The PgBouncer connection string will also be similarly inaccessible from the dashboard.

Supavisor is open source and compatible with any Postgres deployment. Check out [the Github repository](https://github.com/supabase/supavisor).

## Choosing a connection method

- The Serverless APIs provide programmatic access and have [built-in connection pooling](https://postgrest.org/en/stable/references/connection_pool.html). You can use these for all browser and application interactions. We recommend using these wherever possible.
- A "direct connection" is Postgres' native connection system. You should use this for tools which are always alive - usually installed on a long-running server, like Node.js, Ruby, Python, etc.
- A "connection pooler" is a tool which keeps connections "alive". You should use this for serverless functions and tools which disconnect from the database frequently, like Prisma, Drizzle, Kysely, etc.

Why would you use a connection pool? Primarily because the way that Postgres handles connections isn't very scalable for a large number of _temporary_ connections. You can use these simple questions to determine which connection method to use:

- Are you connecting to a database and _maintaining_ a connection? If yes, use a direct connection.
- Are you connecting to your database and then _disconnecting_ immediately (e.g. a serverless environment)? If yes, use a connection pool.

## Connecting with SSL

You should connect to your database using SSL wherever possible, to prevent snooping and man-in-the-middle attacks.

You can obtain your connection info and Server root certificate from your application's dashboard:

![Connection Info and Certificate.](/docs/img/guides/database/connection-info-cert.png)

## How connection pooling works

A "connection pool" is a system (external to Postgres) which manages connections, rather than PostgreSQL's native system. Supabase uses [PgBouncer](https://www.pgbouncer.org/) for connection pooling.

When a client makes a request, PgBouncer "allocates" an available connection to the client. When the client transaction or session is completed the connection is returned to the pool and is free to be used by another client.

![Connection pooling](/docs/img/guides/database/connection-pool.png)

Pgbounce provides several Pool Modes, each handling connections differently:

#### Session

When a new client connects, a connection is assigned to the client until it disconnects. Afterward, the connection is returned back to the pool.

All PostgreSQL features can be used with this option.

#### Transaction

This is the suggested option for serverless functions. A connection is only assigned to the client for the duration of a transaction. Two consecutive transactions from the same client could be executed over two different connections.

Some session-based PostgreSQL features such as prepared statements are not available with this option. A comprehensive list of incompatible features can be found [here](https://www.pgbouncer.org/features.html).

#### Statement

This is the most granular option. Connections are returned to the pool after every statement. Transactions with multiple statements are not allowed. This is best used when `AUTOCOMMIT` is in use.

## Integrations

### Connecting with Drizzle

[Drizzle ORM](https://github.com/drizzle-team/drizzle-orm) is a TypeScript ORM for SQL databases designed with maximum type safety in mind. You can use their ORM to connect to your database.

<StepHikeCompact>

  <StepHikeCompact.Step step={1}>

    <StepHikeCompact.Details title="Install">

    Install Drizzle and releated dependencies.

    </StepHikeCompact.Details>

    <StepHikeCompact.Code>

     ```shell
     npm i drizzle-orm postgres
     npm i -D drizzle-kit
     ```

    </StepHikeCompact.Code>

  </StepHikeCompact.Step>

  <StepHikeCompact.Step step={2}>

    <StepHikeCompact.Details title="Create your models">

    Create a `schema.ts` file and define your models.

    </StepHikeCompact.Details>

    <StepHikeCompact.Code>

    ```ts
    import { pgTable, serial, text, varchar } from "drizzle-orm/pg-core";

    export const users = pgTable('users', {
      id: serial('id').primaryKey(),
      fullName: text('full_name'),
      phone: varchar('phone', { length: 256 }),
    });
    ```

    </StepHikeCompact.Code>

  </StepHikeCompact.Step>

  <StepHikeCompact.Step step={3}>

    <StepHikeCompact.Details title="Connect">

    Connect to your database using the Connection Pooler for serverless environments, and the Direct Connection for long-running servers.

    </StepHikeCompact.Details>

    <StepHikeCompact.Code>

    ```ts
    import { drizzle } from 'drizzle-orm/postgres-js'
    import postgres from 'postgres'
    import { users } from './schema'

    const connectionString = process.env.DATABASE_URL
    const client = postgres(connectionString)
    const db = drizzle(client);

    const allUsers = await db.select().from(users);
    ```

    </StepHikeCompact.Code>

  </StepHikeCompact.Step>

</StepHikeCompact>

### Connecting with pgAdmin

[`pgAdmin`](https://www.pgadmin.org/) is a GUI tool for managing Postgres databases. You can use it to connect to your database via SSL:

<StepHikeCompact>

  <StepHikeCompact.Step step={1}>

    <StepHikeCompact.Details title="Register">

    Register a new Postgres server.

    </StepHikeCompact.Details>

    <StepHikeCompact.Code>

     ![Register a new postgres server.](/docs/img/guides/database/register-server-pgAdmin.png)

    </StepHikeCompact.Code>

  </StepHikeCompact.Step>

  <StepHikeCompact.Step step={2}>

    <StepHikeCompact.Details title="Name">

    Name your server.

    </StepHikeCompact.Details>

    <StepHikeCompact.Code>

     ![Name Postgres Server.](/docs/img/guides/database/name-pg-server.png)

    </StepHikeCompact.Code>

  </StepHikeCompact.Step>

  <StepHikeCompact.Step step={3}>

    <StepHikeCompact.Details title="Connect">

    Add the connection info. You can use the "Direct connection" config, which you can find in your Supabase dashboard.

    </StepHikeCompact.Details>

    <StepHikeCompact.Code>

     ![Add Connection Info.](/docs/img/guides/database/add-pg-server-conn-info.png)

    </StepHikeCompact.Code>

  </StepHikeCompact.Step>

  <StepHikeCompact.Step step={4}>

    <StepHikeCompact.Details title="SSL">

    Navigate to the Parameters tab and select connection parameter as Root Certificate. Next navigate to the Root certificate input, it will open up a file-picker modal. Select the certificate you downloaded from your Supabase dashboard and save the server details. PgAdmin should now be able to connect to your Postgres via SSL.

    </StepHikeCompact.Details>

    <StepHikeCompact.Code>

     ![Add Connection Info.](/docs/img/guides/database/add-ssl-config-parameter.png)

    </StepHikeCompact.Code>

  </StepHikeCompact.Step>

</StepHikeCompact>

### Connecting with psql

[`psql`](https://www.postgresql.org/docs/current/app-psql.html) is a command-line tool that comes with Postgres.

Assuming you've downloaded your SSL certificate to `$HOME/Downloads/prod-supabase.cer`, and your host address is `db.ref.supabase.co` you connect to your database via SSL:

```shell
psql "sslmode=verify-full sslrootcert=$HOME/Downloads/prod-supabase.cer host=db.ref.supabase.co dbname=postgres user=postgres"
```

### Connecting with Postgres.js

[Postgres.js](https://github.com/porsager/postgres) is a full-featured PostgreSQL client for Node.js and Deno.

<StepHikeCompact>

  <StepHikeCompact.Step step={1}>

    <StepHikeCompact.Details title="Install">

    Install Postgres.js and releated dependencies.

    </StepHikeCompact.Details>

    <StepHikeCompact.Code>

     ```shell
     npm i postgres
     ```

    </StepHikeCompact.Code>

  </StepHikeCompact.Step>

  <StepHikeCompact.Step step={2}>

    <StepHikeCompact.Details title="Connect">

    Create a `db.js` file with the connection details. Use the Connection Pooler for serverless environments, and the Direct Connection for long-running servers.

    </StepHikeCompact.Details>

    <StepHikeCompact.Code>

    ```ts
    // db.js
    import postgres from 'postgres'

    const connectionString = process.env.DATABASE_URL
    const sql = postgres(connectionString)

    export default sql
    ```

    </StepHikeCompact.Code>

  </StepHikeCompact.Step>

  <StepHikeCompact.Step step={3}>

    <StepHikeCompact.Details title="Execute commands">

    Use the connection to execute commands.

    </StepHikeCompact.Details>

    <StepHikeCompact.Code>

    ```ts
    import sql from './db.js'

    async function getUsersOver(age) {
      const users = await sql`
        select name, age
        from users
        where age > ${ age }
      `
      // users = Result [{ name: "Walter", age: 80 }, { name: 'Murray', age: 68 }, ...]
      return users
    }
    ```

    </StepHikeCompact.Code>

  </StepHikeCompact.Step>

</StepHikeCompact>

export const Page = ({ children }) => <Layout meta={meta} children={children} />

export default Page