fraudtwin.postgres

Optional PostgreSQL persistence adapters.

Status: Optional

Classes

fraudtwin.postgres.PostgresPersistenceResult

Non-secret metadata recorded in a generated run manifest.

Functions

fraudtwin.postgres.database_status	Return applied migration versions without changing the database.
fraudtwin.postgres.ensure_database_ready	Fail before file emission when the operational schema is unavailable.
fraudtwin.postgres.migrate_database	Apply the packaged, ordered PostgreSQL migrations and return the version.
fraudtwin.postgres.persist_run	Persist one generated run atomically after migrations have been applied.
fraudtwin.postgres.persist_scale_records	Persist a partition-record stream without whole-run materialization.

Constants and protocols

Name	Reference
DSN_ENVIRONMENT	fraudtwin.postgres.DSN_ENVIRONMENT
SCHEMA_VERSION	fraudtwin.postgres.SCHEMA_VERSION

Detailed API

Optional PostgreSQL operational sink for generated FraudTwin runs.

The sink is intentionally kept behind a lazy psycopg import. File-mode generation therefore remains dependency-free, while an enabled PostgreSQL output receives the same observable records in one transactional write.

class fraudtwin.postgres.PostgresPersistenceResult(schema_version, row_counts, logical_fingerprint, idempotent=False)

Bases: object

Non-secret metadata recorded in a generated run manifest.

Parameters:

• schema_version (str)

• row_counts (dict[str, int])

• logical_fingerprint (str)

• idempotent (bool)

fraudtwin.postgres.database_status(dsn=None)

Return applied migration versions without changing the database.

Return type:

tuple[str, ...]

Parameters:

dsn (str | None)

fraudtwin.postgres.ensure_database_ready(dsn=None)

Fail before file emission when the operational schema is unavailable.

Return type:

None

Parameters:

dsn (str | None)

fraudtwin.postgres.migrate_database(dsn=None)

Apply the packaged, ordered PostgreSQL migrations and return the version.

Return type:

str

Parameters:

dsn (str | None)

fraudtwin.postgres.persist_scale_records(records, run_id, *, dsn=None, batch_size=2_000)

Persist a partition-record stream without whole-run materialization.

Scale rows are kept in a narrow staging table so chunks can be consumed independently by downstream jobs. The established persist_run API remains unchanged for small, typed in-memory runs.

Return type:

PostgresPersistenceResult

Parameters:

• records (Iterable[Mapping[str, Any]])

• run_id (str)

• dsn (str | None)

• batch_size (int)

fraudtwin.postgres.persist_run(entities, behavior, manifest, *, dsn=None)

Persist one generated run atomically after migrations have been applied.

Return type:

PostgresPersistenceResult

Parameters:

• entities (Any)

• behavior (Any)

• manifest (Any)

• dsn (str | None)