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.
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
@axiljspackages. The stores match the@axiljs/runtime,@axiljs/securityand@axiljs/aiinterfaces 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 atReadOnlyortPuremethod is not reported as that method's side effect. - Never closes your connection.
close()on a store only stops its cleanup timer.
Install
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:
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:
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}| Member | Required | Description |
|---|---|---|
dialect | yes | 'postgres' | 'mysql' | 'sqlite' |
query(sql, params?) | yes | Run one statement and resolve with { rows, affectedRows? }. Placeholders are already in the dialect's native form |
transaction(work) | no | Run 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:
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 openOptions
| Option | Default | Description |
|---|---|---|
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() |
now | Date.now | Clock in epoch ms, shared by every store |
cleanupIntervalMs | off | Delete expired rows on an unref'd timer, shared by every store |
rateLimit | SqlRateLimitStore options | |
idempotency | SqlIdempotencyStore options | |
cache | SqlCacheStore options | |
leaseLock | SqlLockProvider options (when lock: 'lease') | |
advisoryLock | PgAdvisoryLockProvider options, e.g. { namespace } (when lock: 'advisory') | |
budget | SqlBudgetStore 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:
| Store | Table |
|---|---|
rateLimit | axil_rate_limits |
idempotency | axil_idempotency |
cache | axil_cache and axil_cache_tags |
lock (lease) | axil_locks |
budget | axil_ai_budget |
With lock: 'advisory' there is no lock table.
The returned object
| Member | Description |
|---|---|
rateLimit | SqlRateLimitStore |
idempotency | SqlIdempotencyStore |
cache | SqlCacheStore |
lock | SqlLockProvider or PgAdvisoryLockProvider, depending on lock |
budget | SqlBudgetStore |
tables | The 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).
| Store | Decorators |
|---|---|
rateLimit | tRateLimit, tThrottle |
idempotency | tIdempotent |
cache | tCache, tCachePut, tCacheEvict, tCacheInvalidate |
lock | tLock |
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:
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:
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:
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
| Dialect | Use it for | Notes |
|---|---|---|
| PostgreSQL | Several servers (recommended) | Every operation is a single atomic statement or a short transaction. Supports lock: 'advisory' |
| MySQL 8 | Several servers | No RETURNING: counters use an upsert plus SELECT in one transaction, which needs an executor with transaction() (fromConnection provides one) |
| SQLite | Several processes on one host sharing a database file | The 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.
Related
- Store reference: every store, its table and its consistency rules
- Running multiple instances
- Rate limiting
- Runtime interceptors
- Queue across servers
Was this page helpful?