Migrate between PostHog instances

If you're attempting this migration, feel free to ask questions and provide feedback via the PostHog Communty Slack workspace or a GitHub issue.

Requirements

• Existing PostHog instance that you can login to (Self-hosted versions need a minimum version of 1.30.0, if you version is lower you'll need to upgrade to this version first)
• A new PostHog instance

Approach

This migration has two parts:

1. Migrate your events, this will also create the necessary person, person distinct ID, and related records.
2. Migrate your meta data (projects, dashboards, insights, actions, cohorts, feature flags, experiments, annotations).
   • Note! It won't move over the following:
     1. Project API Key. You'll need to replace the API key in your code with the new API key.
     2. "created by" information. Every object will appear as if it was created by you.
     3. "created at" information. Every object will appear as if it was created on the time you ran this script.

Migrate your events

To migrate your events, we'll be using the PostHog Replicator app:

1. Disable the GeoIP plugin of your new PostHog instance
2. Log in to your old PostHog instance
3. Click 'Apps' on the left-hand tool bar
4. Search for 'Replicator'
5. If self-hosted, select the app, press 'Install' (or make sure it's the latest version)
6. For the configuration details using the following:
   • Host: the hostname of your new PostHog instance e.g. app.posthog.com if you are using US cloud, eu.posthog.com if you were are EU cloud, or the domain you'll be sending events to if you are self-hosting
   • Project API Key: the API key for the new project that you want to send events to - found in the project settings page.
7. After clicking save and activating it (toggle on the left side), the Replicator will start to run. Any events added to your old instance will be replicated in your new instance. It can take a little while (15-20 minutes) for the first events to show up.
8. Once the Replicator is activated, go back to the configuration menu and click the gear next to "Export historical events" under "Jobs." On the calendar, select a start and end date, then click "Run job now." This will begin the process of historical events being import (and might take a while). You can see the progress in logs or by clicking the "App metrics" button (graph) and going to the "Historical exports" tab.
9. To track progress of the export you can click the graph icon next to the Replicator app and then click on the "Historical Exports" tab
10. Re-enable the GeoIP plugin of your new PostHog instance

Migrate your meta data

Follow the instructions on the PostHog migrate metadata repo:

1. Clone the repo and cd into it
   Terminal

   git clone https://github.com/PostHog/posthog-migrate-meta
   cd posthog-migrate-meta

2. Install the dependencies by running yarn
3. Run the script
   Terminal

   ts-node --source [posthog instance you want to migrate from] --sourcekey [personal api key for that instance] --destination [posthog instance you want to migrate to.] --destinationkey [personal api key for destination instance]

For more information on the options see the repo's readme

Migrating your custom apps if you are moving from self-hosted to cloud

If the app was previously extracting events using the scheduled tasks api:

1. (fastest option) you could move this logic from the app into scheduled tasks on your server potentially using a cron job
2. If you can make your app generalizable enough that others can benefit then submit your app to the store.
   • To make it generalizable you'll want to convert anything specific to your configuration into a plugin.json config value

If the app was transforming events before ingestion:

1. (fastest option) you could move this logic from the app into your client before you send the event
2. If you can make your app generalizable enough that others can benefit then submit your app to the store.
   • To make it generalizable you'll want to convert anything specific to your configuration into a plugin.json config value

If the app was used to send events to a custom destination:

1. (fastest option) Convert your app to work as a webhook. We are soon releasing a webhook destination. You can subscribe for updates on the roadmap

2. If you can make your app generalizable enough that others can benefit then submit your app to the store.

   • To make it generalizable you'll want to convert anything specific to your configuration into a plugin.json config value

   If the options above don't work and you were previously paying a substantial amount self-hosting then email us at hey@posthog.com with a link to the public github repo and we can see if it's appropriate as a private cloud app.