Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/notion-migration-deep-dive/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-migration-deep-dive. Copyright stays with the author (MIT).

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

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.