{"id":15430660,"url":"https://github.com/tsukasaoishi/ebisu_connection","last_synced_at":"2025-03-21T01:32:37.860Z","repository":{"id":12423427,"uuid":"15078346","full_name":"tsukasaoishi/ebisu_connection","owner":"tsukasaoishi","description":"EbisuConnection allows access to replica servers","archived":false,"fork":false,"pushed_at":"2022-05-17T06:03:49.000Z","size":97,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-13T07:01:55.563Z","etag":null,"topics":["activerecord","rails","replica","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/tsukasaoishi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-12-10T13:49:01.000Z","updated_at":"2023-08-28T07:34:46.000Z","dependencies_parsed_at":"2022-09-10T19:50:24.698Z","dependency_job_id":null,"html_url":"https://github.com/tsukasaoishi/ebisu_connection","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsukasaoishi%2Febisu_connection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsukasaoishi%2Febisu_connection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsukasaoishi%2Febisu_connection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsukasaoishi%2Febisu_connection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsukasaoishi","download_url":"https://codeload.github.com/tsukasaoishi/ebisu_connection/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244721579,"owners_count":20498978,"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":["activerecord","rails","replica","ruby"],"created_at":"2024-10-01T18:17:55.949Z","updated_at":"2025-03-21T01:32:37.521Z","avatar_url":"https://github.com/tsukasaoishi.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EbisuConnection\n[![Gem Version](https://badge.fury.io/rb/ebisu_connection.svg)](http://badge.fury.io/rb/ebisu_connection) [![Build Status](https://travis-ci.org/tsukasaoishi/ebisu_connection.svg?branch=master)](https://travis-ci.org/tsukasaoishi/ebisu_connection) [![Code Climate](https://codeclimate.com/github/tsukasaoishi/ebisu_connection/badges/gpa.svg)](https://codeclimate.com/github/tsukasaoishi/ebisu_connection)\n\nEbisuConnection allows access to replica servers.  \nYou could assign a performance weight to each replica server.\n\n```\nRails ------------ Master DB\n             |\n             | \n             +---- Replica1 DB (weight 10)\n             |\n             |\n             +---- Replica2 DB (weight 20)\n```\n\nIf you could put a load balancer in front of replica servers, should use [FreshConnection](https://github.com/tsukasaoishi/fresh_connection).\n\n## Usage\n### Access to Replica\nRead query goes to the replica server.\n\n```ruby\nArticle.where(:id =\u003e 1)\n```\n\n### Access to Master\nIf read query want to access to the master server, use `read_master`.  \nIn before version 0.3.1, can use `readonly(false)`.\n\n```ruby\nArticle.where(:id =\u003e 1).read_master\n```\n\nIn transaction, All queries go to the master server.\n\n```ruby\nArticle.transaction do\n  Article.where(:id =\u003e 1)\nend\n```\n\nCreate, Update and Delete queries go to the master server.\n\n```ruby\narticle = Article.create(...)\narticle.title = \"FreshConnection\"\narticle.save\narticle.destory\n```\n\n## Support ActiveRecord version\nEbisuConnection supports ActiveRecord version 5.0 or later.\nIf you are using Rails 4.2, you can use EbisuConnection version 2.4.2 or before.\n\n## Support DB\nEbisuConnection supports MySQL and PostgreSQL.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'ebisu_connection'\n```\n\nAnd then execute:\n\n```\n$ bundle\n```\n\nOr install it yourself as:\n\n```\n$ gem install ebisu_connection\n```\n\n## Config\n\nconfig/database.yml\n\n```yaml\ndefault: \u0026default\n  adapter: mysql2\n  encoding: utf8\n  pool: \u003c%%= ENV.fetch(\"RAILS_MAX_THREADS\") { 5 } %\u003e\n  username: root\n  password:\n\nproduction:\n  \u003c\u003c: *default\n  database: blog_production\n  username: master_db_user\n  password: \u003c%= ENV['MASTER_DATABASE_PASSWORD'] %\u003e\n  host: master_db\n\n  replica:\n    username: replica_db_user\n    password: \u003c%= ENV['REPLICA_DATABASE_PASSWORD'] %\u003e\n```\n\n`replica` is the configuration used for connecting read-only queries to the database replica.  All other connections will use the database master settings.\n\nConfig of each replica server fill out to `config/replica.yml`\n\n```yaml\nproduction:\n  - \"replica1, 10\"\n  - \"replica2, 20\"\n  -\n    host: \"replica3\"\n    weight: 30\n```\n\n```yaml\n\"hostname, weight\"\n```\n\nString format is it. You can write config with hash.\n\n### use multiple replica servers group\nIf you may want to user multiple replica group, write multiple replica group to config/database.yml. \n\n```yaml\ndefault: \u0026default\n  adapter: mysql2\n  encoding: utf8\n  pool: \u003c%%= ENV.fetch(\"RAILS_MAX_THREADS\") { 5 } %\u003e\n  username: root\n  password:\n\nproduction:\n  \u003c\u003c: *default\n  database: blog_production\n  username: master_db_user\n  password: \u003c%= ENV['MASTER_DATABASE_PASSWORD'] %\u003e\n  host: master_db\n\n  replica:\n    username: replica_db_user\n    password: \u003c%= ENV['REPLICA_DATABASE_PASSWORD'] %\u003e\n\n  admin_replica:\n    username: admin_replica_db_user\n    password: \u003c%= ENV['ADMIN_REPLICA_DATABASE_PASSWORD'] %\u003e\n```\n\nConfig of each replica server fill out to `config/replica.yml`\n\n```yaml\nproduction:\n  replica:\n    - \"replica1, 10\"\n    - \"replica2, 20\"\n    -\n      host: \"replica3\"\n      weight: 30\n  admin_replica:\n    - \"replica4, 10\"\n    - \"replica5, 20\"\n```\n\nThe custom replica stanza can then be applied as an argument to the `establish_fresh_connection` method in the models that should use it.  For example:\n\n```ruby\nclass AdminUser \u003c ActiveRecord::Base\n  establish_fresh_connection :admin_replica\nend\n```\n\nThe child (sub) classes of the configured model will inherit the same access as the parent class.  Example:\n\n```ruby\nclass Parent \u003c ActiveRecord::Base\n  establish_fresh_connection :admin_replica\nend\n\nclass AdminUser \u003c Parent\nend\n\nclass Benefit \u003c Parent\nend\n```\n\nThe `AdminUser` and `Benefit` models will access the database configured for the `admin_replica` group.\n\n\n### Master-only Models\n\nIt is possible to declare that specific models always use the DB master for all connections, using the `master_db_only!` method:\n\n```ruby\nclass SomethingModel \u003c ActiveRecord::Base\n  master_db_only!\nend\n```\n\nAll queries generated by methods on the `CustomerState` model will be directed to the DB master.\n\n### Using EbisuConnection With Unicorn\n\n```ruby\nbefore_fork do |server, worker|\n  ...\n  ActiveRecord::Base.clear_all_replica_connections!\n  ...\nend\n```\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n## Test\n\nI'm glad that you would do test!\nTo run the test suite, you need mysql installed.\nHow to setup your test environment.\n\n```bash\n./bin/setup\n```\n\nThis command run the spec suite for all rails versions supported.\n\n```base\n./bin/test\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsukasaoishi%2Febisu_connection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsukasaoishi%2Febisu_connection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsukasaoishi%2Febisu_connection/lists"}