# What steps are involved in migrating existing data into Bubble.io’s database sys

- Tool: Bubble
- Difficulty: Intermediate
- Time required: 25-30 min
- Compatibility: All Bubble plans
- Last updated: March 2026

## TL;DR

Migrating data into Bubble requires mapping your source schema to Bubble Data Types, cleaning and formatting data for CSV import, handling relationships through Unique IDs, validating records post-import, and having a rollback plan. This tutorial walks through each phase of a structured data migration from planning to verification.

## Overview: Migrating Data to Bubble's Database

Moving data from another platform (spreadsheets, SQL databases, other no-code tools) into Bubble requires careful planning. This tutorial covers the complete migration process: analyzing your source data, creating matching Data Types in Bubble, preparing CSV files with correct formatting, importing in the right order to preserve relationships, validating that all records transferred correctly, and having a rollback plan if something goes wrong.

## Before you start

- A Bubble app with the target Data Types already created
- Source data exported as CSV files or accessible via API
- A spreadsheet application for data cleaning (Google Sheets or Excel)
- Understanding of your source data relationships (which tables link to which)

## Step-by-step guide

### 1. Analyze and map your source schema to Bubble Data Types

Start by documenting your source database: list every table, its columns, data types, and relationships. Then create the equivalent structure in Bubble's Data tab. Map each source table to a Bubble Data Type, each column to a field, and each data type to Bubble's field types (text, number, date, yes/no, file, image, or another Data Type for relationships). Pay special attention to relationships — Bubble uses Unique IDs to link records. If your source uses foreign keys (like user_id = 42), you will need to map these to Bubble Unique IDs during import.

> Pro tip: Create all Data Types and fields in Bubble BEFORE importing any data — Bubble needs the structure in place to map CSV columns.

**Expected result:** A mapping document showing source table → Bubble Data Type, source column → Bubble field, with relationship handling noted.

### 2. Clean and format your data for Bubble CSV import

Export your source data as CSV files (one per table/Data Type). Open each file in a spreadsheet and clean it: remove empty rows, standardize date formats to MM/DD/YYYY or YYYY-MM-DD (Bubble accepts both), ensure yes/no fields use 'yes' or 'no' (not TRUE/FALSE or 1/0), clean up text fields that might contain commas or newlines that break CSV parsing (wrap them in quotes), and remove any columns that do not have a matching Bubble field. Save each file as UTF-8 CSV to ensure special characters import correctly.

**Expected result:** Clean CSV files ready for import with correct date formats, boolean values, and UTF-8 encoding.

### 3. Import parent Data Types before child Data Types

Import order matters because of relationships. Start with Data Types that have no dependencies (parent tables like User, Category, Country). In Bubble, go to Data tab → App data → select the Data Type → click Upload. Select your CSV file and map each column to the corresponding Bubble field. After import, Bubble assigns Unique IDs to every new record. Export the imported data immediately to get a CSV with the Unique IDs — you will need these to link child records. Repeat for each independent Data Type before moving to dependent ones.

**Expected result:** Parent Data Types imported with Bubble Unique IDs assigned, ready for child record linking.

### 4. Link related records using Unique IDs

For child Data Types that reference parent records (like an Order that links to a Customer), you need to replace your source foreign keys with Bubble Unique IDs. Open the exported parent CSV (with Unique IDs from step 3). In your child CSV, use a spreadsheet VLOOKUP or INDEX/MATCH formula to replace each source foreign key with the corresponding Bubble Unique ID. For example, replace customer_id '42' with the Bubble Unique ID '1609458792345x123456789'. Save the updated child CSV and import it into Bubble, mapping the relationship column to the correct Data Type field.

> Pro tip: If your source data uses email as a unique identifier, you can use Bubble's 'Search for existing data' option during import to match by email instead of manually replacing IDs.

**Expected result:** Child records imported with correct Bubble Unique ID references linking them to parent records.

### 5. Validate data integrity after import

After all imports are complete, verify the migration. Check record counts: the number of records in each Bubble Data Type should match your source. Spot-check individual records: open 10-20 random records in Bubble's App data viewer and compare field values to the source. Test relationships: in the App data viewer, click linked fields to verify they point to the correct parent records. Check for empty fields that should have values, and look for encoding issues in text fields (garbled characters indicate a UTF-8 problem). Build a simple Bubble page with a Repeating Group for each Data Type to visually verify the data looks correct.

**Expected result:** All records verified for correct counts, field values, relationships, and encoding.

### 6. Create a rollback plan and document the migration

Before considering the migration complete, ensure you have a rollback plan. Keep your original source CSV files safe. In Bubble, you can use the App data view to bulk delete records from a Data Type if you need to re-import. Document the entire migration: what was imported, in what order, which VLOOKUP formulas were used for ID mapping, any manual fixes applied, and the final record counts. This documentation is essential if you need to repeat the migration (for example, importing to a production app after testing in development).

**Expected result:** A complete migration document and rollback capability, with original source files preserved.

## Complete code example

File: `Workflow summary`

```text
DATA MIGRATION PLAN SUMMARY
============================

PHASE 1: SCHEMA MAPPING
  Source Table → Bubble Data Type:
    users → User (built-in + custom fields)
    customers → Customer
    orders → Order
    order_items → Order_Item
    products → Product
    categories → Category

  Field Type Mapping:
    varchar/text → text
    int/float → number
    datetime → date (format: MM/DD/YYYY or YYYY-MM-DD)
    boolean → yes/no (use 'yes'/'no' text)
    blob/file → file (import as URL)
    foreign_key → Data Type reference (via Unique ID)

PHASE 2: DATA CLEANING
  For each CSV:
    □ Remove empty rows
    □ Standardize dates to MM/DD/YYYY
    □ Convert booleans to yes/no
    □ Wrap text with commas in quotes
    □ Remove columns without Bubble fields
    □ Save as UTF-8 CSV

PHASE 3: IMPORT ORDER
  Round 1 (no dependencies):
    1. Category
    2. Product
    3. User/Customer
  Round 2 (has dependencies):
    4. Order (depends on Customer)
    5. Order_Item (depends on Order + Product)

  Per Data Type:
    a. Data tab → App data → [Type] → Upload
    b. Map CSV columns to Bubble fields
    c. Import
    d. Export with Unique IDs
    e. Use IDs for next round's VLOOKUP

PHASE 4: RELATIONSHIP LINKING
  In child CSV (e.g., Order):
    Column: customer_id (source) → Customer (Bubble)
    Formula: =VLOOKUP(source_id, parent_export, id_column, FALSE)
    Replace source foreign key with Bubble Unique ID
    Save and import

PHASE 5: VALIDATION
  □ Record count matches source for each Data Type
  □ Spot-check 10-20 random records per type
  □ Click relationship links to verify correct parent
  □ Check for empty fields that should have values
  □ Verify text encoding (no garbled characters)
  □ Build test page with RG to visually inspect

PHASE 6: DOCUMENTATION
  □ Original source CSVs preserved
  □ Mapping document complete
  □ Import order documented
  □ VLOOKUP formulas saved
  □ Final record counts recorded
  □ Rollback procedure: bulk delete + re-import
```

## Common mistakes

- **Importing child records before parent records** — Child records reference parent records by Unique ID — if parents are not imported yet, the relationship fields will be empty Fix: Always import in dependency order: parent Data Types first, then child Data Types after mapping Unique IDs
- **Using source foreign keys instead of Bubble Unique IDs for relationships** — Bubble does not understand your source database's ID system — it uses its own 32-character Unique IDs for record linking Fix: Export parent data after import to get Bubble Unique IDs, then use VLOOKUP to replace source IDs in child CSVs
- **Not validating data after import** — Silent data loss can occur during import — fields may be mismatched, dates may parse incorrectly, or relationships may break Fix: Always verify record counts, spot-check individual records, and test relationship links after every import

## Best practices

- Create all Bubble Data Types and fields before starting any data import
- Import in dependency order: parent tables first, child tables second
- Export imported data immediately to capture Bubble Unique IDs for relationship mapping
- Use spreadsheet VLOOKUP to convert source foreign keys to Bubble Unique IDs
- Validate record counts and spot-check records after every import batch
- Save original source CSVs and mapping documentation for rollback capability
- Test the complete migration on a development app before running it on production

## Frequently asked questions

### What file format does Bubble accept for data import?

Bubble accepts CSV files. Ensure they are saved as UTF-8 encoded CSV for proper handling of special characters.

### Can I import more than one Data Type at a time?

No. Bubble imports one Data Type at a time. Import each CSV separately through Data tab, App data, select the type, and click Upload.

### How do I handle many-to-many relationships during migration?

Create a junction Data Type in Bubble (like Order_Item linking Order and Product). Import both parent types first, then import the junction type with Unique IDs for both parents.

### What is the maximum number of records I can import?

There is no hard limit, but large imports (10,000+ records) can be slow and may time out. For large datasets, split your CSV into batches of 5,000-10,000 records and import sequentially.

### Can I undo a data import?

There is no undo button. You can bulk delete imported records from the App data view and re-import. This is why keeping your original CSVs is critical.

### Can RapidDev help with complex data migrations to Bubble?

Yes. RapidDev can plan and execute data migrations including schema mapping, relationship handling, data cleaning, validation, and rollback procedures for migrations of any complexity.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/steps-migrating-data-bubble-database-system
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/steps-migrating-data-bubble-database-system