API

shardmonster.activate_caching(timeout)

Activates caching of metadata.

Parameters:timeout (int) – Number of seconds to cache metadata for.

Caching is generally a good thing. However, during a migration there will be a pause equal to whatever the caching timeout. This is to avoid stale reads and writes when the source of truth for a shard changes location.

shardmonster.connect_to_controller(uri, db_name)

Connects to the controlling database. This contains information about the realms, shards and clusters.

Parameters:
  • uri (str) – The Mongo URI to connect to. This should typically detail several replica members to ensure connectivity.
  • db_name (str) – The name of the database to connect to on the given replica set.
shardmonster.do_migration(collection_name, shard_key, new_location)

Migrates the data with the given shard key in the given collection to the new location. E.g.

>>> do_migration('some_collection', 1, 'cluster-1/some_db')

Would migrate everything from some_collection where the shard field is set to 1 to the database some_db on cluster-1.

Parameters:
  • collection_name (str) – The name of the collection to migrate
  • shard_key – The key of the shard that is to be moved
  • new_location (str) – Location that the shard should be moved to in the format “cluster/database”.

This method blocks until the migration is completed.

shardmonster.ensure_cluster_exists(name, uri)

Ensures that a cluster with the given name exists. If it doesn’t exist, a new cluster definition will be created using name and uri. If it does exist then no changes will be made.

Parameters:
  • name (str) – The name of the cluster
  • uri (str) – The URI to use for the cluster
shardmonster.ensure_realm_exists(name, shard_field, collection_name, default_dest)

Ensures that a realm of the given name exists and matches the expected settings.

Parameters:
  • name (str) – The name of the realm
  • shard_field – The field in documents that should be used as the shard field. The only supported values that can go in this field are strings and integers.
  • collection_name (str) – The name of the collection that this realm corresponds to. In general, the collection name should match the realm name.
  • default_dest (str) – The default destination for any data that isn’t explicitly sharded to a specific location.
Returns:

None
shardmonster.make_collection_shard_aware(collection_name)

Returns a new object that proxies the given collection and makes it shard aware.

shardmonster.set_shard_at_rest(realm, shard_key, location, force=False)

Marks a shard as being at rest in the given location. This is used for initiating shards in preparation for migration. Unless force is True this will raise an exception if a shard is already at rest in a specific location.

Parameters:
  • realm (str) – The name of the realm for the shard
  • shard_key – The key of the shard
  • location (str) – The location that the data is at (or should be in the case of a brand new shard)
  • force (bool) – Force a shard to be placed at rest in a specific location even if it has already been placed somewhere.
Returns:

None
shardmonster.where_is(collection_name, shard_key)

Returns a string of the form cluster/database that says where a particular shard of data resides.

Parameters:
  • collection_name – The collection name for the shard
  • shard_key – The shard key to look for
shardmonster.wipe_metadata()

Wipes all metadata. Should only be used during testing. There is no undo.

Wipes caches as well.