# sql-lock

> distributed lock manager based on mysql

Latest version **0.1.3** (published 2020-02-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install sql-lock
pnpm add sql-lock
yarn add sql-lock
bun add sql-lock
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.3 |
| Published | 2020-02-17 |
| First published | 2020-02-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 21.3 KB |
| Known vulnerabilities | 0 (+12 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 3 |
| Maintainers | ronakjain_uc |

## Links

- npm: https://www.npmjs.com/package/sql-lock
- Repository: https://github.com/urbanclap-engg/sql-lock
- Homepage: https://github.com/urbanclap-engg/sql-lock#readme
- Issues: https://github.com/urbanclap-engg/sql-lock/issues
- npm.io page: https://npm.io/package/sql-lock

## Dependencies (6)

- [lodash](https://npm.io/package/lodash.md) ^4.17.15
- [mysql2](https://npm.io/package/mysql2.md) ^2.1.0
- [sequelize](https://npm.io/package/sequelize.md) 5.21.3
- [@types/node](https://npm.io/package/@types/node.md) 13.7.0
- [@types/bluebird](https://npm.io/package/@types/bluebird.md) 3.5.29
- [@types/validator](https://npm.io/package/@types/validator.md) 12.0.1

## Recent versions

- 0.1.3 (latest) — 2020-02-17
- 0.1.2 — 2020-02-07
- 0.1.1 — 2020-02-07
- 0.1.0 — 2020-02-07
- 0.0.9 — 2020-02-07
- 0.0.8 — 2020-02-07
- 0.0.7 — 2020-02-07
- 0.0.6 — 2020-02-07
- 0.0.5 — 2020-02-07
- 0.0.4 — 2020-02-07
- 0.0.3 — 2020-02-07
- 0.0.2 — 2020-02-07

## README

[![Build Status](https://travis-ci.org/ronak-007/sql-lock.svg?branch=master)](https://travis-ci.org/ronak-007/sql-lock)
[![npm version](https://badge.fury.io/js/sql-lock.svg)](https://badge.fury.io/js/sql-lock)

# sql-lock

```sql-lock``` is a distributed lock manager for NodeJS, which works with the help of a MySQL Server. 

## Motivation
There are a lot of use cases that require an exclusive access to a resource. In a distributed system, with several containers running the same piece of code in parallel, achieving this can get quite difficult.

```sql-lock``` solves this problem, by allowing you to get distributed locks in your code from a MySQL server. 


## How does it work

![Simple Locking Mechanism](https://miro.medium.com/max/2120/1*2rSPNJ1q8OvppQGgadUnrA.png)
- On initialization it creates a table `lockings` containing a column `id`.
- Whenever someone tries to get a lock, a transaction is started in MySQL and an entry is created with `id` equal to lock key.
- This gives a row lock to the transaction, which prevents someone from trying to get the same lock again.
- To release the lock, the transaction is committed and the row deleted. Anyone else trying to get a lock with same lock key can then proceed.
- More information can be found in our blog posts -
    - https://medium.com/uc-engineering/pessimistic-locking-for-a-distributed-system-part-1-cc85c755c357
    - https://medium.com/uc-engineering/pessimistic-locking-for-a-distributed-system-part-2-f2d224567284

## Requirements

- MySQL Server
- NodeJS > 6

## Installation

```npm install sql-lock```

## Usage
### Initialization
```Javascript
const sqlLock = require('sql-lock');
sqlLock.initialize(MysqlURI, { locking_ttl: 30000 });
```
 - MysqlURI - MySQL connection string - Eg `mysql://travis@127.0.0.1:3306/test`.
 - Options:
    -  locking_ttl - Default timeout for your locks (in ms)

This will automatically create a table named `locking` in the database.
 
### Code
```Javascript
const sqlLock = require('sql-lock');
const lockReleaser = await sqlLock.getLock('lock_key', 3000);
await someAsyncWork();
lockReleaser(); //Release lock
```
This code gets a lock on the key `lock_key` which is released when either `lockReleaser` function is called or the lock times out.

If someone else tries to get a lock with the same key, they will have to wait till the first lock is released.

`getLock` accepts two parameters -
- lockKey: string - mandatory
- TTL: number - timeout in ms for the lock. If not given, the TTL given during initialization is considered as the timeout.

## Contributions
Contributions are welcome. Please create a pull-request if you want to add new features, test-support or enhance the existing code.

## License
[MIT](https://github.com/urbanclap-engg/sql-lock/blob/master/LICENSE)

---
_Source: https://npm.io/package/sql-lock · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._