Configuration

CouchbaseOrm is customarily configured through a couchbase.yml file that specifies options and clients. The simplest configuration is as follows, which configures CouchbaseOrm to talk to a Couchbase server and use the database named “dev_bucket”.

common: &common
  connection_string: couchbase://localhost
  username: dev_user
  password: dev_password

development:
  <<: *common
  bucket: dev_bucket

test:
  <<: *common
  bucket: dev_bucket_test

# set these environment variables on your production server
production:
  connection_string: <%= ENV['COUCHBASE_CONNECTION_STRING'] %>
  bucket: <%= ENV['COUCHBASE_BUCKET'] %>
  username: <%= ENV['COUCHBASE_USER'] %>
  password: <%= ENV['COUCHBASE_PASSWORD'] %>

The top level key in the configuration file, development in the above example, refers to the environment name which the application is executing in, i.e. development, test or production.

Generating Default Configuration

If you are using Ruby on Rails, you can have CouchbaseOrm generate a default configuration file for you by running the following command:

rails g couchbase_orm:config

The configuration file will be placed in config/couchbase.yml. An It is recommended that all configuration be specified in config/couchbase.yml, but if you prefer, the couchbase_orm.rb initializer may also be used to set configuration options. Note, though, that settings in couchbase.yml always take precedence over settings in the initializer.

If you are not using Rails, you can configure couchbase-orm with an initializer:

# config/initializers/couchbase_orm.rb
CouchbaseOrm::Connection.config = {
  connection_string: "couchbase://localhost"
  username: "dev_user"
  password: "dev_password"
  bucket: "dev_bucket"
}

Loading CouchbaseOrm Configuration

If you are using Ruby on Rails, CouchbaseOrm configuration is automatically loaded for the current environment as stored in Rails.env when the application loads.

ERb Preprocessing

When loading a configuration file, CouchabseOrm processes it with ERb before parsing it as YAML. This allows, for example, constructing the contents of the configuration file at runtime based on environment variables:

production:
  connection_string: <%= ENV['COUCHBASE_CONNECTION_STRING'] %>
  bucket: <%= ENV['COUCHBASE_BUCKET'] %>
  username: <%= ENV['COUCHBASE_USER'] %>
  password: <%= ENV['COUCHBASE_PASSWORD'] %>

Note

When outputting values from ERb, ensure the values are valid YAML and escape them as needed.

Note

Since ERb rendering is performed prior to YAML parsing, all ERb directives in the configuration file are evaluated, including those occurring in YAML comments.