{"id":22835690,"url":"https://github.com/longbridge/gorm-sharding","last_synced_at":"2025-08-10T21:31:26.823Z","repository":{"id":37780815,"uuid":"447066735","full_name":"longbridge/gorm-sharding","owner":"longbridge","description":"High performance table sharding plugin for Gorm.","archived":false,"fork":false,"pushed_at":"2022-01-19T06:10:54.000Z","size":105,"stargazers_count":111,"open_issues_count":0,"forks_count":75,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-12-10T00:26:27.885Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/go-gorm/sharding","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/longbridge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-12T03:43:00.000Z","updated_at":"2024-11-30T00:54:06.000Z","dependencies_parsed_at":"2022-09-01T06:11:03.620Z","dependency_job_id":null,"html_url":"https://github.com/longbridge/gorm-sharding","commit_stats":null,"previous_names":["longbridge/gorm-sharding"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbridge%2Fgorm-sharding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbridge%2Fgorm-sharding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbridge%2Fgorm-sharding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbridge%2Fgorm-sharding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/longbridge","download_url":"https://codeload.github.com/longbridge/gorm-sharding/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229180763,"owners_count":18032473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-12T23:00:25.560Z","updated_at":"2024-12-12T23:01:29.589Z","avatar_url":"https://github.com/longbridge.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Gorm Sharding\n\nThis project has moved to Gorm offical organization: \n\nhttps://github.com/go-gorm/sharding\n\n[![Go](https://github.com/longbridgeapp/gorm-sharding/actions/workflows/go.yml/badge.svg)](https://github.com/longbridgeapp/gorm-sharding/actions/workflows/go.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/longbridgeapp/gorm-sharding.svg)](https://pkg.go.dev/github.com/longbridgeapp/gorm-sharding)\n\n[Gorm](https://github.com/go-gorm/gorm) Sharding plugin using SQL parser and replace for splits large tables into smaller ones, redirects Query into sharding tables. Give you a high performance database access.\n\nGorm Sharding 是我们基于 Longbridge 的业务场景以及我们的实践经验构建出来的一个高性能的数据库分表中间件。\n\n它基于 Conn 层做 SQL 拦截、AST 解析、分表路由、自增主键填充，带来的额外开销极小。对开发者友好、透明，使用上与普通 SQL、[Gorm](https://github.com/go-gorm/gorm) 查询无差别，只需要额外注意一下分表键条件。\n\n## Features\n\n- Non-intrusive design. Load the plugin, specify the config, and all done.\n- Lighting-fast. No network based middlewares, as fast as Go.\n- Multiple database support. PostgreSQL tested, MySQL and SQLite is coming.\n- Allows you custom the Primary Key generator (Sequence, UUID, Snowflake ...).\n\n## Sharding process\n\nThis graph show up how Gorm Sharding works.\n\n![Example](./docs/query.svg)\n\n## Install\n\n```bash\ngo get -u github.com/longbridgeapp/gorm-sharding\n```\n\n## Usage\n\nOpen a db session.\n\n```go\ndsn := \"postgres://localhost:5432/sharding-db?sslmode=disable\"\ndb, err := gorm.Open(postgres.New(postgres.Config{DSN: dsn}))\n```\n\nConfig the sharding middleware, register the tables which you want to shard. See [Godoc](https://pkg.go.dev/github.com/longbridge/gorm-sharding) for config details.\n\n```go\ndb.Use(\u0026sharding.Register(map[string]sharding.Resolver{\n    \"orders\": {\n        ShardingColumn: \"user_id\",\n        ShardingAlgorithm: func(value interface{}) (suffix string, err error) {\n            if uid, ok := value.(int64); ok {\n                return fmt.Sprintf(\"_%02d\", uid%4), nil\n            }\n            return \"\", errors.New(\"invalid user_id\")\n        },\n        PrimaryKeyGenerate: func(tableIdx int64) int64 {\n            return node.Generate()\n        },\n    },\n    \"notifications\": {\n       // ... sharding rule for notifications table\n    },\n}))\n```\n\nUse the db session as usual. Just note that the query should have the `Sharding Key` when operate sharding tables.\n\n```go\n// Gorm create example, this will insert to orders_01\ndb.Create(\u0026Order{UserID: 2})\n// sql: INSERT INTO orders_2 ...\n\n// Show have use Raw SQL to insert, this will insert into orders_04\ndb.Exec(\"INSERT INTO orders(user_id) VALUES(?)\", int64(3))\n\n// This will throw ErrMissingShardingKey error, because there not have sharding key presented.\ndb.Create(\u0026Order{Amount: 10, ProductID: 100})\nfmt.Println(err)\n\n// Find, this will redirect query to orders_03\nvar orders []Order\ndb.Model(\u0026Order{}).Where(\"user_id\", int64(2)).Find(\u0026orders)\nfmt.Printf(\"%#v\\n\", orders)\n\n// This will throw ErrMissingShardingKey error, because WHERE conditions not included sharding key\nerr = db.Model(\u0026Order{}).Where(\"product_id\", \"1\").Find(\u0026orders).Error\nfmt.Println(err)\n\n// Update and Delete are similar to create and query\ndb.Exec(\"UPDATE orders SET product_id = ? WHERE user_id = ?\", 2, int64(3))\nerr = db.Exec(\"DELETE FROM orders WHERE product_id = 3\").Error\nfmt.Println(err) // ErrMissingShardingKey\n```\n\nThe full example is [here](./examples/order.go).\n\n## Primary Key\n\nWhen you sharding tables, you need consider how the primary key generate.\n\n\nRecommend options:\n\n- [Built in keygen](https://github.com/longbridgeapp/gorm-sharding/tree/main/keygen)\n- [Database sequence by manully](https://www.postgresql.org/docs/current/sql-createsequence.html)\n- [UUID](https://github.com/google/uuid)\n- [Snowflake](https://github.com/bwmarrin/snowflake)\n\n\n## License\n\nThis project under MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongbridge%2Fgorm-sharding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flongbridge%2Fgorm-sharding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongbridge%2Fgorm-sharding/lists"}