Database Migration: Build a Field Map Before Importing

Separate Identity From Presentation

Begin with the business identity of each table. A customer name is useful to a person, but names can change and two customers can share one. Preserve a stable source identifier even if the destination assigns a new internal record ID. The mapping between those identifiers becomes the reference for relationships and for investigating later discrepancies.

PostgreSQL documents unique, primary-key and foreign-key constraints as different ways of expressing relational integrity. Those concepts are useful during migration even when your interface does not expose SQL. A successful import should not silently change which customer owns an order.

Documentation: PostgreSQL: constraints and relational integrity

Write the Conversion Rule, Not Just the New Column Name

For every field, specify its original type, its destination type, whether an empty value is allowed and how conversion will work. Keep postal codes and external account numbers as identifiers when leading zeros matter. For timestamps, record the source time zone and the intended interpretation rather than accepting whatever a preview displays.

Treat a formula as behavior, not only as a displayed result. If you import a calculated total as a number, the snapshot may look correct while future edits stop recalculating it. Baserow’s Airtable import documentation explicitly identifies several calculated field types for manual recreation; that is one concrete reason to inspect the conversion path.

Documentation: Baserow: Airtable import and compatibility

Give Every Loss an Owner

Use one exception list for unsupported types, ambiguous dates, missing attachments and unmatched relationships. Record whether each issue blocks release, can be repaired in a rehearsal or is an accepted change. A field should not disappear merely because the importer does not understand it.

For example, a hypothetical sales workspace may preserve an old formula result in legacy_total while rebuilding the calculation in a new total field. That makes a temporary comparison possible without implying that the archived result is still live business logic.

1. List every source table and field, including hidden but operationally important fields.
2. Assign an explicit destination or an intentional exclusion with a reason.
3. Write the conversion and error-handling rule.
4. Run the rule on ordinary, empty and unusual example values.
5. Get the workflow owner to accept every remaining exception before the real move.

Freeze the Contract for a Rehearsal

Version the field map alongside the source snapshot. If the schema changes during testing, record which rows and conversions must be repeated. Otherwise a clean validation report may describe yesterday’s layout while the production source now has another required field.

Keep the contract small enough to inspect. You do not need an enterprise data catalogue to move a small workspace, but you do need an answer for every field that affects the workflow. The next task is validating the converted records against this contract.

A Hypothetical Customer and Order Field Contract

This is an illustrative worksheet to adapt to your own evaluation. It is not a measured product test or a claim about results in your installation.

Accept the field map only when every essential value has a defined meaning and a checkable conversion. A blank destination is a decision to resolve, not an implicit success.