add createOpposite option on @relation

elliots · elliots · commit 042dc492b1ef · 2026-03-15T20:22:00.000+11:00
x
diff --git a/packages/cli/test/plugins/prisma-plugin.test.ts b/packages/cli/test/plugins/prisma-plugin.test.ts
@@ -78,4 +78,143 @@ model User {
         runCli('generate', workDir);
         expect(fs.existsSync(path.join(workDir, 'relative/schema.prisma'))).toBe(true);
     });
+
+    it('should auto-generate opposite relation field with createOpposite: true', async () => {
+        const { workDir } = await createProject(`
+plugin prisma {
+    provider = '@core/prisma'
+}
+
+model User {
+    id String @id @default(cuid())
+}
+
+model Post {
+    id       String @id @default(cuid())
+    userId   String
+    user     User   @relation(fields: [userId], references: [id], createOpposite: true)
+}
+`);
+        runCli('generate', workDir);
+        const prismaSchema = fs.readFileSync(path.join(workDir, 'zenstack/schema.prisma'), 'utf8');
+        expect(prismaSchema).toContain('post Post[]');
+        expect(prismaSchema).not.toContain('createOpposite');
+    });
+
+    it('should distinguish multiple relations to the same model by relation name', async () => {
+        const { workDir } = await createProject(`
+plugin prisma {
+    provider = '@core/prisma'
+}
+
+model User {
+    id String @id @default(cuid())
+}
+
+model Post {
+    id          String @id @default(cuid())
+    createdById String
+    createdBy   User   @relation("CreatedBy", fields: [createdById], references: [id], createOpposite: true)
+    updatedById String
+    updatedBy   User   @relation("UpdatedBy", fields: [updatedById], references: [id], createOpposite: true)
+}
+`);
+        runCli('generate', workDir);
+        const prismaSchema = fs.readFileSync(path.join(workDir, 'zenstack/schema.prisma'), 'utf8');
+        // Both opposite relations should be generated with disambiguated names
+        expect(prismaSchema).toContain('createdBy Post[]');
+        expect(prismaSchema).toContain('updatedBy Post[]');
+        expect(prismaSchema).toContain('"CreatedBy"');
+        expect(prismaSchema).toContain('"UpdatedBy"');
+    });
+
+    it('should error on field name collision with createOpposite', async () => {
+        const { workDir } = await createProject(`
+plugin prisma {
+    provider = '@core/prisma'
+}
+
+model User {
+    id   String @id @default(cuid())
+    post String
+}
+
+model Post {
+    id     String @id @default(cuid())
+    userId String
+    user   User   @relation(fields: [userId], references: [id], createOpposite: true)
+}
+`);
+        // The Prisma plugin catches errors internally, so verify the prisma schema was NOT generated
+        runCli('generate', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/schema.prisma'))).toBe(false);
+    });
+
+    it('should handle composite key models with createOpposite on scalar side', async () => {
+        const { workDir } = await createProject(`
+plugin prisma {
+    provider = '@core/prisma'
+}
+
+model Tenant {
+    orgId    String
+    tenantId String
+    name     String
+
+    @@id([orgId, tenantId])
+}
+
+model Invoice {
+    id             String @id @default(cuid())
+    tenantOrgId    String
+    tenantTenantId String
+    tenant         Tenant @relation(fields: [tenantOrgId, tenantTenantId], references: [orgId, tenantId], createOpposite: true)
+}
+`);
+        runCli('generate', workDir);
+        const prismaSchema = fs.readFileSync(path.join(workDir, 'zenstack/schema.prisma'), 'utf8');
+        expect(prismaSchema).toContain('invoice Invoice[]');
+    });
+
+    it('should handle createOpposite on array side using correct model id fields', async () => {
+        const { workDir } = await createProject(`
+plugin prisma {
+    provider = '@core/prisma'
+}
+
+model User {
+    uuid  String @id @default(cuid())
+    posts Post[] @relation(createOpposite: true)
+}
+
+model Post {
+    id String @id @default(cuid())
+}
+`);
+        runCli('generate', workDir);
+        const prismaSchema = fs.readFileSync(path.join(workDir, 'zenstack/schema.prisma'), 'utf8');
+        // FK should reference User's uuid field, not Post's id
+        expect(prismaSchema).toContain('userUuid String');
+        expect(prismaSchema).toContain('user User');
+        expect(prismaSchema).toContain('@relation(fields: [userUuid], references: [uuid])');
+    });
+
+    it('should error on missing opposite relation without createOpposite', async () => {
+        const { workDir } = await createProject(`
+plugin prisma {
+    provider = '@core/prisma'
+}
+
+model User {
+    id String @id @default(cuid())
+}
+
+model Post {
+    id       String @id @default(cuid())
+    userId   String
+    user     User   @relation(fields: [userId], references: [id])
+}
+`);
+        expect(() => runCli('generate', workDir)).toThrow(/missing an opposite relation/);
+    });
 });
diff --git a/packages/language/res/stdlib.zmodel b/packages/language/res/stdlib.zmodel
@@ -364,8 +364,9 @@ attribute @@index(_ fields: FieldReference[], name: String?, map: String?, lengt
  * @param map: Defines a custom name for the foreign key in the database.
  * @param onUpdate: Defines the referential action to perform when a referenced entry in the referenced model is being updated.
  * @param onDelete: Defines the referential action to perform when a referenced entry in the referenced model is being deleted.
+ * @param createOpposite: When true, auto-generates the opposite relation field in the Prisma schema.
  */
-attribute @relation(_ name: String?, fields: FieldReference[]?, references: TransitiveFieldReference[]?, onDelete: ReferentialAction?, onUpdate: ReferentialAction?, map: String?) @@@prisma
+attribute @relation(_ name: String?, fields: FieldReference[]?, references: TransitiveFieldReference[]?, onDelete: ReferentialAction?, onUpdate: ReferentialAction?, map: String?, createOpposite: Boolean?) @@@prisma
 
 /**
  * Maps a field name or enum value from the schema to a column with a different name in the database.
diff --git a/packages/language/src/validators/datamodel-validator.ts b/packages/language/src/validators/datamodel-validator.ts
@@ -7,6 +7,7 @@ import {
     DataModel,
     ReferenceExpr,
     TypeDef,
+    isBooleanLiteral,
     isDataModel,
     isEnum,
     isStringLiteral,
@@ -258,6 +259,12 @@ export default class DataModelValidator implements AstValidator<DataModel> {
         });
 
         if (oppositeFields.length === 0) {
+            // skip error if createOpposite: true is set — the opposite will be auto-generated
+            const createOppositeArg = thisRelation.attr?.args.find((a) => a.name === 'createOpposite');
+            if (createOppositeArg && isBooleanLiteral(createOppositeArg.value) && createOppositeArg.value.value === true) {
+                return;
+            }
+
             const info: DiagnosticInfo<AstNode, string> = {
                 node: field,
                 code: IssueCodes.MissingOppositeRelation,
diff --git a/packages/sdk/src/prisma/prisma-builder.ts b/packages/sdk/src/prisma/prisma-builder.ts
@@ -44,6 +44,10 @@ export class PrismaModel {
         return e;
     }
 
+    findModel(name: string): Model | undefined {
+        return this.models.find((m) => m.name === name);
+    }
+
     toString(): string {
         return [...this.datasources, ...this.generators, ...this.enums, ...this.models]
             .map((d) => d.toString())
diff --git a/packages/sdk/src/prisma/prisma-schema-generator.ts b/packages/sdk/src/prisma/prisma-schema-generator.ts
@@ -111,6 +111,9 @@ export class PrismaSchemaGenerator {
             this.generateDefaultGenerator(prisma);
         }
 
+        // auto-generate missing opposite relation fields so Prisma schema is always valid
+        this.generateMissingOppositeRelations(prisma);
+
         return this.PRELUDE + prisma.toString();
     }
 
@@ -335,12 +338,15 @@ export class PrismaSchemaGenerator {
         return AstUtils.streamAst(expr).some(isAuthInvocation);
     }
 
+    // Args that are ZenStack-only and should not appear in the generated Prisma schema
+    private readonly NON_PRISMA_RELATION_ARGS = ['createOpposite'];
+
     private makeFieldAttribute(attr: DataFieldAttribute) {
         const attrName = attr.decl.ref!.name;
-        return new PrismaFieldAttribute(
-            attrName,
-            attr.args.map((arg) => this.makeAttributeArg(arg)),
-        );
+        const args = attr.args
+            .filter((arg) => !(attrName === '@relation' && arg.name && this.NON_PRISMA_RELATION_ARGS.includes(arg.name)))
+            .map((arg) => this.makeAttributeArg(arg));
+        return new PrismaFieldAttribute(attrName, args);
     }
 
     private makeAttributeArg(arg: AttributeArg): PrismaAttributeArg {
@@ -512,6 +518,130 @@ export class PrismaSchemaGenerator {
         );
     }
 
+    private hasCreateOpposite(field: DataField): boolean {
+        const relAttr = field.attributes.find((attr) => attr.decl.ref?.name === '@relation');
+        if (!relAttr) return false;
+        const createOppositeArg = relAttr.args.find((arg) => arg.name === 'createOpposite');
+        if (!createOppositeArg) return false;
+        return isLiteralExpr(createOppositeArg.value) && createOppositeArg.value.value === true;
+    }
+
+    private getRelationName(field: DataField): string | undefined {
+        const relAttr = field.attributes.find((attr) => attr.decl.ref?.name === '@relation');
+        if (!relAttr) return undefined;
+        const nameArg = relAttr.args.find((arg) => !arg.name || arg.name === 'name');
+        if (!nameArg) return undefined;
+        return isStringLiteral(nameArg.value) ? (nameArg.value.value as string) : undefined;
+    }
+
+    /**
+     * For relation fields with `createOpposite: true`, auto-generates the opposite relation
+     * field in the Prisma schema so it stays valid.
+     */
+    private generateMissingOppositeRelations(prisma: PrismaModel) {
+        for (const decl of this.zmodel.declarations) {
+            if (!isDataModel(decl)) continue;
+
+            const allFields = getAllFields(decl, false);
+            for (const field of allFields) {
+                if (!isDataModel(field.type.reference?.ref)) continue;
+                if (!this.hasCreateOpposite(field)) continue;
+
+                const relationName = this.getRelationName(field);
+                const oppositeModel = field.type.reference!.ref! as DataModel;
+
+                // match opposite fields by both target model name and relation name
+                const oppositeFields = getAllFields(oppositeModel, false).filter((f) => {
+                    if (f === field || f.type.reference?.ref?.name !== decl.name) return false;
+                    return this.getRelationName(f) === relationName;
+                });
+
+                if (oppositeFields.length === 0) {
+                    // missing opposite relation — add it to the Prisma model
+                    const prismaOppositeModel = prisma.findModel(oppositeModel.name);
+                    if (!prismaOppositeModel) continue;
+
+                    // use relation name to disambiguate when multiple relations target the same model
+                    const fieldName = relationName
+                        ? lowerCaseFirst(relationName)
+                        : lowerCaseFirst(decl.name);
+                    if (prismaOppositeModel.fields.some((f) => f.name === fieldName)) {
+                        throw new Error(
+                            `Cannot auto-generate opposite relation field "${fieldName}" on model "${oppositeModel.name}": a field with that name already exists`,
+                        );
+                    }
+
+                    // build @relation args for the generated field, including relation name if present
+                    const buildRelationAttr = (extraArgs: PrismaAttributeArg[]) => {
+                        const args: PrismaAttributeArg[] = [];
+                        if (relationName) {
+                            args.push(
+                                new PrismaAttributeArg(
+                                    undefined,
+                                    new PrismaAttributeArgValue('String', relationName),
+                                ),
+                            );
+                        }
+                        args.push(...extraArgs);
+                        return new PrismaFieldAttribute('@relation', args);
+                    };
+
+                    if (field.type.array) {
+                        // the field is an array (e.g., posts Post[]), so the opposite should be a scalar relation
+                        const idFields = getIdFields(decl);
+                        if (idFields.length === 0) continue;
+
+                        // create FK fields for all id fields (supports composite keys)
+                        idFields.forEach((idFieldName) => {
+                            const refIdFieldName = fieldName + idFieldName.charAt(0).toUpperCase() + idFieldName.slice(1);
+                            if (!prismaOppositeModel.fields.some((f) => f.name === refIdFieldName)) {
+                                const idField = allFields.find((f) => f.name === idFieldName);
+                                if (idField?.type.type) {
+                                    prismaOppositeModel.addField(
+                                        refIdFieldName,
+                                        new ModelFieldType(idField.type.type, false, false),
+                                    );
+                                }
+                            }
+                        });
+
+                        prismaOppositeModel.addField(
+                            fieldName,
+                            new ModelFieldType(decl.name, false, false),
+                            [
+                                buildRelationAttr([
+                                    new PrismaAttributeArg(
+                                        'fields',
+                                        new PrismaAttributeArgValue('Array', idFields.map(
+                                            (idFieldName) => new PrismaAttributeArgValue('FieldReference',
+                                                new PrismaFieldReference(fieldName + idFieldName.charAt(0).toUpperCase() + idFieldName.slice(1))),
+                                        )),
+                                    ),
+                                    new PrismaAttributeArg(
+                                        'references',
+                                        new PrismaAttributeArgValue('Array', idFields.map(
+                                            (idFieldName) => new PrismaAttributeArgValue('FieldReference', new PrismaFieldReference(idFieldName)),
+                                        )),
+                                    ),
+                                ]),
+                            ],
+                        );
+                    } else {
+                        // the field is a scalar relation (e.g., user User), so the opposite should be an array
+                        const attrs = relationName
+                            ? [buildRelationAttr([])]
+                            : [];
+                        prismaOppositeModel.addField(
+                            fieldName,
+                            new ModelFieldType(decl.name, true, false),
+                            attrs,
+                        );
+                    }
+                }
+            }
+        }
+    }
+
     private truncate(name: string) {
         if (name.length <= IDENTIFIER_NAME_MAX_LENGTH) {
             return name;
