Notion migration deep dive

Notion Migration Deep Dive

Overview

Production migration patterns for moving data to, from, and between Notion workspaces — rate-limited bulk import, paginated export, cross-platform conversion, and post-migration validation. Every bulk-write path respects Notion's 3 requests/second average rate limit.

Prerequisites

• @notionhq/client v2+ installed (npm install @notionhq/client)
• Python alternative: notion-client (pip install notion-client)
• p-queue for rate-limited concurrency (npm install p-queue)
• Source data access (CSV files, Confluence API, Google Docs API, etc.)
• Target Notion database(s) created with matching property schema

Authentication: create a Notion internal integration at notion.so/my-integrations, share the target database(s) with it, and export the secret as NOTION_TOKEN. Every code sample reads process.env.NOTION_TOKEN — the client never takes an inline credential.

Instructions

The workflow has three directions. Each step below gives the essential shape; the full runnable code lives in the reference files so this page stays scannable.

Step 1: Import CSV/JSON into a Notion database

Map each source field to a Notion property value object, strip properties the target schema does not have, and create pages through a rate-limited queue:

const queue = new PQueue({ concurrency: 3, interval: 1000, intervalCap: 3 }); // ≤3 req/s

await notion.pages.create({
  parent: { database_id: databaseId },
  properties: {
    Name: { title: [{ text: { content: record.name || 'Untitled' } }] },
    Status: { select: { name: record.status || 'Not Started' } },
  },
});

Validate the database schema with databases.retrieve before the loop so mismatched columns are dropped instead of failing every row. Full TypeScript + Python importers (property mapping, schema filtering, error collection): full walkthrough.

Step 2: Export from Notion to JSON/CSV

Page through databases.query (100 rows per page) and flatten each page's properties by type. Optionally pull block content for rich-content migrations:

do {
  const response = await notion.databases.query({
    database_id: databaseId, page_size: 100, start_cursor: cursor,
  });
  // extractProperties() maps title/select/multi_select/date/relation/... to flat values
  cursor = response.has_more ? response.next_cursor ?? undefined : undefined;
} while (cursor);

Full exporter with the per-property-type extractor and block-content reader: full walkthrough.

Step 3: Cross-platform migration and validation

See cross-platform migration patterns for HTML/Markdown to Notion block conversion, batch content appending (100-block batches), cross-database sync with duplicate detection, and post-migration validation with integrity checks.

Output

• Rate-limited CSV/JSON import with property mapping and schema validation
• Full database export with pagination and property extraction (all property types)
• Page content export (block-level) for rich content migration
• HTML/Markdown to Notion block conversion for Confluence/Google Docs content
• Cross-database sync with duplicate detection
• Post-migration validation comparing source and target with integrity checks
• Dual language support (TypeScript and Python)

Error Handling

Issue	Cause	Solution
validation_error on import	Property name mismatch	Retrieve database schema first with databases.retrieve
Rate limited during bulk import	Exceeding 3 req/s	Use PQueue with intervalCap: 3, interval: 1000
Empty title error	Missing required title field	Default to 'Untitled' for empty names
Select option not found	New option value	Notion auto-creates new select options (not an error)
Relation import fails	Target pages don't exist yet	Import referenced pages first, then create relations
Rich text truncated	Text exceeds 2000 char limit	Split into multiple text blocks
Block append fails	More than 100 blocks	Batch blocks in groups of 100

Examples

One-Line CSV Import

# Quick import with Node.js script
node -e "
const { Client } = require('@notionhq/client');
const { parse } = require('csv-parse/sync');
const fs = require('fs');
const notion = new Client({ auth: process.env.NOTION_TOKEN });
const rows = parse(fs.readFileSync('data.csv', 'utf-8'), { columns: true });
(async () => {
  for (const row of rows) {
    await notion.pages.create({
      parent: { database_id: process.env.NOTION_DB_ID },
      properties: { Name: { title: [{ text: { content: row.name } }] } }
    });
    await new Promise(r => setTimeout(r, 350)); // ~3 req/s throttle
  }
  console.log('Done:', rows.length, 'imported');
})();
"

Export to JSON File

const data = await exportDatabase(process.env.NOTION_DB_ID!);
writeFileSync('export.json', JSON.stringify(data, null, 2));
console.log(`Exported ${data.length} records to export.json`);

The exportDatabase and importFromCSV helpers referenced here are defined in full in references/implementation.md.

Resources

• Create a Page — import endpoint
• Query a Database — export with pagination
• Append Block Children — add content blocks
• Property Value Object — all property types
• Request Limits — 3 req/s average
• Block Types — paragraph, heading, list, code, etc.
• Related skill: for advanced debugging of migration issues, see notion-advanced-troubleshooting.