agentsclimarketplace

Sharding strategy

Skill jacob-balslev/skills/skills/data-engineering/sharding-strategy

Public Agent Skills library exported from skill-graph. Install: npx skills add jacob-balslev/skills

Install
npx -y skills add jacob-balslev/skills --skill sharding-strategy

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when reasoning about horizontal partitioning of data across nodes for storage capacity and write throughput beyond a single node: the three foundational partitioning schemes (range, hash, directory/lookup), the shard-key choice that determines whether the system scales or hotspots, the resharding problem and how consistent hashing addresses it, cross-shard queries and the joins-and-transactions trade-off, the relationship to replication (sharding partitions data; replication copies each shard), and the failure modes (hot shard, skewed distribution, cross-shard transactions, range-end overload). Do NOT use for replicating the same data across nodes (use replication-patterns), the CAP/PACELC frame (use cap-theorem-tradeoffs), single-node performance tuning (use query-optimization), or indexing within a shard (use indexing-strategy).

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

26.5 KB, ~2.6k tokens by cl100k_base, as published. Nobody here has run it

Sharding Strategy

Concept of the skill

Sharding (horizontal partitioning) is the discipline of dividing a database's data across multiple nodes so each node holds a subset — a shard. The unit of judgment is the shard key: the column or columns the system uses to route each row to a specific shard. Three foundational schemes: range partitioning (contiguous shard-key value ranges per shard — strong for range queries BETWEEN x AND y; weak for hotspots at range boundaries and for resharding-by-split), hash partitioning (hash(shard_key) % N — strong for even balance and no range hotspots; weak for range queries which become scatter-gather, and for resharding which rehashes nearly all data), consistent hashing (hash ring with each key routed to the nearest clockwise shard — adding shards moves only 1/N of data; virtual nodes place each physical shard at many ring positions to reduce imbalance), and directory / lookup partitioning (explicit map per key or key-range — strong for arbitrary placement; weak because the directory itself becomes a bottleneck).

Replaces "scale vertically forever" with horizontal capacity for write throughput, storage, and geographic placement. Solves the problem that when write throughput exceeds the primary's capacity, when storage approaches the node's limit, or when geographic placement is regulatory or latency-driven, the simpler single-node tools — replication (scales reads), caching (reduces load), denormalization (eliminates joins), vertical scaling (adds capacity) — are no longer sufficient. Sharding is the scaling tool of last resort — reached for only when the simpler tools are exhausted, because it adds operational complexity proportional to the gain. The shard key is the most consequential design decision: a well-chosen key gives nearly linear scaling; a poorly-chosen key pays operational complexity without capacity gain — hotspots concentrate on one shard, common queries scatter-gather across all shards, transactions require two-phase commit and become slow and failure-prone. The schema must be designed with sharding in mind from the start, or significant refactoring is required when sharding is later introduced.

Distinct from replication-patterns, which owns copying the same data across nodes for fault tolerance and read scaling; this skill owns dividing different data across nodes for write throughput and storage capacity. The two compose in production because each shard is usually replicated, but they answer different questions. It is also distinct from cap-theorem-tradeoffs, indexing-strategy, entity-relationship-modeling, query-optimization, and transaction-isolation; those skills own the theory frame, within-shard retrieval, schema design, single-query tuning, and single-system transactions respectively.

Coverage

The discipline of dividing a database's data across multiple nodes through horizontal partitioning. Covers the three foundational partitioning schemes (range, hash, directory), consistent hashing as the refinement that solves the resharding problem, the shard-key choice as the most consequential design decision, the cross-shard query and transaction trade-offs, the catalog of failure modes (hot shard, skewed distribution, range-boundary overload), the relationship to replication (sharding divides; replication copies; they compose), and the rule that sharding is one of the last optimizations to reach for after replication, caching, and denormalization.

Philosophy of the skill

Sharding is the scaling tool of last resort. Replication scales reads; caching reduces load; denormalization eliminates joins; vertical scaling adds capacity. When write throughput, storage capacity, or geographic data placement exceeds what those tools provide, sharding becomes the answer.

The shard key is the most consequential design decision. It determines which queries are fast (single-shard) and which are slow (scatter-gather), which operations are atomic (single-shard) and which require distributed commit (cross-shard), which growth patterns hotspot and which balance. A team that chooses the shard key well gains nearly linear scaling; a team that chooses it poorly pays operational complexity without capacity gain.

The schema must be designed with sharding in mind from the start, or significant refactoring is required when sharding is later introduced. Queries must filter on the shard key; related data must be co-located on the same shard; cross-shard operations must be rare or accepted as slow. Sharding is a schema architecture, not just an operational technique.

The Three Partitioning Schemes

SchemeHow it routesStrong forWeak for
RangeContiguous key ranges per shardRange queries (BETWEEN x AND y)Hotspots at range boundaries; resharding by split
HashHash(key) % NEven balance; no range hotspotsRange queries become scatter-gather; resharding rehashes
Consistent hashingHash ring; key → nearest clockwise virtual nodeAdding shards moves only about 1/N of data; virtual nodes smooth imbalanceRange queries still scatter-gather; virtual-node maps must be maintained
DirectoryExplicit map per keyFlexibility; arbitrary routingThe directory itself becomes a bottleneck

Hash with consistent hashing is the default for most large-scale systems; range partitioning is used for time-series and naturally-ordered data; directory is rare but useful for arbitrary placement.

The Shard-Key Selection Rules

A good shard key:

  1. Appears in nearly every query's WHERE clause — for shard-locality.
  2. Distributes data evenly — high cardinality; no value dominates traffic.
  3. Is immutable for a row — moving a row between shards is expensive.
  4. Has predictable growth — won't shift hotspots over time.
  5. Matches the natural grain of operations — common transactions are single-shard.

Common keys:

  • Multi-tenant SaaS: tenant_id. Most queries are tenant-scoped; tenants are independent.
  • Per-user data: user_id. Most queries are user-scoped.
  • Time-series: time_bucket(timestamp). Recent shards hot; older shards cold (often acceptable for time-series).
  • Geographic: region. Latency benefit; regulatory benefit.

Bad keys:

  • created_at (range hotspot at latest range).
  • status (low cardinality; one value dominates).
  • A column not in most query WHERE clauses (scatter-gather every query).

Cross-Shard Query Trade-offs

OperationSingle-shardCross-shard
Lookup by shard keyFastn/a (must include shard key)
Lookup not using shard keySingle-shard if data co-locatedScatter to every shard
JOINFast within shardSlow or unavailable
AggregationFastScatter-gather; partial-aggregate-then-combine
TransactionACID via single-shard primaryTwo-phase commit or distributed consensus; slow and failure-prone

Schema design under sharding co-locates related data (store user's orders on user's shard) to make JOINs and transactions single-shard.

When Sharding Is The Right Tool

Workload propertyTool
Read load too highReplication (read replicas)
Cache hit rate possibleCaching layer
Joins / aggregations slowDenormalization, materialized views
Single-node CPU/memory exceededVertical scaling
Storage approaching node limitSharding (or larger disks first)
Write throughput exceeds primarySharding
Geographic latency requiredSharding by region (with replication within region)
Multi-tenant isolation requiredSharding by tenant

Sharding is the answer when write throughput or storage exceeds single-node capacity. Before that, simpler tools suffice.

Verification

After applying this skill, verify:

  • Sharding is being considered after replication, caching, denormalization, and vertical scaling — not as a first response.
  • The shard key is chosen against the criteria: appears in queries, distributes evenly, immutable, predictable, matches operation grain.
  • Most production queries are single-shard. Scatter-gather queries are recognized as expensive and made rare.
  • Related data is co-located on the same shard for JOIN and transaction locality.
  • Cross-shard transactions are rare. Application design avoids them where possible.
  • Resharding plan exists before launch: how shards are added, how data moves, what downtime is expected.
  • Hot-shard detection is in place. Per-shard load metrics surface hotspots before they become incidents.
  • Consistent hashing is used over modulo hash where resharding is anticipated. Naive hash modulo locks the shard count.
  • The cross-shard query cost is documented and accepted. Reports and analytics that scatter-gather are run on read replicas or designed for the cost.
  • Sharding interacts with replication intentionally — each shard's replication strategy is designed, not defaulted.

Do NOT Use When

Instead of this skillUseWhy
Copying the same data to multiple nodesreplication-patternsreplication copies; sharding partitions
The CAP / PACELC theoretical framecap-theorem-tradeoffsCAP names the trade-off
Tuning a slow queryquery-optimizationquery-optimization is single-query
Designing indexes within a shardindexing-strategyindexing is within-node
Designing schemaentity-relationship-modelingentity-relationship-modeling is the schema design; this is the partitioning of the schema
Single-node transactional behaviortransaction-isolationACID is the single-system frame

Key Sources

Gives 0 of the 12 instructions most performance cost skills give in ~2.6k tokens

Counted across 803 of the 1,058 authors here whose files we hold, read 2026-08-07

  • keep skill files under 500 linesin 82 of 803, across 16 files
  • use imperative form in instructionsin 80 of 803, across 9 files
  • draft assertions while test runs are in progressin 75 of 803, across 9 files
  • create two to three realistic test promptsin 74 of 803, across 9 files
  • write skill descriptions to be pushyin 72 of 803, across 7 files
  • save test cases to evals jsonin 72 of 803, across 6 files
  • ask questions about edge cases and input formatsin 72 of 803, across 7 files
  • save timing data immediately when runs completein 70 of 803, across 5 files
  • include all trigger conditions in the skill descriptionin 69 of 803, across 3 files
  • launch all test runs in a single turnin 69 of 803, across 3 files
  • capture intent before writing a skillin 67 of 803, across 1 file
  • import directly instead of barrel filesin 52 of 803, across 15 files

Said here and by no other author read

  • design the schema for sharding from the start
  • choose a shard key present in most queries
  • choose a high-cardinality evenly-distributed shard key
  • co-locate related data on the same shard
  • keep cross-shard transactions rare
  • use consistent hashing when resharding is anticipated

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.