PHPackages                             doctrine/shards - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. doctrine/shards

AbandonedArchivedLibrary[Database & ORM](/categories/database)

doctrine/shards
===============

v1.0(14y ago)2553.8k↑66.7%4[1 issues](https://github.com/doctrine/shards/issues)PHP

Since May 1Pushed 14y ago12 watchersCompare

[ Source](https://github.com/doctrine/shards)[ Packagist](https://packagist.org/packages/doctrine/shards)[ RSS](/packages/doctrine-shards/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (1)Versions (5)Used By (0)

Doctrine Shards
===============

[](#doctrine-shards)

Doctrine Extension to support horizontal sharding in the Doctrine ORM.

Idea
----

[](#idea)

Implement sharding inside Doctrine at a level that is as unobtrusive to the developer as possible.

Problems to tackle:

1. Where to send INSERT statements?
2. How to generate primary keys?
3. How to pick shards for update, delete statements?
4. How to pick shards for select operations?
5. How to merge select queries that span multiple shards?
6. How to handle/prevent multi-shard queries that cannot be merged (GROUP BY)?
7. How to handle non-sharded data? (static metadata tables for example)
8. How to handle multiple connections?
9. Implementation on the DBAL or ORM level?

Roadmap
-------

[](#roadmap)

Version 1: DBAL 2.3 (Multi-Tenant Apps)

```
1. ID Generation support (in DBAL + ORM done)
2. Multi-Tenant Support: Either pick a global metadata database or exactly one shard.
3. Fan-out queries over all shards (or a subset) by result appending

```

Version 2: ORM related (complex):

```
4. ID resolving (Pick shard for a new ID)
5. Query resolving (Pick shards a query should send to)
6. Shard resolving (Pick shards an ID could be on)
7. Transactions
8. Read Only objects

```

Technical Requirements for Database Schemas
-------------------------------------------

[](#technical-requirements-for-database-schemas)

Sharded tables require the sharding-distribution key as one of their columns. This will affect your code compared to a normalized db-schema. If you have a Blog <-> BlogPost <-> PostComments entity setup sharded by `blog_id` then even the PostComment table needs this column, even if an "unsharded", normalized DB-Schema does not need this information.

Implementation Details
----------------------

[](#implementation-details)

Assumptions:

- For querying you either want to query ALL or just exactly one shard.
- IDs for ALL sharded tables have to be unique across all shards.
- Non-shareded data is replicated between all shards. They redundantly keep the information available. This is necessary so join queries on shards to reference data work.
- If you retrieve an object A from a shard, then all references and collections of this object reside on the same shard.
- The database schema on all shards is the same (or compatible)

### SQL Azure Federations

[](#sql-azure-federations)

SQL Azure is a special case, points 1, 2, 3, 4, 7 and 8 are partly handled on the database level. This makes it a perfect test-implementation for just the subset of features in points 5-6. However there need to be a way to configure SchemaTool to generate the correct Schema on SQL Azure.

- SELECT Operations: The most simple assumption is to always query all shards unless the user specifies otherwise explicitly.
- Queries can be merged in PHP code, this obviously does not work for DISTINCT, GROUP BY and ORDER BY queries.

### Generic Sharding

[](#generic-sharding)

More features are necessary to implement sharding on the PHP level, independent from database support:

1. Configuration of multiple connections, one connection = one shard.
2. Primary Key Generation mechanisms (UUID, central table, sequence emulation)

Primary Use-Cases
-----------------

[](#primary-use-cases)

1. Multi-Tenant Applications

These are easier to support as you have some value to determine the shard id for the whole request very early on. Here also queries can always be limited to a single shard.

2. Scale-Out by some attribute (Round-Robin?)

This strategy requires access to multiple shards in a single request based on the data accessed.

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance19

Infrequent updates — may be unmaintained

Popularity36

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 91.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

4

Last Release

5123d ago

Major Versions

v0.3 → v1.02012-05-08

### Community

Maintainers

![](https://www.gravatar.com/avatar/892698bb1d3f6dae0e3a44abe3e26920ddb4eb000c6c583c87b4db5e5027e166?d=identicon)[beberlei](/maintainers/beberlei)

---

Top Contributors

[![beberlei](https://avatars.githubusercontent.com/u/26936?v=4)](https://github.com/beberlei "beberlei (22 commits)")[![guilhermeblanco](https://avatars.githubusercontent.com/u/208883?v=4)](https://github.com/guilhermeblanco "guilhermeblanco (1 commits)")[![tommygnr](https://avatars.githubusercontent.com/u/929392?v=4)](https://github.com/tommygnr "tommygnr (1 commits)")

### Embed Badge

![Health badge](/badges/doctrine-shards/health.svg)

```
[![Health](https://phpackages.com/badges/doctrine-shards/health.svg)](https://phpackages.com/packages/doctrine-shards)
```

###  Alternatives

[scienta/doctrine-json-functions

A set of extensions to Doctrine that add support for json query functions.

58723.9M36](/packages/scienta-doctrine-json-functions)[martin-georgiev/postgresql-for-doctrine

Extends Doctrine with native PostgreSQL support for arrays, JSONB, ranges, PostGIS geometries, text search, ltree, uuid, and 100+ PostgreSQL-specific functions.

4485.3M4](/packages/martin-georgiev-postgresql-for-doctrine)[damienharper/auditor-bundle

Integrate auditor library in your Symfony projects.

4542.8M](/packages/damienharper-auditor-bundle)[sonata-project/entity-audit-bundle

Audit for Doctrine Entities

644989.8k1](/packages/sonata-project-entity-audit-bundle)[overtrue/laravel-versionable

Make Laravel model versionable.

585308.0k5](/packages/overtrue-laravel-versionable)[worksome/foggy

Foggy is a tool for making database dumps with some data removed/changed.

26571.7k1](/packages/worksome-foggy)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)