# dble: a MySQL sharding middleware with an English documentation gap

> dble is a Java middleware that sits between an application and sharded MySQL nodes, speaking the MySQL protocol and offering two-phase commit. The features are documented, but the English setup story is thin.

**actiontech/dble** — A High Scalability Middle-ware for MySQL Sharding

- Repository: https://github.com/actiontech/dble
- Website: https://opensource.actionsky.com
- Stars: 1,119 · Forks: 315
- Language: Java
- License: GPL-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/actiontech-dble

## dble as a sharding layer in front of MySQL nodes

dble describes itself as "a high scalability middle-ware for MySQL sharding", maintained by ActionTech, and the codebase is Java. The problem it targets is narrow and concrete: a single MySQL instance stops being enough once a table outgrows one machine, and rewriting an application to talk to several databases is expensive. dble sits between the application and the database nodes, so the application keeps addressing a MySQL endpoint while dble decides which underlying node serves each statement.

That framing explains the emphasis in the project description. The goal is not to be a new database. The goal is to sit in front of existing MySQL instances and spread data across them. The README also records that dble is the open-source version of a commercial product, CTREE Shard, which tells you that the middleware is meant to run in production setups rather than as a research prototype.

## The MySQL protocol means most client code stays untouched

The mechanism that makes adoption cheap is protocol compatibility. dble accepts the same wire protocol as MySQL, so a client library, an ORM, or a migration tool that already speaks to MySQL can be pointed at dble instead. The README puts it plainly: you can replace MySQL with dble to power your application without changing a single line of code in most cases.

The phrase "in most cases" is doing real work there. dble also lists support for SQL 92 and the MySQL dialect, with complex queries handled including group by, order by, distinct, join, and union. Sub-queries appear in the roadmap rather than in the supported list, so a query that uses one is exactly the kind of statement where the compatibility promise needs checking against the ROADMAP before you migrate. Complex query optimization is called out separately, covering global-table joins with sharding tables, ER-relation tables, and simplifying select items.

## Clustered nodes and two-phase commit for cross-shard writes

Two mechanisms matter for anyone sizing a deployment. The first is high availability through clustering: the dble server can be used as a cluster so that "business will not suffer from single node fail". The second is distributed transactions, which dble implements with two-phase commit across shards.

The two-phase commit path has two modes and the trade-off is explicit. Normal mode is chosen for performance, and XA mode is chosen for data safety. The README is careful about the conditions attached to XA: it depends on MySQL 5.7 XA transaction support, on the high availability of the MySQL node, and on the data reliability of the disk underneath it. XA is therefore not a switch that makes a deployment safe on its own, it moves the durability requirement outward to the database nodes. A team picking XA needs to reason about shard node failover and disk behaviour, not just about dble.

## Building dble from source with the bundled Makefile

The repository ships a Makefile whose default target builds the project inside a Docker container that already contains a JDK and Maven. The target expands into a single container run, mounting the current directory as a volume so the Maven output lands in your working copy:

```bash
$(DOCKER) run -v $(shell pwd)/:/volume/git  --rm -w /volume/git jamesdbloom/docker-java8-maven mvn clean install
```

Invoke that target from a clone of the repository, with Docker installed and reachable on the path, since the Makefile resolves the docker binary through the shell. You should see Maven resolve dependencies and compile the `src/` tree into artifacts locally, with the build rooted at the volume path. The repository also carries `pom.xml`, `version.txt`, a `version.txt.template`, `algorithm/`, `conf/`, and `docker-images/`, so the packaging metadata is versioned alongside the code. If you would rather not build, the project points to the releases page for binaries and to Docker-based quick starts in `docs/`.

## The English quick start is a link, not a walkthrough

Here is where a prospective user hits friction. The README does not contain an install procedure. It says to read the Quick Start document, the Quick Start With Docker document, or the Quick Start With Docker-Compose document, all of which live under `docs/`. The English documentation index is listed as "Comming soon", and the linked PDF manual is published from the separate `dble-docs-cn` repository, whose name and text make the language clear.

So the honest path for an English-speaking engineer is: pick a release from the releases page, or build with the Makefile, then follow the Docker quick start and expect to be reading a Chinese document for the configuration details. Nothing in the repository listing shows a `conf/` file with a documented example block, and the entry list is a bare directory name rather than a described layout. Treat the config surface as something you learn from the Chinese quick start rather than from the README.

## dble as a MyCat fork with the non-MySQL databases removed

The real alternative to dble is not another sharding proxy, it is the ancestor dble was forked from: MyCat. The README states that dble is based on MyCat and thanks the MyCat contributors, then draws the difference directly. ActionTech cancelled support for other databases, keeping MySQL as the single target, and in the process claims deep improvements to compatibility, complex query behaviour, and distributed transactions, along with a large number of bug fixes.

That is the comparison that matters for an evaluation. Choosing dble over MyCat is a bet that a MySQL-only, more recently revised line is the better bet for a MySQL fleet, and the project does not publish a benchmark table to back the claim, so the judgement stays qualitative. The other side of the comparison is doing nothing: a single MySQL instance needs no sharding layer at all, and every layer you add is a layer that can misroute a transaction or become the thing that fails at peak traffic.

## Release tags from 2023 and a repository still receiving pushes

Maintenance signals point in two directions here. The repository is not archived, and the last push was on 2026-09-04, so commits are still landing on the default branch, master. The visible tags, however, are all from the same day in November 2023: 3.23.08.0, 3.21.10.15, and 3.22.11.1, each published on 2023-11-02. The version numbers follow a year.month.patch convention, and the presence of a 3.21 line alongside a 3.23 line suggests parallel maintenance of older branches, though the repository does not explain that policy.

The gap between the newest visible release and the recent push is worth noticing rather than glossing over. A push after the last tag may be a fix, a dependency bump, or work that has not been cut as a release yet, and the release notes are not reproduced in the repository listing. The project is licensed GPL-2.0, with a separate Add-On-LICENSE file for add-on components, so if you intend to redistribute a modified dble you should read both files before shipping. Enterprise support plans are offered through ActionTech sales contacts, separate from the GPL codebase.

## Conclusion

dble fits teams that already run MySQL, need horizontal sharding behind an unchanged client, and are prepared to read Chinese documentation. It does not fit teams that need sub-query support today, that want English docs, or that want an open-source build with a release published after November 2023. Before adopting it, verify the ROADMAP status of sub-queries, confirm the MySQL version and storage engine behind each shard, and test the two-phase commit path against a real failure of a shard node rather than trusting the normal mode.

## FAQ

### What is dble and what problem does it solve?

dble is a Java middleware for sharding MySQL, maintained by ActionTech. It lets an application talk to a MySQL-protocol endpoint while the data is spread across multiple MySQL nodes, which is aimed at replacing a single instance that has outgrown one machine.

### Does dble require changing application code to replace MySQL?

The project states you can replace MySQL with dble without changing a single line of code in most cases, because dble speaks the MySQL protocol and supports SQL 92 and the MySQL dialect. Sub-queries are still on the roadmap, so statements using them need checking.

### How does dble handle transactions that span multiple shards?

dble supports distributed transactions using two-phase commit, in either a normal mode chosen for performance or an XA mode chosen for data safety. The XA mode depends on MySQL 5.7 XA transaction support, MySQL node high availability, and disk data reliability.

### How do I build dble from source?

The repository Makefile has a default target that runs a Maven clean install inside a Java 8 Maven Docker image, mounting the working directory as a volume. Release binaries are also offered through the releases page, and Docker and Docker-Compose quick starts are documented in the docs directory.

### What is the difference between dble and MyCat?

dble is based on MyCat. The project says it cancelled support for databases other than MySQL, and improved compatibility, complex query behaviour, and distributed transaction handling while fixing a number of bugs.

## Sources

- [actiontech/dble on GitHub](https://github.com/actiontech/dble)
- [License: GPL-2.0](https://github.com/actiontech/dble/blob/master/LICENSE)
- [Project website](https://opensource.actionsky.com)
- [README](https://github.com/actiontech/dble/blob/master/README.md)
- [Releases](https://github.com/actiontech/dble/releases)

---

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