Skip to main content

Vercel migrations

· 5 min read
Serhii Hrekov
Serhii Hrekov
software engineer, creator, artist, programmer, projects founder

Vercel doesn't have a single, built-in migration system but instead relies on standard, database-specific tools. For relational databases like Vercel Postgres, you use traditional ORMs or migration libraries. For key-value stores like Vercel KV, migration is typically a manual process of data transformation.

Vercel Postgres Migrations​

For Vercel Postgres, the most common and recommended approach is to use an ORM (Object-Relational Mapper) with a migration tool. These tools let you manage your database schema in a version-controlled way, ensuring that every deployment has the correct database structure.

1. Using an ORM (Prisma or Drizzle)​

ORMs like Prisma and Drizzle are popular choices for managing Vercel Postgres migrations.

  • Prisma: With Prisma, you define your database schema in a schema.prisma file. You can then use the Prisma CLI to generate migration files based on changes to this schema. The command npx prisma migrate dev creates a new migration file and applies it to your development database [4]. When deploying to Vercel, you can configure your build command to run the migrations (e.g., npx prisma migrate deploy) to ensure the production database is always up to date.
  • Drizzle: Drizzle ORM offers a similar migration workflow. You define your schema using Drizzle's API, and the drizzle-kit generate command creates the necessary SQL migration files. You can then run these migrations either manually or as part of your Vercel build process [2].

2. Manual SQL Migrations​

If you prefer not to use an ORM, you can use a migration tool like Flyway or Liquibase to manage raw SQL migration files. These tools track which migration files have been applied to the database, giving you full control over the schema changes [3].

Vercel KV and Edge Config Migrations​

Unlike relational databases, key-value stores like Vercel KV and Edge Config don't have a schema to migrate in the traditional sense. Migration is a process of data transformation and synchronization.

  • Vercel KV: Migrating data in Vercel KV typically involves writing a script to read data from one key format, transform it, and write it to a new key format. Because KV is often used for caching or temporary data, a common "migration" strategy is simply to invalidate the cache and let the new data format be generated on the next request.
  • Vercel Edge Config: Edge Config data can be managed through the Vercel Dashboard or its API [1]. You can export the current configuration, make changes, and then update the store. Vercel provides a backup and restore functionality to roll back to a previous state if an update goes wrong.

Best Practices​

  • Automate in the Build Step: The best practice for Vercel Postgres is to run migrations as part of your build command. For example, your vercel-build script could be npm run build && npx prisma migrate deploy. This ensures that every successful deployment corresponds to a fully migrated database.
  • Use Vercel's Environment Variables: Always use Vercel's environment variables for your database connection strings. This allows you to connect to a different database for each environment (e.g., a separate database for a preview deployment) [2].
  • No-Downtime Migrations: For a seamless user experience, aim for non-breaking schema changes (like adding a new column) or use an incremental migration strategy to migrate your data in small steps without downtime.

Here is a video that shows how to integrate a Postgres database using Prisma and Next.js and then deploy it to Vercel, which includes the migration process. How to Integrate a Postgres Database in your Vercel & NextJS Projects