fix(cli): add missing opposite relation fields during db pull when multiple FKs target the same model

Back-reference relation fields (the opposite side of a relation, with @relation but no `fields` arg) were silently skipped during the merge phase of `db pull` when no matching field existed in the original schema. This caused models like `Users` that are referenced by many tables (e.g., via `user_created`/`user_updated` FKs) to be missing their back-reference fields after pulling.

The fix adds relation-name-based matching as a new step in the field matching algorithm, and removes the blanket early-skip that discarded all unmatched back-references. Named back-references that don't match any existing field are now correctly added as new fields.

Author: svetch

packages/cli/src/actions/db.ts

@@ -14,7 +14,7 @@ import {
 } from './action-utils';
 import { consolidateEnums, syncEnums, syncRelation, syncTable, type Relation } from './pull';
 import { providers as pullProviders } from './pull/provider';
-import { getDatasource, getDbName, getRelationFieldsKey, getRelationFkName, isDatabaseManagedAttribute } from './pull/utils';
+import { getDatasource, getDbName, getRelationFieldsKey, getRelationFkName, getRelationName, isDatabaseManagedAttribute } from './pull/utils';
 import type { DataSourceProviderType } from '@zenstackhq/schema';
 import { CliError } from '../cli-error';
 
@@ -283,16 +283,9 @@ async function runPull(options: PullOptions) {
                 }
 
                 newDataModel.fields.forEach((f) => {
-                    // Prioritized matching: exact db name > relation fields key > relation FK name > type reference
+                    // Prioritized matching: exact db name > relation fields key > relation FK name > relation name > type reference
                     let originalFields = originalDataModel.fields.filter((d) => getDbName(d) === getDbName(f));
 
-                    // If this is a back-reference relation field (has @relation but no `fields` arg), silently skip
-                    const isRelationField =
-                        f.$type === 'DataField' && !!(f as any).attributes?.some((a: any) => a?.decl?.ref?.name === '@relation');
-                    if (originalFields.length === 0 && isRelationField && !getRelationFieldsKey(f as any)) {
-                        return;
-                    }
-
                     if (originalFields.length === 0) {
                         // Try matching by relation fields key (the `fields` attribute in @relation)
                         // This matches relation fields by their FK field references
@@ -314,11 +307,21 @@ async function runPull(options: PullOptions) {
                         );
                     }
 
+                    if (originalFields.length === 0) {
+                        // Try matching by relation name (the first positional arg in @relation)
+                        // This is essential for back-reference fields that only have a relation name
+                        const newRelName = getRelationName(f as any);
+                        if (newRelName) {
+                            originalFields = originalDataModel.fields.filter(
+                                (d) => d.$type === 'DataField' && getRelationName(d as any) === newRelName,
+                            );
+                        }
+                    }
+
                     if (originalFields.length === 0) {
                         // Try matching by type reference
                         // We need this because for relations that don't have @relation, we can only check if the original exists by the field type.
                         // Yes, in this case it can potentially result in multiple original fields, but we only want to ensure that at least one relation exists.
-                        // In the future, we might implement some logic to detect how many of these types of relations we need and add/remove fields based on this.
                         originalFields = originalDataModel.fields.filter(
                             (d) =>
                                 f.$type === 'DataField' &&
@@ -499,7 +502,7 @@ async function runPull(options: PullOptions) {
                 });
                 originalDataModel.fields
                     .filter((f) => {
-                        // Prioritized matching: exact db name > relation fields key > relation FK name > type reference
+                        // Prioritized matching: exact db name > relation fields key > relation FK name > relation name > type reference
                         const matchByDbName = newDataModel.fields.find((d) => getDbName(d) === getDbName(f));
                         if (matchByDbName) return false;
 
@@ -520,6 +523,15 @@ async function runPull(options: PullOptions) {
                         );
                         if (matchByFkName) return false;
 
+                        // Try matching by relation name (for named back-reference fields)
+                        const originalRelName = getRelationName(f as any);
+                        if (originalRelName) {
+                            const matchByRelName = newDataModel.fields.find(
+                                (d) => d.$type === 'DataField' && getRelationName(d as any) === originalRelName,
+                            );
+                            if (matchByRelName) return false;
+                        }
+
                         const matchByTypeRef = newDataModel.fields.find(
                             (d) =>
                                 f.$type === 'DataField' &&

packages/cli/src/actions/pull/utils.ts

@@ -122,6 +122,20 @@ export function getRelationFkName(decl: DataField): string | undefined {
     return schemaAttrValue?.value;
 }
 
+/**
+ * Gets the relation name from the @relation attribute's first positional argument.
+ * e.g., @relation('myRelation', fields: [...], references: [...]) -> "myRelation"
+ * e.g., @relation(fields: [...], references: [...]) -> undefined
+ * e.g., @relation('backRef') -> "backRef"
+ */
+export function getRelationName(decl: DataField): string | undefined {
+    const relationAttr = decl?.attributes?.find((a) => a.decl?.ref?.name === '@relation');
+    if (!relationAttr) return undefined;
+    const firstPositionalArg = relationAttr.args.find((a) => !a.name);
+    if (!firstPositionalArg || firstPositionalArg.value?.$type !== 'StringLiteral') return undefined;
+    return (firstPositionalArg.value as StringLiteral).value;
+}
+
 /**
  * Gets the FK field names from the @relation attribute's `fields` argument.
  * Returns a sorted, comma-separated string of field names for comparison.

packages/cli/test/db/pull.test.ts

@@ -152,6 +152,83 @@ model Tag {
             expect(restoredSchema).toEqual(schema);
         });
 
+        it('should restore opposite relation fields when multiple models have FKs to the same target', async () => {
+            const { workDir, schema } = await createProject(
+                `model Comment {
+    id               Int    @id @default(autoincrement())
+    text             String
+    commentCreatedBy User?  @relation('Comment_createdByToUser', fields: [createdBy], references: [id])
+    createdBy        Int?
+    commentUpdatedBy User?  @relation('Comment_updatedByToUser', fields: [updatedBy], references: [id])
+    updatedBy        Int?
+}
+
+model Post {
+    id            Int    @id @default(autoincrement())
+    title         String
+    postCreatedBy User?  @relation('Post_createdByToUser', fields: [createdBy], references: [id])
+    createdBy     Int?
+    postUpdatedBy User?  @relation('Post_updatedByToUser', fields: [updatedBy], references: [id])
+    updatedBy     Int?
+}
+
+model User {
+    id               Int       @id @default(autoincrement())
+    email            String    @unique
+    commentCreatedBy Comment[] @relation('Comment_createdByToUser')
+    commentUpdatedBy Comment[] @relation('Comment_updatedByToUser')
+    postCreatedBy    Post[]    @relation('Post_createdByToUser')
+    postUpdatedBy    Post[]    @relation('Post_updatedByToUser')
+}`,
+            );
+            runCli('db push', workDir);
+
+            const schemaFile = path.join(workDir, 'zenstack/schema.zmodel');
+
+            fs.writeFileSync(schemaFile, getDefaultPrelude());
+            runCli('db pull --indent 4', workDir);
+
+            const restoredSchema = getSchema(workDir);
+            expect(restoredSchema).toEqual(schema);
+        });
+
+        it('should preserve opposite relation fields when multiple models have FKs to the same target', async () => {
+            const { workDir, schema } = await createProject(
+                `model Comment {
+    id               Int    @id @default(autoincrement())
+    text             String
+    commentCreatedBy User?  @relation('Comment_createdByToUser', fields: [createdBy], references: [id])
+    createdBy        Int?
+    commentUpdatedBy User?  @relation('Comment_updatedByToUser', fields: [updatedBy], references: [id])
+    updatedBy        Int?
+}
+
+model Post {
+    id            Int    @id @default(autoincrement())
+    title         String
+    postCreatedBy User?  @relation('Post_createdByToUser', fields: [createdBy], references: [id])
+    createdBy     Int?
+    postUpdatedBy User?  @relation('Post_updatedByToUser', fields: [updatedBy], references: [id])
+    updatedBy     Int?
+}
+
+model User {
+    id               Int       @id @default(autoincrement())
+    email            String    @unique
+    commentCreatedBy Comment[] @relation('Comment_createdByToUser')
+    commentUpdatedBy Comment[] @relation('Comment_updatedByToUser')
+    postCreatedBy    Post[]    @relation('Post_createdByToUser')
+    postUpdatedBy    Post[]    @relation('Post_updatedByToUser')
+}`,
+            );
+            runCli('db push', workDir);
+
+            runCli('db pull --indent 4', workDir);
+
+            const restoredSchema = getSchema(workDir);
+            expect(restoredSchema).toEqual(schema);
+        });
+
         it('should restore one-to-one relation when FK is the single-column primary key', async () => {
             const { workDir, schema } = await createProject(
                 `model Profile {