Contract Authoring

An IndexedDB contract describes models, object stores, indexes, relations, and execution defaults. You can author it in Prisma Schema Language (PSL) or TypeScript.

Both surfaces lower into the same internal IdbContractDefinition. One validator checks the definition, and buildIdbContractFromDefinition assembles the contract and computes its hashes. These internal types and functions are not authoring entry points. Equivalent definitions produce the same storageHash, profileHash, and executionHash, regardless of the authoring surface.

Entry points

Both surfaces accept projection: "full" (the default) or projection: "client". Client projection removes excluded models and fields. See Client Contracts for the exclusion rules.

For PSL editor hints, start the schema with // use prisma-8 as its first line. This selects the Prisma 8 language server in the Prisma VS Code extension, which reads the configured IDB family's scalar and attribute metadata. See Editor Setup for setup and troubleshooting.

Attributes and TypeScript declarations

The TypeScript input contains family, target, optional enums, and models. Each model declares its store, key, and scalar or enum fields. Relations are separate from fields.

PSL uses a model name with its first letter lowercased as the default store name. TypeScript requires an explicit store. Index names default to the joined field names, with _unique for unique indexes. TypeScript uses the keys of indexes as names.

Both onDelete and onUpdate default to Restrict in PSL and "restrict" in TypeScript. The other actions are SetDefault / "setDefault" and NoAction / "noAction". NoAction behaves like Restrict.

TypeScript uses "1:N" for a backrelation and "1:1" or "N:1" for a to-one relation. For a backrelation, on.local names the parent key and on.target names the child's foreign key. To-one nullability defaults to whether any local field is nullable. The optional nullable property overrides it.

Only enum fields can be lists. Lists cannot be optional. The Schema & Config reference lists scalar types and IndexedDB key restrictions.

Equivalent contracts

These definitions produce the same contract, including the implicit userId index and execution defaults.

// use prisma-8

model User {
  id    String @id
  todos Todo[]
}

model Todo {
  id        String   @id @default(uuid())
  userId    String
  user      User     @relation(fields: [userId], references: [id])
  title     String   @default("Untitled")
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

import family from "@prisma-idb/family-idb/pack";
import target from "@prisma-idb/target-idb/pack";
import { defineContract, now, updatedAt, uuidv4 } from "@prisma-idb/family-idb/contract-ts";

export default defineContract({
  family,
  target,
  models: {
    User: {
      store: "user",
      key: "id",
      fields: { id: "String" },
      relations: {
        todos: { to: "Todo", cardinality: "1:N", on: { local: ["id"], target: ["userId"] } },
      },
    },
    Todo: {
      store: "todo",
      key: "id",
      fields: { id: "String", userId: "String", title: "String", createdAt: "DateTime", updatedAt: "DateTime" },
      defaults: { id: uuidv4(), title: "Untitled", createdAt: now(), updatedAt: updatedAt() },
      relations: {
        user: { to: "User", cardinality: "N:1", on: { local: ["userId"], target: ["id"] } },
      },
    },
  },
});

Execution defaults

TypeScript helpers come from @prisma-idb/family-idb/contract-ts and appear in the model's defaults map.

Generated defaults require non-nullable fields. A field cannot combine @updatedAt with @default(...). Enum-list defaults are unsupported.

Create defaults apply when the field is omitted. An explicitly supplied value takes precedence. updatedAt() also supplies an omitted timestamp during updates. A defaulted foreign key still undergoes referential-integrity checks.

A literal in defaults also supplies the value for the setDefault referential action. The older fieldDefaults map supplies only that referential-action value; it does not fill omitted fields on create. A field cannot appear in both maps.

Runtime defaults contribute to contract.execution.executionHash. autoincrement() changes storage metadata instead, so it contributes to storageHash. profileHash describes target capabilities.

Foreign-key indexes

Both surfaces add a non-unique, single-field index for every foreign-key field of a to-one relation. The index is named after the field. A compound foreign key gets one index per field. Backrelations ("1:N") do not add indexes on the parent.

A declared index with the same name and the same single-field key path replaces the implicit index, including its uniqueness setting. A differently named index or a compound index does not replace it. A conflicting index name produces IDB_INVALID_INDEX.

TypeScript relations accept index: false to suppress their implicit indexes. This does not remove declared indexes. If several relations share a foreign-key field, each owning relation must opt out to suppress its implicit index. PSL has no opt-out.

An implicit index has the same key-type restrictions as a declared index. A TypeScript relation with a Boolean, BigInt, or Json foreign key needs index: false to avoid an invalid index.

The default can change the storageHash of an existing TypeScript contract. See Adopt foreign-key indexes for the migration procedure.

Diagnostics and errors

Shared validation reports the same IDB_* codes and messages on both surfaces. PSL diagnostics retain source spans. The PSL provider and editor also report parser and binder diagnostics, which can use codes outside IDB_*.

defineContract throws IdbContractError for shared validation failures. Its diagnostics array contains code, message, and at, a path of definition names and attribute coordinates. Its message lists the codes and messages. TypeScript input-shape checks can fail before shared validation, so callers should handle other errors too.

import { defineContract, IdbContractError, type DefineContractInput } from "@prisma-idb/family-idb/contract-ts";

/** Builds an authored contract and reports structured validation failures. */
export function buildContract(input: DefineContractInput) {
  try {
    return defineContract(input);
  } catch (error) {
    if (error instanceof IdbContractError) {
      for (const diagnostic of error.diagnostics) {
        console.error(diagnostic.code, diagnostic.message, diagnostic.at);
      }
    }
    throw error;
  }
}

Keys and indexes

Fields, enums, and defaults

Relations and client projection