Bubble Data Migration Checklist: Records, Files and Access

A Bubble database export is a starting point. It does not prove that the new application has the right records, relationships or permissions. Before moving production traffic, you need evidence that customers can still do their work with the same data and the intended access.

This checklist is for founders and engineers who have already decided to rebuild a Bubble application. It focuses on validating the data move, rather than choosing a stack or estimating the whole project. The outcome is a small acceptance pack your team can inspect before approving launch.

What should your Bubble data migration prove?

It should prove that every in-scope record has a destination, relationships still resolve, values retain their meaning, files remain accessible to the right people, and changes made during migration are accounted for. A matching total row count is useful, but it cannot prove those things on its own.

Use these six checks as your launch gate:

The Bubble-to-code architecture overview explains where data migration fits in a wider rebuild. The checks below turn that planning conversation into testable acceptance criteria.

1. Define exactly what you are exporting

Record the source environment, data type, selected view, filters, fields and extraction time for every export. Bubble keeps separate Development and Live databases; confusing them can produce a clean-looking dataset that has nothing to do with your customers. Check the environment before comparing totals. See Bubble’s database editor documentation.

Bubble’s current export guide supports CSV, JSON and NDJSON. Export starts from Data → App data and the selected view; Bubble emails a download link when it is ready. Scheduled work can delay the export, so record both start and completion times. Neither establishes a transactionally consistent snapshot. If writes continue during extraction, define how changes across that window will be reconciled before treating the export as your baseline.

Create a manifest with one entry per data type: source, filter, included fields, file name, record count, extraction boundary, destination and responsible engineer. Record intentionally excluded test or archived records separately. Do not delete production data just to make reconciliation easier.

Store exports in restricted migration storage. Avoid pasting raw customer records into a shared test ticket. Use record identifiers and sanitized examples when documenting failures.

2. Keep a durable map of source IDs and relationships

Preserve the original Bubble identifier in a dedicated destination field or mapping table, even if the new database uses a different primary key. Names and email addresses are poor substitutes: either may change, and a name may not be unique. Inspect the actual export before importing it: Bubble’s database-editor documentation notes that CSV references can use configured primary fields. Verify that the extraction retains the identifiers needed to resolve each relationship; do not assume a displayed label is the source ID.

Bubble supports references to other data types and lists of references, as described in its data types and fields guide. Map each relationship deliberately. A single project owner may become a foreign key; a project’s list of participants may become a join table. Define how ordering and repeated entries are handled where the product relies on them.

Test duplicate source IDs, missing parents and references to excluded records. A required unresolved relationship should fail validation; an intentionally optional one needs a documented rule. PostgreSQL’s constraint documentation explains the uniqueness and foreign-key mechanisms an engineer can use to enforce parts of that contract.

3. Reconcile values, not just totals

Compare the exact source-ID set with the destination’s imported source-ID set. Then compare useful groups: records per customer, status and reporting period. Finally compare selected fields and business totals. Each layer catches a different failure.

An illustrative acceptance check: if a customer has 120 invoices in the agreed export, verify the same 120 source IDs, not merely 120 destination rows. Compare totals by currency and invoice status rather than mixing currencies into one number. Separate explicitly approved rounding differences from unexplained discrepancies.

Document how blank values, empty lists, zero and false are translated. Check dates around midnight and daylight-saving transitions using the application’s intended timezone. Preserve external identifiers used by integrations instead of generating substitutes without a mapping.

One Bubble-specific trap deserves a test: its export guide notes that a date interval can be exported as descriptive text, such as “2 days,” although its underlying value is milliseconds. Inspect the actual export and define the target representation before transforming it. Do not apply an ordinary timestamp parser to an interval.

The deliverable is an exceptions report: record ID, failed check, observed value, expected rule, owner and resolution. “Import completed” is not an acceptance result.

4. Treat file migration as a separate job

A file field can contain a URL rather than the file’s contents. Moving that value to a new database does not establish that you have copied the underlying document, retained its access rules or removed a dependency on the old storage.

Build a file manifest alongside the record manifest. Track the source record, source location, destination location, transfer result and verification result. Where copying files is in scope, compare file size and a content checksum when available; also open representative formats through the new application.

Test private files with at least an authorized user, an unrelated customer and a signed-out visitor. A successful download from an administrator’s session is insufficient. Bubble’s privacy documentation explains that private-file configuration involves both privacy rules and uploader settings. The replacement needs its own equivalent access behavior.

If old storage will remain temporarily, document that dependency, its owner and the conditions for removing it. Do not retire the old environment while the new app still depends on its file URLs.

5. Test permissions and user journeys together

Recreate the intended authorization model on the new backend. Copying records or hiding a button does not transfer Bubble’s server-side privacy rules. Record access decisions explicitly: who may read, edit, download, approve or administer each resource.

Use an access matrix with roles on one axis and actions on the other. Include “must be denied” cases. For a multi-customer application, verify that a user from customer A cannot retrieve customer B’s project by changing an identifier or calling the endpoint directly.

Then exercise a real business journey using migrated test data: sign in, open an existing project, edit an allowed field, retrieve its attachment and confirm the updated value appears in the relevant report. Check that protected fields stay protected throughout the flow.

Treat authentication migration as a separate acceptance item. A user record in the database does not establish that login, account recovery or session handling works. The engineer responsible for authentication should approve those flows before launch.

Our security and compliance approach describes the distinction between implementing technical controls and obtaining a compliance determination. Passing this checklist is useful engineering evidence; it is not a compliance certificate.

6. Rehearse the final sync and recovery path

Decide how writes will be handled between the first export and launch. A controlled write pause may be sufficient for one app; another may need incremental synchronization. Choose based on acceptable interruption and actual data flows, not a blanket zero-downtime promise.

If using the Data API, the extraction must handle pagination, retries and the current documented limits. Bubble’s Data API request reference describes pagination and filtering. Reading one successful response is not proof that the whole dataset was extracted.

Define how creates, updates and deletions are captured. A modified-date query alone does not account for records that have disappeared. Assign one source of truth during each stage and make repeated imports safe to rerun without creating duplicates.

Before the switch, reconcile the final dataset and record approval. After the switch, run the same critical journeys and monitor failed reads, writes and integration events. Set stop conditions in advance, such as unresolved required relationships or failed customer-isolation tests.

Recovery must also account for new writes accepted by the replacement. Changing traffic back to Bubble can strand those writes unless a reconciliation path exists. Rehearse how you recover them; do not describe rollback as a DNS change alone.

What should you ask the migration team to hand over?

Ask for a compact acceptance pack containing the export manifest, field and ID mapping, reconciliation results, file-transfer results, access tests, final-sync procedure and recovery runbook. Each unresolved exception needs a named owner and an explicit decision before launch.

Bubble to Code’s team and delivery approach combines Bubble development with custom-software engineering and includes testing critical workflows. For your project, ask which of the checks above are included in scope and who signs them off. A generic promise to “migrate all data” leaves too much room for different interpretations.