Enable Database Connection Pooler in Supabase's Local Development

Sep 17, 2025 by Faris Perwira — 2 min read
Enable Database Connection Pooler in Supabase's Local Development
Photo by Richard Horvath on Unsplash

If you're not familiar with Connection Pooling, you can read the Supabase's documentation here. In short, Connection pooling improves database performance by reusing existing connections between queries. This reduces the overhead of establishing connections and improves scalability.

Prerequisites

Before enabling the transaction pooler locally, ensure you have the following:

  • Supabase CLI Installed: Download and install the latest version from the official Supabase CLI documentation. Verify installation by running supabase --version in your terminal.
  • Docker Running: The local Supabase stack relies on Docker to spin up services like Postgres. Ensure Docker Desktop (or equivalent) is installed and running.
  • A Local Supabase Project: If you haven't set one up, navigate to your project directory and run supabase init to create the necessary configuration files, including supabase/config.toml.

These prerequisites allow the CLI to manage the local Docker-based stack, including the database and optional pooler services.

Enable Connection Pooler in Local Dev

  1. Update supabase config.toml to enable [db.pooler] and configure the pooler
[db.pooler]
enabled = true
# Port to use for the local connection pooler.
port = 54329
# Specifies when a server connection can be reused by other clients.
# Configure one of the supported pooler modes: `transaction`, `session`.
pool_mode = "transaction"
# How many server connections to allow per user/database pair.
default_pool_size = 20
# Maximum number of client connections allowed.
max_client_conn = 100
  1. Update dabatabase connection string user to use pooler-dev, eg:
postgresql://postgres.pooler-dev:postgres@localhost:54329/postgres
  1. Test database connection

By enabling the transaction pooler locally, you can develop and test more realistically, especially for apps with transient connections. For production, switch to the hosted Supavisor transaction mode via your dashboard.

References: