Skip to content
Back to search

pglock

PostgreSQL Lock Client for Go

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cirello-io/pglock with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cirello-io/pglock'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cirello-io--pglock/badge.svg)](/listings/cirello-io--pglock)

HTML

<a href="/listings/cirello-io--pglock"><img src="/api/listings/cirello-io--pglock/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

To use the PostgreSQL Lock Client for Go, you must make it sure it is present in `$GOPATH` or in your vendor directory.

$ go get -u cirello.io/pglock

This package has the `go.mod` file to be used with Go's module system. If you need to work on this package, use `go mod edit -replace=cirello.io/pglock@yourlocalcopy`.

For your convenience, there is a function in the package called `CreateTable` that you can use to set up your table, or you may use the schema.sql file. The package level documentation comment has an example of how to use this package. Here is some example code to get you started:

package main

import (
	"context"
	"log"

	"cirello.io/pglock"
)

func main() {
	db, err := sql.Open("postgres", *dsn)
	if err != nil {
		log.Fatal("cannot connect to test database server:", err)
	}
	c, err := pglock.New(db,
		pglock.WithLeaseDuration(3*time.Second),
		pglock.WithHeartbeatFrequency(1*time.Second),
	)
	if err != nil {
		log.Fatal("cannot create lock client:", err)
	}
	if err := c.CreateTable(); err != nil {
		log.Fatal("cannot create table:", err)
	}
	l, err := c.AcquireContext(context.Background(), "lock-name")
	if err != nil {
		log.Fatal("unexpected error while acquiring 1st lock:", err)
	}
	defer l.Close()
	// execute the logic
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 107 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # PostgreSQL Lock Client for Go
  2. [![GoDoc](https://godoc.org/cirello.io/pglock?status.svg)](https://godoc.org/cirello.io/pglock)
  3. [![Build status](https://github.com/cirello-io/pglock/actions/workflows/go.yml/badge.svg)](https://github.com/cirello-io/pglock/actions/workflows/go.yml)
  4. [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
  5. The PostgreSQL Lock Client for Go is a general purpose distributed locking
  6. library built for PostgreSQL. The PostgreSQL Lock Client for Go supports both
  7. fine-grained and coarse-grained locking as the lock keys can be any arbitrary
  8. string, up to a certain length. Please create issues in the GitHub repository
  9. with questions, pull request are very much welcome.
  10. _Recommended PostgreSQL version: 15 or newer_
  11. ## Use cases
  12. A common use case for this lock client is:
  13. let's say you have a distributed system that needs to periodically do work on a
  14. given campaign (or a given customer, or any other object) and you want to make
  15. sure that two boxes don't work on the same campaign/customer at the same time.
  16. An easy way to fix this is to write a system that takes a lock on a customer,
  17. but fine-grained locking is a tough problem. This library attempts to simplify
  18. this locking problem on top of PostgreSQL.
  19. Another use case is leader election. If you only want one host to be the leader,
  20. then this lock client is a great way to pick one. When the leader fails, it will
  21. fail over to another host within a customizable lease duration that you set.
  22. ## Getting Started
  23. To use the PostgreSQL Lock Client for Go, you must make it sure it is present in
  24. `$GOPATH` or in your vendor directory.
  25. ```sh
  26. $ go get -u cirello.io/pglock
  27. ```
  28. This package has the `go.mod` file to be used with Go's module system. If you
  29. need to work on this package, use `go mod edit -replace=cirello.io/pglock@yourlocalcopy`.
  30. For your convenience, there is a function in the package called `CreateTable`
  31. that you can use to set up your table, or you may use the schema.sql file.
  32. The package level documentation comment has an example of how to use this
  33. package. Here is some example code to get you started:
  34. ```Go
  35. package main
  36. import (
  37. "context"
  38. "log"
  39. "cirello.io/pglock"
  40. )
  41. func main() {
  42. db, err := sql.Open("postgres", *dsn)
  43. if err != nil {
  44. log.Fatal("cannot connect to test database server:", err)
  45. }
  46. c, err := pglock.New(db,
  47. pglock.WithLeaseDuration(3*time.Second),
  48. pglock.WithHeartbeatFrequency(1*time.Second),
  49. )
  50. if err != nil {
  51. log.Fatal("cannot create lock client:", err)
  52. }
  53. if err := c.CreateTable(); err != nil {
  54. log.Fatal("cannot create table:", err)
  55. }
  56. l, err := c.AcquireContext(context.Background(), "lock-name")
  57. if err != nil {
  58. log.Fatal("unexpected error while acquiring 1st lock:", err)
  59. }
  60. defer l.Close()
  61. // execute the logic
  62. }
  63. ```
  64. ## Selected Features
  65. ### Send Automatic Heartbeats
  66. When you create the lock client, you can specify `WithHeartbeatFrequency(time.Duration)`
  67. like in the above example, and it will spawn a background goroutine that
  68. continually updates the record version number on your locks to prevent them from
  69. expiring (it does this by calling the `SendHeartbeat()` method in the lock
  70. client.) This will ensure that as long as your application is running, your
  71. locks will not expire until you call `ReleaseContext()` or `lockItem.Close()`
  72. ### Read the data in a lock without acquiring it
  73. You can read the data in the lock without acquiring it. Here's how:
  74. ```Go
  75. lock, err := lockClient.GetContext(context.Background(), "kirk");
  76. ```
  77. ## Logic to avoid problems with clock skew
  78. The lock client never stores absolute times in PostgreSQL. The way locks are
  79. expired is that a call to tryAcquire reads in the current lock, checks the
  80. record version number of the lock and starts a timer. If the lock still has the
  81. same after the lease duration time has passed, the client will determine that
  82. the lock is stale and expire it.
  83. What this means is that, even if two different machines disagree about what time
  84. it is, they will still avoid clobbering each other's locks.
  85. ## Go Version Compatibility Promise
  86. This package follows the same guidance as the Go's:
  87. > Each major Go release is supported until there are two newer major releases. For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release. We fix critical problems, including critical security problems, in supported releases as needed by issuing minor revisions (for example, Go 1.6.1, Go 1.6.2, and so on).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.