README.md in sequel-rails-0.6.1 vs README.md in sequel-rails-0.7.0
- old
+ new
@@ -2,22 +2,31 @@
============
[](https://travis-ci.org/TalentBox/sequel-rails)
[](https://codeclimate.com/github/TalentBox/sequel-rails)
-This gem provides the railtie that allows [sequel](http://github.com/jeremyevans/sequel) to hook into [rails3](http://github.com/rails/rails) and thus behave like a rails framework component. Just like activerecord does in rails, [sequel-rails](http://github.com/talentbox/sequel-rails) uses the railtie API to hook into rails. The two are actually hooked into rails almost identically.
+This gem provides the railtie that allows
+[sequel](http://github.com/jeremyevans/sequel) to hook into
+[Rails (3.x and 4.x)](http://github.com/rails/rails) and thus behave like a
+rails framework component. Just like activerecord does in rails,
+[sequel-rails](http://github.com/talentbox/sequel-rails) uses the railtie API to
+hook into rails. The two are actually hooked into rails almost identically.
-The code for this gem was initially taken from the excellent [dm-rails](http://github.com/datamapper/dm-rails) project.
+The code for this gem was initially taken from the excellent
+[dm-rails](http://github.com/datamapper/dm-rails) project.
-This was originally a fork of [brasten](https://github.com/brasten)'s [sequel-rails](https://github.com/brasten/sequel-rails) that has been updated to support newer versions of rails.
+This was originally a fork of [brasten](https://github.com/brasten)'s
+[sequel-rails](https://github.com/brasten/sequel-rails) that has been updated to
+support newer versions of rails.
-Since January 2013, we've became the official maintainers of the gem after [brasten](https://github.com/brasten) proposed us.
+Since January 2013, we've became the official maintainers of the gem after
+[brasten](https://github.com/brasten) proposed us.
Using sequel-rails
==================
-Using sequel with rails3 requires a couple minor changes.
+Using sequel with Rails (3.x or 4.x) requires a couple minor changes.
First, add the following to your Gemfile (after the `Rails` lines):
```ruby
# depending on you database
@@ -28,11 +37,13 @@
gem "sequel-rails"
```
... be sure to run "bundle install" if needed!
-Secondly, you'll need to require the different Rails components separately in your `config/application.rb` file, and not require `ActiveRecord`. The top of your `config/application.rb` will probably look something like:
+Secondly, you'll need to require the different Rails components separately in
+your `config/application.rb` file, and not require `ActiveRecord`.
+The top of your `config/application.rb` will probably look something like:
```ruby
# require 'rails/all'
# Instead of 'rails/all', require these:
@@ -42,20 +53,75 @@
require "sprockets/railtie"
```
Starting with sequel-rails 0.4.0.pre3 we don't change default Sequel behaviour
nor include any plugin by default, if you want to get back the previous
-behaviour, you can create a new initializer (eg: `config/initializers/sequel.rb`) with content:
+behaviour, you can create a new initializer (eg: `config/initializers/sequel.rb`)
+with content:
```ruby
require "sequel_rails/railties/legacy_model_config"
```
After those changes, you should be good to go!
+Features provided by `sequel-rails`
+===================================
+
+1. Connection management:
+
+ `sequel-rails` will initiate the `Sequel` connection mechanism based on your
+ configuration in `database.yml`.
+
+2. Generators:
+
+ You can use them just like `ActiveRecord`'s ones:
+
+ Migration:
+
+ ```ruby
+ rails generate migration create_admin_users
+ # Or
+ rails generate migration CreateAdminUsers
+ ```
+
+ Model:
+
+ ```ruby
+ rails generate model User email:string
+ ```
+
+ Observer:
+
+ ```ruby
+ rails generate observer User
+ ```
+
+3. Rake tasks similar to `ActiveRecord`, see
+ [Available sequel specific rake tasks](#available-sequel-specific-rake-tasks)
+
+4. Add some `Sequel` and `sequel-rails` specific exceptions to `ActionDispatch`'s `rescue_responses`
+
+ `Sequel::Plugins::RailsExtensions::ModelNotFound` is mapped to `:not_found`
+
+ `Sequel::NoMatchingRow` is mapped to `:not_found`
+
+ `Sequel::ValidationFailed` is mapped to `:unprocessable_entity`
+
+ `Sequel::NoExistingObject` is mapped to `:unprocessable_entity`
+
+5. Add a `i18n_scope` method to `Sequel::Model` which respond with `"sequel"`.
+ This is used by `ActiveModel`.
+
+6. Adding `Sequel` to `ActiveSupport::LogSubscriber`. This is what allows you to
+ see SQL queries in the log and also allows us to implement the next item.
+
+7. Add a hook in `ActionController::Base` so that the sum of SQL queries time
+ for the current action is reported as `DB` for the controller's line in logs.
+
Configuration
-====================================
+=============
You can configure some options with the usual rails mechanism, in
`config/application.rb` and/or in `config/environments/*.rb`.
```ruby
# Allowed options: :sql, :ruby.
@@ -72,10 +138,82 @@
# Configure whether database's rake tasks will be loaded or not
# Defaults to true
config.sequel.load_database_tasks = false
```
+The connection settings are read from the file `config/database.yml` and is
+expected to be similar to `ActiveRecord`'s format.
+
+Here's some examples:
+
+1. For PostgreSQL:
+
+ ```yaml
+ development:
+ adapter: postgresql
+ database: a_database_name
+ user: user_name # Also accept 'username' as key, if both are present 'username' is used
+ password: password
+ host: 10.0.0.2 # Optional
+ port: 5432 # Optional
+ owner: owner_name # Optional
+ encoding: utf8 # Optional, also accept 'charset' as key, if both are present 'encoding' is used (defaults to 'utf8')
+ maintenance_db: template2 # Optional
+ locale: en_US.UTF-8 # Optional, equivalent to setting 'collation' and 'ctype' to the same value
+ collation: en_US.UTF-8 # Optional
+ ctype: en_US.UTF-8 # Optional
+ template: template1 # Optional
+ tablespace: non_default_tablespace_name # Optional
+ ```
+
+2. For MySQL:
+
+ ```yaml
+ development:
+ adapter: mysql # Also accept mysql2
+ database: a_database_name
+ user: user_name # Also accept 'username' as key, if both are present 'username' is used
+ password: password
+ host: 10.0.0.2 # Optional
+ port: 5432 # Optional
+ charset: latin1 # Optional (defaults to 'utf8')
+ collation: latin1_general_ci # Optional (defaults to 'utf8_unicode_ci')
+ ```
+
+2. For SQLite:
+
+ ```yaml
+ development:
+ adapter: sqlite # Also accept sqlite3
+ database: db/mydatabase.sqlite # Path to db relative to Rails root
+ ```
+
+ For in memory testing:
+
+ ```yaml
+ development:
+ adapter: sqlite # Also accept sqlite3
+ database: ":memory:"
+ ```
+
+Enabling plugins
+================
+
+If you want to enable plugins for all your models, you should use the
+after_connect configuration option in `config/application.rb` (0.6.2+):
+
+```ruby
+ config.sequel.after_connect = proc do
+ Sequel::Model.plugin :timestamps, update_on_create: true
+ end
+```
+
+This will ensure that these plugins are loaded before any Sequel models are
+loaded. Loading plugins into `Sequel::Model` after subclasses are already
+created is not supported by Sequel. You can also load extensions in
+`after_connect` or perform any custom actions that you need.
+
Available sequel specific rake tasks
====================================
To get a list of all available rake tasks in your rails3 app, issue the usual in you app's root directory:
@@ -151,9 +289,13 @@
* Rafał Rzepecki (dividedmind)
* Sean Sorrell (rudle)
* Saulius Grigaliunas (sauliusg)
* Jacques Crocker (railsjedi)
* Eric Strathmeyer (strathmeyer)
+* Jan Berdajs (mrbrdo)
+* Robert Payne (robertjpayne)
+* Kevin Menard (nirvdrum)
+* Chris Heisterkamp (cheister)
Credits
=======
The [dm-rails](http://github.com/datamapper/dm-rails) team wrote most of the original code, I just sequel-ized it, but since then most of it as been either adapted or rewritten.