Pglock Integration

What it does

When your agent uses it

• Modifying a Go application that uses cirello.io/pglock for PostgreSQL-backed distributed locks
• Per-resource mutual exclusion
• Leader election
• Lock-aware workflows

Example prompts

• “/pglock-integration”

Requirements

• Python 3
• Compatibility (from SKILL.md): Requires a Go module compatible with the selected pglock version and PostgreSQL 15 or newer. The current package declares Go 1.25.0. Integration tests need a reachable PostgreSQL primary and permission to create or migrate the lock table and sequence.

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

1. 1Add cirello.io/pglock to the application's Go module at the version the
2. 2Choose the driver constructor deliberately. pglock.New validates the
3. 3Provision the lock table and its _rvn sequence once. Prefer a
4. 4Configure a single shared table and a stable owner identity for all
5. 5Select lease and heartbeat values from the workload. A positive heartbeat
6. 6Use AcquireContext or Do with an application context, and always release
7. 7Test contention and lease behavior against PostgreSQL. SQLite or an in-memory

What it can do on your machine

Read from SKILL.md and the folder at commit 6d39959. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/ (Python), which the agent can run.

  Shell commands in SKILL.md call:

  • python3

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Requires a Go module compatible with the selected pglock version and PostgreSQL 15 or newer. The current package declares Go 1.25.0. Integration tests need a reachable PostgreSQL primary and permission to create or migrate the lock table and sequence.

  From compatibility in the SKILL.md frontmatter.

Context cost

Pglock Integration loads about 2.2k tokens when it runs, and up to ~3.4k if it reads all its reference files. Until then it costs about 125 tokens; SKILL.md has 962 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~125

When it runs · the whole SKILL.md, loaded when a task matches

~2.2k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~3.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from cirello-io/pglock at commit 6d39959, republished under its Apache-2.0 licence (© cirello-io). 962 words, ~2,244 tokens.

name

pglock-integration

description

Use when building or modifying a Go application that uses cirello.io/pglock for PostgreSQL-backed distributed locks, per-resource mutual exclusion, leader election, leases, heartbeats, lock metadata, or lock-aware workflows. Guide dependency and driver selection, schema provisioning, client configuration, acquisition and release, context cancellation, error handling, and integration tests. Do not use for changing pglock's own internals or for generic PostgreSQL administration.

compatibility

Requires a Go module compatible with the selected pglock version and PostgreSQL 15 or newer. The current package declares Go 1.25.0. Integration tests need a reachable PostgreSQL primary and permission to create or migrate the lock table and sequence.

license

Apache-2.0

metadata.repository

cirello.io/pglock

metadata.purpose

third-party-application-integration

metadata.version

1

import (
	"context"
	"database/sql"
	"log"
	"time"

	"cirello.io/pglock"
	_ "github.com/lib/pq"
)

ctx := context.Background()
db, err := sql.Open("postgres", dsn)
if err != nil {
	log.Fatal(err)
}
if err := db.PingContext(ctx); err != nil {
	log.Fatal(err)
}

client, err := pglock.New(db,
	pglock.WithOwner(instanceID),
	pglock.WithLeaseDuration(20*time.Second),
	pglock.WithHeartbeatFrequency(5*time.Second),
)
if err != nil {
	log.Fatal(err)
}
if err := client.TryCreateTable(); err != nil {
	log.Fatal(err)
}

import _ "github.com/jackc/pgx/v5/stdlib"

db, err := sql.Open("pgx", dsn)
client, err := pglock.UnsafeNew(db)

import (
	"errors"
	"log"
)

lock, err := client.AcquireContext(ctx, lockKey)
if err != nil {
	if errors.Is(err, pglock.ErrNotAcquired) {
		// The context ended before acquisition, or use FailIfLocked below.
	}
	return err
}
defer func() {
	if releaseErr := lock.Close(); releaseErr != nil &&
		!errors.Is(releaseErr, pglock.ErrLockAlreadyReleased) {
		log.Printf("release %q: %v", lockKey, releaseErr)
	}
}()

// Do the exclusive work while the lock is held.

© cirello-io, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 4 other files (scripts, references) in skills/pglock-integration of cirello-io/pglock.

• SKILL.md
• evals/evals.json
• evals/trigger_queries.json
• references/integration-guide.md
• scripts/validate_skill.py

Open the folder on GitHubat commit 6d39959