> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the public docs of Meridian for Shopify apps: hosting, billing (Plan Builder and the @the-meridian/sdk package), CRM, emails and automations for Shopify app developers.
> Start with these pages: Meridian MCP (https://help.the-meridian.ai/mcp-server.md) to connect a coding agent, AI coding agents (https://help.the-meridian.ai/ai-agents.md) for the agent skill, SDK quickstart (https://help.the-meridian.ai/sdk-quickstart.md), Running your app with the CLI (https://help.the-meridian.ai/cli-dev.md), Deployment (https://help.the-meridian.ai/deployment.md), and Errors (https://help.the-meridian.ai/errors.md) to look up an error code or message.
> Fetch one page at a time as Markdown (the page URL followed by .md), using the index in https://help.the-meridian.ai/llms.txt. llms-full.txt holds every page in one file of about 900 KB, so avoid loading it whole.
> With Meridian MCP connected, search these docs with docs_search and docs_get, and read live facts (feature and event keys, plan ids, environments, deployments, logs) from the MCP tools instead of guessing them.

# Migrate from Heroku Postgres

> Move a Shopify app's Heroku Postgres data into a Meridian PostgreSQL database: capture a backup on Heroku, then restore it in a release command or through support.

A Shopify app that runs on Heroku usually stores its data in Heroku Postgres. Meridian runs [PostgreSQL databases](https://help.the-meridian.ai/database.md) too, so the app keeps its Prisma schema, its migrations and its data: you move the data once, then point the app at Meridian.

The move has four parts: prepare the Meridian app, capture a backup on Heroku, restore it into the Meridian database, then switch traffic.

## Before you start

* The app on Meridian uses **PostgreSQL** as its [engine](https://help.the-meridian.ai/database.md#one-engine-per-app). Add a PostgreSQL database from **Hosting → Database**. If the app already has a MySQL database from its plan, delete it first, while it is still empty.
* The Prisma `datasource` stays `provider = "postgresql"` with `url = env("DATABASE_URL")`. Meridian sets `DATABASE_URL` for the environment.
* The repository is [connected](https://help.the-meridian.ai/github.md) and the environment has a [release command](https://help.the-meridian.ai/deployment.md#release-command), usually `npx prisma migrate deploy`.
* Extensions are not restored: your app's role owns its database and schema, but cannot create extensions. If your schema uses one (for example `citext` or `pg_trgm`), contact support before you migrate.

## 1. Capture a backup on Heroku

Stop writes first, so the backup holds everything. Maintenance mode answers every request with an error page, so plan a quiet window:

```bash theme={null}
heroku maintenance:on -a <heroku-app>
heroku pg:backups:capture -a <heroku-app>
heroku pg:backups:url -a <heroku-app>
```

The last command prints a signed link to the backup. It works for about an hour. Heroku backups are in PostgreSQL's custom format, which `pg_restore` reads.

To keep a copy, download it with `heroku pg:backups:download -a <heroku-app>`, which saves `latest.dump`.

## 2. Restore it into the Meridian database

The Meridian database is private: it is reachable from your hosted app, not from the internet. So the restore runs where the app runs, in the release command, which has the same `DATABASE_URL` and network as the app.

Add `pg_restore` to the image. In the Shopify template's Alpine-based `Dockerfile`:

```dockerfile theme={null}
RUN apk add --no-cache postgresql17-client
```

Use a client of the same major version as your Heroku database, or newer (`heroku pg:info` shows the version).

Add this script to the repository as `scripts/import-heroku.sh`:

```bash theme={null}
#!/bin/sh
# One-off import of a Heroku Postgres backup into the Meridian database.
set -eu

if [ -z "${HEROKU_DUMP_URL:-}" ]; then
  exit 0
fi

# Import into an empty database only, so a second deploy never imports twice.
if [ -n "$(psql "$DATABASE_URL" -tAc "SELECT to_regclass('public._prisma_migrations')")" ]; then
  echo "The database already has a schema: skipping the Heroku import."
  exit 0
fi

wget -qO /tmp/heroku.dump "$HEROKU_DUMP_URL"

# Leave out extensions, which the app's role cannot create.
pg_restore -l /tmp/heroku.dump | grep -v -E 'EXTENSION|heroku_ext' > /tmp/heroku.list

pg_restore --no-owner --no-acl --single-transaction --exit-on-error \
  --use-list=/tmp/heroku.list --dbname="$DATABASE_URL" /tmp/heroku.dump

rm -f /tmp/heroku.dump /tmp/heroku.list
echo "Heroku import complete."
```

Then:

1. On the Meridian environment, add a secret `HEROKU_DUMP_URL` with the link from step 1, scoped to that environment.
2. Set the release command to `sh scripts/import-heroku.sh && npx prisma migrate deploy`.
3. Deploy. The import runs before the new revision exists, and its output appears in the deploy log.

The restore runs in one transaction: if anything fails, the deploy fails, the database stays empty, and you can fix the cause and deploy again. Your Prisma migration history comes with the data, so `prisma migrate deploy` applies only migrations newer than the backup. The release command has 15 minutes, which covers most Shopify app databases; for a larger one, contact support.

Once the import has run, delete the `HEROKU_DUMP_URL` secret, set the release command back to `npx prisma migrate deploy`, and remove the script and the `apk add` line at your next change.

## Or let support import it

If you would rather not change the `Dockerfile`, contact support. Download the backup with `heroku pg:backups:download` and tell us which app and environment it is for: Meridian imports it into that database for you, owned by your app's role, and confirms when it is done.

## 3. Check the data

Open **Hosting → Database** and use the [SQL console](https://help.the-meridian.ai/database.md#reading-and-writing-data) to compare a few counts with Heroku, for example:

```sql theme={null}
SELECT count(*) FROM "Session";
```

Your app's own tables come across with their sequences, so new rows continue the ids Heroku used.

## 4. Switch traffic

Point your Shopify app's URLs at the Meridian environment's domain (the [default domain](https://help.the-meridian.ai/default-domain.md) or your [custom domain](https://help.the-meridian.ai/custom-domain.md)), and deploy the configuration with the Shopify CLI. Keep the Heroku app in maintenance mode until the Meridian app answers, then remove the Heroku database when you no longer need it.

Shop sessions live in the `Session` table you imported, so merchants do not need to reinstall the app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.