@ultimat3/entity 29.3.1 → 29.4.0

package/README.md

@@ -534,6 +534,13 @@ export const posts = entity('posts', {
 | Refused | a unique GIN and an ordered GIN, at `entity()` — Postgres has neither, and the refusal names the edit |
 | Naming | the method is part of what separates two indexes on the same columns, so a btree and a GIN on one column are two indexes with two names |
 
+On a big, hot table, build an index with `concurrently: true` — `{ on: ['status'], concurrently:
+true }`. `x db gen` emits `create index concurrently if not exists` in a migration of its own,
+marked `-- transaction: false`, so writes keep flowing while it builds; an interrupted build is
+rebuilt by the next `x db migrate`. It is how the index is built, not what it is: not part of the
+name, not recorded, and toggling it generates nothing. Every index REMOVED from `indexes` is dropped
+the same way, concurrently or not — `@ultimat3/db`'s README, "Indexes built concurrently".
+
 ## Full-text search
 
 `.searchable()` on a `text()` column puts it in the entity's **one** generated `tsvector`, with a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "29.3.1",
+  "version": "29.4.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -33,9 +33,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.3.1",
-    "@ultimat3/db": "29.3.1",
-    "@ultimat3/schema": "29.3.1",
-    "@ultimat3/time": "29.3.1"
+    "@ultimat3/core": "29.4.0",
+    "@ultimat3/db": "29.4.0",
+    "@ultimat3/schema": "29.4.0",
+    "@ultimat3/time": "29.4.0"
   }
 }

package/src/describe.ts

@@ -231,6 +231,8 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
       // Spread, never `?? null`: absent is what `@ultimat3/db` reads as the btree it always was,
       // and a written-out `null` would be a field no existing snapshot carries.
       ...(index.using === undefined ? {} : { using: index.using }),
+      // `true` or absent, never `false`, for the same reason: `x verify` hashes this projection.
+      ...(index.concurrently === true ? { concurrently: true as const } : {}),
     })),
     tags: input.tags,
     cacheTag: input.cacheTag,

package/src/entity.ts

@@ -13,6 +13,7 @@ import { describeEntity, describeReferences } from './describe';
 import { invariantViolated } from './errors';
 import type { InvariantColumns, Resolve } from './expr';
 import { invariantColumns } from './expr';
+import { distinctIndexes } from './index-identity';
 import type { IndexInit } from './index-init';
 import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
@@ -303,6 +304,8 @@ export const entity = <const C extends ColumnMap>(
         // Absent stays absent: `btree` written out would be a field every existing snapshot lacks,
         // and `indexMethodOf` reads the two the same way precisely so nothing regenerates.
         ...(index.using === undefined || index.using === 'btree' ? {} : { using: index.using }),
+        // How it is BUILT, so not part of the name: `true` or absent, like `appendOnly`.
+        ...(index.concurrently === true ? { concurrently: true as const } : {}),
       };
     }),
     // The one index nobody declared and every search needs. Through the SAME `IndexInit` path a
@@ -319,28 +322,8 @@ export const entity = <const C extends ColumnMap>(
           },
         ]),
   ];
-  /**
-   * A foreign key already indexes its column; naming it again in `indexes` is not two indexes.
-   *
-   * On the WHOLE definition and not on the name. With the discriminator above the two rules agree
-   * exactly, so this is not a behaviour change on its own — it is which one FAILS LOUDLY if the
-   * naming is ever weakened again. Matching on the name drops the second index in silence, which
-   * is how two different partial indexes became one for three majors; matching on the definition
-   * keeps both, and two `create index` statements sharing a name is `42P07` on the next migration.
-   */
-  const identity = (index: IndexDef): string =>
-    [
-      index.name,
-      index.columns.join(','),
-      index.unique,
-      index.order ?? '',
-      index.where ?? '',
-      index.using ?? '',
-    ].join('|');
-  const indexes: readonly IndexDef[] = declared.filter(
-    (index, position) =>
-      declared.findIndex((other) => identity(other) === identity(index)) === position,
-  );
+  // A foreign key's own index named again in `indexes` is one index, not two (`index-identity.ts`).
+  const indexes = distinctIndexes(declared);
 
   const sealed = sealedFields({ $name: name, $table: table, $columns: init.columns });
   assertSealedDeclaration({

package/src/index-identity.ts

@@ -0,0 +1,46 @@
+// When two index declarations are ONE index. Split out of `entity.ts` at the 500-line ceiling: a
+// foreign key already indexes its column, and naming it again in `indexes` is not two indexes.
+
+import type { IndexDef } from './types';
+
+/**
+ * WHAT the index is — never how it is built. `concurrently` is left out on purpose: it changes the
+ * migration that builds an index, not the index, so a foreign key's own index and an `indexes:`
+ * entry asking for the same one concurrently are still one index (`distinctIndexes` keeps the ask).
+ */
+const identity = (index: IndexDef): string =>
+  [
+    index.name,
+    index.columns.join(','),
+    index.unique,
+    index.order ?? '',
+    index.where ?? '',
+    index.using ?? '',
+  ].join('|');
+
+/**
+ * Every declared index once, in first-declared order.
+ *
+ * On the WHOLE definition and not on the name. With the name discriminator (`index-name.ts`) the
+ * two rules agree exactly, so this is not a behaviour change on its own — it is which one FAILS
+ * LOUDLY if the naming is ever weakened again. Matching on the name drops the second index in
+ * silence, which is how two different partial indexes became one for three majors; matching on the
+ * definition keeps both, and two `create index` statements sharing a name is `42P07` on the next
+ * migration.
+ *
+ * A duplicate that asks for `concurrently: true` hands that ask to the one kept: dropping it would
+ * silently build a hot table's index inside the migration's transaction after all.
+ */
+export function distinctIndexes(declared: readonly IndexDef[]): readonly IndexDef[] {
+  return declared
+    .filter(
+      (index, position) =>
+        declared.findIndex((other) => identity(other) === identity(index)) === position,
+    )
+    .map((index) =>
+      index.concurrently !== true &&
+      declared.some((other) => other.concurrently === true && identity(other) === identity(index))
+        ? { ...index, concurrently: true as const }
+        : index,
+    );
+}

package/src/index-init.ts

@@ -26,4 +26,16 @@ export interface IndexInit<C extends ColumnMap> {
    * unique and cannot order its keys.
    */
   readonly using?: IndexMethod;
+  /**
+   * Build it with `create index concurrently`, in a migration step of its own that runs OUTSIDE a
+   * transaction — so a big, hot table keeps taking writes while the index builds. A plain `create
+   * index` holds SHARE on the table for the whole build: every insert, update and delete waits.
+   *
+   * How the index is BUILT, never what it is: not part of its name, not recorded in a snapshot,
+   * and switching it on for an existing index generates nothing. `x db gen` writes the step as
+   * `<id>_concurrently.sql` beside the migration (or as the migration, when it is the only change),
+   * marked `-- transaction: false`; an index on a table the same migration creates is still built
+   * inside that migration's transaction — the table is empty and nobody else can see it.
+   */
+  readonly concurrently?: boolean;
 }

package/src/registry.ts

@@ -112,6 +112,11 @@ export interface IndexDescription {
    * predates the field and an index that declares nothing read the same, so nothing regenerates.
    */
   readonly using?: IndexMethod | undefined;
+  /**
+   * `true` when the index is built with `create index concurrently`, outside a transaction; absent
+   * otherwise, so an entity that never asked hashes exactly what it hashed before.
+   */
+  readonly concurrently?: true | undefined;
 }
 
 export interface EntityDescription {

package/src/types.ts

@@ -451,4 +451,6 @@ export interface IndexDef {
    * one fact that this release exists to stop.
    */
   readonly using?: IndexMethod;
+  /** `indexes: [{ concurrently: true }]` — `true` or absent, never `false` (`IndexInit`). */
+  readonly concurrently?: true;
 }