Connection String Encoding

If your database password contains special characters, you must URL-encode them to avoid authentication errors like:

Error: SASL_SIGNATURE_MISMATCH: The server did not return the correct signature
Error: password authentication failed for user

Get Your Connection String

Before encoding, get your connection string from Supabase:

1. Open Supabase Dashboard
2. Navigate to Settings → Database
3. Scroll to Connection String section
4. Copy the Transaction Mode connection string (port 6543)

The string looks like:

postgresql://postgres.pooler-yourproject:[YOUR-PASSWORD]@aws-0-us-east-1.pooler.supabase.com:6543/postgres

Replace [YOUR-PASSWORD] with your actual database password from the dashboard (you may need to reveal it first).

Common Characters That Need Encoding

Check if your password contains any of these characters:

Character	Encoding	Character	Encoding
@	%40	&	%26
:	%3A	/	%2F
?	%3F	#	%23
%	%25	(space)	%20
!	%21	=	%3D

Full encoding reference at MDN Web Docs

Encode Your Password

Use the code examples below to encode your password on your own machine. These methods allow you to encode your credentials locally without sharing them with third-party services.

Tip

Only encode the password portion, not the entire connection string.

JavaScript / Node.js

const encodedPassword = encodeURIComponent("my@complex&password!");
console.log(encodedPassword);
// Output: my%40complex%26password%21

Python

import urllib.parse
encoded_password = urllib.parse.quote("my@complex&password!")
print(encoded_password)
# Output: my%40complex%26password%21

Linux / macOS

# Requires jq
encoded_password=$(printf %s "my@complex&password!" | jq -sRr @uri)
echo $encoded_password
# Output: my%40complex%26password%21

Complete Example

Here’s a realistic example showing the full process:

Original password from Supabase Dashboard:

P@ssw0rd!2024

Encode just the password:

P%40ssw0rd%212024

Original connection string:

postgresql://postgres.pooler-yourproject:P@[email protected]:6543/postgres

Encoded connection string:

postgresql://postgres.pooler-yourproject:P%40ssw0rd%[email protected]:6543/postgres

Set as Supabase Secret

Use the encoded connection string to set your database secret:

npx supabase secrets set EDGE_WORKER_DB_URL="postgresql://postgres.pooler-yourproject:P%40ssw0rd%[email protected]:6543/postgres"

Replace the hostname, project name, and encoded password with your actual values.

Note

For local development, add the encoded connection string to supabase/functions/.env:

EDGE_WORKER_DB_URL="postgresql://postgres.pooler-yourproject:P%40ssw0rd%[email protected]:6543/postgres"

Verify It Works

Test your connection by deploying and starting your worker:

npx supabase functions deploy your-worker-name
curl "https://your-project.supabase.co/functions/v1/your-worker-name" \
  -H "Authorization: Bearer YOUR_ANON_KEY"

If you see worker logs without authentication errors, the encoding worked.

For full deployment instructions, see Deploy Your First Flow.

Security Considerations

Password Security

When working with database passwords:

• Never paste your database password into untrusted websites for encoding
• Avoid sharing your database password with third-party services
• Don’t commit your database password to Git repositories
• Use environment variables and secrets management tools instead