How I built a custom plugin to add version control to the WordPress database with Dolt

Recently, I discovered a database engine called Dolt, which is essentially a hybrid of MySQL and Git.  It’s a version controlled database.  This blog post is the story of how I discovered Dolt and built a plugin called Branch Manager to add version control to the WordPress database.

Want to see the plugin in action?  I made a video of the plugin in action which you can watch on YouTube.

So, what is Dolt?

Dolt is a drop in replacement for MySQL that enables database-level version control.  With Dolt you can commit changes to your database, create database branches, merge and pull changes and perform so many more Git like operations on your database.  Basically, what Git did for files, Dolt did for databases.

How this project came about

I don’t remember exactly how I found Dolt, but I remember first seeing something about Dolt online around July 2024.  I remember thinking to myself that this has potential.  Over the next few weeks I would continue to casually explore Dolt at a high level, checking out their YouTube Channel and soak up information about Dolt as it had peaked my interest.

Browsing online one day, I came across this empty repository in Dolt’s Github called dolt-wordpress.  This got the wheels in my head turning.  Had someone built a plugin for WordPress to enable version control on the WordPress database?  I thought surely someone must have done this.  I started Googling, seeing if I could find a version control plugin for WordPress powered by Dolt.

I did not find a plugin, however I did find this article by the Dolt team where they did experiment with WordPress and Dolt.  In the article, they install WordPress and use Dolt’s version control to track changes made by WordPress on the database.  While not the most interesting use of WordPress and Dolt, the article did show me one important thing, WordPress can, at least at a surface level, run on Dolt without error.

This got me to thinking, since a plugin for WordPress and Dolt doesn’t exist, could I build one?  For me, the main draw of something like Dolt is the ability to branch database changes.  One of the issues I have on this website is that if I want to make a larger change, such as restructuring a page, my only options are either to 1) make the changes on a local database and then merge the changes back into live manually, overwriting my live database or 2) try and make the changes in live without overwriting anything in live until the changes are all ready to go live.

If I could make my database changes in WordPress in a branch, the same way I do with code changes, that would be a game changer.  I started doing some research, not only into Dolt but also into other projects that would offer me version control within WordPress.  After all, if a good solution already exists, why should I build my own?

The Research

I started looking into WordPress projects that enabled version control for the database.  One project I came across was VersionPress.  VersionPress was a project that aimed to introduce version control to the WordPress database.  However, I was disappointed to see that VersionPress had been recently discontinued.

It turns out, VersionPress works by taking the WordPress database changes and exporting those into a format that can be committed to a standard Git repository.  This results in having to log every database change, output that change to a file, then commit that to a Git repository.  It seems the maintainers of VersionPress thought that this model was unsustainable, as they had abandoned the project and archived their Git repo on July 28, 2024.

Next, I turned to Facebook, asking other developers if they had heard of Dolt and if they had any experience either with Dolt or other database version control for WordPress.  Many developers said they had actually tried to implement their own version of version control for the WordPress database, with one dev saying he spent over a year researching whether a version controlled WordPress database was possible only to realize that the way WordPress saves its data and IDs would create too many conflicts for version control to be a viable option.

Well, I knew from my research that Dolt generates its auto-incrementing IDs not on the individual database branch level, but at the database level as a whole.  So, you can have a change in one branch that adds a new auto-incrementing ID and making a different change in a different branch will ensure that the new change also receives a truly unique auto-incremented ID.  With this knowledge in hand, I saw a challenge.  I was going to build a plugin using Dolt to enable version control within WordPress, or at least give it a try.  I wanted to see if I could do it and thought at least spending a little time tinkering might be beneficial.  Best case I succeed, worst case I waste a week or two coding something that doesn’t work.

Getting Started

The first thing I had to do was actually get WordPress running on Dolt.  One of Dolt’s biggest issues right now is that there isn’t really a readily available way to get Dolt running on commercial hosting.  Your options are basically to either self-host or use Dolt’s hosting, which starts at $50/USD a month.

For local development I like to use the Lando local development environment, so my first step was to see if I could run Dolt using Lando.  Luckily, I came across a blog post by Matthew Daly that showed how to get Dolt running with Lando.  With this knowledge, I could at least get WordPress up and running on a Dolt database and take it for a spin.

Now, at this point my biggest obstacle was probably that I had never used Dolt, like at all.  However, I joined the Dolt Discord where the CEO of Dolt as well as the rest of the Dolt team were excited to hear about my ambitions and were eager to help with all of my Dolt questions.  I couldn’t have built this plugin without the help I got from the Dolt team.

As I started to research the basics of Dolt and what is possible I began to discover that the Dolt team had written a wealth of content about integrating Dolt into different CMS programs and workflows.  For instance, they wrote this blog post where they integrated branches into a Laravel based CMS.  They also had an article where they created a pull request workflow with Dolt in React.  Some of what they posted was over my head, but I could get the gist of the Dolt workflow and start to think about how I could integrate this into WordPress.

Starting to Code

I’m the type of person who likes to jump into things head first.  I knew at a high level what my goal was, enabling the creation and merging of branches inside of WordPress the same way one would branch a Git repository.  Having only a high-level plan, I started to code and experiment.

The first thing I needed was the ability to create a branch and switch to it, without having it affect the live site.  If switching branches for the current user also switched the branch for all users, well, that won’t work so well for a live site.

I managed to find that with Dolt, you can connect to a specific branch by updating your database connection string.  This was my way in.  If I could get WordPress to connect to a different database for only the current user, things would work.

I managed to discover that in WordPress you can select a different database after the plugins_loaded hook is called.  This is the earliest viable hook I could find and I discovered through trial and error that I could set a cookie with a branch name, then switch the branch only for the specific user for the rest of the request.  Perfect!

With this figured out, I started on building an interface to allow users to create a branch, switch to a branch and commit a branch, as well as see any changes at a high level that might be active on a branch.  After a few days, I had this:

Merging Branches

At this point, I had a plugin that could create a new branch and allow a user to switch to it, but it wasn’t going to be much use at all if a user couldn’t merge changes from one branch back into another.

This part of the project is where I struggled the most, as with WordPress there’s a very high chance of data conflicts.  Dolt has a whole article discussing merges and conflicts that was very helpful to me, but there was still so much to figure out.

One of the biggest problems I ran into was that if there is a conflict and you try to resolve it in a different request you lose all your progress.  For instance, if I attempt to do a merge and then load a different page in WordPress to resolve the conflict, the database doesn’t remember that you were trying to merge.

Dolt recommends using a transaction for attempting a merge with a conflict but I couldn’t get that to work within WordPress.  Instead, what I found was that I could attempt the merge on one request, then save the results of the conflicts to a file, then use that file to build a form to allow the user to re-attempt the merge and resolve the conflicts all in a single subsequent request.  Basically, if I did a merge, then had conflicts appear and resolved the conflicts in the same request, everything would work ok.

After much trial and error, I had an interface where I could merge one branch back into another as well as another interface for handling conflicts.  In Dolt, there are three types of conflicts: Data Conflicts, Schema Conflicts and Constraint Violations.

The first type of conflict I ran into was actually a constraint violation.  WordPress had something running in the background that would constantly write to the options table of the database a cache string.  Since the options table enforces not only a unique ID but also a unique identifying string, I would get constant “unique index” constraint violations.

From what I could tell, the best way to handle these was to delete the conflicting data, so I built a screen to allow users to delete each conflicting item when they appear.

The other conflict type I had to handle was data conflicts.  Imagine two people make changes to the same page.  When merging the changes, there will be a conflict and a user will have to choose one version or another.  I built a basic interface to allow users to select whether to keep their changes, or the changes from the other side of the merge.

Via the conflicts resolution interface, users can choose to keep their own changes or the changes from the other side of the merge.  This works very similar to the same option in many Git clients, such as VSCode.

Behind the scenes, to resolve a conflict, data needs to be either deleted or replaced.  If the user keeps their own changes, you can simply clear the appropriate dolt_conflicts database table for the conflicted item and Dolt will know how to update the rest.  If, however, you’re keeping the data from the other side of the merge you need to replace the contents of the database table in your branch with the contents of the table from the other side of the merge.

Dolt makes this somewhat easy with their tables used for conflict resolution and I was able to query this table when doing a merge to ensure that if the user chose the changes from the other side of the merge that the data for the current branch was updated appropriately.

One more note before moving on from conflicts is that I had to store data about what data was conflicted inside of a JSON file on the server.  I originally wanted to store this as an option in the WordPress database, but due to how Dolt rolls back failed conflicts I found this to be difficult, as the change to the options table would not persist beyond the end of the request.

Wrapping Up Development

After getting merging and conflict resolution working, the rest was all downhill.  I worked on a few more interfaces for viewing branches, deleting a branch and viewing a very high level of the commit history for a branch.

What Comes Next

As of right now, I have an initial public beta of my plugin, Branch Manager, out on Github.  If there is interest in the plugin, I may continue development.  There are so many things I can bring to it, including better conflict resolution, the ability for the public to preview a branch, better version history and more.  However, one of the biggest drawbacks is that there isn’t really any hosting that supports Dolt as a database.  Unless you want to roll your own or pay for Dolt’s hosted solution you’re really out of luck.  Unless Dolt can integrate with a big hosting control panel, like CPanel or Enhance, it’s probably going to remain a niche product and not something the average user ever gets a chance to use.

Anyway, if you want to try my plugin you can download it on Github.  It’s free for non-commercial use.  Be sure to follow the installation instructions as it can be a little tricky to get it set up, but it should work well once you are ready to go.  Right now I would call this plugin a beta, meaning it’s probably not a good idea to use it on a production level website.  If you want to be a beta tester and help me improve the plugin, as well as potentially score a free license to use it commercially, reach out.

I would also welcome any feedback or comments you may have about this plugin.  If there’s interest in it, I will certainly pursue making additional updates to it as I think there’s great potential behind it.  You can open an issue on Github or contact me with your feedback.

Until next time.
~ Brandon

P.S. Did you like this article?  You might like to read about how to get started with the Sage 10 theme for WordPress.  Or, you might want to check out our WordPress developer mentorship program where you can learn how to create amazing plugins like this one!