#Migrate self-hosted into convex cloud

1 messages · Page 1 of 1 (latest)

quasi ibex
#

How can I migrate a self-hosted convex instance to the cloud hosted instance?

oak flameBOT
#

Hi @quasi ibex. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

To migrate from a self-hosted Convex instance to the Convex cloud-hosted service, you can use the built-in export and import tools.

1. Export Data from Self-Hosted

First, you need to capture the current state of your self-hosted database. Ensure you stop external traffic to your instance before exporting to avoid losing data that might be written during the process [Software upgrades].

Run the following command to export your data to a zip file:

npx convex export --path ~/Downloads/my-data.zip

[Data Export]

2. Prepare the Cloud Project

If you haven't already, create a Convex account and link your project:

  1. Run npx convex login to authenticate with the cloud service [Trying out Convex].
  2. Ensure your local environment is configured for the cloud deployment by removing self-hosted environment variables (like CONVEX_SELF_HOSTED_URL) from your .env.local [Self-hosting setup].

3. Import Data to the Cloud

Once your CLI is pointed at the cloud deployment, import the data you exported in step 1:

npx convex import --replace-all ~/Downloads/my-data.zip

[Self-hosting setup]

#

4. Migrate Environment Variables and Code

  • Environment Variables: You will need to manually migrate any secrets or environment variables. You can list them from your self-hosted instance using npx convex env list and set them in the cloud using the Convex dashboard or npx convex env set [Software upgrades].
  • Code Deployment: Deploy your functions and schema to the cloud instance using:
    npx convex deploy
    [Deploying your app]

5. Update Frontend Client

Finally, update your frontend's environment variables (e.g., VITE_CONVEX_URL) to point to the new Convex cloud URL instead of your self-hosted URL [Self-hosting setup].

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@quasi ibex Kapa.ai is still learning and improving, please let me know how I did by reacting below.

quasi ibex
#

@oak flame it tries to export the dev environment, how do I export the prod?

oak flameBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

To export data from your production deployment instead of your local development environment, you can use the --prod flag with the npx convex export command.

Run the following command in your terminal:

npx convex export --prod --path ~/Downloads/prod_backup.zip

How the CLI determines the deployment:

  • By default: Commands like export target your development deployment (configured in your local environment variables).
  • Production flag: Adding --prod tells the CLI to target the production deployment associated with your current project [Export data to a file; Production deployment].
  • Deploy Keys: If you are running this in a CI/CD environment or a script where you cannot log in interactively, ensure the CONVEX_DEPLOY_KEY environment variable is set. The CLI will then automatically target the deployment associated with that specific key [Deploy keys].

If you also need to include files from Convex File Storage in your export, you should add the --include-file-storage flag:

npx convex export --prod --include-file-storage --path ~/Downloads/prod_backup.zip

[Export data to a file]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@quasi ibex Kapa.ai is still learning and improving, please let me know how I did by reacting below.

quasi ibex
#

@oak flame

npx convex export --prod --include-file-storage --path ../../export/31122025.zip
✖ The `--prod`, `--preview-name`, and `--deployment-name` flags cannot be used with a self-hosted deployment.
oak flameBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

I'm sorry, but the knowledge sources do not explicitly mention a --prod equivalent flag for self-hosted deployments. In the self-hosted version of Convex, the concepts of "dev" and "prod" are managed by you through different backend instances rather than through CLI flags like --prod or --deployment-name [Self-hosting setup].

To export from your self-hosted production instance, you must ensure your CLI is pointing directly to that specific instance's URL and Admin Key. You can do this by temporarily setting environment variables in your shell before running the command:

CONVEX_SELF_HOSTED_URL="<https://your-production-api-url"> \
CONVEX_SELF_HOSTED_ADMIN_KEY="your-production-admin-key" \
npx convex export --include-file-storage --path ../../export/31122025.zip

Why this is happening:

  • Flag Limitation: The flags --prod, --preview-name, and --deployment-name are designed for the Convex Cloud service, where one project contains multiple managed deployments.
  • Self-Hosted Logic: For self-hosting, the CLI determines which instance to talk to based solely on CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY [Self-hosting setup].
  • Environment Mixing: The CLI will not allow a mix of cloud flags and self-hosted environment variables to prevent accidental deployments or exports from the wrong location [Self-hosting setup].
#

If you have these variables saved in a .env.local file, they are likely pointing to your development instance. Overriding them in the command line as shown above is the standard way to target your production instance [Self-hosting Convex].

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@quasi ibex Kapa.ai is still learning and improving, please let me know how I did by reacting below.

quasi ibex
#

@oak flame how do I unlink the project?

oak flameBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

To unlink a project or stop using specific deployment configurations in Convex, the method depends on whether you are using local development, a cloud-hosted project, or self-hosting.

For Local or Anonymous Deployments

If you are developing against a local backend and want to stop the CLI from using it for your current project, run:

npx convex disable-local-deployments

[Local Deployments for Development]

If you are using anonymous development (without an account) and want to remove old projects from the CLI's suggestion list, you must manually edit the state file on your machine. Delete the project entries from:
~/.convex/anonymous-convex-backend-state
[Discord support thread]

For Cloud-Hosted Projects

To remove the association between your local folder and a Convex Cloud project:

  1. Delete Environment Variables: Remove the CONVEX_DEPLOYMENT and any related Convex URL variables from your .env.local file. This is the primary way the CLI "links" your local directory to a specific deployment [Project Configuration].
  2. Logout: To remove your user credentials from your machine entirely so the CLI no longer recognizes your account, run:
    npx convex logout
    [CLI]

For Self-Hosted Projects

To unlink a self-hosted instance, remove the following variables from your .env.local file:

  • CONVEX_SELF_HOSTED_URL
  • CONVEX_SELF_HOSTED_ADMIN_KEY
#

Once these are removed, the CLI will no longer attempt to communicate with your self-hosted backend [Self-hosting setup].

Deleting a Project Entirely

If by "unlink" you mean permanently deleting the project from the Convex Cloud:

  1. Go to the Convex Dashboard.
  2. Click the triple-dot ⋮ button on the Project card.
  3. Select Delete. This will permanently remove all data and deployments associated with that project [Projects].

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@quasi ibex Kapa.ai is still learning and improving, please let me know how I did by reacting below.

quasi ibex
#

@oak flame How do I do a prod import?

oak flameBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

To perform a data import into your production deployment, you use the --prod flag. This flag tells the Convex CLI to target your production database instead of your personal development deployment [Data Import].

Single Table Import

To import a specific CSV, JSON, or JSONLines file into a table in production:

npx convex import --prod --table <tableName> <path-to-file>

If the table already contains data, you must also specify either --append or --replace [Seeding Data for Preview Deployments].

Restore from a ZIP Backup

To restore an entire deployment (including multiple tables and potential file storage) from a ZIP file into production:

npx convex import --prod --replace <path-to-backup>.zip

The --replace flag is required if the tables mentioned in the ZIP already exist in your production environment [Data Import].

#

Important Considerations

  • Authentication: You must be logged in via npx convex login or have a valid CONVEX_DEPLOY_KEY set in your environment to target production [Deploying your app; Deploy].
  • Atomic Replacement: Imports create and replace tables atomically. This means your queries and mutations will not see partial data during the import process [Data Import].
  • Self-Hosted Limitation: If you are using a self-hosted instance, the --prod flag is not supported. Instead, you must point the CLI to your production instance by setting the CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY environment variables [Self-hosting setup].

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@quasi ibex Kapa.ai is still learning and improving, please let me know how I did by reacting below.

quasi ibex
#

@oak flame it's not importing to prod with the --prod flag, but to dev and then errors because tables aready exist

oak flameBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

I'm sorry, but the knowledge sources do not explicitly mention a bug where the --prod flag fails to target production and defaults to dev instead. However, based on the documentation, there are a few reasons why this behavior or error might be occurring:

1. Missing the --replace or --append Flag

If the CLI is correctly targeting production but the tables already exist, the import will fail by default to prevent accidental data loss. You must explicitly tell Convex how to handle existing data:

  • To overwrite everything: Add the --replace flag.
  • To add to existing data: Add the --append flag (for single table imports).
npx convex import --prod --replace <path>.zip

[Data Import; Seeding Data]

2. Environment Variable Conflicts

If you have CONVEX_SELF_HOSTED_URL or CONVEX_SELF_HOSTED_ADMIN_KEY set in your current shell or .env.local, the CLI may be ignoring the --prod flag because those variables force the CLI into "self-hosted mode," which does not support the --prod flag [Self-hosting setup]. Ensure these variables are unset if you are trying to target Convex Cloud.

#

3. Verification of Deployment

You can verify which deployment the CLI is actually hitting by checking the output logs. When you run the command, it should explicitly state which deployment it is connecting to. If it still appears to hit dev, try explicitly providing the deployment name:

npx convex import --deployment-name <your-prod-deployment-name> --replace <path>.zip

[Discord support thread]

4. Clearing Data Before Import

If you are trying to perform a clean import and want to ensure no conflicts exist, you can clear a table first by importing an empty file with --replace:

npx convex import --prod --table <tableName> --replace /dev/null

[Tips when starting out; Data Import]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: