openstack/tooz
Code Issues Proposed changes
tooz/doc/source/user/drivers.rst
Ben Nemec e76235b675 More explicitly document driver connection strings 
If you're not intimately familiar with RFC 1808 it can be a bit tricky to
write tooz connection strings. In addition, some drivers do not document the
options that they recognize in a connection string. This can force a user to
read the driver code in order to figure out how to configure tooz to use said
driver, which should not be the case.

This change more explicitly documents the format of the connection string,
including which parts of an RFC 1808 URI it recognizes, and the options that
can be passed. It also clarifies which parts of the connection string are
optional (possibly because they have defaults) and which must always be
included.

Note that not every possible configuration is documented. For example, the
postgres driver supports multiple methods of configuring the connection host
and port. For consistency, I only documented the one that matches the other
drivers. This should be sufficient to allow a user to write a working
connection string.

This change also wires the etcd3 and etcd3gw drivers into the doc index since
they were missing before.

Change-Id: I66e54433115f27fb54badc2173f8f6044c49aacb
2018-12-17 22:37:55 +00:00

7.1 KiB
Raw Blame History

Drivers

Tooz is provided with several drivers implementing the provided coordination API. While all drivers provides the same set of features with respect to the API, some of them have different characteristics:

Zookeeper

Driver: :pytooz.drivers.zookeeper.KazooDriver

Characteristics:

:pytooz.drivers.zookeeper.KazooDriver.CHARACTERISTICS

Entrypoint name: zookeeper or kazoo

Summary:

The zookeeper is the reference implementation and provides the most solid features as it's possible to build a cluster of zookeeper servers that is resilient towards network partitions for example.

Test driver: :pytooz.drivers.zake.ZakeDriver

Characteristics:

:pytooz.drivers.zake.ZakeDriver.CHARACTERISTICS

Test driver entrypoint name: zake

Considerations

  • Primitives are based on sessions (and typically require careful selection of session heartbeat periodicity and server side configuration of session expiry).

Memcached

Driver: :pytooz.drivers.memcached.MemcachedDriver

Characteristics:

:pytooz.drivers.memcached.MemcachedDriver.CHARACTERISTICS

Entrypoint name: memcached

Summary:

The memcached driver is a basic implementation and provides little resiliency, though it's much simpler to setup. A lot of the features provided in tooz are based on timeout (heartbeats, locks, etc) so are less resilient than other backends.

Considerations

  • Less resilient than other backends such as zookeeper and redis.
  • Primitives are often based on TTL(s) that may expire before being renewed.
  • Lacks certain primitives (compare and delete) so certain functionality is fragile and/or broken due to this.

Redis

Driver: :pytooz.drivers.redis.RedisDriver

Characteristics:

:pytooz.drivers.redis.RedisDriver.CHARACTERISTICS

Entrypoint name: redis

Summary:

The redis driver is a basic implementation and provides reasonable resiliency when used with redis-sentinel. A lot of the features provided in tooz are based on timeout (heartbeats, locks, etc) so are less resilient than other backends.

Considerations

  • Less resilient than other backends such as zookeeper.
  • Primitives are often based on TTL(s) that may expire before being renewed.

IPC

Driver: :pytooz.drivers.ipc.IPCDriver

Characteristics: :pytooz.drivers.ipc.IPCDriver.CHARACTERISTICS

Entrypoint name: ipc

Summary:

The IPC driver is based on Posix IPC API and implements a lock mechanism and some basic group primitives (with huge limitations).

Considerations

  • The lock can only be distributed locally to a computer processes.

File

Driver: :pytooz.drivers.file.FileDriver

Characteristics: :pytooz.drivers.file.FileDriver.CHARACTERISTICS

Entrypoint name: file

Summary:

The file driver is a simple driver based on files and directories. It implements a lock based on POSIX or Window file level locking mechanism and some basic group primitives (with huge limitations).

Considerations

  • The lock can only be distributed locally to a computer processes.
  • Certain concepts provided by it are not crash tolerant.

PostgreSQL

Driver: :pytooz.drivers.pgsql.PostgresDriver

Characteristics:

:pytooz.drivers.pgsql.PostgresDriver.CHARACTERISTICS

Entrypoint name: postgresql

Summary:

The postgresql driver is a driver providing only a distributed lock (for now) and is based on the PostgreSQL database server and its API(s) that provide for advisory locks to be created and used by applications. When a lock is acquired it will release either when explicitly released or automatically when the database session ends (for example if the program using the lock crashes).

Considerations

  • Lock that may be acquired restricted by max_locks_per_transaction * (max_connections + max_prepared_transactions) upper bound (PostgreSQL server configuration settings).

MySQL

Driver: :pytooz.drivers.mysql.MySQLDriver

Characteristics: :pytooz.drivers.mysql.MySQLDriver.CHARACTERISTICS

Entrypoint name: mysql

Summary:

The MySQL driver is a driver providing only distributed locks (for now) and is based on the MySQL database server supported get_lock primitives. When a lock is acquired it will release either when explicitly released or automatically when the database session ends (for example if the program using the lock crashes).

Considerations

  • Does not work correctly on some MySQL versions.
  • Does not work when MySQL replicates from one server to another (locks are local to the server that they were created from).

Etcd

Driver: :pytooz.drivers.etcd.EtcdDriver

Characteristics: :pytooz.drivers.etcd.EtcdDriver.CHARACTERISTICS

Entrypoint name: etcd

Summary:

The etcd driver is a driver providing only distributed locks (for now) and is based on the etcd server supported key/value storage and associated primitives.

Etcd3

Driver: :pytooz.drivers.etcd3.Etcd3Driver

Characteristics: :pytooz.drivers.etcd3.Etcd3Driver.CHARACTERISTICS

Entrypoint name: etcd3

Summary:

The etcd3 driver is a driver providing only distributed locks (for now) and is based on the etcd server supported key/value storage and associated primitives.

Etcd3 Gateway

Driver: :pytooz.drivers.etcd3gw.Etcd3Driver

Characteristics: :pytooz.drivers.etcd3gw.Etcd3Driver.CHARACTERISTICS

Entrypoint name: etcd3+http

Summary:

The etcd3gw driver is a driver providing only distributed locks (for now) and is based on the etcd server supported key/value storage and associated primitives. It relies on the GRPC Gateway to provide HTTP access to etcd3.

Consul

Driver: :pytooz.drivers.consul.ConsulDriver

Characteristics:

:pytooz.drivers.consul.ConsulDriver.CHARACTERISTICS

Entrypoint name: consul

Summary:

The consul driver is a driver providing only distributed locks (for now) and is based on the consul server key/value storage and/or primitives. When a lock is acquired it will release either when explicitly released or automatically when the consul session ends (for example if the program using the lock crashes).

Characteristics

tooz.coordination.Characteristics