Class: MysqlMutexDriver

The MySQL driver ({type: 'mysql'}, MySQL or MariaDB): the locks are shared by every instance connected to the same server with the same prefix. It needs the optional peer dependency mysql2 (3); without it, the first acquisition fails with MutexDriverNotFoundException. It has two modes:

• 'advisory' (the default): named locks (GET_LOCK) taken on one connection of the driver, opened at the first use. They do not expire and need no renewal: MySQL releases them when the connection closes, so a crashed process frees them at once. When the connection closes or fails, every lock it held is lost (a Mutex aborts their signals) and the next acquisition opens a new connection. A connection cut without the client noticing it is not detected by the renewals. No fencing token. The named locks are not replicated by the clusters (Galera, Group Replication): every holder must connect to the same server.
• 'table': one row per lock in a table, created at the first use with its counter table <table>_fence. The rows expire by the database clock after their ttl unless renewed, so it works through the poolers and the clusters, and each acquisition gets a fencing token from the counter. A pool of 4 connections is used.

Example

import {MysqlMutexDriver, type DriverLock} from 'lakutata/com/mutex'

const driver: MysqlMutexDriver = new MysqlMutexDriver({
    host: '127.0.0.1',
    database: 'app',
    username: 'app',
    password: 'secret'
}, 'my-app:')
const lock: DriverLock | undefined = await driver.acquire('invoice:7', 30000)
if (lock) await driver.release('invoice:7', lock)
//Closing the connection releases its named locks
await driver.close()

Extends

• MutexDriver

Constructors

Constructor

new MysqlMutexDriver(connection, prefix, mode?, table?): MysqlMutexDriver

Create a driver on a MySQL server; it connects at its first use.

Parameters

connection

MysqlMutexConnection

The connection to the server.

prefix

string

The prefix added to the lock names.

mode?

"advisory" | "table"

'advisory' (the default) or 'table'.

table?

string

The table of the table mode, in the connection's database; 'lakutata_mutex' by default.

Returns

MysqlMutexDriver

Throws

When the table is not a valid name (letters, digits and _, not starting with a digit, without a database qualifier).

Overrides

MutexDriver.constructor

Properties

expiring

readonly expiring: boolean

true in the table mode (the rows expire), false in the advisory mode (the locks end with the connection).

Overrides

MutexDriver.expiring

---

onLost

onLost: (names) => void

Called with the names of the locks the driver lost at once, when the connection holding advisory locks closes or fails. A Mutex sets it; it does nothing by default.

Parameters

names

string[]

Returns

void

Inherited from

MutexDriver.onLost

Methods

acquire()

acquire(name, ttl): Promise<DriverLock | undefined>

Try to acquire a lock once: a named lock of the driver's connection, or a row inserted (or taken over when expired) in the table.

Parameters

name

string

The lock name.

ttl

number

How long the lock stays held without a renewal, in milliseconds (the table mode only).

Returns

Promise<DriverLock | undefined>

The lock (with a fencing token in the table mode), or undefined when another holder has it, this driver included.

Throws

When the package mysql2 is not installed.

Overrides

MutexDriver.acquire

---

close()

close(): Promise<void>

Close the connection (MySQL releases its named locks) and the pool; the rows of the table mode stay until they expire.

Returns

Promise<void>

Overrides

MutexDriver.close

---

extend()

extend(name, lock, ttl): Promise<boolean>

Renew a lock: in the table mode, push back the expiration of its row when it still holds this holder's token; in the advisory mode, check that the driver still holds it on its connection, by a query (a connection cut without notice fails it).

Parameters

name

string

The lock name.

lock

DriverLock

The lock acquired.

ttl

number

How long the lock stays held without another renewal, in milliseconds (the table mode only).

Returns

Promise<boolean>

Whether the lock is still held by this holder.

Overrides

MutexDriver.extend

---

release()

release(name, lock): Promise<boolean>

Release a lock still held by this holder: RELEASE_LOCK, or delete the row.

Parameters

name

string

The lock name.

lock

DriverLock

The lock acquired.

Returns

Promise<boolean>

Whether it was released (false when the row expired and was taken, or the connection was lost).

Overrides

MutexDriver.release