henrypoydar / couchrest-rails

A Rails plugin for connecting to and working with CouchDB via CouchRest

CouchRest-Rails

A Rails plugin for connecting to and working with a CouchDB document-oriented database via the CouchRest RESTful CouchDB client.

Specifically, this plugin provides the following utilities:

• Initializer for use with a couchdb.yml configuration file
• CouchDB-specific rake tasks (database creation, deletion, fixture loading, views synchronization)
• CouchDB-specific fixtures
• Setup and teardown helpers for spec'ing and testing
• A paper-thin wrapper around CouchRest::ExtendedDocument
• Support for multiple CouchDB databases per application
• Optional support for Lucene full-text indexing and searching of your CouchDB databases and documents

This plugin does not interfere with the traditional relational database backend, so you can use that as a datastore alongside CouchDB if you want. (In fact, you'll have to unwire the requirement for a relational database if you don't want to use one.)

This plugin assumes some knowledge of CouchDB and its important differences from conventional Rails data storage (RDBMS) options. See the CouchDB site for more information.

Requirements

• CouchRest gem
• Validatable gem
• JSON gem
• RSpec BDD framework (optional - for running plugin specs)
• RSpec-Rails library (optional - for running plugin specs)
• Lucene (optional) for full text searching of CouchDB documents

Installation

Install with the native Rails plugin installation script:

script/plugin install git://github.com/hpoydar/couchrest-rails.git

Or simply add to vendor/plugins and generate the files you need:

script/generate couch_rest_rails

The plugin creates two folders:

• db/couch/ - For storing CouchDB database information map and reduce functions (views)
• test/fixtures/couch - for storing and loading CouchDB fixtures (yaml)

These paths can be customized in an initializer or environment configuration file:

CouchRestRails.fixtures_path  = 'custom/path/to/your/fixtures/from/app/root'
CouchRestRails.views_path     = 'custom/path/to/your/views/from/app/root'

The installation process will also create a config/couchdb.yml file for customizing your configuration.

Usage

Configuration

The couchdb.yml file can be customized to support the specifics of your particular CouchDB installation. Since multiple databases per application are supported, it is recommended that you specify a database_prefix for use in naming the database on the CouchDB server. This will make it much easier to peer into your server with Sofa and figure out which databases belong to which application.

Database names are defined in the CouchRestRails::Document models that use them. (See below, 'CouchRestRails document model')

Rake tasks

Use the rake tasks to create databases, delete databases, reset databases, push views and load fixtures:

rake couchdb:create[database]             # Create a CouchDB database defined in config/couchdb.yml for the current environment (use no database argument to use all databases defined in CouchRestRails::Document models)
rake couchdb:delete[database]             # Deletes a CouchDB database for the current RAILS_ENV (use no database argument to use all databases defined in CouchRestRails::Document models)
rake couchdb:fixtures:load[database]      # Load fixtures into a current environment's CouchDB database (use no database argument to use all databases defined in CouchRestRails::Document models)
rake couchdb:lucene:push[database]        # Push Lucene views into a current environment's CouchDB database (use no database argument to use all databases defined in CouchRestRails::Document models)
rake couchdb:views:push[database]         # Push views into a current environment's CouchDB database (use no database argument to use all databases defined in CouchRestRails::Document models)
rake doc:plugins:couchrest-rails          # Generate documentation for the couchrest-rails plugin

CouchRestRails document model

For models, inherit from CouchRestRails::Document, which hooks up CouchRest::ExtendedDocument to your CouchDB backend and includes the Validatable module:

class YourCouchDocument < CouchRestRails::Document
  use_database :database_name

  property  :email
  property  :question
  property  :answer
  property  :rating

  timestamps!

  view_by :email

  validates_presence_of :question
  validates_numericality_of :rating

  ...

end

Make sure you define your database in the model with the use_database :<database_name> directive.

See the CouchRest documentation and specs for more information about CouchRest::ExtendedDocument. (The views defined here are in addition to the ones you can manually set up and push via rake in db/couch/views.)

CouchDB views

Custom views--outside of the ones defined in your CouchRestRails::Document models--that you want to push up to the CouchDB database/server instance should be in the following format:

db/couch/<database_name>/views
                           |-- <design_document_name>
                               |-- <view_name>
                                   |-- map.js
                                   `-- reduce.js

Push up your views via rake (rake couchdb:views:push) or within your code or console (CouchRestRails::Views.push).

Tests, specs and fixtures

For testing or spec'ing, use these helpers to setup and teardown a test database with fixtures:

CouchRestRails::Tests.setup
CouchRestRails::Tests.teardown

There are also some simple matchers you can can use to spec validations. See spec/lib/matchers.

You can store fixtures as Yaml files in the following path pattern:

test/fixtures/couch/<database_name>.yml

You can customize this path in an initializer or environment file:

CouchRestRails.fixtures_path = 'custom/path/to/your/fixtures'

Rails integration unit testing

Create fixture file by via rake (rake couchdb:fixtures:dump[<database_name>]) or within your code or console (CouchRestRails::Fixtures.dump[<database_name>]).

Add fixtures to rails test:

class RailsTest < Test::Unit::TestCase
  couchdb_fixtures :<database_name>

  ...
end

Lucene

If you want to support Lucene full-text searching of CouchDB documents, enable support for it in an initializer or environment configuration file:

CouchRestRails.use_lucene  = true

The Lucene design documents per database are stored alongside the views:

db/couch/<database_name>/lucene
                           |-- <design_document_name>
                               |-- <lucene_search>.js
                               |-- <lucene_search>.js
                               |-- ...

You can also customize this path:

CouchRestRails.lucene_path = 'custom/path/to/your/lucene/docs/from/app/root'

Push up your lucene doc via rake (rake couchdb:lucence:push) or within your code or console (CouchRestRails::Lucene.push).

Further development and testing

To run the test suite, you'll need rspec installed with rspec-rails library enabled for the host application. You can run the tests in the following way:

<rails_root>$ rake spec:plugins
<plugin_root>$ rake spec
<plugin_root>$ autospec

(The latter requires the ZenTest gem)

Please don't submit any pull requests with failing specs

TODO

• Roll up CouchRest::ExtendedDocument, since it might be deprecated from CouchRest (see CouchRest raw branch)
• A persistent connection object? Keep-alive?
• Hook into Rails logger to display times for CouchDB operations
• Mechanism for better view testing?
• Restful model/controller/test/spec generator
• Error class for CouchRestRails::Document with I18n support
• Support a default database for all CouchRestRails::Document models
• Gemify
• Add more parseable options to couchdb.yml

Contributors / Thanks

• Arnaud Berthomier
• Dave Farkas
• Adam Keyes
• Glenn Rempe
• John Wood

License

Copyright (c) Henry Poydar, released under the MIT license

couchrest-rails's Issues

uninitialized constant CouchRestRails::Document::COUCHDB_SERVER

First of all, nice work! I was frustrated with BasicModel and decided to write something better, and then saw you had already done it.

One problem: I get the error above, pretty much no matter what I try to do.
See below for details.

ALso get this when trying to run a unit test.

---

linux-3:mma uhgall$ rake couchdb:create --trace
(in /Users/uhgall/code/mma)
** Invoke couchdb:create (first_time)
** Invoke environment (first_time)
** Execute environment
rake aborted!
uninitialized constant CouchRestRails::Document::COUCHDB_SERVER
/Users/uhgall/code/mma/vendor/rails/activesupport/lib/active_support/dependencies.rb:105:in const_missing' /Users/uhgall/code/mma/vendor/plugins/couchrest-rails/lib/couch_rest_rails/document.rb:3 /Users/uhgall/code/mma/vendor/rails/activesupport/lib/active_support/dependencies.rb:380:inload_without_new_constant_marking'
/Users/uhgall/code/mma/vendor/rails/activesupport/lib/active_support/dependencies.rb:380:in load_file' /Users/uhgall/code/mma/vendor/rails/activesupport/lib/active_support/dependencies.rb:521:innew_constants_in'
/Users/uhgall/code/mma/vendor/rails/activesupport/lib/active_support/dependencies.rb:379:in load_file' /Users/uhgall/code/mma/vendor/rails/activesupport/lib/active_support/dependencies.rb:259:inrequire_or_load'
/Users/uhgall/code/mma/vendor/rails/activesupport/lib/active_support/dependencies.rb:425:in load_missing_constant' /Users/uhgall/code/mma/vendor/rails/activesupport/lib/active_support/dependencies.rb:80:inconst_missing'
/Users/uhgall/code/mma/vendor/plugins/basic_model/lib/basic_model.rb:34
/Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in gem_original_require' /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:inrequire'

line in init.rb causes shoulda/test-unit tests to fail badly

I had to comment out the following line in the plugin:

http://github.com/hpoydar/couchrest-rails/blob/master/init.rb#L2

The inclusion of the spec/rails/matchers caused my apps tests to fail badly in a very non-obvious way (required a session with git bisect to resolve the root cause).

I am not sure why is this seemingly test related code is being included in the normal runtime anyway? Shouldn't this only be included when running the plugin tests? There should be no assumptions about rspec being present or in use for apps that pull this plugin in.

Thanks.

Use CouchRest::Validation instead of Validatable

It is a bit strange that CouchRest-rails uses a different validation system than the original CouchRest. Is there any special reason for this?

hard coded dependency on 'couchrest' gem

The plugin has a hard coded dependency on the 'couchrest' gem in the plugin init:

http://github.com/hpoydar/couchrest-rails/blob/master/init.rb

This is problematic for those of us using one of the many seemingly official forks of couchrest in our app (e.g. jchris-couchrest, mattetti-couchrest, couchrest-couchrest, or just plain couchrest from rubyforge). According to mattettit 'couchrest-couchrest' is the official repo, but building gems from that repo on github seems to be borked.

Instead of hardcoding the specific gem I would instead specify that users need to specify one of these in their environment.rb with the :lib param of 'couchrest'. I am currently using (working ok so far in my very initial usage) the mattetti-couchrest gem in my app. In order to do this I needed to override your init.rb and specify:

config.gem 'mattetti-couchrest', :lib => 'couchrest'

instead of specifying config.gem statements in your plugin, I would try to require 'couchrest', (and the same for the other gems you hardcode) and raise an exception if one is missing. And add to the docs the requirement that the user has provided each of the approprtiate config gem statements in their environment.rb which will be much more flexible for users.

rake tasks require undocumented arguments

The rake tasks only seem to work when passed an argument for the database name to be used, instead of using the config from couchdb.yml.

The way to pass rake arguments are not documented in the couchrest-rails docs, and are tough to find on google (I wasted about an hour or more on figuring out the solution...)

If no args are passed, the rake task runs with no error output, and just generates two blank lines.

As an example if 'foobar' is the name of the database and a db suffix is setup in the couchdb config yml file to add the current env like 'foobar_development':

rake couchdb:create[foobar]
(in /Users/glenn/src/git/underscore-searchlight)

WARNING: there are no CouchRestRails::Document models using foobar
Created database foobar (foobar_development)

Note, also that the warning generated in this example is erroneous. There is a 'foobar' database specified in the model file (but of course, not foobar_development which is handled in the config). The model file was tested from the console with Model.create and it wrote to the expected foobar_development db.

Also note that tasks which don't accept arguments and instead run other tasks (like 'rake couchdb:reset' seem to always fail unless the individual tasks to destroy and create are run with args).

Is there something I am missing here from a config perspective? If not, would it be possible to make the rake tasks use sensible values from the config file? Or if not, can you please add docs to the readme showing which tasks need args, and what args they accept?

Thanks

autoinstall method not compatible with rails 3

/usr/local/rvm/gems/ruby-1.9.2-p0/gems/activesupport-3.0.3/lib/active_support/dependencies.rb:239:in `require': no such file to load -- rails_generator (LoadError)

there are no CouchRestRails::Document models using {Database}

Dears i got that Warning while creating the database.
while i have a model using CouchRestRails::Document

class Post < CouchRestRails::Document
use_database :couchtry

property :title
property :body

timestamps!

view_by :title

validates_presence_of :title
end

please advise,

Thanks.