psql과 PostgreSQL 프로토콜 연결

기존 PostgreSQL 도구로 데이터베이스에 연결합니다. 로그인 세션을 사용하거나 시스템용 자격 증명을 발급할 수 있습니다.

가장 빠른 방법

runlot pg shell

이 명령은 psql을 찾아 데이터베이스에 연결합니다. -- 뒤에 입력한 인수는 psql에 그대로 전달됩니다.

runlot pg shell -- -c "select count(*) from posts"

비밀번호는 PGPASSWORD 환경 변수로 전달합니다. 명령행 인수는 같은 머신의 다른 사용자가 ps로 확인할 수 있기 때문입니다.

로컬 포트로 연결하기

GUI 클라이언트나 다른 도구를 사용하려면 포트 포워딩이 편리합니다.

runlot port-forward

Forwarding 127.0.0.1:15432 to the me/my-app database.
Connect with psql "postgresql://…@127.0.0.1:15432/…". Press Ctrl-C to stop.

runlot port-forward --port 5555 --listen 127.0.0.1
runlot port-forward --port 0      # picks an available port automatically

비밀번호는 로컬 컴퓨터로 내려오지 않습니다. 포트 포워딩은 runlot login 세션을 사용합니다. CLI는 연결 정보(호스트, 포트, 데이터베이스 이름)만 받고 인증은 앞단에서 로그인 세션으로 처리합니다. 토큰이 만료되거나 조직에서 제외되면 다음 연결부터 거절됩니다.

외부에서 직접 연결하기

외부 BI 도구 또는 다른 호스팅 환경의 앱처럼 runlot login을 사용할 수 없는 곳에서는 pg 토큰으로 자격 증명을 발급하세요.

postgresql://<user>:<password>@<project>--<org>.wire.runlot.app:5433/<database>?sslmode=require

포트 번호는 5433입니다. 호스트 이름에는 프로젝트와 조직이 --로 이어져 있습니다. 프런트는 자격 증명을 받기 전에 이 이름으로 어느 프로젝트의 데이터베이스를 열지 정합니다. 정확한 값은 runlot pg connect가 보여 줍니다.

TLS

sslmode=require는 libpq에서 암호화만 사용하고 인증서를 검증하지 않는다는 뜻입니다. 인증서도 검증하려면 CA 디렉터리를 지정하세요.

runlot pg shell --ca-dir ./ca      # or RUNLOT_CA_DIR

SNI는 인증서 검증 여부와 관계없이 항상 필요합니다. 앞단이 SNI로 대상 프로젝트를 정하므로 SNI를 끄면 연결할 수 없습니다.

드라이버 호환성

바이너리 결과는 지원됩니다. 바이너리 매개변수는 지원되지 않습니다. 매개변수를 바이너리로 표시하는 Bind는 0A000 binary parameter format is not supported로 거부됩니다. 이 한 줄이 어떤 드라이버가 그대로 동작하는지를 결정합니다.

드라이버	동작 여부	알아둘 점
`psql`	예	항상 텍스트입니다. 설정할 것이 없습니다.
node-postgres (`pg`)	예	모든 매개변수를 텍스트로 전송하므로 매개변수화된 쿼리에 문제가 없습니다.
Drizzle · Kysely · Prisma · TypeORM · Knex · Sequelize	예	워커 내부에서 `@runlot/pg`를 통해 사용합니다 — 와이어 프로토콜을 거치지 않습니다.
psycopg 3	부분적으로	매개변수가 없는 쿼리와 텍스트 매개변수는 동작합니다. Python `int`는 바이너리 매개변수로 덤프되므로 `cur.execute("… %s", (7,))`는 거부됩니다. `cursor(binary=False)`는 도움이 되지 않습니다 — 이 옵션은 결과에 관한 것입니다. 클라이언트 측에서 바인딩하려면 `cursor_factory=ClientCursor`를 전달하세요.
pgx · Npgsql · JDBC · asyncpg	부분적으로	이들은 바이너리 결과를 읽는데, 이제 이 부분은 동작하므로 매개변수가 없는 쿼리는 성공합니다. 타입이 지정된 매개변수를 바이너리로 전송하는 부분은 거부됩니다.

이 표의 모든 행은 psql, node-postgres, psycopg 3 를 각각 별도 프로세스로 띄워 실제 데이터베이스에 대고 확인한 것입니다.

바이너리 매개변수 지원은 로드맵에 있습니다. 그때까지는 위의 방법 중 하나로 매개변수를 텍스트로 보내세요.

인증 방식

앞단은 SNI로 프로젝트를 식별한 뒤 연결 시작 직후 인증을 완료합니다. 사용할 수 있는 자격 증명은 다음과 같습니다.

대상	자격 증명	사용 위치
사용자	`runlot login` 세션	`runlot port-forward`, 대시보드 SQL 편집기
시스템	연결 문자열의 비밀번호	외부 BI 도구, 다른 호스팅 환경의 앱

클라이언트가 보낸 runlot_* startup 파라미터는 앞단에서 모두 제거하고, 확인된 역할 정보만 다시 추가합니다. 클라이언트가 역할을 위조할 수 없습니다.