Connecting to your database
Explore the options for connecting to your Postgres database.
Supabase provides several options for programmatically connecting to your Postgres database:
- The Data APIs
- Using one of the many Client Libraries
- Direct connections using the built-in Postgres connection system
- 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.
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 for more info.
_10// Example String_10postgresql://postgres:[YOUR-PASSWORD]@db.apbkobhfnmcqqzqeeqss.supabase.co:5432/postgres
You can find the direct connection string in the Database settings inside the dashboard:
- Go to the
Settings
section. - Click
Database
. - Under
Connection string
, make sureUse 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_10postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-ca-central-1.pooler.supabase.com:5432/postgres
Transaction mode (port 6543):
Transaction mode does not support prepared statements. To avoid errors, turn off prepared statements for your specific connection library.
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_10postgres://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:
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
If you'd like us to add a new quickstart guide, share your feedback, and we'll try to add it going forwards.