Repository navigation
docs(orm-postgres,orm-family-sql): document public entry points for SQL errors, pool factory, AST builders, target descriptor and migration reader #31165
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -42,9 +42,47 @@ A generated `contract.d.ts` imports every framework, family and target type it n | |
| | `/family-contract`, `/family-contract/*` | `@prisma/orm-family-sql/contract` | | ||
| | `/target/*` | `@prisma/orm-target-postgres/target` | | ||
| | `/adapter`, `/adapter/*` | `@prisma/orm-target-postgres/adapter` | | ||
| | `/driver`, `/driver/*` | `@prisma/orm-target-postgres/driver` | | ||
| | `/relational-core`, `/relational-core/*` | `@prisma/orm-family-sql/relational-core` | | ||
| | `/migration-tools/*` | `@prisma/orm-toolchain/migration-tools` | | ||
|
|
||
| These forward; they do not copy. `@prisma/orm-postgres/contract/types` and `@prisma/orm-framework/contract/types` are the same module, so shared registries and `instanceof` checks hold across the boundary. | ||
|
|
||
| ## Lower-level entry points | ||
|
|
||
| Beneath the client factories the facade also publishes the layers they are built from, as stable subpaths code names directly when it needs the layer beneath the client: an expression the raw-SQL lane cannot infer a codec for, a caller-owned pool, a decomposed install, a script that audits migrations. | ||
|
|
||
| | Entrypoint | Surface | | ||
| | --- | --- | | ||
| | `/relational-core/expression` | the expression helpers: `param(value, { codecId })` wraps a literal value whose codec the raw-SQL lane cannot infer (the fix `RUNTIME.RAW_SQL_UNSUPPORTED_INTERPOLATION` names; a query fragment interpolates directly and must not be wrapped), `toExpr(value, codec?)` lifts an expression or a raw value into an AST expression — a raw value requires `codec` (without one it throws `RUNTIME.PARAM_REF_CODEC_REQUIRED`), an expression does not, `buildOperation(spec)` builds a custom operation's AST | | ||
| | `/relational-core/ast` | the relational AST classes a plan's query is built from (`ColumnRef`, `ParamRef`, `LiteralExpr`, `BinaryExpr`, `TableSource`, …) | | ||
| | `/relational-core/types` | the plan and scope types: `SqlOrmPlan`, the shape `db.query(plan)` and `db.execute(plan)` accept | | ||
| | `/driver/runtime` | `createPgPool(config, sessionSettings)` and `createPgClient(config, sessionSettings)` — a pool or client whose every session starts with the session settings the target declares | | ||
| | `/target/runtime` | the Postgres runtime target descriptor (the default export), with `sessionSettings` and the codec, query-operation and collection-method contributions a decomposed install composes | | ||
| | `/migration-tools/io` | the migration package reader: `readMigrationPackage(dir, options)` reads one package, `readMigrationsDir(root, options)` reads the graph directory, returns per-package load problems in `problems`, skips directories without `migration.json` silently, and throws for filesystem errors while listing the root or stat-ing an entry | | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Document the missing-root exception. If the migrations root does not exist,
|
||
|
|
||
| ```ts | ||
| import { param } from '@prisma/orm-postgres/relational-core/expression'; | ||
| import { createPgPool } from '@prisma/orm-postgres/driver/runtime'; | ||
| import postgresTarget from '@prisma/orm-postgres/target/runtime'; | ||
|
|
||
| // A value the raw-SQL lane would refuse (anything not number, bigint, string, | ||
| // boolean or Uint8Array) is wrapped with an explicit codec: | ||
| const plan = db.raw | ||
| .sql`SELECT id FROM event WHERE at > ${param(myTimestamp, { codecId: 'pg/timestamptz-temporal@1' })}` | ||
| .returnsRow({ id: 'pg/int8@1' }) | ||
| .build(); | ||
|
|
||
| // A caller-owned pool whose sessions start with the same settings the | ||
| // facade-owned pool gets: | ||
| const pool = createPgPool( | ||
| { connectionString: process.env['DATABASE_URL'] }, | ||
| postgresTarget.sessionSettings ?? {}, | ||
| ); | ||
| ``` | ||
|
|
||
| A decomposed install (see *Decomposing* below) composes the runtime stack from the descriptors these entry points carry: the target, the driver, and the adapter of its choice passed to `createSqlExecutionStack`. Under the facade the stack builder is `@prisma/orm-postgres/family-runtime`; a decomposed install composes the same modules through the platform packages (`@prisma/orm-target-postgres/target/runtime`, `@prisma/orm-target-postgres/driver/runtime`, `@prisma/orm-family-sql/runtime`), which are the exact-pinned dependencies the facade would have installed. | ||
|
|
||
| ## The CLI | ||
|
|
||
| This package ships no bin. The ORM commands run inside the unified `prisma` CLI, which mounts the command family published at `@prisma/orm-toolchain/cli`. | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Qualify the code-less error case.
A code-less pg connection failure can become a
SqlConnectionError.normalizePgConnectFailurewraps it and retains the original error as itscause. State that code-less errors can surface unchanged, except when the driver identifies a connection failure.