Install tracevault and pg, start with bootstrap.ensureSchema, or apply SQL migrations 001–003 manually.

Package

Tracevault has zero runtime dependencies beyond pg. This site documents v1.0.1 on npm.

terminal

npm install tracevault pg

Quick start (default bootstrap)

By default, startTracevault runs idempotent DDL for every physical table listed in scopes — the same shape as generateInitSql. Set bootstrap: { ensureSchema: false } when your migration pipeline owns the schema.

bootstrap.ts

import { startTracevault } from "tracevault"

const audit = await startTracevault({
  driver: "postgres",
  connectionString: process.env.DATABASE_URL_WRITE!,
  readConnectionString: process.env.DATABASE_URL_READ,
  defaultScope: "default",
  scopes: {
    default: { tableName: "audit_logs" },
    users: { tableName: "audit_user_events" },
  },
  bootstrap: { ensureSchema: true },
  maskFields: ["password", "token", "pin"],
  defaultMode: "sync",
  environment: process.env.NODE_ENV,
})

// Write URL: INSERT (+ DDL when ensureSchema). Read URL: SELECT-only role recommended.

Use readConnectionString with a PostgreSQL role that has only SELECT on audit tables. The write URL should carry INSERT (and DDL when ensureSchema is enabled).

Manual migrations

Shipped SQL under node_modules/tracevault/sql/: 001 creates the table; 002 adds generated outcome and error_code; 003 adds generated severity.

terminal

# Optional — when bootstrap.ensureSchema is false:
psql "$DATABASE_URL" -f node_modules/tracevault/sql/001_init_audit_logs.sql
psql "$DATABASE_URL" -f node_modules/tracevault/sql/002_audit_logs_outcome_error_code.sql
psql "$DATABASE_URL" -f node_modules/tracevault/sql/003_audit_logs_severity.sql

generateInitSql (operators / CI)

Returns combined 001 + 002 + 003 DDL for a table name. Validates the name, uses IF NOT EXISTS, and never executes.

ddl.ts

import { generateInitSql } from "tracevault"

// Same DDL startTracevault runs per table. Does not execute.
const ddl = generateInitSql("audit_user_events")
console.log(ddl)

terminal

node -e 'console.log(require("tracevault").generateInitSql("audit_user_events"))' \
  | psql "$DATABASE_URL"

Configure scopes and emits on

Configure scopes and emits on Writing. List events with Query.