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.
Prerequisites
- 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
Analyze and map your source schema to Bubble Data Types
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.
Clean and format your data for Bubble CSV import
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.
Import parent Data Types before child Data Types
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.
Link related records using Unique IDs
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.
Validate data integrity after import
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.
Create a rollback plan and document the migration
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 working example
1DATA MIGRATION PLAN SUMMARY2============================34PHASE 1: SCHEMA MAPPING5 Source Table → Bubble Data Type:6 users → User (built-in + custom fields)7 customers → Customer8 orders → Order9 order_items → Order_Item10 products → Product11 categories → Category1213 Field Type Mapping:14 varchar/text → text15 int/float → number16 datetime → date (format: MM/DD/YYYY or YYYY-MM-DD)17 boolean → yes/no (use 'yes'/'no' text)18 blob/file → file (import as URL)19 foreign_key → Data Type reference (via Unique ID)2021PHASE 2: DATA CLEANING22 For each CSV:23 □ Remove empty rows24 □ Standardize dates to MM/DD/YYYY25 □ Convert booleans to yes/no26 □ Wrap text with commas in quotes27 □ Remove columns without Bubble fields28 □ Save as UTF-8 CSV2930PHASE 3: IMPORT ORDER31 Round 1 (no dependencies):32 1. Category33 2. Product34 3. User/Customer35 Round 2 (has dependencies):36 4. Order (depends on Customer)37 5. Order_Item (depends on Order + Product)3839 Per Data Type:40 a. Data tab → App data → [Type] → Upload41 b. Map CSV columns to Bubble fields42 c. Import43 d. Export with Unique IDs44 e. Use IDs for next round's VLOOKUP4546PHASE 4: RELATIONSHIP LINKING47 In child CSV (e.g., Order):48 Column: customer_id (source) → Customer (Bubble)49 Formula: =VLOOKUP(source_id, parent_export, id_column, FALSE)50 Replace source foreign key with Bubble Unique ID51 Save and import5253PHASE 5: VALIDATION54 □ Record count matches source for each Data Type55 □ Spot-check 10-20 random records per type56 □ Click relationship links to verify correct parent57 □ Check for empty fields that should have values58 □ Verify text encoding (no garbled characters)59 □ Build test page with RG to visually inspect6061PHASE 6: DOCUMENTATION62 □ Original source CSVs preserved63 □ Mapping document complete64 □ Import order documented65 □ VLOOKUP formulas saved66 □ Final record counts recorded67 □ Rollback procedure: bulk delete + re-importCommon mistakes
Why it's a problem: Importing child records before parent records
How to avoid: Always import in dependency order: parent Data Types first, then child Data Types after mapping Unique IDs
Why it's a problem: Using source foreign keys instead of Bubble Unique IDs for relationships
How to avoid: Export parent data after import to get Bubble Unique IDs, then use VLOOKUP to replace source IDs in child CSVs
Why it's a problem: Not validating data after import
How to avoid: 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
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I need to migrate data from a MySQL database with 5 tables (users, products, orders, order_items, categories) to Bubble. The tables have foreign key relationships. Can you help me plan the migration order and show me how to handle the relationship mapping?
Help me import data from CSV files into my Bubble app. I have Customer, Order, and Product Data Types. Orders link to Customers. Show me how to import in the right order and link the records correctly.
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.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation