Sharding Guide
This guide points from the backend docs to the deeper Cabloy sharding architecture.
Current source of truth
The older ORM page for sharding is intentionally thin because the actual sharding capability is provided by the a-cabloy suite.
In the new docs structure, treat sharding as a Cabloy-level capability that affects backend data architecture.
Why this matters
Sharding is not a local model trick. It changes how data distribution, query behavior, transaction expectations, and system-scale architecture are designed.
That means it belongs in the broader Cabloy knowledge graph, even when ORM-facing examples reference it.
When sharding is the right mental model
A useful distinction is:
- ordinary multi-datasource routing chooses among existing datasources
- dynamic datasource chooses a datasource based on runtime context
- sharding changes how data itself is partitioned across the system
This matters because not every scaling problem should immediately be treated as sharding.
Relationship to the broader ORM family
Read this guide together with:
Guidance for contributors and AI workflows
When a task mentions sharding, do not assume ordinary single-database model rules are sufficient.
Instead:
- identify whether the work belongs to core Vona model design or Cabloy sharding infrastructure
- inspect the Cabloy-level sharding guidance and source implementation
- verify whether related concerns such as cache, transactions, relations, and DTO inference still behave correctly under the sharded design
Documentation placement rule
Keep this page as the backend-facing pointer, but treat the Cabloy-level sharding material as the deeper source of truth.