mysql-semaphore

library0.1.1jsnpmunverified

A semaphore handler for Node.js using MySQL as the coordination backend. Current stable version 0.1.1. No recent releases. Provides lock, unlock, and islocked methods via Promises for clustered Node.js environments where you need to ensure only one instance runs a task (e.g., cron jobs). Key differentiators: simple MySQL-based semaphore with no external dependencies beyond mysql package. Known issues: lock name uniqueness is critical to avoid accidental unlocking across applications; no automatic lock cleanup.

database devops

npm install mysql-semaphore

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MYSQL-SEMAPHORE

mysql-semaphore

databasejavascriptv0.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import Semaphore from 'mysql-semaphore'

✗ const { Semaphore } = require('mysql-semaphore')

CommonJS require returns the constructor directly. ESM imports work as default export.

Semaphore

✓ const Semaphore = require('mysql-semaphore')

✗ const Semaphore = require('mysql-semaphore').Semaphore

CJS: the constructor is the module.exports, not a named export.

Semaphore

✓ new Semaphore({ host, user, password, database })

✗ new Semaphore(connection)

Constructor expects MySQL connection options object, not a mysql connection instance.

Shows how to initialize the semaphore, acquire a lock with a 5-second timeout, perform work, and release the lock.

import Semaphore from 'mysql-semaphore'; const semaphore = new Semaphore({ host: 'localhost', user: 'root', password: process.env.MYSQL_PASSWORD ?? '', database: 'test' }); async function run() { const locked = await semaphore.lock('myapp_myjob', 5); if (locked) { console.log('Lock acquired, doing work...'); await new Promise(resolve => setTimeout(resolve, 1000)); await semaphore.unlock('myapp_myjob'); console.log('Work done, lock released.'); } else { console.log('Could not acquire lock, another instance is running.'); } } run().catch(console.error);

Debug

Known issues

gotchaLock name must be globally unique across all applications using the same MySQL database. If another application uses the same lock name, it can unlock your lock.

fix

Use a naming convention that includes application name, database, and purpose, e.g., 'myapp_mydb_myprocess'.

affects: >=0.0.0

gotchaNo automatic lock cleanup on process crash. If a process holding a lock crashes, the lock remains in the database indefinitely.

fix

Implement a heartbeat or TTL mechanism externally, or set up a cleanup cron job.

affects: >=0.0.0

gotchaThe library does not use MySQL GET_LOCK() but creates its own table 'semaphore' for locks. This may have different performance characteristics and potential for deadlocks.

fix

Review the custom locking mechanism in source code; consider using MySQL's built-in GET_LOCK() as an alternative.

affects: >=0.0.0

Errors

Common errors & fixes

Error: ER_NO_SUCH_TABLE: Table 'test.semaphore' doesn't exist

The library expects a 'semaphore' table to exist in the database; it does not auto-create it (despite some documentation implying otherwise).

fix

Create the table manually: CREATE TABLE IF NOT EXISTS semaphore (lockName VARCHAR(255) PRIMARY KEY, lockTime DATETIME);

TypeError: Semaphore is not a constructor

Using ES6 import with named import instead of default import in ESM environment.

fix

Use import Semaphore from 'mysql-semaphore' (default import).

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

mysqlrequiredNode.js MySQL driver for database connectivity

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/n8j1s/node-mysql-semaphore ↗

packagemysql-semaphore ↗

homepagehttps://github.com/n8j1s/node-mysql-semaphore#readme ↗