Config File

Config File

To enable shard, you need to create a file named shards.yml in your config directory inside your rails application. If you want to use octopus in a plain ruby application, create a folder named config, and put the file inside them. The shards.yml file should looks like this:

octopus:
  environments:
    - development
    - production
  development:
    shard_one:
      host: localhost
      adapter: mysql
      database: app_development
  production:
    shard_one:
      host: localhost
      adapter: mysql
      database: app_production

In this example, you have one shard for each enviroment, named shard_one. This is a example of a config file using rails, when you have a shard for development, and another for production. You also need to specify what environments octopus will runs, with the octopus_environments tag. All configs should start with the ‘octopus’ tag. The difference stays when you have a application that isn’t running rails, so octopus will assume that you don’t have shards for environments, like this example:

octopus:
  shards:
    alone_shard:
      adapter: mysql
      host: localhost
      database: octopus_shard5

    postgresql_shard:
      adapter: postgresql
      username: postgres
      password:
      database: octopus_shard1
      encoding: unicode

Octopus also works with groups of shards. with groups, you could send queries to all members of a group. This is how the config file should looks:

  octopus:
    shards:
      history_shards:
        aug2009:
          adapter: mysql
          host: localhost
          database: octopus_shard2
        aug2010:
          adapter: mysql
          host: localhost
          database: octopus_shard3
        aug2011:
          adapter: mysql
          host: localhost
          database: octopus_shard4

      country_shards:
        canada:
          adapter: mysql
          host: localhost
          database: octopus_shard5
        brazil:
          adapter: mysql
          host: localhost
          database: octopus_shard6
        russia:
          adapter: mysql
          host: localhost
          database: octopus_shard7

If you want replication, you need to add some lines, like this:

octopus:
  replicated: true
  production:
    slave1:
      adapter: mysql
      host: localhost
      database: octopus_shard2
    slave2:
      adapter: mysql
      host: localhost
      database: octopus_shard3
    slave3:
      adapter: mysql
      host: localhost
      database: octopus_shard4
    slave4:
      adapter: mysql
      host: localhost
      database: octopus_shard5

If Octopus finds the directive replicated: true, it will assume all shards as slaves, and the database specified in database.yml as master database. In a normal setup, octopus will just use replication for models that are marked as ‘replicated_model’. So, if you want to send all writes queries will be sent to master, and all reads queries to slaves, you need to enable with the following line:

  fully_replicated: true 

if you have some shards specified inside a group, octopus will see them as normal slaves.

Octopus also supports different shards that runs on different databases, like if you have a PostgreSQL Shard, and the master database is MySQL, no problem, Octopus will handle this for you ;-), just specify in the config file and all will work:

octopus:
  development:
    postgres_shard:
      adapter: postgresql
      username: postgres
      password:
      database: octopus_shard1
      encoding: unicode

If you have duplicated shards names or groups names, Octopus will raise a exception, helping the programmer to fix the problem.