Shared Stores

Stores

Keep AxilJS rate limits, idempotency records, cache entries, locks and AI budgets in PostgreSQL, MySQL or SQLite with @axiljs/stores, so several servers share one view of them.

7 min readUpdated DocumentationEdit this page
On this page15

@axiljs/stores keeps the state that AxilJS otherwise holds in process memory (rate-limit counters, idempotency records, cache entries, distributed locks and AI budget counters) in the database you already run: PostgreSQL, MySQL or SQLite. Every server pointed at the same database shares one view of that state, so a multi-instance deployment works correctly without Redis.

Note

New in 0.3.5: the @axiljs/stores package. New in 0.3.6: createSqlStores(), SqlBudgetStore, and useStores() in @axiljs/runtime.

Why

By default, tIdempotent, tCache, tLock, tRateLimit and tThrottle from @axiljs/runtime, rateLimit() from @axiljs/security and withBudget() from @axiljs/ai keep their state in the memory of one process. That is correct for a single instance and wrong behind a load balancer:

  • a retried payment reaches a server that has not seen its idempotency key, and runs twice;
  • a lock is held by two servers at once;
  • a limit of 100 requests becomes 100 per instance.

The stores in this package implement the same interfaces as the in-memory defaults, backed by SQL tables. See Running multiple instances for the complete setup, including the queue and events.

Properties

  • Zero dependencies, including other @axiljs packages. The stores match the @axiljs/runtime, @axiljs/security and @axiljs/ai interfaces structurally.
  • No migration step. Each store creates its table on first use (CREATE TABLE IF NOT EXISTS). ensureSchema() creates them up front if you prefer.
  • Invisible to intent checks. Every statement the stores run is excluded from @axiljs/runtime's intent checks, so a cache write or lock row inside a tReadOnly or tPure method is not reported as that method's side effect.
  • Never closes your connection. close() on a store only stops its cleanup timer.

Install

❯npm install @axiljs/stores
❯pnpm add @axiljs/stores
❯yarn add @axiljs/stores
❯bun add @axiljs/stores

You also need a database connection, usually from @axiljs/orm with its driver (pg, mysql2 or better-sqlite3).

Connecting: fromConnection

The stores talk to the database through a minimal SqlExecutor. fromConnection() builds one from an @axiljs/orm connection and reads the dialect from the connection config:

TypeScript
TS
1import { createConnection } from '@axiljs/orm'
2import { fromConnection } from '@axiljs/stores'
3
4const db   = await createConnection({ driver: 'postgres', url: process.env.DATABASE_URL })
5const exec = fromConnection(db)

fromConnection accepts anything with getDriver() whose driver exposes config.driver ('postgres', 'mysql' or 'sqlite') and query(). It also forwards the driver's transaction(). Any other driver name throws unsupported driver.

A custom executor

To use another client, implement SqlExecutor yourself:

TypeScript
TS
1import type { SqlExecutor } from '@axiljs/stores'
2
3const exec: SqlExecutor = {
4  dialect: 'postgres',
5  // sql arrives with native placeholders ($1..$n for postgres, ? for mysql/sqlite)
6  async query(sql, params) {
7    const r = await pool.query(sql, params)
8    return { rows: r.rows, affectedRows: r.rowCount }
9  },
10  // optional; needed for exact MySQL rate-limit and budget counts and for PgAdvisoryLockProvider
11  async transaction(work) { /* BEGIN on one connection, work(trxExecutor), COMMIT */ }
12}
MemberRequiredDescription
dialectyes'postgres' | 'mysql' | 'sqlite'
query(sql, params?)yesRun one statement and resolve with { rows, affectedRows? }. Placeholders are already in the dialect's native form
transaction(work)noRun work(trx) on a single connection inside a transaction. Used by the MySQL rate-limit and budget paths for an exact count, and required by PgAdvisoryLockProvider

toDialect(dialect, sql) is exported too: it rewrites ? placeholders to $1..$n for postgres and leaves other dialects unchanged.

All stores at once: createSqlStores

createSqlStores(executor, options?) builds every store on one executor with a shared table prefix:

TypeScript
TS
1import { useStores } from '@axiljs/runtime'
2import { fromConnection, createSqlStores } from '@axiljs/stores'
3
4const stores = createSqlStores(fromConnection(db), { cleanupIntervalMs: 60_000 })
5await stores.ensureSchema()   // optional: create every table at startup
6useStores(stores)             // tRateLimit, tThrottle, tIdempotent, tCache*, tLock
7
8// on shutdown
9stores.close()                // stops cleanup timers; the connection stays open

Options

OptionDefaultDescription
tablePrefix'axil_'Prepended to every table name. Letters, digits and _ only; may be empty. Anything else throws
lock'lease''lease' uses SqlLockProvider (any dialect). 'advisory' uses PgAdvisoryLockProvider and throws unless the executor is postgres with transaction()
nowDate.nowClock in epoch ms, shared by every store
cleanupIntervalMsoffDelete expired rows on an unref'd timer, shared by every store
rateLimitSqlRateLimitStore options
idempotencySqlIdempotencyStore options
cacheSqlCacheStore options
leaseLockSqlLockProvider options (when lock: 'lease')
advisoryLockPgAdvisoryLockProvider options, e.g. { namespace } (when lock: 'advisory')
budgetSqlBudgetStore options

The per-store options override the shared ones, including table. See the store reference for each store's options.

Table names

With the default prefix the tables are:

StoreTable
rateLimitaxil_rate_limits
idempotencyaxil_idempotency
cacheaxil_cache and axil_cache_tags
lock (lease)axil_locks
budgetaxil_ai_budget

With lock: 'advisory' there is no lock table.

The returned object

MemberDescription
rateLimitSqlRateLimitStore
idempotencySqlIdempotencyStore
cacheSqlCacheStore
lockSqlLockProvider or PgAdvisoryLockProvider, depending on lock
budgetSqlBudgetStore
tablesThe table names in use (no lock table with advisory locks)
ensureSchema()Create every table now. Idempotent; runs the stores in sequence, which suits a migration step or startup hook. Without it each store still creates its table on first use
close()Stop every cleanup timer. Does not close the database connection

Wiring the stores

@axiljs/runtime: useStores

useStores() accepts { rateLimit?, idempotency?, cache?, lock? }, installs the stores it is given, ignores other properties (so the whole createSqlStores result can be passed), and returns the names it installed. Stores you leave out keep their current implementation (in-process by default).

StoreDecorators
rateLimittRateLimit, tThrottle
idempotencytIdempotent
cachetCache, tCachePut, tCacheEvict, tCacheInvalidate
locktLock

Any object with the matching members works, so a Redis or custom implementation plugs in the same way. To install stores one by one, use the individual setters:

TypeScript
TS
1import { setRateLimitStore, setIdempotencyStore, setCacheStore, setLockProvider } from '@axiljs/runtime'
2import { SqlRateLimitStore, SqlIdempotencyStore, SqlCacheStore, SqlLockProvider } from '@axiljs/stores'
3
4setRateLimitStore(new SqlRateLimitStore(exec))       // tRateLimit, tThrottle
5setIdempotencyStore(new SqlIdempotencyStore(exec))   // tIdempotent
6setCacheStore(new SqlCacheStore(exec))               // tCache, tCachePut, tCacheEvict, tCacheInvalidate
7setLockProvider(new SqlLockProvider(exec))           // tLock

@axiljs/security: HTTP rate limiting

SqlRateLimitStore has the shape of rateLimit()'s store:

TypeScript
TS
1import { rateLimit } from '@axiljs/security'
2import { SqlRateLimitStore } from '@axiljs/stores'
3
4app.use(rateLimit({
5  windowMs: 60_000,
6  max: 100,
7  store: new SqlRateLimitStore(exec, { table: 'api_rate_limits', cleanupIntervalMs: 60_000 })
8}))

Warning

The same key in one table shares one window. When limiters have different windows, give each its own table (or a distinct key prefix through keyGenerator).

@axiljs/ai: budgets

SqlBudgetStore implements @axiljs/ai's BudgetStore, so withBudget limits hold across every server that shares the table instead of per process:

TypeScript
TS
1import { OpenAIProvider, withBudget } from '@axiljs/ai'
2
3const ai = withBudget(new OpenAIProvider({ apiKey }), {
4  limits: [
5    { window: 'minute', requests: 60 },
6    { window: 'month',  costUsd: 50 }
7  ],
8  pricing: { 'gpt-4o-mini': { inputPerMTok: 0.15, outputPerMTok: 0.6 } },
9  store: stores.budget          // or new SqlBudgetStore(exec, { cleanupIntervalMs: 3_600_000 })
10})

Dialects

DialectUse it forNotes
PostgreSQLSeveral servers (recommended)Every operation is a single atomic statement or a short transaction. Supports lock: 'advisory'
MySQL 8Several serversNo RETURNING: counters use an upsert plus SELECT in one transaction, which needs an executor with transaction() (fromConnection provides one)
SQLiteSeveral processes on one host sharing a database fileThe stores never open transactions on SQLite; correctness-critical steps are single statements

The per-dialect details and caveats are in the store reference.

Tip

Keep server clocks in sync with NTP. Windows, expiries and leases are computed from each server's Date.now(), so clock skew between servers shifts window boundaries and lease expiry by the skew.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY