Dolt System Variables

Dolt System Variables

Dolt exposes various information about the state of the current session. This information is typically only useful for advanced users. See information on Detached Head mode.

@@dbname_head_ref

Each session defines a system variable that controls the current session head. For a database called mydb, 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/master |
6
+-------------------------+
Copied!
To switch heads, set this session variable. Use either refs/heads/branchName or just branchName:
SET @@mydb_head_ref = 'feature-branch'

@@dbname_head

This system variable controls the current session's head commit. Setting this variable to a commit hash causes your session to enter detached head mode.
See Detached Head mode for more detail.

@@dbname_working

This system variable controls the current working root value. Setting it is an expert use case that can have very many unexpected consequences. Selecting it is useful for diagnostics.

@@dbname_staged

This system variable controls the current staged root value. Setting it is an expert use case that can have very many unexpected consequences. Selecting it is useful for diagnostics.

@@dolt_default_branch

This system variable toggles the default database branch on server (or SQL engine) instantiation. Setting this changes the active branch and working set new server sessions connect to.

@@dolt_replicate_to_remote

This system variable is used to push to replication middlemen. Dolt commit triggers a push and transmits the resulting dataset to the named remote. SQL commits do not trigger replication.
1
mysql> select name from dolt_remotes;
2
+---------+
3
| name |
4
+---------+
5
| remote1 |
6
| origin |
7
+---------+
8
mysql> SET @@GLOBAL.dolt_replicate_to_remote remote1;
9
mysql> select dolt_commit('-am', 'push on write');
Copied!

@@dolt_read_replica_remote

This system variable is used to pull updates to read replicas. Pulling is triggered on SQL START TRANSACTION. Setting autocommit = 1 will wrap every query in a transaction.
Setting dolt_replicate_heads or dolt_replicate_all_heads is required.
1
mysql> SET @@GLOBAL.dolt_read_replica_remote = origin;
2
mysql> SET @@GLOBAL.dolt_replicate_heads main;
3
mysql> START TRANSACTION;
Copied!

@@dolt_skip_replication_errors

This system variable is used to quiet replication errors that would otherwise halt query execution. Missing or malformed configuration is the main target of replication warnings. Faults unrelated to replication should still error.
1
mysql> SET @@GLOBAL.dolt_skip_replication_errors = 1;
Copied!

@@dolt_replicate_heads

This system variable specifies which heads a read replica should fetch. Pair with dolt_read_replica_remote. Use is mutually exclusive with dolt_replicate_all_heads.
1
mysql> SET @@GLOBAL.dolt_replicate_heads main;
2
mysql> SET @@GLOBAL.dolt_replicate_heads main,feature1,feature2;
Copied!

@@dolt_replicate_all_heads

This system variable indicates to pull all branches for every read replica fetch. Pair with dolt_read_replica_remote. Use is mutually exclusive with dolt_replicate_heads.
1
mysql> SET @@GLOBAL.dolt_replicate_all_heads = 1;
Copied!

Persisting System Variables

Dolt supports a limited form of system variable persistence. The same way session variables can be changed with SET, global variables can be persisted to disk with SET PERSIST. Persisted system variables survive restarts, loading back into the global variables namespace on startup.
Dolt supports SET PERSIST and SET PERSIST_ONLY by writing system variables to the local .dolt/config.json. The same result can be achieved with the CLI by appending sqlserver.global. prefix to keys with the dolt config add --local command. System variables are used as session variables, and the SQL interface is the encouraged access point. Variables that affect server startup, like replication, must be set before instantiation.

Examples

SET PERSIST

1
SET PERSIST max_connections = 1000;
2
SET @@PERSIST.max_connections = 1000;
Copied!

SET PERSIST_ONLY

1
SET PERSIST_ONLY back_log = 1000;
2
SET @@PERSIST_ONLY.back_log = 1000;
Copied!

CLI

1
$ dolt config --local --add sqlserver.global.max_connections 1000
Copied!

Limitations

  1. 1.
    Deleting variables with RESET PERSIST is not supported.
  2. 2.
    Persistence in multi-db mode is not supported.
  3. 3.
    Loading variables from the Dolt global config on server startup is not supported.
Last modified 1mo ago