Moving to the Buildpad Engine
A Supabase project can move to the Buildpad Engine, in place, from its project page. It keeps its ID, its URLs, its microapps and its users. You check a full rehearsal before anything changes. After the move, you can move back during the retention period, not after. After a move back, you can start a new move.
Move to the Buildpad Engine shows on a project’s DaaS page, and in the More actions (⋯) menu of its Details page, when your platform offers the move to your organization. To move the project, you need the Admin role on the project. Organization Admins are Admins of every project. When you create a project, you are its Admin. See Roles and Access.
The project’s Admins can do every step of the move, including Delete the old project now. Other members do not see it. If you do not see it, ask a project Admin or your platform operator. Operators can also move a project with the migration tool: see Moving with the Command Line.
What Moves and What You Do
| Part | How it moves |
|---|---|
| Collections, fields and relations | Copied. The Buildpad Engine needs a primary key on every table: a table without one gets its id column as its key, and the report says so. A table with no key and no id column stops the move until you add a key to it. A column that points to a scope item by its ID, not its URI, is copied without that link, and the report lists it. |
| Roles, policies, permissions and their links | Copied. You acknowledge each rule whose meaning changes before the cutover. |
| Users | Copied. Users keep their IDs, their passwords, their roles and their authenticator apps. |
| Folders and files | Copied, with the same IDs. Files up to 5 GiB move. |
| Records | Copied, with the same primary keys. ID counters continue after the copied records. |
| Project settings: name, look, outgoing email and MCP | Copied |
| Hooks, cron jobs and custom services | The ones that run on the Buildpad Engine are copied, switched off, and switched on at the cutover. You rewrite the others with your AI agent’s migrate-to-engine skill. |
| Scope types and items (tenants) | Copied, with the same IDs |
| Workflows | Copied |
| App code | Each app’s routine changes are made on a branch named move-to-engine in its repository. You review and merge it, and port the rest with your AI agent’s migrate-to-engine skill. |
| URLs, the apps’ settings and the workers | Switched at the cutover. You change nothing. |
These do not move:
- Passwords of users who signed in only with Google or another provider. They sign in with XAppHub, or an administrator sets a password.
- Authenticator apps that the old project stored encrypted. Those users set up MFA again.
- Static tokens. Give their holders new tokens on the Buildpad Engine.
- CORS settings. The Engine needs none.
- Database views, functions and triggers.
The report lists every item that needs a step from you.
Before You Start
Update the project. The move needs a recent Buildpad DaaS version. The preflight tells you if the project is too old. If it is, open the project’s DaaS page, create a backup, and click Update Version. The update keeps your data.
Use a static token if the administrator has MFA. If the Studio administrator signs in with an authenticator app, the preflight asks for a static token. Create one in the Studio (Users, the user, Token). It is kept encrypted for this move only.
Step by Step
Run the preflight
On the project’s DaaS page, click Move to the Buildpad Engine (on the Details page, it is in More actions (⋯)), then Run the preflight. The preflight reads the project and changes nothing. It shows:
- the version check;
- what will be copied: collections, rows, users, files, rules and automation;
- what has no place on the Buildpad Engine, such as database views;
- how long the Freeze will take, approximately.
A file over 5 GiB stops the move. Make it smaller, or remove it, and run the preflight again.
Start the move
Tick the confirmation and click Start move. The platform sets up a Buildpad Engine for the project and copies a live copy of the project to it. This is the rehearsal. The project keeps running, and your users notice nothing.
The move cannot start while another operation runs on the project, such as a backup, a restore, a worker setup or a new microapp. The page then shows “Another operation is in progress on this project”. Wait until the operation ends, then click Start move again.
From the start of the move until the cutover ends, the platform refuses these operations on the project: start and stop, Update Version, creating or deleting a backup, restoring a backup, deleting the project, creating a microapp, enabling workers, creating a worker, connecting or disconnecting a connector, and moving the project to another organization. Each one shows “A move to the Buildpad Engine is in progress”. The same refusal applies while a move back or the deletion of the old project runs. During the retention period, these operations work again, but you cannot move the project to another organization.
Read the rehearsal’s report
When the rehearsal ends, the page shows its report:
- What was copied, and any difference in counts, with the reason.
- Users who need a step: no usable password, no role, an authenticator to set up again, or a static token to replace with a new Buildpad Engine token. Users are listed by ID. Click Show address to see one user’s email. Each look is recorded.
- Rules that behave differently. These rules use a variable that the old project read as empty, such as
$CURRENT_ROLESor$NOW. On the Buildpad Engine they mean what the documentation says, so they can match more rows. Read each one. Change it in the Studio if it does not do what its author meant. Then click Acknowledge. - Rules not copied. Rewrite them on the Buildpad Engine after the move.
- Automation to rewrite. Rewrite each item with your AI agent’s
migrate-to-engineskill, switched off and under the same name.
To copy again after you change the old project, click Rehearse again.
The Apps card shows while the move waits for the Freeze and during the final review. It lists each app that has a repository: the Main app and each microapp of the project, by its name, with a link to the move-to-engine branch in its repository. A microapp that is still being created, or whose creation failed, is not in the list. If the project has no such app, the page does not show the Apps card or Settings for the ported app. Each app shows one of these results:
- branch move-to-engine pushed: review it, merge it during the Freeze. The app’s ported code is on a branch named
move-to-engine. The branch’sMOVE-TO-ENGINE.mdlists what you port by hand. Review the branch and test it against the temporary hosts in Settings for the ported app. Merge it during the Freeze, before you cut over. Do not merge it before the Freeze: an app that deploys on each merge then runs Engine code against the old project, and the app stops working. - already merged. The app’s port is already merged. You do nothing.
- nothing to change. The app needs no change, or its repository has no code yet. You do nothing.
- porting failed: port it by hand. The card shows the reason. Port the app by hand with the values in Settings for the ported app below. Then click Ported by hand. The app then shows the Ported by hand badge.
Settings for the ported app, under the apps, shows the values that a ported app uses on the Buildpad Engine. None of them is a secret. To copy a value, click Copy next to it.
| Setting | Value |
|---|---|
NEXT_PUBLIC_SUPABASE_URL | The project’s own API URL |
NEXT_PUBLIC_BUILDPAD_DAAS_URL | The project’s own API URL, as above |
NEXT_PUBLIC_BUILDPAD_TENANT_ID | The project’s tenant ID on the Buildpad Engine |
NEXT_PUBLIC_SUPABASE_ANON_KEY | The fixed public value of the Buildpad Engine |
From the cutover, the project’s API URL serves the Buildpad Engine.
At the cutover, the platform sets these values on each web app and removes SUPABASE_SERVICE_ROLE_KEY. Your code only reads them. Put the same values in your local .env.local.
Before the cutover, the project’s URL still serves the old project. Thus Settings for the ported app also shows the rehearsal’s Buildpad Engine at a temporary address:
- Temporary Engine URL: to try the ported app on the Buildpad Engine before the cutover, set both URLs in
.env.localto this address. - Temporary Studio: the Studio of the same Buildpad Engine.
The temporary address holds the rehearsal’s copy. Rehearse again and the Freeze copy the data to it again. It stops working at the cutover.
Freeze the project
Click Freeze now, or pick a time from 5 minutes to 30 days ahead and click Schedule. To remove a scheduled Freeze, click Cancel the schedule. During the Freeze:
- the old project refuses every write, and its apps show a maintenance answer;
- its cron jobs and hooks are switched off;
- the platform copies everything again and checks the counts.
The project stays frozen until you cut over or unfreeze. Plan the Freeze for a quiet time. The preflight and the rehearsal tell you how long the copy takes.
Review the final report
The final report shows what changed since the rehearsal. Acknowledge any new rule, make sure each app is merged or ported, then click Accept report.
If you are not ready, click Unfreeze. The project runs again as before, and you can freeze it later.
Cut over
Choose how long to keep the old project: from 7 to 90 days, 30 by default. Click Cut over. The platform:
- points the project’s URLs to the Buildpad Engine;
- sets your web apps (the main app and each web microapp) to the values in Settings for the ported app, removes
SUPABASE_SERVICE_ROLE_KEYfrom them, and deploys their mergedmove-to-enginebranch; - points your workers to the Buildpad Engine;
- switches on the hooks, cron jobs and custom services that were on in the old project;
- stops the old project and keeps it.
Your users sign in again with their old passwords.
The cutover does not change or rebuild mobile apps. During the retention period, the move page shows the ID of each mobile app to rebuild, so that it uses the Buildpad Engine.
Check the project during the retention period
A banner on the project’s pages shows when the project moved and how long the old project is kept. From the banner or the move page:
- Move back returns the URLs, data service and apps to the old project as it was at the cutover. Writes made on the Buildpad Engine since the cutover are not carried back. Tick I understand that these writes are lost. and click Move back. The move back does not change microapps created after the cutover. After the move back, the move page lists them, so you can check where they point. The platform deletes the Buildpad Engine 7 days after the move back, or before a new move starts.
- Extend keeps the old project longer. Pick a later date in Keep it until, up to 90 days after the cutover.
- Delete the old project now, on the move page only, deletes the old project and its backups now, before the end of the retention period. Click Delete the old project to confirm. After this you cannot move back.
At the end of the retention period, the platform deletes the old project and its backups. 7 days before and 1 day before, the platform sends an email to the project’s Admins: the organization Admins and the people with the Admin role on the project. The email links to the move page. If you extend the retention period, the platform sends the two emails again for the new date.
If a Step Fails
The move page shows the step that failed and why. Click Retry to run it again.
If the Freeze, the final copy or the count check fails, the platform unfreezes the old project first, so your users can work. Retry then freezes the project again before it copies.
The old project must run during the move. From the provision step until the cutover, the platform keeps the old project out of the nightly scheduled stop. If the project stopped anyway, a step fails. While the move runs, the platform cannot start the project, and its DaaS page cannot start it either. Contact Buildpad support to start the old project’s server, then click Retry.
Before the cutover, you can also click Abandon: the platform deletes the Buildpad Engine it set up and unfreezes the project, and nothing changes on the project. After the cutover, use Move back.