{"id":23782581,"url":"https://github.com/joinhandshake/knockoff","last_synced_at":"2025-09-06T01:32:42.803Z","repository":{"id":40617430,"uuid":"74906287","full_name":"joinhandshake/knockoff","owner":"joinhandshake","description":"A gem for easily using read replicas.","archived":false,"fork":false,"pushed_at":"2024-12-17T16:31:12.000Z","size":126,"stargazers_count":20,"open_issues_count":1,"forks_count":7,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-12-30T12:33:35.082Z","etag":null,"topics":["activerecord","deprecated","deprecated-unmaintained","no-maintenance-intended","replica-databases","replicas","ruby-gem"],"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/joinhandshake.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-27T18:29:46.000Z","updated_at":"2024-12-16T21:50:18.000Z","dependencies_parsed_at":"2024-01-08T18:46:35.021Z","dependency_job_id":"a47b25a7-962f-4435-8743-424eb1c47205","html_url":"https://github.com/joinhandshake/knockoff","commit_stats":null,"previous_names":["sgringwe/knockoff"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joinhandshake%2Fknockoff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joinhandshake%2Fknockoff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joinhandshake%2Fknockoff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joinhandshake%2Fknockoff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joinhandshake","download_url":"https://codeload.github.com/joinhandshake/knockoff/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232076655,"owners_count":18469237,"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","deprecated","deprecated-unmaintained","no-maintenance-intended","replica-databases","replicas","ruby-gem"],"created_at":"2025-01-01T12:16:13.348Z","updated_at":"2025-01-01T12:16:13.943Z","avatar_url":"https://github.com/joinhandshake.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!Important]  \n\u003e This gem is deprecated and no longer updated.\n\u003e \n\u003e This functionality is natively supported by Rails since 6.1\n\n# [Deprecated] Knockoff\n\n[![Build Status](https://github.com/joinhandshake/knockoff/actions/workflows/ruby.yml/badge.svg)](https://github.com/joinhandshake/knockoff/actions)\n[![Gem Version](https://badge.fury.io/rb/knockoff.svg)](https://badge.fury.io/rb/knockoff)\n\nA gem for easily using read replicas.\n\n:handshake: Battle tested at [Handshake](https://joinhandshake.com/)\n\n## Library Goals\n\n* Minimal ActiveRecord monkey-patching\n* Easy run-time configuration using ENV variables\n* Opt-in usage of replicas\n* No need to change code when adding/removing replicas\n* Be thread safe\n\n## Supported Versions\n\n| Knockoff version: | 1.0 | 1.1.0 | 1.1.1 | 1.4 | 1.5 |\n| --- | --- | --- | --- | --- | --- |\n| Ruby 2.2 | :heavy_check_mark: |  |  |  |  |\n| Ruby 2.3 | :heavy_check_mark: | :heavy_check_mark: |  |  |  |\n| Ruby 2.4 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |  |  |\n| Ruby 2.5 |  | :heavy_check_mark: | :heavy_check_mark: |  |  |\n| Ruby 2.6 |  |  | :heavy_check_mark: | :heavy_check_mark: |  |\n| Ruby 2.7 |  |  | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |\n| Ruby 3.0 |  |  |  | :heavy_check_mark: | :heavy_check_mark: |\n| Ruby 3.1 |  |  |  | :heavy_check_mark: | :heavy_check_mark: |\n\n| Knockoff version: | 1.0 | 1.1.0 | 1.1.1 | 1.4 | 1.5 |\n| --- | --- | --- | --- | --- | --- |\n| Rails 4 | :heavy_check_mark: | :heavy_check_mark: |  |  |  |\n| Rails 5.0 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |  |  |\n| Rails 5.1 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |  |  |\n| Rails 5.2 | :heavy_check_mark: | :heavy_check_mark:| :heavy_check_mark: |  |  |\n| Rails 6.0 |  |  | :heavy_check_mark: | :heavy_check_mark: |  |\n| Rails 6.1 |  |  |  | :heavy_check_mark: | :heavy_check_mark: |\n| Rails 7.0 |  |  |  |  | :heavy_check_mark: |\n| Rails 7.1 |  |  |  |  |  |\n| Rails 7.2 |  |  |  |  |  |\n\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'knockoff'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install knockoff\n\n## Usage\n\n### Initializer\n\nAdd an initializer at config/knockoff.rb with the below contents\n\n```ruby\nKnockoff.enabled = true # NOTE: Consider adding ENV based disabling\n```\n\n### Configuration\n\nConfiguration is done using ENV properties. This makes it easy to add and remove replicas at runtime (or to fully disable if needed). First, set up ENV variables pointing to your replica databases. Consider using the [dotenv](https://github.com/bkeepers/dotenv) gem for manging ENV variables.\n\n```dotenv\n# .env\n\nREPLICA_1=postgres://username:password@localhost:5432/database_name\n```\n\nThe second ENV variable to set is `KNOCKOFF_REPLICA_ENVS` which is a comma-separated list of ENVS holding database URLs to use as replicas. In this case, the ENV would be set as follows.\n\n```\n# .env\n\nKNOCKOFF_REPLICA_ENVS=REPLICA_1\n```\n\nNote that it can be multiple replicas, and `knockoff` will use both evenly:\n\n```\nKNOCKOFF_REPLICA_ENVS=REPLICA_1,REPLICA_2\n```\n\nLastly, knockoff will read the `'knockoff_replicas'` database.yml config for specifying additional params:\n\n```yml\n# database.yml\n\nknockoff_replicas:\n  \u003c\u003c: *common\n  prepared_statements: false\n```\n\n### Basics\n\nTo use one of the replica databases, use\n\n```ruby\nKnockoff.on_replica { User.count }\n```\n\nTo force primary, use\n\n```ruby\nKnockoff.on_primary { User.create(name: 'Bob') }\n```\n\n### Using in Controllers\n\nA common use case is to use replicas for GET requests and otherwise use primary. A simplified use case might look something like this:\n\n```ruby\n# application_controller.rb\n\naround_action :choose_database\n\ndef choose_database(\u0026block)\n  if should_use_primary_database?\n    Knockoff.on_primary(\u0026block)\n  else\n    Knockoff.on_replica(\u0026block)\n  end\nend\n\ndef should_use_primary_database?\n  request.method_symbol != :get\nend\n\n```\n\n#### Replication Lag\n\nReplicas will often be slightly behind the primary database. To compensate, consider \"sticking\" a user who has recently made changes to the primary for a small duration of time to the primary database. This will avoid cases where a user creates a record on primary, is redirected to view that record, and receives a 404 error since the record is not yet in the replica. A simple implementation for this could look like:\n\n```ruby\n# application_record.rb\n\nafter_commit :track_commit_occurred_in_request\n\n# If any commit happens in a request, we record that and have the logged_in_user\n# read from primary for a short period of time.\ndef track_commit_occurred_in_request\n  RequestLocals.store['commit_occurred_in_current_request'] = true\nend\n\n# application_controller.rb\n\nafter_action :force_leader_if_commit\n\ndef force_leader_if_commit\n  if RequestLocals.store['commit_occurred_in_current_request'].to_b\n    session[:use_leader_until] = Time.current + FORCE_PRIMARY_DURATION\n  end\nend\n\n```\n\nThen, in your `should_use_primary_database?` method, consult `session[:use_leader_until]` for the decision.\n\n### Run-time Configuration\n\nKnockoff can be configured during runtime. This is done through the `establish_new_connections!` method which takes in a hash of new configurations to apply to each replica before re-connecting.\n\n```ruby\nKnockoff.establish_new_connections!({ 'pool' =\u003e db_pool })\n```\n\nFor example, to specify a puma connection pool at bootup your code might look something like\n\n```ruby\n# puma.rb\n\ndb_pool = Integer(ENV['PUMA_WORKER_DB_POOL'] || threads_count)\n# Configure the database connection to have the new pool size and re-establish connection\ndatabase_config = ActiveRecord::Base.configurations[Rails.env] || Rails.application.config.database_configuration[Rails.env]\ndatabase_config['pool'] = db_pool\nActiveRecord::Base.establish_connection(database_config)\nKnockoff.establish_new_connections!({ 'pool' =\u003e db_pool })\n\n```\n\n#### Forking\n\nFor forking servers, you may disconnect all replicas before forking with `Knockoff.disconnect_all!`.\n\n```ruby\n# puma.rb\n\nbefore_fork do\n  ActiveRecord::Base.connection_pool.disconnect!\n  Knockoff.disconnect_all!\nend\n```\n\n### Other Cases\n\nThere are likely other cases specific to each application where it makes sense to force primary database and avoid replication lag. Good candidates are time-based pages (a live calendar, for example), forms, and payments.\n\n## Usage Notes\n\n* Do not use prepared statements with this gem\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/joinhandshake/knockoff.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoinhandshake%2Fknockoff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoinhandshake%2Fknockoff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoinhandshake%2Fknockoff/lists"}