Branch への接続

Branch への接続方法は 3 つあります。

方法	接続先	Branch の選び方
直接接続	Branch が動いているノードの、Branch 専用のポート	接続先のポートで決まる
ProxySQL 経由・ユーザー名	どのノードでもよい（MySQL 6033 / PostgreSQL 6133）	接続するユーザー名
ProxySQL 経由・クエリのコメント	どのノードでもよい（MySQL 6033 / PostgreSQL 6133）	クエリに付けたコメント

直接接続

Branch は、いずれか 1 つのノードで動くデータベースサーバーです。db-branch branch show <name> で表示されるホスト、ポート、ユーザーを指定して接続します。パスワード付きの接続 URL は、次のコマンドで確認できます。

db-branch branch dsn feature-x

REST API では、同じ情報が connection（host、port、user、database）として返されます。

ProxySQL 経由の接続

各ノードでは、無料の db-branch-proxysql モジュールにより ProxySQL 3.x が動いています。どのノードの ProxySQL に接続しても、クラスター内のすべての Branch にアクセスできるため、アプリは Branch がどのノードにあるかを知る必要がありません。

• 接続先: どのノードでもよい
• ポート: MySQL は 6033、PostgreSQL は 6133（どちらのエンジンも同じ仕組みで振り分けます）

ProxySQL 経由で Branch を選ぶ方法は、次の 2 つです。

ProxySQL 経由：ユーザー名で Branch を選ぶ

Branch ごとに、Branch と同じ名前の専用ユーザーが作られます（例: feature-x）。ProxySQL のポートに、そのユーザー名で接続すると、その Branch に振り分けられます。アプリ側は、接続文字列のユーザー名を変えるだけで済みます。

mysql://feature-x:<password>@node1:6033/app
postgresql://feature-x:<password>@node1:6133/app

ProxySQL 経由：クエリのコメントで Branch を選ぶ

ProxySQL のポートに、すべての Branch で共通のユーザーで接続し、クエリに sqlcommenter 形式のコメントで Branch 名を書きます。ProxySQL がコメントを読み取り、その Branch に振り分けます。

SELECT * FROM users WHERE id = 1 /*db_branch='feature-x'*/;

ミドルウェアで HTTP ヘッダー（例: X-DB-Branch）を読み取って各クエリにこのコメントを付ければ、1 つの接続設定のまま、リクエストごとに Branch を切り替えられます。

共通ユーザーは、コメントがないときに使う既定の Branch を指定して追加します（パスワードは標準入力から渡します）。

db-branch route user add app --default main < pw.txt

存在しない Branch をコメントで指定すると、db-branch: the db_branch comment names no branch というエラーが返ります。

ProxySQL 経由の注意点

• 振り分けは、コメント、ユーザー名、共通ユーザーの既定の Branch の順に優先されます。
• トランザクションの途中で Branch が切り替わることはありません。
• mysql コマンドラインクライアントは、-c を付けて起動しないとコメントを削除します。
• 共通ユーザーは、コメントでどの Branch にも接続できます。コメントによる振り分けを無効にするには、proxysql モジュールの設定 comment_routing を false にします。無効にすると、接続は各ユーザーの Branch にだけ振り分けられます。

db-branch settings set proxysql comment_routing=false