Connecting to a branch

There are two ways to reach a branch: directly, or through ProxySQL.

Direct

Each branch is a database server on one node. Use the host, port and user shown by db-branch branch show <name>, or print a URL with the password:

db-branch branch dsn feature-x

The REST API returns the same data as connection (host, port, user, database).

Through ProxySQL

Every node runs ProxySQL 3.x, installed as the free db-branch-proxysql module. Connecting to any node reaches every branch in the cluster. Client ports are 6033 for MySQL and 6133 for PostgreSQL. Both engines use the same rules.

By user name

Each branch gets its own user, named after the branch (for example feature-x). The application changes only the user in its connection string:

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

By query comment

Put the branch name in a comment, in sqlcommenter style:

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

A middleware can add this comment to each query from an HTTP header (for example X-DB-Branch), which switches branches per request.

This works with a user shared by every branch. Add one with a default branch (the password is read from stdin):

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

A comment that names no known branch is rejected with db-branch: the db_branch comment names no branch.

Rules

• Priority: comment, then user name, then the user’s default branch.
• A transaction never switches branch midway.
• The mysql command-line client strips comments unless you start it with -c.
• A shared user can reach any branch with a comment. To turn comment routing off, set comment_routing to false in the proxysql module settings. Connections then reach only their user’s branch:

db-branch settings set proxysql comment_routing=false