PostgreSQL connection string builder
Build a PostgreSQL connection URI, a libpq keyword/value string, an Npgsql (ADO.NET) string, a JDBC URL and more from one form, or paste any of them to see what each parameter does and whether sslmode actually protects you. It all runs in your browser: nothing you type is sent anywhere.
Open this connection in SQLly
Opens SQLly's connection editor filled in.
Open this connection in SQLly
Private by design. The builder and decoder are plain JavaScript running in this tab. The page sends no request with what you type, stores nothing (not even in your browser), and keeps working offline once loaded. The Open in SQLly link goes from your browser straight to the app on your computer.
PostgreSQL connection string formats
Most PostgreSQL drivers sit on libpq or copy its rules, so the URI postgresql://user:password@host:5432/db?sslmode=verify-full and the keyword/value form host=... dbname=... work almost everywhere: psql, psycopg, pgx, lib/pq, node-postgres. Npgsql (.NET) and pgJDBC (Java) have their own spellings.
The parameter that matters most is sslmode. Its default, prefer, uses TLS when the server offers it but never checks the certificate and quietly falls back to plain text. Only verify-full checks both the certificate chain and the host name.
URI libpq, psql, psycopg, pgx, node-postgres, Prisma
postgresql://app_user:[email protected]/sales?sslmode=verify-full
Keyword/value libpq conninfo, psycopg, pgx, lib/pq
host=db.example.com dbname=sales user=app_user password=your_password sslmode=verify-full
ADO.NET (Npgsql) Npgsql, Entity Framework Core
Host=db.example.com;Database=sales;Username=app_user;Password=your_password;SSL Mode=VerifyFull
JDBC PostgreSQL JDBC Driver (pgJDBC)
jdbc:postgresql://db.example.com/sales?user=app_user&password=your_password&sslmode=verify-full
ODBC psqlODBC
Driver={PostgreSQL Unicode};Server=db.example.com;Database=sales;Uid=app_user;Pwd=your_password;SSLmode=verify-full;
SQLAlchemy URL Python SQLAlchemy with psycopg 3
postgresql+psycopg://app_user:[email protected]/sales?sslmode=verify-full
Several hosts (failover) libpq 10+, pgx, Npgsql, pgJDBC
postgresql://[email protected]:5432,db2.example.com:5432/sales?target_session_attrs=read-write
Placeholders such as your_password are just that: build your own string with the form above. More about connecting SQLly to PostgreSQL: SQLly for PostgreSQL.
libpq parameters (URI and keyword/value)
URI form: postgresql://[user[:password]@][host][:port][,...][/dbname][?param=value&...] (postgres:// works too); percent-encode special characters, including the slashes of a Unix-socket path used as the host. Keyword/value form: key=value pairs separated by spaces; single-quote a value that is empty or contains spaces, and write \' and \\ for a quote or backslash inside it.
| Keyword | Synonyms | Default | What it does |
|---|---|---|---|
host |
- | Unix socket in /tmp (localhost on Windows) | Host name, IP, or a directory for a Unix socket. A comma list is tried in order. |
hostaddr |
- | - | Numeric IP, skipping DNS (host is still used for TLS checks). |
port |
- | 5432 (the build default) | One port, or one per host. |
dbname |
- | the user name | Database to connect to. |
user |
- | the operating-system user | Role to connect as. |
password |
- | - | Better kept in ~/.pgpass (or PGPASSWORD) than in the string. |
passfile |
- | ~/.pgpass (%APPDATA%\postgresql\pgpass.conf on Windows) | Password file. |
connect_timeout |
- | 0 (wait forever) | Seconds per host. PostgreSQL 16 and older treat 1 as 2. |
sslmode |
- | prefer | disable, allow, prefer, require, verify-ca, verify-full. require verifies the CA only if a root certificate file exists; only verify-full checks the host name. |
sslrootcert |
- | ~/.postgresql/root.crt | CA file. system (16+) uses the operating system's trusted CAs and makes verify-full the default. |
sslcert / sslkey |
- | ~/.postgresql/postgresql.crt / .key | Client certificate and key. |
sslnegotiation |
- | postgres | 17+. direct starts TLS immediately (needs sslmode require or stronger). |
application_name |
- | - | Shown in pg_stat_activity and the server log. |
options |
- | - | Server settings at startup, e.g. -c statement_timeout=30000 -c search_path=app. |
target_session_attrs |
- | any | any, read-write, read-only, primary, standby, prefer-standby. |
load_balance_hosts |
- | disable | 16+. random shuffles the host list. |
keepalives |
- | 1 | TCP keepalives on/off; tune with keepalives_idle, keepalives_interval, keepalives_count. |
channel_binding |
- | prefer | require refuses to authenticate without SCRAM channel binding. |
Npgsql (ADO.NET) parameters
Npgsql uses ADO.NET Key=Value; syntax with its own keyword names. Quote values containing ; with double quotes.
| Keyword | Synonyms | Default | What it does |
|---|---|---|---|
Host |
Server | - (required) | Host name, IP, a comma list, or a socket directory starting with /. |
Port |
- | 5432 | TCP port. |
Database |
DB | the user name | Database name. |
Username |
User Name, User Id, UID | PGUSER, else the OS user | Role name. |
Password |
PSW, PWD | PGPASSWORD | Password. |
SSL Mode |
SslMode | Prefer | Disable, Allow, Prefer, Require, VerifyCA, VerifyFull. Since Npgsql 6, Require does not validate the certificate. |
Trust Server Certificate |
- | false | Skip validation. Npgsql 6 and 7 required it with Require; Npgsql 8 does not. |
Root Certificate |
- | PGSSLROOTCERT | CA file for VerifyCA / VerifyFull. |
Timeout |
- | 15 | Seconds to wait for a connection. |
Command Timeout |
- | 30 | Default command timeout in seconds; 0 waits forever. |
Application Name |
- | PGAPPNAME | application_name. |
Search Path |
- | - | Schema search path. |
Target Session Attributes |
- | any | any, primary, standby, prefer-primary, prefer-standby, read-write, read-only. |
Pooling |
- | true | Connection pooling. |
Maximum Pool Size |
- | 100 | Largest pool. |
Minimum Pool Size |
- | 0 | Smallest pool. |
Keepalive |
- | 0 (off) | Seconds between keepalive queries. |
Include Error Detail |
- | false | Puts server error detail, which can contain row data, into exception messages. |
pgJDBC properties
URL form: jdbc:postgresql://host:port/database?property=value&.... pgJDBC does not read user:password@ in the URL: pass user and password as parameters or connection properties.
| Keyword | Synonyms | Default | What it does |
|---|---|---|---|
user / password |
- | - | Credentials. |
sslmode |
- | prefer | Same values as libpq. require, allow and prefer do not validate the certificate. |
ssl |
- | false | true with no sslmode means verify-full. |
sslrootcert |
- | ~/.postgresql/root.crt | CA file. |
connectTimeout |
- | 10 | Seconds to wait for the socket; 0 disables the limit. |
socketTimeout |
- | 0 | Seconds a read may block; 0 waits forever. |
loginTimeout |
- | 0 | Seconds to wait for the whole login. |
ApplicationName |
- | PostgreSQL JDBC Driver | application_name. |
currentSchema |
- | - | search_path, comma separated. |
targetServerType |
- | any | any, primary, secondary, preferPrimary, preferSecondary. |
options |
- | - | Startup options, e.g. -c statement_timeout=30000 (percent-encoded in the URL). |
Common PostgreSQL connection errors
FATAL: no pg_hba.conf entry for host "10.0.0.7", user "app_user", database "sales", no encryption
Why: The server reached, but no line in pg_hba.conf allows this client, user and database, or the matching line is hostssl and you connected without TLS ("no encryption").
Fix: Connect with sslmode=require or stronger if the server expects TLS, or ask the administrator to add a host/hostssl line for your address and reload the server.
connection to server at "db.example.com" (10.0.0.5), port 5432 failed: Connection refused
Why: Nothing is listening on that address and port: the server is down, listen_addresses only covers localhost, the port is different, or a firewall rejects the connection.
Fix: Check listen_addresses and port in postgresql.conf, the firewall or cloud security group, and whether you need a different port (managed services and poolers often use 6432 or a custom one).
FATAL: password authentication failed for user "app_user"
Why: Wrong password, a role without a password, or a special character in the password that was not percent-encoded in the URI, so the driver read a different password.
Fix: Check the password; in a URI encode @ as %40, : as %3A, / as %2F and % as %25. Paste the URI into the decoder to see exactly which password the driver will send.
server does not support SSL, but SSL was required
Why: The string asks for sslmode=require (or verify-ca / verify-full) and the server has ssl = off.
Fix: Turn TLS on in the server, or connect to the TLS endpoint your provider documents. Do not drop to sslmode=disable across a network you do not control.
root certificate file "/home/app/.postgresql/root.crt" does not exist
Why: sslmode=verify-ca or verify-full needs a CA certificate to check against, and libpq found none at the default path.
Fix: Download your provider's CA bundle and set sslrootcert=/path/to/ca.pem, or on PostgreSQL 16+ clients use sslrootcert=system when the server's certificate comes from a public CA.
FATAL: database "app_user" does not exist
Why: No dbname was given, so libpq used the user name as the database name.
Fix: Add the database to the URI path (/sales) or set dbname=sales.
invalid connection option "sslmod"
Why: libpq rejects the whole string when a keyword is misspelled or belongs to another driver (for example ApplicationName from pgJDBC instead of application_name).
Fix: Fix the spelling. The decoder lists every libpq parameter and marks unknown ones.
PostgreSQL connection string FAQ
What is the PostgreSQL connection string format?
Two forms work with libpq-based drivers: the URI postgresql://user:password@host:5432/dbname?sslmode=verify-full and the keyword/value string host=host port=5432 dbname=dbname user=user sslmode=verify-full. Npgsql uses Host=...;Database=...;Username=... and Java uses jdbc:postgresql://host:5432/dbname.
Which sslmode should I use?
verify-full with sslrootcert pointing at your CA (or system on PostgreSQL 16+). require encrypts but does not check who answered, and prefer, the default, can silently fall back to plain text. Use disable only for a socket or localhost.
How do I escape special characters in a PostgreSQL URI?
Percent-encode them in the user name, password and database: @ is %40, : is %3A, / is %2F, # is %23, ? is %3F, % is %25 and a space is %20. The keyword/value form avoids most of this: wrap the value in single quotes and escape ' and \ with a backslash.
How do I set a statement timeout in the connection string?
With libpq-based drivers add options=-c statement_timeout=30000 (milliseconds; percent-encode it in a URI as options=-c%20statement_timeout%3D30000). Npgsql has Command Timeout, a client-side timeout in seconds.
Can I list several hosts for failover?
Yes. Write postgresql://host1:5432,host2:5432/db or host=host1,host2 port=5432,5432. libpq tries them in order; add target_session_attrs=read-write to skip read-only standbys, or load_balance_hosts=random (PostgreSQL 16+) to spread connections.
Why does node-postgres verify the certificate with sslmode=require?
pg-connection-string currently treats sslmode=prefer, require and verify-ca as verify-full and prints a warning that this will change to the libpq meanings in a future major version. Add uselibpqcompat=true to opt in to libpq behavior now, or configure ssl in the client config instead.
Other engines
Connect once. Then just write SQL.
SQLly is a native SQL workbench for macOS, Windows and Linux. Paste a connection string into its connection editor, keep passwords in your system keychain, and get schema-aware IntelliSense on PostgreSQL and more.