Core

audit.New(db, config) → (Auditor, error)

Creates an Auditor backed by database/sql. The caller supplies an open *sql.DB — Go Audit never opens its own connection.

auditor, err := audit.New(sqlDB, audit.Config{
    Dialect: audit.PostgreSQL,
    UserFunc: userFromContext,
    DataAudit: audit.DataAuditConfig{Enabled: true},
})

Returns (Auditor, error). The returned Auditor is an interface value (see below). No DB I/O happens until you call AutoMigrate or the first CRUD through an ORM adapter.

Validation errors returned by New:

• DataAudit.Enabled && UserFunc == nil — UserFunc required when data audit is enabled.
• Neither DataAudit.Enabled nor APIAudit.Enabled is true.
• DataAudit.Table or APIAudit.Table is not a valid SQL identifier.

audit.NewWithStore(store, dialect, config) → (Auditor, error)

Alternative constructor that takes any Store implementation. Useful for tests (with audit.NewMemoryStore()) or for routing audit writes through a custom persistence layer.

audit.Config

type Config struct {
    Dialect   DialectType
    UserFunc  UserFunc
    DataAudit DataAuditConfig
    APIAudit  APIAuditConfig
    Logger    func(format string, args ...any)
}

audit.DataAuditConfig

type DataAuditConfig struct {
    Table           string
    Enabled         bool
    ExcludeFields   []string
    ExcludeEntities []string
    SkipOldValues   bool
    OnError         ErrorMode
}

audit.APIAuditConfig

type APIAuditConfig struct {
    Table            string
    Enabled          bool
    RedactHeaders    []string
    RedactBodyFields []string
    MaxBodySize      int
    OnError          ErrorMode
}

audit.ErrorMode

const (
    ErrorFailLoud   ErrorMode = iota // auditor returns store errors; each adapter surfaces them as far as its ORM allows (default)
    ErrorFailSilent                  // logs via Config.Logger and returns nil
)

Under ErrorFailLoud the auditor returns the store error from RecordDataChange / RecordAPICall. How far it travels depends on the adapter:

In every adapter the ORM write has already been applied when the audit store fails — fail-loud reports, it does not roll back on its own. See the per-adapter pages for details: GORM, Bun, Ent.

Under ErrorFailSilent the auditor logs via Config.Logger and returns nil in every adapter. Use it when the application write must not be coupled to audit availability (e.g. the audit DB is allowed to be briefly unavailable during maintenance).

audit.UserFunc

type UserFunc func(ctx context.Context) (userID string, userType string)

Called on every audit write. Typical implementation pulls a user out of the request context set by middleware.

func userFromContext(ctx context.Context) (string, string) {
    if u, ok := ctx.Value(userCtxKey).(*User); ok {
        return u.ID, u.Role
    }
    return "system", "system"
}

Required when DataAudit.Enabled == true.

Constants

const (
    ActionCreate     = "create"
    ActionUpdate     = "update"
    ActionDelete     = "delete"
    ActionSoftDelete = "soft_delete"
    ActionRestore    = "restore"
)

const (
    PostgreSQL DialectType = "postgres"
    MySQL      DialectType = "mysql"
    SQLite     DialectType = "sqlite"
)

Auditor Interface

type Auditor interface {
    RecordDataChange(ctx context.Context, entry DataEntry) error
    API() APIAuditor
    Query(ctx context.Context, filter DataFilter) ([]AuditLog, error)
    QueryByTransaction(ctx context.Context, txID string) (*TransactionLog, error)
    AutoMigrate(ctx context.Context) error
    Purge(ctx context.Context, before time.Time) (PurgeResult, error)
    Snapshot(ctx context.Context, entityType, entityID string, at time.Time) (map[string]any, error)
    Restore(ctx context.Context, entityType, entityID string, at time.Time) (*RestoreResult, error)
    Config() Config
}

• RecordDataChange — manual entry point used by ORM adapters and callers writing via raw SQL. Applies diff, exclusion, and context transaction ID resolution.
• API() — returns the APIAuditor for third-party call logging.
• Query / QueryByTransaction — read paths (see Query & Filters).
• AutoMigrate(ctx) — creates audit tables and indexes. Safe to call repeatedly; uses IF NOT EXISTS everywhere.
• Purge(ctx, before) — deletes rows older than before from both tables (if enabled). Returns per-table counts.
• Snapshot / Restore — reconstruct entity state at a past time by replaying audit history (see Query & Filters).
• Config() — returns the configuration the Auditor was created with.

Store Helpers

audit.NewSQLStore(db *sql.DB, d Dialect) Store
audit.NewMemoryStore() Store

NewSQLStore backs the default path. NewMemoryStore is intended for tests.