runlot ドキュメント

既存の 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

libpq における sslmode=require は、暗号化だけを行い証明書は検証しないという意味です。証明書も検証する場合は 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	はい	worker 内で `@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 パラメータはフロントですべて削除され、検証済みのロール情報だけが改めて追加されます。クライアントがロールを偽装することはできません。

psql と PostgreSQL プロトコル接続