{"id":13714243,"url":"https://github.com/bxcodec/dbresolver","last_synced_at":"2025-04-09T18:17:23.437Z","repository":{"id":47352201,"uuid":"497947677","full_name":"bxcodec/dbresolver","owner":"bxcodec","description":"Golang Database Resolver and Wrapper for any multiple database connections topology, e.g. master-slave replication database, cross-region application, and for separated ReadWrite (RW) and ReadOnly (RO) database connections","archived":false,"fork":false,"pushed_at":"2025-02-24T09:53:51.000Z","size":209,"stargazers_count":162,"open_issues_count":3,"forks_count":15,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-09T18:17:18.869Z","etag":null,"topics":["database","database-replication","dbresolver","global-database","go","golang","master-slave-replication","mysql","postgres","postgresql","sql","sqlite3"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/bxcodec/dbresolver","language":"Go","has_issues":true,"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/bxcodec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["bxcodec"]}},"created_at":"2022-05-30T13:07:59.000Z","updated_at":"2025-04-03T21:17:15.000Z","dependencies_parsed_at":"2024-01-17T09:59:57.472Z","dependency_job_id":"50ed0799-44e1-4562-92af-de7cc25aec35","html_url":"https://github.com/bxcodec/dbresolver","commit_stats":{"total_commits":44,"total_committers":6,"mean_commits":7.333333333333333,"dds":0.2954545454545454,"last_synced_commit":"d0a3ce8e527027dcf80da714356c3265db362a81"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxcodec%2Fdbresolver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxcodec%2Fdbresolver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxcodec%2Fdbresolver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxcodec%2Fdbresolver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bxcodec","download_url":"https://codeload.github.com/bxcodec/dbresolver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085321,"owners_count":21045139,"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":["database","database-replication","dbresolver","global-database","go","golang","master-slave-replication","mysql","postgres","postgresql","sql","sqlite3"],"created_at":"2024-08-02T23:01:55.477Z","updated_at":"2025-04-09T18:17:23.410Z","avatar_url":"https://github.com/bxcodec.png","language":"Go","readme":"# dbresolver\n\nGolang Database Resolver and Wrapper for any multiple database connections topology, eg. master-slave replication database, cross-region application.\n\n[![Go](https://github.com/bxcodec/dbresolver/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/bxcodec/dbresolver/actions/workflows/go.yml)\n[![Go.Dev](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go\u0026logoColor=white)](https://pkg.go.dev/github.com/bxcodec/dbresolver/v2?tab=doc)\n\n## Idea and Inspiration\n\nThis DBResolver library will split your connections to correct defined DBs. Eg, all read query will routed to ReadOnly replica db, and all write operation(Insert, Update, Delete) will routed to Primary/Master DB.\n\n**Read More**\n|Items| Link|  \n------|-----|\n|Blogpost| [blog post](https://betterprogramming.pub/create-a-cross-region-rdbms-connection-library-with-dbresolver-5072bed6a7b8) |\n|Excalidraw| [diagram](https://excalidraw.com/#json=DTs8yxHOGF6uLkjnZny4z,RVo8iwhO0Rk6DRGkKuNZTg)|\n|GoSG Meetup Demo| [repository](https://github.com/bxcodec/dbresolver-examples) |\n| GoSG Presentation | [deck](https://www.canva.com/design/DAFgbpc7tfw/bEXVFtcHEnlFxKVBdnUggA/edit?utm_content=DAFgbpc7tfw\u0026utm_campaign=designshare\u0026utm_medium=link2\u0026utm_source=sharebutton) |\n| Instagram | [post](https://www.instagram.com/p/CnlDFPsBAJG/?utm_source=ig_web_copy_link\u0026igsh=MzRlODBiNWFlZA==)|\n\n### Usecase 1: Separated RW and RO Database connection\n\n\u003cdetails open\u003e\n\n\u003csummary\u003eClick to Expand\u003c/summary\u003e\n\n- You have your application deployed\n- Your application is heavy on read operations\n- Your DBs replicated to multiple replicas for faster queries\n- You separate the connections for optimized query\n- ![readonly-readwrite](https://user-images.githubusercontent.com/11002383/206952018-dd393059-c42c-4ffc-913a-f21c3870bd80.png)\n\n\u003c/details\u003e\n\n### Usecase 2: Cross Region Database\n\n\u003cdetails open\u003e\n\n\u003csummary\u003eClick to Expand\u003c/summary\u003e\n\n- Your application deployed to multi regions.\n- You have your Databases configured globally.\n- ![cross-region](https://user-images.githubusercontent.com/11002383/206952598-ed21a6f8-5542-4f26-aaa6-67d9c2aa5940.png)\n\n\u003c/details\u003e\n\n### Usecase 3: Multi-Master (Multi-Primary) Database\n\n\u003cdetails open\u003e\n\n\u003csummary\u003eClick to Expand\u003c/summary\u003e\n  \n- You're using a Multi-Master database topology eg, Aurora Multi-Master\n- ![multi-master](https://user-images.githubusercontent.com/11002383/206953082-c2b1bfa8-050e-4a6e-88e8-e5c7047edd71.png)\n\n\u003c/details\u003e\n\n## Support\n\nYou can file an [Issue](https://github.com/bxcodec/dbresolver/issues/new).\nSee documentation in [Go.Dev](https://pkg.go.dev/github.com/bxcodec/dbresolver/v2?tab=doc)\n\n## Getting Started\n\n#### Download\n\n```shell\ngo get -u github.com/bxcodec/dbresolver/v2\n```\n\n# Example\n\n### Implementing DB Resolver using \\*sql.DB\n\n\u003cdetails open\u003e\n\n\u003csummary\u003eClick to Expand\u003c/summary\u003e\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"database/sql\"\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/bxcodec/dbresolver/v2\"\n\t_ \"github.com/lib/pq\"\n)\n\nfunc main() {\n\tvar (\n\t\thost1     = \"localhost\"\n\t\tport1     = 5432\n\t\tuser1     = \"postgresrw\"\n\t\tpassword1 = \"\u003cpassword\u003e\"\n\t\thost2     = \"localhost\"\n\t\tport2     = 5433\n\t\tuser2     = \"postgresro\"\n\t\tpassword2 = \"\u003cpassword\u003e\"\n\t\tdbname    = \"\u003cdbname\u003e\"\n\t)\n\t// connection string\n\trwPrimary := fmt.Sprintf(\"host=%s port=%d user=%s password=%s dbname=%s sslmode=disable\", host1, port1, user1, password1, dbname)\n\treadOnlyReplica := fmt.Sprintf(\"host=%s port=%d user=%s password=%s dbname=%s sslmode=disable\", host2, port2, user2, password2, dbname)\n\n\t// open database for primary\n\tdbPrimary, err := sql.Open(\"postgres\", rwPrimary)\n\tif err != nil {\n\t\tlog.Print(\"go error when connecting to the DB\")\n\t}\n\t// configure the DBs for other setup eg, tracing, etc\n\t// eg, tracing.Postgres(dbPrimary)\n\n\t// open database for replica\n\tdbReadOnlyReplica, err := sql.Open(\"postgres\", readOnlyReplica)\n\tif err != nil {\n\t\tlog.Print(\"go error when connecting to the DB\")\n\t}\n\t// configure the DBs for other setup eg, tracing, etc\n\t// eg, tracing.Postgres(dbReadOnlyReplica)\n\n\tconnectionDB := dbresolver.New(\n\t\tdbresolver.WithPrimaryDBs(dbPrimary),\n\t\tdbresolver.WithReplicaDBs(dbReadOnlyReplica),\n\t\tdbresolver.WithLoadBalancer(dbresolver.RoundRobinLB))\n\n\tdefer connectionDB.Close()\n\t// now you can use the connection for all DB operation\n\t_, err = connectionDB.ExecContext(context.Background(), \"DELETE FROM book WHERE id=$1\") // will use primaryDB\n\tif err != nil {\n\t\tlog.Print(\"go error when executing the query to the DB\", err)\n\t}\n\tconnectionDB.QueryRowContext(context.Background(), \"SELECT * FROM book WHERE id=$1\") // will use replicaReadOnlyDB\n}\n```\n\n\u003c/details\u003e\n\n## Important Notes\n\n- Primary Database will be used when you call these functions\n  - `Exec`\n  - `ExecContext`\n  - `Begin` (transaction will use primary)\n  - `BeginTx`\n  - Queries with `\"RETURNING\"` clause\n    - `Query`\n    - `QueryContext`\n    - `QueryRow`\n    - `QueryRowContext`\n- Replica Databases will be used when you call these functions\n  - `Query`\n  - `QueryContext`\n  - `QueryRow`\n  - `QueryRowContext`\n\n## Contribution\n\nTo contrib to this project, you can open a PR or an issue.\n","funding_links":["https://github.com/sponsors/bxcodec"],"categories":["Repositories"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbxcodec%2Fdbresolver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbxcodec%2Fdbresolver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbxcodec%2Fdbresolver/lists"}