drizzle-audit

library0.1.12jsnpmunverified

Configurable audit logging for Drizzle ORM (v0.1.12). Provides automatic CRUD audit interception, custom action logging, scoped tracking with duration, and field-level transforms (redact, mask, hash, omit). Supports PostgreSQL, SQLite, and MySQL with pluggable storage (same DB, external DB, webhook, MongoDB). Integrates with frameworks (Hono, Elysia, Express, etc.) and workers (BullMQ, Temporal). Features AsyncLocalStorage context propagation, transaction awareness, and skip-on-noop. Zero-config start, progressive enhancement, and strict TypeScript. Active development with weekly releases.

database

npm install drizzle-audit

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DRIZZLE-AUDIT

drizzle-audit

databasejavascriptv0.1.12

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

withDrizzleAudit

✓ import { withDrizzleAudit } from 'drizzle-audit'

✗ const withDrizzleAudit = require('drizzle-audit')

ESM-only package; CommonJS require() will fail. Use dynamic import if needed: import('drizzle-audit').

drizzleTableStorage

✓ import { drizzleTableStorage } from 'drizzle-audit/storage/drizzle'

✗ import { drizzleTableStorage } from 'drizzle-audit'

Storage implementations are imported from subpaths: 'drizzle-audit/storage/drizzle', 'drizzle-audit/storage/http', etc.

pgAuditTable

✓ import { pgAuditTable } from 'drizzle-audit/pg'

✗ import { pgAuditTable } from 'drizzle-audit'

Dialect-specific table builders: 'drizzle-audit/pg', 'drizzle-audit/sqlite', 'drizzle-audit/mysql'.

db.$audit

✓ const db = withDrizzleAudit(rawDb, config); await db.$audit.action(...)

✗ const db = drizzle(client); await db.$audit.action(...)

The $audit namespace is only available on the wrapped db returned by withDrizzleAudit, not on the raw drizzle instance.

types

✓ import type { AuditEntry, AuditStorage, AuditConfig } from 'drizzle-audit'

Type imports are available for custom storage implementations and configuration.

Wrap a PostgreSQL Drizzle instance with audit logging using drizzleTableStorage, enabling automatic CRUD audit and custom actions.

import { drizzle } from 'drizzle-orm/postgres-js'; import { withDrizzleAudit } from 'drizzle-audit'; import { drizzleTableStorage } from 'drizzle-audit/storage/drizzle'; import { pgAuditTable } from 'drizzle-audit/pg'; import postgres from 'postgres'; const client = postgres(process.env.DATABASE_URL ?? ''); const rawDb = drizzle(client); const auditLog = pgAuditTable(); const db = withDrizzleAudit(rawDb, { storage: drizzleTableStorage(auditLog, { db: rawDb }), auditTable: auditLog, context: { userId: 'system' }, }); await db.insert(users).values({ name: 'Alice' }).returning(); await db.$audit.action({ action: 'EXPORT', tableName: 'users', metadata: { reason: 'backup' } });

Debug

Known issues

breakingAutomatic audit interception requires .returning() on insert/update/delete calls. Without .returning(), no audit entry is created.

fix

Add .returning() to all DML operations you want audited. For MySQL (no RETURNING), use db.$audit.action() manually.

affects: >=0.1.0

breakingMySQL does not support RETURNING. Drizzle-audit cannot intercept changes for MySQL automatically.

fix

Use manual audit entries via db.$audit.action() after each DML operation. See examples/express-mysql-sqlite for a pattern.

affects: >=0.1.0

deprecatedThe context option in withDrizzleAudit config is deprecated in favor of AsyncLocalStorage-based context propagation.

fix

Use withAuditContext(context) helper or framework middlewares to set context per request/worker.

affects: >=0.1.0

gotchaThe audit table itself must be excluded from auditing by passing it in the auditTable config option, otherwise infinite loops occur.

fix

Always include `auditTable: auditLog` in the config passed to withDrizzleAudit.

affects: >=0.1.0

gotchaTransactions are tracked as a single audit entry for the entire transaction. You cannot get per-statement entries inside a transaction.

fix

If per-statement auditing is required inside transactions, use manual db.$audit.action() calls instead of relying on automatic interception.

affects: >=0.1.0

Errors

Common errors & fixes

Cannot find module 'drizzle-audit' or its corresponding type declarations.

Missing peer dependency drizzle-orm or incompatible version.

fix

Ensure drizzle-orm >= 0.33.0 is installed: npm install drizzle-orm@latest

TypeError: db.$audit is undefined

Using the raw drizzle instance instead of the wrapped instance returned by withDrizzleAudit.

fix

Wrap your drizzle instance: const db = withDrizzleAudit(rawDb, config);

Error: auditTable is not defined in config

Missing auditTable option in withDrizzleAudit config, or the table is not excluded from auditing.

fix

Add `auditTable: myAuditTable` to the config object.

Cannot find module 'drizzle-audit/storage/drizzle'

Using a bundler that doesn't support subpath exports or using CommonJS require.

fix

Use ESM imports (import) and ensure your bundler supports Node.js subpath exports, or use a full path like './node_modules/drizzle-audit/storage/drizzle.js'.

Upgrade

Version history

0.1.12latest on npm

Audit

Dependencies

drizzle-ormrequiredPeer dependency: >= 0.33.0 < 2. Required for database operations and type integration.

typescriptoptionalPeer dependency: ^5. Required for type safety and TypeScript features.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/xantiagoma/drizzle-audit ↗

packagedrizzle-audit ↗

homepagehttps://github.com/xantiagoma/drizzle-audit#readme ↗