Configuration

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
  index:
    migrations_path: db/indexes
    schema_path: db/index_schema.rb
    num_replica: 0

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'] %>
  index:
    bucket: <%= ENV['COUCHBASE_INDEX_BUCKET'] %>
    schema_path: <%= ENV['COUCHBASE_INDEX_SCHEMA_PATH'] %>
    num_replica: 1

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.

Index migration settings for Rails applications may also be configured in the nested index section. Supported keys are bucket, migrations_path schema_path, and num_replica.

When index.bucket is omitted, CouchbaseOrm uses the top-level connection bucket as the default index bucket.

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. 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 loaded from couchbase.yml during Rails initialization take precedence over values set earlier in an initializer. Later explicit CouchbaseOrm.configure calls still override those loaded values at runtime.

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.

For index migrations, Rails loads the same config/couchbase.yml entry and applies nested index values after connection settings are loaded.

The index.schema_path value controls where schema snapshot commands read and write index state:

  • bundle exec couchbaseorm index:schema:dump writes the schema file.

  • bundle exec couchbaseorm index:schema:load loads indexes from the schema file.

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.

Contents