#How to safely perform schema updates

1 messages · Page 1 of 1 (latest)

idle belfry
#

How can I safely perform schema upgrades?

hexed doveBOT
#

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

#

To safely perform schema upgrades in Convex, you should follow a series of best practices that ensure your data and application remain consistent and available throughout the migration process:

  1. Use Optional and Union Types for Backwards Compatibility

    • When adding a new field, first add it as optional in your schema. This allows existing documents to remain valid. Once all documents have the new field set, you can make it required.
    • If you need to change a field’s type, use a union of the old and new types. Migrate your data to the new type, then update the schema to only allow the new type once all data is migrated. Convex will not let you push a schema that doesn’t match the data at rest, ensuring safety during transitions Best practices for changing data asynchronously, Stateful Online Migrations using Mutations.

  2. Migrate Data with Mutations or Bulk Edits

    • For small changes, you can use the Convex dashboard’s bulk edit feature to patch documents directly.
    • For larger datasets, write a migration mutation that paginates through your data and updates documents in batches. This allows for online migrations without downtime Lightweight Migrations, Migrating Data with Mutations.
#

  1. Handle Both Old and New Formats During Migration

    • Update your application code to handle both the old and new data formats while the migration is in progress. This is often called “dual read” or “dual write” and ensures your app works correctly regardless of the migration state Dual read vs. dual write.

  2. Push Schema and Code Changes Separately

    • First, push schema changes that allow for the new format (e.g., making a field optional). Then, update your code to use the new format. This separation allows for safer rollbacks if issues arise Best practices for changing data asynchronously.

  3. Clean Up After Migration

    • Once all data is migrated and your code no longer needs to support the old format, update your schema and code to remove support for the old format.

  4. Leverage Convex’s Schema Enforcement

    • Convex enforces that your schema matches the data at rest. You cannot push a schema that is incompatible with your current data, which helps prevent accidental data loss or corruption Typical team development workflow.

  5. Test and Validate

    • Use dry runs and validate your migrations before applying them to production. Codify your migration logic in code and verify against seed data when possible Operational maturity for production.
#

By following these steps, you can safely evolve your Convex schema with minimal risk and no downtime. For more details and code examples, see the Convex Migrations Component documentation and related guides.

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

#

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

idle belfry
#

@hexed dove When I am developing if I delete a field in my schema will it delete all that data form my development convex environment?

hexed doveBOT
#

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

#

No, deleting a field from your schema in Convex does not automatically delete the corresponding data from your development environment. If you remove a field from the schema, Convex will only allow you to push that schema if there are no documents in the database that still have data in that field. In other words, you must first remove the data from all documents (typically by making the field optional, running a migration to unset it, and then removing it from the schema). Convex enforces that the schema matches the data at rest, so it will prevent you from pushing a schema that is incompatible with your current data Best practices for changing data asynchronously, Typical team development workflow.

If you want to remove the data, you need to:

  1. Make the field optional in your schema.
  2. Run a migration or use bulk edit to unset the field in all documents.
  3. Remove the field from the schema.

Only after all data is removed will Convex allow you to remove the field from the schema. The data is not deleted automatically just by editing the schema.

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