Establish safe Prisma baseline and upgrade path for db-push-era environments

[deltawi]

Problem

Recent DeltaLLM releases are moving to a strict Prisma migration contract:

• application startup uses prisma migrate deploy
• batch-related schema changes now rely on migration history being present
• environments that were historically initialized with prisma db push can fail startup with Prisma P3005

This creates an upgrade trap for existing shared environments that have a populated schema but no _prisma_migrations baseline.

Why this matters

• New releases should deliver new features safely without forcing ad hoc production fixes.
• Existing users need a predictable upgrade path from db push-era deployments.
• Runtime startup should stay strict and fail fast on true migration problems.

Long-term solution

1. Establish a one-time baseline workflow for legacy environments

Create and document an operator procedure to:

• inspect _prisma_migrations
• compare live schema against the expected migration chain
• mark historical migrations as applied only when the schema already matches
• rerun prisma migrate deploy

This should be treated as a one-time remediation for older environments, not a recurring runtime behavior.

2. Standardize production/shared environments on prisma migrate deploy

For all non-disposable environments:

• use prisma migrate deploy only
• stop relying on prisma db push during app startup or release rollout

db push should remain a local/dev convenience only.

3. Separate migration execution from app rollout

Release flow should be:

1. run migrations explicitly
2. verify migration success
3. roll out application pods

Do not rely on the serving pod to discover migration drift during startup.

4. Fix chart and deployment defaults

The Helm chart and deployment docs should align with the strict migration contract:

• remove migrate deploy || db push --accept-data-loss fallbacks from default migration paths
• prefer a migration job or a clearly documented pre-upgrade step
• keep app startup strict

5. Add upgrade-path testing to CI/release validation

Each release should validate:

• fresh install on an empty database
• upgrade from at least the previous released version’s database snapshot

For schema-heavy releases, include representative populated data.

6. Publish a migration/upgrade runbook

Add operator docs covering:

• how to detect an unbaselined environment
• exact baseline commands
• validation before/after migration
• rollback expectations
• release-specific prerequisites

Acceptance criteria

• Operators have a documented baseline procedure for legacy db push environments.
• Helm/deployment defaults no longer suggest unsafe schema fallback paths for production.
• Release validation includes at least one real upgrade-path test.
• Future DeltaLLM releases can be adopted safely without manual firefighting for migration history drift.