# Constructive Orm

> Use the optional generated Constructive ORM for typed queries, mutations, relations, pagination, and custom-domain server workflows against a stable GraphQL schema. Use when asked about findMany, findOne, create, update, delete, relations, or pagination in generated ORM code. Use Blocks runtime for dynamic tenant consoles and generic _meta CRUD.

- Skill: `constructive-io/constructive-orm` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add constructive-io/constructive-orm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/constructive-io/constructive-orm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: constructive-io (https://skillmd.com/u/constructive-io)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/constructive-io/constructive-orm

---


# Constructive ORM

Use the generated Prisma-like ORM for stable custom-domain schemas. It is optional and must remain endpoint-scoped. Console Kit uses runtime discovery, standalone Data introspects through Sheets, and the other standalone feature packs receive resources and actions from their host.

## When to Apply

Use this skill when:

- A project has deliberately generated an ORM from a stable domain schema.
- Implementing typed queries, mutations, relations, or pagination in server code.
- Creating a client for one explicit endpoint and request/session scope.
- Debugging generated ORM output or regeneration drift.

Use [`constructive-blocks`](../constructive-blocks/SKILL.md) for Console Kit and feature-pack data. Use [`constructive-frontend`](../constructive-frontend/SKILL.md) for bespoke runtime `_meta` UI.

## Blocks Package Gate

The pinned Blocks snapshot is branch-only with
`release.publicRegistryReady: false`. Before importing the current
`@constructive-io/data` contract from an ORM workflow, run the
`constructive-blocks` source preflight and pinned local package-consumption
workflow. The same rule applies whenever an ORM-adjacent task reaches for the
current `@constructive-io/ui`, `@constructive-io/schema-builder`, or
`@constructive-io/sheets` package or an `@constructive` registry root. Public
installation becomes valid only after an updated Blocks snapshot points to a
released commit, sets `publicRegistryReady: true`, and passes its checker.

## Per-Scope Client

Create the ORM client from an explicit endpoint for the current request or tenant. Do not export a mutable process-wide client when endpoints or identities can change.

```ts
import { createClient } from '@/generated/orm';

export function createDomainClient(endpoint: string, accessToken: string) {
  return createClient({
    endpoint,
    headers: { Authorization: `Bearer ${accessToken}` }
  });
}
```

Keep the token in the host session or server request boundary and create/dispose the binding with that scope.

## Query and Mutation Shape

```ts
const db = createDomainClient(dataEndpoint, accessToken);

const projectsResult = await db.project.findMany({
  select: { id: true, name: true, completed: true },
  first: 20
}).unwrap();
const projects = projectsResult.projects.nodes;

await db.project.update({
  where: { id: projectId },
  data: { completed: true },
  select: { id: true, completed: true }
}).unwrap();
```

Every model method returns a `QueryBuilder`. Use `.execute()` for the `QueryResult` discriminated union or call `.unwrap()`, `.unwrapOr()`, or `.unwrapOrElse()` directly on the builder. List data remains under the generated GraphQL field, such as `projectsResult.projects.nodes`. Never interpret an empty collection as proof that the schema lacks rows—the active identity's RLS policy may be filtering them.

## Pagination

Prefer cursor pagination for mutable datasets and stable traversal. Offset pagination is suitable for bounded administrative views where page-number navigation matters and drift is acceptable.

See [pagination.md](./references/pagination.md) for generated pagination patterns.

## Runtime Metadata

The generated ORM is not the owner of the current `_meta` contract. After the
pinned local package workflow is active, import the contract documents, types,
compatibility guards, and operation-analysis helpers from
`@constructive-io/data`, then reconcile `_meta` with standard introspection.

See [query-meta-introspection.md](./references/query-meta-introspection.md) for the evidence model. Use the Data feature pack instead of rebuilding generic table CRUD.

## References

| File | Content |
|---|---|
| [codegen-orm-output.md](./references/codegen-orm-output.md) | Generated ORM output |
| [codegen-orm-patterns.md](./references/codegen-orm-patterns.md) | Advanced custom-domain patterns |
| [pagination.md](./references/pagination.md) | Cursor and offset pagination |
| [query-generators-api.md](./references/query-generators-api.md) | Runtime operation generators |
| [query-runtime.md](./references/query-runtime.md) | Runtime query construction |
| [query-meta-introspection.md](./references/query-meta-introspection.md) | Current `_meta` and introspection boundary |
| [codegen-query-keys.md](./references/codegen-query-keys.md) | Generated query keys |

## Cross-References

- [`constructive-codegen`](../constructive-codegen/SKILL.md) — generation and regeneration.
- [`constructive-hooks`](../constructive-hooks/SKILL.md) — optional fixed-endpoint React Query layer.
- [`constructive-security`](../constructive-security/SKILL.md) — RLS and effective authorization.