Upgrading Cal.diy

Purpose and Scope

This page explains the supported Cal.diy upgrade path for self-hosters who already have an instance running and want to move it to the current repository version. The documented workflow is deliberately short, but each step protects a different part of the deployment: source code, workspace dependencies, database schema, environment variables, and runtime process state. Cal.diy is a self-hosted community edition, so the operator is responsible for reviewing the changes before applying them to infrastructure that stores real booking, calendar, payment, or user data.

Sources: apps/docs/content/upgrading.mdx, apps/docs/content/database-migrations.mdx

The upgrade guide belongs to the Getting Started section of the self-hosting documentation alongside Installation, Database Migrations, Docker, and Apps. That placement is important: upgrading is not just a Git operation. It is the point where application code, Prisma migrations, environment files, and app credentials meet. Treat every upgrade as a small release process, especially if the instance uses integrations such as Google Calendar or Daily video, because those integrations depend on environment variables and external provider configuration that may need to stay aligned with the upgraded application.

Sources: apps/docs/content/_meta.ts, apps/docs/content/apps/_meta.ts, apps/docs/content/apps/daily.mdx, apps/docs/content/apps/google.mdx

Relevant Source Files

• apps/docs/content/upgrading.mdx - Defines the supported command sequence: pull the current version, install dependency changes, run the appropriate Prisma migration command, check environment variables, and restart in development or production mode.
• apps/docs/content/database-migrations.mdx - Explains why upgrades should use Prisma migrations, distinguishes migration creation from migration deployment, and documents recovery commands for schema-state problems such as Prisma P3005.
• apps/docs/content/_meta.ts - Places Upgrading in the Getting Started documentation group with Installation, Database Migrations, Docker, and Apps, which signals the surrounding operational concerns for self-hosted instances.
• apps/docs/content/apps/_meta.ts - Lists the integration documentation area that may need to be revisited after an upgrade when app credentials or callbacks change.
• apps/docs/content/apps/daily.mdx - Shows an app configuration example where upgrade validation should preserve DAILY_API_KEY and the optional DAILY_SCALE_PLAN setting.
• apps/docs/content/apps/google.mdx - Shows a more complex app configuration example with OAuth redirect URIs, GOOGLE_API_CREDENTIALS, .env, .env.appStore, and app-store seeding after credentials are added.

Supported Upgrade Flow

The supported source-based upgrade starts by pulling the current version of the repository. This updates the application code and documentation to the latest state on the checked-out branch. Before doing anything destructive, review the incoming changes in the normal way for your deployment process: understand whether dependencies, database migrations, environment variables, or integration instructions changed. The official first command is simple, but it should happen in a working tree where local changes are either committed, intentionally carried, or separated from the deployment checkout.

Sources: apps/docs/content/upgrading.mdx

git pull

After the code is updated, reinstall workspace dependencies. The upgrade page explicitly calls out this step as the way to handle dependencies that were added, updated, or removed. In practice, this is the step that brings the local package graph back into agreement with the lockfile and workspace manifests expected by the new code. Skipping it can leave the server running old transitive packages or missing newly required packages, which may only surface later as build or runtime failures.

Sources: apps/docs/content/upgrading.mdx

yarn

The next step is database migration, and it is the most important decision point in the upgrade. Cal.diy documents two different commands: db-migrate for development and db-deploy for production. Use the development command when working on a local instance where data loss is acceptable, because the guide warns that it can clear a development database in some cases. Use the production command for real deployments because it applies existing migrations instead of creating or resetting local development state.

Sources: apps/docs/content/upgrading.mdx, apps/docs/content/database-migrations.mdx

yarn workspace @calcom/prisma db-migrate

yarn workspace @calcom/prisma db-deploy

Once migrations are applied, run the environment-variable check step. The upgrade guide names yarn predev as the command to check for .env variable changes. In this repository, app setup pages make clear why this matters: Daily requires DAILY_API_KEY and may use DAILY_SCALE_PLAN, while Google Calendar requires OAuth JSON in GOOGLE_API_CREDENTIALS, values in both .env and .env.appStore, and redirect URIs that match the deployed Cal.diy URL. An upgrade that changes configuration expectations can break integrations even when the web app itself starts cleanly.

Sources: apps/docs/content/upgrading.mdx, apps/docs/content/apps/daily.mdx, apps/docs/content/apps/google.mdx

yarn predev

Database Migration Concerns

Database migrations are the safety mechanism for schema changes during upgrades. The migration documentation explains that changing schema.prisma without a migration can damage or delete production data because the system may not know how to transform existing records from the old shape to the new shape. Migrations make each schema step reproducible and transparent. For operators, that means the database step is not optional housekeeping; it is the controlled way to move stored scheduling data forward with the application code.

Sources: apps/docs/content/database-migrations.mdx

When upgrading a development environment, yarn workspace @calcom/prisma db-migrate can be appropriate because it is also the command used when modifying the schema and creating a migration. When upgrading a production environment, prefer yarn workspace @calcom/prisma db-deploy, because the upgrade guide separates it as the production command. If you maintain a fork and introduce schema changes, create a short migration name that describes what changed, commit the generated migration with the code that depends on it, and inspect what Prisma generated before trusting it.

Sources: apps/docs/content/upgrading.mdx, apps/docs/content/database-migrations.mdx

The migration page also documents a common recovery case: Prisma error P3005, where the database schema is not empty and Prisma migration state does not match the actual database. Prisma tracks applied migrations in _prisma_migrations. If a database already contains schema changes, the documented repair path is to mark specific migrations as applied with yarn prisma migrate resolve --applied migration_name. That command should be used intentionally for each migration you know has already been applied, not as a blind replacement for understanding database state.

Sources: apps/docs/content/database-migrations.mdx

yarn prisma migrate resolve --applied migration_name

For local development databases that are out of sync with local migrations, the docs include a reset-oriented PostgreSQL recovery path that deletes from _prisma_migrations and then resolves migrations from the migrations directory. This is explicitly a local troubleshooting pattern, not a production upgrade shortcut. The operational rule is straightforward: production upgrades should apply migrations predictably; local environments can be reset or repaired more aggressively when the developer accepts the data consequences.

Sources: apps/docs/content/database-migrations.mdx

Docker and Runtime Restart Concerns

The official upgrade page shows source commands, but the same phases apply when the runtime is containerized: update the deployable application artifact, ensure dependencies match the new version, apply database migrations using the production migration path for real data, verify environment variables, and restart the service. Docker does not remove the need to think about database state. A new container image can contain application code that expects a newer schema, so the database migration step should be part of the rollout plan rather than a later troubleshooting action.

Sources: apps/docs/content/upgrading.mdx, apps/docs/content/database-migrations.mdx

For non-container local development, the documented restart is yarn dev. For a production build, the guide gives yarn build followed by yarn start. In any deployment model, restart only after code, dependencies, migrations, and environment checks have been handled. That sequencing reduces the chance that users hit a partially upgraded instance, such as a server running new code against an old schema or a server booting without newly required provider secrets.

Sources: apps/docs/content/upgrading.mdx

yarn dev

yarn build
yarn start

Integration and App-Store Checks After Upgrade

After an upgrade, revisit integration documentation for any providers your instance enables. The Apps metadata lists Google, Microsoft, Zoom, Daily, HubSpot, SendGrid, Stripe, Twilio, and Zoho as documented integration areas. The Google page is a good example of the amount of state that can sit outside the application: enabled APIs, OAuth consent configuration, scopes, test users, redirect URIs, downloaded OAuth JSON, .env and .env.appStore values, and app-store seeding. If scheduling relies on calendar sync, validate those flows after restart.

Sources: apps/docs/content/apps/_meta.ts, apps/docs/content/apps/google.mdx

Daily is simpler but still demonstrates the same upgrade principle. The Daily integration depends on an API key in .env, and an optional scale-plan flag enables features such as video recording. If an upgrade changes environment examples or app behavior, a server can appear healthy while a specific conferencing path fails at booking time. Include at least one smoke test for the integrations your users rely on: create a booking page, connect the relevant calendar or video app, and confirm that callbacks and generated meeting details work with the configured public URL.

Sources: apps/docs/content/apps/daily.mdx, apps/docs/content/apps/google.mdx

Compact Command Reference

Sources: apps/docs/content/upgrading.mdx, apps/docs/content/database-migrations.mdx

Next Steps

Before running the next upgrade, prepare a small checklist for your instance: back up the database, pull the code, install dependencies, run the correct Prisma command, check .env and .env.appStore, rebuild or restart the runtime, and smoke-test the integrations that matter. If a migration error appears, move to the Database Migrations documentation rather than repeatedly rerunning upgrade commands. If an integration breaks after restart, compare the current app documentation with your provider settings, callback URLs, app-store seed state, and environment values.