feat(cli): gate UUID segment in temp Prisma schema name behind --random-prisma-schema-name

The UUID suffix introduced in f962351 to avoid collisions between
concurrent `zen db push` runs is now opt-in. Default behavior restores
the upstream `~schema.prisma` filename; pass `--random-prisma-schema-name`
to `db push` or any `migrate` subcommand to re-enable the UUID suffix.

Addresses the maintainer's review comment on #2491.

Assisted-by: Cursor:claude-opus-4.7 [Shell] [Read] [StrReplace] [Write]

Author: jesus-gomez-aetonix

packages/cli/src/actions/action-utils.ts

@@ -87,16 +87,19 @@ export function handleSubProcessError(err: unknown) {
     }
 }
 
-export async function generateTempPrismaSchema(zmodelPath: string, folder?: string) {
+export async function generateTempPrismaSchema(
+    zmodelPath: string,
+    opts: { folder?: string; randomName?: boolean } = {},
+) {
+    const { folder: folderOpt, randomName = false } = opts;
     const model = await loadSchemaDocument(zmodelPath);
     if (!model.declarations.some(isDataSource)) {
         throw new CliError('Schema must define a datasource');
     }
     const prismaSchema = await new PrismaSchemaGenerator(model).generate();
-    if (!folder) {
-        folder = path.dirname(zmodelPath);
-    }
-    const prismaSchemaFile = path.resolve(folder, `~schema.${crypto.randomUUID()}.prisma`);
+    const folder = folderOpt ?? path.dirname(zmodelPath);
+    const fileName = randomName ? `~schema.${crypto.randomUUID()}.prisma` : '~schema.prisma';
+    const prismaSchemaFile = path.resolve(folder, fileName);
     fs.writeFileSync(prismaSchemaFile, prismaSchema);
     return prismaSchemaFile;
 }

packages/cli/src/actions/db.ts

@@ -22,6 +22,7 @@ type PushOptions = {
     schema?: string;
     acceptDataLoss?: boolean;
     forceReset?: boolean;
+    randomPrismaSchemaName?: boolean;
 };
 
 export type PullOptions = {
@@ -55,7 +56,9 @@ async function runPush(options: PushOptions) {
     await requireDataSourceUrl(schemaFile);
 
     // generate a temp prisma schema file
-    const prismaSchemaFile = await generateTempPrismaSchema(schemaFile);
+    const prismaSchemaFile = await generateTempPrismaSchema(schemaFile, {
+        randomName: options.randomPrismaSchemaName,
+    });
 
     try {
         // run prisma db push

packages/cli/src/actions/migrate.ts

@@ -9,6 +9,7 @@ type CommonOptions = {
     schema?: string;
     migrations?: string;
     skipSeed?: boolean;
+    randomPrismaSchemaName?: boolean;
 };
 
 type DevOptions = CommonOptions & {
@@ -39,7 +40,10 @@ export async function run(command: string, options: CommonOptions) {
     await requireDataSourceUrl(schemaFile);
 
     const prismaSchemaDir = options.migrations ? path.dirname(options.migrations) : undefined;
-    const prismaSchemaFile = await generateTempPrismaSchema(schemaFile, prismaSchemaDir);
+    const prismaSchemaFile = await generateTempPrismaSchema(schemaFile, {
+        folder: prismaSchemaDir,
+        randomName: options.randomPrismaSchemaName,
+    });
 
     try {
         switch (command) {

packages/cli/src/index.ts

@@ -76,6 +76,11 @@ function createProgram() {
     const noVersionCheckOption = new Option('--no-version-check', 'do not check for new version');
     const noTipsOption = new Option('--no-tips', 'do not show usage tips');
 
+    const randomPrismaSchemaNameOption = new Option(
+        '--random-prisma-schema-name',
+        'append a random UUID to the temporary Prisma schema filename to avoid collisions between concurrent runs sharing a working directory (default: "~schema.prisma")',
+    ).default(false);
+
     program
         .command('generate')
         .description('Run code generation plugins')
@@ -111,6 +116,7 @@ function createProgram() {
         .addOption(new Option('-n, --name <name>', 'migration name'))
         .addOption(new Option('--create-only', 'only create migration, do not apply'))
         .addOption(migrationsOption)
+        .addOption(randomPrismaSchemaNameOption)
         .description('Create a migration from changes in schema and apply it to the database')
         .action((options) => migrateAction('dev', options));
 
@@ -121,6 +127,7 @@ function createProgram() {
         .addOption(migrationsOption)
         .addOption(new Option('--skip-seed', 'skip seeding the database after reset'))
         .addOption(noVersionCheckOption)
+        .addOption(randomPrismaSchemaNameOption)
         .description('Reset your database and apply all migrations, all data will be lost')
         .addHelpText(
             'after',
@@ -133,6 +140,7 @@ function createProgram() {
         .addOption(schemaOption)
         .addOption(noVersionCheckOption)
         .addOption(migrationsOption)
+        .addOption(randomPrismaSchemaNameOption)
         .description('Deploy your pending migrations to your production/staging database')
         .action((options) => migrateAction('deploy', options));
 
@@ -141,6 +149,7 @@ function createProgram() {
         .addOption(schemaOption)
         .addOption(noVersionCheckOption)
         .addOption(migrationsOption)
+        .addOption(randomPrismaSchemaNameOption)
         .description('Check the status of your database migrations')
         .action((options) => migrateAction('status', options));
 
@@ -149,6 +158,7 @@ function createProgram() {
         .addOption(schemaOption)
         .addOption(noVersionCheckOption)
         .addOption(migrationsOption)
+        .addOption(randomPrismaSchemaNameOption)
         .addOption(new Option('--applied <migration>', 'record a specific migration as applied'))
         .addOption(new Option('--rolled-back <migration>', 'record a specific migration as rolled back'))
         .description('Resolve issues with database migrations in deployment databases')
@@ -163,6 +173,7 @@ function createProgram() {
         .addOption(noVersionCheckOption)
         .addOption(new Option('--accept-data-loss', 'ignore data loss warnings'))
         .addOption(new Option('--force-reset', 'force a reset of the database before push'))
+        .addOption(randomPrismaSchemaNameOption)
         .action((options) => dbAction('push', options));
 
     dbCommand

packages/cli/test/action-utils.test.ts

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { generateTempPrismaSchema } from '../src/actions/action-utils';
+import { createProject } from './utils';
+
+const model = `
+model User {
+    id String @id @default(cuid())
+}
+`;
+
+describe('generateTempPrismaSchema', () => {
+    it('defaults to a deterministic "~schema.prisma" filename', async () => {
+        const { workDir } = await createProject(model, { provider: 'sqlite' });
+        const schemaPath = path.join(workDir, 'zenstack/schema.zmodel');
+
+        const generated = await generateTempPrismaSchema(schemaPath);
+
+        try {
+            expect(path.basename(generated)).toBe('~schema.prisma');
+            expect(fs.existsSync(generated)).toBe(true);
+        } finally {
+            if (fs.existsSync(generated)) {
+                fs.unlinkSync(generated);
+            }
+        }
+    });
+
+    it('appends a random UUID segment when randomName is true', async () => {
+        const { workDir } = await createProject(model, { provider: 'sqlite' });
+        const schemaPath = path.join(workDir, 'zenstack/schema.zmodel');
+
+        const first = await generateTempPrismaSchema(schemaPath, { randomName: true });
+        const second = await generateTempPrismaSchema(schemaPath, { randomName: true });
+
+        try {
+            const uuidPattern = /^~schema\.[0-9a-f-]{36}\.prisma$/;
+            expect(path.basename(first)).toMatch(uuidPattern);
+            expect(path.basename(second)).toMatch(uuidPattern);
+            expect(first).not.toBe(second);
+            expect(fs.existsSync(first)).toBe(true);
+            expect(fs.existsSync(second)).toBe(true);
+        } finally {
+            for (const f of [first, second]) {
+                if (fs.existsSync(f)) {
+                    fs.unlinkSync(f);
+                }
+            }
+        }
+    });
+});