Migrate a Project to Lakehouse v2

You can move one project at a time from Lakehouse v1 to Lakehouse v2. Other projects in the same workspace keep running on v1 until you migrate them too, so you can migrate a single project and leave everything else alone.

Migration moves the project’s tables and everything built on them: queries, expressions, views, Superset datasets, calculated columns, metrics, and row access rules.

Changes Made During a Migration Are Lost

A migration copies your data as it stands when the run starts. Anything written to the project after that — a workflow run, an imported file, an edited table — is not carried across and is not recoverable from the migrated copy. The project’s own workflow schedules pause while the migration runs and are restored afterwards, but nothing stops a manual run or an import. A workflow started during a migration shows a warning. Tell project members to stay out of the project until it finishes.

Migration Is One Way

There is no migrate-back. You can undo a migration and return the project to Lakehouse v1 within the undo window, as described in Undo a Migration. After that the original data is deleted.

Before You Start

• Migrate Project to Lakehouse v2… appears in the Tools menu for members who can edit projects. Only a project’s Architects can migrate it: starting, scheduling, cancelling and undoing a migration all need Architect access to the project.
• You need Architect access to the project, and the project must be unlocked.
• Your plan needs room for the copy. See Storage Check.
• Anyone who can open a project can run the readiness check.
• Run the readiness check first and resolve anything it refuses. A migration that starts on a project it cannot translate stops partway.
• Plan for the project to be unavailable for the length of the run, because writes during the run are lost.
• If other projects read this project’s tables through a data share, migrate those projects first, or remove the share. A project that others read through a data share is migrated after them.

Check Migration Readiness

The readiness check reports what will happen to the project before you commit to anything. It changes nothing.

1. Open the Tools menu.

2. Select Check Migration Readiness….

3. Select the project.

If the project is already on Lakehouse v2, the check says so and that there is nothing to migrate.

The report lists each area as one of:

Status	Meaning
Clear	PlaidCloud scanned the area and found nothing.
Needs review	Something will change, and you acknowledge it before the run.
Blocked	The migration cannot start until it is resolved.
Checked during migration	The area is checked while the migration runs, so it is never shown as clear beforehand.

The areas are tables, views, steps, dashboards, data shares and capacity. Every finding comes with a plain-language explanation, and a suggested rewrite is shown where one exists.

What the Readiness Check Refuses

Refusal	Why
A column whose type has no Lakehouse v2 equivalent	The migration refuses rather than quietly turning the column into text. Change the column’s type in the project, then re-run the check.
The target Lakehouse v2 warehouse cannot be resolved	The workspace’s v2 lakehouse is not visible to the service running the migration. This is an administrative problem, not something you can resolve in the project.
Deletion protection on the storage bucket cannot be confirmed	The undo window depends on it, so the migration will not start without it.

JSON columns migrate. Earlier releases refused them; they are supported now.

Storage Check

Before a run starts, PlaidCloud checks that your plan has room for the copy.

• On a plan with a storage limit, the run is refused if the migrated copy would not fit. Other migrations in progress count against the limit.
• On a plan billed for extra storage, the run starts with a warning of the expected overage.

Try on v2

Try on v2… makes a private trial copy of the project on Lakehouse v2 so you can check results before you migrate the real project. In the trial copy, schedules and sensors are turned off and ERP posting is in simulate mode. Steps that write outside PlaidCloud, such as SFTP, email and REST posts, are listed as a warning before you confirm. Start Trial makes the copy. A project that already has a trial offers Open Existing Trial and Replace Trial….

Run the Migration

1. Open the Tools menu.

2. Select Migrate Project to Lakehouse v2…. The window lists migration runs for the workspace.

3. Start a new run and select the project.

4. Read the readiness report shown in the window and acknowledge each named finding. Accepting a finding accepts it for that specific item only.

5. Select Start Migration, or tick Start at a scheduled time, set the time and select Schedule Migration. A scheduled migration shows a banner on the project, and you can cancel it before it starts. When it starts, PlaidCloud checks readiness, compatibility, capacity and your permissions again.

6. Start the run. The progress dialog shows each table as it is copied and checked. The project’s enabled workflow schedules pause for the run. You can close the dialog and reopen it from the run list; the run continues either way.

Once a run is switching the project over to Lakehouse v2, it can’t be stopped. If the switch-over itself fails partway, the run shows Contact support. Don’t retry. instead of offering Resume. Contact support and leave the run as it is.

When the run finishes, the project is bound to Lakehouse v2 and queries begin using it, and the paused schedules are restored. A schedule you edited or deleted during the migration is left as you left it and is named in the report. The original Lakehouse v1 copy is kept, unavailable to the project, for the undo window. You are notified, by message and by email, when a migration finishes or fails.

A Failed Migration

A failed migration shows why it failed and the time after which writes to the source will be lost. Select Resume to continue it. Views that can’t run on Lakehouse v2 are skipped and listed rather than stopping the run.

What Changed

After a migration, open What Changed… for the run. It lists each table as copied, copied with a named gap, skipped or failed, with row counts and reasons, the views that were skipped, tables created or dropped in the source during the run, and the schedules that were paused and restored.

Weekly Grouping Shifts by One Day

Lakehouse v2 starts its weeks on Sunday. Lakehouse v1 started them on Monday.

Anything grouped by week changes accordingly, with no error and no warning. A row dated Sunday 14 June belonged to the week beginning Monday 8 June on v1. On v2 it belongs to the week beginning Sunday 14 June.

The totals on either side of that boundary move. A weekly chart, a weekly summary table, and a report grouped by week all keep working and all show different numbers than they did before. Check any weekly figure you rely on after migrating, and expect a one-day shift rather than a mistake.

What Does Not Carry Over

Your data migrates. Some things built on top of the old engine, and some details of how columns were declared, do not.

Item	What happens
Snapshot history, time travel, and flashback	Not transferred. The migrated tables start with fresh history, so you cannot query the project as of a time before the migration.
Table branches and tags	Existing branches and tags are not transferred.
VARCHAR(n) length limits	The length limit is dropped. Text columns become unconstrained text; existing values are unaffected.
Narrow integer widths	Small integer types become 32-bit integers. Values are unaffected.
Fractional-second precision on timestamps	A declared precision is dropped.
Spatial, geometry, and bitmap columns	Migrated, but excluded from the automatic value comparison — check them yourself.
Binary, array, and map columns	Migrated, but excluded from the automatic value comparison — check them yourself.
JSON columns	Migrated with their types kept. A number inside JSON too large for exact storage is stored with double precision and reported.

Very Large Unsigned Integers

An unsigned 64-bit integer column holding values above 9,223,372,036,854,775,807 cannot be represented on Lakehouse v2, and those values are not reported as a refusal. If a project stores unsigned integers near that limit, check them before and after migrating.

Undo a Migration

For the undo window after a run completes, the original Lakehouse v1 data is kept intact but detached from the project. Undo Migration… returns the project to Lakehouse v1 in that window. You need Architect access to the project.

Undo asks you to type the project name to confirm. All changes made to the project since the switch to Lakehouse v2 are lost. Progress shows while the undo runs. If the undo is refused, the reason is named, for example that the undo window has closed.

Use it if results look wrong after migrating — weekly figures aside, which are expected to shift.

After the undo window the original data is deleted and the migration is final.

After the Migration

Sessions that were already open keep reading the copy they started with until they end. A long-lived Panel application session, in particular, continues serving the old data until it is restarted. Restart long-running sessions after a migration so they pick up Lakehouse v2.

Related

• Lakehouse Management
• Bind a Project to an External Lakehouse
• Vector Data Type