Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/umbrellio/sequel-connection_guard
A Sequel extension that provides a set of abstractions for working with unreliable database connections.
https://github.com/umbrellio/sequel-connection_guard
database sequel sequel-extension sequel-plugin
Last synced: 2 days ago
JSON representation
A Sequel extension that provides a set of abstractions for working with unreliable database connections.
- Host: GitHub
- URL: https://github.com/umbrellio/sequel-connection_guard
- Owner: umbrellio
- License: mit
- Created: 2019-05-21T12:36:25.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2019-05-23T11:52:39.000Z (over 5 years ago)
- Last Synced: 2024-09-23T16:46:18.618Z (about 2 months ago)
- Topics: database, sequel, sequel-extension, sequel-plugin
- Language: Ruby
- Homepage: https://www.rubydoc.info/gems/sequel-connection_guard
- Size: 3.91 KB
- Stars: 4
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# sequel-connection_guard
[](https://travis-ci.org/umbrellio/sequel-connection_guard)
[](https://coveralls.io/github/umbrellio/sequel-connection_guard?branch=master)
[](https://badge.fury.io/rb/sequel-connection_guard)
This Sequel extension provides a set of abstractions for working with databases that might not be
reachable at any given moment in time.
**This gem was only tested against PostgreSQL databases.**
Goals:
- Allow to bootstrap an application when a database server is down
- Allow to safely and explicitly access a database
- In case connection fails, retry on next attempt
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'sequel-connection_guard'
```
And then execute:
```sh
$ bundle
```
Enable the extension:
```ruby
Sequel.extension :connection_guard
```
## Usage
This extension provides two main abstractions for accessing unreliable databases. These are almost
identical, but one allows you to reach a database handle (instance of `Sequel::Database`) and
another allows you to reach a Sequel model (instance of `Sequel::Model`).
### Database guard
A database guard is what you use to access a database handle. First, you need to instantiate one:
```ruby
::DB = Sequel::DatabaseGuard.new('postgres://localhost/mydb')
```
You can perform additional actions upon DB initialization, such as enabling Sequel plugins:
```ruby
::DB = Sequel::DatabaseGuard.new('postgres://localhost/mydb') do |db|
db.extension :advisory_locking
db.extension :pg_json
end
```
There are two ways of using the guard.
#### Safe access
You can safely access the database handle by using `#safe_execute`:
```ruby
users = DB.safe_execute do
# if the database is reachable
alive do |db|
db[:users].all
end
# if the database could not be reached. NOTE: this is optional
dead do
[]
end
end
```
#### Unsafe access
When you don't care about safety (or you're already inside a `safe_execute` context), use
`#force_execute`:
```ruby
users = DB.force_execute { |db| db[:users].all }
```
#### Accessing a raw database handle
Sometimes it's necessary to get access to a raw instance of `Sequel::Database` (for example, when
using the `database_cleaner` gem). You can get a raw handle like this:
```ruby
DB.raw_handle
```
Beware that this will raise `Sequel::DatabaseConnectionError` if the database is currently
unreachable.
### Model guard
A model guard is what you use to access a model handle. To create a model guard:
```ruby
# NOTE: `DB` must be an instance of Sequel::DatabaseGuard
UserGuard = Sequel::ModelGuard(DB[:users]) do
one_to_many :cookies, class: 'Cookie::RawModel'
def admin?
role == 'admin'
end
end
```
There are, again, two ways of using the guard.
#### Safe access
You can safely access the model by using `#safe_execute`:
```ruby
users = UserGuard.safe_execute do
# if the database is reachable
alive do |model|
model.all
end
# if the database could not be reached. NOTE: this is optional
dead do
[]
end
end
```
#### Unsafe access
When you don't care about safety (or you're already inside a `safe_execute` context), use
`#force_execute`:
```ruby
users = UserGuard.force_execute { |model| model.all }
```
#### Accessing a raw model
Sometimes it's necessary to get access to a raw instance of `Sequel::Model` (good examples are
using this extension with `factory_bot` and describing associations like shown above).
To get the raw model:
```ruby
User = UserGuard::RawModel
```
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/umbrellio/sequel-connection_guard.
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## Authors
Created by [Alexander Komarov](https://github.com/akxcv).
