mirror of
https://github.com/supabase/supabase.git
synced 2026-10-17 23:29:08 +03:00
142 lines
6.7 KiB
Plaintext
142 lines
6.7 KiB
Plaintext
---
|
|
id: 'connecting-to-postgres'
|
|
title: 'Connecting to your database'
|
|
description: 'Explore the options for connecting to your Postgres database.'
|
|
subtitle: 'Explore the options for connecting to your Postgres database.'
|
|
---
|
|
|
|
Supabase provides several options for programmatically connecting to your Postgres database:
|
|
|
|
1. The Data APIs
|
|
1. Using one of the many [Client Libraries](/docs/reference)
|
|
1. Direct connections using the built-in Postgres connection system
|
|
1. 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](/docs/guides/api): interact with your database through a REST interface.
|
|
- [GraphQL](/docs/guides/graphql/api): interact with your database through a GraphQL interface.
|
|
- [Realtime](/docs/guides/realtime#realtime-api): listen to database changes over websockets.
|
|
|
|
## Client libraries
|
|
|
|
Supabase offers [client libraries](/docs/reference) 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](/docs/guides/api/rest/client-libs), Supabase provides three connection strings for direct database access, compatible with all postgres libraries, such as [Prisma](/docs/guides/database/prisma) and [Drizzle](/docs/guides/database/drizzle), as well as tools like [PSQL](/docs/guides/database/psql) and [pgAdmin](/docs/guides/database/pgadmin).
|
|
|
|
You can find these connection strings in your [Database Settings](https://supabase.com/dashboard/project/_/settings/database).
|
|
|
|
### 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.
|
|
|
|
<Admonition type="caution">
|
|
|
|
Direct connections use IPv6 by default. If your environment doesn't support IPv6 or you're unsure but still want to use a direct connection, check out the [networking guide](/docs/guides/platform/ipv4-address#supabase-and-ipv6-compatibility) for more info.
|
|
|
|
</Admonition>
|
|
|
|
```md
|
|
// Example String
|
|
postgresql://postgres:[YOUR-PASSWORD]@db.apbkobhfnmcqqzqeeqss.supabase.co:5432/postgres
|
|
```
|
|
|
|
You can find the direct 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. 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.
|
|
|
|
```md
|
|
// Example String
|
|
postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-ca-central-1.pooler.supabase.com:5432/postgres
|
|
```
|
|
|
|
### Transaction mode (port 6543):
|
|
|
|
<Admonition type="caution">
|
|
|
|
Transaction mode does not support [prepared statements](https://postgresql.org/docs/current/sql-prepare.html). To avoid errors, [turn off prepared statements](https://github.com/orgs/supabase/discussions/28239) for your specific connection library.
|
|
|
|
</Admonition>
|
|
|
|
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.
|
|
|
|
```md
|
|
// Example String
|
|
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](https://github.com/supabase/supavisor) in transaction mode, sit between clients and the database and can be thought of as load balancers for Postgres connections.
|
|
|
|
<Image
|
|
alt="New migration files trigger migrations on the preview instance."
|
|
src={{
|
|
dark: '/docs/img/guides/database/connecting-to-postgres/how-connection-pooling-works.png',
|
|
light:
|
|
'/docs/img/guides/database/connecting-to-postgres/how-connection-pooling-works--light.png',
|
|
}}
|
|
caption="Connecting to the database directly vs using a Connection Pooler"
|
|
zoomable
|
|
/>
|
|
|
|
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:
|
|
|
|
|
|
|
|
## 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
|
|
|
|
<Admonition type="tip">
|
|
|
|
If you'd like us to add a new quickstart guide, share your [feedback](https://supabase.com/dashboard/support/new), and we'll try to add it going forwards.
|
|
|
|
</Admonition>
|
|
|
|
### External libraries
|
|
|
|
- [Prisma](/docs/guides/database/prisma)
|
|
- [Drizzle](/docs/guides/database/drizzle)
|
|
- [Postgres.js](/docs/guides/database/postgres-js)
|
|
|
|
### External tools
|
|
|
|
- [pgAdmin](/docs/guides/database/pgadmin)
|
|
- [PSQL](/docs/guides/database/psql)
|
|
- [DBeaver](/docs/guides/database/dbeaver)
|
|
|
|
## Resources
|
|
|
|
- [Connection management](/docs/guides/database/connection-management)
|