diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/3_0_release_notes.md | 2 | ||||
| -rw-r--r-- | guides/source/3_1_release_notes.md | 2 | ||||
| -rw-r--r-- | guides/source/3_2_release_notes.md | 2 | ||||
| -rw-r--r-- | guides/source/4_0_release_notes.md | 2 | ||||
| -rw-r--r-- | guides/source/action_controller_overview.md | 4 | ||||
| -rw-r--r-- | guides/source/action_mailer_basics.md | 2 | ||||
| -rw-r--r-- | guides/source/action_view_overview.md | 4 | ||||
| -rw-r--r-- | guides/source/active_job_basics.md | 34 | ||||
| -rw-r--r-- | guides/source/active_record_postgresql.md | 12 | ||||
| -rw-r--r-- | guides/source/api_app.md | 723 | ||||
| -rw-r--r-- | guides/source/association_basics.md | 4 | ||||
| -rw-r--r-- | guides/source/caching_with_rails.md | 186 | ||||
| -rw-r--r-- | guides/source/development_dependencies_install.md | 6 | ||||
| -rw-r--r-- | guides/source/getting_started.md | 5 | ||||
| -rw-r--r-- | guides/source/i18n.md | 10 | ||||
| -rw-r--r-- | guides/source/rails_on_rack.md | 6 |
16 files changed, 511 insertions, 493 deletions
diff --git a/guides/source/3_0_release_notes.md b/guides/source/3_0_release_notes.md index 9ad32e8168..696493a3cf 100644 --- a/guides/source/3_0_release_notes.md +++ b/guides/source/3_0_release_notes.md @@ -88,7 +88,7 @@ $ cd myapp Rails now uses a `Gemfile` in the application root to determine the gems you require for your application to start. This `Gemfile` is processed by the [Bundler](http://github.com/carlhuda/bundler,) which then installs all your dependencies. It can even install all the dependencies locally to your application so that it doesn't depend on the system gems. -More information: - [bundler homepage](http://gembundler.com) +More information: - [bundler homepage](http://bundler.io/) ### Living on the Edge diff --git a/guides/source/3_1_release_notes.md b/guides/source/3_1_release_notes.md index d753346fa3..327495704a 100644 --- a/guides/source/3_1_release_notes.md +++ b/guides/source/3_1_release_notes.md @@ -151,7 +151,7 @@ $ cd myapp Rails now uses a `Gemfile` in the application root to determine the gems you require for your application to start. This `Gemfile` is processed by the [Bundler](https://github.com/carlhuda/bundler) gem, which then installs all your dependencies. It can even install all the dependencies locally to your application so that it doesn't depend on the system gems. -More information: - [bundler homepage](http://gembundler.com) +More information: - [bundler homepage](http://bundler.io/) ### Living on the Edge diff --git a/guides/source/3_2_release_notes.md b/guides/source/3_2_release_notes.md index 6ddf77d9c0..c52c39b705 100644 --- a/guides/source/3_2_release_notes.md +++ b/guides/source/3_2_release_notes.md @@ -81,7 +81,7 @@ $ cd myapp Rails now uses a `Gemfile` in the application root to determine the gems you require for your application to start. This `Gemfile` is processed by the [Bundler](https://github.com/carlhuda/bundler) gem, which then installs all your dependencies. It can even install all the dependencies locally to your application so that it doesn't depend on the system gems. -More information: [Bundler homepage](http://gembundler.com) +More information: [Bundler homepage](http://bundler.io/) ### Living on the Edge diff --git a/guides/source/4_0_release_notes.md b/guides/source/4_0_release_notes.md index 9feaff098a..b9444510ea 100644 --- a/guides/source/4_0_release_notes.md +++ b/guides/source/4_0_release_notes.md @@ -36,7 +36,7 @@ $ cd myapp Rails now uses a `Gemfile` in the application root to determine the gems you require for your application to start. This `Gemfile` is processed by the [Bundler](https://github.com/carlhuda/bundler) gem, which then installs all your dependencies. It can even install all the dependencies locally to your application so that it doesn't depend on the system gems. -More information: [Bundler homepage](http://gembundler.com) +More information: [Bundler homepage](http://bundler.io) ### Living on the Edge diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index 7d95d4792e..d506722f75 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -185,7 +185,9 @@ end These options will be used as a starting point when generating URLs, so it's possible they'll be overridden by the options passed to `url_for` calls. -If you define `default_url_options` in `ApplicationController`, as in the example above, it will be used for all URL generation. The method can also be defined in a specific controller, in which case it only affects URLs generated there. +If you define `default_url_options` in `ApplicationController`, as in the example above, these defaults will be used for all URL generation. The method can also be defined in a specific controller, in which case it only affects URLs generated there. + +In a given request, the method is not actually called for every single generated URL; for performance reasons, the returned hash is cached, there is at most one invocation per request. ### Strong Parameters diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md index bf3bf5d19e..6f159b2fc4 100644 --- a/guides/source/action_mailer_basics.md +++ b/guides/source/action_mailer_basics.md @@ -696,7 +696,7 @@ files (environment.rb, production.rb, etc...) | Configuration | Description | |---------------|-------------| |`logger`|Generates information on the mailing run if available. Can be set to `nil` for no logging. Compatible with both Ruby's own `Logger` and `Log4r` loggers.| -|`smtp_settings`|Allows detailed configuration for `:smtp` delivery method:<ul><li>`:address` - Allows you to use a remote mail server. Just change it from its default `"localhost"` setting.</li><li>`:port` - On the off chance that your mail server doesn't run on port 25, you can change it.</li><li>`:domain` - If you need to specify a HELO domain, you can do it here.</li><li>`:user_name` - If your mail server requires authentication, set the username in this setting.</li><li>`:password` - If your mail server requires authentication, set the password in this setting.</li><li>`:authentication` - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of `:plain`, `:login`, `:cram_md5`.</li><li>`:enable_starttls_auto` - Set this to `false` if there is a problem with your server certificate that you cannot resolve.</li></ul>| +|`smtp_settings`|Allows detailed configuration for `:smtp` delivery method:<ul><li>`:address` - Allows you to use a remote mail server. Just change it from its default `"localhost"` setting.</li><li>`:port` - On the off chance that your mail server doesn't run on port 25, you can change it.</li><li>`:domain` - If you need to specify a HELO domain, you can do it here.</li><li>`:user_name` - If your mail server requires authentication, set the username in this setting.</li><li>`:password` - If your mail server requires authentication, set the password in this setting.</li><li>`:authentication` - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of `:plain` (will send the password in the clear), `:login` (will send password Base64 encoded) or `:cram_md5` (combines a Challenge/Response mechanism to exchange information and a cryptographic Message Digest 5 algorithm to hash important information)</li><li>`:enable_starttls_auto` - Detects if STARTTLS is enabled in your SMTP server and starts to use it. Defaults to `true`.</li><li>`:openssl_verify_mode` - When using TLS, you can set how OpenSSL checks the certificate. This is really useful if you need to validate a self-signed and/or a wildcard certificate. You can use the name of an OpenSSL verify constant ('none', 'peer', 'client_once', 'fail_if_no_peer_cert') or directly the constant (`OpenSSL::SSL::VERIFY_NONE`, `OpenSSL::SSL::VERIFY_PEER`, ...).</li></ul>| |`sendmail_settings`|Allows you to override options for the `:sendmail` delivery method.<ul><li>`:location` - The location of the sendmail executable. Defaults to `/usr/sbin/sendmail`.</li><li>`:arguments` - The command line arguments to be passed to sendmail. Defaults to `-i -t`.</li></ul>| |`raise_delivery_errors`|Whether or not errors should be raised if the email fails to be delivered. This only works if the external email server is configured for immediate delivery.| |`delivery_method`|Defines a delivery method. Possible values are:<ul><li>`:smtp` (default), can be configured by using `config.action_mailer.smtp_settings`.</li><li>`:sendmail`, can be configured by using `config.action_mailer.sendmail_settings`.</li><li>`:file`: save emails to files; can be configured by using `config.action_mailer.file_settings`.</li><li>`:test`: save emails to `ActionMailer::Base.deliveries` array.</li></ul>See [API docs](http://api.rubyonrails.org/classes/ActionMailer/Base.html) for more info.| diff --git a/guides/source/action_view_overview.md b/guides/source/action_view_overview.md index 09fac41491..3c1c3c7873 100644 --- a/guides/source/action_view_overview.md +++ b/guides/source/action_view_overview.md @@ -725,7 +725,7 @@ Returns a select tag with options for each of the seconds 0 through 59 with the ```ruby # Generates a select field for seconds that defaults to the seconds for the time provided -select_second(Time.now + 16.minutes) +select_second(Time.now + 16.seconds) ``` #### select_time @@ -1429,7 +1429,7 @@ This sanitize helper will HTML encode all tags and strip all attributes that are sanitize @article.body ``` -If either the `:attributes` or `:tags` options are passed, only the mentioned tags and attributes are allowed and nothing else. +If either the `:attributes` or `:tags` options are passed, only the mentioned attributes and tags are allowed and nothing else. ```ruby sanitize @article.body, tags: %w(table tr td), attributes: %w(id class style) diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md index 29d0c32b09..22f3c0146a 100644 --- a/guides/source/active_job_basics.md +++ b/guides/source/active_job_basics.md @@ -4,7 +4,7 @@ Active Job Basics ================= This guide provides you with all you need to get started in creating, -enqueueing and executing background jobs. +enqueuing and executing background jobs. After reading this guide, you will know: @@ -20,7 +20,7 @@ Introduction ------------ Active Job is a framework for declaring jobs and making them run on a variety -of queueing backends. These jobs can be everything from regularly scheduled +of queuing backends. These jobs can be everything from regularly scheduled clean-ups, to billing charges, to mailings. Anything that can be chopped up into small units of work and run in parallel, really. @@ -28,11 +28,14 @@ into small units of work and run in parallel, really. The Purpose of Active Job ----------------------------- The main point is to ensure that all Rails apps will have a job infrastructure -in place, even if it's in the form of an "immediate runner". We can then have -framework features and other gems build on top of that, without having to -worry about API differences between various job runners such as Delayed Job -and Resque. Picking your queuing backend becomes more of an operational concern, -then. And you'll be able to switch between them without having to rewrite your jobs. +in place. We can then have framework features and other gems build on top of that, +without having to worry about API differences between various job runners such as +Delayed Job and Resque. Picking your queuing backend becomes more of an operational +concern, then. And you'll be able to switch between them without having to rewrite +your jobs. + +NOTE: Rails by default comes with an "immediate runner" queuing implementation. +That means that each job that has been enqueued will run immediately. Creating a Job @@ -78,7 +81,7 @@ end Enqueue a job like so: ```ruby -# Enqueue a job to be performed as soon the queueing system is +# Enqueue a job to be performed as soon the queuing system is # free. MyJob.perform_later record ``` @@ -99,17 +102,20 @@ That's it! Job Execution ------------- -If no adapter is set, the job is immediately executed. +For enqueuing and executing jobs you need to set up a queuing backend, that is to +say you need to decide for a 3rd-party queuing library that Rails should use. +Rails itself does not provide a sophisticated queuing system and just executes the +job immediately if no adapter is set. ### Backends -Active Job has built-in adapters for multiple queueing backends (Sidekiq, +Active Job has built-in adapters for multiple queuing backends (Sidekiq, Resque, Delayed Job and others). To get an up-to-date list of the adapters see the API Documentation for [ActiveJob::QueueAdapters](http://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html). ### Setting the Backend -You can easily set your queueing backend: +You can easily set your queuing backend: ```ruby # config/application.rb @@ -123,6 +129,10 @@ module YourApp end ``` +NOTE: Since jobs run in parallel to your Rails application, most queuing libraries +require that you start a library-specific queuing service (in addition to +starting your Rails app) for the job processing to work. For information on +how to do that refer to the documentation of your respective library. Queues ------ @@ -212,7 +222,7 @@ end ProcessVideoJob.perform_later(Video.last) ``` -NOTE: Make sure your queueing backend "listens" on your queue name. For some +NOTE: Make sure your queuing backend "listens" on your queue name. For some backends you need to specify the queues to listen to. diff --git a/guides/source/active_record_postgresql.md b/guides/source/active_record_postgresql.md index dcc523eb0f..fe112a4708 100644 --- a/guides/source/active_record_postgresql.md +++ b/guides/source/active_record_postgresql.md @@ -266,13 +266,14 @@ revision = Revision.first revision.identifier # => "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11" ``` -You can use `uuid` type to define references in migrations +You can use `uuid` type to define references in migrations: ```ruby # db/migrate/20150418012400_create_blog.rb -create_table :posts, id: :uuid +enable_extension 'pgcrypto' unless extension_enabled?('pgcrypto') +create_table :posts, id: :uuid, default: 'gen_random_uuid()' -create_table :comments, id: :uuid do |t| +create_table :comments, id: :uuid, default: 'gen_random_uuid()' do |t| # t.belongs_to :post, type: :uuid t.references :post, type: :uuid end @@ -288,6 +289,8 @@ class Comment < ActiveRecord::Base end ``` +See [this section](#uuid-primary-keys) for more details on using UUIDs as primary key. + ### Bit String Types * [type definition](http://www.postgresql.org/docs/current/static/datatype-bit.html) @@ -377,6 +380,9 @@ device = Device.create device.id # => "814865cd-5a1d-4771-9306-4268f188fe9e" ``` +NOTE: `uuid_generate_v4()` (from `uuid-ossp`) is assumed if no `:default` option was +passed to `create_table`. + Full Text Search ---------------- diff --git a/guides/source/api_app.md b/guides/source/api_app.md index 0a6335ed88..29ca872254 100644 --- a/guides/source/api_app.md +++ b/guides/source/api_app.md @@ -1,435 +1,408 @@ -Using Rails for API-only Apps -============================= +**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON http://guides.rubyonrails.org.** + + +Using Rails for API-only Applications +===================================== In this guide you will learn: -- What Rails provides for API-only applications -- How to configure Rails to start without any browser features -- How to decide which middlewares you will want to include -- How to decide which modules to use in your controller +* What Rails provides for API-only applications +* How to configure Rails to start without any browser features +* How to decide which middlewares you will want to include +* How to decide which modules to use in your controller -endprologue. +-------------------------------------------------------------------------------- -### What is an API app? +What is an API app? +------------------- -Traditionally, when people said that they used Rails as an “API”, they -meant providing a programmatically accessible API alongside their web -application.\ -For example, GitHub provides [an API](http://developer.github.com) that -you can use from your own custom clients. +Traditionally, when people said that they used Rails as an "API", they meant +providing a programmatically accessible API alongside their web application. +For example, GitHub provides [an API](http://developer.github.com) that you +can use from your own custom clients. -With the advent of client-side frameworks, more developers are using -Rails to build a backend that is shared between their web application -and other native applications. +With the advent of client-side frameworks, more developers are using Rails to +build a back-end that is shared between their web application and other native +applications. -For example, Twitter uses its [public API](https://dev.twitter.com) in -its web application, which is built as a static site that consumes JSON -resources. +For example, Twitter uses its [public API](https://dev.twitter.com) in its web +application, which is built as a static site that consumes JSON resources. -Instead of using Rails to generate dynamic HTML that will communicate -with the server through forms and links, many developers are treating -their web application as just another client, delivered as static HTML, -CSS and JavaScript, and consuming a simple JSON API +Instead of using Rails to generate dynamic HTML that will communicate with the +server through forms and links, many developers are treating their web application +as just another client, delivered as static HTML, CSS and JavaScript consuming +a simple JSON API. -This guide covers building a Rails application that serves JSON -resources to an API client **or** client-side framework. +This guide covers building a Rails application that serves JSON resources to an +API client **or** a client-side framework. -### Why use Rails for JSON APIs? +Why use Rails for JSON APIs? +---------------------------- -The first question a lot of people have when thinking about building a -JSON API using Rails is: “isn’t using Rails to spit out some JSON -overkill? Shouldn’t I just use something like Sinatra?” +The first question a lot of people have when thinking about building a JSON API +using Rails is: "isn't using Rails to spit out some JSON overkill? Shouldn't I +just use something like Sinatra?". For very simple APIs, this may be true. However, even in very HTML-heavy -applications, most of an application’s logic is actually outside of the -view layer. +applications, most of an application's logic is actually outside of the view +layer. -The reason most people use Rails is that it provides a set of defaults -that allows us to get up and running quickly without having to make a -lot of trivial decisions. +The reason most people use Rails is that it provides a set of defaults that +allows us to get up and running quickly without having to make a lot of trivial +decisions. -Let’s take a look at some of the things that Rails provides out of the -box that are still applicable to API applications. +Let's take a look at some of the things that Rails provides out of the box that are +still applicable to API applications. Handled at the middleware layer: -- Reloading: Rails applications support transparent reloading. This - works even if your application gets big and restarting the server - for every request becomes non-viable. -- Development Mode: Rails application come with smart defaults for - development, making development pleasant without compromising - production-time performance. -- Test Mode: Ditto test mode. -- Logging: Rails applications log every request, with a level of - verbosity appropriate for the current mode. Rails logs in - development include information about the request environment, - database queries, and basic performance information. -- Security: Rails detects and thwarts [IP spoofing - attacks](http://en.wikipedia.org/wiki/IP_address_spoofing) and - handles cryptographic signatures in a [timing - attack](http://en.wikipedia.org/wiki/Timing_attack) aware way. Don’t - know what an IP spoofing attack or a timing attack is? Exactly. -- Parameter Parsing: Want to specify your parameters as JSON instead - of as a URL-encoded String? No problem. Rails will decode the JSON - for you and make it available in *params*. Want to use nested - URL-encoded params? That works too. -- Conditional GETs: Rails handles conditional *GET*, (*ETag* and - *Last-Modified*), processing request headers and returning the - correct response headers and status code. All you need to do is use - the - [stale?](http://api.rubyonrails.org/classes/ActionController/ConditionalGet.html#method-i-stale-3F) - check in your controller, and Rails will handle all of the HTTP - details for you. -- Caching: If you use *dirty?* with public cache control, Rails will - automatically cache your responses. You can easily configure the - cache store. -- HEAD requests: Rails will transparently convert *HEAD* requests into - *GET* requests, and return just the headers on the way out. This - makes *HEAD* work reliably in all Rails APIs. - -While you could obviously build these up in terms of existing Rack -middlewares, I think this list demonstrates that the default Rails -middleware stack provides a lot of value, even if you’re “just -generating JSON”. - -Handled at the ActionPack layer: - -- Resourceful Routing: If you’re building a RESTful JSON API, you want - to be using the Rails router. Clean and conventional mapping from - HTTP to controllers means not having to spend time thinking about - how to model your API in terms of HTTP. -- URL Generation: The flip side of routing is URL generation. A good - API based on HTTP includes URLs (see [the GitHub gist - API](http://developer.github.com/v3/gists/) for an example). -- Header and Redirection Responses: *head :no\_content* and - *redirect\_to user\_url(current\_user)* come in handy. Sure, you - could manually add the response headers, but why? -- Caching: Rails provides page, action and fragment caching. Fragment - caching is especially helpful when building up a nested JSON object. -- Basic, Digest and Token Authentication: Rails comes with - out-of-the-box support for three kinds of HTTP authentication. -- Instrumentation: Rails 3.0 added an instrumentation API that will - trigger registered handlers for a variety of events, such as action - processing, sending a file or data, redirection, and database - queries. The payload of each event comes with relevant information - (for the action processing event, the payload includes the - controller, action, params, request format, request method and the - request’s full path). -- Generators: This may be passé for advanced Rails users, but it can - be nice to generate a resource and get your model, controller, test - stubs, and routes created for you in a single command. -- Plugins: Many third-party libraries come with support for Rails that - reduces or eliminates the cost of setting up and gluing together the - library and the web framework. This includes things like overriding - default generators, adding rake tasks, and honoring Rails choices - (like the logger and cache backend). - -Of course, the Rails boot process also glues together all registered -components. For example, the Rails boot process is what uses your -*config/database.yml* file when configuring ActiveRecord. - -**The short version is**: you may not have thought about which parts of -Rails are still applicable even if you remove the view layer, but the -answer turns out to be “most of it”. - -### The Basic Configuration - -If you’re building a Rails application that will be an API server first -and foremost, you can start with a more limited subset of Rails and add -in features as needed. +- Reloading: Rails applications support transparent reloading. This works even if + your application gets big and restarting the server for every request becomes + non-viable. +- Development Mode: Rails applications come with smart defaults for development, + making development pleasant without compromising production-time performance. +- Test Mode: Ditto development mode. +- Logging: Rails applications log every request, with a level of verbosity + appropriate for the current mode. Rails logs in development include information + about the request environment, database queries, and basic performance + information. +- Security: Rails detects and thwarts [IP spoofing + attacks](http://en.wikipedia.org/wiki/IP_address_spoofing) and handles + cryptographic signatures in a [timing + attack](http://en.wikipedia.org/wiki/Timing_attack) aware way. Don't know what + an IP spoofing attack or a timing attack is? Exactly. +- Parameter Parsing: Want to specify your parameters as JSON instead of as a + URL-encoded String? No problem. Rails will decode the JSON for you and make + it available in `params`. Want to use nested URL-encoded parameters? That + works too. +- Conditional GETs: Rails handles conditional `GET`, (`ETag` and `Last-Modified`), + processing request headers and returning the correct response headers and status + code. All you need to do is use the + [`stale?`](http://api.rubyonrails.org/classes/ActionController/ConditionalGet.html#method-i-stale-3F) + check in your controller, and Rails will handle all of the HTTP details for you. +- Caching: If you use `dirty?` with public cache control, Rails will automatically + cache your responses. You can easily configure the cache store. +- HEAD requests: Rails will transparently convert `HEAD` requests into `GET` ones, + and return just the headers on the way out. This makes `HEAD` work reliably in + all Rails APIs. + +While you could obviously build these up in terms of existing Rack middlewares, +this list demonstrates that the default Rails middleware stack provides a lot +of value, even if you're "just generating JSON". + +Handled at the Action Pack layer: + +- Resourceful Routing: If you're building a RESTful JSON API, you want to be + using the Rails router. Clean and conventional mapping from HTTP to controllers + means not having to spend time thinking about how to model your API in terms + of HTTP. +- URL Generation: The flip side of routing is URL generation. A good API based + on HTTP includes URLs (see [the GitHub gist API](http://developer.github.com/v3/gists/) + for an example). +- Header and Redirection Responses: `head :no_content` and + `redirect_to user_url(current_user)` come in handy. Sure, you could manually + add the response headers, but why? +- Caching: Rails provides page, action and fragment caching. Fragment caching + is especially helpful when building up a nested JSON object. +- Basic, Digest and Token Authentication: Rails comes with out-of-the-box support + for three kinds of HTTP authentication. +- Instrumentation: Rails has an instrumentation API that will trigger registered + handlers for a variety of events, such as action processing, sending a file or + data, redirection, and database queries. The payload of each event comes with + relevant information (for the action processing event, the payload includes + the controller, action, parameters, request format, request method and the + request's full path). +- Generators: This may be passé for advanced Rails users, but it can be nice to + generate a resource and get your model, controller, test stubs, and routes + created for you in a single command. +- Plugins: Many third-party libraries come with support for Rails that reduce + or eliminate the cost of setting up and gluing together the library and the + web framework. This includes things like overriding default generators, adding + rake tasks, and honoring Rails choices (like the logger and cache back-end). + +Of course, the Rails boot process also glues together all registered components. +For example, the Rails boot process is what uses your `config/database.yml` file +when configuring Active Record. + +**The short version is**: you may not have thought about which parts of Rails +are still applicable even if you remove the view layer, but the answer turns out +to be "most of it". + +The Basic Configuration +----------------------- + +If you're building a Rails application that will be an API server first and +foremost, you can start with a more limited subset of Rails and add in features +as needed. You can generate a new api Rails app: -<shell>\ -\$ rails new my\_api --api\ -</shell> +```bash +$ rails new my_api --api +``` This will do three main things for you: -- Configure your application to start with a more limited set of - middleware than normal. Specifically, it will not include any - middleware primarily useful for browser applications (like cookie - support) by default. -- Make *ApplicationController* inherit from *ActionController::API* - instead of *ActionController::Base*. As with middleware, this will - leave out any *ActionController* modules that provide functionality - primarily used by browser applications. -- Configure the generators to skip generating views, helpers and - assets when you generate a new resource. - -If you want to take an existing app and make it an API app, follow the +- Configure your application to start with a more limited set of middlewares + than normal. Specifically, it will not include any middleware primarily useful + for browser applications (like cookies support) by default. +- Make `ApplicationController` inherit from `ActionController::API` instead of + `ActionController::Base`. As with middlewares, this will leave out any Action + Controller modules that provide functionalities primarily used by browser + applications. +- Configure the generators to skip generating views, helpers and assets when + you generate a new resource. + +If you want to take an existing application and make it an API one, read the following steps. -In *config/application.rb* add the following line at the top of the -*Application* class: - -<ruby>\ -config.api\_only!\ -</ruby> - -Change *app/controllers/application\_controller.rb*: - -<ruby> - -1. instead of\ - class ApplicationController \< ActionController::Base\ - end - -<!-- --> - -1. do\ - class ApplicationController \< ActionController::API\ - end\ - </ruby> - -### Choosing Middlewares - -An API application comes with the following middlewares by default. - -- *Rack::Cache*: Caches responses with public *Cache-Control* headers - using HTTP caching semantics. See below for more information. -- *Rack::Sendfile*: Uses a front-end server’s file serving support - from your Rails application. -- *Rack::Lock*: If your application is not marked as threadsafe - (*config.threadsafe!*), this middleware will add a mutex around your - requests. -- *ActionDispatch::RequestId*: -- *Rails::Rack::Logger*: -- *Rack::Runtime*: Adds a header to the response listing the total - runtime of the request. -- *ActionDispatch::ShowExceptions*: Rescue exceptions and re-dispatch - them to an exception handling application -- *ActionDispatch::DebugExceptions*: Log exceptions -- *ActionDispatch::RemoteIp*: Protect against IP spoofing attacks -- *ActionDispatch::Reloader*: In development mode, support code - reloading. -- *ActionDispatch::ParamsParser*: Parse XML, YAML and JSON parameters - when the request’s *Content-Type* is one of those. -- *ActionDispatch::Head*: Dispatch *HEAD* requests as *GET* requests, - and return only the status code and headers. -- *Rack::ConditionalGet*: Supports the *stale?* feature in Rails - controllers. -- *Rack::ETag*: Automatically set an *ETag* on all string responses. - This means that if the same response is returned from a controller - for the same URL, the server will return a *304 Not Modified*, even - if no additional caching steps are taken. This is primarily a - client-side optimization; it reduces bandwidth costs but not server - processing time. - -Other plugins, including *ActiveRecord*, may add additional middlewares. -In general, these middlewares are agnostic to the type of app you are +In `config/application.rb` add the following line at the top of the `Application` +class definition: + +```ruby +config.api_only = true +``` + +Finally, inside `app/controllers/application_controller.rb`, instead of: + +```ruby +class ApplicationController < ActionController::Base +end +``` + +do: + +```ruby +class ApplicationController < ActionController::API +end +``` + +Choosing Middlewares +-------------------- + +An API application comes with the following middlewares by default: + +- `Rack::Sendfile` +- `ActionDispatch::Static` +- `Rack::Lock` +- `ActiveSupport::Cache::Strategy::LocalCache::Middleware` +- `ActionDispatch::RequestId` +- `Rails::Rack::Logger` +- `Rack::Runtime` +- `ActionDispatch::ShowExceptions` +- `ActionDispatch::DebugExceptions` +- `ActionDispatch::RemoteIp` +- `ActionDispatch::Reloader` +- `ActionDispatch::Callbacks` +- `ActionDispatch::ParamsParser` +- `Rack::Head` +- `Rack::ConditionalGet` +- `Rack::ETag` + +See the [internal middlewares](rails_on_rack.html#internal-middleware-stack) +section of the Rack guide for further information on them. + +Other plugins, including Active Record, may add additional middlewares. In +general, these middlewares are agnostic to the type of application you are building, and make sense in an API-only Rails application. You can get a list of all middlewares in your application via: -<shell>\ -\$ rake middleware\ -</shell> +```bash +$ rake middleware +``` -#### Using Rack::Cache +### Using the Cache Middleware -When used with Rails, *Rack::Cache* uses the Rails cache store for its -entity and meta stores. This means that if you use memcache, for your -Rails app, for instance, the built-in HTTP cache will use memcache. +By default, Rails will add a middleware that provides a cache store based on +the configuration of your application (memcache by default). This means that +the built-in HTTP cache will rely on it. -To make use of *Rack::Cache*, you will want to use *stale?* in your -controller. Here’s an example of *stale?* in use. +For instance, using the `stale?` method: -<ruby>\ -def show\ +```ruby +def show @post = Post.find(params[:id]) -if stale?(:last\_modified =\> `post.updated_at) - render json: `post\ - end\ -end\ -</ruby> + if stale?(last_modified: @post.updated_at) + render json: @post + end +end +``` -The call to *stale?* will compare the *If-Modified-Since* header in the -request with *@post.updated\_at*. If the header is newer than the last -modified, this action will return a *304 Not Modified* response. -Otherwise, it will render the response and include a *Last-Modified* -header with the response. +The call to `stale?` will compare the `If-Modified-Since` header in the request +with `@post.updated_at`. If the header is newer than the last modified, this +action will return a "304 Not Modified" response. Otherwise, it will render the +response and include a `Last-Modified` header in it. -Normally, this mechanism is used on a per-client basis. *Rack::Cache* +Normally, this mechanism is used on a per-client basis. The cache middleware allows us to share this caching mechanism across clients. We can enable -cross-client caching in the call to *stale?* +cross-client caching in the call to `stale?`: -<ruby>\ -def show\ +```ruby +def show @post = Post.find(params[:id]) -if stale?(:last\_modified =\> `post.updated_at, :public => true) - render json: `post\ - end\ -end\ -</ruby> + if stale?(last_modified: @post.updated_at, public: true) + render json: @post + end +end +``` -This means that *Rack::Cache* will store off *Last-Modified* value for a -URL in the Rails cache, and add an *If-Modified-Since* header to any +This means that the cache middleware will store off the `Last-Modified` value +for a URL in the Rails cache, and add an `If-Modified-Since` header to any subsequent inbound requests for the same URL. Think of it as page caching using HTTP semantics. -NOTE: The *Rack::Cache* middleware is always outside of the *Rack::Lock* -mutex, even in single-threaded apps. +NOTE: This middleware is always outside of the `Rack::Lock` mutex, even in +single-threaded applications. -#### Using Rack::Sendfile +### Using Rack::Sendfile -When you use the *send\_file* method in a Rails controller, it sets the -*X-Sendfile* header. *Rack::Sendfile* is responsible for actually -sending the file. +When you use the `send_file` method inside a Rails controller, it sets the +`X-Sendfile` header. `Rack::Sendfile` is responsible for actually sending the +file. -If your front-end server supports accelerated file sending, -*Rack::Sendfile* will offload the actual file sending work to the -front-end server. +If your front-end server supports accelerated file sending, `Rack::Sendfile` +will offload the actual file sending work to the front-end server. -You can configure the name of the header that your front-end server uses -for this purposes using *config.action\_dispatch.x\_sendfile\_header* in -the appropriate environment config file. +You can configure the name of the header that your front-end server uses for +this purpose using `config.action_dispatch.x_sendfile_header` in the appropriate +environment's configuration file. -You can learn more about how to use *Rack::Sendfile* with popular +You can learn more about how to use `Rack::Sendfile` with popular front-ends in [the Rack::Sendfile -documentation](http://rubydoc.info/github/rack/rack/master/Rack/Sendfile) +documentation](http://rubydoc.info/github/rack/rack/master/Rack/Sendfile). -The values for popular servers once they are configured to support +Here are some values for popular servers, once they are configured, to support accelerated file sending: -<ruby> - -1. Apache and lighttpd\ - config.action\_dispatch.x\_sendfile\_header = “X-Sendfile” - -<!-- --> - -1. nginx\ - config.action\_dispatch.x\_sendfile\_header = “X-Accel-Redirect”\ - </ruby> - -Make sure to configure your server to support these options following -the instructions in the *Rack::Sendfile* documentation. - -NOTE: The *Rack::Sendfile* middleware is always outside of the -*Rack::Lock* mutex, even in single-threaded apps. - -#### Using ActionDispatch::ParamsParser - -*ActionDispatch::ParamsParser* will take parameters from the client in -JSON and make them available in your controller as *params*. - -To use this, your client will need to make a request with JSON-encoded -parameters and specify the *Content-Type* as *application/json*. - -Here’s an example in jQuery: - -<plain>\ -jQuery.ajax({\ - type: ‘POST’,\ - url: ‘/people’\ - dataType: ‘json’,\ - contentType: ‘application/json’,\ - data: JSON.stringify({ person: { firstName: “Yehuda”, lastName: “Katz” -} }), - -success: function(json) { }\ -});\ -</plain> - -*ActionDispatch::ParamsParser* will see the *Content-Type* and your -params will be *{ :person =\> { :firstName =\> “Yehuda”, :lastName =\> -“Katz” } }*. - -#### Other Middlewares - -Rails ships with a number of other middlewares that you might want to -use in an API app, especially if one of your API clients is the browser: - -- *Rack::MethodOverride*: Allows the use of the *\_method* hack to - route POST requests to other verbs. -- *ActionDispatch::Cookies*: Supports the *cookie* method in - *ActionController*, including support for signed and encrypted - cookies. -- *ActionDispatch::Flash*: Supports the *flash* mechanism in - *ActionController*. -- *ActionDispatch::BestStandards*: Tells Internet Explorer to use the - most standards-compliant available renderer. In production mode, if - ChromeFrame is available, use ChromeFrame. -- Session Management: If a *config.session\_store* is supplied, this - middleware makes the session available as the *session* method in - *ActionController*. - -Any of these middlewares can be adding via: - -<ruby>\ -config.middleware.use Rack::MethodOverride\ -</ruby> - -#### Removing Middlewares - -If you don’t want to use a middleware that is included by default in the -API-only middleware set, you can remove it using -*config.middleware.delete*: - -<ruby>\ -config.middleware.delete ::Rack::Sendfile\ -</ruby> - -Keep in mind that removing these features may remove support for certain -features in *ActionController*. - -### Choosing Controller Modules - -An API application (using *ActionController::API*) comes with the -following controller modules by default: - -- *ActionController::UrlFor*: Makes *url\_for* and friends available -- *ActionController::Redirecting*: Support for *redirect\_to* -- *ActionController::Rendering*: Basic support for rendering -- *ActionController::Renderers::All*: Support for *render :json* and - friends -- *ActionController::ConditionalGet*: Support for *stale?* -- *ActionController::ForceSSL*: Support for *force\_ssl* -- *ActionController::RackDelegation*: Support for the *request* and - *response* methods returning *ActionDispatch::Request* and - *ActionDispatch::Response* objects. -- *ActionController::DataStreaming*: Support for *send\_file* and - *send\_data* -- *AbstractController::Callbacks*: Support for *before\_filter* and - friends -- *ActionController::Instrumentation*: Support for the instrumentation - hooks defined by *ActionController* (see [the - source](https://github.com/rails/rails/blob/master/actionpack/lib/action_controller/metal/instrumentation.rb) - for more). -- *ActionController::Rescue*: Support for *rescue\_from*. - -Other plugins may add additional modules. You can get a list of all -modules included into *ActionController::API* in the rails console: - -<shell>\ -\$ irb\ -\>\> ActionController::API.ancestors - -ActionController::Metal.ancestors\ -</shell> - -#### Adding Other Modules - -All ActionController modules know about their dependent modules, so you -can feel free to include any modules into your controllers, and all -dependencies will be included and set up as well. +```ruby +# Apache and lighttpd +config.action_dispatch.x_sendfile_header = "X-Sendfile" + +# Nginx +config.action_dispatch.x_sendfile_header = "X-Accel-Redirect" +``` + +Make sure to configure your server to support these options following the +instructions in the `Rack::Sendfile` documentation. + +NOTE: The `Rack::Sendfile` middleware is always outside of the `Rack::Lock` +mutex, even in single-threaded applications. + +### Using ActionDispatch::ParamsParser + +`ActionDispatch::ParamsParser` will take parameters from the client in the JSON +format and make them available in your controller inside `params`. + +To use this, your client will need to make a request with JSON-encoded parameters +and specify the `Content-Type` as `application/json`. + +Here's an example in jQuery: + +```javascript +jQuery.ajax({ + type: 'POST', + url: '/people', + dataType: 'json', + contentType: 'application/json', + data: JSON.stringify({ person: { firstName: "Yehuda", lastName: "Katz" } }), + success: function(json) { } +}); +``` + +`ActionDispatch::ParamsParser` will see the `Content-Type` and your parameters +will be: + +```ruby +{ :person => { :firstName => "Yehuda", :lastName => "Katz" } } +``` + +### Other Middlewares + +Rails ships with a number of other middlewares that you might want to use in an +API application, especially if one of your API clients is the browser: + +- `Rack::MethodOverride` +- `ActionDispatch::Cookies` +- `ActionDispatch::Flash` +- For sessions management + * `ActionDispatch::Session::CacheStore` + * `ActionDispatch::Session::CookieStore` + * `ActionDispatch::Session::MemCacheStore` + +Any of these middlewares can be added via: + +```ruby +config.middleware.use Rack::MethodOverride +``` + +### Removing Middlewares + +If you don't want to use a middleware that is included by default in the API-only +middleware set, you can remove it with: + +```ruby +config.middleware.delete ::Rack::Sendfile +``` + +Keep in mind that removing these middlewares will remove support for certain +features in Action Controller. + +Choosing Controller Modules +--------------------------- + +An API application (using `ActionController::API`) comes with the following +controller modules by default: + +- `ActionController::UrlFor`: Makes `url_for` and friends available. +- `ActionController::Redirecting`: Support for `redirect_to`. +- `ActionController::Rendering`: Basic support for rendering. +- `ActionController::Renderers::All`: Support for `render :json` and friends. +- `ActionController::ConditionalGet`: Support for `stale?`. +- `ActionController::ForceSSL`: Support for `force_ssl`. +- `ActionController::RackDelegation`: Support for the `request` and `response` + methods returning `ActionDispatch::Request` and `ActionDispatch::Response` + objects. +- `ActionController::DataStreaming`: Support for `send_file` and `send_data`. +- `AbstractController::Callbacks`: Support for `before_filter` and friends. +- `ActionController::Instrumentation`: Support for the instrumentation + hooks defined by Action Controller (see [the instrumentation + guide](active_support_instrumentation.html#action-controller)). +- `ActionController::Rescue`: Support for `rescue_from`. +- `ActionController::BasicImplicitRender`: Makes sure to return an empty response + if there's not an explicit one. +- `ActionController::StrongParameters`: Support for parameters white-listing in + combination with Active Model mass assignment. +- `ActionController::ParamsWrapper`: Wraps the parameters hash into a nested hash + so you don't have to specify root elements sending POST requests for instance. + +Other plugins may add additional modules. You can get a list of all modules +included into `ActionController::API` in the rails console: + +```bash +$ bin/rails c +>> ActionController::API.ancestors - ActionController::Metal.ancestors +``` + +### Adding Other Modules + +All Action Controller modules know about their dependent modules, so you can feel +free to include any modules into your controllers, and all dependencies will be +included and set up as well. Some common modules you might want to add: -- *AbstractController::Translation*: Support for the *l* and *t* - localization and translation methods. These delegate to - *I18n.translate* and *I18n.localize*. -- *ActionController::HTTPAuthentication::Basic* (or *Digest* - or +Token): Support for basic, digest or token HTTP authentication. -- *AbstractController::Layouts*: Support for layouts when rendering. -- *ActionController::MimeResponds*: Support for content negotiation - (*respond\_to*, *respond\_with*). -- *ActionController::Cookies*: Support for *cookies*, which includes - support for signed and encrypted cookies. This requires the cookie - middleware. - -The best place to add a module is in your *ApplicationController*. You -can also add modules to individual controllers. +- `AbstractController::Translation`: Support for the `l` and `t` localization + and translation methods. +- `ActionController::HTTPAuthentication::Basic` (or `Digest` or `Token`): Support + for basic, digest or token HTTP authentication. +- `AbstractController::Layouts`: Support for layouts when rendering. +- `ActionController::MimeResponds`: Support for `respond_to`. +- `ActionController::Cookies`: Support for `cookies`, which includes + support for signed and encrypted cookies. This requires the cookies middleware. + +The best place to add a module is in your `ApplicationController` but you can +also add modules to individual controllers. diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md index 05dd0d2a04..5c96a53d09 100644 --- a/guides/source/association_basics.md +++ b/guides/source/association_basics.md @@ -2344,13 +2344,13 @@ associations, public methods, etc. Creating a car will save it in the `vehicles` table with "Car" as the `type` field: ```ruby -Car.create color: 'Red', price: 10000 +Car.create(color: 'Red', price: 10000) ``` will generate the following SQL: ```sql -INSERT INTO "vehicles" ("type", "color", "price") VALUES ("Car", "Red", 10000) +INSERT INTO "vehicles" ("type", "color", "price") VALUES ('Car', 'Red', 10000) ``` Querying car records will just search for vehicles that are cars: diff --git a/guides/source/caching_with_rails.md b/guides/source/caching_with_rails.md index 782406659d..b0103c9af4 100644 --- a/guides/source/caching_with_rails.md +++ b/guides/source/caching_with_rails.md @@ -1,14 +1,14 @@ **DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON http://guides.rubyonrails.org.** -Caching with Rails: An overview +Caching with Rails: An Overview =============================== -This guide will teach you what you need to know about avoiding that expensive round-trip to your database and returning what you need to return to the web clients in the shortest time possible. +This guide is an introduction to speeding up your Rails app with caching. After reading this guide, you will know: -* Page and action caching (moved to separate gems as of Rails 4). -* Fragment caching. +* Page and action caching. +* Fragment and Russian doll caching. * Alternative cache stores. * Conditional GET support. @@ -18,11 +18,14 @@ Basic Caching ------------- This is an introduction to three types of caching techniques: page, action and -fragment caching. Rails provides by default fragment caching. In order to use -page and action caching, you will need to add `actionpack-page_caching` and +fragment caching. By default Rails provides fragment caching. In order to use +page and action caching you will need to add `actionpack-page_caching` and `actionpack-action_caching` to your Gemfile. -To start playing with caching you'll want to ensure that `config.action_controller.perform_caching` is set to `true` if you're running in development mode. This flag is normally set in the corresponding `config/environments/*.rb` and caching is disabled by default for development and test, and enabled for production. +By default, caching is only enabled in your production environment. To play +around with caching locally you'll want to enable caching in your local +environment by setting `config.action_controller.perform_caching` to `true` in +the relevant `config/environments/*.rb` file: ```ruby config.action_controller.perform_caching = true @@ -30,7 +33,12 @@ config.action_controller.perform_caching = true ### Page Caching -Page caching is a Rails mechanism which allows the request for a generated page to be fulfilled by the webserver (i.e. Apache or NGINX), without ever having to go through the Rails stack at all. Obviously, this is super-fast. Unfortunately, it can't be applied to every situation (such as pages that need authentication) and since the webserver is literally just serving a file from the filesystem, cache expiration is an issue that needs to be dealt with. +Page caching is a Rails mechanism which allows the request for a generated page +to be fulfilled by the webserver (i.e. Apache or NGINX) without having to go +through the entire Rails stack. While this is super fast it can't be applied to +every situation (such as pages that need authentication). Also, because the +webserver is serving a file directly from the filesystem you will need to +implement cache expiration. INFO: Page Caching has been removed from Rails 4. See the [actionpack-page_caching gem](https://github.com/rails/actionpack-page_caching). @@ -42,105 +50,102 @@ INFO: Action Caching has been removed from Rails 4. See the [actionpack-action_c ### Fragment Caching -Life would be perfect if we could get away with caching the entire contents of a page or action and serving it out to the world. Unfortunately, dynamic web applications usually build pages with a variety of components not all of which have the same caching characteristics. In order to address such a dynamically created page where different parts of the page need to be cached and expired differently, Rails provides a mechanism called Fragment Caching. +Dynamic web applications usually build pages with a variety of components not +all of which have the same caching characteristics. When different parts of the +page need to be cached and expired separately you can use Fragment Caching. Fragment Caching allows a fragment of view logic to be wrapped in a cache block and served out of the cache store when the next request comes in. -As an example, if you wanted to show all the orders placed on your website in real time and didn't want to cache that part of the page, but did want to cache the part of the page which lists all products available, you could use this piece of code: +For example, if you wanted to cache each product on a page, you could use this +code: ```html+erb -<% Order.find_recent.each do |o| %> - <%= o.buyer.name %> bought <%= o.product.name %> -<% end %> - -<% cache do %> - All available products: - <% Product.all.each do |p| %> - <%= link_to p.name, product_url(p) %> +<% @products.each do |product| %> + <% cache product do %> + <%= render product %> <% end %> <% end %> ``` -The cache block in our example will bind to the action that called it and is written out to the same place as the Action Cache, which means that if you want to cache multiple fragments per action, you should provide an `action_suffix` to the cache call: +When your application receives its first request to this page, Rails will write +a new cache entry with a unique key. A key looks something like this: -```html+erb -<% cache(action: 'recent', action_suffix: 'all_products') do %> - All available products: +``` +views/products/1-201505056193031061005000/bea67108094918eeba42cd4a6e786901 ``` -and you can expire it using the `expire_fragment` method, like so: +The number in the middle is the `product_id` followed by the timestamp value in +the `updated_at` attribute of the product record. Rails uses the timestamp value +to make sure it is not serving stale data. If the value of `updated_at` has +changed, a new key will be generated. Then Rails will write a new cache to that +key, and the old cache written to the old key will never be used again. This is +called key-based expiration. -```ruby -expire_fragment(controller: 'products', action: 'recent', action_suffix: 'all_products') -``` +Cache fragments will also be expired when the view fragment changes (e.g., the +HTML in the view changes). The string of characters at the end of the key is a +template tree digest. It is an md5 hash computed based on the contents of the +view fragment you are caching. If you change the view fragment, the md5 hash +will change, expiring the existing file. + +TIP: Cache stores like Memcached will automatically delete old cache files. -If you don't want the cache block to bind to the action that called it, you can also use globally keyed fragments by calling the `cache` method with a key: +If you want to cache a fragment under certain conditions, you can use +`cache_if` or `cache_unless`: ```erb -<% cache('all_available_products') do %> - All available products: +<% cache_if admin?, product do %> + <%= render product %> <% end %> ``` -This fragment is then available to all actions in the `ProductsController` using the key and can be expired the same way: +### Russian Doll Caching -```ruby -expire_fragment('all_available_products') -``` -If you want to avoid expiring the fragment manually, whenever an action updates a product, you can define a helper method: +You may want to nest cached fragments inside other cached fragments. This is +called Russian doll caching. -```ruby -module ProductsHelper - def cache_key_for_products - count = Product.count - max_updated_at = Product.maximum(:updated_at).try(:utc).try(:to_s, :number) - "products/all-#{count}-#{max_updated_at}" - end -end -``` +The advantage of Russian doll caching is that if a single product is updated, +all the other inner fragments can be reused when regenerating the outer +fragment. -This method generates a cache key that depends on all products and can be used in the view: +As explained in the previous section, a cached file will expire if the value of +`updated_at` changes for a record on which the cached file directly depends. +However, this will not expire any cache the fragment is nested within. -```erb -<% cache(cache_key_for_products) do %> - All available products: -<% end %> -``` - -If you want to cache a fragment under certain conditions, you can use `cache_if` or `cache_unless` +For example, take the following view: ```erb -<% cache_if (condition, cache_key_for_products) do %> - All available products: +<% cache product do %> + <%= render product.games %> <% end %> ``` -You can also use an Active Record model as the cache key: +Which in turn renders this view: ```erb -<% Product.all.each do |p| %> - <% cache(p) do %> - <%= link_to p.name, product_url(p) %> - <% end %> +<% cache game %> + <%= render game %> <% end %> ``` -Behind the scenes, a method called `cache_key` will be invoked on the model and it returns a string like `products/23-20130109142513`. The cache key includes the model name, the id and finally the updated_at timestamp. Thus it will automatically generate a new fragment when the product is updated because the key changes. +If any attribute of game is changed, the `updated_at` value will be set to the +current time, thereby expiring the cache. However, because `updated_at` +will not be changed for the product object, that cache will not be expired and +your app will serve stale data. To fix this, we tie the models together with +the `touch` method: -You can also combine the two schemes which is called "Russian Doll Caching": +```ruby +class Product < ActiveRecord::Base + has_many :games +end -```erb -<% cache(cache_key_for_products) do %> - All available products: - <% Product.all.each do |p| %> - <% cache(p) do %> - <%= link_to p.name, product_url(p) %> - <% end %> - <% end %> -<% end %> +class Game < ActiveRecord::Base + belongs_to :product, touch: true +end ``` -It's called "Russian Doll Caching" because it nests multiple fragments. The advantage is that if a single product is updated, all the other inner fragments can be reused when regenerating the outer fragment. +With `touch` set to true, any action which changes `updated_at` for a game +record will also change it for the associated product, thereby expiring the +cache. ### Low-Level Caching @@ -164,7 +169,10 @@ NOTE: Notice that in this example we used the `cache_key` method, so the resulti ### SQL Caching -Query caching is a Rails feature that caches the result set returned by each query so that if Rails encounters the same query again for that request, it will use the cached result set as opposed to running the query against the database again. +Query caching is a Rails feature that caches the result set returned by each +query. If Rails encounters the same query again for that request, it will use +the cached result set as opposed to running the query against the database +again. For example: @@ -186,7 +194,10 @@ end The second time the same query is run against the database, it's not actually going to hit the database. The first time the result is returned from the query it is stored in the query cache (in memory) and the second time it's pulled from memory. -However, it's important to note that query caches are created at the start of an action and destroyed at the end of that action and thus persist only for the duration of the action. If you'd like to store query results in a more persistent fashion, you can in Rails by using low level caching. +However, it's important to note that query caches are created at the start of +an action and destroyed at the end of that action and thus persist only for the +duration of the action. If you'd like to store query results in a more +persistent fashion, you can with low level caching. Cache Stores ------------ @@ -227,13 +238,21 @@ There are some common options used by all cache implementations. These can be pa ### ActiveSupport::Cache::MemoryStore -This cache store keeps entries in memory in the same Ruby process. The cache store has a bounded size specified by the `:size` option to the initializer (default is 32Mb). When the cache exceeds the allotted size, a cleanup will occur and the least recently used entries will be removed. +This cache store keeps entries in memory in the same Ruby process. The cache +store has a bounded size specified by sending the `:size` option to the +initializer (default is 32Mb). When the cache exceeds the allotted size, a +cleanup will occur and the least recently used entries will be removed. ```ruby config.cache_store = :memory_store, { size: 64.megabytes } ``` -If you're running multiple Ruby on Rails server processes (which is the case if you're using mongrel_cluster or Phusion Passenger), then your Rails server process instances won't be able to share cache data with each other. This cache store is not appropriate for large application deployments, but can work well for small, low traffic sites with only a couple of server processes or for development and test environments. +If you're running multiple Ruby on Rails server processes (which is the case +if you're using mongrel_cluster or Phusion Passenger), then your Rails server +process instances won't be able to share cache data with each other. This cache +store is not appropriate for large application deployments. However, it can +work well for small, low traffic sites with only a couple of server processes, +as well as development and test environments. ### ActiveSupport::Cache::FileStore @@ -243,9 +262,13 @@ This cache store uses the file system to store entries. The path to the director config.cache_store = :file_store, "/path/to/cache/directory" ``` -With this cache store, multiple server processes on the same host can share a cache. Server processes running on different hosts could share a cache by using a shared file system, but that set up would not be ideal and is not recommended. The cache store is appropriate for low to medium traffic sites that are served off one or two hosts. +With this cache store, multiple server processes on the same host can share a +cache. The cache store is appropriate for low to medium traffic sites that are +served off one or two hosts. Server processes running on different hosts could +share a cache by using a shared file system, but that setup is not recommended. -Note that the cache will grow until the disk is full unless you periodically clear out old entries. +As the cache will grow until the disk is full, it is recommended to +periodically clear out old entries. This is the default cache store implementation. @@ -253,7 +276,10 @@ This is the default cache store implementation. This cache store uses Danga's `memcached` server to provide a centralized cache for your application. Rails uses the bundled `dalli` gem by default. This is currently the most popular cache store for production websites. It can be used to provide a single, shared cache cluster with very high performance and redundancy. -When initializing the cache, you need to specify the addresses for all memcached servers in your cluster. If none is specified, it will assume memcached is running on the local host on the default port, but this is not an ideal set up for larger sites. +When initializing the cache, you need to specify the addresses for all +memcached servers in your cluster. If none are specified, it will assume +memcached is running on localhost on the default port, but this is not an ideal +setup for larger sites. The `write` and `fetch` methods on this cache accept two additional options that take advantage of features specific to memcached. You can specify `:raw` to send a value directly to the server with no serialization. The value must be a string or number. You can use memcached direct operations like `increment` and `decrement` only on raw values. You can also specify `:unless_exist` if you don't want memcached to overwrite an existing entry. @@ -383,3 +409,9 @@ class ProductsController < ApplicationController end end ``` + +References +---------- + +* [DHH's article on key-based expiration](https://signalvnoise.com/posts/3113-how-key-based-cache-expiration-works) +* [Ryan Bates' Railscast on cache digests](http://railscasts.com/episodes/387-cache-digests) diff --git a/guides/source/development_dependencies_install.md b/guides/source/development_dependencies_install.md index 295e48f493..3c670a1221 100644 --- a/guides/source/development_dependencies_install.md +++ b/guides/source/development_dependencies_install.md @@ -9,7 +9,7 @@ After reading this guide, you will know: * How to set up your machine for Rails development * How to run specific groups of unit tests from the Rails test suite -* How the ActiveRecord portion of the Rails test suite operates +* How the Active Record portion of the Rails test suite operates -------------------------------------------------------------------------------- @@ -60,7 +60,7 @@ In Ubuntu you're done with just: $ sudo apt-get install sqlite3 libsqlite3-dev ``` -And if you are on Fedora or CentOS, you're done with +If you are on Fedora or CentOS, you're done with ```bash $ sudo yum install sqlite3 sqlite3-devel @@ -213,7 +213,7 @@ FreeBSD users will have to run the following: ```bash # pkg install mysql56-client mysql56-server -# pkg install postgresql93-client postgresql93-server +# pkg install postgresql94-client postgresql94-server ``` Or install them through ports (they are located under the `databases` folder). diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index e64a788ac2..79d4393f32 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -1547,11 +1547,10 @@ class CreateComments < ActiveRecord::Migration t.text :body # this line adds an integer column called `article_id`. - t.references :article, index: true + t.references :article, index: true, foreign_key: true t.timestamps null: false end - add_foreign_key :comments, :articles end end ``` @@ -1571,8 +1570,6 @@ run against the current database, so in this case you will just see: == CreateComments: migrating ================================================= -- create_table(:comments) -> 0.0115s --- add_foreign_key(:comments, :articles) - -> 0.0000s == CreateComments: migrated (0.0119s) ======================================== ``` diff --git a/guides/source/i18n.md b/guides/source/i18n.md index 9f0ed1a85b..31682464ee 100644 --- a/guides/source/i18n.md +++ b/guides/source/i18n.md @@ -216,8 +216,8 @@ We can include something like this in our `ApplicationController` then: ```ruby # app/controllers/application_controller.rb -def default_url_options(options = {}) - { locale: I18n.locale }.merge options +def default_url_options + { locale: I18n.locale } end ``` @@ -225,7 +225,7 @@ Every helper method dependent on `url_for` (e.g. helpers for named routes like ` You may be satisfied with this. It does impact the readability of URLs, though, when the locale "hangs" at the end of every URL in your application. Moreover, from the architectural standpoint, locale is usually hierarchically above the other parts of the application domain: and URLs should reflect this. -You probably want URLs to look like this: `www.example.com/en/books` (which loads the English locale) and `www.example.com/nl/books` (which loads the Dutch locale). This is achievable with the "over-riding `default_url_options`" strategy from above: you just have to set up your routes with [`scoping`](http://api.rubyonrails.org/classes/ActionDispatch/Routing/Mapper/Scoping.html) option in this way: +You probably want URLs to look like this: `http://www.example.com/en/books` (which loads the English locale) and `http://www.example.com/nl/books` (which loads the Dutch locale). This is achievable with the "over-riding `default_url_options`" strategy from above: you just have to set up your routes with [`scope`](http://api.rubyonrails.org/classes/ActionDispatch/Routing/Mapper/Scoping.html): ```ruby # config/routes.rb @@ -234,7 +234,9 @@ scope "/:locale" do end ``` -Now, when you call the `books_path` method you should get `"/en/books"` (for the default locale). An URL like `http://localhost:3001/nl/books` should load the Dutch locale, then, and following calls to `books_path` should return `"/nl/books"` (because the locale changed). +Now, when you call the `books_path` method you should get `"/en/books"` (for the default locale). A URL like `http://localhost:3001/nl/books` should load the Dutch locale, then, and following calls to `books_path` should return `"/nl/books"` (because the locale changed). + +WARNING. Since the return value of `default_url_options` is cached per request, the URLs in a locale selector cannot be generated invoking helpers in a loop that sets the corresponding `I18n.locale` in each iteration. Instead, leave `I18n.locale` untouched, and pass an explicit `:locale` option to the helper, or edit `request.original_fullpath`. If you don't want to force the use of a locale in your routes you can use an optional path scope (denoted by the parentheses) like so: diff --git a/guides/source/rails_on_rack.md b/guides/source/rails_on_rack.md index 993cd5ac44..99ab47d1db 100644 --- a/guides/source/rails_on_rack.md +++ b/guides/source/rails_on_rack.md @@ -68,11 +68,10 @@ def middleware end ``` -`Rails::Rack::Debugger` is primarily useful only in the development environment. The following table explains the usage of the loaded middlewares: +The following table explains the usage of the loaded middlewares: | Middleware | Purpose | | ----------------------- | --------------------------------------------------------------------------------- | -| `Rails::Rack::Debugger` | Starts Debugger | | `Rack::ContentLength` | Counts the number of bytes in the response and set the HTTP Content-Length header | ### `rackup` @@ -83,7 +82,6 @@ To use `rackup` instead of Rails' `rails server`, you can put the following insi # Rails.root/config.ru require ::File.expand_path('../config/environment', __FILE__) -use Rails::Rack::Debugger use Rack::ContentLength run Rails.application ``` @@ -329,8 +327,6 @@ Resources * [Official Rack Website](http://rack.github.io) * [Introducing Rack](http://chneukirchen.org/blog/archive/2007/02/introducing-rack.html) -* [Ruby on Rack #1 - Hello Rack!](http://m.onkey.org/ruby-on-rack-1-hello-rack) -* [Ruby on Rack #2 - The Builder](http://m.onkey.org/ruby-on-rack-2-the-builder) ### Understanding Middlewares |