@tslock/spanner

TSLock provider backed by Google Cloud Spanner.

A TSLock provider that uses the StorageBasedLockProvider pattern with a StorageAccessor that runs inside Spanner readWriteTransactions and uses mutations for inserts/updates.

Installation

pnpm add @tslock/core @tslock/spanner @google-cloud/spanner

Setup

Create the lock table once:

-- Column names match the defaults passed to createSpannerProvider below.
CREATE TABLE shedlock (
  name       STRING(64)  NOT NULL,
  lockUntil  TIMESTAMP    NOT NULL,
  lockedAt   TIMESTAMP    NOT NULL,
  lockedBy   STRING(255) NOT NULL,
) PRIMARY KEY (name);

Usage

import { createLockConfig, DefaultLockingTaskExecutor } from '@tslock/core';
import { createSpannerProvider } from '@tslock/spanner';
import { Spanner } from '@google-cloud/spanner';

const spanner = new Spanner({ projectId: process.env.GCP_PROJECT_ID });
const instance = spanner.instance('my-instance');
const database = instance.database('my-database');

const provider = createSpannerProvider(database, 'shedlock', {
  name: 'name',
  lockUntil: 'lockUntil',
  lockedAt: 'lockedAt',
  lockedBy: 'lockedBy',
}, 'my-hostname');

const executor = new DefaultLockingTaskExecutor(provider);

await executor.executeWithLock(
  () => myScheduledTask(),
  createLockConfig({ name: 'my-task', lockAtMostFor: '5m' }),
);

Configuration

createSpannerProvider(database, tableName, columnNames, lockedByValue) takes:

| Argument | Default / notes | |---|---| | database | A Spanner Database instance (required). | | tableName | e.g. 'shedlock'. | | columnNames | { name, lockUntil, lockedAt, lockedBy } (all required). | | lockedByValue | Identifier written to lockedBy. |

Use resolveSpannerConfiguration() if you prefer defaults + Partial<SpannerColumnNames> overrides.

Integration limitation: The Spanner emulator does not provide a reliable substitute for the transaction behavior required by this provider. Spanner coverage therefore relies on mocked-driver unit tests and the optional live test, which requires TSLOCK_SPANNER_INSTANCE, TSLOCK_SPANNER_DATABASE, and TSLOCK_SPANNER_PROJECT_ID.

Requirements

• Node.js >= 22
• Peer: @google-cloud/spanner

License

Apache 2.0 — see LICENSE for details.