Library / SDK
go-mysql-org/go-mysql avatar
go-mysql-org/go-mysql

go-mysql-org/go-mysql: a pure Go library for the MySQL protocol and binlog replication

a powerful mysql toolset with Go

4,976 stars1,101 forksGoMIT

At a glance

What is it?
go-mysql is a Go library that speaks the MySQL wire protocol and consumes the binlog, plus a set of example binaries built from the cmd directory. It is aimed at engineers who need replication streams, a fake server or a dump tool inside their own Go program, not at teams looking for a drop-in ORM.
Who is it for?
Adopt go-mysql if you are writing Go and need to read a binlog stream, run a fake MySQL server for tests, or embed a MySQL client without cgo. Do not adopt it if you want an ORM or a query builder; the repository is a protocol and replication library, and the database/sql driver it ships is one component among several.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • go-mysql-org/go-mysql4,976 ★ · +7
Star history
Repository2026-09-232026-11-15
go-mysql-org/go-mysql5k5k

7 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What go-mysql actually replaces in a Go stack

The README describes go-mysql as "a pure Go library to handle MySQL network protocol and replication as used by MySQL and MariaDB". That sentence is the scope. It is not a full ORM and it is not a database server. It is the layer underneath: the packet encoding, the client handshake, the server side of the same protocol, and the binlog parser and streamer.

The audience is narrower than the description suggests. If you are writing a Go service that reacts to row changes in MySQL, the replication package is the reason to look here. If you are writing a test suite that needs a MySQL endpoint without starting a real server, the server package is the reason. If you want to move data out of MySQL into Redis or Elasticsearch, the canal package is the documented path. If you want to write `SELECT * FROM users WHERE id = ?` and have it map into a struct, this is the wrong project, and the README points you at its own database/sql driver rather than at an ORM.

The repository layout matches that framing. The top level contains canal/, client/, cmd/, compress/, driver/, dump/, mysql/, packet/, replication/, schema/, serialization/, server/, stmt/ and utils/, each a separate concern. There is no models directory and no migration runner. The MIT licence applies to the repository, with a separate vitess_license file present at the top level.

Binlog streaming: the mechanism behind the replication package

The replication package works as a MySQL replica. You construct a BinlogSyncerConfig with a unique ServerID, a Flavor of either "mysql" or "mariadb", and connection details, then create a syncer with replication.NewBinlogSyncer. From there you have two starting points. StartSync takes a mysql.Position built from a binlog file name and a position. The README example also notes that you can start a GTID replication instead.

Once started, the streamer hands you events. The documented output shows RotateEvent, FormatDescriptionEvent and QueryEvent blocks with fields including Log position, Event size, Server version and the raw Query text.

The ServerID requirement is worth stating plainly: the comment in the example says it "must be different from other MySQL's". Reusing an ID that another replica already uses is a configuration error on your side, not something the library can detect for you.

MariaDB 11.4 and later introduced an optimisation where events written through transaction or statement cache carry LogPos=0, because the server copies them straight to the binlog without computing a real end position. The README is explicit that this makes position tracking unreliable for clients that track LogPos inside transactions. The library's answer is a FillZeroLogPos option on BinlogSyncerConfig. When it is true and the flavor is mariadb, the library adds BINLOG_SEND_ANNOTATE_ROWS_EVENT to binlog dump commands so the server emits ANNOTATE_ROWS_EVENT events, and it calculates LogPos dynamically for events with LogPos=0 that are not artificial. The README states the option has no effect with MySQL and should be set to true if you need LogPos tracking inside transactions.

Installing go-mysql and building the example binaries

There is no install step in the README beyond using it as a Go module. The module path is github.com/go-mysql-org/go-mysql, and go.mod declares go 1.25.0, so your toolchain needs to satisfy that. Add it to a project the normal way:

bash
go get github.com/go-mysql-org/go-mysql

The repository also ships example applications in the cmd directory. The README states they can be built by running make build in the root, and that the resulting binaries land in bin/. The Makefile build target confirms the five binaries:

bash
make build

That produces bin/go-binlogparser, bin/go-canal, bin/go-mysqlbinlog, bin/go-mysqldump and bin/go-mysqlserver. Their purposes, per the README, are: parse a binlog file at a given offset, stream binlog events from a server to canal, stream binlog events, act like mysqldump but in Go, and run a fake MySQL server.

For a first real use, the smallest thing to run is the syncer example. The README's snippet sets ServerID to 100, Flavor to "mysql", Host to "127.0.0.1", Port to 3306, User to "root" and an empty Password, then starts a stream and dumps each event. What you should see is a sequence of event blocks beginning with a RotateEvent and a FormatDescriptionEvent, followed by QueryEvent blocks as statements are executed on the server. If your server is MariaDB 11.4 or newer and you need positions inside transactions, add FillZeroLogPos: true to that config and set Flavor to "mariadb".

For local testing, the Makefile defines a test-local target that runs a mysql container with MYSQL_ALLOW_EMPTY_PASSWORD=true and MYSQL_DATABASE=test, mounts docker/resources/replication.cnf, waits on 127.0.0.1 3306, then runs the race-enabled test suite. A separate mariadb-start target runs MariaDB with --binlog-format=row and TLS material mounted from docker/resources.

Canal and the ROW format constraint

Canal is the package for syncing MySQL into other stores. The README describes it in one line: "Canal is a package that can sync your MySQL into everywhere, like Redis, Elasticsearch." The flow is a full dump of existing data followed by incremental sync from the binlog.

The constraint is stated before any example: you must use ROW format for binlog. That is a real operational requirement, not a suggestion. If your server runs STATEMENT or MIXED binlog format, canal is not the tool for you, and the fix is a server-side configuration change plus a restart, not a library option.

The Makefile's MariaDB container starts with --binlog-format=row, which is consistent with that requirement and gives you a working local reference configuration.

Where go-mysql is the wrong choice

Start with the platform table. Linux on amd64, s390x and arm64 are marked as runtime supported and covered by CI; Linux arm is built in CI only to confirm 32-bit builds work; FreeBSD amd64 is described as sporadically tested by developers. The README adds that other platforms supported by Go may work but have not been verified, and states plainly that the library is not compatible with TinyGo. If you are targeting a TinyGo build, this is a dead end.

The second boundary is scope. The README's content list does not include schema migration, query building or an ORM. The database/sql driver is listed as "an alternative database/sql driver for MySQL", one entry in a content list that also includes a fake server and a dump tool. Treating the project as a general-purpose data access layer will leave you writing the parts you assumed existed.

The third is the MariaDB 11.4+ position behaviour already described. If you depend on LogPos inside transactions and you do not set FillZeroLogPos, the README's own wording is that position tracking is unreliable. That is a silent correctness problem rather than a crash, which is the worse kind.

Finally, the replication model itself: acting as a replica means you are subject to the same constraints a replica is, including the ServerID uniqueness requirement and the binlog format of the source server.

How it compares to python-mysql-replication and to a plain driver

The README makes one direct comparison: the replication package "handles MySQL replication protocol like python-mysql-replication". The difference is the runtime, and it is not cosmetic. python-mysql-replication is a Python library, so a Go service that wants binlog events would need a second process, an IPC channel and a second deployment artifact. go-mysql keeps the stream in the same binary as the consumer, which removes that hop but also means the binlog parsing shares a process with your application logic, including its garbage collection and its failure modes.

The other comparison the README invites is internal. The project offers a simple MySQL client, a database/sql driver, a fake server and a dump tool in one module. Against a driver-only package such as go-sql-driver/mysql, the difference is that go-mysql's centre of gravity is the replication and protocol layer, with the driver as one component. If all you need is query execution, the extra surface is weight you are not using. If you need the binlog, the driver-only packages do not cover it at all.

The cmd binaries give a third option: go-mysqldump is described as "like mysqldump, but in Go", and go-mysqlbinlog streams binlog events as a standalone process. That lets you keep the replication work out of your application binary when you would rather not embed it.

Maintenance, upgrades and licence

The repository is not archived, and the last push was on 2026-11-01. The README states that the library uses a CHANGELOG.md, and there is a CHANGELOG.md at the top level, so version-to-version changes have a documented home. The repository has no published GitHub releases, so the changelog file is the place to look rather than any release listing.

The upgrade cost is dominated by the dependency graph in go.mod. The module requires go 1.25.0, and it pulls in github.com/pingcap/tidb/pkg/parser at a pseudo-version, github.com/klauspost/compress, github.com/goccy/go-json, github.com/jmoiron/sqlx and others. A pseudo-version dependency on a parser means your build resolves a specific commit rather than a tagged release, so a go.sum change is a real code change. Plan for that when you pin.

The licence is MIT. The top level also contains a file named vitess_license, which indicates licence terms attached to at least one component or derived work in the tree. If you redistribute the module or vendor it, read vitess_license directly rather than assuming MIT covers everything. This is a description of what is in the repository, not legal advice.

Editorial conclusion

Adopt go-mysql if you are writing Go and need to read a binlog stream, run a fake MySQL server for tests, or embed a MySQL client without cgo. Do not adopt it if you want an ORM or a query builder; the repository is a protocol and replication library, and the database/sql driver it ships is one component among several. Before you commit, verify two things in your own environment: that your binlog format is ROW, as the canal documentation requires, and that your MySQL or MariaDB version is covered by the compatibility notes, including the MariaDB 11.4+ LogPos behaviour and the FillZeroLogPos option.

Frequently asked questions

What is go-mysql used for?

It is a pure Go library for the MySQL network protocol and replication as used by MySQL and MariaDB. The README lists binlog event processing, canal-based incremental dumping into stores such as Redis or Elasticsearch, a simple client, a fake server and an alternative database/sql driver.

How do I install go-mysql in a Go project?

It is consumed as a Go module at github.com/go-mysql-org/go-mysql, and go.mod declares go 1.25.0. The repository's example applications are built by running make build in the root, which places binaries in bin/.

Does go-mysql work with MariaDB as well as MySQL?

Yes. BinlogSyncerConfig takes a Flavor field set to either "mysql" or "mariadb", and the README documents separate GTID set formats for each. The FillZeroLogPos option applies only to the MariaDB flavor and has no effect with MySQL.

What binlog format does go-mysql canal require?

The README states you must use ROW format for binlog.

Official sources

  1. go-mysql-org/go-mysql on GitHub
  2. Issues
  3. License: MIT
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/go-mysql-org-go-mysql.svg)](https://hysenlabs.com/projects/go-mysql-org-go-mysql)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/go-mysql-org-go-mysql.svg)](https://hysenlabs.com/projects/go-mysql-org-go-mysql)

Was this useful?