Apache ShardingSphere: JDBC and Proxy Access Ends for Sharded Databases

What ShardingSphere adds above an existing database

ShardingSphere does not create a new database. The README describes it as a layer above heterogeneous databases, and the repository layout matches that claim: kernel, parser, jdbc, proxy, mode, features and infra sit alongside a database directory rather than replacing it. The problem it targets is a familiar one. An application has outgrown one MySQL or PostgreSQL instance, but replacing the database means a migration project and a new vendor relationship. ShardingSphere instead intercepts the SQL, rewrites it, and routes it to several existing databases.

The audience is narrower than the tagline suggests. ShardingSphere-JDBC is for Java applications that can add a dependency and share resources with the driver. ShardingSphere-Proxy is for everything else: services in other languages, DBAs who want a single connection endpoint, and environments where a static entry point matters more than in-process latency. The README states that the two can be deployed independently or in hybrid deployment, configured through the same registry center.

One number in the README is worth reading carefully. It says the project has been adopted by 19,000+ projects, and links to a GitHub code search for Maven POM files mentioning shardingsphere. That is a measure of how often the artifact appears in build files, not of production deployments or of how many of those projects are still running it.

The dual-access architecture: JDBC driver versus standalone Proxy

The mechanism is the same on both ends. SQL arrives, the parser turns it into an abstract syntax tree, the kernel applies rules (sharding, readwrite-splitting, encryption, masking), and the rewritten SQL goes to the physical databases. The difference is where that pipeline runs.

ShardingSphere-JDBC is a JAR. It runs inside the application JVM, shares resources with it, and connects directly to the databases. The README calls it decentralized and says it is compatible with ORM frameworks such as MyBatis, JPA and Hibernate. It also states there is no independent deployment. That is the appeal: no extra process, no extra network hop, no extra thing to keep alive. The cost is that every application instance carries the enhancement logic, and upgrading it means redeploying the application.

ShardingSphere-Proxy is a server. It speaks the MySQL or PostgreSQL wire protocol, so any client compatible with those protocols can connect without a ShardingSphere-specific driver. The README lists cluster deployment, load balancing and failover for it, and describes it as DBA friendly. That is the opposite trade: one place to configure and one place to upgrade, but a new hop in every query and a new component whose availability your application now depends on.

The README does not give latency figures for either end, so the choice has to be made on operational grounds rather than on published benchmarks.

Installing ShardingSphere-JDBC and running a first sharded query

The README does not include install steps. It points to the official website at shardingsphere.apache.org, and the repository ships an examples directory containing shardingsphere-jdbc-example-generator and shardingsphere-parser-example. Treat those examples as the starting point rather than the README.

The README names the JDBC access end as ShardingSphere-JDBC and describes it as a lightweight Java framework provided as a JAR package, with no independent deployment required. It does not print a dependency block, a version number, or a configuration sample, so the exact artifact coordinates and the YAML shape have to come from the official documentation or from the examples directory. What the README does establish is the structure of the configuration: a mode, a set of data sources, and one or more rules, all expressed as YAML. The related searches around shardingsphere jdbc maven and the Spring Boot starter point at the same access end.

Because the repository gives no copy-ready snippet, the first real use is a reading exercise before it is a coding one. Open examples/shardingsphere-jdbc-example-generator, follow how it declares data sources and rules, and adapt that shape to your own databases. The README does not document a rollback path once a rule is applied, so the first run should target a schema you can recreate. After one query, check the physical tables directly to confirm where the rows landed.

Where ShardingSphere is the wrong tool

The parser is the constraint. ShardingSphere does not pass SQL through untouched. It parses, rewrites and routes it, which means any statement the parser cannot handle is a statement you cannot run. The repository keeps a dedicated parser module and a jdbc-dialect module precisely because dialect coverage is work. If your application relies on vendor-specific syntax, stored procedures, or a query shape the parser does not cover, the enhancement layer becomes an obstacle rather than a convenience.

The second failure mode is configuration drift. In a hybrid deployment, JDBC and Proxy read the same registry center. That is the design, and it is also the risk: a rule change reaches every application instance and every proxy at once. There is no staged rollout described in the README.

The third case is simpler. If you have one database that fits comfortably on one machine, ShardingSphere adds a parser and a routing layer to solve a problem you do not have. The README's own comparison is against distributed databases and cloud vendor solutions, not against running a single PostgreSQL instance well.

Finally, the last push to the repository was on 2026-02-28, the same date as the 5.5.3 release. The previous release, 5.5.2, was on 2025-01-22. That is a gap of roughly thirteen months between releases, which is worth knowing before you plan an upgrade cadence around it.

ShardingSphere compared with Vitess and with doing nothing

The related searches include shardingsphere vs vitess and shardingsphere alternative, so the comparison is worth making on architecture rather than on feature lists. Vitess is a MySQL sharding system built around a proxy and its own control plane, with a strong opinion about how the sharded keyspace is defined. ShardingSphere keeps the databases as they are and puts the intelligence in a driver or a proxy that speaks the native MySQL or PostgreSQL protocol.

The practical difference is where your existing tooling keeps working. With ShardingSphere-Proxy, a client connects as if to MySQL or PostgreSQL, so existing clients keep working, but the sharding rules live in ShardingSphere YAML rather than in the database. With ShardingSphere-JDBC, there is no proxy at all: the application carries the logic, and non-Java services cannot use that path.

The alternative to both is to shard in the application or to move to a database that shards natively. That removes the parser from the query path entirely and puts the complexity in your code or in a vendor. ShardingSphere's stated position is that it is more lightweight than a distributed database and avoids vendor lock-in. Whether that holds depends on how much of your SQL the parser accepts and how much YAML you are willing to own.

Licence, releases and the cost of staying current

ShardingSphere is released under Apache-2.0, and the repository carries LICENSE and NOTICE files at the top level. Apache-2.0 permits commercial use and modification, and it includes a patent grant. It does not give legal advice, and it does not cover the licences of the databases or drivers you connect to. If you redistribute a distribution built from this repository, the NOTICE file is the one to read.

The upgrade cost is the real operating cost. The release list shows 5.5.1 in October 2024, 5.5.2 in January 2025, and 5.5.3 on 2026-02-28. Between 5.5.2 and 5.5.3 there is more than a year. That cadence matters because ShardingSphere sits in the query path: an upgrade changes parsing and routing behaviour, not just a library API. In a JDBC deployment, upgrading means rebuilding and redeploying every application that embeds the driver. In a Proxy deployment, it means restarting the entry point that all clients share.

The README does not document a rollback procedure, and it does not describe a compatibility matrix between ShardingSphere versions and database versions. Both are things to confirm against the official documentation before you commit to a version.

Editorial conclusion

Adopt ShardingSphere when you already run MySQL or PostgreSQL and need sharding, readwrite-splitting or masking without replacing the database, and when you are willing to own a YAML configuration that every query passes through. Do not adopt it for a single small database, or if you need a feature the README does not list, since the README does not document rollback or downgrade. Before committing, verify three things in your own environment: that the ShardingSphere-JDBC artifact version matches your Java and Spring Boot versions, that your SQL survives the parser for the statements you actually run, and that a failed Proxy instance leaves a working entry point.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes