Granola Migration Guide
Upgrading to 1.0.0
Version 1.0.0 changes the notes stream's incremental cursor from created_at to updated_at, so notes edited after a sync are replicated again instead of requiring a full refresh. Records in notes now include the updated_at field.
This is a breaking change for existing connections:
- Cursor state written by earlier versions is keyed on
created_at, which the newupdated_atcursor ignores. The first sync after upgrading re-reads every note updated since your configuredstart_date, which can produce duplicate records in destinations that sync in append mode. start_datenow bounds when notes were last updated, not when they were created. The first sync after upgrading may therefore read notes created before your start date that were updated after it.- The first sync after upgrading reads every note updated since your
start_datein a single pass. If it fails partway through, the next attempt restarts fromstart_date.
Who needs to act
If your connection doesn't propagate schema changes automatically, refresh the source schema after upgrading so it picks up the new updated_at column and cursor. Then:
notesin Incremental | Append + Deduped or Full Refresh | Overwrite: no action is needed. The first sync re-reads your notes and the destination keeps one row per note, now with its latest edits.notesin Incremental | Append: the first sync appends a second copy of every note updated since your start date. From then on, each edit to a note appends a new row. If you want one row per note, switch the stream to Append + Deduped. To remove the one-time duplicates, refresh the stream and remove records. Read the warning below first.
Clearing the notes stream, or refreshing it with Remove records, deletes the existing rows from your destination. The next sync can only bring back notes Granola still returns: notes you deleted or unshared, notes your API key can no longer read, and notes last updated before your start date are gone for good. If you left Start Date empty, it's a rolling two-year window. Snapshot the notes table first if you need that history.
Update downstream models
If you sync notes in Incremental | Append, your destination now holds more than one row per note. Each edit adds a new row, and each sync repeats the most recently updated note, because the connector re-reads the stored cursor's last second so it doesn't miss changes made in that second. Models, dashboards, and file consumers that assume one row per id should keep the row with the latest updated_at for each id.
Other streams
detailed_notes and note_transcripts don't need any action. They have no cursor state and re-read every note updated since your start_date on every sync. After upgrading, they also include notes created before your start_date that were updated after it.
Connector upgrade guide
The general steps below end by clearing the affected streams. That step doesn't apply to this upgrade: refresh the source schema, then follow Who needs to act instead of clearing notes.
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.
-
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.
-
-
Edit the entry for the connector you want to pin.
-
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.
-
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.
-
-
Find the connector you want to update in the list of connectors.
noteAirbyte lists two versions, the current in-use version and the latest version available.
-
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.
-
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.
-
-
Select the instance of the connector you wish to upgrade.
-
Select Upgrade.
-
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.
-
In the nav bar, click Connections.
-
Find the connection affected by the upgrade.
-
Click the Schema tab.
-
Click Refresh source schema (looks like ). When Airbyte finishes, it shows you any detected schema changes.
-
Click OK.
-
Click Save changes
-
Clear the data for the streams affected by this upgrade.
Once the clear is complete, you can begin syncing your data again as usual.