Prisma Integration#

Overview#

Cedar integrates Prisma as its database layer for API-side services. The most operationally significant part of this integration is schema synchronization during test setup: before each test run, Cedar pushes your Prisma schema to the test database so it matches the current state of schema.prisma. This sync runs automatically via Jest's globalSetup or Vitest's custom environment, and is controlled by several environment variables.

Schema Sync During Test Setup#

When you run cedar test, the following happens before tests execute:

1. cedar test CLI handler sets DATABASE_URL to TEST_DATABASE_URL (if set) or falls back to a SQLite file at .cedar/test.db 1. It also calls warnIfNonStandardDatasourceUrl() when the api side is included 2.

2. Jest globalSetup (packages/testing/src/config/jest/api/globalSetup.ts) or the Vitest custom environment (CedarApiVitestEnv.ts) runs the Prisma schema sync command:

   • Default strategy: prisma db push --force-reset --accept-data-loss
   • reset strategy (when TEST_DATABASE_STRATEGY=reset): prisma migrate reset --force

Controlling Schema Sync#

The --no-db-push flag sets SKIP_DB_PUSH=1 via the CLI handler 3. Both the Jest globalSetup 4 and Vitest environment 5 respect this flag.

Datasource Warning (datasourceWarning.ts)#

packages/cli/src/commands/test/datasourceWarning.ts exports warnIfNonStandardDatasourceUrl(), which runs before Jest/Vitest starts (while the process still has an interactive TTY).

It parses the Prisma config file for a url: env(...) line 6. If the datasource URL env var is anything other than DATABASE_URL, it warns the user and prompts for confirmation — since Cedar only overrides DATABASE_URL (and optionally DIRECT_DATABASE_URL) during testing, a custom name risks running destructive commands against a non-test database 7.

Pass --force to suppress the interactive prompt 8.

Known Limitation: No Provider/URL Protocol Validation#

There is no validation that the Prisma schema provider matches the resolved DATABASE_URL protocol.

The classic failure mode (tracked in issue #2284):

• schema.prisma declares provider = "postgresql"
• TEST_DATABASE_URL is unset in .env
• The CLI falls back to file:.cedar/test.db (a SQLite path)
• prisma db push is invoked with a SQLite URL against a PostgreSQL schema
• Result: the process hangs indefinitely with zero output — no error, no progress indicator 9

This is especially problematic for non-interactive/agent contexts, where there is no way to distinguish "still working" from "hung forever" without an external timeout.

Workaround: Always set TEST_DATABASE_URL explicitly in .env when your schema uses any provider other than sqlite.

The fix suggested in #2284 is to detect the mismatch upfront — comparing config.datasources[0].provider against the URL scheme of the resolved test database URL — and fail fast with an actionable message before invoking Prisma 9.

Key Source Files#