# 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: `tooz.drivers.zookeeper.KazooDriver`

Characteristics:

`tooz.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: `tooz.drivers.zake.ZakeDriver`

Characteristics:

`tooz.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: `tooz.drivers.memcached.MemcachedDriver`

Characteristics:

`tooz.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: `tooz.drivers.redis.RedisDriver`

Characteristics:

`tooz.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: `tooz.drivers.ipc.IPCDriver`

Characteristics: `tooz.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: `tooz.drivers.file.FileDriver`

Characteristics: `tooz.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: `tooz.drivers.pgsql.PostgresDriver`

Characteristics:

`tooz.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: `tooz.drivers.mysql.MySQLDriver`

Characteristics: `tooz.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: `tooz.drivers.etcd.EtcdDriver`

Characteristics: `tooz.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 Gateway

Driver: `tooz.drivers.etcd3gw.Etcd3Driver`

Characteristics: `tooz.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: `tooz.drivers.consul.ConsulDriver`

Characteristics:

`tooz.drivers.consul.ConsulDriver.CHARACTERISTICS`

Entrypoint name: `consul`

Summary:

The consul driver is a driver providing distributed locking and group membership 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

class tooz.coordination.Characteristics(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Attempts to describe the characteristic that a driver supports.

  CAUSAL = 'CAUSAL'

    The driver has the following properties:

    - Does not have to enforce the order of every operation from a process, perhaps, only causally related operations must occur in order.

  DISTRIBUTED_ACROSS_HOSTS = 'DISTRIBUTED_ACROSS_HOSTS'

    Coordinator components when used by multiple hosts work the same as if those components were only used by a single thread.

  DISTRIBUTED_ACROSS_PROCESSES = 'DISTRIBUTED_ACROSS_PROCESSES'

    Coordinator components when used by multiple processes work the same as if those components were only used by a single thread.

  DISTRIBUTED_ACROSS_THREADS = 'DISTRIBUTED_ACROSS_THREADS'

    Coordinator components when used by multiple threads work the same as if those components were only used by a single thread.

  LINEARIZABLE = 'LINEARIZABLE'

    The driver has the following properties:

    - Ensures each operation must take place before its completion time.

    - Any operation invoked subsequently must take place after the invocation and by extension, after the original operation itself.

  NON_TIMEOUT_BASED = 'NON_TIMEOUT_BASED'

    The driver has the following property:

    - Its operations are not based on the timeout of other clients, but on some other more robust mechanisms.

  SAME_VIEW_ACROSS_CLIENTS = 'SAME_VIEW_ACROSS_CLIENTS'

    A client connected to one server will always have the same view every other client will have (no matter what server those other clients are connected to). Typically this is a sacrifice in write availability because before a write can be acknowledged it must be acknowledged by all servers in a cluster (so that all clients that are connected to those servers read the exact same thing).

  SAME_VIEW_UNDER_PARTITIONS = 'SAME_VIEW_UNDER_PARTITIONS'

    When a client is connected to a server and that server is partitioned from a group of other servers it will (somehow) have the same view of data as a client connected to a server on the other side of the partition (typically this is accomplished by write availability being lost and therefore nothing can change).

  SEQUENTIAL = 'SEQUENTIAL'

    The driver has the following properties:

    - Operations can take effect before or after completion - but all operations retain the constraint that operations from any given process must take place in that processes order.

  SERIALIZABLE = 'SERIALIZABLE'

    The driver has the following properties:

    - The history of all operations is equivalent to one that took place in some single atomic order but with unknown invocation and completion times - it places no bounds on time or order.

this page last updated: 2025-02-03 10:42:00

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug