Supabase Connection String: Guide, Ports & Pooling (2026)

Building a modern application often means connecting your frontend to a powerful backend, and Supabase has become a go to choice for its simplicity and robust Postgres foundation. At the heart of this process is the Supabase connection string: a single URI containing all the credentials (host, port, user, and password) an application needs to connect to your database. You can find this string directly in your Supabase dashboard under Project Settings > Database. Whether you are building from scratch or using a visual development platform like WeWeb to accelerate your workflow, you will eventually need to handle this key credential.

This guide will demystify everything else you need to know. We will break down the string’s format, how to choose the right one for your needs (from direct connections to advanced pooling), and how to troubleshoot the most common errors. If you’re building with WeWeb, check out our Academy tutorials for step‑by‑step guidance.

What is a Supabase Connection String (and Where to Find It)?

A database connection string is a single line of text that contains all the information an application needs to connect to a database. Think of it as the complete address and set of keys for your data. It typically includes the host, port, database name, username, and password.

For Supabase, which is built on PostgreSQL, this string follows a standard URI (Uniform Resource Identifier) format. It consolidates all your credentials into one convenient package, making it easy to configure your application.

How to find your Supabase connection string:

Finding your connection details is straightforward.

Log in to your Supabase account.
Navigate to the project you want to connect to.
In the left sidebar, go to Project Settings (the gear icon).
Click on Database.
Under the Connection info section, you will find all the components (host, database name, user, port) and a fully assembled Supabase connection string ready to be copied.

Always treat your connection string like a password. It contains sensitive credentials and should never be exposed in client side code or committed to a public git repository. The best practice is to store it in an environment variable on your server.

Decoding the Supabase Connection String Format

The Supabase connection string uses the standard PostgreSQL URI format, which looks like this:

postgresql://[user]:[password]@[host]:[port]/[database_name]

Let’s break down each part:

postgresql://: The protocol. Sometimes you might see the shorter postgres://.
[user]: The username for your database. For Supabase, this is typically postgres.
[password]: The password you set for your database during project creation.
[host]: The address of your Supabase database server. This is a unique domain provided by Supabase.
[port]: The port number the database is listening on. This can vary depending on the type of connection (direct vs. pooled).
[database_name]: The name of the database to connect to. In Supabase, this is usually postgres.

You can also add extra options as query parameters at the end, like ?sslmode=require. For example, a complete string might look like: postgresql://postgres:YourPassword@db.projectref.supabase.co:5432/postgres.

Direct vs. Pooled: Choosing the Right Connection String

Supabase provides different connection strings to optimize for various use cases, primarily centered around a powerful feature called connection pooling. A connection pooler is a service that sits between your app and the database to manage connections efficiently, preventing your database from being overwhelmed.

Session Mode: For Stateful Applications

In session pooling mode, when your application connects, it gets a dedicated database connection for the entire duration of its session. It is the most straightforward pooling method because it behaves just like a direct connection.

How it works: One client gets one database connection until it disconnects.
Pros: Supports all PostgreSQL features, including temporary tables, session variables, and LISTEN/NOTIFY. It is the safest and most compatible mode.
Cons: Can still use up many database connections if you have a lot of long lived, concurrent clients.
Supabase Connection String: This is often the default connection string found in your dashboard, typically using port 5432. It is ideal for traditional monolithic backends or stateful applications such as internal tools.

Transaction Mode: For Serverless and Edge Functions

In transaction pooling mode, your application borrows a connection only for the duration of a single transaction. Once the transaction is committed or rolled back, the connection is immediately returned to the pool for another client to use.

How it works: Connections are shared and reused very quickly between many clients.
Pros: Massively scalable. It allows thousands of clients (like serverless functions) to connect without exhausting database resources. This is why Supabase recommends it for serverless and edge environments. Building a SaaS? See how WeWeb helps you build and scale SaaS apps.
Cons: Does not support session specific features. Any state (like SET search_path or temporary tables) is lost between transactions.
Supabase Connection String: Supabase provides a separate connection string for its transaction pooler, which uses a different port, often 6543.

Fact: Using a transaction pooler, a platform like Supabase can support up to 10,000 concurrent client connections, far more than a PostgreSQL database could handle directly.

The Dedicated Pooler: For Production Scale

For projects on paid plans, Supabase provisions a dedicated pooler. Unlike the default shared pooler, which handles traffic for many projects, a dedicated pooler is a resource exclusive to your project.

This offers better performance, lower latency, and more stability because you are not competing with “noisy neighbors”. When you upgrade, you will find a new dedicated Supabase connection string in your dashboard. This string will point to the dedicated pooler, which is co‑located with your database for minimal latency. You can then plug it into your stack via WeWeb integrations.

Advanced Connection String Options

Beyond the basics, a few other factors can influence your Supabase connection string.

IPv4 vs. IPv6: Does It Matter for Your Connection?

By default, Supabase database instances are often accessible over IPv6, a newer internet protocol with a vastly larger address space than the older IPv4.

What this means: If your application or hosting environment does not support IPv6, you might encounter a “Connection refused” or “No route to host” error.
The solution: Supabase provides an IPv4 add on for paid projects. Alternatively, the shared connection pooler usually has an IPv4 address available. If you use an IPv6 address directly in a URI, it must be enclosed in brackets, like postgresql://user@[2001:db8::1]:5432/db.

Securing Your Connection with SSL

SSL (or more accurately, TLS) encrypts the data between your application and your database. This is crucial for security, as it prevents anyone from snooping on your network traffic.

Supabase and most other managed database providers require SSL connections. You can enforce this in your connection string with the sslmode parameter.

?sslmode=require: This ensures an encrypted connection but does not verify the server’s certificate identity. This is a common and secure enough setting for many use cases.
?sslmode=verify-full: This is even more secure, as it encrypts the connection and verifies that you are connecting to the legitimate server, preventing man in the middle attacks.

Prepared Statements and the Transaction Pooler

Prepared statements are a database feature that can boost performance by pre compiling SQL queries. Historically, they were incompatible with transaction poolers because they rely on session state, which is lost in transaction mode. This often led to “prepared statement does not exist” errors.

Fact: This limitation is now a thing of the past. Modern versions of PgBouncer (the pooler used by Supabase) starting with version 1.21, now support prepared statements in transaction mode. This allows you to get the best of both worlds: the scalability of transaction pooling and the performance benefits of prepared statements. Supabase is rolling out this feature, so check their latest documentation for availability.

Troubleshooting Common Supabase Connection Errors

Even with the correct Supabase connection string, you can run into issues. Here are two of the most common errors and how to fix them.

Fixing “Connection Refused”

This error means your request reached the server, but it was actively rejected. It is a network level problem, not an authentication issue.

Common Causes and Fixes:

Database is Paused: Free tier Supabase projects are paused after a week of inactivity. Go to your dashboard and resume the project.
Incorrect Host or Port: Double check your connection string. Are you using the correct port for the pooler you intend to use (e.g., 5432 vs. 6543)?
Firewall or Network Rules: If you are connecting from a corporate network or have strict firewall rules, ensure that outbound traffic to your Supabase host and port is allowed. Supabase also requires you to add your connecting IP address to a network allow list for direct connections.
IPv4/IPv6 Mismatch: As mentioned earlier, your environment might not support the IPv6 address of your database. Try using the pooled connection string or enable the IPv4 add on.

Fixing “Password Authentication Failed”

This error is more straightforward: the database user exists, but the password you provided is incorrect.

Common Causes and Fixes:

Incorrect Password: This is the most common reason. A simple typo or using credentials from a different environment (e.g., staging vs. production) can cause this. Verify the password and update it in your application’s environment variables.
Special Characters: If your password contains special characters, it may need to be URL encoded to be parsed correctly in the connection string URI.
Password Was Reset: Did you or a team member reset the database password in the Supabase dashboard? If so, you must update your connection string everywhere it is used.

Building powerful applications doesn’t have to be a struggle with infrastructure. While knowing your way around a Supabase connection string is empowering, platforms like WeWeb abstract away much of this complexity. You can securely connect to Supabase, build a full‑stack application visually, start from production‑ready templates, and let the platform handle the heavy lifting. Want inspiration? Explore real‑world apps in the WeWeb Showcase.

Frequently Asked Questions

What is the default Supabase connection string port?

The default port for a direct or session mode connection to Supabase PostgreSQL is 5432. The transaction mode connection pooler typically uses port 6543.

How do I get my Supabase connection string?

You can find and copy your full Supabase connection string from your project’s dashboard by navigating to Project Settings > Database > Connection info.

What is the difference between the session and transaction mode Supabase connection string?

The main difference is the port number and the underlying pooling behavior. The session mode string (port 5432) gives you a dedicated connection, supporting all Postgres features. The transaction mode string (port 6543) is for high scalability (like serverless functions) and reuses connections aggressively, which restricts some session based features.

Why is my Supabase connection string not working?

Common reasons include a paused database (on the free tier), incorrect credentials (wrong password), network restrictions (firewall or IP allow lists), or an IPv4/IPv6 connectivity issue. Start by checking if your project is active in the Supabase dashboard.

Can I use my Supabase connection string directly in my frontend application?

No, never do this. Your Supabase connection string contains your master database password and would be exposed to anyone visiting your site. This would give them full control over your database. You should only use this string from a secure backend server. For frontend access, use the Supabase client libraries with Row Level Security.

Does the Supabase connection string change?

The string will change if you reset your database password or if you upgrade to a plan with a dedicated pooler. After making these changes, you will need to copy the new connection string from your dashboard and update your application’s environment variables.