XiaoMi/Gaea: a MySQL proxy from Xiaomi for sharding, routing and read/write splitting

The problem Gaea sits in front of

A single MySQL instance eventually stops fitting. The usual escape is sharding, but sharding pushes routing decisions into application code, and every service that touches the database then needs its own copy of the shard map, its own connection handling, and its own read/write split logic. Gaea moves that logic into a proxy that speaks the MySQL wire protocol. Applications keep connecting with an ordinary MySQL client and stop knowing how many backends exist.

The README describes Gaea as Xiaomi's self-developed database middleware based on the MySQL protocol, in use across phone, automotive, ecosystem-chain, finance and internet business lines. The audience is therefore infrastructure teams inside a company that already operates MySQL fleets, not individual developers. The feature list is aimed at that audience: multi-cluster, multi-tenant, transparent SQL forwarding, slow and error SQL fingerprinting, annotation-based routing, slow logs, read/write splitting with replica load balancing, custom SQL interception and filtering, connection pooling, hot configuration reloading, IP and IP-range allowlists, and global sequence numbers.

Sharding is explicitly framed as compatibility work. The README states that the sharding scheme is compatible with the routing approaches of mycat and kingshard, and that the design references mycat, kingshard and vitess, with TiDB's parser used as the built-in SQL parser. That is a useful signal about migration cost: if you already run one of those two, the routing model will look familiar.

How routing, parsing and the control plane fit together

The repository layout tells most of the architecture story. Top-level directories include proxy/, backend/, parser/, mysql/, server/, models/, stats/, log/, core/, cc/, cmd/ and tests/. The parser/ directory is built separately by the Makefile, which is consistent with the README's statement that TiDB's parser is embedded. The mysql/ and stats/ modules are credited to external projects: mysql is described as drawn from google vitess, tidb and kingshard, and stats from google vitess for metrics.

A query arriving at the proxy is parsed, routed, and forwarded to a backend. The README lists the aggregation support that makes this non-trivial: max, min, sum, count, group by and order by are handled across shards, and joins are supported between a sharded table and a global table, or between multiple sharded tables that share the same routing rule. Those two join cases are the honest boundary. A join across shards with different routing rules is not in the list.

Configuration management is split out. The README's cluster deployment diagram shows one gaea-cc plus etcd managing multiple Gaea clusters, handling create, read, update and delete of namespace configuration inside a cluster. There is a separate document for the gaea-cc HTTP interface. go.mod confirms the dependency: github.com/coreos/etcd v3.3.13+incompatible is required, alongside gin for the HTTP layer and the go-sql-driver/mysql client. So the operational shape is a proxy tier plus a control plane plus an etcd cluster, and the namespace is the unit that configuration is organized around.

Building Gaea from source and pointing it at a config

The README does not give inline install commands; it points to docs/quickstart.md and docs/configuration.md. What the repository does give is a Makefile and a Dockerfile, and those are enough to describe the build. The Makefile defines gaea and gaea-cc targets and a parser target, and the build target runs parser first, then both binaries. The parser step matters because the SQL parser is a vendored subdirectory with its own Makefile.

To produce the binaries, run the build target from the repository root. The Makefile sets CGO_ENABLED=0 and defaults GOOS to linux, so the output is a static Linux binary written to bin/gaea and bin/gaea-cc.

make build

The Dockerfile shows the expected runtime layout. It builds with golang:1.16.15, copies the binary to /home/work/gaea/bin/gaea, creates /home/work/gaea/etc, and sets the entrypoint to launch the proxy with a config file at a fixed path. That path is the contract between the image and your configuration.

ENTRYPOINT /home/work/gaea/bin/gaea -config /home/work/gaea/etc/gaea.ini

So a first real run means mounting or baking a gaea.ini at /home/work/gaea/etc/gaea.ini. Note that the Dockerfile's base images are pulled from micr.cloud.mioffice.cn, an internal Xiaomi registry, so building the image as written requires access to that registry or a substitution of the FROM lines. The README does not document a public image.

For the configuration file itself, the README defers to docs/configuration.md, and go.mod shows github.com/go-ini/ini is a dependency, which is consistent with the .ini format the Dockerfile entrypoint names. The README does not reproduce the keys here, so treat that document as the source of truth before writing your first namespace.

What the roadmap says is still missing

The roadmap is the most informative part of the README for anyone evaluating fit. Exactly one item is checked: configuration encryption storage with a switch. Everything else is open. Execution plan caching, transaction tracing, secondary indexes, distributed transactions, smooth scale-out and scale-in, and backend connection pool optimization with request-time queuing are all unchecked.

The distributed transactions gap is the one that decides most adoption questions. If your workload spans shards inside a single logical transaction, Gaea's documented feature set does not cover it, and the roadmap says it is not there yet. The same applies to resharding: smooth expansion and contraction is listed as future work, and the README does not document a rollback path for a shard move. A team that expects to grow from four shards to thirty-two without downtime should read that as a warning rather than a roadmap promise.

There is a second, quieter limitation in the join support. Joins work between a sharded table and a global table, or between sharded tables that share a routing rule. That is a real constraint on schema design, and it is the kind of thing that surfaces late, when a query that used to be local becomes cross-shard. The compatibility document, docs/compatibility.md, is where the README sends readers for the full statement-level picture; the README itself does not enumerate what fails.

Gaea compared with Vitess and ProxySQL

The closest comparison the README invites is Vitess, which it credits as a design reference and as the source of the mysql and stats modules. Vitess is a full clustering system for MySQL with its own topology service, orchestration for resharding, and a query planner built around its VSchema abstraction. Gaea is narrower: it is a proxy plus a control plane, and the README's roadmap places smooth scale-out and scale-in in the future, whereas resharding workflows are a documented part of Vitess. If you need the resharding machinery, Vitess is the more complete answer, at the cost of a much larger operational surface.

The other comparison is ProxySQL, a widely deployed MySQL proxy whose configuration model is built around its own admin interface and runtime tables rather than an etcd-backed control plane. Gaea's configuration story is different in kind: gaea-cc plus etcd manages namespaces across multiple Gaea clusters, and the README lists configuration hot reloading as a feature with a dedicated design document. That is a genuine architectural difference, and it is the reason a team already running etcd will find Gaea's control plane familiar while a team that prefers a single self-contained proxy will find it heavier.

Mycat and kingshard deserve a mention too, since the README states Gaea's sharding scheme is compatible with their routing approaches. For a team already on either, Gaea is less a rewrite of routing rules and more a change of runtime.

Licence, maintenance and the cost of upgrading

Gaea is Apache-2.0, per the licence badge in the README and the LICENSE file at the repository root. Apache-2.0 permits commercial use, modification and redistribution with the usual notice and patent-grant conditions attached. That is a permissive licence, and it is the same family as the licences of the projects Gaea builds on. This is a description of the licence identifier, not legal advice; if you redistribute a modified Gaea, read the LICENSE file itself.

On maintenance, the repository is not archived, and the last push was on 2026-03-18. The most recent tagged release is v2.4.2 from 2024-09-20, and the release list before that jumps back to v1.2.5 in 2022. The gap between the v2.4.2 tag and the 2026 push suggests work has continued on main without a corresponding release, though the README does not describe a release cadence and the CHANGELOG is not reproduced here. Anyone pinning a version should check what main contains relative to the last tag before assuming the tagged build has the fixes.

Upgrade cost is dominated by the control plane rather than the binary. The Makefile builds a single static binary, so replacing the proxy is straightforward. The harder part is configuration: namespaces live in etcd and are managed through gaea-cc, and the README documents hot reloading as a feature with its own design document, docs/config-reloading.md. That document is where you should look before assuming a config change can be applied without a restart. The README does not state which changes are reloadable and which require a restart; docs/config-reloading.md is the place that should answer it.

Editorial conclusion

Adopt Gaea if you already run MySQL at a scale where one primary cannot absorb the write path and you are willing to operate a proxy tier plus etcd and gaea-cc alongside it. Skip it if you need distributed transactions or online resharding today: both sit unchecked on the roadmap, and the README does not document rollback for a shard move. Before committing, read docs/compatibility.md and confirm your statement mix is covered, then check whether the repository's recent activity matches your support expectations, since the last push was on 2026-03-18 and the most recent tagged release, v2.4.2, dates from 2024-09-20.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. XiaoMi/Gaea on GitHub