{"id":13879326,"url":"https://github.com/zendesk/active_record_shards","last_synced_at":"2025-05-16T01:05:03.165Z","repository":{"id":8830931,"uuid":"10532775","full_name":"zendesk/active_record_shards","owner":"zendesk","description":"Support for sharded databases and replicas for ActiveRecord","archived":false,"fork":false,"pushed_at":"2024-05-16T18:13:14.000Z","size":846,"stargazers_count":250,"open_issues_count":21,"forks_count":24,"subscribers_count":423,"default_branch":"main","last_synced_at":"2025-05-09T14:03:01.540Z","etag":null,"topics":[],"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/zendesk.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-06-06T17:56:48.000Z","updated_at":"2025-02-11T21:31:45.000Z","dependencies_parsed_at":"2024-02-15T14:29:20.741Z","dependency_job_id":"99046d84-1041-4404-81ed-5db92804b3b9","html_url":"https://github.com/zendesk/active_record_shards","commit_stats":{"total_commits":571,"total_committers":38,"mean_commits":"15.026315789473685","dds":0.7162872154115587,"last_synced_commit":"ee5b2c751821108a9ed2a275e204f9de13d87b5d"},"previous_names":[],"tags_count":116,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Factive_record_shards","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Factive_record_shards/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Factive_record_shards/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Factive_record_shards/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zendesk","download_url":"https://codeload.github.com/zendesk/active_record_shards/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448579,"owners_count":22072764,"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-08-06T08:02:17.288Z","updated_at":"2025-05-16T01:05:03.140Z","avatar_url":"https://github.com/zendesk.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"[![Build Status](https://github.com/zendesk/active_record_shards/workflows/CI/badge.svg)](https://github.com/zendesk/active_record_shards/actions?query=workflow%3ACI)\n\n# ActiveRecord Shards\n\nActiveRecord Shards is an extension for ActiveRecord that provides support for sharded database and replicas. Basically it is just a nice way to\nswitch between database connections. We've made the implementation very small, and have tried not to reinvent any wheels already present in ActiveRecord.\n\nActiveRecord Shards has been used and tested on Rails 5.x and 6.0, and has in some form or another been used in production on large Rails apps for several years.\n\nRails 6.1 introduced new connection handling and support for sharding. Apps are encouraged to migrate to the native sharding logic but ActiveRecord Shards supports Rails 6.1 when `legacy_connection_handling` is set to `true`. For more information see [Rails 6.1 installation](#rails-61-installation) and Rails' [multiple databases guide](https://guides.rubyonrails.org/active_record_multiple_databases.html).\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Migrations](#migrations)\n  - [Example](#example)\n    - [Shared Model](#create-a-table-for-the-shared-not-sharded-model)\n    - [Sharded Model](#create-a-table-for-the-sharded-model)\n- [Usage](#usage)\n- [Debugging](#debugging)\n\n## Installation\n\n    $ gem install active_record_shards\n\nand make sure to require 'active\\_record\\_shards' in some way.\n\n### Rails 6.1 \u0026 7.0 installation\n\nRails 6.1 \u0026 7.0 are **only** supported with `legacy_connection_handling` set to `true`.\n\nEnable the legacy handling in your configuration files e.g. `config/application.rb` by setting:\n\n``` Ruby\nconfig.active_record.legacy_connection_handling = true\n```\n\nor\n\n``` Ruby\nActiveRecord::Base.legacy_connection_handling = true\n```\n\n## Configuration\n\nAdd the replica and shard configuration to config/database.yml:\n\n```yaml\nproduction:\n  adapter: mysql\n  encoding: utf8\n  database: my_app_main\n  pool: 5\n  host: db1\n  username: root\n  password:\n  replica:\n    host: db1_replica\n  shards:\n    1:\n      host: db_shard1\n      database: my_app_shard\n      replica:\n        host: db_shard1_replica\n    2:\n      host: db_shard2\n      database: my_app_shard\n      replica:\n        host: db_shard2_replica\n```\n\nbasically connections inherit configuration from the parent configuration file.\n\n## Migrations\n\nActiveRecord Shards also patches migrations to support running migrations on a shared (not sharded) or a sharded database.\nEach migration class has to specify a shard spec indicating where to run the migration.\n\nValid shard specs:\n\n* `:none` - Run this migration on the shared database, not any shards\n* `:all` - Run this migration on all of the shards, not the shared database\n\n#### Example\n\n###### Create a table for the shared (not sharded) model\n\n```ruby\nclass CreateAccounts \u003c ActiveRecord::Migration\n  shard :none\n\n  def change\n    create_table :accounts do |t|\n      # This is NOT necessary for the gem to work, we just use it in the examples below demonstrating one way to switch shards\n      t.integer :shard_id, null: false\n\n      t.string :name\n    end\n  end\nend\n```\n\n###### Create a table for the sharded model\n\n```ruby\nclass CreateProjects \u003c ActiveRecord::Migration\n  shard :all\n\n  def change\n    create_table :projects do |t|\n      t.references :account\n      t.string :name\n    end\n  end\nend\n```\n\n## Usage\n\nNormally you have some models that live on a shared database, and you might need to query this data in order to know what shard to switch to.\nAll the models that live on the shared database must be marked as not\\_sharded:\n\n```ruby\nclass Account \u003c ActiveRecord::Base\n  not_sharded\n\n  has_many :projects\nend\n\nclass Project \u003c ActiveRecord::Base\n  belongs_to :account\nend\n```\n\nSo in this setup the accounts live on the shared database, but the projects are sharded. If accounts have a shard\\_id column, you could lookup the account\nin a rack middleware and switch to the right shard:\n\n```ruby\nclass AccountMiddleware\n  def initialize(app)\n    @app = app\n  end\n\n  def call(env)\n    account = lookup_account(env)\n\n    if account\n      ActiveRecord::Base.on_shard(account.shard_id) do\n        @app.call(env)\n      end\n    else\n      @app.call(env)\n    end\n  end\n\n  def lookup_account(env)\n    # ...\n  end\nend\n```\n\nYou can switch to the replica databases at any point by wrapping your code in an on\\_replica block:\n\n```ruby\nActiveRecord::Base.on_replica do\n  Account.find_by_big_expensive_query\nend\n```\n\nThis will perform the query on the replica, and mark the returned instances as read-only. There is also a shortcut for this:\n\n```ruby\nAccount.on_replica.find_by_big_expensive_query\n```\n\nIf you do not want instances returned from replicas to be marked as read-only, this can be disabled globally:\n\n`ActiveRecordShards.disable_replica_readonly_records = true`\n\n## Debugging\n\nShow if a query went to primary or replica in the logs:\n\n```Ruby\nrequire 'active_record_shards/sql_comments'\nActiveRecordShards::SqlComments.enable\n```\n\n## Copyright\n\nCopyright (c) 2011 Zendesk. See LICENSE for details.\n\n## Authors\nMick Staugaard, Eric Chapweske\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzendesk%2Factive_record_shards","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzendesk%2Factive_record_shards","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzendesk%2Factive_record_shards/lists"}