go-mysql

go-mysql is a pure Go implementation of the MySQL client/server network protocol and binary log replication format, used for MySQL and MariaDB. Rather than shipping a single client, it exposes a set of composable packages: a low-level client for issuing queries and streaming large result sets, a server package for building fake or proxy MySQL servers that speak the real wire protocol, a replication package for consuming binlog events (row, GTID, and transaction-payload formats) directly from a master, and a database/sql-compatible driver.

On top of these primitives sits canal, which combines an initial mysqldump snapshot with incremental binlog tailing to give applications a full change-data-capture (CDC) stream — the same pattern used by tools like Debezium, but as an embeddable Go library rather than a separate service. It underlies several downstream sync tools (go-mysql-elasticsearch, and others in the go-mysql-org organization) and is a common building block for teams writing their own MySQL-to-anything replication pipelines, proxies, or protocol-level test doubles.

The project has been maintained since 2014, currently sees active weekly commit activity, and is tested in CI against a matrix of MySQL 8.0/8.4/9.x and multiple OS/architectures (including s390x and arm64), reflecting its use in production replication and proxy infrastructure.

What You Get

• A client package for connecting to MySQL/MariaDB, executing queries, using prepared statements, streaming very large SELECT results row-by-row without buffering the whole result set, and pooling connections
• A replication package (BinlogSyncer) that registers as a replica and streams parsed binlog events — row changes, GTID sets, query events, and MariaDB/MySQL-specific extensions like FillZeroLogPos for MariaDB 11.4+ — directly to your application
• A canal package that combines a mysqldump-based initial snapshot with live binlog tailing behind a single EventHandler interface, giving you a ready-made CDC pipeline to sync MySQL into Redis, Elasticsearch, or any other sink
• A server package for implementing your own MySQL-protocol-compatible server (fake servers for testing, or protocol-level proxies), supporting mysql_native_password, caching_sha2_password, and sha256_password auth and TLS out of the box
• A database/sql driver (driver package) so existing Go code using the standard sql.DB interface can run on top of go-mysql’s connection handling, with both DSN-string and structured Connector configuration
• Standalone CLI example binaries (go-binlogparser, go-canal, go-mysqlbinlog, go-mysqldump, go-mysqlserver) under cmd/ that double as usage references for each package

Common Use Cases

• Building a change-data-capture pipeline that streams MySQL row changes into Elasticsearch, Redis, Kafka, or a data warehouse
• Writing a MySQL-protocol-compatible proxy or middleware layer (query routing, sharding, caching) that real MySQL clients can connect to unmodified
• Consuming binlog events directly (GTID or file-position based) to build cache invalidation, audit logging, or cross-database replication
• Parsing or replaying binlog files offline for auditing, debugging, or migration tooling
• Standing up lightweight fake MySQL servers in integration tests without a real MySQL instance

Under The Hood

Architecture go-mysql is organized as a stack of composable packages with a clear dependency direction: packet implements the raw MySQL wire framing (packet read/write, compression, TLS), mysql builds protocol types and result-set handling on top of it, and client, server, and replication each build higher-level behavior on those primitives — a query client, a protocol-compatible server implementation, and a binlog-consuming replica, respectively. canal sits at the top of the stack, composing client (for the initial dump), dump (mysqldump wrapper), replication (binlog tailing), and schema (table introspection) behind a single EventHandler interface, so callers implementing CDC pipelines never touch the lower-level packages directly. This layering means the wire-protocol code (packet/mysql) has no knowledge of replication or canal, so changes to core protocol handling propagate upward through few, well-defined seams rather than being duplicated across the client/server/replication packages.

Tech Stack The library targets modern Go (go.mod requires Go 1.25) with a deliberately small dependency footprint: github.com/pingcap/tidb/pkg/parser for SQL parsing in canal, github.com/google/uuid and filippo.io/edwards25519/golang.org/x/text for protocol-level needs, github.com/klauspost/compress and goccy/go-json for performance-sensitive paths, and stretchr/testify for assertions in tests. There’s no external ORM or web framework dependency — it is the lower-level layer other tools build on. Builds and example binaries are driven by a Makefile, and integration testing uses a Docker-based MySQL setup (docker/docker-compose.yaml) alongside GitHub Actions matrices covering MySQL 8.0/8.4/9.x and multiple Linux distributions/architectures plus FreeBSD.

Code Quality The repository has an extensive test suite (dozens of _test.go files across every package) using testify for assertions, plus real-database integration tests that run against live MySQL instances in CI rather than mocks alone — including a dedicated CI job matrix across Go versions, OS/architecture combinations (amd64, arm64, arm, s390x), and multiple MySQL server versions. Linting is enforced via a comprehensive golangci-lint configuration (staticcheck, govet with most checks enabled, errcheck, unused, revive, and more) with gofumpt/goimports for formatting, and errors are returned as typed values (via github.com/pingcap/errors) rather than swallowed. Naming and package boundaries are consistent with idiomatic Go conventions throughout.

API Design The public API favors small, focused interfaces over large configuration objects: canal.EventHandler requires implementing just OnRow (via embedding DummyEventHandler for the rest), BinlogSyncerConfig is a flat struct with sensible defaults (flavor defaults to MySQL if unset), and the driver package offers both a familiar DSN string and a structured Connector for callers who want typed configuration. Getting started requires moderate boilerplate — configuring a BinlogSyncerConfig or canal.Config and registering a handler — but the README documents each entry point (replication, canal, client, server, driver) with runnable examples, and a dedicated examples/ directory plus cmd/ reference binaries lower the barrier for a first integration.