{"id":13562253,"url":"https://github.com/cirello-io/pglock","last_synced_at":"2025-04-05T10:08:07.386Z","repository":{"id":34686566,"uuid":"162168429","full_name":"cirello-io/pglock","owner":"cirello-io","description":"PostgreSQL Lock Client for Go","archived":false,"fork":false,"pushed_at":"2025-03-25T18:17:54.000Z","size":372,"stargazers_count":114,"open_issues_count":0,"forks_count":25,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T09:12:39.627Z","etag":null,"topics":["lock","locking"],"latest_commit_sha":null,"homepage":"https://godoc.org/cirello.io/pglock","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cirello-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-17T17:43:41.000Z","updated_at":"2025-03-25T18:17:50.000Z","dependencies_parsed_at":"2023-11-09T16:27:57.843Z","dependency_job_id":"45801fac-e535-4860-b32c-3d24f3ce0bf0","html_url":"https://github.com/cirello-io/pglock","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirello-io%2Fpglock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirello-io%2Fpglock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirello-io%2Fpglock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cirello-io%2Fpglock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cirello-io","download_url":"https://codeload.github.com/cirello-io/pglock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247318744,"owners_count":20919484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lock","locking"],"created_at":"2024-08-01T13:01:06.304Z","updated_at":"2025-04-05T10:08:07.367Z","avatar_url":"https://github.com/cirello-io.png","language":"Go","funding_links":[],"categories":["Go","Distributed Systems"],"sub_categories":["Advanced Console UIs"],"readme":"# PostgreSQL Lock Client for Go\n\n[![GoDoc](https://godoc.org/cirello.io/pglock?status.svg)](https://godoc.org/cirello.io/pglock)\n[![Build status](https://github.com/cirello-io/pglock/actions/workflows/go.yml/badge.svg)](https://github.com/cirello-io/pglock/actions/workflows/go.yml)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)\n\nThe PostgreSQL Lock Client for Go is a general purpose distributed locking\nlibrary built for PostgreSQL. The PostgreSQL Lock Client for Go supports both\nfine-grained and coarse-grained locking as the lock keys can be any arbitrary\nstring, up to a certain length. Please create issues in the GitHub repository\nwith questions, pull request are very much welcome.\n\n_Recommended PostgreSQL version: 13 or newer_\n\n## Use cases\nA common use case for this lock client is:\nlet's say you have a distributed system that needs to periodically do work on a\ngiven campaign (or a given customer, or any other object) and you want to make\nsure that two boxes don't work on the same campaign/customer at the same time.\nAn easy way to fix this is to write a system that takes a lock on a customer,\nbut fine-grained locking is a tough problem. This library attempts to simplify\nthis locking problem on top of PostgreSQL.\n\nAnother use case is leader election. If you only want one host to be the leader,\nthen this lock client is a great way to pick one. When the leader fails, it will\nfail over to another host within a customizable lease duration that you set.\n\n## Getting Started\nTo use the PostgreSQL Lock Client for Go, you must make it sure it is present in\n`$GOPATH` or in your vendor directory.\n\n```sh\n$ go get -u cirello.io/pglock\n```\n\nThis package has the `go.mod` file to be used with Go's module system. If you\nneed to work on this package, use `go mod edit -replace=cirello.io/pglock@yourlocalcopy`.\n\nFor your convenience, there is a function in the package called `CreateTable`\nthat you can use to set up your table, or you may use the schema.sql file.\nThe package level documentation comment has an example of how to use this\npackage. Here is some example code to get you started:\n\n```Go\npackage main\n\nimport (\n\t\"log\"\n\n\t\"cirello.io/pglock\"\n)\n\nfunc main() {\n\tdb, err := sql.Open(\"postgres\", *dsn)\n\tif err != nil {\n\t\tlog.Fatal(\"cannot connect to test database server:\", err)\n\t}\n\tc, err := pglock.New(db,\n\t\tpglock.WithLeaseDuration(3*time.Second),\n\t\tpglock.WithHeartbeatFrequency(1*time.Second),\n\t)\n\tif err != nil {\n\t\tlog.Fatal(\"cannot create lock client:\", err)\n\t}\n\tif err := c.CreateTable(); err != nil {\n\t\tlog.Fatal(\"cannot create table:\", err)\n\t}\n\tl, err := c.Acquire(\"lock-name\")\n\tif err != nil {\n\t\tlog.Fatal(\"unexpected error while acquiring 1st lock:\", err)\n\t}\n\tdefer l.Close()\n\t// execute the logic\n}\n```\n\n## Selected Features\n### Send Automatic Heartbeats\nWhen you create the lock client, you can specify `WithHeartbeatFrequency(time.Duration)`\nlike in the above example, and it will spawn a background goroutine that\ncontinually updates the record version number on your locks to prevent them from\nexpiring (it does this by calling the `SendHeartbeat()` method in the lock\nclient.) This will ensure that as long as your application is running, your\nlocks will not expire until you call `Release()` or `lockItem.Close()`\n\n### Read the data in a lock without acquiring it\nYou can read the data in the lock without acquiring it. Here's how:\n```Go\nlock, err := lockClient.Get(\"kirk\");\n```\n\n## Logic to avoid problems with clock skew\nThe lock client never stores absolute times in PostgreSQL. The way locks are\nexpired is that a call to tryAcquire reads in the current lock, checks the\nrecord version number of the lock and starts a timer. If the lock still has the\nsame after the lease duration time has passed, the client will determine that\nthe lock is stale and expire it.\n\nWhat this means is that, even if two different machines disagree about what time\nit is, they will still avoid clobbering each other's locks.\n\n## Go Version Compatibility Promise\n\nThis package follows the same guidance as the Go's:\n\n\u003e 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirello-io%2Fpglock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcirello-io%2Fpglock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirello-io%2Fpglock/lists"}