Reconciler

The Reconciler is the ONLY class allowed to issue DDL (Data Definition Language) on your record tables. When you add, modify, or remove a field from an entity, the Reconciler translates that into safe SQL.

What the Reconciler does

Detects drift — compares the entity definition (what you want) against the actual database table (what exists)
Generates a plan — a sequence of SQL operations to bring the table in sync
Applies the plan — executes the operations, refusing unsafe changes unless you force them

Plan operations

Operation	When	Safety
CREATE TABLE	New entity	Safe
ADD COLUMN	New field added	Safe
MODIFY COLUMN	Field type changed	Safe if compatible, unsafe if data loss possible
DROP COLUMN	Field removed	Safe only if 0 non-null rows exist

Safety levels

Level	Description	Requires force?
`safe`	No data can be lost. Auto-applied.	No
`caution`	Possible data truncation (e.g., VARCHAR(255) → VARCHAR(100))	Yes
`destructive`	Data WILL be lost (DROP COLUMN with data, incompatible type change)	Yes

Dry run

Always preview changes before applying:

POST /pfw/v1/meta/entities/{slug}/dry-run-reconcile

Returns the full plan with operations, safety levels, and warnings without executing anything.

The `force` parameter

When creating or modifying fields, pass force=true to auto-apply the reconcile. Without it, the field change is saved to the entity definition but the table is not updated until you manually reconcile.

Handling destructive changes

If you need to remove a field with existing data:

Export the data you want to keep
Remove the field with force=true
The column is dropped and data is permanently deleted

Force-applying destructive changes is irreversible.
Always do a dry run first and back up your database.