Last updated

Plane Import

The plane-import command loads a Plane project into a Windshift workspace. It preserves item numbers, authors, and timestamps, and it is safe to re-run.

The import has two pieces that share one JSONL contract:

Piece Runs against Does
tools/plane-import/dump.sql The Plane PostgreSQL database Emits the JSONL contract.
plane-import The Windshift PostgreSQL database Loads the contract into a workspace.

plane-import supports PostgreSQL only. It connects directly to the database and does not support SQLite.

Before you start

Collect these items:

  • The Plane database connection string.
  • The Plane project id from projects.id.
  • The Windshift PostgreSQL connection string.
  • The destination workspace key.
  • A users sidecar file, if the export includes authors.

Dump the contract

Run the dumper against the Plane database with psql 12 or newer:

psql "$PLANE_DATABASE_URL" -q -v ON_ERROR_STOP=1 \
  -v project_id='8bcd9a90-64b9-4283-9b1f-dfd3755b1ac4' \
  -v max_sequence='' \
  -t -A -f tools/plane-import/dump.sql > contract.jsonl

Set max_sequence to a number to freeze the number range at a cutover sequence. Only issues at or below the cap, and their comments and parents, are emitted. Leave it empty for the full project.

The dumper reads Plane's own database. Plane's HTTP export is session-auth only and cannot be fetched with an API key, so the database is the faithful source.

Dry run

A dry run parses the contract, maps the authors, and reports what the real run would create. The vocabulary pass commits and then rolls back, so a dry run proves the writes against the live schema and persists nothing.

plane-import \
  --connection "$WINDSHIFT_POSTGRES_CONNECTION_STRING" \
  --workspace VECTIS \
  --workspace-slug solum-designum \
  --contract contract.jsonl \
  --alias hakerx1@gmail.com=oskars_germovs@inbox.lv \
  --dry-run

Run the import

plane-import \
  --connection "$WINDSHIFT_POSTGRES_CONNECTION_STRING" \
  --workspace VECTIS \
  --workspace-slug solum-designum \
  --contract contract.jsonl \
  --alias hakerx1@gmail.com=oskars_germovs@inbox.lv

The command writes a JSON report to stdout and progress lines to stderr. The report lists imported rows, rows that already existed, converged rows, rows left alone because they changed after import, comments, unmapped authors, created vocabulary, and any collisions.

Option Description
--connection Windshift PostgreSQL connection string. Defaults to $POSTGRES_CONNECTION_STRING.
--workspace Destination workspace key. Required.
--workspace-slug Source Plane workspace slug. When set, it must match the contract meta.
--contract Path to the JSONL contract. Required.
--users Path to the users sidecar JSON array. Optional.
--alias Maps a Plane email to a different Windshift email. Repeatable.
--strict Fail when an author cannot be resolved.
--dry-run Parse, map, and report without writing.
--skip-migrate Do not run the migration catalog.
--batch Issues committed per transaction. Default 200.

Without --alias, an author whose email differs between the two systems is reported as unmapped and imports with a null creator instead of inventing a user.

What the import preserves

  • Item numbers. The source sequence_id becomes the workspace item number. Gaps in the source numbering stay gaps, and the counter continues above the maximum.
  • Authors and timestamps. creator_id and created_at use the source values, not import time.
  • States, priorities, and labels. Every state, priority, and label the contract names exists in Windshift after the run. A missing status is created under the category its Plane group implies, urgent gets a priority row, and labels are created and linked.
  • Comments and parent links.

New statuses get workflow edges in the workflow the workspace resolves, so items can move onto and off them after the import.

Re-runs

The import is idempotent and converging. It keys imported rows on the source uuid in plane_import_mappings.

  • A row nobody edited since import is moved onto the state, priority, and labels the contract says it has.
  • A row edited after import is left alone and counted. The operator's later decision outranks the import.
  • A number collision the importer does not own stops the run.

Schema

By default the command runs the Windshift migration catalog, which creates plane_import_mappings. Use this on a fresh install or a deployment at the binary's version.

Pass --skip-migrate when the application manages its own schema. Apply any missing pieces first. For a deployment that predates the current catalog, tools/plane-import/legacy-schema.sql contains the complete set the importer needs. Every statement is copied from the upstream migration and is IF NOT EXISTS, so a later application upgrade finds it present.

Caution: Without --skip-migrate, the command moves the shared database to this binary's version. An older application container then refuses to restart until it is updated too.