Upgrading from CareNova 1.1.0 to 1.2.0

This guide is for an existing CareNova 1.1.0 installation. A fresh installation should use the complete INSTALL.sql file instead.

Before you begin

1. Back up the PostgreSQL database.

2. Record the current Supabase Auth and Storage configuration.

3. Back up the deployment environment and private secrets.

4. Keep the previous application deployment available for rollback.

5. Rehearse the complete upgrade against a staging copy before changing production.

Preserve all clinic IDs, user IDs, database URLs, Supabase keys, and payment-encryption material.

Never run INSTALL.sql, npm run db:seed, npm run setup:db, demo pruning, a database reset, or an unreviewed npm run db:push on an existing customer database.

Install the released source

Extract the 1.2.0 source into a separate directory and install the exact released dependencies:

npm ci

Do not upgrade dependencies while performing the database upgrade.

Apply the additive migrations

Configure DIRECT_DATABASE_URL with the intended Supabase session connection on port 5432, then run these commands in order:

npm run db:apply-sql -- migrations/add_patient_portal.sql
npm run db:apply-sql -- migrations/add_clinic_invoice_payments.sql

The first migration adds patient identity links and portal controls. The second adds per-clinic payment settings and payment-provider/review metadata. Neither migration moves the database to another provider.

Update the environment

Review the new .env.example and confirm at least:

• NEXT_PUBLIC_SITE_URL matches the exact production HTTPS origin.

• PATIENT_PORTAL_ENABLED is enabled only when the portal is ready.

• CRON_SECRET is a long, private random value.

• CARENOVA_PAYMENT_ENCRYPTION_KEY is a stable private value of at least 32 characters before saving Stripe credentials.

• LICENSE_VERIFICATION_ENABLED is false or unset for normal operation.

If payment settings were already encrypted, preserve the exact key material used when they were saved. Changing it without deliberately re-saving or migrating the credentials can make them unreadable.

Update Supabase Auth

Add the exact callback URL for the deployed hostname:

https://your-domain.com/auth/callback

CareNova 1.2.0 uses /auth/callback, not /auth/confirm.

Acceptance test

Before production rollout, verify that:

• Platform administrator and clinic staff sign-in still work.

• A disposable patient can sign up, confirm their email, and sign in.

• Every enabled OAuth provider returns to the intended patient or staff entry point.

• The patient can edit their profile and photo.

• A portal appointment request appears in the clinic dashboard and can be confirmed.

• The confirmed appointment appears in the portal and exports to the native calendar.

• The patient can view and download an invoice PDF.

• Bank transfer and Stripe sandbox flows settle only the intended invoice and clinic.

• Password change and disposable portal-account deletion work.

• English, French, Spanish, Arabic/RTL, light mode, dark mode, and mobile layouts remain correct.

Rollback

If the application must be rolled back, restore the previous deployment version. Do not automatically remove the additive 1.2.0 schema or discard portal/payment records that may already exist. Preserve the payment-encryption key and reconcile any payments recorded during the rollout window.