mirror of
https://github.com/supabase/supabase.git
synced 2026-07-07 03:34:27 +08:00
154 lines
4.9 KiB
Plaintext
154 lines
4.9 KiB
Plaintext
---
|
|
id: connecting-to-postgres
|
|
title: "Connecting"
|
|
description: There are various ways to connect to your Postgres database.
|
|
---
|
|
|
|
Supabase provides several options for programmatically connecting to your Postgres database:
|
|
|
|
## Types of Connection
|
|
|
|
- HTTP connections using the API.
|
|
- Direct connections using Postgres' standard connection system.
|
|
- Connection pooling using PgBouncer.
|
|
|
|
|
|
### Direct vs Connection Pooling
|
|
|
|
A "direct connection" is when a connection is made to the database using Postgres' native connection implementation.
|
|
|
|
A "connection pool" is a system (external to Postgres)
|
|
which manage connections, rather than Postgres' native system.
|
|
|
|
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.
|
|
|
|
|
|
## API
|
|
|
|
Supabase provides an auto-updating [API](/docs/guides/api). This is the easiest way to get started if you are managing data (fetching, inserting, updating).
|
|
|
|
|
|
### Interfaces
|
|
|
|
We provides several types of API to suit your preferences and use-case:
|
|
|
|
- [REST](/docs/guides/api#rest-api): interact with your database through a REST interface.
|
|
- [GraphQL](/docs/guides/api#graphql-api): interact with your database through a GraphQL interface.
|
|
- [Realtime](/docs/guides/api#realtime-api): listen to database changes over websockets.
|
|
|
|
You cannot manage the database schema via the API (for security reasons). To do that you can use the dashboard or connect directly to your database.
|
|
|
|
### Finding your API URL
|
|
|
|
You can find the API URL and Keys inside the Dashboard.
|
|
|
|
<Tabs
|
|
defaultValue="UI"
|
|
values={[
|
|
{label: 'UI', value: 'UI'}
|
|
]}>
|
|
<TabItem value="UI">
|
|
|
|
```sh
|
|
1. Go to the "Settings" section.
|
|
2. Click "API" in the sidebar.
|
|
3. Find your API URL and Keys in this page.
|
|
```
|
|
|
|
<video width="99%" muted playsInline controls="true">
|
|
<source src="/docs/videos/api/api-url-and-key.mp4" type="video/mp4" muted playsInline />
|
|
</video>
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
|
|
## Direct connections
|
|
|
|
Every Supabase project provides a full Postgres database. You can connect to the database using any tool which supports Postgres.
|
|
|
|
### Finding your connection string
|
|
|
|
<Tabs
|
|
defaultValue="UI"
|
|
values={[
|
|
{label: 'UI', value: 'UI'}
|
|
]}>
|
|
<TabItem value="UI">
|
|
|
|
```sh
|
|
1. Go to the "Settings" section.
|
|
2. Click "Database".
|
|
3. Find your Connection Info and Connection String.
|
|
```
|
|
|
|
<video width="99%" muted playsInline controls="true">
|
|
<source src="/docs/videos/postgres-connection.mp4" type="video/mp4" muted playsInline />
|
|
</video>
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Connection Pool
|
|
|
|
Connection pools are useful for managing a large number of _temporary_ connections. For example, if you are using [Prisma](/docs/guides/integrations/prisma) deployed to a Serverless environment.
|
|
|
|
### 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.
|
|
|
|
|
|
|
|
|
|
|
|
### Pool modes
|
|
|
|
Pool Mode determines how PgBouncer handles a connection.
|
|
|
|
#### 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.
|
|
|
|
### Finding the connection pool config
|
|
|
|
<Tabs
|
|
defaultValue="UI"
|
|
values={[
|
|
{label: 'UI', value: 'UI'}
|
|
]}>
|
|
<TabItem value="UI">
|
|
|
|
```sh
|
|
1. Go to the "Database" section.
|
|
2. Click "Connection Pooling".
|
|
3. Find your Connection Info and Connection String.
|
|
```
|
|
|
|
<video width="99%" muted playsInline controls="true">
|
|
<source src="/docs/videos/pgbouncer-connection.mp4" type="video/mp4" muted playsInline />
|
|
</video>
|
|
|
|
</TabItem>
|
|
</Tabs>
|