{"id":25872090,"url":"https://github.com/aktsk/octoball","last_synced_at":"2025-04-05T16:08:21.765Z","repository":{"id":41176009,"uuid":"304217076","full_name":"aktsk/octoball","owner":"aktsk","description":"Octopus-like Database Sharding Helper for ActiveRecord 6.1+","archived":false,"fork":false,"pushed_at":"2024-10-10T04:02:26.000Z","size":64,"stargazers_count":36,"open_issues_count":0,"forks_count":8,"subscribers_count":72,"default_branch":"master","last_synced_at":"2025-03-29T15:08:14.313Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aktsk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2020-10-15T05:13:12.000Z","updated_at":"2025-03-28T07:27:08.000Z","dependencies_parsed_at":"2022-08-21T00:20:51.309Z","dependency_job_id":"de72451c-1c5b-4acb-b73b-178f1a1bfc6d","html_url":"https://github.com/aktsk/octoball","commit_stats":{"total_commits":31,"total_committers":1,"mean_commits":31.0,"dds":0.0,"last_synced_commit":"0e481034bd47af2f7229c532db596568ceae21c6"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aktsk%2Foctoball","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aktsk%2Foctoball/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aktsk%2Foctoball/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aktsk%2Foctoball/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aktsk","download_url":"https://codeload.github.com/aktsk/octoball/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247361691,"owners_count":20926643,"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":"2025-03-02T07:37:25.351Z","updated_at":"2025-04-05T16:08:21.741Z","avatar_url":"https://github.com/aktsk.png","language":"Ruby","readme":"# Octoball - Octopus-like sharding helper library for ActiveRecord 6.1+\n\n\u003cimg src=\"https://user-images.githubusercontent.com/26372128/98494380-3711be00-2280-11eb-8805-6f9e47aeee21.jpg\" align=\"left\" width=120\u003e\n\nOctoball provides [Octopus](https://github.com/thiagopradi/octopus)-like database sharding helpers for ActiveRecord 6.1+.\nThis will make it easier to upgrade Rails to 6.1+ for applications using [Octopus gem](https://github.com/thiagopradi/octopus) for database sharding with Rails 4.x/5.x.\n\nCurrently, its implementation is focusing on horizontal database sharding. However, by customizing shard key mapping, it can be applied to replication use case too.\n\u003cbr clear=\"both\"\u003e\n\n## Scope of this gem\n\n### What is included in Octoball\n- Octopus-like shard swithcing by `using` class method, e.g.:\n  ```ruby\n  Octoball.using(:shard1) { User.find_by_name(\"Alice\") }\n  User.using(:shard1).first\n  ```\n- Each model instance knows which shard it came from so shard will be switched automatically:\n  ```ruby\n  user1 = User.using(:shard1).find_by_name(\"Bob\")\n  user2 = User.using(:shard2).find_by_name(\"Charlie\")\n  user1.age += 1\n  user2.age += 1\n  user1.save!  #  Save the user1 in the correct shard `:shard1`\n  user2.save!  #  Save the user2 in the correct shard `:shard2`\n  ```\n- Relations such as `has_many` are also resolved from the model instance's shard:\n  ```ruby\n  user = User.using(:shard1).find_by_name(\"Alice\")\n  user.blogs.where(title: \"blog\")  # user's blogs are fetched from `:shard1`\n  ```\n\n### What is NOT included in Octoball\n- Connection handling and configuration -- managed by the native `ActiveRecord::Base.connects_to` methods introduced in ActiveRecord 6.1.\n  - You need to migrate from Octopus' `config/shards.yml` to [Rails native multiple DB configuration using `config/database.yml`](https://edgeguides.rubyonrails.org/active_record_multiple_databases.html). Please refer the [Setup](#Setup) section for more details.\n- Migration -- done by ActiveRecord 6.1+ natively.\n  - Instead of `using` method in Octopus, you can specify the `migrations_paths` parameter in the `config/database.yml` file.\n- Replication handling -- done by ActiveRecord's `role`\n  - round-robin connection scheduler is currently omitted.\n\n## Setup\n\n```\ngem \"octoball\"\n```\n\nDefine the database connections in `config/database.yml`, e.g.:\n```\ndefault: \u0026default\n  adapter: mysql2\n  pool: 5\n  username: root\n  host: localhost\n  timeout: 5000\n  connnect_timeout: 5000\n\ndevelopment:\n  master:\n    \u003c\u003c: *default\n    database: db_primary\n  shard1_connection:\n    \u003c\u003c: *default\n    database: db_shard1\n```\nAnd define shards and corresponding connections in abstract ActiveRecord model class, e.g.:\n```ruby\nclass ApplicationRecord \u003c ActiveRecord::Base\n  self.abstract_class = true\n\n  connects_to shards: {\n    master: { writing: :master },\n    shard1: { writing: :shard1_connection },\n  }\nend\n\nclass User \u003c ApplicationRecord\n  ...\nend\n```\n\nOptionally, to use the `:master` shard as a default connection like Octopus, add the following script to `config/initializers/default_shard.rb`:\n```\nActiveRecord::Base.default_shard = :master\n```\n\n\n## Development of Octoball\nOctoball has rspec tests delived from subsets of Octopus' rspec.\n\nTo run the rspec tests, follow these steps:\n```\nRAILS_ENV=test bundle exec rake db:prepare\nRAILS_ENV=test bundle exec rake spec\n```\n\n## License\nOctoball is released under the MIT license.\n\nOriginal Octopus' copyright: Copyright (c) Thiago Pradi\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faktsk%2Foctoball","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faktsk%2Foctoball","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faktsk%2Foctoball/lists"}