diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/4_0_release_notes.md | 13 | ||||
| -rw-r--r-- | guides/source/active_record_validations.md | 140 | ||||
| -rw-r--r-- | guides/source/asset_pipeline.md | 58 | ||||
| -rw-r--r-- | guides/source/migrations.md | 225 | ||||
| -rw-r--r-- | guides/source/security.md | 20 |
5 files changed, 392 insertions, 64 deletions
diff --git a/guides/source/4_0_release_notes.md b/guides/source/4_0_release_notes.md index dd57787111..55ac4bca87 100644 --- a/guides/source/4_0_release_notes.md +++ b/guides/source/4_0_release_notes.md @@ -165,6 +165,19 @@ Please refer to the [Changelog](https://github.com/rails/rails/blob/master/railt ### Notable changes +* Improve ways to write `change` migrations, making the old `up` & `down` methods no longer necessary. + + * The methods `drop_table` and `remove_column` are now reversible, as long as the necessary information is given. + The method `remove_column` used to accept multiple column names; instead use `remove_columns` (which is not revertible). + The method `change_table` is also reversible, as long as its block doesn't call `remove`, `change` or `change_default` + + * New method `reversible` makes it possible to specify code to be run when migrating up or down. + See the [Guide on Migration](https://github.com/rails/rails/blob/master/guides/source/migrations.md#using-the-reversible-method) + + * New method `revert` will revert a whole migration or the given block. + If migrating down, the given migration / block is run normally. + See the [Guide on Migration](https://github.com/rails/rails/blob/master/guides/source/migrations.md#reverting-previous-migrations) + * Adds some metadata columns to `schema_migrations` table. * `migrated_at` diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md index 88d52cb829..822d12aa3a 100644 --- a/guides/source/active_record_validations.md +++ b/guides/source/active_record_validations.md @@ -909,6 +909,146 @@ class Invoice < ActiveRecord::Base end ``` +Working with Validation Errors +------------------------------ + +In addition to the `valid?` and `invalid?` methods covered earlier, Rails provides a number of methods for working with the `errors` collection and inquiring about the validity of objects. + +The following is a list of the most commonly used methods. Please refer to the `ActiveModel::Errors` documentation for a list of all the available methods. + +### `errors` + +Returns an instance of the class `ActiveModel::Errors` containing all errors. Each key is the attribute name and the value is an array of strings with all errors. + +```ruby +class Person < ActiveRecord::Base + validates :name, presence: true, length: { minimum: 3 } +end + +person = Person.new +person.valid? # => false +person.errors + # => {:name=>["can't be blank", "is too short (minimum is 3 characters)"]} + +person = Person.new(name: "John Doe") +person.valid? # => true +person.errors # => [] +``` + +### `errors[]` + +`errors[]` is used when you want to check the error messages for a specific attribute. It returns an array of strings with all error messages for the given attribute, each string with one error message. If there are no errors related to the attribute, it returns an empty array. + +```ruby +class Person < ActiveRecord::Base + validates :name, presence: true, length: { minimum: 3 } +end + +person = Person.new(name: "John Doe") +person.valid? # => true +person.errors[:name] # => [] + +person = Person.new(name: "JD") +person.valid? # => false +person.errors[:name] # => ["is too short (minimum is 3 characters)"] + +person = Person.new +person.valid? # => false +person.errors[:name] + # => ["can't be blank", "is too short (minimum is 3 characters)"] +``` + +### `errors.add` + +The `add` method lets you manually add messages that are related to particular attributes. You can use the `errors.full_messages` or `errors.to_a` methods to view the messages in the form they might be displayed to a user. Those particular messages get the attribute name prepended (and capitalized). `add` receives the name of the attribute you want to add the message to, and the message itself. + +```ruby +class Person < ActiveRecord::Base + def a_method_used_for_validation_purposes + errors.add(:name, "cannot contain the characters !@#%*()_-+=") + end +end + +person = Person.create(name: "!@#") + +person.errors[:name] + # => ["cannot contain the characters !@#%*()_-+="] + +person.errors.full_messages + # => ["Name cannot contain the characters !@#%*()_-+="] +``` + +Another way to do this is using `[]=` setter + +```ruby + class Person < ActiveRecord::Base + def a_method_used_for_validation_purposes + errors[:name] = "cannot contain the characters !@#%*()_-+=" + end + end + + person = Person.create(name: "!@#") + + person.errors[:name] + # => ["cannot contain the characters !@#%*()_-+="] + + person.errors.to_a + # => ["Name cannot contain the characters !@#%*()_-+="] +``` + +### `errors[:base]` + +You can add error messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. Since `errors[:base]` is an array, you can simply add a string to it and it will be used as an error message. + +```ruby +class Person < ActiveRecord::Base + def a_method_used_for_validation_purposes + errors[:base] << "This person is invalid because ..." + end +end +``` + +### `errors.clear` + +The `clear` method is used when you intentionally want to clear all the messages in the `errors` collection. Of course, calling `errors.clear` upon an invalid object won't actually make it valid: the `errors` collection will now be empty, but the next time you call `valid?` or any method that tries to save this object to the database, the validations will run again. If any of the validations fail, the `errors` collection will be filled again. + +```ruby +class Person < ActiveRecord::Base + validates :name, presence: true, length: { minimum: 3 } +end + +person = Person.new +person.valid? # => false +person.errors[:name] + # => ["can't be blank", "is too short (minimum is 3 characters)"] + +person.errors.clear +person.errors.empty? # => true + +p.save # => false + +p.errors[:name] +# => ["can't be blank", "is too short (minimum is 3 characters)"] +``` + +### `errors.size` + +The `size` method returns the total number of error messages for the object. + +```ruby +class Person < ActiveRecord::Base + validates :name, presence: true, length: { minimum: 3 } +end + +person = Person.new +person.valid? # => false +person.errors.size # => 2 + +person = Person.new(name: "Andrea", email: "andrea@example.com") +person.valid? # => true +person.errors.size # => 0 +``` + Displaying Validation Errors in Views ------------------------------------- diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md index 743a04ed42..b302ef76c6 100644 --- a/guides/source/asset_pipeline.md +++ b/guides/source/asset_pipeline.md @@ -96,28 +96,25 @@ Assets can still be placed in the `public` hierarchy. Any assets under `public` In production, Rails precompiles these files to `public/assets` by default. The precompiled copies are then served as static assets by the web server. The files in `app/assets` are never served directly in production. +### Controller Specific Assets + When you generate a scaffold or a controller, Rails also generates a JavaScript file (or CoffeeScript file if the `coffee-rails` gem is in the `Gemfile`) and a Cascading Style Sheet file (or SCSS file if `sass-rails` is in the `Gemfile`) for that controller. -For example, if you generate a `ProjectsController`, Rails will also add a new file at `app/assets/javascripts/projects.js.coffee` and another at `app/assets/stylesheets/projects.css.scss`. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as `<%= javascript_include_tag params[:controller] %>` or `<%= stylesheet_link_tag params[:controller] %>`. Note that you have to set `config.assets.precompile` in `config/environments/production.rb` if you want to precomepile them and use in production mode. You can append them one by one or do something like this: - - # config/environments/production.rb - config.assets.precompile << Proc.new { |path| - if path =~ /\.(css|js)\z/ - full_path = Rails.application.assets.resolve(path).to_path - app_assets_path = Rails.root.join('app', 'assets').to_path - if full_path.starts_with? app_assets_path - puts "including asset: " + full_path - true - else - puts "excluding asset: " + full_path - false - end - else - false - end - } - -NOTE: You must have an [ExecJS](https://github.com/sstephenson/execjs#readme) supported runtime in order to use CoffeeScript. If you are using Mac OS X or Windows you have a JavaScript runtime installed in your operating system. Check [ExecJS](https://github.com/sstephenson/execjs#readme) documentation to know all supported JavaScript runtimes. +For example, if you generate a `ProjectsController`, Rails will also add a new file at `app/assets/javascripts/projects.js.coffee` and another at `app/assets/stylesheets/projects.css.scss`. By default these files will be ready to use by your application immediately using the `require_tree` directive. See [Manifest Files and Directives](#manifest-files-and-directives) for more details on require_tree. + +You can also opt to include controller specific stylesheets and JavaScript files only in their respective controllers using the following: `<%= javascript_include_tag params[:controller] %>` or `<%= stylesheet_link_tag params[:controller] %>`. Ensure that you are not using the `require_tree` directive though, as this will result in your assets being included more than once. + +WARNING: When using asset precompilation (the production default), you will need to ensure that your controller assets will be precompiled when loading them on a per page basis. By default .coffee and .scss files will not be precompiled on their own. This will result in false positives during development as these files will work just fine since assets will be compiled on the fly. When running in production however, you will see 500 errors since live compilation is turned off by default. See [Precompiling Assets](#precompiling-assets) for more information on how precompiling works. + +NOTE: You must have an ExecJS supported runtime in order to use CoffeeScript. If you are using Mac OS X or Windows you have a JavaScript runtime installed in your operating system. Check [ExecJS](https://github.com/sstephenson/execjs#readme) documentation to know all supported JavaScript runtimes. + +You can also disable the generation of asset files when generating a controller by adding the following to your `config/application.rb` configuration: + +```ruby +config.generators do |g| + g.assets false +end +``` ### Asset Organization @@ -459,6 +456,27 @@ If you have other manifests or individual stylesheets and JavaScript files to in config.assets.precompile += ['admin.js', 'admin.css', 'swfObject.js'] ``` +Or you can opt to precompile all assets with something like this: + +```ruby +# config/environments/production.rb +config.assets.precompile << Proc.new { |path| + if path =~ /\.(css|js)\z/ + full_path = Rails.application.assets.resolve(path).to_path + app_assets_path = Rails.root.join('app', 'assets').to_path + if full_path.starts_with? app_assets_path + puts "including asset: " + full_path + true + else + puts "excluding asset: " + full_path + false + end + else + false + end +} +``` + NOTE. Always specify an expected compiled filename that ends with js or css, even if you want to add Sass or CoffeeScript files to the precompile array. The rake task also generates a `manifest.yml` that contains a list with all your assets and their respective fingerprints. This is used by the Rails helper methods to avoid handing the mapping requests back to Sprockets. A typical manifest file looks like: diff --git a/guides/source/migrations.md b/guides/source/migrations.md index 9840e7694f..62b70b5571 100644 --- a/guides/source/migrations.md +++ b/guides/source/migrations.md @@ -56,25 +56,40 @@ Before this migration is run, there will be no table. After, the table will exist. Active Record knows how to reverse this migration as well: if we roll this migration back, it will remove the table. -On databases that support transactions with statements that change the schema , +On databases that support transactions with statements that change the schema, migrations are wrapped in a transaction. If the database does not support this then when a migration fails the parts of it that succeeded will not be rolled back. You will have to rollback the changes that were made by hand. If you wish for a migration to do something that Active Record doesn't know how -to reverse, you can use `up` and `down` instead of `change`: +to reverse, you can use `reversible`: ```ruby class ChangeProductsPrice < ActiveRecord::Migration + def change + reversible do |dir| + change_table :products do |t| + dir.up { t.change :price, :string } + dir.down { t.change :price, :integer } + end + end + end +end +``` + +Alternatively, you can use `up` and `down` instead of `change`: + +``ruby +class ChangeProductsPrice < ActiveRecord::Migration def up change_table :products do |t| - t.string :price, null: false + t.change :price, :string end end - + def down change_table :products do |t| - t.integer :price, null: false + t.change :price, :integer end end end @@ -93,7 +108,7 @@ of the migration. The name of the migration class (CamelCased version) should match the latter part of the file name. For example `20080906120000_create_products.rb` should define class `CreateProducts` and `20080906120001_add_details_to_products.rb` should define -`AddDetailsToProducts`. +`AddDetailsToProducts`. Of course, calculating timestamps is no fun, so Active Record provides a generator to handle making it for you: @@ -139,12 +154,8 @@ generates ```ruby class RemovePartNumberFromProducts < ActiveRecord::Migration - def up - remove_column :products, :part_number - end - - def down - add_column :products, :part_number, :string + def change + remove_column :products, :part_number, :string end end ``` @@ -170,10 +181,6 @@ As always, what has been generated for you is just a starting point. You can add or remove from it as you see fit by editing the `db/migrate/YYYYMMDDHHMMSS_add_details_to_products.rb` file. -NOTE: The generated migration file for destructive migrations will still be -old-style using the `up` and `down` methods. This is because Rails needs to -know the original data types defined when you made the original changes. - Also, the generator accepts column type as `references`(also available as `belongs_to`). For instance @@ -346,7 +353,7 @@ Products.connection.execute('UPDATE `products` SET `price`=`free` WHERE 1') For more details and examples of individual methods, check the API documentation. In particular the documentation for [`ActiveRecord::ConnectionAdapters::SchemaStatements`](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html) -(which provides the methods available in the `up` and `down` methods), +(which provides the methods available in the `change`, `up` and `down` methods), [`ActiveRecord::ConnectionAdapters::TableDefinition`](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html) (which provides the methods available on the object yielded by `create_table`) and @@ -362,25 +369,82 @@ definitions: * `add_column` * `add_index` +* `add_reference` * `add_timestamps` * `create_table` +* `create_join_table` +* `drop_table` (must supply a block) +* `drop_join_table` (must supply a block) * `remove_timestamps` * `rename_column` * `rename_index` +* `remove_reference` * `rename_table` -If you're going to need to use any other methods, you'll have to write the -`up` and `down` methods instead of using the `change` method. +`change_table` is also reversible, as long as the block does not call `change`, +`change_default` or `remove`. + +If you're going to need to use any other methods, you should use `reversible` +or write the `up` and `down` methods instead of using the `change` method. + +### Using `reversible` + +Complex migrations may require processing that Active Record doesn't know how +to reverse. You can use `reversible` to specify what to do when running a +migration what else to do when reverting it. For example, + +```ruby +class ExampleMigration < ActiveRecord::Migration + def change + create_table :products do |t| + t.references :category + end + + reversible do |dir| + dir.up do + #add a foreign key + execute <<-SQL + ALTER TABLE products + ADD CONSTRAINT fk_products_categories + FOREIGN KEY (category_id) + REFERENCES categories(id) + SQL + end + dir.down do + execute <<-SQL + ALTER TABLE products + DROP FOREIGN KEY fk_products_categories + SQL + end + end + + add_column :users, :home_page_url, :string + rename_column :users, :email, :email_address + end +``` + +Using `reversible` will insure that the instructions are executed in the +right order too. If the previous example migration is reverted, +the `down` block will be run after the `home_page_url` column is removed and +right before the table `products` is dropped. + +Sometimes your migration will do something which is just plain irreversible; for +example, it might destroy some data. In such cases, you can raise +`ActiveRecord::IrreversibleMigration` in your `down` block. If someone tries +to revert your migration, an error message will be displayed saying that it +can't be done. ### Using the `up`/`down` Methods +You can also use the old style of migration using `up` and `down` methods +instead of the `change` method. The `up` method should describe the transformation you'd like to make to your schema, and the `down` method of your migration should revert the transformations done by the `up` method. In other words, the database schema should be unchanged if you do an `up` followed by a `down`. For example, if you create a table in the `up` method, you should drop it in the `down` method. It is wise to reverse the transformations in precisely the reverse order they were -made in the `up` method. For example, +made in the `up` method. The example in the `reversible` section is equivalent to: ```ruby class ExampleMigration < ActiveRecord::Migration @@ -415,19 +479,92 @@ class ExampleMigration < ActiveRecord::Migration end ``` -Sometimes your migration will do something which is just plain irreversible; for -example, it might destroy some data. In such cases, you can raise +If your migration is irreversible, you should raise `ActiveRecord::IrreversibleMigration` from your `down` method. If someone tries to revert your migration, an error message will be displayed saying that it can't be done. +### Reverting Previous Migrations + +You can use Active Record's ability to rollback migrations using the `revert` method: + +```ruby +require_relative '2012121212_example_migration' + +class FixupExampleMigration < ActiveRecord::Migration + def change + revert ExampleMigration + + create_table(:apples) do |t| + t.string :variety + end + end +end +``` + +The `revert` method also accepts a block of instructions to reverse. +This could be useful to revert selected parts of previous migrations. +For example, let's imagine that `ExampleMigration` is committed and it +is later decided it would be best to serialize the product list instead. +One could write: + +```ruby +class SerializeProductListMigration < ActiveRecord::Migration + def change + add_column :categories, :product_list + + reversible do |dir| + dir.up do + # transfer data from Products to Category#product_list + end + dir.down do + # create Products from Category#product_list + end + end + + revert do + # copy-pasted code from ExampleMigration + create_table :products do |t| + t.references :category + end + + reversible do |dir| + dir.up do + #add a foreign key + execute <<-SQL + ALTER TABLE products + ADD CONSTRAINT fk_products_categories + FOREIGN KEY (category_id) + REFERENCES categories(id) + SQL + end + dir.down do + execute <<-SQL + ALTER TABLE products + DROP FOREIGN KEY fk_products_categories + SQL + end + end + + # The rest of the migration was ok + end + end +end +``` + +The same migration could also have been written without using `revert` +but this would have involved a few more steps: reversing the order +of `create_table` and `reversible`, replacing `create_table` +by `drop_table`, and finally replacing `up` by `down` and vice-versa. +This is all taken care of by `revert`. + Running Migrations ------------------ Rails provides a set of Rake tasks to run certain sets of migrations. The very first migration related Rake task you will use will probably be -`rake db:migrate`. In its most basic form it just runs the `up` or `change` +`rake db:migrate`. In its most basic form it just runs the `change` or `up` method for all the migrations that have not yet been run. If there are no such migrations, it exits. It will run these migrations in order based on the date of the migration. @@ -436,7 +573,7 @@ Note that running the `db:migrate` also invokes the `db:schema:dump` task, which will update your `db/schema.rb` file to match the structure of your database. If you specify a target version, Active Record will run the required migrations -(up, down or change) until it has reached the specified version. The version +(change, up, down) until it has reached the specified version. The version is the numerical prefix on the migration's filename. For example, to migrate to version 20080906120000 run @@ -445,7 +582,8 @@ $ rake db:migrate VERSION=20080906120000 ``` If version 20080906120000 is greater than the current version (i.e., it is -migrating upwards), this will run the `up` method on all migrations up to and +migrating upwards), this will run the `change` (or `up`) method +on all migrations up to and including 20080906120000, and will not execute any later migrations. If migrating downwards, this will run the `down` method on all the migrations down to, but not including, 20080906120000. @@ -460,14 +598,15 @@ number associated with the previous migration you can run $ rake db:rollback ``` -This will run the `down` method from the latest migration. If you need to undo +This will rollback the latest migration, either by reverting the `change` +method or by running the `down` method. If you need to undo several migrations you can provide a `STEP` parameter: ```bash $ rake db:rollback STEP=3 ``` -will run the `down` method from the last 3 migrations. +will revert the last 3 migrations. The `db:migrate:redo` task is a shortcut for doing a rollback and then migrating back up again. As with the `db:rollback` task, you can use the `STEP` parameter @@ -495,14 +634,15 @@ contents of the current schema.rb file. If a migration can't be rolled back, If you need to run a specific migration up or down, the `db:migrate:up` and `db:migrate:down` tasks will do that. Just specify the appropriate version and -the corresponding migration will have its `up` or `down` method invoked, for -example, +the corresponding migration will have its `change`, `up` or `down` method +invoked, for example, ```bash $ rake db:migrate:up VERSION=20080906120000 ``` -will run the `up` method from the 20080906120000 migration. This task will +will run the 20080906120000 migration by running the `change` method (or the +`up` method). This task will first check whether the migration is already performed and will do nothing if Active Record believes that it has already been run. @@ -596,6 +736,10 @@ you require. Editing a freshly generated migration that has not yet been committed to source control (or, more generally, which has not been propagated beyond your development machine) is relatively harmless. +The `revert` method can be helpful when writing a new migration to undo +previous migrations in whole or in part +(see [Reverting Previous Migrations](#reverting-previous-migrations) above). + Using Models in Your Migrations ------------------------------- @@ -622,6 +766,9 @@ column. class AddFlagToProduct < ActiveRecord::Migration def change add_column :products, :flag, :boolean + reversible do |dir| + dir.up { Product.update_all flag: false } + end Product.update_all flag: false end end @@ -645,7 +792,9 @@ column. class AddFuzzToProduct < ActiveRecord::Migration def change add_column :products, :fuzz, :string - Product.update_all fuzz: 'fuzzy' + reversible do |dir| + dir.up { Product.update_all fuzz: 'fuzzy' } + end end end ``` @@ -697,7 +846,9 @@ class AddFlagToProduct < ActiveRecord::Migration def change add_column :products, :flag, :boolean Product.reset_column_information - Product.update_all flag: false + reversible do |dir| + dir.up { Product.update_all flag: false } + end end end ``` @@ -712,7 +863,9 @@ class AddFuzzToProduct < ActiveRecord::Migration def change add_column :products, :fuzz, :string Product.reset_column_information - Product.update_all fuzz: 'fuzzy' + reversible do |dir| + dir.up { Product.update_all fuzz: 'fuzzy' } + end end end ``` @@ -810,9 +963,9 @@ Rake task) into `db/structure.sql`. For example, for PostgreSQL, the `pg_dump` utility is used. For MySQL, this file will contain the output of `SHOW CREATE TABLE` for the various tables. -Loading these schemas is simply a question of executing the SQL statements they -contain. By definition, this will create a perfect copy of the database's -structure. Using the `:sql` schema format will, however, prevent loading the +Loading these schemas is simply a question of executing the SQL statements they +contain. By definition, this will create a perfect copy of the database's +structure. Using the `:sql` schema format will, however, prevent loading the schema into a RDBMS other than the one used to create it. ### Schema Dumps and Source Control diff --git a/guides/source/security.md b/guides/source/security.md index 8096ea2383..0b0cfe69c4 100644 --- a/guides/source/security.md +++ b/guides/source/security.md @@ -94,16 +94,15 @@ Rails 2 introduced a new default session storage, CookieStore. CookieStore saves * The client can see everything you store in a session, because it is stored in clear-text (actually Base64-encoded, so not encrypted). So, of course, _you don't want to store any secrets here_. To prevent session hash tampering, a digest is calculated from the session with a server-side secret and inserted into the end of the cookie. -That means the security of this storage depends on this secret (and on the digest algorithm, which defaults to SHA512, which has not been compromised, yet). So _don't use a trivial secret, i.e. a word from a dictionary, or one which is shorter than 30 characters_. Put the secret in your environment.rb: +That means the security of this storage depends on this secret (and on the digest algorithm, which defaults to SHA512, which has not been compromised, yet). So _don't use a trivial secret, i.e. a word from a dictionary, or one which is shorter than 30 characters_. -```ruby -config.action_dispatch.session = { - key: '_app_session', - secret: '0x0dkfj3927dkc7djdh36rkckdfzsg...' -} -``` +`config.secret_key_base` is used for specifying a key which allows sessions for the application to be verified against a known secure key to prevent tampering. Applications get `config.secret_key_base` initialized to a random key in `config/initializers/secret_token.rb`, e.g.: + + YourApp::Application.config.secret_key_base = '49d3f3de9ed86c74b94ad6bd0...' -There are, however, derivatives of CookieStore which encrypt the session hash, so the client cannot see it. +Older versions of Rails use CookieStore, which uses `secret_token` instead of `secret_key_base` that is used by EncryptedCookieStore. Read the upgrade documentation for more information. + +If you have received an application where the secret was exposed (e.g. an application whose source was shared), strongly consider changing the secret. ### Replay Attacks for CookieStore Sessions @@ -959,6 +958,11 @@ Used to control which sites are allowed to bypass same origin policies and send * Strict-Transport-Security [Used to control if the browser is allowed to only access a site over a secure connection](http://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) +Environmental Security +---------------------- + +It is beyond the scope of this guide to inform you on how to secure your application code and environments. However, please secure your database configuration, e.g. `config/database.yml`, and your server-side secret, e.g. stored in `config/initializers/secret_token.rb`. You may want to further restrict access, using environment-specific versions of these files and any others that may contain sensitive information. + Additional Resources -------------------- |