Migrating from a broken PostHog self-hosted instance

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

If your PostHog instance is running we highly recommend the migrating between PostHog instances guide

Requirements

• Existing PostHog self-hosted instance that you can no longer login too
• 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:

Migrate your events

1. Access your Clickhouse database and export all your events to disk (including uuid, timestamp, distinctid, event, properties, $group0, $group[1-3])
2. Disable the GeoIP plugin of your new PostHog instance
3. Write a script to send them as new requests (likely easiest with our node or python library). Here's an example of how we do it with the Replicator app.
4. Re-enable the GeoIP plugin

Migrate your meta data

To migrate the non-event data (such as user information, feature flags, dashboard configurations, etc), we'll need to create a data dump and load that into the new instance. This non-event data is stored in Postgres.

This is only officially supported for importing events into a new cloud instance of PostHog or an enterprise self-hosted instance using Kubernetes. If you're using a different deployment method, you can still try this approach but we can't guarantee it will work.

• You should have a clean PostHog cloud or self-hosted PostHog instance up and running. Your new PostHog instance should have no ingested events. We recommend using a fresh and unused installation.
• Your old and new instances should both be running the exact same version of PostHog (minimum 1.30.0).

1. Create a data dump from your old instance

Please note that this guide assumes your PostHog pods are running in the posthog kubernetes namespace, thus appending -n posthog to kubectl commands. Substitute posthog for the namespace applicable to you, or omit the -n flag if you're using the default namespace.

Access your old PostHog instance and run the following command:

# tip: use the flag -U to specify a username if necessary
pg_dump -d posthog -f tmp/export.sql --no-owner --data-only --disable-triggers \
-t posthog_action \
-t posthog_actionstep \
-t posthog_annotation \
-t posthog_cohort \
-t posthog_dashboard \
-t posthog_dashboarditem \
-t posthog_featureflag \
-t posthog_featureflagoverride \
-t posthog_messagingrecord \
-t posthog_organization \
-t posthog_organizationinvite \
-t posthog_organizationmembership \
-t posthog_personalapikey \
-t posthog_plugin \
-t posthog_pluginattachment \
-t posthog_pluginconfig \
-t posthog_pluginstorage \
-t posthog_team \
-t posthog_user \
-t posthog_user_groups \
-t posthog_user_user_permissions

Note: You may see a warning regarding circular dependencies between tables, which shouldn't be an issue as we are using --disable-triggers. If you do run into issues when restoring, try doing a full dump instead of --data-only.

If you do not access your Postgres database via a port-forwarding mechanism to your local machine, you will then need to copy the file from the server to your local system (or the remote server from where you access your new instance). You can do this with scp:

Note: If your old PostHog instance is hosted on Heroku, you should follow this guide to export all of your data, load into a separate database (we recommend a local Postgres instance), and then run the command above.

scp <your_username>@<database_hostname>:/tmp/export.sql .

If your old instance was deployed using the Helm chart, you can use:

kubectl cp <postgres-pod-name>:/tmp/export.sql ./export.sql # -n posthog

2. Send events to your new instance

You'll need to write a script to process this data and create the following resources on PostHog cloud. The PostHog migrate code which we use to migrate between two cloud instances will likely be useful.

Moving a license key

If you have an existing license key, please email sales@posthog.com to move your license key over.