Instalá tracevault y pg, empezá con bootstrap.ensureSchema, o aplicá migraciones SQL 001–003 manualmente.

Paquete

Tracevault no tiene dependencias runtime más allá de pg. Este sitio documenta v1.0.1 en npm.

terminal

npm install tracevault pg

Inicio rápido (bootstrap por defecto)

Por defecto, startTracevault ejecuta DDL idempotente para cada tabla física listada en scopes — la misma forma que generateInitSql. Seteá bootstrap: { ensureSchema: false } cuando tu pipeline de migraciones maneja el 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.

Usá readConnectionString con un rol PostgreSQL que solo tenga SELECT en tablas de auditoría. La URL de escritura debe tener INSERT (y DDL cuando ensureSchema está activo).

Migraciones manuales

SQL incluido en node_modules/tracevault/sql/: 001 crea la tabla; 002 agrega outcome y error_code generados; 003 agrega severity generado.

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 (operadores / CI)

Devuelve DDL combinado 001 + 002 + 003 para un nombre de tabla. Valida el nombre, usa IF NOT EXISTS, y nunca ejecuta.

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"

Configurá scopes y emits en

Configurá scopes y emits en Writing. Listá eventos con Query.