ForgeVPSImport a Supabase database
Copy selected application schemas into a new local database, verify the result, and switch your app deliberately.
On this page
What the import copies
The import copies selected application schemas, table data, sequences, indexes, and constraints into a new managed PostgreSQL database. It is a snapshot, not ongoing replication. The existing Supabase database is not overwritten.
Supabase Auth, Storage file contents, Realtime, Edge Functions, global roles and grants, and large objects outside the selected schemas are not migrated. Schema objects that depend on Supabase roles, Auth functions, other schemas, or unavailable extensions may need changes before the import can succeed.
Row-level security policies are retained. A policy referring to an unavailable role or function can make the restore fail; the importer does not silently remove these policies.
Prepare the connection
- Have PostgreSQL set up on the destination machine and enough free disk space for the transfer and restored database.
- Get your Supabase PostgreSQL connection string. Use its direct endpoint or session pooler; the session pooler on port 5432 works when the VPS needs IPv4. Direct connections may need IPv6.
- Do not use the transaction pooler on port 6543. This flow supports Supabase's direct and shared session-pooler domains, not arbitrary PostgreSQL or custom/self-hosted Supabase hosts.
- Choose the application schemas to copy. The default is public. Check dependencies before excluding another schema.
- For a final cutover, plan a pause in application writes and take an independent backup. New writes after the snapshot will not be copied automatically.
Treat the connection string as a password. Enter it directly into the import dialog rather than pasting it into an agent conversation or command-line history.
If the destination VPS already hosts application databases, back them up before approving a PostgreSQL upgrade. ForgeVPS's Backups dialog protects managed databases on that VPS; arrange the source Supabase backup separately.
Start the import
- Open the machine's Databases tab and choose Import.
- Enter the Supabase connection string, a new destination database name, and the application schemas.
- Review connection and PostgreSQL version checks. The destination must be at least the source major version; installing a newer dump client alone does not make a downgrade work.
- Start the import. If an upgrade is required, review the separate confirmation before choosing Upgrade and import.
- Follow the job's progress in Databases. It runs on the machine and continues if you close or refresh the page. Only one import can run on a machine at a time.
When PostgreSQL needs upgrading
The preview lists affected databases, extensions, disk requirements, and blockers. Upgrading affects the local cluster and can interrupt every app using it, including a self-hosted panel. Do not approve it as a routine retry.
Automatic upgrades cover supported standard Debian/Ubuntu host clusters. Replication, custom configuration, or unavailable extensions can require a manual upgrade. Review downtime and recovery needs with the machine owner before proceeding.
If the cluster upgrade succeeds but the import fails, PostgreSQL stays upgraded. An import failure does not automatically roll back the cluster. Recovery files are retained locally; they are not an off-machine disaster backup.
Verify before switching your application
- Open the new database and inspect the expected tables, representative rows, schema objects, and application behavior.
- Use Connect to obtain the destination connection string. The imported database has its own role and password; Supabase ownership and grants are not reused.
- Update the app's database configuration and restart the intended app when you are ready. ForgeVPS does not rewrite application environments automatically.
- Test reads and writes, generated IDs, constraints, and permissions. Keep the source and your backup until the migration has been verified.
If the import fails
Read the reported error and private job log path. Typical causes include unreachable Supabase endpoints, a source version newer than the destination, schema dependencies, unsupported extensions, or a destination name already in use.
A handled failure cleans up the database and role created by that import. A hard kill or machine restart can leave an unpublished destination or recovery files. Inspect the recorded state before retrying; do not delete existing databases or import directories indiscriminately.
For an interrupted PostgreSQL upgrade, use the recovery README in the job's recovery directory before restarting clusters. Share only a redacted error excerpt when asking for help.