@medusajs/locking-postgres 2.22.0-snapshot-20261021091347 → 2.22.0

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.
Files changed (3) hide show
  1. package/AGENTS.md +52 -0
  2. package/README.md +87 -0
  3. package/package.json +7 -3
package/AGENTS.md ADDED
@@ -0,0 +1,52 @@
1
+ # @medusajs/locking-postgres
2
+
3
+ Locking Module provider backed by PostgreSQL: `execute` uses transaction-scoped advisory locks, while `acquire`/`release` use rows in a `locking` table. Use it for multi-instance deployments without Redis.
4
+
5
+ ## Using this package
6
+
7
+ ```ts
8
+ module.exports = defineConfig({
9
+ modules: [
10
+ {
11
+ resolve: "@medusajs/medusa/locking",
12
+ options: {
13
+ providers: [
14
+ {
15
+ resolve: "@medusajs/medusa/locking-postgres",
16
+ id: "locking-postgres",
17
+ // use this provider by default
18
+ is_default: true,
19
+ },
20
+ ],
21
+ },
22
+ },
23
+ ],
24
+ })
25
+ ```
26
+
27
+ - No options. Then run `npx medusa db:migrate` to create the `locking` table.
28
+ - The default provider is used unless a call names another; without `is_default` and with several providers registered, the Locking Module falls back to its in-memory provider.
29
+ - Docs: https://docs.medusajs.com/resources/infrastructure-modules/locking/postgres.md
30
+ - Build a custom locking provider: https://docs.medusajs.com/resources/references/locking-module-provider.md
31
+
32
+ ## Architecture
33
+
34
+ - `src/services/advisory-lock.ts`: `PostgresAdvisoryLockProvider extends MedusaService({ Locking }) implements ILockingProvider`, `static identifier = "locking-postgres"`.
35
+ - `ILockingProvider` methods: `execute(keys, job, { timeout? })`, `acquire(keys, { ownerId?, expire? })`, `release(keys, { ownerId? })`, `releaseAll({ ownerId? })`. Reference for a custom locking provider.
36
+ - `execute`: opens a transaction, runs `pg_advisory_xact_lock(hash(key))` per key (djb2-style 32-bit hash), races against `timeout` (default 5 s), runs `job`, commits. The lock is held by the transaction, so no lease renewal.
37
+ - `acquire`/`release`: raw SQL on the `locking` table (`id` = key, `owner_id`, `expiration`).
38
+ - `src/models/locking.ts` + `src/migrations/` (MikroORM config in `mikro-orm.config.dev.ts`).
39
+
40
+ ## Development
41
+
42
+ - `yarn build`, `yarn test`
43
+ - `yarn test:integration`: `integration-tests/__tests__/index.spec.ts` uses `moduleIntegrationTestRunner`, so it needs a local Postgres (`DB_HOST`, `DB_USERNAME`, `DB_PASSWORD`).
44
+ - After changing the model: `yarn migration:create` from this package.
45
+
46
+ ## Gotchas
47
+
48
+ - Forgetting `db:migrate` after registering the provider makes `acquire`/`release` fail (`locking` table missing); `execute` still works since it only uses advisory locks.
49
+ - `execute` ignores `expire` and never aborts the job's `AbortSignal`; a long job holds a DB connection and transaction for its whole duration.
50
+ - Keys are hashed to 32-bit ints for advisory locks, so distinct keys can collide and serialize each other.
51
+ - `releaseAll()` without `ownerId` truncates the whole `locking` table.
52
+ - `acquire` on a key held by a lock with `owner_id = null` always fails, even for a caller without `ownerId`.
package/README.md ADDED
@@ -0,0 +1,87 @@
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/locking-postgres
12
+ </h1>
13
+
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ PostgreSQL Locking Module Provider for Medusa: implements the Locking Module's locks with PostgreSQL advisory locks, using the application's existing database. Use it in production when you don't have Redis; the Redis provider is recommended when available. It ships with `@medusajs/medusa` and is registered through the `@medusajs/medusa/locking-postgres` path.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/locking-postgres` |
44
+ | Type | Module Provider (Locking Module) |
45
+ | Provider ID | `locking-postgres` |
46
+ | Registered by default | No (the Locking Module uses an in-memory provider by default) |
47
+ | Import from | `@medusajs/medusa/locking-postgres` |
48
+
49
+ ## Installation
50
+
51
+ No installation needed. The provider is a dependency of `@medusajs/medusa`.
52
+
53
+ ## Usage
54
+
55
+ Register the provider in the Locking Module's `providers` array in `medusa-config.ts`, then run `npx medusa db:migrate` to create the provider's table.
56
+
57
+ ```ts
58
+ import { defineConfig } from "@medusajs/framework/utils"
59
+
60
+ module.exports = defineConfig({
61
+ // ...
62
+ modules: [
63
+ {
64
+ resolve: "@medusajs/medusa/locking",
65
+ options: {
66
+ providers: [
67
+ {
68
+ resolve: "@medusajs/medusa/locking-postgres",
69
+ id: "locking-postgres",
70
+ // makes this the default locking provider
71
+ is_default: true,
72
+ },
73
+ ],
74
+ },
75
+ },
76
+ ],
77
+ })
78
+ ```
79
+
80
+ ## Configuration
81
+
82
+ The provider has no options.
83
+
84
+ ## Resources
85
+
86
+ - [PostgreSQL Locking Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/locking/postgres)
87
+ - [Locking Module](https://docs.medusajs.com/resources/infrastructure-modules/locking)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@medusajs/locking-postgres",
3
- "version": "2.22.0-snapshot-20261021091347",
3
+ "version": "2.22.0",
4
4
  "description": "Postgres Advisory Locks for Medusa",
5
5
  "main": "dist/index.js",
6
6
  "repository": {
@@ -13,20 +13,24 @@
13
13
  },
14
14
  "files": [
15
15
  "dist",
16
+ "AGENTS.md",
16
17
  "!dist/**/__tests__",
17
18
  "!dist/**/__mocks__",
18
19
  "!dist/**/__fixtures__"
19
20
  ],
21
+ "llms": "https://docs.medusajs.com/llms.txt",
22
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
23
+ "mcpServer": "https://docs.medusajs.com/mcp",
20
24
  "engines": {
21
25
  "node": ">=22.22.0"
22
26
  },
23
27
  "author": "Medusa",
24
28
  "license": "MIT",
25
29
  "devDependencies": {
26
- "@medusajs/framework": "2.22.0-snapshot-20261021091347"
30
+ "@medusajs/framework": "2.22.0"
27
31
  },
28
32
  "peerDependencies": {
29
- "@medusajs/framework": "2.22.0-snapshot-20261021091347"
33
+ "@medusajs/framework": "2.22.0"
30
34
  },
31
35
  "scripts": {
32
36
  "watch": "yarn run -T tsc --build --watch",