Expanding on the README...
(Work in progress, read at own risk as some info may be wrong)
This is the initial database Rails uses. If there's a core database in the system, specify this one.
In config/database.yml (not shards.yml). Simple version:
octopus:
master_shard: development
Let's make that work across all environments (assuming you have "development" "test" etc as your DB keys in database.yml, which is the Rails defauilt):
octopus:
master_shard: <%= Rails.env %>
Let's offer the command-line a way to override the environment. This is useful for migrations, where, for the temporary process running the migration, we want it to use the database under migration as the default database.
octopus:
master_shard: <%= ENV['SHARD'] || Rails.env %>
Now we can run a migration using ENV=user_shard1 rake db:migrate