Конструктор строки подключения PostgreSQL
Создавайте URI подключения PostgreSQL, строку ключ/значение libpq, строку Npgsql (ADO.NET), JDBC URL и другие форматы в одной форме или вставьте любой из них, чтобы увидеть, что делает каждый параметр и действительно ли sslmode вас защищает. Всё работает в вашем браузере: ничего из того, что вы вводите, никуда не отправляется.
Открыть это подключение в SQLly
Открывает редактор подключений SQLly с заполненными полями.
Открыть это подключение в SQLly
Приватность на уровне архитектуры. Конструктор и декодер — обычный JavaScript, работающий в этой вкладке. Страница никуда не отправляет то, что вы вводите, ничего не хранит (даже в вашем браузере) и продолжает работать офлайн после загрузки. Ссылка «Открыть в SQLly» ведёт из вашего браузера прямо в приложение на вашем компьютере.
Форматы строки подключения PostgreSQL
Большинство драйверов PostgreSQL основаны на libpq или копируют его правила, поэтому URI postgresql://user:password@host:5432/db?sslmode=verify-full и форма ключ/значение host=... dbname=... работают почти везде: psql, psycopg, pgx, lib/pq, node-postgres. У Npgsql (.NET) и pgJDBC (Java) свои варианты записи.
Самый важный параметр — sslmode. Его значение по умолчанию, prefer, использует TLS, когда сервер его предлагает, но никогда не проверяет сертификат и молча откатывается к открытому тексту. Только verify-full проверяет и цепочку сертификатов, и имя хоста.
URI libpq, psql, psycopg, pgx, node-postgres, Prisma
postgresql://app_user:[email protected]/sales?sslmode=verify-full
Ключевое слово/значение 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 JDBC-драйвер PostgreSQL (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;
URL SQLAlchemy Python SQLAlchemy с psycopg 3
postgresql+psycopg://app_user:[email protected]/sales?sslmode=verify-full
Несколько хостов (резервирование) libpq 10+, pgx, Npgsql, pgJDBC
postgresql://[email protected]:5432,db2.example.com:5432/sales?target_session_attrs=read-write
Заполнители, такие как your_password — это лишь примеры: соберите свою строку в форме выше. Подробнее о подключении SQLly к PostgreSQL: SQLly для PostgreSQL.
Параметры libpq (URI и ключ/значение)
Формат URI: postgresql://[user[:password]@][host][:port][,...][/dbname][?param=value&...] (postgres:// тоже работает); специальные символы, включая слэши в пути Unix-сокета, используемого как хост, нужно кодировать в процентной записи. Формат ключ/значение: key=value пары разделяются пробелами; берите в одинарные кавычки значение, которое пустое или содержит пробелы, и пишите \' и \\ для кавычки или обратной косой черты внутри него.
| Ключевое слово | Синонимы | По умолчанию | Что оно делает |
|---|---|---|---|
host |
- | Unix-сокет в /tmp (localhost в Windows) | Имя хоста, IP или каталог для Unix-сокета. Список через запятую перебирается по порядку. |
hostaddr |
- | - | Числовой IP-адрес без поиска DNS (для проверки TLS по-прежнему используется имя хоста). |
port |
- | 5432 (значение по умолчанию при сборке) | Один порт либо один на каждый хост. |
dbname |
- | Имя пользователя | База данных для подключения. |
user |
- | пользователь операционной системы | Роль, под которой осуществляется подключение. |
password |
- | - | Лучше хранить в ~/.pgpass (или PGPASSWORD), чем в строке. |
passfile |
- | ~/.pgpass (%APPDATA%\postgresql\pgpass.conf на Windows) | Файл пароля. |
connect_timeout |
- | 0 (ждать бесконечно) | Секунды на хост. PostgreSQL 16 и старше считают 1 за 2. |
sslmode |
- | предпочтительно | disable, allow, prefer, require, verify-ca, verify-full. require проверяет CA только если существует файл корневого сертификата; только verify-full проверяет имя хоста. |
sslrootcert |
- | ~/.postgresql/root.crt | Файл CA. system (16+) использует доверенные CA операционной системы и делает verify-full по умолчанию. |
sslcert / sslkey |
- | ~/.postgresql/postgresql.crt / .key | Клиентский сертификат и ключ. |
sslnegotiation |
- | postgres | 17+. direct немедленно запускает TLS (требуется sslmode require или выше). |
application_name |
- | - | Отображается в pg_stat_activity и в журнале сервера. |
options |
- | - | Настройки сервера при запуске, например: -c statement_timeout=30000 -c search_path=app. |
target_session_attrs |
- | любое | any, read-write, read-only, primary, standby, prefer-standby. |
load_balance_hosts |
- | отключить | 16+. random перемешивает список хостов. |
keepalives |
- | 1 | TCP keepalives вкл/выкл; настраивается с помощью keepalives_idle, keepalives_interval, keepalives_count. |
channel_binding |
- | предпочтительно | require отказывается аутентифицироваться без привязки канала SCRAM. |
Параметры Npgsql (ADO.NET)
Npgsql использует ADO.NET Key=Value; синтаксис со своими именами ключевых слов. Оборачивайте значения, содержащие ; в двойные кавычки.
| Ключевое слово | Синонимы | По умолчанию | Что оно делает |
|---|---|---|---|
Host |
Сервер | - (обязательно) | Имя хоста, IP, список через запятую или каталог сокетов, начинающийся с /. |
Port |
- | 5432 | TCP-порт. |
Database |
БД | Имя пользователя | Имя базы данных. |
Username |
Имя пользователя, User Id, UID | PGUSER, иначе пользователь ОС | Имя роли. |
Password |
PSW, PWD | PGPASSWORD | Пароль. |
SSL Mode |
SslMode | Prefer | Disable, Allow, Prefer, Require, VerifyCA, VerifyFull. Начиная с Npgsql 6, Require не проверяет сертификат. |
Trust Server Certificate |
- | ложь | Пропустить проверку. В Npgsql 6 и 7 она требовалась с Require; Npgsql 8 — нет. |
Root Certificate |
- | PGSSLROOTCERT | Файл CA для VerifyCA / VerifyFull. |
Timeout |
- | 15 | Секунды ожидания соединения. |
Command Timeout |
- | 30 | Тайм-аут команды по умолчанию в секундах; 0 — ждать бесконечно. |
Application Name |
- | PGAPPNAME | application_name. |
Search Path |
- | - | Путь поиска по схеме. |
Target Session Attributes |
- | любое | any, primary, standby, prefer-primary, prefer-standby, read-write, read-only. |
Pooling |
- | истина | Пул подключений. |
Maximum Pool Size |
- | 100 | Наибольший пул. |
Minimum Pool Size |
- | 0 | Минимальный пул. |
Keepalive |
- | 0 (выключено) | Секунды между keepalive-запросами. |
Include Error Detail |
- | ложь | Помещает детали ошибки сервера, вплоть до данных строк, в сообщения об исключениях. |
Свойства pgJDBC
Формат URL: jdbc:postgresql://host:port/database?property=value&.... pgJDBC не читает user:password@ в URL: передайте user и password как параметры или свойства соединения.
| Ключевое слово | Синонимы | По умолчанию | Что оно делает |
|---|---|---|---|
user / password |
- | - | Учётные данные. |
sslmode |
- | предпочтительно | Те же значения, что и libpq. require, allow и prefer не проверяют сертификат. |
ssl |
- | ложь | true без sslmode означает verify-full. |
sslrootcert |
- | ~/.postgresql/root.crt | Файл CA. |
connectTimeout |
- | 10 | Секунды ожидания сокета; 0 отключает лимит. |
socketTimeout |
- | 0 | Секунды, на которые может блокироваться чтение; 0 означает бесконечное ожидание. |
loginTimeout |
- | 0 | Секунды ожидания для всего процесса входа. |
ApplicationName |
- | JDBC-драйвер PostgreSQL | application_name. |
currentSchema |
- | - | search_path, через запятую. |
targetServerType |
- | любое | any, primary, secondary, preferPrimary, preferSecondary. |
options |
- | - | Параметры запуска, например -c statement_timeout=30000 (с процентным кодированием в URL). |
Распространённые ошибки подключения к PostgreSQL
FATAL: no pg_hba.conf entry for host "10.0.0.7", user "app_user", database "sales", no encryption
Почему: Соединение с сервером установлено, но ни одна строка в pg_hba.conf не разрешает этому клиенту, пользователю и базе данных, или соответствующая строка hostssl и вы подключились без TLS ("без шифрования").
Исправлено: Подключение с помощью sslmode=require или сильнее, если сервер ожидает TLS, или попросите администратора добавить host/hostssl строку с вашим адресом и перезагрузить сервер.
connection to server at "db.example.com" (10.0.0.5), port 5432 failed: Connection refused
Почему: На этом адресе и порте никто не слушает: сервер не работает, listen_addresses покрывает только localhost, порт другой или брандмауэр отклоняет соединение.
Исправлено: Проверить listen_addresses и port в postgresql.conf, брандмауэре или облачной группе безопасности, и нужен ли вам другой порт (управляемые сервисы и пулеры часто используют 6432 или нестандартный порт).
FATAL: password authentication failed for user "app_user"
Почему: Неправильный пароль, роль без пароля или специальный символ в пароле, не закодированный в URI процентным кодированием, — драйвер прочитал другой пароль.
Исправлено: Проверьте пароль; в URI закодируйте @ как %40, : как %3A, / как %2F и % как %25. Вставьте URI в декодер, чтобы точно увидеть, какой пароль отправит драйвер.
server does not support SSL, but SSL was required
Почему: Строка запрашивает sslmode=require (или verify-ca / verify-full), а на сервере есть ssl = off.
Исправлено: Включите TLS на сервере или подключитесь к TLS-эндпоинту, указанному вашим провайдером. Не переходите на sslmode=disable через сеть, которой вы не управляете.
root certificate file "/home/app/.postgresql/root.crt" does not exist
Почему: sslmode=verify-ca или verify-full нужен сертификат CA для проверки, а libpq не нашёл его по стандартному пути.
Исправлено: Скачайте пакет CA-сертификатов вашего провайдера и задайте sslrootcert=/path/to/ca.pemили для клиентов PostgreSQL 16+ используйте sslrootcert=system когда сертификат сервера выдан публичным CA.
FATAL: database "app_user" does not exist
Почему: Нет dbname был указан, поэтому libpq использовал имя пользователя в качестве имени базы данных.
Исправлено: Добавьте базу данных в путь URI (/sales) или установите dbname=sales.
invalid connection option "sslmod"
Почему: libpq отклоняет всю строку, если ключевое слово написано с ошибкой или принадлежит другому драйверу (например, ApplicationName из pgJDBC вместо application_name).
Исправлено: Исправьте орфографию. Декодер перечисляет все параметры libpq и отмечает неизвестные.
Часто задаваемые вопросы о строке подключения PostgreSQL
Каков формат строки подключения PostgreSQL?
Две формы работают с драйверами на основе libpq: URI postgresql://user:password@host:5432/dbname?sslmode=verify-full и строка ключ/значение host=host port=5432 dbname=dbname user=user sslmode=verify-full. Npgsql использует Host=...;Database=...;Username=... а Java использует jdbc:postgresql://host:5432/dbname.
Какой sslmode мне следует использовать?
verify-full с sslrootcert указывая на ваш CA (или system в PostgreSQL 16+). require шифрует, но не проверяет, кто ответил, и prefer, по умолчанию, может молча откатиться к открытому тексту. Используйте disable только для сокета или localhost.
Как экранировать специальные символы в URI PostgreSQL?
Кодируйте их в имени пользователя, пароле и базе данных с помощью процентного кодирования: @ является %40, : является %3A, / является %2F, # является %23, ? является %3F, % является %25 и пробел это %20. Форма ключевого слова/значения избегает большей части этого: заключите значение в одинарные кавычки и экранируйте ' и \ с помощью обратной косой черты.
Как задать тайм-аут для запроса в строке подключения?
С драйверами на основе libpq добавьте options=-c statement_timeout=30000 (миллисекунды; в URI закодируйте его процентным кодированием как options=-c%20statement_timeout%3D30000). У Npgsql есть Command Timeout, тайм-аут на стороне клиента в секундах.
Могу ли я указать несколько хостов для отказоустойчивости?
Да. Напишите postgresql://host1:5432,host2:5432/db или host=host1,host2 port=5432,5432. libpq пытается подключиться к ним по порядку; добавьте target_session_attrs=read-write чтобы пропускать резервные серверы в режиме только для чтения, или load_balance_hosts=random (PostgreSQL 16+) для распределения соединений.
Почему node-postgres проверяет сертификат при sslmode=require?
pg-connection-string в настоящее время обрабатывает sslmode=prefer, require и verify-ca как verify-full и печатает предупреждение, что в будущей мажорной версии смысл станет как в libpq. Добавьте uselibpqcompat=true чтобы сразу использовать поведение libpq, или настройте ssl вместо этого в конфигурации клиента.
Другие движки
- Строки подключения к SQL Server
- Строки подключения к MySQL
- Строки подключения к MariaDB
- Строки подключения к SQLite
- Строки подключения к Oracle
- Строки подключения Redis
- Строки подключения ClickHouse
- Строки подключения DuckDB
- Строки подключения libSQL
- Все движки и форматы
- Форматировщик SQL
- Все бесплатные инструменты
Подключитесь один раз. А потом просто пишите SQL.
SQLly — это нативная рабочая среда SQL для macOS, Windows и Linux. Вставьте строку подключения в её редактор подключений, храните пароли в системной связке ключей и получайте IntelliSense с учётом схемы для PostgreSQL и других баз данных.