@prisma-next/adapter-postgres
Advanced tools
PostgreSQL adapter for Prisma Next.
The PostgreSQL adapter implements the adapter SPI for PostgreSQL databases. It provides SQL lowering, capability discovery, codec definitions, and error mapping for PostgreSQL-specific behavior. It also exports both control-plane and runtime-plane adapter descriptors for config wiring.
Provide PostgreSQL-specific adapter implementation, codecs, and capabilities. Enable PostgreSQL dialect support in Prisma Next through the adapter SPI.
Adapter SPI for PostgreSQL
json_agg, json_build_object) and scalar subquerieslateral, jsonAgg)RuntimeError envelopeNon-goals:
This package spans multiple planes:
src/core/**): Core adapter implementation, codecs, and types that can be imported by both migration and runtime planessrc/exports/control.ts): Control-plane entry point that exports the adapter descriptor for config filessrc/exports/runtime.ts): Runtime-plane entry point that exports the runtime adapter descriptorflowchart TD
subgraph "Runtime"
RT[Runtime]
PLAN[Plan]
end
subgraph "Postgres Adapter"
ADAPTER[Adapter]
LOWERER[Lowerer]
CODECS[Codecs]
CAPS[Capabilities]
end
subgraph "Postgres Driver"
DRIVER[Driver]
PG[(PostgreSQL)]
end
subgraph "Descriptors"
CONTROL[Control Descriptor]
RUNTIME_DESC[Runtime Descriptor]
CODECTYPES[Codec Types]
end
RT --> PLAN
PLAN --> ADAPTER
ADAPTER --> LOWERER
ADAPTER --> CODECS
ADAPTER --> CAPS
ADAPTER --> DRIVER
DRIVER --> PG
CONTROL --> RT
RUNTIME_DESC --> RT
CODECTYPES --> RT
CODECS --> CODECTYPES
src/core/)Adapter (adapter.ts)
json_agg, json_build_object) and scalar subquerieslateral, jsonAgg, returning)RuntimeErrorCodecs (codecs.ts)
sql/char, sql/varchar, sql/int, sql/floatpg/char, pg/varchar, pg/int, pg/floatint2, int4, int8, float4, float8, text, bool, enumint2, int4, int8, float4, float8, text, timestamp, timestamptz, bool, enum, json, jsonbcharacter(n), character varying(n), numeric(p,s), bit(n), bit varying(n), timestamp(p), timestamptz(p), time(p), timetz(p), interval(p)Types (types.ts)
src/exports/)Control Entry Point (control.ts)
prisma-next.config.ts to declare the adapterRuntime Entry Point (runtime.ts)
Adapter Export (adapter.ts)
createPostgresAdapter from coreCodec Types Export (codec-types.ts)
contract.d.ts generationTypes Export (types.ts)
Column Types Export (column-types.ts)
Exports column descriptors for built-in types and enum helpers (enumType, enumColumn(typeRef, nativeType))
Parameterized helpers: charColumn(length), varcharColumn(length), numericColumn(precision, scale?), bitColumn(length), varbitColumn(length), timeColumn(precision?), timetzColumn(precision?), intervalColumn(precision?)
Exports raw JSON helpers:
jsonColumn, jsonbColumn — untyped raw JSON / JSONB column descriptors@prisma-next/extension-arktype-json for arktype). The schema-accepting json(schema) / jsonb(schema) overloads previously shipped here retired in Phase C of the codec-registry-unification project.@prisma-next/sql-contract: SQL contract types@prisma-next/sql-relational-core: SQL AST types and codec registry@prisma-next/cli: CLI config types and extension pack manifest types@prisma-next/extension-arktype-json for arktype); see ADR 208 - Higher-order codecs for parameterized types.import { createPostgresAdapter } from '@prisma-next/adapter-postgres/adapter';
import { createRuntime } from '@prisma-next/sql-runtime';
const runtime = createRuntime({
contract,
adapter: createPostgresAdapter(),
driver: postgresDriver,
});
import postgresAdapter from '@prisma-next/adapter-postgres/control';
export default defineConfig({
family: sql,
target: postgres,
adapter: postgresAdapter,
extensions: [],
});
The adapter declares the following PostgreSQL capabilities:
orderBy: true - Supports ORDER BY clauseslimit: true - Supports LIMIT clauseslateral: true - Supports LATERAL joinsjsonAgg: true - Supports JSON aggregation functions (json_agg)returning: true - Supports RETURNING clauses for DML operations (INSERT, UPDATE, DELETE)sql.enums: true - Supports contract-defined enum storage typesImportant: Capabilities must be declared in both places:
src/exports/control.ts and src/exports/runtime.ts): Capabilities are read during emission and included in the contractsrc/core/adapter.ts): The defaultCapabilities constant is used at runtime via adapter.profile.capabilitiesThe capabilities on the descriptor must match the capabilities in code. If they don't match, emitted contracts and runtime capability checks will diverge.
See docs/reference/capabilities.md and docs/architecture docs/subsystems/5. Adapters & Targets.md for details.
The renderer lowers JSON-aggregation AST nodes to PostgreSQL's json_agg:
json_agg(json_build_object(...)) aggregates a row set into a JSON array of objectsSubqueryExpr) in the SELECT list correlates against the outer row through its WHERE clauseORDER BY and LIMIT, its rows are wrapped in an inner SELECT, then aggregated with json_agg(row_to_json(sub.*))Example SQL Output:
SELECT "user"."id" AS "id", (
SELECT json_agg(json_build_object('id', "post"."id", 'title', "post"."title")) AS "posts"
FROM "post"
WHERE "user"."id" = "post"."userId"
) AS "posts"
FROM "user"
The adapter supports RETURNING clauses for DML operations (INSERT, UPDATE, DELETE), allowing you to return affected rows:
Lowering Strategy:
RETURNING clause after INSERT, UPDATE, or DELETE statementsCapability Required:
returning: true - Enables RETURNING clause supportExample SQL Output:
-- INSERT with RETURNING
INSERT INTO "user" ("email", "createdAt") VALUES ($1, $2) RETURNING "user"."id", "user"."email"
-- UPDATE with RETURNING
UPDATE "user" SET "email" = $1 WHERE "user"."id" = $2 RETURNING "user"."id", "user"."email"
-- DELETE with RETURNING
DELETE FROM "user" WHERE "user"."id" = $1 RETURNING "user"."id", "user"."email"
Note: MySQL does not support RETURNING clauses. A future MySQL adapter would declare returning: false and either reject plans with RETURNING or provide an alternative implementation.
The adapter supports PostgreSQL-native json and jsonb columns.
Both json and jsonb accept any valid JSON value:
null (distinct from SQL NULL)jsonb uses normalized binary storage, so whitespace and object key order are not preserved.
import { jsonbColumn } from '@prisma-next/adapter-postgres/column-types';
import { arktypeJson } from '@prisma-next/extension-arktype-json/column-types';
import { type as arktype } from 'arktype';
const auditPayloadSchema = arktype({
action: 'string',
actorId: 'number',
});
table('event', (t) =>
t
// Schema-typed JSONB via the per-library extension package.
.column('payload', { type: arktypeJson(auditPayloadSchema), nullable: false })
// Untyped raw JSONB via the adapter's static descriptor.
.column('raw', { type: jsonbColumn, nullable: true }),
);
@prisma-next/extension-arktype-json). The emit-path renderer reads the schema's expression from typeParams and produces a concrete TS type in contract.d.ts.jsonColumn, jsonbColumn), the emitted type falls back to JsonValue../adapter: Adapter implementation (createPostgresAdapter)./codec-types: PostgreSQL codec types (CodecTypes, JsonValue)./column-types: Column type descriptors and authoring helpers (jsonColumn, jsonbColumn, enumType, enumColumn, textColumn, int4Column, etc.)./types: PostgreSQL-specific types./control: Control-plane entry point (adapter descriptor)./runtime: Runtime-plane entry point (runtime adapter descriptor)FAQs
PostgreSQL adapter for Prisma Next.
The npm package @prisma-next/adapter-postgres receives a total of 22,837 weekly downloads. As such, @prisma-next/adapter-postgres popularity was classified as popular.
We found that @prisma-next/adapter-postgres demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
A fake corepack.org site is impersonating the Node.js tool and delivers an infostealer and proxyware to developers who download it.
Research
/Security News
A large-scale campaign abused GitHub Actions in compromised repositories to exploit CVE-2026-41940 in cPanel and WHM and steal server credentials.
Security News
Five frontier LLMs generated the same nonexistent package names, leaving 53 available for potential slopsquatting across PyPI and npm.