PALs 0.3.2__tar.gz → 0.3.4__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {PALs-0.3.2 → PALs-0.3.4}/.circleci/config.yml +2 -2
- PALs-0.3.4/MANIFEST.in +6 -0
- PALs-0.3.4/PALs.egg-info/PKG-INFO +298 -0
- {PALs-0.3.2 → PALs-0.3.4}/PALs.egg-info/SOURCES.txt +3 -6
- PALs-0.3.4/PALs.egg-info/requires.txt +6 -0
- PALs-0.3.4/PKG-INFO +298 -0
- {PALs-0.3.2 → PALs-0.3.4}/changelog.rst +16 -0
- PALs-0.3.4/docker-compose.yaml +9 -0
- {PALs-0.3.2 → PALs-0.3.4}/pals/core.py +28 -10
- {PALs-0.3.2 → PALs-0.3.4}/pals/tests/test_core.py +5 -2
- PALs-0.3.4/pals/version.py +1 -0
- {PALs-0.3.2 → PALs-0.3.4}/readme.rst +1 -2
- PALs-0.3.4/scripts/setup-codecov +7 -0
- {PALs-0.3.2 → PALs-0.3.4}/setup.py +11 -3
- PALs-0.3.4/stable-requirements.txt +13 -0
- {PALs-0.3.2 → PALs-0.3.4}/tox.ini +17 -11
- PALs-0.3.2/MANIFEST.in +0 -8
- PALs-0.3.2/PALs.egg-info/PKG-INFO +0 -279
- PALs-0.3.2/PALs.egg-info/requires.txt +0 -1
- PALs-0.3.2/PKG-INFO +0 -279
- PALs-0.3.2/docker-compose.yaml +0 -7
- PALs-0.3.2/pals/version.py +0 -1
- PALs-0.3.2/requirements/Makefile +0 -13
- PALs-0.3.2/requirements/common.in +0 -12
- PALs-0.3.2/requirements/common.txt +0 -45
- PALs-0.3.2/requirements/dev.in +0 -5
- PALs-0.3.2/requirements/dev.txt +0 -46
- {PALs-0.3.2 → PALs-0.3.4}/.ci/pytest.ini +0 -0
- {PALs-0.3.2 → PALs-0.3.4}/.coveragerc +0 -0
- {PALs-0.3.2 → PALs-0.3.4}/PALs.egg-info/dependency_links.txt +0 -0
- {PALs-0.3.2 → PALs-0.3.4}/PALs.egg-info/not-zip-safe +0 -0
- {PALs-0.3.2 → PALs-0.3.4}/PALs.egg-info/top_level.txt +0 -0
- {PALs-0.3.2 → PALs-0.3.4}/license.txt +0 -0
- {PALs-0.3.2 → PALs-0.3.4}/pals/__init__.py +0 -0
- {PALs-0.3.2 → PALs-0.3.4}/pyp.ini +0 -0
- {PALs-0.3.2 → PALs-0.3.4}/scripts/hang.py +0 -0
- {PALs-0.3.2 → PALs-0.3.4}/setup.cfg +0 -0
|
@@ -3,7 +3,7 @@ jobs:
|
|
|
3
3
|
build:
|
|
4
4
|
docker:
|
|
5
5
|
- image: level12/python-test-multi
|
|
6
|
-
- image: postgres:
|
|
6
|
+
- image: postgres:15
|
|
7
7
|
environment:
|
|
8
8
|
POSTGRES_USER: postgres
|
|
9
9
|
POSTGRES_PASSWORD: password
|
|
@@ -35,4 +35,4 @@ jobs:
|
|
|
35
35
|
|
|
36
36
|
- run:
|
|
37
37
|
name: push code coverage
|
|
38
|
-
command:
|
|
38
|
+
command: source scripts/setup-codecov && ./codecov -t bef3273d-1997-4764-9c87-81e7d6a57778
|
PALs-0.3.4/MANIFEST.in
ADDED
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: PALs
|
|
3
|
+
Version: 0.3.4
|
|
4
|
+
Summary: Easy distributed locking using PostgreSQL Advisory Locks.
|
|
5
|
+
Home-page: https://github.com/level12/pals
|
|
6
|
+
Author: Randy Syring
|
|
7
|
+
Author-email: randy.syring@level12.io
|
|
8
|
+
License: BSD-3-Clause
|
|
9
|
+
Platform: UNKNOWN
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: BSD License
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.7
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Description-Content-Type: text/x-rst
|
|
20
|
+
Provides-Extra: tests
|
|
21
|
+
|
|
22
|
+
.. default-role:: code
|
|
23
|
+
|
|
24
|
+
PostgreSQL Advisory Locks (PALs)
|
|
25
|
+
################################
|
|
26
|
+
|
|
27
|
+
.. image:: https://circleci.com/gh/level12/pals.svg?style=shield
|
|
28
|
+
:target: https://circleci.com/gh/level12/pals
|
|
29
|
+
.. image:: https://codecov.io/gh/level12/pals/branch/master/graph/badge.svg
|
|
30
|
+
:target: https://codecov.io/gh/level12/pals
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
Introduction
|
|
34
|
+
============
|
|
35
|
+
|
|
36
|
+
PALs makes it easy to use `PostgreSQL Advisory Locks`_ to do distributed application level
|
|
37
|
+
locking.
|
|
38
|
+
|
|
39
|
+
Do not confuse this type of locking with table or row locking in PostgreSQL. It's not the same
|
|
40
|
+
thing.
|
|
41
|
+
|
|
42
|
+
Distributed application level locking can be implemented by using Redis, Memcache, ZeroMQ and
|
|
43
|
+
others. But for those who are already using PostgreSQL, setup & management of another service is
|
|
44
|
+
unnecessary.
|
|
45
|
+
|
|
46
|
+
.. _PostgreSQL Advisory Locks: https://www.postgresql.org/docs/current/static/explicit-locking.html#ADVISORY-LOCKS
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
Usage
|
|
50
|
+
========
|
|
51
|
+
|
|
52
|
+
Install with::
|
|
53
|
+
|
|
54
|
+
pip install PALs
|
|
55
|
+
|
|
56
|
+
Then usage is as follows:
|
|
57
|
+
|
|
58
|
+
.. code:: python
|
|
59
|
+
|
|
60
|
+
import datetime as dt
|
|
61
|
+
import pals
|
|
62
|
+
|
|
63
|
+
# Think of the Locker instance as a Lock factory.
|
|
64
|
+
locker = pals.Locker('my-app-name', 'postgresql://user:pass@server/dbname')
|
|
65
|
+
|
|
66
|
+
lock1 = locker.lock('my-lock')
|
|
67
|
+
lock2 = locker.lock('my-lock')
|
|
68
|
+
|
|
69
|
+
# The first acquire works
|
|
70
|
+
assert lock1.acquire() is True
|
|
71
|
+
|
|
72
|
+
# Non blocking version should fail immediately
|
|
73
|
+
assert lock2.acquire(blocking=False) is False
|
|
74
|
+
|
|
75
|
+
# Blocking version should fail after a short time
|
|
76
|
+
start = dt.datetime.now()
|
|
77
|
+
acquired = lock2.acquire(acquire_timeout=300)
|
|
78
|
+
waited_ms = duration(start)
|
|
79
|
+
|
|
80
|
+
assert acquired is False
|
|
81
|
+
assert waited_ms >= 300 and waited_ms < 350
|
|
82
|
+
|
|
83
|
+
# Release the lock
|
|
84
|
+
lock1.release()
|
|
85
|
+
|
|
86
|
+
# Non-blocking usage pattern
|
|
87
|
+
if not lock1.acquire(blocking=False):
|
|
88
|
+
# Aquire returned False, indicating we did not get the lock.
|
|
89
|
+
return
|
|
90
|
+
try:
|
|
91
|
+
# do your work here
|
|
92
|
+
finally:
|
|
93
|
+
lock1.release()
|
|
94
|
+
|
|
95
|
+
# If you want to block, you can use a context manager:
|
|
96
|
+
try:
|
|
97
|
+
with lock1:
|
|
98
|
+
# Do your work here
|
|
99
|
+
pass
|
|
100
|
+
except pals.AcquireFailure:
|
|
101
|
+
# This indicates the aquire_timeout was reached before the lock could be aquired.
|
|
102
|
+
pass
|
|
103
|
+
|
|
104
|
+
Docs
|
|
105
|
+
========
|
|
106
|
+
|
|
107
|
+
Just this readme, the code, and tests. It a small project, should be easy to understand.
|
|
108
|
+
|
|
109
|
+
Feel free to open an issue with questions.
|
|
110
|
+
|
|
111
|
+
Running Tests Locally
|
|
112
|
+
=====================
|
|
113
|
+
|
|
114
|
+
Setup Database Connection
|
|
115
|
+
-------------------------
|
|
116
|
+
|
|
117
|
+
We have provided a docker-compose file to ease running the tests::
|
|
118
|
+
|
|
119
|
+
$ docker-compose up -d
|
|
120
|
+
$ export PALS_DB_URL=postgresql://postgres:password@localhost:54321/postgres
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
Run the Tests
|
|
124
|
+
-------------
|
|
125
|
+
|
|
126
|
+
With tox::
|
|
127
|
+
|
|
128
|
+
$ tox
|
|
129
|
+
|
|
130
|
+
Or, manually (assuming an activated virtualenv)::
|
|
131
|
+
|
|
132
|
+
$ pip install -e .[tests]
|
|
133
|
+
$ pytest pals/tests/
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
Lock Releasing & Expiration
|
|
137
|
+
---------------------------
|
|
138
|
+
|
|
139
|
+
Unlike locking systems built on cache services like Memcache and Redis, whose keys can be expired
|
|
140
|
+
by the service, there is no faculty for expiring an advisory lock in PostgreSQL. If a client
|
|
141
|
+
holds a lock and then sleeps/hangs for mins/hours/days, no other client will be able to get that
|
|
142
|
+
lock until the client releases it. This actually seems like a good thing to us, if a lock is
|
|
143
|
+
acquired, it should be kept until released.
|
|
144
|
+
|
|
145
|
+
But what about accidental failures to release the lock?
|
|
146
|
+
|
|
147
|
+
1. If a developer uses `lock.acquire()` but doesn't later call `lock.release()`?
|
|
148
|
+
2. If code inside a lock accidentally throws an exception (and .release() is not called)?
|
|
149
|
+
3. If the process running the application crashes or the process' server dies?
|
|
150
|
+
|
|
151
|
+
PALs helps #1 and #2 above in a few different ways:
|
|
152
|
+
|
|
153
|
+
* Locks work as context managers. Use them as much as possible to guarantee a lock is released.
|
|
154
|
+
* Locks release their lock when garbage collected.
|
|
155
|
+
* PALs uses a dedicated SQLAlchemy connection pool. When a connection is returned to the pool,
|
|
156
|
+
either because a connection `.close()` is called or due to garbage collection of the connection,
|
|
157
|
+
PALs issues a `pg_advisory_unlock_all()`. It should therefore be impossible for an idle
|
|
158
|
+
connection in the pool to ever still be holding a lock.
|
|
159
|
+
|
|
160
|
+
Regarding #3 above, `pg_advisory_unlock_all()` is implicitly invoked by PostgreSQL whenever a
|
|
161
|
+
connection (a.k.a session) ends, even if the client disconnects ungracefully. So if a process
|
|
162
|
+
crashes or otherwise disappears, PostgreSQL should notice and remove all locks held by that
|
|
163
|
+
connection/session.
|
|
164
|
+
|
|
165
|
+
The possibility could exist that PostgreSQL does not detect a connection has closed and keeps
|
|
166
|
+
a lock open indefinitely. However, in manual testing using `scripts/hang.py` no way was found
|
|
167
|
+
to end the Python process without PostgreSQL detecting it.
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
See Also
|
|
171
|
+
==========
|
|
172
|
+
|
|
173
|
+
* https://vladmihalcea.com/how-do-postgresql-advisory-locks-work/
|
|
174
|
+
* https://github.com/binded/advisory-lock
|
|
175
|
+
* https://github.com/vaidik/sherlock
|
|
176
|
+
* https://github.com/Xof/django-pglocks
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
Changelog
|
|
181
|
+
=========
|
|
182
|
+
|
|
183
|
+
0.3.4 released 2023-03-06
|
|
184
|
+
-------------------------
|
|
185
|
+
|
|
186
|
+
- support SQLAlchemy 2.0 (6879081_)
|
|
187
|
+
|
|
188
|
+
.. _6879081: https://github.com/level12/pals/commit/6879081
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
0.3.3 released 2023-01-06
|
|
192
|
+
-------------------------
|
|
193
|
+
|
|
194
|
+
- add additional info to AcquireFailure exception (6d81db9_)
|
|
195
|
+
|
|
196
|
+
.. _6d81db9: https://github.com/level12/pals/commit/6d81db9
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
0.3.2 released 2021-02-01
|
|
200
|
+
-------------------------
|
|
201
|
+
|
|
202
|
+
- Support shared advisory locks (thanks to @absalon-james) (ba2fe21_)
|
|
203
|
+
|
|
204
|
+
.. _ba2fe21: https://github.com/level12/pals/commit/ba2fe21
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
0.3.1 released 2020-09-03
|
|
208
|
+
-------------------------
|
|
209
|
+
|
|
210
|
+
- readme: update postgresql link (260bf75_)
|
|
211
|
+
- Handle case where a DB connection is returned to the pool which is already closed (5d730c9_)
|
|
212
|
+
- Fix a couple of typos in comments (da2b8af_)
|
|
213
|
+
- readme improvements (4efba90_)
|
|
214
|
+
- CI: fix coverage upload (52daa27_)
|
|
215
|
+
- Fix CI: bump CI python to v3.7 and postgres to v11 (23b3028_)
|
|
216
|
+
|
|
217
|
+
.. _260bf75: https://github.com/level12/pals/commit/260bf75
|
|
218
|
+
.. _5d730c9: https://github.com/level12/pals/commit/5d730c9
|
|
219
|
+
.. _da2b8af: https://github.com/level12/pals/commit/da2b8af
|
|
220
|
+
.. _4efba90: https://github.com/level12/pals/commit/4efba90
|
|
221
|
+
.. _52daa27: https://github.com/level12/pals/commit/52daa27
|
|
222
|
+
.. _23b3028: https://github.com/level12/pals/commit/23b3028
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
0.3.0 released 2019-11-13
|
|
226
|
+
-------------------------
|
|
227
|
+
|
|
228
|
+
Enhancements
|
|
229
|
+
~~~~~~~~~~~~
|
|
230
|
+
|
|
231
|
+
- Add acquire timeout and blocking defaults at Locker level (681c3ba_)
|
|
232
|
+
- Adjust default lock timeout from 1s to 30s (5a0963b_)
|
|
233
|
+
|
|
234
|
+
Project Cleanup
|
|
235
|
+
~~~~~~~~~~~~~~~
|
|
236
|
+
|
|
237
|
+
- adjust flake8 ignore and other tox project warning (ee123fc_)
|
|
238
|
+
- fix comment in test (0d8eb98_)
|
|
239
|
+
- Additional readme updates (0786766_)
|
|
240
|
+
- update locked dependencies (f5743a6_)
|
|
241
|
+
- Remove Python 3.5 from CI (b63c71a_)
|
|
242
|
+
- Cleaned up the readme code example a bit and added more references (dabb497_)
|
|
243
|
+
- Update setup.py to use SPDX license identifier (b811a99_)
|
|
244
|
+
- remove Pipefiles (0637f39_)
|
|
245
|
+
- move to using piptools for dependency management (af2e91f_)
|
|
246
|
+
|
|
247
|
+
.. _ee123fc: https://github.com/level12/pals/commit/ee123fc
|
|
248
|
+
.. _681c3ba: https://github.com/level12/pals/commit/681c3ba
|
|
249
|
+
.. _5a0963b: https://github.com/level12/pals/commit/5a0963b
|
|
250
|
+
.. _0d8eb98: https://github.com/level12/pals/commit/0d8eb98
|
|
251
|
+
.. _0786766: https://github.com/level12/pals/commit/0786766
|
|
252
|
+
.. _f5743a6: https://github.com/level12/pals/commit/f5743a6
|
|
253
|
+
.. _b63c71a: https://github.com/level12/pals/commit/b63c71a
|
|
254
|
+
.. _dabb497: https://github.com/level12/pals/commit/dabb497
|
|
255
|
+
.. _b811a99: https://github.com/level12/pals/commit/b811a99
|
|
256
|
+
.. _0637f39: https://github.com/level12/pals/commit/0637f39
|
|
257
|
+
.. _af2e91f: https://github.com/level12/pals/commit/af2e91f
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
0.2.0 released 2019-03-07
|
|
261
|
+
-------------------------
|
|
262
|
+
|
|
263
|
+
- Fix misspelling of "acquire" (737763f_)
|
|
264
|
+
|
|
265
|
+
.. _737763f: https://github.com/level12/pals/commit/737763f
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
0.1.0 released 2019-02-22
|
|
269
|
+
-------------------------
|
|
270
|
+
|
|
271
|
+
- Use `lock_timeout` setting to expire blocking calls (d0216ce_)
|
|
272
|
+
- fix tox (1b0ffe2_)
|
|
273
|
+
- rename to PALs (95d5a3c_)
|
|
274
|
+
- improve readme (e8dd6f2_)
|
|
275
|
+
- move tests file to better location (a153af5_)
|
|
276
|
+
- add flake8 dep (3909c95_)
|
|
277
|
+
- fix tests so they work locally too (7102294_)
|
|
278
|
+
- get circleci working (28f16d2_)
|
|
279
|
+
- suppress exceptions in Lock __del__ (e29c1ce_)
|
|
280
|
+
- Add hang.py script (3372ef0_)
|
|
281
|
+
- fix packaging stuff, update readme (cebd976_)
|
|
282
|
+
- initial commit (871b877_)
|
|
283
|
+
|
|
284
|
+
.. _d0216ce: https://github.com/level12/pals/commit/d0216ce
|
|
285
|
+
.. _1b0ffe2: https://github.com/level12/pals/commit/1b0ffe2
|
|
286
|
+
.. _95d5a3c: https://github.com/level12/pals/commit/95d5a3c
|
|
287
|
+
.. _e8dd6f2: https://github.com/level12/pals/commit/e8dd6f2
|
|
288
|
+
.. _a153af5: https://github.com/level12/pals/commit/a153af5
|
|
289
|
+
.. _3909c95: https://github.com/level12/pals/commit/3909c95
|
|
290
|
+
.. _7102294: https://github.com/level12/pals/commit/7102294
|
|
291
|
+
.. _28f16d2: https://github.com/level12/pals/commit/28f16d2
|
|
292
|
+
.. _e29c1ce: https://github.com/level12/pals/commit/e29c1ce
|
|
293
|
+
.. _3372ef0: https://github.com/level12/pals/commit/3372ef0
|
|
294
|
+
.. _cebd976: https://github.com/level12/pals/commit/cebd976
|
|
295
|
+
.. _871b877: https://github.com/level12/pals/commit/871b877
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
|
|
@@ -7,6 +7,7 @@ pyp.ini
|
|
|
7
7
|
readme.rst
|
|
8
8
|
setup.cfg
|
|
9
9
|
setup.py
|
|
10
|
+
stable-requirements.txt
|
|
10
11
|
tox.ini
|
|
11
12
|
.ci/pytest.ini
|
|
12
13
|
.circleci/config.yml
|
|
@@ -20,9 +21,5 @@ pals/__init__.py
|
|
|
20
21
|
pals/core.py
|
|
21
22
|
pals/version.py
|
|
22
23
|
pals/tests/test_core.py
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
requirements/common.txt
|
|
26
|
-
requirements/dev.in
|
|
27
|
-
requirements/dev.txt
|
|
28
|
-
scripts/hang.py
|
|
24
|
+
scripts/hang.py
|
|
25
|
+
scripts/setup-codecov
|
PALs-0.3.4/PKG-INFO
ADDED
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: PALs
|
|
3
|
+
Version: 0.3.4
|
|
4
|
+
Summary: Easy distributed locking using PostgreSQL Advisory Locks.
|
|
5
|
+
Home-page: https://github.com/level12/pals
|
|
6
|
+
Author: Randy Syring
|
|
7
|
+
Author-email: randy.syring@level12.io
|
|
8
|
+
License: BSD-3-Clause
|
|
9
|
+
Platform: UNKNOWN
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: BSD License
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.7
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Description-Content-Type: text/x-rst
|
|
20
|
+
Provides-Extra: tests
|
|
21
|
+
|
|
22
|
+
.. default-role:: code
|
|
23
|
+
|
|
24
|
+
PostgreSQL Advisory Locks (PALs)
|
|
25
|
+
################################
|
|
26
|
+
|
|
27
|
+
.. image:: https://circleci.com/gh/level12/pals.svg?style=shield
|
|
28
|
+
:target: https://circleci.com/gh/level12/pals
|
|
29
|
+
.. image:: https://codecov.io/gh/level12/pals/branch/master/graph/badge.svg
|
|
30
|
+
:target: https://codecov.io/gh/level12/pals
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
Introduction
|
|
34
|
+
============
|
|
35
|
+
|
|
36
|
+
PALs makes it easy to use `PostgreSQL Advisory Locks`_ to do distributed application level
|
|
37
|
+
locking.
|
|
38
|
+
|
|
39
|
+
Do not confuse this type of locking with table or row locking in PostgreSQL. It's not the same
|
|
40
|
+
thing.
|
|
41
|
+
|
|
42
|
+
Distributed application level locking can be implemented by using Redis, Memcache, ZeroMQ and
|
|
43
|
+
others. But for those who are already using PostgreSQL, setup & management of another service is
|
|
44
|
+
unnecessary.
|
|
45
|
+
|
|
46
|
+
.. _PostgreSQL Advisory Locks: https://www.postgresql.org/docs/current/static/explicit-locking.html#ADVISORY-LOCKS
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
Usage
|
|
50
|
+
========
|
|
51
|
+
|
|
52
|
+
Install with::
|
|
53
|
+
|
|
54
|
+
pip install PALs
|
|
55
|
+
|
|
56
|
+
Then usage is as follows:
|
|
57
|
+
|
|
58
|
+
.. code:: python
|
|
59
|
+
|
|
60
|
+
import datetime as dt
|
|
61
|
+
import pals
|
|
62
|
+
|
|
63
|
+
# Think of the Locker instance as a Lock factory.
|
|
64
|
+
locker = pals.Locker('my-app-name', 'postgresql://user:pass@server/dbname')
|
|
65
|
+
|
|
66
|
+
lock1 = locker.lock('my-lock')
|
|
67
|
+
lock2 = locker.lock('my-lock')
|
|
68
|
+
|
|
69
|
+
# The first acquire works
|
|
70
|
+
assert lock1.acquire() is True
|
|
71
|
+
|
|
72
|
+
# Non blocking version should fail immediately
|
|
73
|
+
assert lock2.acquire(blocking=False) is False
|
|
74
|
+
|
|
75
|
+
# Blocking version should fail after a short time
|
|
76
|
+
start = dt.datetime.now()
|
|
77
|
+
acquired = lock2.acquire(acquire_timeout=300)
|
|
78
|
+
waited_ms = duration(start)
|
|
79
|
+
|
|
80
|
+
assert acquired is False
|
|
81
|
+
assert waited_ms >= 300 and waited_ms < 350
|
|
82
|
+
|
|
83
|
+
# Release the lock
|
|
84
|
+
lock1.release()
|
|
85
|
+
|
|
86
|
+
# Non-blocking usage pattern
|
|
87
|
+
if not lock1.acquire(blocking=False):
|
|
88
|
+
# Aquire returned False, indicating we did not get the lock.
|
|
89
|
+
return
|
|
90
|
+
try:
|
|
91
|
+
# do your work here
|
|
92
|
+
finally:
|
|
93
|
+
lock1.release()
|
|
94
|
+
|
|
95
|
+
# If you want to block, you can use a context manager:
|
|
96
|
+
try:
|
|
97
|
+
with lock1:
|
|
98
|
+
# Do your work here
|
|
99
|
+
pass
|
|
100
|
+
except pals.AcquireFailure:
|
|
101
|
+
# This indicates the aquire_timeout was reached before the lock could be aquired.
|
|
102
|
+
pass
|
|
103
|
+
|
|
104
|
+
Docs
|
|
105
|
+
========
|
|
106
|
+
|
|
107
|
+
Just this readme, the code, and tests. It a small project, should be easy to understand.
|
|
108
|
+
|
|
109
|
+
Feel free to open an issue with questions.
|
|
110
|
+
|
|
111
|
+
Running Tests Locally
|
|
112
|
+
=====================
|
|
113
|
+
|
|
114
|
+
Setup Database Connection
|
|
115
|
+
-------------------------
|
|
116
|
+
|
|
117
|
+
We have provided a docker-compose file to ease running the tests::
|
|
118
|
+
|
|
119
|
+
$ docker-compose up -d
|
|
120
|
+
$ export PALS_DB_URL=postgresql://postgres:password@localhost:54321/postgres
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
Run the Tests
|
|
124
|
+
-------------
|
|
125
|
+
|
|
126
|
+
With tox::
|
|
127
|
+
|
|
128
|
+
$ tox
|
|
129
|
+
|
|
130
|
+
Or, manually (assuming an activated virtualenv)::
|
|
131
|
+
|
|
132
|
+
$ pip install -e .[tests]
|
|
133
|
+
$ pytest pals/tests/
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
Lock Releasing & Expiration
|
|
137
|
+
---------------------------
|
|
138
|
+
|
|
139
|
+
Unlike locking systems built on cache services like Memcache and Redis, whose keys can be expired
|
|
140
|
+
by the service, there is no faculty for expiring an advisory lock in PostgreSQL. If a client
|
|
141
|
+
holds a lock and then sleeps/hangs for mins/hours/days, no other client will be able to get that
|
|
142
|
+
lock until the client releases it. This actually seems like a good thing to us, if a lock is
|
|
143
|
+
acquired, it should be kept until released.
|
|
144
|
+
|
|
145
|
+
But what about accidental failures to release the lock?
|
|
146
|
+
|
|
147
|
+
1. If a developer uses `lock.acquire()` but doesn't later call `lock.release()`?
|
|
148
|
+
2. If code inside a lock accidentally throws an exception (and .release() is not called)?
|
|
149
|
+
3. If the process running the application crashes or the process' server dies?
|
|
150
|
+
|
|
151
|
+
PALs helps #1 and #2 above in a few different ways:
|
|
152
|
+
|
|
153
|
+
* Locks work as context managers. Use them as much as possible to guarantee a lock is released.
|
|
154
|
+
* Locks release their lock when garbage collected.
|
|
155
|
+
* PALs uses a dedicated SQLAlchemy connection pool. When a connection is returned to the pool,
|
|
156
|
+
either because a connection `.close()` is called or due to garbage collection of the connection,
|
|
157
|
+
PALs issues a `pg_advisory_unlock_all()`. It should therefore be impossible for an idle
|
|
158
|
+
connection in the pool to ever still be holding a lock.
|
|
159
|
+
|
|
160
|
+
Regarding #3 above, `pg_advisory_unlock_all()` is implicitly invoked by PostgreSQL whenever a
|
|
161
|
+
connection (a.k.a session) ends, even if the client disconnects ungracefully. So if a process
|
|
162
|
+
crashes or otherwise disappears, PostgreSQL should notice and remove all locks held by that
|
|
163
|
+
connection/session.
|
|
164
|
+
|
|
165
|
+
The possibility could exist that PostgreSQL does not detect a connection has closed and keeps
|
|
166
|
+
a lock open indefinitely. However, in manual testing using `scripts/hang.py` no way was found
|
|
167
|
+
to end the Python process without PostgreSQL detecting it.
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
See Also
|
|
171
|
+
==========
|
|
172
|
+
|
|
173
|
+
* https://vladmihalcea.com/how-do-postgresql-advisory-locks-work/
|
|
174
|
+
* https://github.com/binded/advisory-lock
|
|
175
|
+
* https://github.com/vaidik/sherlock
|
|
176
|
+
* https://github.com/Xof/django-pglocks
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
Changelog
|
|
181
|
+
=========
|
|
182
|
+
|
|
183
|
+
0.3.4 released 2023-03-06
|
|
184
|
+
-------------------------
|
|
185
|
+
|
|
186
|
+
- support SQLAlchemy 2.0 (6879081_)
|
|
187
|
+
|
|
188
|
+
.. _6879081: https://github.com/level12/pals/commit/6879081
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
0.3.3 released 2023-01-06
|
|
192
|
+
-------------------------
|
|
193
|
+
|
|
194
|
+
- add additional info to AcquireFailure exception (6d81db9_)
|
|
195
|
+
|
|
196
|
+
.. _6d81db9: https://github.com/level12/pals/commit/6d81db9
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
0.3.2 released 2021-02-01
|
|
200
|
+
-------------------------
|
|
201
|
+
|
|
202
|
+
- Support shared advisory locks (thanks to @absalon-james) (ba2fe21_)
|
|
203
|
+
|
|
204
|
+
.. _ba2fe21: https://github.com/level12/pals/commit/ba2fe21
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
0.3.1 released 2020-09-03
|
|
208
|
+
-------------------------
|
|
209
|
+
|
|
210
|
+
- readme: update postgresql link (260bf75_)
|
|
211
|
+
- Handle case where a DB connection is returned to the pool which is already closed (5d730c9_)
|
|
212
|
+
- Fix a couple of typos in comments (da2b8af_)
|
|
213
|
+
- readme improvements (4efba90_)
|
|
214
|
+
- CI: fix coverage upload (52daa27_)
|
|
215
|
+
- Fix CI: bump CI python to v3.7 and postgres to v11 (23b3028_)
|
|
216
|
+
|
|
217
|
+
.. _260bf75: https://github.com/level12/pals/commit/260bf75
|
|
218
|
+
.. _5d730c9: https://github.com/level12/pals/commit/5d730c9
|
|
219
|
+
.. _da2b8af: https://github.com/level12/pals/commit/da2b8af
|
|
220
|
+
.. _4efba90: https://github.com/level12/pals/commit/4efba90
|
|
221
|
+
.. _52daa27: https://github.com/level12/pals/commit/52daa27
|
|
222
|
+
.. _23b3028: https://github.com/level12/pals/commit/23b3028
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
0.3.0 released 2019-11-13
|
|
226
|
+
-------------------------
|
|
227
|
+
|
|
228
|
+
Enhancements
|
|
229
|
+
~~~~~~~~~~~~
|
|
230
|
+
|
|
231
|
+
- Add acquire timeout and blocking defaults at Locker level (681c3ba_)
|
|
232
|
+
- Adjust default lock timeout from 1s to 30s (5a0963b_)
|
|
233
|
+
|
|
234
|
+
Project Cleanup
|
|
235
|
+
~~~~~~~~~~~~~~~
|
|
236
|
+
|
|
237
|
+
- adjust flake8 ignore and other tox project warning (ee123fc_)
|
|
238
|
+
- fix comment in test (0d8eb98_)
|
|
239
|
+
- Additional readme updates (0786766_)
|
|
240
|
+
- update locked dependencies (f5743a6_)
|
|
241
|
+
- Remove Python 3.5 from CI (b63c71a_)
|
|
242
|
+
- Cleaned up the readme code example a bit and added more references (dabb497_)
|
|
243
|
+
- Update setup.py to use SPDX license identifier (b811a99_)
|
|
244
|
+
- remove Pipefiles (0637f39_)
|
|
245
|
+
- move to using piptools for dependency management (af2e91f_)
|
|
246
|
+
|
|
247
|
+
.. _ee123fc: https://github.com/level12/pals/commit/ee123fc
|
|
248
|
+
.. _681c3ba: https://github.com/level12/pals/commit/681c3ba
|
|
249
|
+
.. _5a0963b: https://github.com/level12/pals/commit/5a0963b
|
|
250
|
+
.. _0d8eb98: https://github.com/level12/pals/commit/0d8eb98
|
|
251
|
+
.. _0786766: https://github.com/level12/pals/commit/0786766
|
|
252
|
+
.. _f5743a6: https://github.com/level12/pals/commit/f5743a6
|
|
253
|
+
.. _b63c71a: https://github.com/level12/pals/commit/b63c71a
|
|
254
|
+
.. _dabb497: https://github.com/level12/pals/commit/dabb497
|
|
255
|
+
.. _b811a99: https://github.com/level12/pals/commit/b811a99
|
|
256
|
+
.. _0637f39: https://github.com/level12/pals/commit/0637f39
|
|
257
|
+
.. _af2e91f: https://github.com/level12/pals/commit/af2e91f
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
0.2.0 released 2019-03-07
|
|
261
|
+
-------------------------
|
|
262
|
+
|
|
263
|
+
- Fix misspelling of "acquire" (737763f_)
|
|
264
|
+
|
|
265
|
+
.. _737763f: https://github.com/level12/pals/commit/737763f
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
0.1.0 released 2019-02-22
|
|
269
|
+
-------------------------
|
|
270
|
+
|
|
271
|
+
- Use `lock_timeout` setting to expire blocking calls (d0216ce_)
|
|
272
|
+
- fix tox (1b0ffe2_)
|
|
273
|
+
- rename to PALs (95d5a3c_)
|
|
274
|
+
- improve readme (e8dd6f2_)
|
|
275
|
+
- move tests file to better location (a153af5_)
|
|
276
|
+
- add flake8 dep (3909c95_)
|
|
277
|
+
- fix tests so they work locally too (7102294_)
|
|
278
|
+
- get circleci working (28f16d2_)
|
|
279
|
+
- suppress exceptions in Lock __del__ (e29c1ce_)
|
|
280
|
+
- Add hang.py script (3372ef0_)
|
|
281
|
+
- fix packaging stuff, update readme (cebd976_)
|
|
282
|
+
- initial commit (871b877_)
|
|
283
|
+
|
|
284
|
+
.. _d0216ce: https://github.com/level12/pals/commit/d0216ce
|
|
285
|
+
.. _1b0ffe2: https://github.com/level12/pals/commit/1b0ffe2
|
|
286
|
+
.. _95d5a3c: https://github.com/level12/pals/commit/95d5a3c
|
|
287
|
+
.. _e8dd6f2: https://github.com/level12/pals/commit/e8dd6f2
|
|
288
|
+
.. _a153af5: https://github.com/level12/pals/commit/a153af5
|
|
289
|
+
.. _3909c95: https://github.com/level12/pals/commit/3909c95
|
|
290
|
+
.. _7102294: https://github.com/level12/pals/commit/7102294
|
|
291
|
+
.. _28f16d2: https://github.com/level12/pals/commit/28f16d2
|
|
292
|
+
.. _e29c1ce: https://github.com/level12/pals/commit/e29c1ce
|
|
293
|
+
.. _3372ef0: https://github.com/level12/pals/commit/3372ef0
|
|
294
|
+
.. _cebd976: https://github.com/level12/pals/commit/cebd976
|
|
295
|
+
.. _871b877: https://github.com/level12/pals/commit/871b877
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
|
|
@@ -1,6 +1,22 @@
|
|
|
1
1
|
Changelog
|
|
2
2
|
=========
|
|
3
3
|
|
|
4
|
+
0.3.4 released 2023-03-06
|
|
5
|
+
-------------------------
|
|
6
|
+
|
|
7
|
+
- support SQLAlchemy 2.0 (6879081_)
|
|
8
|
+
|
|
9
|
+
.. _6879081: https://github.com/level12/pals/commit/6879081
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
0.3.3 released 2023-01-06
|
|
13
|
+
-------------------------
|
|
14
|
+
|
|
15
|
+
- add additional info to AcquireFailure exception (6d81db9_)
|
|
16
|
+
|
|
17
|
+
.. _6d81db9: https://github.com/level12/pals/commit/6d81db9
|
|
18
|
+
|
|
19
|
+
|
|
4
20
|
0.3.2 released 2021-02-01
|
|
5
21
|
-------------------------
|
|
6
22
|
|