# PgIpLock class · @imqueue/pg-pubsub

Source: https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock/
Published: 2026-08-01
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/pg-pubsub 3.0.5 — generated reference, not hand-written

Implements manageable inter-process locking mechanism over existing PostgreSQL connection for a given `LISTEN` channel.

It uses periodic locks acquire retries and implements graceful shutdown using `SIGINT`, `SIGTERM` and `SIGABRT` OS signals, by which safely releases an acquired lock, which causes an event to other similar running instances on another processes (or on another hosts) to capture free lock.

By running inside Docker containers this would work flawlessly on implementation auto-scaling services, as docker destroys containers gracefully.

Currently, the only known issue could happen only if, for example, database or software (or hardware) in the middle will cause a silent disconnect. For some period of time, despite the fact that there are other live potential listeners some messages can go into void. This time period can be tuned by bypassing wanted `acquireInterval` argument. By the way, take into account that too short period and number of running services may cause huge flood of lock acquire requests to a database, so selecting the proper number should be a thoughtful trade-off between overall system load and reliability level.

Usually you do not need to instantiate this class directly - it will be done by a PgPubSub instances on their needs. Therefore, you may re-use this piece of code in some other implementations, so it is exported as is.

**Signature:**

```typescript
export declare class PgIpLock implements AnyLock 
```
**Implements:** [AnyLock](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.anylock/)

## Constructors


| Constructor | Modifiers | Description |
| --- | --- | --- |
| [(constructor)(channel, options, uniqueKey)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock._constructor_/) |  | Constructs a new instance of the `PgIpLock` class |


## Properties


| Property | Modifiers | Type | Description |
| --- | --- | --- | --- |
| [channel](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.channel/) | `readonly` | string | Channel this lock guards. One lock row exists per channel, so this is what the competing processes contend over. |
| [options](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.options/) | `readonly` | PgIpLockOptions | Connection, schema and retry settings for this lock. |
| [schemaName](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.schemaname/) | `readonly` | string | DB lock schema name getter |
| [uniqueKey?](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.uniquekey/) | `readonly` | string \| undefined | _(Optional)_ Optional content key making the lock a de-duplication marker for one specific payload rather than a listener election for the channel. Supplied by the execution-lock path; see `EXECUTION_LOCK`. |


## Methods


| Method | Modifiers | Description |
| --- | --- | --- |
| [acquire()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.acquire/) |  | Acquires a lock on the current channel. Returns true on success, false - otherwise |
| [destroy()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.destroy/) |  | Destroys this lock properly. |
| [destroy()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.destroy_1/) | `static` | Calls destroy() on all created instances at a time |
| [dispose()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.dispose/) |  | Frees all local resources held by this lock (acquire timer, client notification listener, global registry entry) without touching the database. Used directly when the underlying connection is already dead (e.g. on reconnect) and as a part of destroy(). |
| [hasInstances()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.hasinstances/) | `static` | Returns true if at least one instance was created, false - otherwise |
| [init()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.init/) |  | Initializes inter-process locks storage in database and starts listening of lock release events, as well as initializes lock acquire retry timer. |
| [isAcquired()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.isacquired/) |  | Returns current lock state, true if acquired, false - otherwise. |
| [onAcquire(handler)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.onacquire/) |  | This would provide a late acquire handler which will be called once the lock is taken over by the retry timer, with the channel name bypassed to a given handler. Acquiring the lock is only ever half of the caller's job - the other half (issuing `LISTEN`, in the PgPubSub case) happens right after acquire() returns true. When the first attempt loses to another process, that caller is long gone by the time the timer wins the lock, so without this handler the second half never runs and the lock is held by a process that does nothing with it - forever, since a held lock keeps every other process away too. |
| [onRelease(handler)](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.onrelease/) |  | This would provide release handler which will be called once the lock is released and the channel name would be bypassed to a given handler |
| [release()](https://imqueue.org/api/pg-pubsub/latest/pg-pubsub.pgiplock.release/) |  | Releases acquired lock on this channel. After lock is released, another running process or host would be able to acquire the lock. |