# installArchiving() function · @imqueue/pg-prisma

Source: https://imqueue.org/api/pg-prisma/latest/pg-prisma.installarchiving/
Published: 2026-08-01
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/pg-prisma 1.0.1 — generated reference, not hand-written

Install the row-archiving machinery: a mirror `archive` schema, its settings table, the sweep function, and — best effort — a pg\_cron schedule to run it.

**Signature:**

```typescript
export declare function installArchiving(options: InstallArchiveOptions): Promise<void>;
```

## Parameters


| Parameter | Type | Description |
| --- | --- | --- |
| options | [InstallArchiveOptions](https://imqueue.org/api/pg-prisma/latest/pg-prisma.installarchiveoptions/) | Client, naming, defaults, the tables to watch, and the schedule. |


**Returns:**

Promise<void>

Nothing; it resolves once the DDL has been applied.

## Exceptions

Error when any schema, table or column name is not a plain SQL identifier — these are interpolated into DDL, so they are validated rather than escaped.

## Remarks

Aged rows are moved out of the watched tables into same-named tables in the archive schema, which keeps the hot tables small without losing the data. Every step is idempotent, so this is safe to call on every start.

What it does, in order:

1. Creates the archive schema. 2. Creates its settings table, one row per watched table: the source schema, the watch column, the retention period in seconds, an `enabled` flag, and a hash of the config the code asked for. 3. Reconciles the supplied `models` against that table — inserting new rows, and rewriting the code-owned columns only when the hash differs. 4. Creates the `run()` sweep function. For each enabled setting it checks whether any row is older than that setting's period, and only then creates `archive.<table>` and moves the aged rows across in a single `DELETE ... RETURNING` piped into an `INSERT`. So the archive table appears when there is finally something to put in it, not at install time. 5. Tries to create the pg\_cron extension and schedule `run()`. This step is best effort: if pg\_cron is unavailable the failure is caught and scheduling is skipped without an error, which means a successful call does NOT guarantee the sweep is scheduled. `run()` is a plain function, so it can equally be called by hand or driven by any external scheduler.

The division of ownership in step 3 is the part worth understanding. While the hash is unchanged, an operator's edits to the source schema, watch column and period are preserved — the code will not clobber them on the next start. Changing any of those three in code changes the hash, and then the code's values win. The `enabled` flag is never written after the initial insert, so turning a table off in the database keeps it off regardless.

`run()` reads the settings table at call time rather than baking them in, so operator changes take effect on the next sweep without reinstalling.

## Example


```typescript
await installArchiving({
    client: prisma,
    models: [{ name: 'AuditLog', periodSeconds: 7 * 24 * 3600 }],
});
```