# How to handle data migration in Bubble.io: Step-by-Step Guide

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

## TL;DR

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.

## Before you start

- 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

### 1. 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.

### 2. 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.

### 3. 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.

### 4. 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.

```
POST https://yourapp.bubbleapps.io/api/1.1/obj/contact
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane@example.com",
  "company": "1234567890x1234"
}
```

**Expected result:** Records are created programmatically via the API with full control over batching and error handling.

### 5. 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 code example

File: `Workflow summary`

```text
DATA MIGRATION — PROCESS SUMMARY
==================================

PHASE 1: PLANNING
  1. List all source tables → map to Bubble Data Types
  2. Map each source column → Bubble field + note type conversions
  3. Identify parent-child relationships (import order matters)
  4. Create all Data Types and fields in Bubble

PHASE 2: DATA CLEANING
  1. Remove duplicates
  2. Standardize dates to YYYY-MM-DD
  3. Remove currency symbols from numbers
  4. Convert booleans to true/false
  5. Replace relationship keys with Bubble Unique IDs

PHASE 3: IMPORT ORDER
  1. Import standalone Data Types first (no foreign keys)
  2. Export imported records to get Unique IDs
  3. Add Unique IDs to child record CSVs
  4. Import child Data Types

PHASE 4: IMPORT METHODS
  Small datasets (<10K): CSV upload in Data tab
  Large datasets (>10K): Data API with batch processing
  Complex transforms: API + backend workflow for per-record logic

PHASE 5: VALIDATION
  1. Compare source row counts vs Bubble record counts
  2. Spot-check 10-20 random records
  3. Verify relationships load correctly
  4. Search for empty required fields
  5. Test app functionality with migrated data
```

## Common mistakes

- **Importing child records before parent records** — Child records reference parent Unique IDs that do not exist yet, resulting in broken relationships Fix: Always import parent Data Types first, export to get their Unique IDs, then add those IDs to child CSVs before importing
- **Not cleaning date formats before import** — Bubble expects specific date formats. Inconsistent dates (01/15/2026 mixed with 2026-01-15) cause import failures Fix: Standardize all dates to one format (YYYY-MM-DD recommended) in your spreadsheet before uploading
- **Importing all data at once without testing a sample first** — A mapping error on 50,000 records means deleting and re-importing everything Fix: 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

## 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.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/handle-data-migration-in-bubble
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/handle-data-migration-in-bubble