Notion Migration Guide

Availability

Core Standard Plus Pro Enterprise Flex Self-Managed Enterprise PyAirbyte

Support Level

Airbyte

Connector Version

4.0.7 (last updated 18 days ago)

Definition ID

6e00b415-b02e-4160-bf02-58176a0ae687

Upgrading to 4.0.0

Version 4.0.0 migrates the connector from Notion API version 2022-06-28 to 2025-09-03. This is a major update driven by Notion's introduction of multi-source databases, where the concept of a "database" has been split into "databases" (containers) and "data sources" (individual schemas/property sets). A "data source" now represents what was previously called a "database" — the table containing pages and properties.

Breaking Changes

1. databases stream replaced by data_sources: The databases stream has been removed and replaced with a new data_sources stream. The new stream returns objects with "object": "data_source" instead of "object": "database", along with a different parent structure (database_id parent and database_parent grandparent fields).

2. pages stream parent field updated: Pages that belong to a database now report parent.type: "data_source_id" with a parent.data_source_id field instead of parent.type: "database_id" with a parent.database_id field.

3. blocks stream schema additions: New in_trash boolean field added and data_source_id parent type added.

Migration Steps

A full schema refresh and data reset are required for the Data Sources (formerly Databases), Pages, and Blocks streams.

1. Select Connections in the main nav bar.
   1. Select the connection(s) affected by the update.
2. Select the Schema tab.
   1. Click Refresh source schema to pick up the new data_sources stream and updated pages schema.
   2. Enable the new Data Sources stream if you were previously syncing the Databases stream.
3. Select the Status tab.
   1. In the Enabled streams list, click the three dots on the right side of the Pages stream and select Clear data.
   2. Do the same for the Blocks stream if you are syncing it.
4. Trigger a new sync by clicking Sync Now.

For more information on clearing your data in Airbyte, see this page.

Upgrading to 3.0.0

Version 3.0.0 migrates the connector from the Python CDK to the low-code CDK. This migration changes how state is managed for incremental streams nested within a parent stream, which is a breaking change for users syncing the Comments stream.

If you are not syncing the Comments stream, no action is required.

Migration Steps

Clear the data for the Comments stream:

1. Select Connections in the main nav bar.
   1. Select the connection(s) affected by the update.
2. Select the Status tab.
   1. In the Enabled streams list, click the three dots on the right side of the Comments stream and select Clear data.
3. After the clear succeeds, click Sync Now.

For more information on clearing your data in Airbyte, see this page.

Upgrading to 2.0.0

Version 2.0.0 updates the JSON schemas of the Blocks, Databases, and Pages streams to reflect changes in the Notion API:

• The rich_text property in Pages changed from an object to an array of rich_text objects.
• The phone_number property in Pages changed from a string to an object.
• The deprecated text property in content blocks was renamed to rich_text across the Blocks, Databases, and Pages streams.

Migration Steps

A full schema refresh and data reset are required.

1. Select Connections in the main nav bar.
   1. Select the connection(s) affected by the update.
2. Select the Schema tab.
   1. Click Refresh source schema to pick up the updated schemas.
3. Select the Status tab.
   1. In the Enabled streams list, click the three dots on the right side of each affected stream (Blocks, Databases, Pages) and select Clear data.
4. Click Sync Now.

For more information on clearing your data in Airbyte, see this page.

Connector upgrade guide

Review the following information to prepare for and execute your upgrade.

Review the changelog

Before updating a connector, review the changelog to understand the changes and their potential impact on your existing connections. Find the changelog for any connector by navigating to the bottom of the documentation for that connector. Major version releases also include a migration guide.

Plan for major updates

Major updates may require you to adjust connection settings or even make changes to your data pipelines. Allocate enough time and resources for this. Use the migration guide to ensure your transition process goes smoothly.

Airbyte provides tooling that guarantees safe connector version bumps and enforces automated version bumps for minor and patch updates. You always need to manually update for major version bumps.

Self-managed plans: pin a specific version if you can't update

If you're unable to upgrade to the new version of a connector, you can pin that connector to a specific version.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Edit the entry for the connector you want to pin.

3. Set the Default Version to the version you want to use.

Self-managed plans: update the local connector image

If you self-manage Airbyte, you must manually update the connector image in your local registry before proceeding with the migration. Follow the steps below.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Find the connector you want to update in the list of connectors.

   note

   Airbyte lists two versions, the current in-use version and the latest version available.

3. Click Change to update your OSS version to the latest available version.

Update the connector version

Update each instance of the connector separately. If you have multiple instances of a connector, updating one doesn't affect the others.

1. In the navigation bar:

   • If you're on the Self-Managed Enterprise plan, click Organization settings > Sources/Destinations.

   • If you're on any other plan, click Workspace settings > Sources/Destinations.

2. Select the instance of the connector you wish to upgrade.

3. Select Upgrade.

4. Follow the prompt to confirm you are ready to upgrade to the new version.

Clear data from affected streams

After upgrading a connector with a breaking change, you must refresh affected schemas and clear your data.

1. In the nav bar, click Connections.

2. Find the connection affected by the upgrade.

3. Click the Schema tab.

4. Click Refresh source schema (looks like ). When Airbyte finishes, it shows you any detected schema changes.

5. Click OK.

6. Click Save changes

7. Clear the data for the streams affected by this upgrade.

Once the clear is complete, you can begin syncing your data again as usual.