【実務・中級編】pgAdmin 4のSSHトンネル（Port Forwarding）接続で「Network Error」が出る時の原因とファイアウォール越えの設定手順 – データベース・API管理活用バイブル

pgAdmin 4のSSHトンネル地獄からの脱出：Network Errorを完全鎮圧し、開発速度を限界突破させるプロの技術

テックリードの私たちが新しいプロジェクトに参入した際、最も不毛でエンジニアリングの魂を削られる瞬間の一つが「データベースへの接続確立」ではないだろうか。

特に、セキュアな本番・ステージング環境へ踏み台サーバー（SSH）経由でアクセスする際、pgAdmin 4のGUI画面に無慈悲に表示される `Network Error`。このエラーメッセージほど、開発の手を止める無能な存在はない。エラーログを見ても「connection failed」や「timeout」の文字が並ぶだけで、何が原因でパケットがドロップしているのか即座に判断するのは難しい。

今回は、pgAdmin 4のビルトインSSHトンネル機能の裏側で何が起きているのかを解剖し、この「Network Error」を根絶するための極限の知見を授ける。さらに、日々の開発スピードを劇的に高めるショートカット、設定のチーム共有化ルールまで、実務に直結するノウハウを余すところなく解説しよう。

—

1. なぜpgAdminのSSHトンネルは「Network Error」を吐くのか？（真の原因特定）

pgAdmin 4のSSHトンネル機能は、PythonのParamikoライブラリをベースに実装されている。ブラウザ（UI）からリクエストを受け取ったバックエンド（サーバーモードまたはデスクトップモードのPythonプロセス）が、指定された踏み台サーバーへSSH接続を確立し、そこでポートフォワーディングを行う仕組みだ。

ここで「Network Error」が発生する場合、原因は大きく3つに集約される。

1. 秘密鍵（Private Key）のフォーマット・パーミッション違反（Paramikoの仕様による厳格な拒絶）
2. SSHエージェントやパスフレーズの不整合
3. TCPキープアライブ（KeepAlive）の欠如による静寂な切断

特に、Docker環境やLinux/macOS上でpgAdminを動かしている場合、SSH秘密鍵のパーミッションが緩すぎると、Paramikoはセキュリティ上の理由からエラーメッセージもロクに出さずに接続を即座に切断する。これが「Network Error」の正体だ。

—

2. 秘密鍵のパーミッションエラー対策と鍵認証の極意

SSH鍵認証において、クライアント側（pgAdmin側）が用意する秘密鍵の設定はシビアを極める。

鉄則：パーミッションは `600` または `400`

LinuxやmacOSでホストされているpgAdmin、あるいはDockerコンテナ内にマウントされた秘密鍵は、所有者以外の読み取り権限（Group/Otherの読み取り権限）が少しでも残っていると失敗する。

ターミナルで必ず実行すべきパーミッションの厳格化
chmod 600 ~/.ssh/id_ed25519
または
chmod 400 ~/.ssh/id_rsa

パスフレーズ付き秘密鍵の罠

pgAdmin 4のGUIでSSHトンネルを設定する際、「Password / Passphrase」欄に何を入力すべきか迷うエンジニアが多い。

SSH鍵にパスフレーズがかかっている場合: そのパスフレーズを入力する。
SSH鍵にパスフレーズがない場合: 空欄にする。

もしここでパスフレーズの入力を間違えても、pgAdminは親切に「Passphrase invalid」とは言わず、冷酷に `Network Error` を返すことがある。あらかじめローカルのターミナルで `ssh -i ~/.ssh/id_ed25519 user@bastion-host` がパスワードなし（またはパスフレーズ入力のみ）で通ることを必ず確認してからpgAdminに設定すべし。

—

3. タイムアウトを完全回避する「KeepAlive」設定

踏み台サーバー経由で重いクエリを実行していたり、少し席を外して戻ってきたとき、突然クエリが固まり、再度操作しようとすると `Network Error` になる現象に悩まされたことはないか？

これは、ルーターやファイアウォール、あるいはSSHサーバー自体のアイドルタイムアウト（`ClientAliveInterval`）によって、無通信状態のTCPコネクションがサイレント切断されることが原因である。

pgAdmin 4のGUI上には、残念ながら隠された高度なSSH KeepAlive設定項目が少ない。これを根本から解決するには、ローカル環境のSSH設定ファイル（`~/.ssh/config`）にあらかじめ踏み台サーバーのプロ定義を行い、pgAdmin側からはそのエイリアスを叩く、あるいはParamikoの挙動を前提とした接続設計に落とし込むのがプロの常道だ。

ベストプラクティス：`~/.ssh/config` の最適化

pgAdminを設定する前に、まずはローカルのSSHクライアント設定を固める。

~/.ssh/config のベストプラクティス構成例
Host production-bastion
HostName bastion.example.com
Port 22
User ec2-user
IdentityFile ~/.ssh/id_ed25519
# ファイアウォール越えの切断を防ぐための死活監視設定
ServerAliveInterval 60
ServerAliveCountMax 3
# TCPコネクションの維持
TCPKeepAlive yes

この設定を行った上で、pgAdminのSSHトンネル設定には以下のように入力する。

Tunnel Host: `bastion.example.com` （または `production-bastion` を直接引けない場合はIP）
Tunnel Port: `22`
Username: `ec2-user`
Identity file: `~/.ssh/id_ed25519`

—

4. チーム開発で爆速を産む！pgAdmin設定の共有化ルールとJSONベストプラクティス

属人化したデータベース接続情報はチームの生産性を殺す最大の癌である。「あの人のPCでは繋がるのに、私の環境ではNetwork Errorが出る」という不毛な会話を根絶するため、pgAdminの接続設定はコードとして管理し、共有すべきだ。

pgAdmin 4は、接続情報をJSON形式（Servers.json）でエクスポート・インポートする機能を持っている。これをバージョン管理（Git）に組み込むことで、チーム全員が全く同じセキュアな接続基盤を即座に構築できる。

実用的な `servers.json` ベストプラクティス構成例

パスワードや秘密鍵の絶対パスは環境によって異なるため、プレースホルダーを活用するか、共通のディレクトリ構造をチーム内で規定する。

{
“Servers”: {
“1”: {
“Name”: “🚀 [PROD] 本番データベース (SSH経由)”,
“Group”: “Production”,
“Host”: “10.0.1.100”,
“Port”: 5432,
“MaintenanceDB”: “postgres”,
“Username”: “app_admin”,
“PassSave”: 1,
“UseSSHTunnel”: 1,
“TunnelHost”: “bastion.example.com”,
“TunnelPort”: 22,
“TunnelUsername”: “ec2-user”,
“TunnelAuthentication”: 1,
“TunnelIdentityFile”: “/path/to/your/home/.ssh/id_ed25519”,
“TunnelPassword”: “”,
“ConnectionTimeout”: 10,
“Color”: “#E74C3C”
},
“2”: {
“Name”: “🧪 [STG] ステージングデータベース”,
“Group”: “Staging”,
“Host”: “10.0.2.100”,
“Port”: 5432,
“MaintenanceDB”: “postgres”,
“Username”: “stg_admin”,
“PassSave”: 1,
“UseSSHTunnel”: 1,
“TunnelHost”: “bastion-stg.example.com”,
“TunnelPort”: 22,
“TunnelUsername”: “ec2-user”,
“TunnelAuthentication”: 1,
“TunnelIdentityFile”: “/path/to/your/home/.ssh/id_ed25519”,
“Color”: “#F39C12”
}
}
}

> 💡 テックリードからの運用ルール:
> `servers.json` をチームで共有する際は、機密情報（平文パスワードなど）が含まれていないことを確認し、リポジトリにはテンプレート（`servers.json.sample`）として配置する。各エンジニアはそれをローカルの `servers.json` にリネームしてインポートするフローを徹底しよう。また、UI上のタブカラー（`Color` プロパティ）を本番は赤、ステージングはオレンジに強制することで、「本番環境への誤爆（破壊的クエリの実行）」を視覚的に防ぐ。これも極めて重要なリスク管理である。

—

5. 開発スピードを劇的に高める隠れたキーボードショートカット

最後に、DBクライアントとしてのpgAdminの戦闘力を極限まで高める、知られざるキーボードショートカットを紹介する。マウス操作を排除し、指をホームポジションに置いたままクエリの奔流をコントロールしろ。

—

結びにかえて

「Network Error」という無機質なエラーは、ネットワークの機嫌が悪いわけでも、pgAdminのバグでもない。多くの場合、私たちエンジニアが「セキュリティの厳格な要件」と「クライアントツールの仕様」の間にある境界線を正しく理解しきれていないことに起因する。

パーミッションを整え、SSHトンネルの背後にあるTCPの挙動を掌握し、設定をコードとしてチームで共有する。この一連のエンジニアリングを完遂したとき、あなたの開発環境から無駄なストレスは消え去り、純粋に「良いコードを書き、データを操る快感」だけが残るはずだ。

さあ、今すぐ設定を見直し、秒速でデータベースへ接続を完了させよう。