@intx/db

Drizzle ORM client, schema, migrations, and row parsers for the hub's PostgreSQL database. Owns the database-backed GrantStore, the tenant hierarchy walk, the credential resolution layer, the model catalog and its resolution into ordered inference sources, and the parseRow family that validates jsonb columns at the database boundary so internal code never re-checks them.

Consumed by @intx/hub-api (HTTP request handlers and grant middleware) and @intx/hub-sessions (session orchestration and agent repo metadata).

Surface

• @intx/db — the client (createDB), config validator, migration runner, grant store, credential resolution, tenant hierarchy helpers, and the parseRow functions.
• @intx/db/schema — the Drizzle table exports, used by callers that compose queries against the schema directly.

import { createDB } from "@intx/db";
import { agent } from "@intx/db/schema";
import { eq } from "drizzle-orm";

const { db } = createDB(process.env);

const row = await db.query.agent.findFirst({
  where: eq(agent.id, agentId),
});

The parseRow functions (parseWorkflowDefinitionRow, parseGrantRow, and so on) validate each table's jsonb columns once and return fully typed values; downstream code uses those values without re-casting. See CONVENTIONS.md for the project-wide rule against cast-at-callsite in DB consumers.

canExecuteWorkflowRun checks a loaded run's status, cancellation request, and lifetime deadline. For delivery, use withExecutableWorkflowRun with the authenticated allocation identity and a synchronous send callback. It locks the anchor run, which cancellation and retirement of a runnable deployment's allocation also write, then reads the allocation and checks the current time. It takes no lock on the allocation, so a pack receive holding that row does not delay delivery. Finish asynchronous message preparation before calling it; the callback queues frames on the socket and must not wait for a worker acknowledgement. An ineligible run throws WorkflowRunNotExecutableError; database failures remain errors so callers can retry them.

Connections created by createDB set PostgreSQL's statement_timeout to 60,000 milliseconds. Override it with statementTimeoutMs in DBConfig (a positive integer up to 2,147,483,647 milliseconds). The Hub and the bin/ database scripts read this override from DB_STATEMENT_TIMEOUT_MS.

PostgreSQL cancels statements that exceed the deadline, including time waiting for locks. An uncaught timeout rolls back the enclosing transaction. This bounds individual statements once they reach PostgreSQL; pool waits, network stalls, and time between statements in an open transaction remain outside that deadline. Migration clients use their own connection settings.

Model catalog

The model, model_provider, model_offering, and model_pricing tables hold a tenant-scoped catalog of models, the providers that serve them, their pairings (offerings), and append-only multi-currency pricing. catalog-resolution lists the models, providers, and offerings visible to a tenant after walking the ancestor chain leaf-to-root: the nearest tenant to define an entry wins (shadowing), and a disabled entry suppresses it for that tenant and its descendants. model-source-resolution turns an agent's model requirements plus a launch's invoker preferences into an ordered InferenceSource[] — the head is the active source, the tail is the failover chain — dereferencing each offering's provider credential to the secret. pricing.resolveActivePrice selects, per currency, the row in effect at a given time from the append-only history, and getDescendantTenants walks the subtree so a catalog edit can be pushed to every affected running instance.