Skip to content

Conversation

@jkomyno
Copy link
Contributor

@jkomyno jkomyno commented Dec 10, 2025

This PR:

  • fixes TML-1673
  • adds a new e2e test, prisma-config-generate-doesnt-need-valid-url
  • updates the import { env } from 'prisma/config''s error message
    • before: "Missing required environment variable: UNDEFINED_VARIABLE"
    • after: "Cannot resolve environment variable: UNDEFINED_VARIABLE."

After this PR:

  • prisma generate works when the datasource.url value in the Prisma config file is undefined:

    // prisma.config.ts
    import { defineConfig } from 'prisma/config'
    
    export default defineConfig({
      datasource: {
        url: process.env['UNDEFINED_VARIABLE'],
      },
    })
  • prisma generate still fails when the datasource.url value in the Prisma config file uses the env utility with an undefined variable:

    // prisma.config.ts
    import { defineConfig, env } from 'prisma/config'
    
    export default defineConfig({
      datasource: {
        url: env('UNDEFINED_VARIABLE'),
      },
    })

    The error looks like: Failed to load config file "[path]/prisma.config.ts" as a TypeScript/JavaScript module. Error: PrismaConfigEnvError: Missing required environment variable: UNDEFINED_VARIABLE.

  • prisma db push still fails when the datasource.url value in the Prisma config file is undefined.
    The error looks like: Error: The datasource.url property is required in your Prisma config file when using prisma db push..

Summary by CodeRabbit

Release Notes

  • New Features

    • Datasource URL is now optional in Prisma configuration files, allowing prisma generate to succeed without a valid database URL.
  • Bug Fixes

    • Enhanced error messages to specify exactly which configuration property is required (datasource.url instead of datasource).
    • Improved environment variable resolution error messages for clarity when variables cannot be resolved.

✏️ Tip: You can customize this high-level summary in your review settings.

@jkomyno jkomyno added this to the 7.2.0 milestone Dec 10, 2025
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Dec 10, 2025

Walkthrough

This PR makes the datasource.url property optional in Prisma configurations and refines validation error messages. A new end-to-end test verifies that prisma generate succeeds without a valid datasource URL, while operations requiring database access still enforce the URL requirement. Error messages are updated to distinguish between missing configuration properties and unresolvable environment variables.

Changes

Cohort / File(s) Summary
Config type and validation updates
packages/config/src/PrismaConfig.ts, packages/internals/src/utils/validatePrismaConfigWithDatasource.ts, packages/config/src/env.ts
Made DatasourceShape.url optional; updated PrismaConfigWithDatasource type to require datasource.url specifically; changed error message from "Missing required environment variable" to "Cannot resolve environment variable"; updated validation logic to check for datasource.url presence
Config package tests
packages/config/src/__tests__/env.test.ts, packages/config/src/__tests__/loadConfigFromFile.test.ts
Updated test expectations to reflect new error message text; added tests for undefined environment variable handling during config loading
Config test fixtures
packages/config/src/__tests__/fixtures/loadConfigFromFile/datasource-url-undefined/*
Added fixture configs referencing undefined environment variables via both process.env and env() helper
CLI package changes
packages/cli/src/__tests__/commands/Generate.test.ts, packages/cli/src/__tests__/incomplete-schemas.test.ts, packages/cli/src/utils/loadConfig.ts
Updated test expectations for error messages; added handling for PrismaConfigEnvError in config loading with diagnostic logging
Migrate package tests
packages/migrate/src/__tests__/Db*.test.ts, packages/migrate/src/__tests__/Migrate*.test.ts
Updated test assertions across all migration command tests to expect "datasource.url" requirement instead of general "datasource" in error messages
E2E test suite
packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/*
Added new end-to-end test directory with package setup, config files (including ones with undefined env vars), Prisma schema, test steps, and TypeScript configuration verifying prisma generate succeeds without valid datasource URL

Possibly related PRs

  • prisma/prisma#28860: Relates to datasource URL configuration validation and error message handling for config overrides.

Suggested labels

lgtm

Suggested reviewers

  • FGoessler
  • aqrln

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. You can run @coderabbitai generate docstrings to improve docstring coverage.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes the main change: making datasource.url optional to allow undefined URLs for commands like prisma generate.
✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch feat/config-allow-undefined-urls-prisma-generate

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions
Copy link
Contributor

github-actions bot commented Dec 10, 2025

size-limit report 📦

Path Size
packages/client/runtime/index-browser.js 2.23 KB (0%)
packages/client/runtime/index-browser.d.ts 3.28 KB (0%)
packages/cli/build/index.js 2.52 MB (+0.01% 🔺)
packages/client/prisma-client-0.0.0.tgz 10.24 MB (-0.01% 🔽)
packages/cli/prisma-0.0.0.tgz 6.71 MB (+0.01% 🔺)
packages/bundle-size/da-workers-libsql/output.tgz 805.36 KB (0%)
packages/bundle-size/da-workers-neon/output.tgz 859.4 KB (0%)
packages/bundle-size/da-workers-pg/output.tgz 852.34 KB (0%)
packages/bundle-size/da-workers-planetscale/output.tgz 804.91 KB (0%)
packages/bundle-size/da-workers-d1/output.tgz 788.27 KB (0%)

@jkomyno jkomyno marked this pull request as ready for review December 10, 2025 14:11
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f27b66b and a2bc4e6.

⛔ Files ignored due to path filters (1)
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (26)
  • packages/cli/src/__tests__/commands/Generate.test.ts (1 hunks)
  • packages/cli/src/__tests__/incomplete-schemas.test.ts (13 hunks)
  • packages/cli/src/utils/loadConfig.ts (2 hunks)
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/README.md (1 hunks)
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/_steps.ts (1 hunks)
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/package.json (1 hunks)
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/prisma.config.ts (1 hunks)
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/src/prisma.config.process-env.ts (1 hunks)
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/src/prisma.config.using-env-helper.ts (1 hunks)
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/src/prisma/schema.prisma (1 hunks)
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/tsconfig.json (1 hunks)
  • packages/config/src/PrismaConfig.ts (1 hunks)
  • packages/config/src/__tests__/env.test.ts (1 hunks)
  • packages/config/src/__tests__/fixtures/loadConfigFromFile/datasource-url-undefined-env/prisma.config.ts (1 hunks)
  • packages/config/src/__tests__/fixtures/loadConfigFromFile/datasource-url-undefined/prisma.config.ts (1 hunks)
  • packages/config/src/__tests__/loadConfigFromFile.test.ts (1 hunks)
  • packages/config/src/env.ts (1 hunks)
  • packages/internals/src/utils/validatePrismaConfigWithDatasource.ts (3 hunks)
  • packages/migrate/src/__tests__/DbDrop.test.ts (1 hunks)
  • packages/migrate/src/__tests__/DbExecute.test.ts (1 hunks)
  • packages/migrate/src/__tests__/DbPush.test.ts (1 hunks)
  • packages/migrate/src/__tests__/MigrateDeploy.test.ts (1 hunks)
  • packages/migrate/src/__tests__/MigrateDev.test.ts (1 hunks)
  • packages/migrate/src/__tests__/MigrateReset.test.ts (1 hunks)
  • packages/migrate/src/__tests__/MigrateResolve.test.ts (1 hunks)
  • packages/migrate/src/__tests__/MigrateStatus.test.ts (1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ts,tsx,js,jsx}: Use kebab-case for new file names (e.g., query-utils.ts, filter-operators.test.ts)
Avoid creating barrel files (index.ts that re-export from other modules). Import directly from the source file (e.g., import { foo } from './utils/query-utils' not import { foo } from './utils'), unless ./utils/index.ts file already exists

Files:

  • packages/migrate/src/__tests__/DbDrop.test.ts
  • packages/migrate/src/__tests__/MigrateDev.test.ts
  • packages/cli/src/__tests__/incomplete-schemas.test.ts
  • packages/config/src/env.ts
  • packages/config/src/__tests__/loadConfigFromFile.test.ts
  • packages/config/src/PrismaConfig.ts
  • packages/cli/src/utils/loadConfig.ts
  • packages/config/src/__tests__/env.test.ts
  • packages/migrate/src/__tests__/MigrateDeploy.test.ts
  • packages/migrate/src/__tests__/MigrateResolve.test.ts
  • packages/migrate/src/__tests__/DbPush.test.ts
  • packages/cli/src/__tests__/commands/Generate.test.ts
  • packages/migrate/src/__tests__/DbExecute.test.ts
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/_steps.ts
  • packages/migrate/src/__tests__/MigrateStatus.test.ts
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/src/prisma.config.process-env.ts
  • packages/internals/src/utils/validatePrismaConfigWithDatasource.ts
  • packages/config/src/__tests__/fixtures/loadConfigFromFile/datasource-url-undefined/prisma.config.ts
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/src/prisma.config.using-env-helper.ts
  • packages/config/src/__tests__/fixtures/loadConfigFromFile/datasource-url-undefined-env/prisma.config.ts
  • packages/migrate/src/__tests__/MigrateReset.test.ts
  • packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/prisma.config.ts
**/*.test.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

Test files named *.test.ts are excluded from build output via esbuild config; place tests alongside source files

Files:

  • packages/migrate/src/__tests__/DbDrop.test.ts
  • packages/migrate/src/__tests__/MigrateDev.test.ts
  • packages/cli/src/__tests__/incomplete-schemas.test.ts
  • packages/config/src/__tests__/loadConfigFromFile.test.ts
  • packages/config/src/__tests__/env.test.ts
  • packages/migrate/src/__tests__/MigrateDeploy.test.ts
  • packages/migrate/src/__tests__/MigrateResolve.test.ts
  • packages/migrate/src/__tests__/DbPush.test.ts
  • packages/cli/src/__tests__/commands/Generate.test.ts
  • packages/migrate/src/__tests__/DbExecute.test.ts
  • packages/migrate/src/__tests__/MigrateStatus.test.ts
  • packages/migrate/src/__tests__/MigrateReset.test.ts
🧬 Code graph analysis (4)
packages/config/src/__tests__/loadConfigFromFile.test.ts (3)
packages/config/src/loadConfigFromFile.ts (1)
  • loadConfigFromFile (92-168)
packages/config/src/index.ts (1)
  • loadConfigFromFile (5-5)
packages/config/src/__tests__/fixtures/loadConfigFromFile/invalid/no-default-export/prisma.config.ts (1)
  • config (3-5)
packages/cli/src/utils/loadConfig.ts (2)
packages/config/src/index.ts (1)
  • PrismaConfigEnvError (3-3)
packages/internals/src/index.ts (1)
  • HelpError (15-15)
packages/config/src/__tests__/env.test.ts (2)
packages/config/src/env.ts (2)
  • env (14-20)
  • PrismaConfigEnvError (1-6)
packages/config/src/index.ts (2)
  • env (3-3)
  • PrismaConfigEnvError (3-3)
packages/internals/src/utils/validatePrismaConfigWithDatasource.ts (1)
packages/config/src/PrismaConfig.ts (3)
  • PrismaConfig (198-231)
  • Datasource (26-29)
  • SchemaEngineConfigInternal (31-33)
🔇 Additional comments (25)
packages/config/src/PrismaConfig.ts (1)

21-29: LGTM! Type change correctly makes datasource.url optional.

The change from required to optional for both the Shape definition and TypeScript type is consistent and aligns with the PR objective to allow prisma generate without a valid datasource URL. Command-level validation (as evidenced by updated test expectations across migrate commands) ensures operations requiring database access still enforce the URL requirement.

packages/migrate/src/__tests__/MigrateDeploy.test.ts (1)

12-19: LGTM! Test expectation correctly updated to reference datasource.url property.

The updated error message is more specific about the required configuration property, consistent with the broader validation refinements in this PR.

packages/migrate/src/__tests__/DbPush.test.ts (1)

17-24: LGTM! Test expectation correctly updated to reference datasource.url property.

Consistent with validation message updates across other migrate commands.

packages/migrate/src/__tests__/MigrateResolve.test.ts (1)

10-19: LGTM! Test expectation correctly updated to reference datasource.url property.

Aligns with validation refinements across migrate commands.

packages/migrate/src/__tests__/DbExecute.test.ts (1)

33-44: LGTM! Test expectation correctly updated to reference datasource.url property.

Maintains consistency with validation message refinements across migrate commands.

packages/config/src/env.ts (1)

1-6: LGTM! Improved error message clarity.

The updated message "Cannot resolve environment variable" is more accurate than "Missing required environment variable" as it covers both missing and empty-string scenarios. The change also improves consistency by adding a trailing period.

packages/config/src/__tests__/env.test.ts (2)

26-31: LGTM! Test expectation correctly updated.

The inline snapshot matches the refined error message from PrismaConfigEnvError.


33-39: LGTM! Test expectation correctly updated.

Consistent with the updated error message for unresolvable environment variables.

packages/migrate/src/__tests__/MigrateReset.test.ts (1)

8-17: LGTM! Test expectation correctly updated to reference datasource.url property.

Completes the consistent validation message refinement across all migrate commands.

packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/src/prisma.config.process-env.ts (1)

1-7: LGTM!

The test configuration correctly uses process.env['UNDEFINED_VARIABLE'] to test the scenario where datasource.url is undefined. According to the PR objectives, prisma generate should succeed in this case.

packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/src/prisma.config.using-env-helper.ts (1)

1-7: LGTM!

The test configuration correctly uses env('UNDEFINED_VARIABLE') to test the scenario where the env helper is used with an undefined variable. According to the PR objectives, this approach should fail with a PrismaConfigEnvError, which provides the expected behavior for required environment variables.

packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/package.json (1)

1-16: LGTM!

The package.json configuration is appropriate for an e2e test, with all necessary dependencies included. The use of local tarball paths for Prisma packages is standard practice for testing.

packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/src/prisma/schema.prisma (1)

1-35: LGTM!

The Prisma schema is well-structured with proper model definitions and relations. The datasource intentionally omits the url property as it will be provided by the Prisma config file, which aligns with the test's purpose.

packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/tsconfig.json (1)

1-4: LGTM!

The TypeScript configuration correctly extends the base config and excludes the _steps.ts file, which is standard practice for e2e test suites.

packages/migrate/src/__tests__/DbDrop.test.ts (1)

14-21: LGTM!

The updated error message correctly specifies that datasource.url is required rather than the generic datasource, providing clearer guidance to users. This aligns with the PR's goal of making datasource validation more specific.

packages/migrate/src/__tests__/MigrateDev.test.ts (1)

57-65: LGTM!

The updated error message correctly specifies that datasource.url is required for prisma migrate dev, providing clearer and more actionable feedback. This change is consistent with the broader PR effort to make datasource validation more specific.

packages/cli/src/__tests__/commands/Generate.test.ts (1)

19-25: Error message expectation correctly updated to datasource.url.

The snapshot now matches the more precise config validation (“The datasource.url property is required…”), which aligns with the new behavior for prisma generate --sql.

packages/cli/src/utils/loadConfig.ts (1)

1-6: Warning diagnostic for PrismaConfigEnvError is well-scoped and non-breaking.

Importing PrismaConfigEnvError and pushing a warn diagnostic only when the inner error matches cleanly augments CLI feedback, while still returning the same HelpError for the load failure. This keeps behavior stable while exposing the env-resolution detail.

Also applies to: 26-38

packages/migrate/src/__tests__/MigrateStatus.test.ts (1)

7-15: Status error snapshot now correctly targets datasource.url.

The expectation string for prisma migrate status is consistent with the new requirement that datasource.url (not just datasource) be present in the Prisma config.

packages/config/src/__tests__/fixtures/loadConfigFromFile/datasource-url-undefined/prisma.config.ts (1)

1-7: Fixture correctly models datasource.url coming from process.env as undefined.

Using process.env['UNDEFINED_VARIABLE'] here is appropriate for exercising the “raw env yields undefined but is accepted” path in loadConfigFromFile.

packages/cli/src/__tests__/incomplete-schemas.test.ts (2)

101-197: Env-unset snapshots now match PrismaConfigEnvError wording.

All expectations switched from “Missing required environment variable” to “Cannot resolve environment variable: SOME_UNDEFINED_DB.”, which aligns with the new PrismaConfigEnvError message and the wrapped HelpError text.


213-274: Config-validation snapshots consistently require datasource.url.

The updated messages for db push/pull/execute and migrate reset/dev now explicitly mention The datasource.url property is required…, matching the stricter config validation and improving guidance for users.

packages/config/src/__tests__/fixtures/loadConfigFromFile/datasource-url-undefined-env/prisma.config.ts (1)

1-7: Fixture correctly targets the env()-helper failure path.

Importing env and setting datasource.url: env('UNDEFINED_VARIABLE') is the right setup for tests that expect a ConfigLoadError wrapping PrismaConfigEnvError.

packages/client/tests/e2e/prisma-config-generate-doesnt-need-valid-url/prisma.config.ts (1)

1-8: E2E Prisma config uses defineConfig and datasource.url correctly.

The config object (file-based SQLite URL plus explicit schema path) is well-formed and matches the new prisma/config entrypoint usage expected in the e2e suite.

packages/internals/src/utils/validatePrismaConfigWithDatasource.ts (1)

1-1: LGTM: Validation now correctly enforces datasource.url requirement.

The changes improve specificity by:

  • Requiring datasource.url to be a string (not just datasource to exist)
  • Updating the type definition to reflect this requirement
  • Providing a clearer error message that references datasource.url specifically

This aligns with the PR objectives and ensures commands that need database access (e.g., prisma db push) properly validate the URL presence, while allowing prisma generate to work without it.

Also applies to: 18-20, 23-23, 37-37

@igalklebanov
Copy link
Contributor

igalklebanov commented Dec 15, 2025

Hey 👋

This still failing for env(...) usage, which is the main path according to docs, is not really fixing the problem (unless I'm missing something).

If a command doesn't require a config thing, it should work when the thing is not available - regardless how the thing is provided (e.g. the env() helper). Anything else is bad DX.

The responsibility of deciding what should throw should be the command's. The config loader should do best effort and report (not throw) missing things.

@jkomyno
Copy link
Contributor Author

jkomyno commented Dec 16, 2025

Hey 👋

This still failing for env(...) usage, which is the main path according to docs, is not really fixing the problem (unless I'm missing something).

If a command doesn't require a config thing, it should work when the thing is not available - regardless how the thing is provided (e.g. the env() helper). Anything else is bad DX.

The responsibility of deciding what should throw should be the command's. The config loader should do best effort and report (not throw) missing things.

That's by design. env()'s whole purpose is to raise the error PrismaConfigEnvError: Missing required environment variable $VARIABLE_NAME when process.env[$VARIABLE_NAME] resolves to undefined. And, since it was shipped in Prisma 7.0.0, we can't suddenly break this behavior.

Now, I've already shared with the docs team (in the past 10 days or so) that env() should NOT be the default option shown in our guides / tutorials.

What this PR does, is to allow the process.env[$VARIABLE_NAME] == undefined case not to trigger an error in prisma.config.ts' loader, which is an improvement over the previous DX, and the main point of TML-1673 altogether.

@igalklebanov
Copy link
Contributor

That's by design. env()'s whole purpose is to raise the error PrismaConfigEnvError: Missing required environment variable $VARIABLE_NAME when process.env[$VARIABLE_NAME] resolves to undefined.

But that doesn't matter for commands that don't require or use the config property it was invoked for. Nobody's expecting env() should throw for datasource.url if I run prisma generate. That's too rigid.

Sometimes people run these commands without providing the envars they normally would for others. e.g. a GitHub workflow that generates the client and then runs tsc --noEmit should not have access to a connection string or other secrets.

@dosubot dosubot bot added the lgtm This PR has been approved by a maintainer label Dec 16, 2025
@jkomyno jkomyno merged commit ed03287 into main Dec 16, 2025
255 checks passed
@jkomyno jkomyno deleted the feat/config-allow-undefined-urls-prisma-generate branch December 16, 2025 10:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

lgtm This PR has been approved by a maintainer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants