Behavior of `bal persist pull` when database schema undergoes destructive changes

Question

Goal: Understand the expected behavior of the bal persist pull command when the underlying relational database has experienced destructive changes such as dropped tables or columns after the persistence model was initially generated.
Constraint: The persistence model produced by bal persist pull is treated as regenerable output and is overwritten on each invocation, so any manual edits to the generated .bal files are lost. The current documentation does not explicitly state whether the tool should silently remove corresponding entity definitions, emit a warning, or fail when it detects that a table or column no longer exists in the database, creating uncertainty about safe recovery semantics for data that was previously persisted.

Should bal persist pull silently delete entity definitions that correspond to dropped tables or columns?
Should it emit a warning and retain the stale definitions, requiring manual cleanup?
Should it treat the mismatch as an error and halt the pull operation until the model is reconciled?

Tasadduq Burney · Answer

When bal persist pull runs, it introspects the live relational database and overwrites the entire persist directory (or the path configured in Ballerina.toml). If a table or column has been dropped since the last pull, the corresponding entity or field definition is simply omitted from the regenerated output. The command does not emit a warning, error, or halt; it completes with exit code 0, and the generated model reflects the current database schema.

Because the persistence model is treated as regenerative output, any manual edits made to .bal files within the persist directory are lost on the next invocation. The CLI does not preserve stale definitions, nor does it maintain a history of schema changes.

If a dropped table was referenced by foreign keys in other entities, those relationships are also removed from the model; no orphaned references remain in the generated output.

Safe recovery pattern

Commit the persist folder to version control before running bal persist pull.
  After the pull, run git diff persist/ to see which entity definitions were removed.
  Review the diff against an approved schema-change ticket or migration record.
  If the change is expected, proceed; if not, restore the previous version and investigate the database state.

Version and configuration assumptions
The described behavior is inferred from Ballerina 2201.x (Swan Lake) through the 2024.x series. Earlier or later releases, as well as custom templates or bal persist configuration overrides in Ballerina.toml's [persist] section, may alter output semantics.
If the database user lacks information_schema access, bal persist pull may fail or produce an incomplete model, which can masquerade as silent deletion. Verifying CLI exit code and output logs is recommended.

If your database user lacks information_schema access or you are using a custom persist template, please specify so the recovery guidance can be refined.

Behavior of `bal persist pull` when database schema undergoes destructive changes

1 answer

Safe recovery pattern

Version and configuration assumptions

Your perspective belongs here.

0 question comments