feat: add nulls option to createIndex (#1489)

jonahkagan · brenoepics · web-flow · commit 1c81b161a92f · 2025-08-13T11:30:35.000Z
Co-authored-by: Breno A. &lt;git@breno.tech&gt;
diff --git a/docs/src/migrations/indexes.md b/docs/src/migrations/indexes.md
@@ -27,6 +27,7 @@
 | `ifNotExists`  | `boolean`                   | default false                                                             |
 | `method`       | `string`                    | btree \| hash \| gist \| spgist \| gin                                    |
 | `include`      | `string` or `array[string]` | columns to add to the include clause                                      |
+| `nulls`        | `string`                    | distinct \| not distinct (for unique indexes only)                        |
 
 ### Examples
 
diff --git a/src/operations/indexes/createIndex.ts b/src/operations/indexes/createIndex.ts
@@ -18,6 +18,8 @@ export interface CreateIndexOptions extends IfNotExistsOption {
   method?: 'btree' | 'hash' | 'gist' | 'spgist' | 'gin';
 
   include?: string | string[];
+
+  nulls?: 'distinct' | 'not distinct';
 }
 
 export type CreateIndexFn = (
@@ -37,8 +39,15 @@ export function createIndex(mOptions: MigrationOptions): CreateIndex {
       method,
       where,
       include,
+      nulls,
     } = options;
 
+    if (nulls && !unique) {
+      throw new Error(
+        'The "nulls" option can only be used with unique indexes.'
+      );
+    }
+
     /*
     columns - the column, columns, or expression to create the index on
 
@@ -49,6 +58,7 @@ export function createIndex(mOptions: MigrationOptions): CreateIndex {
     concurrently -
     ifNotExists - optionally create index
     options.method -  [ btree | hash | gist | spgist | gin ]
+    nulls - nulls distinct or not distinct (for unique indexes only)
     */
     const columns = toArray(rawColumns);
 
@@ -67,10 +77,11 @@ export function createIndex(mOptions: MigrationOptions): CreateIndex {
     const includeStr = include
       ? ` INCLUDE (${toArray(include).map(mOptions.literal).join(', ')})`
       : '';
+    const nullsStr = nulls ? ` NULLS ${nulls.toUpperCase()}` : '';
     const indexNameStr = mOptions.literal(indexName);
     const tableNameStr = mOptions.literal(tableName);
 
-    return `CREATE${uniqueStr} INDEX${concurrentlyStr}${ifNotExistsStr} ${indexNameStr} ON ${tableNameStr}${methodStr} (${columnsString})${includeStr}${whereStr};`;
+    return `CREATE${uniqueStr} INDEX${concurrentlyStr}${ifNotExistsStr} ${indexNameStr} ON ${tableNameStr}${methodStr} (${columnsString})${includeStr}${nullsStr}${whereStr};`;
   };
 
   _create.reverse = dropIndex(mOptions);
diff --git a/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-13.stdout.log b/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-13.stdout.log
@@ -1,4 +1,5 @@
 > Migrating files:
+> - 095_index_nulls
 > - 094_unlogged_table
 > - 093_alter_column_expression
 > - 092_partition
@@ -93,6 +94,10 @@
 > - 003_promise
 > - 002_callback
 > - 001_noop
+### MIGRATION 095_index_nulls (DOWN) ###
+DELETE FROM "public"."pgmigrations" WHERE name='095_index_nulls';
+
+
 ### MIGRATION 094_unlogged_table (DOWN) ###
 DROP TABLE "t_unlogged";
 DROP TABLE "t_regular";
diff --git a/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-14.stdout.log b/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-14.stdout.log
@@ -1,4 +1,5 @@
 > Migrating files:
+> - 095_index_nulls
 > - 094_unlogged_table
 > - 093_alter_column_expression
 > - 092_partition
@@ -93,6 +94,10 @@
 > - 003_promise
 > - 002_callback
 > - 001_noop
+### MIGRATION 095_index_nulls (DOWN) ###
+DELETE FROM "public"."pgmigrations" WHERE name='095_index_nulls';
+
+
 ### MIGRATION 094_unlogged_table (DOWN) ###
 DROP TABLE "t_unlogged";
 DROP TABLE "t_regular";
diff --git a/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-15.stdout.log b/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-15.stdout.log
@@ -1,4 +1,5 @@
 > Migrating files:
+> - 095_index_nulls
 > - 094_unlogged_table
 > - 093_alter_column_expression
 > - 092_partition
@@ -93,6 +94,11 @@
 > - 003_promise
 > - 002_callback
 > - 001_noop
+### MIGRATION 095_index_nulls (DOWN) ###
+DROP TABLE "t095";
+DELETE FROM "public"."pgmigrations" WHERE name='095_index_nulls';
+
+
 ### MIGRATION 094_unlogged_table (DOWN) ###
 DROP TABLE "t_unlogged";
 DROP TABLE "t_regular";
diff --git a/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-16.stdout.log b/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-16.stdout.log
@@ -1,4 +1,5 @@
 > Migrating files:
+> - 095_index_nulls
 > - 094_unlogged_table
 > - 093_alter_column_expression
 > - 092_partition
@@ -93,6 +94,11 @@
 > - 003_promise
 > - 002_callback
 > - 001_noop
+### MIGRATION 095_index_nulls (DOWN) ###
+DROP TABLE "t095";
+DELETE FROM "public"."pgmigrations" WHERE name='095_index_nulls';
+
+
 ### MIGRATION 094_unlogged_table (DOWN) ###
 DROP TABLE "t_unlogged";
 DROP TABLE "t_regular";
diff --git a/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-17.stdout.log b/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-17.stdout.log
@@ -1,4 +1,5 @@
 > Migrating files:
+> - 095_index_nulls
 > - 094_unlogged_table
 > - 093_alter_column_expression
 > - 092_partition
@@ -93,6 +94,11 @@
 > - 003_promise
 > - 002_callback
 > - 001_noop
+### MIGRATION 095_index_nulls (DOWN) ###
+DROP TABLE "t095";
+DELETE FROM "public"."pgmigrations" WHERE name='095_index_nulls';
+
+
 ### MIGRATION 094_unlogged_table (DOWN) ###
 DROP TABLE "t_unlogged";
 DROP TABLE "t_regular";
diff --git a/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-up.pg-13.stdout.log b/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-up.pg-13.stdout.log
@@ -93,6 +93,7 @@
 > - 092_partition
 > - 093_alter_column_expression
 > - 094_unlogged_table
+> - 095_index_nulls
 ### MIGRATION 001_noop (UP) ###
 INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('001_noop', NOW());
 
@@ -812,4 +813,8 @@ ALTER TABLE "t_regular"
 INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('094_unlogged_table', NOW());
 
 
+### MIGRATION 095_index_nulls (UP) ###
+INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('095_index_nulls', NOW());
+
+
 Migrations complete!
diff --git a/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-up.pg-14.stdout.log b/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-up.pg-14.stdout.log
@@ -93,6 +93,7 @@
 > - 092_partition
 > - 093_alter_column_expression
 > - 094_unlogged_table
+> - 095_index_nulls
 ### MIGRATION 001_noop (UP) ###
 INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('001_noop', NOW());
 
@@ -812,4 +813,8 @@ ALTER TABLE "t_regular"
 INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('094_unlogged_table', NOW());
 
 
+### MIGRATION 095_index_nulls (UP) ###
+INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('095_index_nulls', NOW());
+
+
 Migrations complete!
diff --git a/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-up.pg-15.stdout.log b/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-up.pg-15.stdout.log
@@ -93,6 +93,7 @@
 > - 092_partition
 > - 093_alter_column_expression
 > - 094_unlogged_table
+> - 095_index_nulls
 ### MIGRATION 001_noop (UP) ###
 INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('001_noop', NOW());
 
@@ -812,4 +813,12 @@ ALTER TABLE "t_regular"
 INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('094_unlogged_table', NOW());
 
 
+### MIGRATION 095_index_nulls (UP) ###
+CREATE TABLE "t095" (
+  "id" integer
+);
+CREATE UNIQUE INDEX "t095_id_unique_index" ON "t095" ("id") NULLS NOT DISTINCT;
+INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('095_index_nulls', NOW());
+
+
 Migrations complete!
diff --git a/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-up.pg-16.stdout.log b/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-up.pg-16.stdout.log
@@ -93,6 +93,7 @@
 > - 092_partition
 > - 093_alter_column_expression
 > - 094_unlogged_table
+> - 095_index_nulls
 ### MIGRATION 001_noop (UP) ###
 INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('001_noop', NOW());
 
@@ -812,4 +813,12 @@ ALTER TABLE "t_regular"
 INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('094_unlogged_table', NOW());
 
 
+### MIGRATION 095_index_nulls (UP) ###
+CREATE TABLE "t095" (
+  "id" integer
+);
+CREATE UNIQUE INDEX "t095_id_unique_index" ON "t095" ("id") NULLS NOT DISTINCT;
+INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('095_index_nulls', NOW());
+
+
 Migrations complete!
diff --git a/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-up.pg-17.stdout.log b/test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-up.pg-17.stdout.log
@@ -93,6 +93,7 @@
 > - 092_partition
 > - 093_alter_column_expression
 > - 094_unlogged_table
+> - 095_index_nulls
 ### MIGRATION 001_noop (UP) ###
 INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('001_noop', NOW());
 
@@ -822,4 +823,12 @@ ALTER TABLE "t_regular"
 INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('094_unlogged_table', NOW());
 
 
+### MIGRATION 095_index_nulls (UP) ###
+CREATE TABLE "t095" (
+  "id" integer
+);
+CREATE UNIQUE INDEX "t095_id_unique_index" ON "t095" ("id") NULLS NOT DISTINCT;
+INSERT INTO "public"."pgmigrations" (name, run_on) VALUES ('095_index_nulls', NOW());
+
+
 Migrations complete!
diff --git a/test/migration.spec.ts b/test/migration.spec.ts
@@ -80,7 +80,7 @@ describe('migration', () => {
       const filePaths = await getMigrationFilePaths(dir, { logger });
 
       expect(Array.isArray(filePaths)).toBeTruthy();
-      expect(filePaths).toHaveLength(94);
+      expect(filePaths).toHaveLength(95);
       expect(filePaths).not.toContainEqual(expect.stringContaining('nested'));
 
       for (const filePath of filePaths) {
@@ -101,7 +101,7 @@ describe('migration', () => {
       });
 
       expect(Array.isArray(filePaths)).toBeTruthy();
-      expect(filePaths).toHaveLength(69);
+      expect(filePaths).toHaveLength(70);
 
       for (const filePath of filePaths) {
         expect(isAbsolute(filePath)).toBeTruthy();
@@ -117,7 +117,7 @@ describe('migration', () => {
       });
 
       expect(Array.isArray(filePaths)).toBeTruthy();
-      expect(filePaths).toHaveLength(107);
+      expect(filePaths).toHaveLength(108);
       expect(filePaths).toContainEqual(expect.stringContaining('nested'));
 
       for (const filePath of filePaths) {
@@ -137,7 +137,7 @@ describe('migration', () => {
       });
 
       expect(Array.isArray(filePaths)).toBeTruthy();
-      expect(filePaths).toHaveLength(106);
+      expect(filePaths).toHaveLength(107);
       expect(filePaths).toContainEqual(expect.stringContaining('nested'));
 
       for (const filePath of filePaths) {
@@ -167,7 +167,7 @@ describe('migration', () => {
         ignorePattern
       );
 
-      expect(nextPrefix).toEqual('095');
+      expect(nextPrefix).toEqual('096');
     });
 
     it('should fail to get the next index with invalid filenames', async () => {
diff --git a/test/migrations/095_index_nulls.js b/test/migrations/095_index_nulls.js
@@ -0,0 +1,24 @@
+const getMajorVersion = async (pgm) => {
+  const [{ server_version: version }] = await pgm.db.select(
+    'SHOW "server_version"'
+  );
+  const [major] = version.split('.');
+  return Number(major);
+};
+
+const isSupportedVersion = (major) => major >= 15;
+
+export const up = async (pgm) => {
+  const major = await getMajorVersion(pgm);
+  if (isSupportedVersion(major)) {
+    pgm.createTable('t095', { id: { type: 'integer' } });
+    pgm.createIndex('t095', 'id', { unique: true, nulls: 'not distinct' });
+  }
+};
+
+export const down = async (pgm) => {
+  const major = await getMajorVersion(pgm);
+  if (isSupportedVersion(major)) {
+    pgm.dropTable('t095');
+  }
+};
diff --git a/test/operations/indexes/createIndex.spec.ts b/test/operations/indexes/createIndex.spec.ts
@@ -28,11 +28,12 @@ describe('operations', () => {
           concurrently: true,
           ifNotExists: true,
           include: ['director', 'rating'],
+          nulls: 'not distinct',
         });
 
         expect(statement).toBeTypeOf('string');
         expect(statement).toBe(
-          'CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS "films_title_unique_index" ON "films" ("title") INCLUDE ("director", "rating");'
+          'CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS "films_title_unique_index" ON "films" ("title") INCLUDE ("director", "rating") NULLS NOT DISTINCT;'
         );
       });
 
@@ -142,6 +143,27 @@ describe('operations', () => {
           ['xTable', ['yName'], { name: 'zIndex', include: 'someOtherColumn' }],
           'CREATE INDEX "z_index" ON "x_table" ("y_name") INCLUDE ("some_other_column");',
         ],
+        // should add nulls option
+        [
+          'should add nulls option 1',
+          options1,
+          [
+            'xTable',
+            ['yName'],
+            { name: 'zIndex', unique: true, nulls: 'distinct' },
+          ],
+          'CREATE UNIQUE INDEX "zIndex" ON "xTable" ("yName") NULLS DISTINCT;',
+        ],
+        [
+          'should add nulls option 2',
+          options2,
+          [
+            'xTable',
+            ['yName'],
+            { name: 'zIndex', unique: true, nulls: 'not distinct' },
+          ],
+          'CREATE UNIQUE INDEX "z_index" ON "x_table" ("y_name") NULLS NOT DISTINCT;',
+        ],
       ] as const)(
         '%s',
         (_, optionPreset, [tableName, columns, options], expected) => {
@@ -158,6 +180,12 @@ describe('operations', () => {
         }
       );
 
+      it('should throw an error if nulls option is used without unique index', () => {
+        expect(() =>
+          createIndexFn('films', ['title'], { nulls: 'distinct' })
+        ).toThrow('The "nulls" option can only be used with unique indexes.');
+      });
+
       describe('reverse', () => {
         it('should contain a reverse function', () => {
           expect(createIndexFn.reverse).toBeTypeOf('function');
