Gaea is a MySQL protocol proxy whose Docker build needs a private registry

A MySQL protocol proxy, and the three projects it was built from

The one-line description says Gaea is a MySQL proxy developed by the Xiaomi b2c-dev team. The Chinese README expands it: an in-house database middleware speaking the MySQL protocol, in use across phones, cars, the ecosystem chain, finance and internet businesses, supporting sharding, SQL routing and read and write separation.

The lineage is stated plainly, and it is the most useful paragraph on the page. Gaea referenced mycat, kingshard and vitess during design and implementation, and uses the tidb parser as its built-in SQL parser.

That has a direct consequence for anyone reading the feature list. When the README says the sharding scheme is compatible with the routing approaches of both mycat and kingshard, it is describing two inherited designs rather than one new one. The database-level sharding is mycat's approach and the table-level splitting is kingshard's, and the own-modules list credits `proxy/router` with the kingshard routing coming from the kingshard project itself.

The external-modules list completes the picture: a MySQL library shared with vitess, tidb and kingshard, the tidb parser, vitess's stats package for metrics, and a `util` directory marked as mixed.

The README is written in Chinese, and the two diagram headings it contains, for the architecture and the cluster deployment, are followed by text rather than a figure.

Joins work across shards only when the routing rule matches

The sharding section is where an adopter should stop reading. Two capabilities are claimed: support for mycat's database sharding style, and support for kingshard's table splitting style.

The aggregate function support is the ordinary set, max, min, sum, count, group by and order by. What matters more is the join statement, and it has two halves with different reach. Gaea supports joins between a sharded table and a global table, and it supports joins across several sharded tables provided they share the same routing rule.

Read the second clause as a limit rather than a detail. A join spanning two sharded tables on different routing rules is not listed as supported, and a sharding proxy that cannot scatter-gather a join across arbitrary shards cannot implement one. If your queries join tables that shard differently, this is the constraint that decides the project for you, and it is stated in a single clause of a feature list.

A global table, therefore, is not a convenience here. It is the mechanism that makes a cross-shard join possible at all.

Transparent forwarding and annotation routing pull in opposite directions

Thirteen basic features are listed: multi-cluster, multi-tenant, transparent SQL forwarding, slow SQL fingerprinting, error SQL fingerprinting, annotation routing, slow logging, read and write separation with replica load balancing, custom SQL interception and filtering, a connection pool, hot configuration reload, an IP and CIDR allowlist, and global sequence IDs.

One of those changes what your application has to do. Transparent SQL forwarding and everything else in the list work at the protocol level, where the client sends the same SQL it always sent. Annotation routing, by name, works by a marker travelling with the statement, which means something upstream has to attach it.

So there are two routing modes on offer and they are not equivalent in cost. Fingerprinting slow and erroneous SQL, hot reloading and the allowlist are all invisible to the application. Annotation routing is not, and the page does not say whether annotations travel in a SQL comment, a connection attribute or a session variable.

The design and implementation documents list the mechanisms separately: multi-tenant design, configuration hot reload, the backend connection pool, and a `prepare` stage. The last of those is the one to look at first if you care how a statement is validated before it is routed.

Seven roadmap items, six of them unchecked

The roadmap is short and mostly empty. One item is done: support for encrypted configuration storage, with a switch. Six are not: execution plan caching, transaction tracing, secondary indexes, distributed transactions, smooth scaling up and down, and backend connection pool optimisation described as queueing by request time.

Two of those six matter more than the rest for anyone running this in production. Distributed transactions is the one a sharding proxy is usually bought for, and smooth scaling is the one that decides whether a rebalance is a maintenance window or a migration.

The release history adds a timing question. The visible tags are v1.2.4 on 2022-03-02, v1.2.5 on 2022-04-02 and v2.4.2 on 2024-09-20, and the last push to the branch was on 2026-03-18. So the newest published release is close to two years older than the branch head, and the list skips everything between 1.2.5 and 2.4.2.

The performance figures have the same problem one minor version further back. The only performance document linked is titled for version 2.3.7, so the published numbers describe a build two minors behind the newest tag and two years behind the branch.

Both container base images come from a private registry

The Dockerfile is the first thing to look at if you plan to build this yourself, and it is where the deployment story gets specific.

The builder stage is golang 1.16.15 and the runtime stage is an alpine image, and neither comes from a public registry:

FROM micr.cloud.mioffice.cn/dockerhub/library/golang:1.16.15 AS builder
FROM micr.cloud.mioffice.cn/devdba/alpine:gaea-v1

The first is a mirror of the official golang image on Xiaomi's internal host. The second is not a stock alpine tag at all; it is `alpine:gaea-v1`, an image built for this project, so even with network access to that host you are depending on an artefact somebody else maintains.

The build inside is `make gaea`, and the entrypoint pins the configuration path:

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

The locale and timezone are also set explicitly, to en_US.UTF-8 and Asia/Shanghai. In practice `docker build` on this repository fails outside that network until both FROM lines are rewritten, which makes the Dockerfile a fork point rather than a build recipe.

The test target disables inlining, which a mocking library needs

go.mod declares `go 1.16` and the Makefile builds with CGO disabled. Among the direct dependencies is github.com/bytedance/mockey, a library that patches functions at runtime rather than through interfaces.

That dependency explains the test target, which is not a normal one:

test:
	go test -gcflags="all=-l -N" -coverprofile=.coverage.out `go list ./...` -short

`-l -N` disables inlining and optimisation across all packages, which is exactly the requirement for a library that rewrites compiled code at runtime. So a reader who sees unusual compiler flags here is looking at the price of the mocking approach, not at a leftover.

The rest of the Makefile is worth scanning. `all` runs build and test. The parser target shells out to another Makefile:

parser:
	cd parser && make && cd ..

End to end tests build both binaries, copy them into tests/e2e/cmd/ and then run two scripts, with separate pairs for MySQL 5 and MySQL 8. The check target runs `./hack/verify-$*.sh` over a list of two checks, EOF and spelling. And the integration target is spelled `integrate_test`, not `integration_test`.

There are three version-related shell scripts at the root: gen_ldflags.sh, gen_version.sh and genver.sh.

Three CI configurations, and the default branch is main

Continuous integration is configured in three places at once: a .github/ directory, a .gitlab/ directory and a .travis.yml file. The README badges point at Travis and at goreportcard, neither of which reflects the .gitlab/ or .github/ configuration.

Then there is the branch. The repository's default branch is `main`, and the licence badge at the top of the README points at `blob/master/LICENSE`, a path on a branch named master. One of the two links is stale, and the badge row is the first thing anyone sees.

The community section is where the page runs out. It names a Gitter channel for xiaomi-b2c/Gaea with a badge URL, then a heading for Feishu with no address, no invitation and no text after it.

What is documented, by contrast, is thorough. Under installation and usage there are quickstart, configuration, Grafana monitoring, global sequence ID, concepts, SQL compatibility and FAQ documents. Under design and implementation there are separate write-ups for the overall architecture, multi-tenancy, configuration hot reload, the backend connection pool and the prepare stage, plus an HTTP interface document for gaea-cc, the component that manages multiple Gaea clusters alongside etcd and handles namespace configuration inside a cluster.

Editorial conclusion

Adopt Gaea if you run MySQL behind a connection string you control and need sharding, read and write separation and hot configuration reload without touching application code, and you can live inside two inherited routing schemes instead of one you designed. Do not adopt it expecting distributed transactions, execution plan caching or elastic scaling, since all three sit unchecked on its own roadmap and joins are supported only across shard tables sharing a routing rule. Verify first that you can build it at all, because both Docker base images are pulled from a private Xiaomi registry and the runtime stage uses a custom alpine tag, then check which release your performance figures describe, since the only published report is for version 2.3.7 while the newest tag is v2.4.2.

Frequently asked questions

Official sources

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