fix(cli): require datasource url for running migration and db push commands

[ymc9]

Summary by CodeRabbit

• Bug Fixes
  • Database push and migrate operations now validate datasource configuration upfront before proceeding, preventing errors from missing or invalid datasource URLs during execution.

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

[coderabbitai]

Walkthrough

A new validation utility function requireDataSourceUrl is introduced in action-utils.ts to verify that datasource declarations contain a required URL field. This function is subsequently integrated into the push and migrate command handlers to validate datasource configuration before processing.

Changes

Cohort / File(s)	Summary
Datasource URL validation utility packages/cli/src/actions/action-utils.ts	New async function requireDataSourceUrl(schemaFile: string) added that loads a schema document, locates the datasource declaration, and validates the presence of a URL field. Throws CliError if validation fails.
Integration into migration & push commands packages/cli/src/actions/db.ts, packages/cli/src/actions/migrate.ts	Both files import requireDataSourceUrl from action-utils. Integration occurs early in runPush and migrate.run respectively, validating the datasource URL before schema generation and command execution.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• The new requireDataSourceUrl function logic should be verified for correct schema parsing and datasource field validation
• Integration order in both db.ts and migrate.ts should be confirmed to ensure validation occurs at appropriate points in the workflow
• Error handling and CliError messages should be reviewed for consistency and clarity

Poem

🐰 A datasource URL check, so neat and keen,
Before the push and migrate scenes!
Validation hops through schema ground,
Ensuring URLs safe are found. ✨

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 summarizes the main change: adding datasource URL validation to migration and db push commands.

✨ 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 fix/cli-require-url

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[claude]

Claude finished @ymc9's task —— View job

---

PR Review: fix(cli): require datasource url for running migration and db push commands

Review Tasks

• Read and analyze modified files
• Evaluate code quality and best practices
• Check for potential bugs or issues
• Assess performance considerations
• Review security concerns
• Evaluate test coverage needs
• Provide comprehensive feedback

---

Summary

This PR adds validation to ensure that a datasource with a url field is present in the ZModel schema before executing database migration and push commands. The change prevents runtime failures by catching missing datasource URLs early.

Code Quality & Best Practices ✅

Strengths:

• Clean separation of concerns: New validation logic is properly extracted into a reusable requireDataSourceUrl function in action-utils.ts
• Consistent error handling: Uses existing CliError class with clear, user-friendly error messages
• Proper async/await usage: Function correctly handles async schema loading
• Good placement: Validation happens early in both migrate.ts and db.ts before expensive operations
• DRY principle: Shared utility avoids code duplication between migrate and db commands

Minor suggestions:

• The error message could be more specific about which commands require the URL field
• Consider adding a hint about how to add a datasource URL to the error message

Potential Issues ✅

No major issues found

• Logic correctly checks for datasource existence and URL field presence using optional chaining
• Early validation prevents downstream Prisma errors
• Proper cleanup in finally blocks ensures temp schema files are removed even if validation fails

Performance Considerations ✅

Minimal impact:

• Schema validation adds negligible overhead compared to database operations
• Early validation actually improves performance by preventing unnecessary Prisma schema generation when URL is missing
• Async loading is appropriate and doesn't block unnecessarily

Security Concerns ✅

No security issues identified:

• No sensitive data exposure in error messages
• Input validation follows existing patterns
• No new attack vectors introduced

Test Coverage Assessment ⚠️

Current test coverage:

• Existing tests in db.test.ts and migrate.test.ts use schemas with valid datasource URLs (via createProject utility)
• Tests currently pass because they always include a proper datasource configuration

Missing test coverage:
The PR should include tests for the new validation logic:

// Suggested test cases needed:
it('should throw error when datasource URL is missing for db push', () => {
    const modelWithoutUrl = `
    datasource db {
        provider = "sqlite"
        // missing url field
    }
    model User { id String @id }
    `;
    const workDir = createProject(modelWithoutUrl, false);
    expect(() => runCli('db push', workDir)).toThrow('must have a "url" field');
});

it('should throw error when datasource is missing entirely', () => {
    const modelWithoutDatasource = `model User { id String @id }`;
    const workDir = createProject(modelWithoutDatasource, false);
    expect(() => runCli('db push', workDir)).toThrow('must have a "url" field');
});

Implementation Quality

The implementation is solid and follows ZenStack's patterns:

• Validation timing: packages/cli/src/actions/migrate.ts:39 and packages/cli/src/actions/db.ts:26 - validation occurs at the right point in the execution flow
• Function signature: packages/cli/src/actions/action-utils.ts:139-145 - clean, focused function that does one thing well
• Error handling: Consistent with existing codebase patterns

Recommendations

1. Add test coverage for the new validation scenarios (missing URL field, missing datasource)
2. Consider enhancing error message with usage hints:

   throw new CliError('The schema\'s "datasource" must have a "url" field to use this command. Add a datasource block with a url field, e.g.:\n\ndatasource db {\n  provider = "sqlite"\n  url = "file:./dev.db"\n}');

Verdict

✅ Approved with minor suggestions

This is a well-implemented defensive programming improvement that prevents cryptic runtime errors. The code quality is high and follows established patterns. Main recommendation is to add corresponding test cases to ensure the validation works as expected.

---

[Copilot]

Pull Request Overview

This PR adds validation to require a datasource URL before running migration and database push commands. The change prevents these commands from executing when the schema's datasource lacks a url field, which would cause failures during Prisma operations.

Key Changes:

• Added requireDataSourceUrl function to validate datasource URL presence
• Applied validation to migration commands (migrate dev, reset, deploy, status, resolve)
• Applied validation to database push command (db push)

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
packages/cli/src/actions/action-utils.ts	Introduces new requireDataSourceUrl validation function that checks for datasource URL field
packages/cli/src/actions/migrate.ts	Adds datasource URL validation before executing any migration commands
packages/cli/src/actions/db.ts	Adds datasource URL validation before executing database push command

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/cli/src/actions/action-utils.ts (1)

139-145: Consider improving the error message specificity.

The current implementation conflates two distinct error cases:

1. No datasource declaration exists in the schema
2. Datasource exists but lacks a url field

When no datasource is present, dataSource is undefined, and the error message "The schema's datasource must have a url field" is misleading.

Apply this diff to provide clearer error messages:

 export async function requireDataSourceUrl(schemaFile: string) {
     const zmodel = await loadSchemaDocument(schemaFile);
     const dataSource = zmodel.declarations.find(isDataSource);
+    if (!dataSource) {
+        throw new CliError('The schema must define a "datasource" to use this command.');
+    }
-    if (!dataSource?.fields.some((f) => f.name === 'url')) {
+    if (!dataSource.fields.some((f) => f.name === 'url')) {
         throw new CliError('The schema\'s "datasource" must have a "url" field to use this command.');
     }
 }

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 71ee094 and 31ff094.

📒 Files selected for processing (3)

• packages/cli/src/actions/action-utils.ts (1 hunks)
• packages/cli/src/actions/db.ts (2 hunks)
• packages/cli/src/actions/migrate.ts (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (3)

packages/cli/src/actions/action-utils.ts (2)

packages/language/src/generated/ast.ts (1)

• isDataSource (417-419)

packages/cli/src/cli-error.ts (1)

• CliError (4-4)

packages/cli/src/actions/migrate.ts (1)

packages/cli/src/actions/action-utils.ts (1)

• requireDataSourceUrl (139-145)

packages/cli/src/actions/db.ts (1)

packages/cli/src/actions/action-utils.ts (1)

• requireDataSourceUrl (139-145)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Agent
• GitHub Check: build-test (20.x, sqlite)
• GitHub Check: build-test (20.x, postgresql)

🔇 Additional comments (4)

packages/cli/src/actions/db.ts (2)

3-3: LGTM!

The import is correctly added and aligns with the usage in the runPush function.

---

24-28: LGTM! Early validation improves error reporting.

The datasource URL validation is correctly placed before schema generation, providing early feedback to users. The logic flow is clear and well-commented.

packages/cli/src/actions/migrate.ts (2)

5-5: LGTM!

The import is correctly added and consistent with the usage in the run function below.

---

37-40: LGTM! Validation gate protects all migration commands.

The datasource URL validation is correctly positioned before schema generation and applies uniformly to all migration subcommands (dev, reset, deploy, status, resolve). The early validation ensures users receive clear feedback before any migration operations proceed.