Dolt is the world's first and only version-controlled SQL database. It gives you the power of a SQL database to quickly and expressively query data, combined with distributed version control features that allow you to branch, fork, merge, diff, and even submit pull requests for your data.

Replicating data is a requirement for many production database systems, and Dolt supports multiple replication protocols. In this post, we show Dolt's support for MySQL's binlog replication protocol, which allows Dolt to be the source or the replica in a replication topology with another MySQL, or MySQL-compatible, database. We're specifically looking at replicating data from a MariaDB source to a Dolt replica. As a bonus, we'll show you how you can use the Dolt replica to see a versioned history of the changes being replicated.

Replication

Database replication is useful for many reasons. Read replicas are commonly used for horizontal scaling, since they allow offloading read-only requests to separate servers. Replication is also needed for fast-failover scenarios where you have a backup server ready to be quickly swapped in for the primary in case the primary fails. Having a stream of changes is also useful for change data capture scenarios, such as auditing or publishing to a data warehouse.

Dolt can be used in several different replication setups to support the scenarios above. Dolt implements two replication protocols. Which one you choose depends on your requirements:

• Dolt Native Replication – This replication protocol was developed for Dolt, and takes advantage of Dolt's ability to track commits at different points on a commit graph, quickly compute diffs, and transfer only the changed content to the replica. This is the same process used when pulling changes from a remote with Git or Dolt. When you're replicating between two Dolt sql-servers, this is the best and most optimized replication protocol to use. It also supports a hot-standby mode if you need a fast failover solution.
• MySQL Binary Log Replication – The binary log replication protocol is native to MySQL. We support this replication protocol for compatibility with MySQL and MySQL-compatible systems. One common way to set this up is to add a Dolt replica to an existing MySQL system so that you can start building a versioned history of changes.

MariaDB

MariaDB is a popular open-source relational database management system (RDBMS) that is MySQL-compatible. MariaDB was created by the original developers of MySQL after concerns over Oracle’s acquisition of the project, and its goal is to maintain compatibility with MySQL while offering improvements in performance, storage engines, and open development practices. MariaDB is widely used in production systems due to its reliability, active community, and support for standard SQL features along with advanced options such as Galera clustering.

Setting up MariaDB to Dolt Replication

Let's walk through a simple example of setting up a new MariaDB server as a replication source, and configuring a Dolt server to replicate the changes from it.

Install MariaDB

The first thing we need to do is get a MariaDB server running. MariaDB is pretty easy to install, but you do need to be careful if you have an existing MySQL installation on your system. MariaDB aims to be a drop-in replacement for MySQL, to the point that it even overwrites MySQL libraries and binaries with binaries of the same name. I was able to get MySQL and MariaDB both installed from Homebrew on my Mac, but I ran into issues using MariaDB with MySQL installed at the same time. Ultimately, I ended up using brew remove to remove MariaDB and the couple of MySQL versions I had installed. After that, when I reinstalled MariaDB, everything worked correctly.

brew install mariadb

At the time of writing this, Homebrew installed MariaDB version 11.7.2.

Note that in this example, we're working with a brand new install of MariaDB. Since there's no data stored in our MariaDB server yet, we won't need to manually import data to the replica before we start replication to get it in sync with the current data in the MariaDB server. If you want to start replication on a MariaDB or MySQL server that has data stored in it already, you'll need to first warm up the replica by importing a dump from the source server using mysqldump.

Configure the MariaDB Source Server

Before we start up MariaDB, let's update our configuration so that we can run MariaDB as a replication source. There are just a few options we need to set.

On my system, using Homebrew for my install, the default configuration file is located at /opt/homebrew/etc/my.cnf. You can use the command below to determine where MariaDB will look for the default configuration on your system:

mysqld --verbose --help | grep -A 1 "Default options"

Note that we're still using a binary named mysqld, even though we're using MariaDB now. MariaDB overwrites the standard MySQL binaries to make it easier to drop-in MariaDB in place of MySQL, but be aware that this approach can cause problems if you have a MySQL install and a MariaDB install on the same host.

My output looks something like:

Default options are read from the following files in the given order:
/opt/homebrew/etc/my.cnf ~/.my.cnf

Go ahead and open an editor for that default configuration file, and make sure you have the following configuration options specified:

[mysqld]
server_id = 123
log_bin=mariadb-bin
binlog_format = ROW
gtid_strict_mode = ON

Here's a quick explanation about what each of these settings does:

• server_id – Every server in a MySQL replication topology must have a unique server_id. We configure the MariaDB server to 123 here and rely on the default of 1 in the Dolt replica.
• log_bin – This turns on binary logging and configures the file name prefix used for naming the binary log files. Note that in MySQL 8.4, binary logging is now enabled by default, but you currently still need to manually turn it on for the latest MariaDB versions.
• binlog_format – Controls how data changes are recorded to the binary log and thus how they are transferred over the wire. Dolt replicas expect the ROW format, which is also the safest format for ensuring accurate data replication.
• gtid_strict_mode – Enabling this option will cause the server to emit errors for additional cases where GTID-based replication may cause inconsistencies on a replica.

If you're familiar with configuring MySQL server settings for replication, you might notice that the enforce_gtid_consistency setting isn't listed. Normally, this is a setting you'd want to enable on a MySQL source server, but MariaDB doesn't include this setting, so we omit it. Instead, we enable gtid_strict_mode for similar GTID consistency checks.

After you update your my.cnf file, it's a good idea to run mysqld --print-defaults to sanity check that the correct options are getting loaded. You should see something like:

% mysqld --print-defaults   
mysqld would have been started with the following arguments:
--server_id=123 --log_bin=mariadb-bin --binlog_format=ROW --gtid_strict_mode=ON 

Those settings match what we configured in our my.cnf, so we're good to start up the server! You can launch the mysqld binary directly, but since I'm using Homebrew, I'll run brew services start mariadb:

% brew services start mariadb
==> Successfully started `mariadb` (label: homebrew.mxcl.mariadb)

Create a Replication User

Now that we've got our MariaDB server up and running and configured to support replication, let's log into the server and create a user account that we'll use to connect from our Dolt replica. By default, our install created a root admin account, but we don't want to use that superuser account for replication, so we'll create a new replicator user that has only the privileges required for replication.

After you've logged into the root account on the MariaDB server using the mysql command line, run the following three commands to create the replicator user:

-- Create a replication user on the MariaDB server
CREATE USER 'replicator'@'localhost' IDENTIFIED BY 'your_password';

-- Grant them access to stream replication events
GRANT REPLICATION SLAVE ON *.* TO 'replicator'@'localhost';

-- Flush privileges will ensure the privilege changes are persisted
FLUSH PRIVILEGES;

Configure the Dolt Replica Server

Our MariaDB server is all set up for replication now, so let's get our Dolt server set up next. If you don't already have the dolt binary on your system, go ahead and install it. If you're using Homebrew, like me, then you can just run brew install dolt.

Next, let's create a directory for our Dolt databases and get dolt sql-server running:

mkdir dolt_dbs && cd dolt_dbs;
dolt sql-server --port 11229 

Note that by default, both MariaDB and Dolt (and MySQL) run on port 3306. Since we've already started MariaDB on port 3306, we've put Dolt on port 11229 instead.

When you start up dolt sql-server, you should see output like this:

Starting server with Config HP="localhost:11229"|T="28800000"|R="false"|L="info"|S="/tmp/mysql.sock"
INFO[0000] Creating root@localhost superuser            
WARN[0000] unix socket set up failed: file already in use: /tmp/mysql.sock 
INFO[0000] Server ready. Accepting connections.         
WARN[0000] secure_file_priv is set to "", which is insecure. 
WARN[0000] Any user with GRANT FILE privileges will be able to read any file which the sql-server process can read. 
WARN[0000] Please consider restarting the server with secure_file_priv set to a safe (or non-existent) directory. 

Now that our Dolt server is running, let's log into a SQL session using mysql and then configure a replication connection to our MariaDB source server.

mysql -uroot --protocol TCP --port 11229 

-- Configure replication on the Dolt server
CHANGE REPLICATION SOURCE TO
  SOURCE_HOST='localhost',
  SOURCE_USER='replicator',
  SOURCE_PASSWORD='your_password',
  SOURCE_AUTO_POSITION=1;

Last, but not least... let's turn on replication:

START REPLICA;

To sanity check that replication is running and that we're connected to the MariaDB source server, we can run the SHOW REPLICA STATUS \G statement. (The \G line ending will cause mysql to display results in a vertical format that is a bit easier to read.) Lots of interesting replica status information is displayed, but we're primarily interested to see the lines for Replica_IO_Running and Replica_SQL_Running. Both of those lines should be Yes as shown below:

...
Replica_IO_Running: Yes
Replica_SQL_Running: Yes
...

If you see that the replica is connected, good job setting up this replication configuration! If instead you see the status says Connecting and doesn't change, then the replica is having problems connecting to the MariaDB source. Double-check the configuration settings for the MariaDB server and the Dolt replica, and look in the output that dolt sql-server is logging to see if any logged errors have clues.

Replicating Data

Now that we've got a replication connection between our MariaDB source and our Dolt replica, let's test it out and replicate some data!

On our MariaDB server, we'll create a database, then create some data in it and go check out if the data was replicated to our Dolt replica.

In a SQL session on the MariaDB source server, run the following statements:

CREATE DATABASE db1;
USE db1;
CREATE TABLE myReplicatedTable(pk int primary key, col1 varchar(255));
INSERT INTO myReplicatedTable VALUES (1, 'uno'), (2, 'dos'), (100, 'cien');
CREATE TABLE mySecondTable(name varchar(100), c1 int, c2 varchar(100));

Now, let's jump over to our SQL session on the Dolt replica server and see if our new database and table have been replicated correctly:

SHOW DATABASES;
+--------------------+
| Database           |
+--------------------+
| db1                |
| information_schema |
| mysql              |
+--------------------+
3 rows in set (0.001 sec)

USE db1;

SHOW TABLES;
+-------------------+
| Tables_in_db1     |
+-------------------+
| myReplicatedTable |
| mySecondTable     |
+-------------------+
2 rows in set (0.000 sec)

SELECT * FROM myReplicatedTable;
+-----+------+
| pk  | col1 |
+-----+------+
|   1 | uno  |
|   2 | dos  |
| 100 | cien |
+-----+------+
3 rows in set (0.000 sec)

Finally, let's take a look at the commits that our Dolt replica has created in our commit graph. When a transaction is replicated from the source to the replica, the replica will automatically create a Dolt commit in the commit graph for each SQL transaction that is replicated. Over time, as the commit history builds up, this gives us a really easy way to view how the data in our replica has changed.

We can view the Dolt commit log for the current branch by querying the dolt_log system table:

SELECT * FROM dolt_log;
+----------------------------------+---------------------+-------------------------------+---------------------+-------------------------------------------+
| commit_hash                      | committer           | email                         | date                | message                                   |
+----------------------------------+---------------------+-------------------------------+---------------------+-------------------------------------------+
| ct2jujbaotvpiu33jd09qk5fig7l1acm | dolt-binlog-applier | dolt-binlog-applier@localhost | 2025-05-22 23:11:51 | Dolt binlog replica commit: GTID 0-123-11 |
| cj7l9i2tsgrfq60dk97ql294i0q99l2r | dolt-binlog-applier | dolt-binlog-applier@localhost | 2025-05-22 23:11:51 | Dolt binlog replica commit: GTID 0-123-10 |
| 8furata71849884gcn7voh4gfipqr7bn | dolt-binlog-applier | dolt-binlog-applier@localhost | 2025-05-22 23:11:51 | Dolt binlog replica commit: GTID 0-123-9  |
| lsp84cohgk7gf2bl69l00gi7q1m2n4uf | Jason Fulghum       | jason@dolthub.com             | 2025-05-22 23:11:51 | Initialize data repository                |
+----------------------------------+---------------------+-------------------------------+---------------------+-------------------------------------------+
4 rows in set (0.002 sec)

The commit log shows us each commit in the commit graph, and we can take those commits and query the data as it looked at those times, create branches from older data, or diff the data to see exactly how each commit changed the database. Here's an example of querying the data diff between two commits using the dolt_diff() table function:

SELECT * FROM dolt_diff('8furata71849884gcn7voh4gfipqr7bn', 'cj7l9i2tsgrfq60dk97ql294i0q99l2r', 'myReplicatedTable');
+-------+---------+----------------------------------+-------------------------+---------+-----------+----------------------------------+-------------------------+-----------+
| to_pk | to_col1 | to_commit                        | to_commit_date          | from_pk | from_col1 | from_commit                      | from_commit_date        | diff_type |
+-------+---------+----------------------------------+-------------------------+---------+-----------+----------------------------------+-------------------------+-----------+
|     1 | uno     | cj7l9i2tsgrfq60dk97ql294i0q99l2r | 2025-05-22 23:11:50.877 |    NULL | NULL      | 8furata71849884gcn7voh4gfipqr7bn | 2025-05-22 23:11:50.865 | added     |
|     2 | dos     | cj7l9i2tsgrfq60dk97ql294i0q99l2r | 2025-05-22 23:11:50.877 |    NULL | NULL      | 8furata71849884gcn7voh4gfipqr7bn | 2025-05-22 23:11:50.865 | added     |
|   100 | cien    | cj7l9i2tsgrfq60dk97ql294i0q99l2r | 2025-05-22 23:11:50.877 |    NULL | NULL      | 8furata71849884gcn7voh4gfipqr7bn | 2025-05-22 23:11:50.865 | added     |
+-------+---------+----------------------------------+-------------------------+---------+-----------+----------------------------------+-------------------------+-----------+
3 rows in set (0.003 sec)

The output above shows the before and after state of all columns in the table we specified (myReplicatedTable) for each row that changed between the two commits we specified. Additionally, each row shows some metadata about the commit that changed that row. You can find many other stored procedures, functions, and system tables to explore a Dolt database's versioned history.

Conclusion

Dolt provides multiple ways to replicate data, including support for the MySQL binlog replication protocol, which lets Dolt act as a source or replica with any other MySQL-compatible database that supports the binlog replication protocol. As we saw with MariaDB, some settings and configuration may vary slightly between MySQL-compatible databases, but the overall process of configuring and starting replication is the same.

If you're curious about data replication, or just want to learn more about Dolt, come join us on Discord, where our dev team and our customers hang out, and we'll be happy to help.