ziplinectl migrate-pglite

This command copies your PostgreSQL database into a new PGlite directory. It does not move uploaded files or thumbnails; keep your existing datasource and storage mounted.

Usage

ziplinectl migrate-pglite [options] <directory>

The destination directory must not already exist. Its parent must be writable by the user running the command.

Before migrating

1. Back up PostgreSQL.
2. Upgrade Zipline while still using PostgreSQL and let its database migrations finish. See the 4.8 upgrade notes.
3. Stop Zipline, but leave PostgreSQL running so the command can read it.

Copy the database

For a manual installation, run this from the Zipline project directory, with your existing PostgreSQL configuration still in place:

pnpm ctl migrate-pglite /var/lib/zipline/database

To specify a different PostgreSQL source, use --source <url>.

Docker

Before running the command, add persistent storage to the zipline service, keeping its existing volumes and PostgreSQL connection settings:

services:
  zipline:
    volumes:
      - './data:/zipline/data'

Stop the application and use a one-off container to run the migration. Unlike docker compose exec, this works while the Zipline service is stopped. Overriding the entrypoint runs the CLI instead of starting the server:

docker compose stop zipline
docker compose run --rm --no-deps --entrypoint ziplinectl zipline migrate-pglite /zipline/data/database

PostgreSQL must still be running and reachable from that container. The example creates ./data/database on the host; do not create that destination directory beforehand.

Switch to PGlite

On success, the command prints the new DATABASE_URL. Set it in your environment or Compose configuration. For the Docker example above:

DATABASE_URL=pglite:///zipline/data/database

If your Compose service defines DATABASE_URL under environment, update that value too; it overrides the value from env_file. Keep the persistent volume, then start Zipline and verify that your users and files are present.

docker compose up -d zipline

For a manual installation, use pnpm start instead. Once the new database is verified, the PostgreSQL service and Zipline's dependency on it are no longer needed. Keep your original database and backup until you are satisfied with the migration; subsequent writes to PGlite are not copied back to PostgreSQL.