# kingshard: a Go MySQL proxy for read/write splitting and sharding

> kingshard is a MySQL proxy written in Go that splits reads from writes and shards tables across nodes. It targets teams outgrowing a single MySQL instance but not ready to rewrite their application for a sharded cluster.

**flike/kingshard** — A high-performance MySQL proxy

- Repository: https://github.com/flike/kingshard
- Stars: 6,398 · Forks: 1,214
- Language: Go
- License: not declared
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/flike-kingshard

## What kingshard sits between and why

kingshard is a proxy that speaks the MySQL protocol to your application and forwards statements to one or more MySQL backends. The README describes the two jobs it does: splitting read and write SQL, and sharding. The sharding part is what the project calls its most important feature, with the stated aim of simplifying MySQL sharding.

The audience is narrow but real. If your application connects to MySQL through a normal client library, kingshard can sit in front of that connection and decide which backend handles each statement. That means the application keeps sending plain SQL. The trade-off is that the proxy now has to parse and route every statement, and the README puts the cost plainly: performance is about 80% compared to connecting to MySQL directly. That is a stated figure from the project, not a measured one, and it is the number to keep in mind when deciding whether a proxy hop is acceptable for your workload.

Basic statement coverage is select, insert, update, replace and delete. Anything outside that set is a candidate for failure, and the README does not claim otherwise.

## How routing, sharding and the SQL parser fit together

The repository layout tells you most of the architecture. There is a sqlparser/ directory containing a grammar (sql.y) plus a generated sql.go, a backend/ directory, a proxy/ directory, a mysql/ directory, a config/ directory and a monitor/ directory. Statements arrive through the proxy layer, get parsed by the generated parser, and are dispatched to backends according to configuration.

The Makefile makes the parser dependency explicit. There is a goyacc target that runs goyacc over ./sqlparser/sql.y to regenerate ./sqlparser/sql.go, then gofmt on the result. That means the parser is a real grammar rather than a set of regular expressions, and it also means the generated file is committed to the repository. If you change the grammar you regenerate; if you do not, you are working with whatever the checked-in sql.go contains.

Sharding supports hash, range and date strategies across multiple nodes, and the README says you can send SQL to a specified node directly. Aggregation over shards covers max, min, count and sum, with join, limit, order by and group by listed as supported. Those are the operations that make a proxy useful rather than merely a router, because a count across shards has to be merged somewhere. The parser is where that merging logic is anchored.

Beyond routing, the README lists client IP ACL control, transactions confined to a single node, a cap on connections to the MySQL backend, taking a backend online or offline dynamically, prepared statements through COM_STMT_PREPARE and COM_STMT_EXECUTE, multiple slaves with load balancing between them, forced reads from the master, last_insert_id(), backend HA, a configurable proxy charset, a SQL blacklist, and dynamic config changes. Note the transaction scope: single node only. A transaction that spans shards is not something the README claims to handle.

## Installing kingshard and running it for the first time

The README gives a seven-step install. It assumes Go is already present and that you are working inside a GOPATH layout, cloning to $GOPATH/src/github.com/flike/kingshard. The dev.sh script is sourced before building, and the build itself is a make.

```bash
git clone https://github.com/flike/kingshard.git $GOPATH/src/github.com/flike/kingshard
cd $GOPATH/src/github.com/flike/kingshard
source ./dev.sh
make
```

After make completes you should have a binary at ./bin/kingshard. The Makefile builds it with go build -mod=vendor and injects a build version and build date through ldflags, so the binary carries the commit hash it was built from.

Configuration lives in etc/ks.yaml. The README does not document the individual keys of that file, so treat the checked-in example as the source of truth for what is available. Once it is set, you start the proxy with the config flag:

```bash
./bin/kingshard -config=etc/ks.yaml
```

If you would rather not build Go locally, the repository ships a Dockerfile. It builds in a golang:1.13.8 stage with CGO_ENABLED=0 make, then copies the binary into an alpine:3.11.3 image, placing the config at /etc/kingshard/ks.yaml and starting with kingshard -config=/etc/kingshard/ks.yaml. The image also installs tzdata and sets the container timezone to Asia/Shanghai, which is worth knowing if your timestamps matter.

For a first real use, the practical path is to point the proxy at one master and one slave, confirm that a select lands on the slave and an insert lands on the master, and only then introduce a sharding rule. The README points to doc/KingDoc/how_to_use_kingshard_EN.md for building a cluster, which is the document to read before touching sharding config.

## Where kingshard will disappoint you

The first limitation is statement coverage. The supported list is select, insert, update, replace and delete. Anything else is outside what the README claims, and a proxy that cannot parse a statement cannot route it correctly. If your application leans on stored procedures, complex DDL, or vendor-specific syntax, test those statements against the parser before you commit.

The second is transactions. The README says transactions are supported in a single node. That is a real boundary: once a transaction needs to touch two shards, this design does not cover it, and the README offers no alternative.

The third is operational. The README does not document rollback, upgrade procedures, or how to recover a proxy that has been left with stale backend state. Dynamic config changes are listed as a feature, but the README does not describe what happens to in-flight connections when a value changes. For a component sitting in front of your database, that silence matters more than the feature list.

The fourth is the release cadence. The most recent release in the repository is 1.6 from 2018-06-07, preceded by 1.5 in 2016 and 1.4 in 2016. The last push to master was on 2026-06-05, so the code has moved since the last tagged release, but there is no tagged version that reflects those later commits. If your process requires pinning to a release, you are pinning to something from 2018.

None of this makes kingshard unusable. It makes it a component you adopt with your eyes open, and it makes the 80% performance figure and the single-node transaction scope the two numbers to weigh first.

## How kingshard differs from ProxySQL and Vitess

The closest comparison in approach is ProxySQL, which is also a MySQL protocol proxy sitting between clients and backends. The difference is where the work happens. kingshard is a Go program you build from source with make and configure through a YAML file at etc/ks.yaml, with a generated yacc grammar in sqlparser/ handling statement parsing. ProxySQL is configured through its own runtime administration interface rather than a file you edit and restart against. If your team prefers configuration as code in a repository, kingshard's model is the more familiar one; if you prefer changing routing rules at runtime without a rebuild, that is a different workflow.

Vitess takes a different route entirely. It is a sharding system built around its own topology and a set of components, rather than a single proxy binary that you drop in front of existing MySQL servers. kingshard's pitch is that you keep your MySQL servers and put a proxy in front of them. Vitess asks you to adopt more of its stack. The trade-off is that kingshard's sharding feature set is bounded by what its parser and config support, while a fuller system carries more machinery for the same problem.

If your requirement is only read/write splitting with no sharding, a proxy is arguably more moving parts than you need; MySQL replication with two connection pools in the application achieves the same routing without an extra network hop. kingshard's sharding is the reason to accept that hop.

## Maintenance cost and the licence question

Maintenance here is not a matter of pulling releases. There is no tagged release after 1.6 from 2018-06-07, so any upgrade path runs through master, whose last push was on 2026-06-05. Building from master means running make against whatever the current grammar and vendored dependencies are; the Makefile uses -mod=vendor, and the repository carries a vendor/ directory, so dependency resolution is pinned in-tree rather than fetched. That is good for reproducibility and bad if a vendored dependency needs a security fix, because someone has to update the vendor directory.

If you modify the grammar, you also own the goyacc regeneration step and the gofmt pass that follows it. That is a real build dependency: goyacc comes from golang.org/x/tools/cmd/goyacc, fetched by the Makefile target rather than vendored.

On licensing, the README states that kingshard is under the Apache 2.0 license and points to the LICENSE file under doc/License. The repository metadata given here does not carry a licence identifier, so the README statement is the claim to verify against the actual file before you rely on it. Apache 2.0 includes an explicit patent grant and requires attribution and notice retention, which matters if you redistribute a modified binary. That is a description of the licence, not legal advice; if redistribution is part of your plan, have someone qualified read doc/License.

## Conclusion

kingshard fits teams that want sharding and read/write splitting without changing application SQL, and that are comfortable building it from source with make and maintaining etc/ks.yaml by hand. It is the wrong choice if you need documented rollback procedures, an actively released version, or a proxy you can upgrade on a predictable cadence: the newest release listed in the repository is 1.6 from 2018-06-07, and the last push to master was on 2026-06-05. Before adopting it, verify that the SQL your application actually sends is covered by the supported statement list, and confirm the Apache 2.0 licence text referenced under doc/License matches what you need.

## FAQ

### What does kingshard do?

It is a MySQL proxy written in Go that splits read and write SQL and shards tables across multiple nodes using hash, range or date strategies. The README describes sharding as its most important feature and states that performance is about 80% compared to connecting to MySQL directly.

### How do I install and run kingshard?

The README's steps are to install Go, clone the repository into $GOPATH/src/github.com/flike/kingshard, source ./dev.sh, run make, set etc/ks.yaml, then start it with ./bin/kingshard -config=etc/ks.yaml. A Dockerfile is also present in the repository.

### Does kingshard support transactions across shards?

No. The README lists transaction support as being in a single node, and does not describe cross-shard transactions.

### Which SQL statements does kingshard support?

The README says it supports the basic statements select, insert, update, replace and delete. For sharded queries it also lists max, min, count, sum, join, limit, order by and group by.

### What licence is kingshard under?

The README states that kingshard is under the Apache 2.0 license and points to the LICENSE file under doc/License. The repository metadata does not carry a licence identifier, so check that file directly.

## Sources

- [flike/kingshard on GitHub](https://github.com/flike/kingshard)
- [Issues](https://github.com/flike/kingshard/issues)
- [README](https://github.com/flike/kingshard/blob/master/README.md)
- [Releases](https://github.com/flike/kingshard/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/flike-kingshard