fix(orm): prepend DISTINCT ON fields to ORDER BY for PostgreSQL compatibility (#2562)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: Yiming Cao <ymc9@users.noreply.github.com>

Author: 3 people

packages/orm/src/client/crud/dialects/base-dialect.ts

@@ -138,21 +138,42 @@ export abstract class BaseCrudDialect<Schema extends SchemaDef> {
         }
         result = this.buildSkipTake(result, skip, take);
 
-        // orderBy
-        result = this.buildOrderBy(result, model, modelAlias, args.orderBy, negateOrderBy, take);
-
         // distinct
+        let distinctFields: string[] = [];
         if ('distinct' in args && (args as any).distinct) {
-            const distinct = ensureArray((args as any).distinct) as string[];
+            distinctFields = ensureArray((args as any).distinct) as string[];
             if (this.supportsDistinctOn) {
-                result = result.distinctOn(distinct.map((f) => this.eb.ref(`${modelAlias}.${f}`)));
+                result = result.distinctOn(distinctFields.map((f) => this.eb.ref(`${modelAlias}.${f}`)));
             } else {
                 throw createNotSupportedError(`"distinct" is not supported by "${this.schema.provider.type}" provider`);
             }
         }
 
+        // orderBy
+        // Some dialects (e.g., postgres) requires DISTINCT ON expressions to match the leftmost ORDER BY expressions.
+        // Prepend distinct fields only when the user-supplied orderBy doesn't already satisfy this.
+        let effectiveOrderBy = args.orderBy;
+        if (distinctFields.length > 0 && this.supportsDistinctOn) {
+            const existingOrderBy = enumerate(args.orderBy).filter((o) => Object.keys(o as object).length > 0);
+            const alreadySatisfied = distinctFields.every(
+                (f, i) => i < existingOrderBy.length && Object.keys(existingOrderBy[i] as object)[0] === f,
+            );
+            if (existingOrderBy.length > 0 && !alreadySatisfied) {
+                const prependedOrderBy = distinctFields.map((f) => ({ [f]: 'asc' })) as any[];
+                effectiveOrderBy = [...prependedOrderBy, ...existingOrderBy];
+            }
+        }
+        result = this.buildOrderBy(result, model, modelAlias, effectiveOrderBy, negateOrderBy, take);
+
         if (args.cursor) {
-            result = this.buildCursorFilter(model, result, args.cursor, args.orderBy, negateOrderBy, modelAlias);
+            result = this.buildCursorFilter(
+                model,
+                result,
+                args.cursor,
+                effectiveOrderBy as OrArray<Record<string, SortOrder>> | undefined,
+                negateOrderBy,
+                modelAlias,
+            );
         }
         return result;
     }

tests/regression/test/issue-2529.test.ts

@@ -0,0 +1,69 @@
+import { createTestClient } from '@zenstackhq/testtools';
+import { describe, expect, it } from 'vitest';
+
+// https://github.com/zenstackhq/zenstack/issues/2529
+describe('Regression for issue #2529', () => {
+    async function setup() {
+        const db = await createTestClient(
+            `
+model Post {
+    id        Int      @id @default(autoincrement())
+    title     String
+    createdAt DateTime @default(now())
+}
+            `,
+            { provider: 'postgresql' },
+        );
+        await db.post.create({ data: { title: 'A' } });
+        await db.post.create({ data: { title: 'A' } });
+        await db.post.create({ data: { title: 'B' } });
+        return db;
+    }
+
+    it('distinct only without orderBy', async () => {
+        const db = await setup();
+
+        const result = await db.post.findMany({ distinct: ['title'] });
+
+        expect(result).toHaveLength(2);
+        const titles = result.map((p: any) => p.title).sort();
+        expect(titles).toEqual(['A', 'B']);
+    });
+
+    it('orderBy only without distinct', async () => {
+        const db = await setup();
+
+        const result = await db.post.findMany({ orderBy: { title: 'desc' } });
+
+        expect(result).toHaveLength(3);
+        expect(result.map((p: any) => p.title)).toEqual(['B', 'A', 'A']);
+    });
+
+    it('prepends the distinct field to orderBy when user-supplied orderBy does not start with it', async () => {
+        const db = await setup();
+
+        const result = await db.post.findMany({
+            distinct: ['title'],
+            orderBy: { createdAt: 'desc' },
+        });
+
+        expect(result).toHaveLength(2);
+        const titles = result.map((p: any) => p.title).sort();
+        expect(titles).toEqual(['A', 'B']);
+    });
+
+    it('does not double-prepend when user-supplied orderBy already starts with the distinct field', async () => {
+        const db = await setup();
+
+        // User already satisfies pg's requirement: ORDER BY "title" DESC, "createdAt" DESC
+        // The distinct field must NOT be prepended again, which would change sort semantics.
+        const result = await db.post.findMany({
+            distinct: ['title'],
+            orderBy: [{ title: 'desc' }, { createdAt: 'desc' }],
+        });
+
+        expect(result).toHaveLength(2);
+        // With ORDER BY title DESC, we expect 'B' before 'A'
+        expect(result.map((p: any) => p.title)).toEqual(['B', 'A']);
+    });
+});