https://github.com/dirk/active_replicas
Smart read replicas in ActiveRecord
https://github.com/dirk/active_replicas
Last synced: about 1 year ago
JSON representation
Smart read replicas in ActiveRecord
- Host: GitHub
- URL: https://github.com/dirk/active_replicas
- Owner: dirk
- License: bsd-3-clause
- Created: 2016-11-20T03:44:04.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-06-29T01:06:46.000Z (almost 9 years ago)
- Last Synced: 2025-03-21T13:45:39.674Z (over 1 year ago)
- Language: Ruby
- Homepage:
- Size: 75.2 KB
- Stars: 3
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ActiveReplicas
[](https://travis-ci.org/dirk/active_replicas)
Drop-in read-replica querying in ActiveRecord. It proxies around ActiveRecord's connection to send read-only queries to replica databases; writes will automatically go to the primary and "stick" the request into using the primary for any further queries.
This is heavily inspired by [Kickstarter's `replica_pools`](https://github.com/kickstarter/replica_pools) gem. It seeks to improve on that gem by better interfacing with ActiveRecord's connection pools.
## Installation & usage
ActiveReplicas injects itself into ActiveRecord. To start you'll want to add it to your application's `Gemfile`:
```ruby
gem 'active_replicas'
```
You then need to instruct it as to which connection to use for the primary and which connection(s) to use for the read replicas:
```ruby
# config/initializers/active_replicas.rb
ActiveReplicas::Railtie.hijack_active_record primary: { url: 'mysql2://user@primary/my_app' },
replicas: {
replica0: { url: 'mysql2://user@replica/my_app' }
}
```
**Note**: ActiveReplicas does not do anything automatically. It only injects itself into ActiveRecord when you tell it do so (see above).
## How it works
A few things happen when you call [`hijack_active_record`](http://www.rubydoc.info/github/dirk/active_replicas/master/ActiveReplicas/Railtie#hijack_active_record-class_method):
- It defines delegations for the [connection](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters.html) methods that can be sent to replicas and the methods that must be sent to a primary.
- It sets up a [`ConnectionHandler`](http://www.rubydoc.info/github/dirk/active_replicas/master/ActiveReplicas/Rails4/ConnectionHandler) that will act in place of ActiveRecord's normal connection handler.
- It replaces ActiveRecord's log subscriber with its own [`LogSubscriber`](http://www.rubydoc.info/github/dirk/active_replicas/master/ActiveReplicas/LogSubscriber) which adds information about replica/primary status to logging messages.
The new connection handler manages connection pools for each configured primary and replica database(s). Externally it provides instances of [`ProxyingConnectionPool`](http://www.rubydoc.info/github/dirk/active_replicas/master/ActiveReplicas/ProxyingConnectionPool) in place of normal connection pools. Those proxying pools then forward connection methods to primary or replica pools.
### Using it with Ruby on Rails
ActiveReplicas works seamlessly within the Rails request lifecycle. It extends the [`clear_active_connections!` called in ActiveRecord's middleware](https://github.com/rails/rails/blob/4-2-stable/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb#L645-L663) to not only clear the active connections (releasing them back to their respective pool) but also resets the primary/replica state. That way the next connection will start out using a replica.
## Contributing
Bug reports and pull requests are welcome on [GitHub][]. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
[GitHub]: https://github.com/dirk/active_replicas
## License
Licensed under the 3-clause BSD license. See [LICENSE](LICENSE) for details.