syncguard/postgres/backend.d.ts

Functional TypeScript library for distributed locking across microservices. Prevents race conditions with Redis, PostgreSQL, Firestore, and custom backends. Features automatic lock management, timeout handling, and extensible architecture.

import type { Sql } from "postgres";
import type { LockBackend } from "../common/backend.js";
import type { PostgresBackendOptions, PostgresCapabilities } from "./types.js";
/**
 * Creates PostgreSQL-based distributed lock backend using transactions.
 *
 * Storage: Two tables:
 * - {tableName}: Lock data (key PRIMARY KEY, lock_id indexed)
 * - {fenceTableName}: Fence counters (fence_key PRIMARY KEY, never deleted)
 *
 * Uses postgres.js library (porsager/postgres) for optimal performance.
 *
 * IMPORTANT: Call setupSchema() once before creating backends to set up schema.
 *
 * @param sql - postgres.js SQL instance
 * @param options - Backend configuration (tables, cleanup options)
 * @returns LockBackend with server-side time authority
 * @see docs/specs/postgres-backend.md
 *
 * @example
 * ```typescript
 * import postgres from 'postgres';
 * import { createPostgresBackend, setupSchema } from 'syncguard/postgres';
 *
 * const sql = postgres('postgresql://localhost:5432/myapp');
 *
 * // Setup schema (once, during initialization)
 * await setupSchema(sql);
 *
 * // Create backend (synchronous)
 * const backend = createPostgresBackend(sql);
 *
 * const result = await backend.acquire({ key: 'resource:123', ttlMs: 30_000 });
 * ```
 */
export declare function createPostgresBackend(sql: Sql, options?: PostgresBackendOptions): LockBackend<PostgresCapabilities>;