There are open-source libaries for doing schema migration, such as Flyway and Liquibase. These libaries require the developer to write migration files by hand every time a table is added or modified.
Delia takes a different approach. The set of types and fields in a Delia program make up its schema. Delia tracks the current schema in the database in a special table. Every time a Delia program is run, it compares its schema with the one in the special table. If they are equal, no schema changes are needed. If they are not equal, Delia creates a migration plan and, if the plan is low-risk (see below), executes it. The migration plan modifies tables and fields to make the database schema match the Delia program's schema. Once migration is finished, the Delia program is executed.
Thus, as long as migrations are low-risk, they are fully automatic.
A Delia program's schema consists of:
Let's look at the types of changes you can make.
Adding types is low-risk, since these have no effect on existing data in the database.
Adding optional fields is low-risk, since existing records will have a null value for the new field, which is allowed.
Adding mandatory fields is not low-risk, and migration will not be done. Mandatory fields are not allowed to be null; existing records would break this rule.
If the table has no records in it, then adding a mandatory field is allowed, and is considered low-risk.
If you remove a type from a Delia program, the migration plan includes a delete-table step. However, for the safety of your data, Delia keeps the table, and renames to __BAK. Your Delia program will not access this table but it is still in the database in case the data is needed later.
If you remove a field from a Delia type, the migration plan will include a delete-field step. However, for the safety of your data, Delia keeps the field, and renames to __BAK. Your Delia program will not access this field but it is still in the database in case the data is needed later.
If you rename a type from a Delia program, Delia may not reliably be able to detect it. A rename looks similar to a delete-table + add-table. The migration plan will include a rename-table step.
This is considered a risky step and will never be done automatically. Instead, see ..
If you rename a field in a Delia program, Delia may not reliably be able to detect it. A rename looks similar to a delete-field + add-field. The migration plan will include a rename-field step.
This is considered a risky step and will never be done automatically. Instead, see ..
If you alter a field's modifiers in a Delia program, Delia may not reliably be able to change the database schema. For example if you remove
the optional modifier, the field is now mandatory. The database field will be NOT NULL. However, the ALTER COLUMN action will fail if any
rows in the table have NULL for this field.
Similar issues occur with changing relations.
This is considered a risky step and will never be done automatically. Instead, see ..
The following changes are considered low-risk:
If the only changes that you do are low-risk, then the migration will be done automatically be Delia.
The following changes are considered risky:
If any of the changes that you have done are risky, then the migration will not be done automatically. Instead, Delia will halt with a “migration-review-needed” error. It will also write the proposed migration plan to the log.
You need to manually review the migration steps and verify that they are what you want. You need to modify any incorrect steps to make them correct.
Once you have reviewed and/or corrected the plan, use the Delia REPL to execute it.
On production servers it is important to be very careful. Use the delia config setting migration.automatic.enabled = false. This will ensure that migrations are never done automatically. Instead, Delia will halt with a “migration-review-needed” eror and you can manually review the migration plan. Then use the Delia REPL to run it.