PostgreSQL 연결 문자열 생성기
하나의 폼에서 PostgreSQL 연결 URI, libpq 키워드/값 문자열, Npgsql (ADO.NET) 문자열, JDBC URL 등을 생성하거나, 이들 중 하나를 붙여넣어 각 매개변수가 무엇을 의미하는지와 sslmode가 실제로 보호하는지 확인할 수 있습니다. 모든 처리는 브라우저에서 이뤄집니다: 입력한 내용은 어디로도 전송되지 않습니다.
이 연결을 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 PostgreSQL JDBC 드라이버(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와 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에 연결하는 방법 더 알아보기: PostgreSQL용 SQLly.
libpq 매개변수(URI와 키워드/값)
URI 형식: postgresql://[user[:password]@][host][:port][,...][/dbname][?param=value&...] (postgres:// 이것도 작동합니다); 호스트로 사용하는 Unix 소켓 경로의 슬래시를 포함한 특수 문자는 퍼센트 인코딩하세요. 키워드/값 형식: key=value 쌍을 공백으로 구분합니다. 비어 있거나 공백을 담은 값은 작은따옴표로 묶고, 다음과 같이 적습니다 \' 그리고 \\ 값 안의 따옴표나 백슬래시를 표현할 때 씁니다.
| 키워드 | 동의어 | 기본값 | 기능 |
|---|---|---|---|
host |
- | /tmp의 Unix 소켓 (Windows에서는 localhost) | 호스트 이름, IP 또는 Unix 소켓용 디렉터리. 쉼표로 구분된 목록이 순서대로 시도됩니다. |
hostaddr |
- | - | 숫자 IP로 접속하여 DNS를 건너뜁니다(호스트는 여전히 TLS 검사에 사용됩니다). |
port |
- | 5432 (빌드 기본값) | 포트 하나, 또는 호스트마다 하나씩. |
dbname |
- | 사용자 이름 | 연결할 데이터베이스. |
user |
- | 운영체제 사용자 | 연결에 사용할 역할. |
password |
- | - | 문자열에 직접 넣기보다는 ~/.pgpass (또는 PGPASSWORD) 문자열에 담아 두는 것보다 낫습니다. |
passfile |
- | ~/.pgpass (Windows에서는 %APPDATA%\postgresql\pgpass.conf) | 비밀번호 파일. |
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 | any, read-write, read-only, primary, standby, prefer-standby. |
load_balance_hosts |
- | disable | 16+. random 호스트 목록을 섞습니다. |
keepalives |
- | 1 | TCP keepalive 켜기/끄기; 조정은 다음으로 keepalives_idle, keepalives_interval, keepalives_count. |
channel_binding |
- | 선호 | require SCRAM 채널 바인딩 없이는 인증을 거부합니다. |
Npgsql (ADO.NET) 매개변수
Npgsql은 ADO.NET Key=Value; 고유한 키워드 이름을 지닌 자체 구문을 씁니다. 다음이 들어간 값은 ; 큰따옴표로 묶습니다.
| 키워드 | 동의어 | 기본값 | 기능 |
|---|---|---|---|
Host |
서버 | - (필수) | 호스트 이름, IP, 쉼표로 구분된 목록 또는 다음으로 시작하는 소켓 디렉터리 /. |
Port |
- | 5432 | TCP 포트. |
Database |
DB | 사용자 이름 | 데이터베이스 이름. |
Username |
사용자 이름, 사용자 ID, UID | PGUSER, 그렇지 않으면 OS 사용자 | 역할 이름. |
Password |
PSW, PWD | PGPASSWORD | 비밀번호. |
SSL Mode |
SslMode | 더 편한 것은 | Disable, Allow, Prefer, Require, VerifyCA, VerifyFull. Npgsql 6 이후, Require 인증서를 검증하지 않습니다. |
Trust Server Certificate |
- | 거짓 | 검증 건너뛰기. Npgsql 6과 7에서는 Require; Npgsql 8에서는 그렇지 않습니다. |
Root Certificate |
- | PGSSLROOTCERT | VerifyCA / VerifyFull용 CA 파일. |
Timeout |
- | 15 | 연결 대기 시간(초). |
Command Timeout |
- | 30 | 기본 명령 시간 초과(초 단위); 0이면 무한 대기. |
Application Name |
- | PGAPPNAME | application_name. |
Search Path |
- | - | 스키마 검색 경로. |
Target Session Attributes |
- | any | 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 |
- | PostgreSQL JDBC 드라이버 | application_name. |
currentSchema |
- | - | search_path, 쉼표로 구분. |
targetServerType |
- | any | 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에서는 다음과 같이 인코딩합니다 @ as %40, : as %3A, / as %2F 그리고 % as %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 대신) application_name).
해결: 철자를 수정하세요. 디코더는 모든 libpq 매개변수를 나열하고 모르는 매개변수는 알 수 없음으로 표시합니다.
PostgreSQL 연결 문자열 FAQ
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 전용입니다.
PostgreSQL URI에서 특수 문자를 어떻게 이스케이프하나요?
사용자 이름, 비밀번호, 데이터베이스에서는 퍼센트 인코딩하세요: @ 입니다 %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 as verify-full 그리고 향후 주요 버전에서 libpq 의미로 바뀔 것이라는 경고를 출력합니다. 다음을 추가하세요 uselibpqcompat=true 를 지정해 지금 libpq 방식을 따르거나, 다음을 구성하세요 ssl 대신 클라이언트 설정에서.
한 번 연결하세요. 그 뒤는 그냥 SQL만 쓰면 됩니다.
SQLly는 macOS, Windows, Linux용 네이티브 SQL 워크벤치입니다. 연결 편집기에 연결 문자열을 붙여넣고, 비밀번호는 시스템 키체인에 보관하고, PostgreSQL 등에서 스키마 인식 IntelliSense를 사용할 수 있습니다.