Dolt Configuration
Dolt configuration is a bit of a mess. To start, it's a union of Git and MySQL styles of configuration. Then, Dolt specific configuration is sprinkled on top. It's been on our list for a long time to consolidate and rationalize Dolt configuration with the goal of making it more user friendly. But, that project never bubbles to the top of the stack.
Dolt configuration was not designed up front. It evolved as Dolt evolved. Dolt started as a Git-like command line tool to share data and had to support all the relevant configuration to do so. Later, Dolt became a fully MySQL-compatible database and had to support all the relevant configuration to do that as well.
This article will explain all the different places Dolt configuration lives. If you're having trouble figuring out where something is configured, this article can help.
dolt config
dolt config is Git-style configuration. It is set and retrieved using the git config command line interface (CLI) command. It is generally used by the command line. I'll create a new database called config_blog to show off Dolt's various configuration.
$ mkdir config_blog
$ cd config_blog
$ dolt init --fun
Successfully initialized dolt data repository.
$ dolt config --list
user.email = tim@dolthub.com
user.name = timsehnGlobal configuration, accessed via the --global argument, is stored in your home directory at ~/.dolt/config_global.json. The Dolt README recommends setting your user.name and user.email immediately which I have done. You must set user.name and 'user.email to make Dolt commits via the command line interface.
$ dolt config --global --list
user.email = tim@dolthub.com
user.name = timsehnLocal configuration, accessed via the --local argument, is stored in your database at .dolt/config.json. This should be empty because this is a brand new database.
$ dolt config --local --list
$Local overrides global. Let's set my user.name to configblog for this new database.
$ dolt config --local --set user.name configblog
Config successfully updated.
$ dolt config --local --list
user.name = configblog
$ dolt config --get user.name
configblogValid configuration keys are listed in our Dolt documentation and repeated here:
core.editor- lets you edit 'commit' or 'tag' messages by launching the set editor.creds.add_url- sets the endpoint used to authenticate a client for 'dolt login'.doltlab.insecure- boolean flag used to authenticate a client against DoltLab.init.defaultbranch- allows overriding the default branch name e.g. when initializing a new repository.metrics.disabled- boolean flag disables sending metrics when true.user.creds- sets user keypairs for authenticating with doltremoteapi.user.email- sets name used in the author and committer field of commit objects.user.name- sets email used in the author and committer field of commit objects.remotes.default_host- sets default host for authenticating with doltremoteapi.remotes.default_port- sets default port for authenticating with doltremoteapi.push.autoSetupRemote- if set to "true" assume --set-upstream on default push when no upstream tracking exists for the current branch.
As you can see it's a potpourri of values mostly used by the command line.
If you need to set any of these variables and do not have command line access to the host where you are running Dolt, you must assemble the appropriate JSON file and somehow get it to the proper location on the host you are using. This is sometimes not possible so you have to live with the defaults. To get around this limitation, we could implement dolt config as a SQL procedure. If you hit this problem, please file an issue.
repo_state.json
repo_state.json stores state information about your current checked out branch (ie. HEAD), remotes, and backups. In a fresh Dolt database, it starts with only the HEAD set. This information is meant to be database and version control specific, unlike the configuration stored in config.json.
$ cat .dolt/repo_state.json
{
"head": "refs/heads/main",
"remotes": {},
"backups": {},
"branches": {}
}When you checkout a branch or add a remote, that configuration is stored in repo_state.json. For example, if I add a remote with dolt remote add:, repo_state.json is updated appropriately.
$ dolt remote add origin timsehn/config_blog
$ cat .dolt/repo_state.json
{
"head": "refs/heads/main",
"remotes": {
"origin": {
"name": "origin",
"url": "https://doltremoteapi.dolthub.com/timsehn/config_blog",
"fetch_specs": [
"refs/heads/*:refs/remotes/origin/*"
],
"params": {}
}
},
"backups": {},
"branches": {}config.yaml
Next, we have config.yaml. This file can actually be called anything .yaml but in all of our documentation we refer to it as config.yaml. config.yaml is MySQL-style configuration for dolt sql-server. When you start a MySQL-compatible Dolt server using dolt sql-server, you can pass in a --config=/path/to/config.yaml to have the Dolt SQL server start with the options defined in config.yaml.
A pretty complete example of a config.yaml file with all the default values can be found in the Dolt documentation. The options are also explained in that documentation.
log_level: info
behavior:
read_only: false
autocommit: true
persistence_behavior: load
disable_client_multi_statements: false
dolt_transaction_commit: false
event_scheduler: "ON"
user:
name: ""
password: ""
listener:
host: localhost
port: 3306
max_connections: 100
read_timeout_millis: 28800000
write_timeout_millis: 28800000
tls_key: null
tls_cert: null
require_secure_transport: null
allow_cleartext_passwords: null
performance:
query_parallelism: null
data_dir: .
cfg_dir: .doltcfg
metrics:
labels: {}
host: null
port: -1
remotesapi: {}
privilege_file: .doltcfg/privileges.db
branch_control_file: .doltcfg/branch_control.db
user_session_vars: []
jwks: []So, if you want to change the port to 3500, you make a config.yaml file with the following entry:
listener:
port:3500and then start the dolt sql-server with the --config=config.yaml argument.
$ cat config.yaml
listener:
port: 3500
$ dolt sql-server --config=config.yaml
Starting server with Config HP="localhost:3500"|T="28800000"|R="false"|L="info"|S="/tmp/mysql.sock"As you can see from the start up message, the server is running on port 3500.
Persisted SQL Variables
User session variables can be persisted using the SET PERSIST SQL query. Dolt supports SET PERSIST for all the Dolt system variables and many MySQL system variables.
Persisted session variables are stored in config.json, the same place as configuration defined using the dolt config command line operation. Confusing right?
$ dolt sql -q "SET PERSIST dolt_show_system_tables = 1;"
$ cat .dolt/config.json
{"sqlserver.global.dolt_show_system_tables":"1","user.name":"configblog"}The dolt_show_system_table system variable tells show tables to show Dolt system tables.
$ dolt sql -q "show tables"
+----------------------------+
| Tables_in_config_blog |
+----------------------------+
| dolt_branches |
| dolt_commit_ancestors |
| dolt_commits |
| dolt_conflicts |
| dolt_constraint_violations |
| dolt_log |
| dolt_remote_branches |
| dolt_remotes |
| dolt_status |
+----------------------------+As you can see the system variable is persisted across sessions as each command line invocation is a different session.
Session variables for individual users can also be set using config.yaml using the user_session_vars map. Again. Confusing right?
.doltcfg directory
Finally, we get to .doltcfg. This directory can be found at .dolt/.doltcfg after you configure users and grants or branch permissions. This is shown off in this anatomy of a Dolt database article. I won't go into more detail here.
Conclusion
Because Dolt evolved from a Git-style command line tool into a fully-compatible MySQL server, configuring Dolt is kind of messy. It's not always clear where to set a configuration variable or find the value of one that is set. We'll get around to fixing that eventually. Suggestions on how to make it better? Come by our Discord and let us know.