Database

Connecting to your database

Explore the options for connecting to your Postgres database.

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

  1. The Data APIs
  2. Using one of the many Client Libraries
  3. Direct connections using the built-in Postgres connection system
  4. Connection pooling for scalable connections

Data APIs

Supabase's Data APIs are 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: interact with your database through a REST interface.
  • GraphQL: interact with your database through a GraphQL interface.
  • Realtime: listen to database changes over websockets.

Client libraries

Supabase offers client libraries for popular programming languages. These libraries provide a convenient wrapper around the Data APIs, making it easier to interact with your database using your preferred language.

Connecting to external libraries and tools

Beyond the Supabase client-libraries, Supabase provides three connection strings for direct database access, compatible with all postgres libraries, such as Prisma and Drizzle, as well as tools like PSQL and pgAdmin.

You can find these connection strings in your Database Settings.

Direct connections:

It connects directly to your Postgres instance. It is ideal for persistent servers, such as virtual machines (VMs) and long-lasting containers. Examples include AWS EC2 machines, Fly.io VMs, and DigitalOcean Droplets.


_10
// Example String
_10
postgresql://postgres:[YOUR-PASSWORD]@db.apbkobhfnmcqqzqeeqss.supabase.co:5432/postgres

You can find the direct connection string in the Database settings inside the dashboard:

  1. Go to the Settings section.
  2. Click Database.
  3. Under Connection string, make sure Use connection pooling is unchecked. Copy the URI.

Supavisor session mode (port 5432):

In Session mode, Supavisor acts as an IPv4 proxy. It allows developers in IPv4-only environments to access a direct-connection experience without needing the IPv4 add-on.


_10
// Example String
_10
postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-ca-central-1.pooler.supabase.com:5432/postgres

Transaction mode (port 6543):

Supavisor in transaction mode forms hot connections with the database and only allows clients to access them when a query is pending. It has amazing scaling capacity, and is best used with temporary servers, such as serverless/Edge Functions or auto-scaling servers.


_10
// Example String
_10
postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-ca-central-1.pooler.supabase.com:6543/postgres

Connection pooling in-depth

Application side poolers

Application-side poolers are built into connection libraries and API servers, such as Prisma, SQLAlchemy, and PostgREST. They maintain several active connections with Postgres or a server-side pooler, reducing the overhead of establishing connections between queries. When deploying to static architecture, such as long-standing containers or VMs, application-side poolers are satisfactory on their own.

Serverside poolers

Postgres connections are like WebSocket, once established, they are preserved until the client (application server) disconnects. A server might only make a single 10 ms query, but needlessly reserve its database connection for seconds or longer.

Serverside-poolers, such as Supabase's Supavisor in transaction mode, sit between clients and the database and can be thought of as load balancers for Postgres connections.

They maintain hot connections with the database and intelligently share them with clients only when needed, maximizing the amount of queries a single connection can service. They're best used to manage queries from auto-scaling systems, such as edge and serverless functions.

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.

Choosing a connection method

  • Data APIs: Best for operations supported by the Data APIs.
  • Supavisor Pooler:
    • Transaction mode (port 6543): Best for serverless/edge functions and rapidly auto-scaling servers
    • Session mode (port 5432): For long-lived servers, such as virtual machines (VM) and enduring containers (if IPv6 is unsupported)
  • Direct Connections: For long-lived servers, such as VMs and enduring containers (if IPv6 is supported or the IPv4 Add-On is enabled).

Quickstart connection guides

External libraries

External tools

Resources