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 environment, 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 ‘environments’ tag. All configs should start with the ‘octopus’ tag. The difference stays when you have an 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 look like:

  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. By default, octopus will assume `fully_replicated` to be `true`. So, if you don’t want to send all write queries to master, and all reads queries to slaves, you need to disable with the following line:

  fully_replicated: false 

See more at replication.

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.