// бесплатный инструмент

Конструктор строки подключения PostgreSQL

Создавайте URI подключения PostgreSQL, строку ключ/значение libpq, строку Npgsql (ADO.NET), JDBC URL и другие форматы в одной форме или вставьте любой из них, чтобы увидеть, что делает каждый параметр и действительно ли sslmode вас защищает. Всё работает в вашем браузере: ничего из того, что вы вводите, никуда не отправляется.

Открыть это подключение в 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.

SQLly — это нативная рабочая среда SQL для macOS, Windows и Linux. Вставьте строку подключения в её редактор подключений, храните пароли в системной связке ключей и получайте IntelliSense с учётом схемы для PostgreSQL и других баз данных.