Threadline.Capture.AuditTransaction (Threadline v1.0.0)

Copy Markdown View Source

An AuditTransaction groups row changes from one database transaction; it is not a request or an action.

An AuditTransaction groups every row mutation that occurred within a single PostgreSQL transaction. Records are created automatically by the capture triggers installed by mix threadline.gen.triggers — application code does not insert them directly.

Key fields

  • :txid — the PostgreSQL transaction ID, used by the trigger to group concurrent changes safely under PgBouncer transaction-mode pooling.
  • :occurred_at — timestamp when the transaction committed (microsecond precision).
  • :actor_ref — who performed the writes. Populated from the threadline.actor_ref GUC when it is set inside the same database transaction as the audited writes (see Threadline.Plug for the bridge pattern).
  • :action_id — optional FK to Threadline.Semantics.AuditAction. Set when you call Threadline.record_action/2 and link semantic intent to captured rows.
  • :source — free-form string identifying the application subsystem, for example "web" or "oban".

Stable 1.x fields

The stable struct fields for 1.x are id, txid, occurred_at, actor_ref, action_id, and source. The t() type may gain fields; this list does not make every current schema field or virtual relationship a promise.

Relationships

  • has_many :changes, Threadline.Capture.AuditChange — the row mutations captured in this transaction.
  • :action_id — optional foreign key to an audit_actions row. The capture schema does not declare an Ecto association to Threadline.Semantics.AuditAction (capture must not own semantics-layer concerns). The virtual :action field is filled by Threadline's read functions (Threadline.transaction_context/2, Threadline.incident_bundle/2, and the other investigation helpers) via a hidden batched hydrate step — it is nil until one of those functions hydrates it, never an Ecto association.

Setup

Run mix threadline.install to generate the migration that creates this table, then mix threadline.gen.triggers to register capture triggers on your application tables. See guides/domain-reference.md for the full domain model.

Summary

Types

t()

A database transaction that groups captured row changes.

Types

t()

@type t() :: %Threadline.Capture.AuditTransaction{
  __meta__: Ecto.Schema.Metadata.t(),
  action: struct() | nil,
  action_id: Ecto.UUID.t() | nil,
  actor_ref: Threadline.Semantics.ActorRef.t() | nil,
  changes:
    [Threadline.Capture.AuditChange.t()] | Ecto.Association.NotLoaded.t(),
  id: Ecto.UUID.t() | nil,
  meta: Threadline.json_map() | nil,
  occurred_at: DateTime.t(),
  source: String.t() | nil,
  txid: integer()
}

A database transaction that groups captured row changes.

The virtual :action is a hydrated Threadline.Semantics.AuditAction; nil until hydrated.