gorm-sharding

Route GORM database operations to shards for PostgreSQL and MySQL tables.

Updated Apr 4, 2026
One-click install
npx skills add https://github.com/liurida/gorm-development-skill --skill gorm-sharding
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: gorm-sharding
Source: https://github.com/liurida/gorm-development-skill/tree/main/sharding
Command: npx skills add https://github.com/liurida/gorm-development-skill --skill gorm-sharding

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

The GORM sharding plugin routes database operations to the correct physical shard for horizontally partitioned tables, preventing ambiguous queries, failed operations, and inconsistent primary key generation across distributed datasets.

Core Features & Use Cases

  • Plugin-based interception: Automatically rewrites GORM queries to target shard-specific tables based on a sharding key.
  • Customizable routing: Supports modulo-based routing and user-defined sharding algorithms for complex distribution rules.
  • Shard-aware primary keys: Integrates with generators like Snowflake or PostgreSQL sequences to provide globally unique IDs across shards.
  • Operational guidance: Requires pre-creating shard tables, always including the sharding key in WHERE clauses to avoid ErrMissingShardingKey, and avoiding cross-shard joins by design.
  • Use Case: Scale an orders table across 64 shards so each user's orders are routed to and queried from a single shard, improving write throughput and storage distribution.

Quick Start

Register the GORM sharding plugin with ShardingKey set to user_id, choose NumberOfShards, create the per-shard tables, and then run your normal Create/Read/Update/Delete operations including the sharding key.

Frequently Asked Questions about gorm-sharding

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I scale a PostgreSQL database horizontally with GORM?

To scale PostgreSQL horizontally with GORM, register a sharding plugin with a defined ShardingKey and NumberOfShards, pre-create per-shard tables, and use shard-aware primary keys like Snowflake to route create, read, update, and delete operations to the correct physical shard.

Why do I need to include a sharding key in every GORM query?

You must include a sharding key in GORM queries to determine the target shard for horizontally partitioned tables. Omitting the sharding key from WHERE clauses prevents the plugin from routing the operation and triggers an ErrMissingShardingKey error.

Can I use auto-increment IDs for primary key generation across MySQL shards?

You cannot use auto-increment IDs for primary key generation across MySQL shards because they cause inconsistent IDs across distributed datasets. You must use a shard-aware primary key generator such as Snowflake or PostgreSQL sequences to provide globally unique IDs.

Does GORM sharding support custom routing algorithms for complex data distribution?

GORM sharding supports custom routing algorithms for complex data distribution by allowing user-defined sharding algorithms alongside default modulo-based routing, intercepting and rewriting GORM queries to target shard-specific tables based on your custom rules.

What are the limitations of horizontal sharding for relational databases?

Limitations of horizontal sharding include avoiding cross-shard joins by design and the requirement to pre-create per-shard tables. You must also consistently include the sharding key in operations to prevent ambiguous queries and failed database operations.

What is the best way to route database operations to appropriate shards for partitioned tables?

The best way to route database operations to appropriate shards is using a GORM plugin-based interception mechanism that rewrites queries to target shard-specific tables, requiring a defined ShardingKey and NumberOfShards to distribute records like an orders table across 64 shards for improved write throughput.