{"id":23463527,"url":"https://github.com/readysettech/readyset-rails","last_synced_at":"2026-02-27T06:12:21.050Z","repository":{"id":203190248,"uuid":"709035275","full_name":"readysettech/readyset-rails","owner":"readysettech","description":"Readyset + Rails integration gem","archived":false,"fork":false,"pushed_at":"2024-02-01T17:33:54.000Z","size":338,"stargazers_count":1,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T03:34:44.961Z","etag":null,"topics":["cache","postgres","rails","readyset","ruby"],"latest_commit_sha":null,"homepage":"https://readyset.io","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/readysettech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-10-23T22:04:52.000Z","updated_at":"2024-02-21T20:38:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"e7017444-70ba-407d-9716-1e3cdc88a274","html_url":"https://github.com/readysettech/readyset-rails","commit_stats":null,"previous_names":["helpotters/readyset","readysettech/readyset-rails"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readysettech%2Freadyset-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readysettech%2Freadyset-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readysettech%2Freadyset-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readysettech%2Freadyset-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/readysettech","download_url":"https://codeload.github.com/readysettech/readyset-rails/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248844036,"owners_count":21170505,"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":["cache","postgres","rails","readyset","ruby"],"created_at":"2024-12-24T09:12:43.926Z","updated_at":"2026-02-27T06:12:16.018Z","avatar_url":"https://github.com/readysettech.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ReadySet Rails\n\nA gem for caching with [ReadySet](https://readyset.io) within Rails applications.\n\n![Build status](https://github.com/readysettech/readyset-rails/actions/workflows/rspec.yml/badge.svg)\n[![Number of GitHub issues that are open](https://img.shields.io/github/issues/readysettech/readyset-rails)](https://github.com/readysettech/readyset-rails/issues)\n![Number of GitHub closed issues](https://img.shields.io/github/issues-closed/readysettech/readyset-rails)\n![Number of GitHub pull requests that are open](https://img.shields.io/github/issues-pr-raw/readysettech/readyset-rails)\n![GitHub release; latest by date](https://img.shields.io/github/v/release/readysettech/readyset-rails)\n[![Slack](https://img.shields.io/badge/Join%20Slack-gray?logo=slack\u0026logoColor=white)](https://join.slack.com/t/readysetcommunity/shared_invite/zt-2272gtiz4-0024xeRJUPGWlRETQrGkFw)\n[![Follow us on X, formerly Twitter](https://img.shields.io/twitter/follow/ReadySet?style=social)](https://twitter.com/readysetio)\n\n:star: If you find this gem useful, please consider giving us a star on GitHub! Your support helps us continue to innovate and deliver exciting new features.\n\n## Table of Contents\n- [What is ReadySet?](#what-is-readyset)\n- [What does this gem do?](#what-does-this-gem-do)\n- [Installing](#installing)\n- [Quickstart](#quickstart)\n- [Usage](#usage)\n    - [Getting Started with Caching](#getting-started-with-caching)\n        - [Query Routing in Controllers](#query-routing-in-controllers)\n        - [Query Routing in Models](#query-routing-in-models)\n    - [Cache Migrations](#cache-migrations)\n    - [Automatic Failover](#automatic-failover)\n- [Configuration Options](#configuration-options)\n- [License](#license)\n\n## What is ReadySet?\n\n[ReadySet](https://readyset.io) is a database acceleration engine that acts as\na read replica and implements a novel type of query caching that automatically \nkeeps your caches up-to-date by watching your database's replication stream.\nReadySet helps you scale your database by shedding load and reducing query\nlatency.\n\n## What does this gem do?\n\nThis gem makes it easy to use ReadySet from within your Rails application by\nallowing you to selectively route queries to ReadySet. The high-level features\nof this gem include:\n\n- A `Readyset.route` method that takes a block and routes to ReadySet any\n  queries within that block\n- A controller extension that allows you to route to ReadySet all queries\n  that occur within specific controller actions\n- A model extension that allows you to define queries to be routed to ReadySet\n  within the context of an existing model\n- Rake tasks that allow you to easily manage cache migration on ReadySet,\n  ensuring that a consistent set of caches exists across all of your\n  environments\n- Automatic failover back to your primary database in the event that your\n  ReadySet instance is unreachable (disabled by default)\n\n**Note that ReadySet only guarantees support for PostgreSQL right now, so this\ngem only supports PostgreSQL.**\n\n## Installing\n\nIf you run into any trouble with the below steps, please feel free to reach\nout via our [community Slack](https://join.slack.com/t/readysetcommunity/shared_invite/zt-2272gtiz4-0024xeRJUPGWlRETQrGkFw)!\n\n1. Follow the instructions [here](https://docs.readyset.io/get-started/install-rs/postgres)\n   to install and run ReadySet\n2. Add the following line to your Gemfile and run `bundle install`:\n   ```sh\n   gem 'readyset'\n   ```\n   The ReadySet Rails gem currenly supports Ruby versions \u003e= 3.0 and Rails\n   versions \u003e= 6.1.\n3. Add a section to your `config/database.yml` file with ReadySet's connection\n   information. If you currently connect to only one database, you'll need to\n   move your primary database connection information to be nested under a new\n   key named `primary`.\n   ```yaml\n   development:\n     primary:\n       # This is the connection information for your primary database\n       database: testdb\n       username: postgres\n       password: readyset\n       adapter: postgresql\n       port: 5432\n     readyset:\n       # This is the connection information for ReadySet\n       database: testdb\n       username: postgres\n       password: readyset\n       adapter: readyset\n       host: \"127.0.0.1\"\n       port: 5433\n       # This setting tells Rails that there's no need to run migrations or other database\n       # administration tasks against ReadySet\n       database_tasks: false\n   ```\n   You can verify that ReadySet is up and your application is connected by\n   running `rails readyset:status`:\n   ```sh\n   $ rails readyset:status\n   +----------------------------+------------------------+\n   | Database Connection        | Connected              |\n   | Connection Count           | 1                      |\n   | Snapshot Status            | Completed              |\n   | Maximum Replication Offset | (0/6DBBD78, 0/6DBBFF0) |\n   | Minimum Replication Offset | (0/6DBBD78, 0/6DBBFF0) |\n   | Last started Controller    | 2024-01-17 18:49:02    |\n   | Last completed snapshot    | 2024-01-19 15:18:02    |\n   | Last started replication   | 2024-01-19 15:18:02    |\n   +----------------------------+------------------------+\n   ```\n   You can also view the tables that ReadySet knows about and their statuses by\n   running `rails readyset:tables`:\n   ```sh\n   $ rails readyset:tables\n   +---------------------------------+-------------+-------------+\n   | table                           | status      | description |\n   +---------------------------------+-------------+-------------+\n   | \"public\".\"posts\"                | Snapshotted |             |\n   +---------------------------------+-------------+-------------+\n   ```\n4. Run `Readyset.configure` wherever you configure other gems in your\n   application, and set any desired configuration options:\n   ```ruby\n   Readyset.configure do |config|\n     # Set your config options here\n   end\n   ```\n   The list of available configuration options can be found\n   [here](#configuration-options).\n5. FOR RAILS 7 USERS: Enable Rails's query log tags features by setting\n   `config.active_record.query_log_tags_enabled = true` wherever you configure\n   your ActiveRecord settings. This will append information to your\n   ActiveRecord query logs that tells you where the given query was routed (e.g.\n   to ReadySet or to your primary database)\n\n## Quickstart\n\n1. Follow the instructions above to set up ReadySet and install the gem\n2. Route a query to ReadySet in your application like so:\n   ```ruby\n   Readyset.route do\n     Post.where(user_id: user_id)\n   end\n   ```\n3. Start up your application and drive traffic through the part of your\n   application that invokes the query you routed in the previous step\n4. If you are running Rails 7 and enabled query log tags as explained in step 5\n   [above](#installing), you should see an annotation next to the query in your\n   application logs that denotes where the query was routed. If the\n   `destination` tag has the value `readyset`, the query was routed to\n   ReadySet.\n\n   If you are running Rails 6, you can validate that the query was routed to\n   ReadySet by running `rails readyset:proxied_queries`. A \"proxied\" query is\n   one that was served by ReadySet but was proxied to your primary database,\n   since a cache for the query does not yet exist:\n   ```sh\n   $ rails readyset:proxied_queries\n   +--------------------+-------------------------------------------------------+-------------+-------+\n   | id                 | text                                                  | supported   | count |\n   +--------------------+-------------------------------------------------------+-------------+-------+\n   | q_281c5f9b8e4013bb | SELECT                                                | yes         | 1     |\n   |                    |   *                                                   |             |       |\n   |                    | FROM                                                  |             |       |\n   |                    |   \"posts\"                                             |             |       |\n   |                    | WHERE                                                 |             |       |\n   |                    |   (\"user_id\" = $1)                                    |             |       |\n   +--------------------+-------------------------------------------------------+-------------+-------+\n   ```\n5. Create a cache for the query by running\n   `rails readyset:proxied_queries:cache_all_supported`. This will create caches for\n   all of the queries proxied by ReadySet that are supported to be cached. You\n   can verify that the expected caches were created by running\n   `rails readyset:caches`:\n   ```sh\n   $ rails readyset:caches\n   +--------------------+--------------------+-------------------------------------+--------+-------+\n   | id                 | name               | text                                | always | count |\n   +--------------------+--------------------+-------------------------------------+--------+-------+\n   | q_281c5f9b8e4013bb | q_281c5f9b8e4013bb | SELECT                              | false  | 0     |\n   |                    |                    |   \"public\".\"posts\".\"user_id\"        |        |       |\n   |                    |                    | FROM                                |        |       |\n   |                    |                    |   \"public\".\"posts\"                  |        |       |\n   |                    |                    | WHERE                               |        |       |\n   |                    |                    |   (\"public\".\"posts\".\"user_id\" = $1) |        |       |\n   +--------------------+--------------------+-------------------------------------+--------+-------+\n   ```\n6. Drive traffic through the part of your application that invokes your cached\n   query. The first invocation of the query will be a cache miss, but the\n   second will be served from the cache. You can verify that the cache was\n   successfully used by looking at the `count` column in the output of\n   `rails readyset:caches`:\n   ```sh\n   $ rails readyset:caches\n   +--------------------+--------------------+-------------------------------------+--------+-------+\n   | id                 | name               | text                                | always | count |\n   +--------------------+--------------------+-------------------------------------+--------+-------+\n   | q_281c5f9b8e4013bb | q_281c5f9b8e4013bb | SELECT                              | false  | 1     |\n   |                    |                    |   \"public\".\"posts\".\"user_id\"        |        |       |\n   |                    |                    | FROM                                |        |       |\n   |                    |                    |   \"public\".\"posts\"                  |        |       |\n   |                    |                    | WHERE                               |        |       |\n   |                    |                    |   (\"public\".\"posts\".\"user_id\" = $1) |        |       |\n   +--------------------+--------------------+-------------------------------------+--------+-------+\n   ```\n\n## Usage\n\n### Getting Started with Caching\n\nQueries in arbitrary code blocks can be routed to ReadySet using the\n`Readyset.route` method like so:\n\n```ruby\nReadyset.route do\n  Post.where(user_id: user_id)\nend\n```\n\nAny queries invoked in the given block will be routed to the ReadySet instance\nconfigured in your `config/database.yml` file; however, until a cache is created\nfor a particular query, invocations of that query against ReadySet will be proxied\nto your database. To create a cache for a specific query, you have a few options:\n\n- Invoke `.create_readyset_cache` directly on an ActiveRecord query in the\n  Rails console:\n  ```ruby\n  Post.where(user_id: 1).create_readyset_cache!\n  ```\n- Create caches for all of the queries supported by ReadySet that ReadySet has\n  seen and proxied to your database since it last started up using the provided\n  Rake task:\n  ```sh\n  rails readyset:proxied_queries:cache_all_supported\n  ```\n  **Note:** If you route a query to ReadySet, decide you no longer want to cache\n  that query, and stop routing that query to ReadySet, that query will still\n  exist in ReadySet's list of queries that it has proxied to your database.\n  This means that running the above Rake task will still create a cache for that\n  query **even though it is no longer annotated to be routed to ReadySet in your\n  application code**. The list of queries ReadySet has proxied can be cleared by\n  restarting ReadySet or by running `rails readyset:proxied_queries:drop_all`.\n- View the list of queries that ReadySet has proxied by running the following\n  in a Rails console:\n  ```ruby\n  Readyset::Query::ProxiedQuery.all\n  ```\n  You can invoke `#cache!` on the queries in this list for which you'd like to\n  create caches on ReadySet.\n- View the list of queries that ReadySet has proxied *and* that are supported\n  by ReadySet to be cached by running the following:\n  ```sh\n  rails readyset:proxied_queries:supported\n  ```\n  Pick a query from the list that you'd like to cache, and pass the ID to the\n  `rails readyset:create_cache` command like so:\n  ```sh\n  rails 'readyset:create_cache[your_query_id]'\n  ```\n\nOnce a cache has been created for a particular query, it will persist on\nReadySet across restarts (although any in-memory cached data will be lost when\nReadySet goes down). You can view the list of existing caches using the provided\nRake task:\n```sh\nrails readyset:caches\n```\nTo drop a given cache in the list printed by the above command, you can pass the\nname of the cache to the `readyset:caches:drop` Rake task like so:\n```sh\nrails 'readyset:caches:drop[my_cache]'\n```\nYou can also view the list of existing caches in an interactive form via the\nRails console:\n```ruby\nReadyset::Query::CachedQuery.all\n```\nYou can invoke `#drop!` on any of the caches in this list to remove the cache\nfrom ReadySet.\n\n#### Query Routing in Controllers\n\nThe gem includes an extension to `ActionController` that allows you to route to\nReadySet all of the queries that occur within the context of a given controller\naction:\n```ruby\nclass PostsController \u003c ActionController\n  route_to_readyset only: :show\n\n  def show\n    @post = Post.where(id: params[:id])\n  end\nend\n```\n`route_to_readyset` takes the same parameters as Rails's\n[`around_filters`](https://guides.rubyonrails.org/action_controller_overview.html#after-filters-and-around-filters).\n\n#### Query Routing in Models\n\nThe gem also includes an extension that allows you to define queries in your\nmodel that will be routed to ReadySet:\n```ruby\nclass Post \u003c ApplicationRecord\n    readyset_query :posts_for_user, -\u003e(user_id) { where(user_id: user_id) }\nend\n```\nThe above example will define a `.posts_for_user` class method on the `Post`\nmodel that invokes the query `Post.where(user_id: user_id)` against ReadySet.\n**Note that other invocations of this query outside of the context of the\n`.posts_for_user` method will not be routed to ReadySet.**\n\nThis feature allows you to specify which queries should be routed to ReadySet\nin a centralized location and prevents the need to use `Readyset.route`\neverywhere a cached query is invoked.\n\n### Cache Migrations\n\nOnce you have a set of caches you are happy with in your development\nenvironment, you'll need a way to easily reproduce the same set of caches in\nother environments (e.g. staging, production, etc.). To facilitate this, the\ngem includes a \"migration\" feature, that allows you to dump the current set of\ncaches to a \"migration file\" and re-create these caches using the same\nmigration file.\n\nThe following Rake task dumps the current set of caches to the\n`db/readyset_caches.rb` file:\n```sh\nrails readyset:caches:dump\n```\nThis file should be checked into version control with your application code. To\nupdate a ReadySet instance so that its set of caches matches the caches in your\nmigration file:\n```sh\nrails readyset:caches:migrate\n```\nThis command 1) drops any caches that exist on ReadySet that are not present in\nthe migration file and 2) creates any caches that are present in the migration\nfile that do not exist on ReadySet. To run the command for a particular Rails\nenvironment, you can set the `RAILS_ENV` environment variable.\n\n### Automatic Failover\n\nTo handle situations where ReadySet is unreachable for any reason, the gem\nincludes an automatic failover feature. The gem tracks the number of ReadySet\nconnection failures over a configurable window of time, and if the number of\nerrors exceeds the configured threshold, any queries previously being routed to\nReadySet will be routed to the primary database. A background task is started up\nthat periodically attempts to establish a connection to ReadySet and check its\nstatus. When the task confirms that ReadySet is available again, it allows\nqueries to be routed to ReadySet again.\n\nThis feature is disabled by default. To enable it, set the\n`config.failover.enabled` configuration option to `true`. You can read about the\nother available configuration options [here](#configuration-options).\n\n## Configuration Options\n\nThe gem's configuration options can be set by passing a block to\n`Readyset.configure` and setting options on the yielded\n`Readyset::Configuration` object. The available options are documented below.\nThe values below are the default values for each of the options.\n\n```ruby\nReadyset.configure do |config|\n  # Whether the gem's automatic failover feature should be enabled.\n  config.failover.enabled = false\n  # Sets the interval upon which the background task will check\n  # ReadySet's availability after failover has occurred.\n  config.failover.healthcheck_interval = 5.seconds\n  # Sets the time window over which connection errors are counted\n  # when determining whether failover should occur.\n  config.failover.error_window_period = 1.minute\n  # Sets the number of errors that must occur within the configured\n  # error window period in order for failover to be triggered.\n  config.failover.error_window_size = 10\n  # The file in which cache migrations should be stored.\n  config.migration_path = File.join(Rails.root, 'db/readyset_caches.rb')\nend\n```\n\n## License\n\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadysettech%2Freadyset-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freadysettech%2Freadyset-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadysettech%2Freadyset-rails/lists"}