Permalink
Browse files

reformat readme

  • Loading branch information...
1 parent 8d1e9ca commit 22dfba6c9dfa9d1b949c42071412c01e5efd847b @mislav committed Nov 1, 2008
Showing with 114 additions and 80 deletions.
  1. +114 −80 README.markdown
View
@@ -1,98 +1,132 @@
masochism
=========
-The masochism plugin provides an easy solution for Ruby on Rails applications to
-work in a replicated database environment. Connection proxy sends some database
-queries (those in a transaction, update statements, and ActiveRecord::Base#reload)
-to a master database, and the rest to the slave database.
-
-The ActiveReload::MasterDatabase model uses a 'master_database' setting that
-can either be defined for all of your environments, or for each environment as
-a nested declaration.
-
-The ActiveReload::SlaveDatabase model uses a 'slave_database' setting that
-can only be defined per environment.
-
-Example declarations:
-
- # config/database.yml
- login: &login
- adapter: postgresql
- host: localhost
- port: 5432
-
- production:
- database: production_slave_database_name
- <<: *login
-
- master_database:
- database: production_master_database_name
- <<: *login
-
- staging:
- database: staging_database_name
- host: slave-db-pool.local
- <<: *login
- master_database:
- database: staging_database_name
- host: master-db-server.local
- <<: *login
+The masochism plugin provides an easy solution for Ruby on Rails applications to work in a
+replicated database environment. It works by replacing the `connection` object accessed by
+ActiveRecord models by ConnectionProxy that chooses between master and slave when
+executing queries. Generally all writes go to master.
+
+
+Quick setup
+-----------
+
+First, setup your database.yml:
+
+ # default configuration (slave)
+ production: &defaults
+ adapter: mysql
+ database: app_production
+ username: webapp
+ password: ********
+ host: localhost
+
+ # setup for masochism (master)
+ master_database:
+ <<: *defaults
+ host: master.example.com
+
+To enable masochism, this is required:
+
+ # enable masochism
+ ActiveReload::ConnectionProxy.setup!
+
+Example usage:
+
+ # in environment.rb
+ config.after_initialize do
+ if Rails.env.production?
+ ActiveReload::ConnectionProxy::setup!
+ end
+ end
- qa:
- database: qa_master_database_name
- host: qa-master
- <<: *login
- slave_database:
- database: qa_slave_database_name
- host: qa-slave
- <<: *login
- development: # Does not use masochism
- database: development_database_name
- <<: *login
+Considerations
+--------------
-To setup:
+### Litespeed web server
-Whether you want this in production only, or maybe just your deployment server,
-is up to you. Just call the following method in your desired environment file.
+If you are using the Litespeed web server, child processes are initialized on creation,
+which means any setup done in an environment file will be effectively ignored. [A brief
+discussion of the problem is posted here](http://litespeedtech.com/support/wiki/doku.php?id=litespeed_wiki:rails:memcache).
- ActiveReload::ConnectionProxy.setup!
+One solution for Litespeed users is to check the connection at your first request and do
+the `setup!` call if your connection hasn't been initialized, like:
-Some suggestions:
+ # in ApplicationController
+ prepend_before_filter do |controller|
+ unless ActiveRecord::Base.connection.is_a? ActiveReload::ConnectionProxy
+ ActiveReload::ConnectionProxy.setup!
+ end
+ end
- * in a config/initializer
- * config.after_initialize block
-If you are using the Litespeed web server, child processes are initialized on
-creation, which means any setup done in an environment file will be effectively
-ignored. A brief discussion of the problem is posted here:
-http://litespeedtech.com/support/wiki/doku.php?id=litespeed_wiki:rails:memcache
+Advanced
+--------
+
+The ActiveReload::MasterDatabase model uses a 'master_database' setting that can either be
+defined for all of your environments, or for each environment as a nested declaration.
+
+The ActiveReload::SlaveDatabase model uses a 'slave_database' setting that can only be
+defined per environment.
+
+Example:
+
+ login: &login
+ adapter: postgresql
+ host: localhost
+ port: 5432
+
+ production:
+ database: production_slave_database_name
+ <<: *login
+
+ master_database:
+ database: production_master_database_name
+ <<: *login
+
+ staging:
+ database: staging_database_name
+ host: slave-db-pool.local
+ <<: *login
+ master_database:
+ database: staging_database_name
+ host: master-db-server.local
+ <<: *login
+
+ qa:
+ database: qa_master_database_name
+ host: qa-master
+ <<: *login
+ slave_database:
+ database: qa_slave_database_name
+ host: qa-slave
+ <<: *login
+
+ development: # Does not use masochism
+ database: development_database_name
+ <<: *login
+
+If you want a model to always use the Master database, you can inherit
+`ActiveReload::MasterDatabase`. Any models with their own database connection will not be
+affected.
+
+### More control at setup
-One solution for Litespeed users is to check the connection at your first request
-and do the setup! call if your connection hasn't been initialized, like:
+By default, masochism `setup!` is a shorthand for this:
-class ApplicationController < ActionController::Base
- prepend_before_filter do |controller|
- ActiveReload::ConnectionProxy.setup! unless ActiveRecord::Base.connection.is_a? ActiveReload::ConnectionProxy
- end
- ...
-end
+ ActiveReload::ConnectionProxy.setup_for ActiveReload::MasterDatabase, ActiveRecord::Base
+The first argument is the model that has the master database connection established; the
+second argument is the model whose `connection` gets hijacked by ConnectionProxy. But we
+don't have to touch `ActiveRecord::Base` at all:
-If you want a model to always use the Master database, you can inherit
-ActiveRelaod::MasterDatabase. Any models with their own database connection
-will not be affected.
+ # set up MyMaster's connection as the master database connection for User:
+ ActiveReload::ConnectionProxy.setup_for MyMaster, User
-Setting up your own proxies:
+### The controller filter
- # Sets up MyMaster's connection as the master database connection for User.
- ActiveReload::ConnectionProxy.setup_for MyMaster, User
-
-Using the MasterFilter class is quite simple. If you have any actions you know require
-the Master DB for both reads and writes simply do the following:
+If you have any actions you know require the master database for both reads and writes,
+simply do the following:
-class RandomController < ApplicationController
- around_filter ActiveReload::MasterFilter, :only => [:show, :edit, :update]
-
- ...
-end
+ # in a controller:
+ around_filter ActiveReload::MasterFilter, :only => [:show, :edit, :update]

0 comments on commit 22dfba6

Please sign in to comment.