Concepts
SQL Reference
CLI Reference
Architecture
Using Branches
Unlike other relational databases, Dolt has multiple heads, one for each branch in the database. A head can be a branch, a tag, or a working set. Multiple clients can connect to each branch, and will see other writes to the same branch following the normal SQL transactional isolation semantics (REPEATABLE_READ). In effect, each branch functions as its own isolated database instance, with changes only visible to other clients connected to the same branch.
A Dolt database server with multiple heads
A database server has a default branch, which is the checked-out branch at the time the server was started. Each client can choose a specific branch to connect to with their connection string, or change it for their session with various statements.
Specify a branch in the connection string
The exact connection string you need to use will vary depending on your client.
To connect to the default branch, use a connection string with the name of the database only.
mysql://127.0.0.1:3306/mydbTo connect to a different branch, specify that branch name with a slash after the database name:
mysql://127.0.0.1:3306/mydb/feature-branchTo connect to a specific revision of the database, use a commit hash instead of a branch name. The database will be read-only in this case.
mysql://127.0.0.1:3306/mydb/ia1ibijq8hq1llr7u85uivsi5lh3310pThe above options also work with the standard MySQL command line client:
1
mysql --host 127.0.0.1 --port 3306 -u root mydb/feature-branch
Copied!
Switch heads with the USE statement
USE statementFollowing the above connection string examples, you can issue
USE statements to switch your current branch.USE mydb switches to the default branch.To switch to a named branch:
1
USE `mydb/feature-branch`
Copied!
Note that the string must be back-tick quoted, since it contains a
/ character.To switch to a read-only database at a commit hash:
1
USE `mydb/ia1ibijq8hq1llr7u85uivsi5lh3310p`
Copied!
Switch branches with the DOLT_CHECKOUT() function
DOLT_CHECKOUT() functionThe
DOLT_CHECKOUT() SQL function provides identical functionality to the dolt checkout command on the command line, and accepts the same arguments.SELECT DOLT_CHECKOUT('feature-branch'); switches the session to the feature-branch branch. You can also switch to a new branch, like so:1
SELECT DOLT_CHECKOUT('-b', 'new-branch');
Copied!
You can switch to a new branch with a starting commit as well:
1
SELECT DOLT_CHECKOUT('-b', 'new-branch-at-commit', 'ia1ibijq8hq1llr7u85uivsi5lh3310p')
Copied!
Switch branches with a session variable
Each session defines a system variable that controls the current session head. For a database called
mydb as above, this variable will be called @@mydb_head_ref and be set to the current head.1
mydb> select @@mydb_head_ref;
2
+-------------------------+
3
| @@SESSION.mydb_head_ref |
4
+-------------------------+
5
| refs/heads/main |
6
+-------------------------+
Copied!
To switch branches, set this session variable. Use either
refs/heads/branchName or just branchName:1
SET @@mydb_head_ref = 'feature-branch'
Copied!
Notes on switching branches
If you have outstanding changes in your session (because you have issued DML or DDL statements to change the data or schema), you must
COMMIT them or ROLLBACK the transaction before switching branches.Last modified 11d ago