Basic operations

Manipulating keys

Keys can be created with or without a value. they can also be assigned a ttl (aka time to live), after which key will be automatically deleted or expired. following will create a key name pink_floyd and assign sheep as its value.

client.create('/pink_floyd', value: 'sheep')

to create a key with ttl

client.create('/deltron_3030', value: 'automator', ttl: 3)

this will create a key named deltron_3030 and assign the value automator to it. the last argument specifies ttl. here the key will be automatically deleted or expired after 3 seconds. Obtaining a key's value following will retrieve the value of pink_floyd key.

client.get('/pink_floyd').value

Updating a key following will update the value of pink_floyd key from sheep to pigs on the wing

client.update('/pink_floyd','pigs on the wing')

Deleting a key

client.delete('/pink_floyd')

Checking if a key exist?

client.create('/existing_key', value: 'Tangible')
p client.exists?('/existing_key') # will return true
p client.exists?('/non_existing_key') # will return false

Manipulating directories

In etcd keys can be nested. and in such cases parent keys are treated as directories. directories can not have values, they can only contain other keys. empty directories can be created by passing the directory flag. We'll be using the term node to represent an etcd key, which can be either a leaf key (can store value) or directory (can contain other keys, but can not store any value). Following will create an empty directory named dir1

client.create('/dir1', dir: true)

Directories can also be auto created, if a nested key is created. Following api call will automatically create dir2 and dir3.

client.create('/dir2/dir3/foo', value: 10)

Directories can be retrieved in similar fashion as keys. directory? method call against them will return true. Children of a directory can be obtained via children method.

d = client.get('/dir2')
p d.directory?
p d.children

Directories can be deleted similar ways as keys, except we have to pass the dir flag. If the directory contain any key or other directories, then we have to pass the recursive flag as well (think of rmdir and rm -rf).

client.delete('/dir1', dir: true)
client.delete('/dir2', dir: true, recursive: true) # non-empty directory deletionrequires the recursive flag

Like keys, directories too can have ttl. Following will create a directory which will be automatically deleted after 30 seconds.

client.create('/ephemeral_directory', dir: true, ttl: 3)

Watching events

etcd allows client to watch for actions against keys or directories. If the key or directory under watch changes (i.e. deleted or updated) all watchers will receive a notification event. In following example we'll create a key with 3 seconds ttl and then watch for changes. The watch method is blocking, it will wait till it receives an event or times out (by default 60 seconds).

client.create('/credence_clearwater_revival', 3)
p client.watch('/credence_clearwater_revival')

the default timeout can be overridden by passing the timeout parameter.