TitaniumGuard
Ledger Extension Reference | Docs | TitaniumGuard

Ledger Extension Reference

Ledger Extension Reference

This page documents the PostgreSQL extension surface currently defined by tg_ledger--0.1.0.sql and exercised by the repository smoke tests.

Core lifecycle

ledger_status()

ledger_status() RETURNS bool

Returns true when tg_ledger is installed in the current database.

ledger_version()

ledger_version() RETURNS text

Returns the installed extension version.

ledger_enable(table_identifier text, backfill boolean default false, order_by text default null)

ledger_enable(table_identifier text, backfill boolean default false, order_by text default null) RETURNS bool

Behavior:

  • Adds ledger_seq, ledger_ts, row_hash, and prev_hash if they are missing
  • Installs the insert trigger and update/delete rejection trigger
  • Registers ledger metadata for the table
  • Supports deterministic backfill for existing rows when backfill = true
  • Creates schema-history metadata for the enabled table

ledger_disable(table_identifier text)

ledger_disable(table_identifier text) RETURNS bool

Behavior:

  • Removes extension-managed triggers
  • Drops the Ledger-managed columns
  • Removes the table from extension metadata

Verification and inspection

ledger_verify_table(table_identifier text)

ledger_verify_table(table_identifier text)
RETURNS TABLE(
  ok boolean,
  checked_rows bigint,
  first_bad_seq bigint,
  error_code text,
  error_detail text
)

Runs full-table structural and hash-chain verification.

ledger_verify_range(table_identifier text, start_seq bigint, end_seq bigint)

ledger_verify_range(table_identifier text, start_seq bigint, end_seq bigint)
RETURNS TABLE(
  ok boolean,
  checked_rows bigint,
  first_bad_seq bigint,
  error_code text,
  error_detail text
)

Runs the same verification logic over a bounded sequence range.

ledger_verify_from_checkpoint(table_identifier text, checkpoint_to_seq bigint)

ledger_verify_from_checkpoint(table_identifier text, checkpoint_to_seq bigint)
RETURNS TABLE(
  ok boolean,
  checked_rows bigint,
  first_bad_seq bigint,
  error_code text,
  error_detail text
)

Verifies from a stored checkpoint forward.

ledger_verify_progress(job_id text)

ledger_verify_progress(job_id text)
RETURNS TABLE(
  job_id text,
  status text,
  checked_rows bigint,
  last_seq bigint,
  detail text
)

Current behavior:

  • Returns a single row with status = 'UNAVAILABLE'
  • Exists as a placeholder for background or resumable verification jobs

ledger_table_head(table_identifier text)

ledger_table_head(table_identifier text)
RETURNS TABLE(
  row_count bigint,
  max_ledger_seq bigint,
  head_hash bytea,
  last_verified_seq bigint,
  last_verified_hash bytea,
  schema_hash bytea
)

Returns the current table head summary.

ledger_table_heads

The extension also creates a ledger_table_heads view with:

  • table_oid
  • table_name
  • max_seq
  • head_hash
  • last_checkpoint_seq
  • last_checkpoint_hash
  • row_count
  • schema_hash

ledger_debug_row(table_identifier text, seq bigint)

ledger_debug_row(table_identifier text, seq bigint)
RETURNS TABLE(
  canonical_payload text,
  prev_hash bytea,
  stored_row_hash bytea,
  recomputed_row_hash bytea,
  expected_prev_hash bytea,
  schema_hash bytea
)

Returns row-level hash-debugging data for one ledgered row.

ledger_export_proof(table_identifier text, start_seq bigint, end_seq bigint)

ledger_export_proof(table_identifier text, start_seq bigint, end_seq bigint)
RETURNS TABLE(
  proof_version bigint,
  table_oid bigint,
  start_seq bigint,
  end_seq bigint,
  rows text,
  prior_hash bytea,
  resulting_hash bytea,
  schema_hash bytea,
  checkpoint_hash bytea
)

Exports a proof bundle for a contiguous sequence range.

Checkpoints and policies

ledger_register_checkpoint_policy(table_identifier text, frequency bigint)

ledger_register_checkpoint_policy(table_identifier text, frequency bigint) RETURNS bool

Upserts checkpoint cadence for a ledger-enabled table.

ledger_unregister_checkpoint_policy(table_identifier text)

ledger_unregister_checkpoint_policy(table_identifier text) RETURNS bool

Disables checkpoint policy enforcement for a ledger-enabled table.

ledger_list_checkpoints(table_identifier text)

ledger_list_checkpoints(table_identifier text)
RETURNS TABLE(
  from_seq bigint,
  to_seq bigint,
  head_hash bytea,
  checkpoint_hash bytea,
  row_count bigint,
  schema_hash bytea,
  checkpoint_kind text,
  created_at timestamptz
)

Lists checkpoints recorded for the table.

ledger_create_checkpoint(table_identifier text)

ledger_create_checkpoint(table_identifier text)
RETURNS TABLE(
  from_seq bigint,
  to_seq bigint,
  head_hash bytea,
  checkpoint_hash bytea,
  row_count bigint,
  schema_hash bytea,
  checkpoint_kind text,
  created_at timestamptz
)

Creates or returns the current checkpoint row at the table head.

ledger_set_policy(table_identifier text, checkpoint_frequency bigint, external_anchor_required boolean, ddl_lockdown boolean, signature_required boolean, retention_policy text)

ledger_set_policy(
  table_identifier text,
  checkpoint_frequency bigint,
  external_anchor_required boolean,
  ddl_lockdown boolean,
  signature_required boolean,
  retention_policy text
)
RETURNS TABLE(
  table_oid bigint,
  checkpoint_frequency bigint,
  external_anchor_required boolean,
  ddl_lockdown boolean,
  signature_required boolean,
  retention_policy text,
  created_at timestamptz,
  updated_at timestamptz
)

Upserts table-level policy state.

ledger_get_policy(table_identifier text)

ledger_get_policy(table_identifier text)
RETURNS TABLE(
  table_oid bigint,
  checkpoint_frequency bigint,
  external_anchor_required boolean,
  ddl_lockdown boolean,
  signature_required boolean,
  retention_policy text,
  created_at timestamptz,
  updated_at timestamptz
)

Returns current policy state for the table.

Schema tracking

ledger_compute_schema_fingerprint(table_identifier text)

ledger_compute_schema_fingerprint(table_identifier text)
RETURNS TABLE(
  table_oid bigint,
  schema_hash bytea,
  schema_definition text
)

Computes the canonical schema fingerprint for the current table definition.

ledger_get_active_schema(table_identifier text)

ledger_get_active_schema(table_identifier text)
RETURNS TABLE(
  table_oid bigint,
  schema_hash bytea,
  schema_definition text,
  effective_from_seq bigint,
  recorded_at timestamptz,
  change_kind text,
  ddl_command_tag text
)

Returns the latest schema-history row.

ledger_list_schema_history(table_identifier text)

ledger_list_schema_history(table_identifier text)
RETURNS TABLE(
  table_oid bigint,
  schema_hash bytea,
  schema_definition text,
  effective_from_seq bigint,
  recorded_at timestamptz,
  change_kind text,
  ddl_command_tag text
)

Lists schema-history entries for the table.

ledger_get_schema_for_seq(table_identifier text, seq bigint)

ledger_get_schema_for_seq(table_identifier text, seq bigint)
RETURNS TABLE(
  table_oid bigint,
  schema_hash bytea,
  schema_definition text,
  effective_from_seq bigint,
  recorded_at timestamptz,
  change_kind text,
  ddl_command_tag text
)

Returns the schema-history row that applies to the requested sequence number.

External anchoring

ledger_export_anchor_payload(table_identifier text, checkpoint_to_seq bigint)

ledger_export_anchor_payload(table_identifier text, checkpoint_to_seq bigint)
RETURNS TABLE(
  ok boolean,
  anchor_payload text,
  anchor_hash bytea,
  checkpoint_hash bytea,
  table_oid bigint,
  from_seq bigint,
  to_seq bigint,
  created_at timestamptz,
  error_code text,
  error_detail text
)

Exports the serialized checkpoint payload used for external anchoring.

ledger_export_anchor_signing_payload(table_identifier text, checkpoint_to_seq bigint)

ledger_export_anchor_signing_payload(table_identifier text, checkpoint_to_seq bigint) RETURNS bytea

Returns the signing digest for a checkpoint anchor payload.

ledger_verify_anchor_payload(table_identifier text, checkpoint_to_seq bigint, expected_anchor_hash bytea)

ledger_verify_anchor_payload(table_identifier text, checkpoint_to_seq bigint, expected_anchor_hash bytea)
RETURNS TABLE(
  ok boolean,
  error_code text,
  error_detail text,
  computed_anchor_hash bytea,
  expected_anchor_hash bytea
)

Recomputes and checks the expected anchor hash.

ledger_register_anchor(table_identifier text, checkpoint_to_seq bigint, anchor_target text, external_reference text, anchor_status text)

ledger_register_anchor(
  table_identifier text,
  checkpoint_to_seq bigint,
  anchor_target text,
  external_reference text,
  anchor_status text
)
RETURNS TABLE(
  anchor_id bigint,
  table_oid bigint,
  checkpoint_to_seq bigint,
  checkpoint_hash bytea,
  anchor_payload text,
  anchor_hash bytea,
  anchor_target text,
  anchor_status text,
  external_reference text,
  signature_key_id text,
  signature bytea,
  created_at timestamptz,
  updated_at timestamptz,
  last_error text
)

Creates an external-anchor record for a checkpoint.

ledger_update_anchor_status(anchor_id bigint, anchor_status text, external_reference text, last_error text)

ledger_update_anchor_status(anchor_id bigint, anchor_status text, external_reference text, last_error text)
RETURNS TABLE(
  anchor_id bigint,
  table_oid bigint,
  checkpoint_to_seq bigint,
  checkpoint_hash bytea,
  anchor_payload text,
  anchor_hash bytea,
  anchor_target text,
  anchor_status text,
  external_reference text,
  signature_key_id text,
  signature bytea,
  created_at timestamptz,
  updated_at timestamptz,
  last_error text
)

Updates anchor publication state.

ledger_attach_anchor_signature(anchor_id bigint, signature_key_id text, signature bytea)

ledger_attach_anchor_signature(anchor_id bigint, signature_key_id text, signature bytea)
RETURNS TABLE(
  anchor_id bigint,
  table_oid bigint,
  checkpoint_to_seq bigint,
  checkpoint_hash bytea,
  anchor_payload text,
  anchor_hash bytea,
  anchor_target text,
  anchor_status text,
  external_reference text,
  signature_key_id text,
  signature bytea,
  created_at timestamptz,
  updated_at timestamptz,
  last_error text
)

Stores signature material for an anchor record.

ledger_list_external_anchors(table_identifier text)

ledger_list_external_anchors(table_identifier text)
RETURNS TABLE(
  anchor_id bigint,
  table_oid bigint,
  checkpoint_to_seq bigint,
  checkpoint_hash bytea,
  anchor_payload text,
  anchor_hash bytea,
  anchor_target text,
  anchor_status text,
  external_reference text,
  signature_key_id text,
  signature bytea,
  created_at timestamptz,
  updated_at timestamptz,
  last_error text
)

Lists external-anchor rows for a ledger-enabled table.

Hardening and guards

ledger_check_hardening(table_identifier text)

ledger_check_hardening(table_identifier text)
RETURNS TABLE(
  check_name text,
  ok boolean,
  detail text
)

Reports whether required hardening controls remain intact.

Internal trigger and event-trigger functions

These functions are created so PostgreSQL can execute extension-managed triggers:

  • ledger_before_insert() RETURNS trigger
  • ledger_reject_update_delete() RETURNS trigger
  • ledger_ddl_guard() RETURNS event_trigger

Operators should treat them as internal implementation hooks rather than a direct API.

Guardrails

When Ledger is enabled on a table:

  • Inserts receive monotonically increasing ledger_seq values
  • The hash chain is maintained with prev_hash and row_hash
  • Automatic checkpoints can be emitted when checkpoint policy frequency is reached
  • Schema transitions are recorded into ledger_schema_history
  • Updates and deletes are rejected
  • The DDL event trigger blocks destructive changes to ledger-enabled tables