Quick answer: During reconciliation every table gets one of four statuses: missing, drift, matched, or extra. Missing means the model expects a table the database does not have, drift means it exists but differs, matched means it agrees, and extra means the database has a table the model does not. The status names the table-level state before any migration is proposed.
Why a table status matters
A migration plan that does not first name the table state is hard to trust. A table that already matches should not be rebuilt, a table that differs needs a precise diff rather than a blind replace, and an extra table might be intentional or forgotten. The status settles those questions at the table level before the field-level work.
The four labels keep the comparison readable and prevent a uniform change from touching tables that were already correct.
The four statuses
| Status | Meaning | Typical response |
|---|---|---|
| Missing | The model expects it, the database lacks it | Add it in the plan |
| Drift | It exists but the fields differ | Reconcile the diff |
| Matched | It exists and agrees | Leave it alone |
| Extra | The database has it, the model does not | Confirm its purpose |
Matched is the stable case, and it is the one the plan should not touch, so a forward-only migration can stay additive and narrow.
How the status is used
- Read the live tables in the Observed layer.
- Compare each against the derived model in the Modeled layer.
- Assign the missing, drift, matched, or extra label.
- Read the field diffs for the drift tables.
- Propose changes only for the tables that need them.
The drift label is where the field diffs matter, because the table exists but one or more fields do not match. The extra label is the opposite direction, and it should not be treated as a reason to delete, because the table may hold data the model simply does not describe.
Consider a table that holds audit events. The model derived from the API does not describe it, so the table is labeled extra rather than dropped, and the team confirms it is written by a separate logging process the API does not expose. Next to it, a table the model expects for preferences is missing, and a third table that holds users drifts because one field changed type. The statuses keep these three cases separate: the extra table stays, the missing table enters the additive plan, and the drift table gets a field diff rather than a rebuild. A single label would blur all three, and reading the status first keeps the migration from touching a table that was already correct or deleting one that sits outside the API.
Honest reading
A status is a comparison result, not a value judgment. An extra table is not automatically dead code, and a missing table is not automatically required, because the model is derived from the API and may not cover every storage concern. Confirm the intent before acting on either.
When business logic cannot be inferred unambiguously, the result raises an open question rather than forcing a label that hides the uncertainty. The ER diagram reflects the node state against this reconciliation, and the generated SQL is never auto-executed.
Powerduck keeps the table status and the field diffs together so the reviewer sees both the state and the reason.
Frequently asked questions
Does extra mean I should delete the table? No. It means the model does not describe it, and the table may be intentional, so confirm its purpose first.
What does drift cover? The table exists but one or more fields differ, and the field diffs name the exact mismatch.
Should matched tables be rebuilt? No. A forward-only, additive plan leaves the matched tables alone and changes only what needs it.
The bottom line
The four statuses make the table-level comparison explicit: missing, drift, matched, and extra each answer a different question about whether the table exists and agrees. Use the field diffs for drift, leave matched tables alone, and confirm the intent behind missing and extra rather than treating them as automatic actions. The labels are comparison evidence, not a decision to delete, and the plan still never executes itself. Read more in the API data model guide.
