CodeVetter · Repo Unpack · Data flow
prisma/prisma
Authoring starts in prisma.config.ts, where defineConfig binds a family, target, adapter, driver, and extensions to a contract source. Emit loads that source, enriches it with component descriptors, round-trips it through the target serializer, and writes a canonical JSON document plus a generated contract.d.ts. At runtime the Postgres client revalidates that JSON into a typed contract, and the SQL runtime lowers a query plan to SQL, encodes parameters, checks the marker, and decodes rows. Schema changes are a separate pipeline: introspect the database, plan a contract-space aggregate, and apply operations under a class policy. CLI telemetry is a side channel that forks a sender after the command settles.
- Postgres defineConfig calls core defineConfig with family sql, target postgres, adapter postgresAdapter, driver postgresDriver, the caller extensions array, and a normalized contract config. Output defaults beside the first contract input when the caller omits it.
- executeContractEmit is the single publication path for the CLI and the Vite plugin. It requires config.contract, a source.load function, and an output path; builds a control stack; calls source.load with composed extension ids, authoring contributions, codec lookup, and capabilities; then enrichContract, target serializeContract, and family deserializeContract before emit.
- @internal/emitter emit rejects the call unless to-one relations declare nullability, canonicalizes with schemaVersion "1" via the target serializeContract hook, stamps a _generated warning, and returns contractJson, prettier-formatted contract.d.ts, storageHash, optional executionHash, and profileHash.
- The emit JSDoc says publication is serialized per output JSON path by queueEmitByOutput (last submission wins) and that publishContractArtifactPair stages temp files, renames contract.d.ts before contract.json, and tries to restore the previous pair if a rename fails.
- postgres() either serializes an in-memory contract or accepts contractJson, then always deserializes through PostgresContractSerializer so the runtime object is the validated form. A url binding becomes a pg Pool (connectionTimeoutMillis default 20000, idleTimeoutMillis default 30000) wrapped in suppressIdleConnectionErrors.
- sql() builds a BuilderContext from contract capabilities, query operation types, target, storageHash, and mutation defaults, then returns a Proxy: the first key is a storage namespace id, the second is a table resolved by resolveTableInNamespace and wrapped in TableProxyImpl.
- queryAgainstQueryable validates the codec registry once, calls prepareQueryExecution, buildDecodeContext, and streamRows. prepareOperation, for a not-yet-lowered plan, runs compilePlan, lowerToDraft, a SqlParamRefMutator before-hook, and encodeParams. streamRows then setupDriverExecution, runQueryWithMiddleware, and decodeRow.
- verifyMarker reads the family marker. If the marker is absent it logs CONTRACT.MARKER_MISSING and returns. If storageHash or profileHash differs it logs CONTRACT.MARKER_MISMATCH and returns. It does not throw, so execution continues. The first call is single-flighted on verifyMarkerPromise unless verifyMarker was set to false.
- executeDbUpdate uses policy classes additive, widening, and destructive and delegates to executeRun. db-run.ts documents the strategy as introspect then planMigration, and imports buildContractSpaceAggregate, planMigration, and runMigration. In apply mode without acceptDataLoss or consent, guardDestructiveChanges pre-plans and returns DESTRUCTIVE_CHANGES with databaseName and planHash.
- createControlClient builds a ControlStack from family, target, adapter, driver, and extensions, creates the family instance, and asserts framework-component compatibility before any connect. connect refuses a second connection until close and errors with CONFIG.DB_CONNECTION_REQUIRED when no connection was supplied.
- On non-CI processes with telemetry enabled, resolveTelemetryHooks prints a first-run notice, then onSettled fires runTelemetry with the command path, CLI version, exit code, and cwd. The sender forks detached. The POST URL is TELEMETRY_ENDPOINT_PATH /events on https://cmpbfbsdp09hr3jf7pojjs5qs.ewr.prisma.build, overridable only by PRISMA_TELEMETRY_ENDPOINT.
- loadContractFromTs bundles a user TypeScript contract with esbuild (platform node, target es2022) into a file under os.tmpdir named prisma-8-contract-*.mjs. The default import allowlist is @internal/*, @prisma/orm-*, and node:crypto. Imports from the entry that fail the allowlist become CONTRACT.SOURCE_IMPORT_DISALLOWED. Relative and absolute imports are not filtered.