Handle data migration in Bubble by importing CSV files through the Data tab, using the API Connector for programmatic transfers, and managing data type mismatches between your source and Bubble's field types. This tutorial covers planning, executing, and validating a data migration into or out of Bubble.
Overview: Data Migration in Bubble
Data migration involves moving data into Bubble from another platform (like a spreadsheet, Airtable, or legacy database) or out of Bubble to a new system. This tutorial covers the complete migration process including planning your data mapping, executing the transfer via CSV or API, handling type conversions, and verifying everything landed correctly.
Prerequisites
- A Bubble account with the target Data Types already created
- Your source data exported as CSV or accessible via API
- Basic understanding of Bubble's Data tab and field types
- A spreadsheet application for reviewing and cleaning CSV data
Step-by-step guide
Map your source data to Bubble Data Types
Map your source data to Bubble Data Types
Before importing anything, create a mapping document. List every table/sheet in your source alongside its corresponding Bubble Data Type. Map each column to a Bubble field, noting type conversions needed (e.g., source text dates → Bubble date fields). Identify relationships that need to be recreated (e.g., a customer ID that links to an orders table). Create all target Data Types and fields in Bubble first.
Pro tip: Export a sample of 5-10 records first to test the mapping before running the full migration.
Expected result: A clear mapping document showing source columns → Bubble fields with any type conversion notes.
Clean and prepare your CSV files
Clean and prepare your CSV files
Open your source data in a spreadsheet. Clean it: remove duplicate rows, standardize date formats to YYYY-MM-DD (or MM/DD/YYYY), ensure number fields contain only numbers (no currency symbols), and convert yes/no fields to true/false for Bubble booleans. For linked records, ensure the CSV contains the Bubble Unique ID of the related record (import parent records first, export them to get IDs, then add those IDs to child record CSVs).
Expected result: Clean CSV files ready for import with consistent formatting and proper relationship IDs.
Import data via CSV upload
Import data via CSV upload
Go to Data tab → App data → select the target Data Type. Click the Upload button (up arrow icon). Select your CSV file. Bubble shows a mapping screen where you match CSV columns to Data Type fields. Verify each mapping is correct. For list fields, separate values with commas. Click 'Upload' to start the import. Bubble processes records in batches — large imports may take several minutes.
Pro tip: Import parent Data Types before children. For example, import Companies before Contacts that reference them.
Expected result: Records appear in the Data tab's App data view for the target Data Type.
Use the Data API for large or complex migrations
Use the Data API for large or complex migrations
For datasets over 10,000 records or those requiring transformation logic, use the Data API. Enable it in Settings → API tab. Use a tool like Postman or a simple script to POST records to https://yourapp.bubbleapps.io/api/1.1/obj/datatype. Send each record as a JSON body with field names matching your Data Type fields. Process in batches of 50-100 records with delays between batches to avoid rate limiting.
1POST https://yourapp.bubbleapps.io/api/1.1/obj/contact2Authorization: Bearer YOUR_API_TOKEN3Content-Type: application/json45{6 "first_name": "Jane",7 "last_name": "Smith",8 "email": "jane@example.com",9 "company": "1234567890x1234"10}Expected result: Records are created programmatically via the API with full control over batching and error handling.
Validate the migrated data
Validate the migrated data
After import, verify data integrity. Compare record counts: source row count vs Bubble record count (Data tab → App data shows total count). Spot-check 10-20 random records to verify field values match the source. Check linked records by opening a child record and confirming its parent reference loads correctly. Use Bubble's search to find records with empty required fields (constraint: field is empty) to catch incomplete imports.
Expected result: Record counts match, spot-checked records are accurate, and no critical fields are empty.
Complete working example
1DATA MIGRATION — PROCESS SUMMARY2==================================34PHASE 1: PLANNING5 1. List all source tables → map to Bubble Data Types6 2. Map each source column → Bubble field + note type conversions7 3. Identify parent-child relationships (import order matters)8 4. Create all Data Types and fields in Bubble910PHASE 2: DATA CLEANING11 1. Remove duplicates12 2. Standardize dates to YYYY-MM-DD13 3. Remove currency symbols from numbers14 4. Convert booleans to true/false15 5. Replace relationship keys with Bubble Unique IDs1617PHASE 3: IMPORT ORDER18 1. Import standalone Data Types first (no foreign keys)19 2. Export imported records to get Unique IDs20 3. Add Unique IDs to child record CSVs21 4. Import child Data Types2223PHASE 4: IMPORT METHODS24 Small datasets (<10K): CSV upload in Data tab25 Large datasets (>10K): Data API with batch processing26 Complex transforms: API + backend workflow for per-record logic2728PHASE 5: VALIDATION29 1. Compare source row counts vs Bubble record counts30 2. Spot-check 10-20 random records31 3. Verify relationships load correctly32 4. Search for empty required fields33 5. Test app functionality with migrated dataCommon mistakes when handling data migration in Bubble.io: Step-by-Step Guide
Why it's a problem: Importing child records before parent records
How to avoid: Always import parent Data Types first, export to get their Unique IDs, then add those IDs to child CSVs before importing
Why it's a problem: Not cleaning date formats before import
How to avoid: Standardize all dates to one format (YYYY-MM-DD recommended) in your spreadsheet before uploading
Why it's a problem: Importing all data at once without testing a sample first
How to avoid: Import 5-10 sample records first, verify they look correct, then run the full import
Best practices
- Always test with a small sample (5-10 records) before running a full migration
- Import parent Data Types before child types that reference them
- Standardize date and number formats in your CSV before uploading
- Keep a backup of your original source data in case you need to re-run the migration
- Document your field mapping for future reference and troubleshooting
- Use the Data API for large datasets to avoid browser timeout during CSV upload
- Validate record counts and spot-check data after every migration step
- Run the migration in your Development environment first, then repeat for Live
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I need to migrate 15,000 customer records from an Airtable base into my Bubble.io app. The data includes customers, orders, and products with relationships between them. Can you help me plan the migration order, data cleaning steps, and import process?
Help me migrate data into my app. I have CSV files for customers, orders, and products. Create the appropriate Data Types if they do not exist, and guide me through importing the data in the correct order with proper relationships.
Frequently asked questions
How long does a CSV import take?
Speed varies by record count and complexity. Expect roughly 100-500 records per minute for CSV upload. Datasets over 10,000 records may take 20-60 minutes.
Can I import images via CSV?
Yes. Include the full image URL in your CSV. Bubble will store the URL in the image field. The images must be publicly accessible for Bubble to display them.
What happens if an import fails midway?
Bubble does not roll back partial imports. Records created before the failure remain in the database. You may need to delete those records and restart the import after fixing the issue.
Can I automate ongoing data sync instead of one-time migration?
Yes. Use the API Connector to build a recurring sync workflow that pulls new records from your external source periodically and creates or updates them in Bubble.
How do I handle duplicate records during import?
Bubble CSV import does not check for duplicates automatically. De-duplicate your CSV before upload, or use a backend workflow that checks for existing records by a unique field (like email) before creating new ones.
Can RapidDev help with complex data migrations?
Yes. RapidDev handles complex data migrations including multi-table relationships, data transformation, deduplication, and ongoing sync setups between Bubble and external systems.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation