Skip to content

1.0.0-rc.6

Pre-release
Pre-release

Choose a tag to compare

@AndriiSherman AndriiSherman released this 20 Nov 19:31
f163324

v1.0.0-rc.6

drizzle-orm

Breaking changes

  • Drivers no longer configure output decoding in drivers' configurations - following configurations set by drizzle constructors were removed:

    • client.options.bigint = true from bun-sql/postgres, bun-sql/mysql
    • transparent decoders from postgres-js
    • global types.setTypeParser(...) from neon-http, netlify-db
    • per-query parser overrides from raw mode and other queries not decoded by codecs (node-postgres, node-postgres/dsql, vercel-postgres, neon-serverless, netlify-db, cockroach, pglite, mysql2)

    ❗postgres-js still overrides client's param serializers (client-wide, replacing user-configured ones) for timestamptz (1184), timestamp (1114), date (1082), time (1083) and their arrays:

    • Date values are sent as value.toISOString() - same as postgres.js' default for timestamptz, timestamp, date
    • strings are sent as is to be parsed by the server - postgres.js' default re-encodes them via new Date(value).toISOString(), which reads offset-less timestamps in process' local time, truncates microseconds and throws on values JS can't parse ('infinity', '12:00:00')
    • time switches Date processing from date.toString() to ISO string

    sqlite: integer-based codecs (integer, integer:boolean, integer:timestamp, integer:timestamp_ms) accept number, bigint and integer text, which makes them independent of safe integer modes (better-sqlite3's defaultSafeIntegers, bun:sqlite's safeIntegers, node:sqlite's readBigInts, libsql's intMode)

    ❗ Results of raw queries (db.execute(sql...)) now honor driver's configuration

    ⚠️ Codecs only cover client options with predictable output (bigint, safeIntegers, intMode, decimalNumbers, jsonStrings, ...). Custom parsing functions (pg's types.setTypeParser(...) / types.getTypeParser, postgres' types, mysql2's typeCast) that change output of types drizzle doesn't request per query still require custom codecs, e.g.:

    import { refineCodecs } from 'drizzle-orm/codecs';
    import { drizzle, mysql2Codecs } from 'drizzle-orm/mysql2';
    import { createPool } from 'mysql2/promise';
    
    const client = createPool({
      uri: process.env.DATABASE_URL,
      typeCast: (field, next) => {
        // `tinyint(1)` is returned as `boolean` instead of `number`
        if (field.type === 'TINY' && field.length === 1) return field.string() === '1';
        // `BLOB`-typed fields (`text`, `blob` columns) are returned as `Buffer` instead of `string`
        if (field.type === 'BLOB') return field.buffer();
        return next();
      },
    });
    
    const fromBuffer = (value: Buffer) => value.toString('utf8');
    
    const db = drizzle({
      client,
      codecs: refineCodecs(mysql2Codecs, {
        // default `boolean` codec expects `0` / `1` - client's output is already final
        boolean: { normalize: undefined },
        // text codecs have no decoders by default - client's output is expected to be a string
        text: { normalize: fromBuffer },
        mediumtext: { normalize: fromBuffer },
      }),
    });
    import { refineCodecs } from 'drizzle-orm/codecs';
    import { arrayCompatNormalize, arrayCompatNormalizeInput } from 'drizzle-orm/pg-core';
    import { drizzle, postgresJsCodecs } from 'drizzle-orm/postgres-js';
    import postgres from 'postgres';
    
    type Line = [a: number, b: number, c: number];
    
    const client = postgres(process.env.DATABASE_URL, {
      types: {
        // `point` (and `point[]`) is returned as `{ x, y }` instead of `(x,y)` text
        point: {
          to: 600,
          from: [600],
          // drizzle already encodes points to `(x,y)` text
          serialize: (value: string) => value,
          parse: (value: string) => {
            const [x, y] = value.slice(1, -1).split(',').map(Number);
            return { x, y };
          },
        },
        // `line` (and `line[]`) is returned as `[a, b, c]` instead of `{a,b,c}` text, params are expected as `[a, b, c]`
        line: {
          to: 628,
          from: [628],
          serialize: ([a, b, c]: Line) => `{${a},${b},${c}}`,
          parse: (value: string) => value.slice(1, -1).split(',').map(Number) as Line,
        },
      },
    });
    
    const toABC = ([a, b, c]: Line) => ({ a, b, c });
    const toLine = (value: string) => value.slice(1, -1).split(',').map(Number) as Line;
    
    const db = drizzle({
      client,
      codecs: refineCodecs(postgresJsCodecs(client), {
        // default `point` codecs parse `(x,y)` text - client's output is already final
        point: { normalize: undefined, normalizeArray: undefined },
        // `line({ mode: 'abc' })` columns
        line: {
          normalize: toABC,
          normalizeArray: arrayCompatNormalize(toABC),
          // drizzle encodes `{ a, b, c }` to `{a,b,c}` text
          normalizeParam: toLine,
          // `postgres.js` 4 serializes array params element by element, with the type's `serialize` - elements are typed,
          // or it would read the tuples as nested arrays
          normalizeParamArray: arrayCompatNormalizeInput((value: string) => client.typed(toLine(value) as any, 628)),
        },
      }),
    });
  • Removed cast codecs: selected columns are no longer wrapped in casts (::text, cast(... as char), epoch milliseconds, ...) and set operations in select ... from (...) "drizzle_union" (except singlestore); toSQL() / getSQL() of query builders lost their withCastCodecs switch. This fixes select distinct ... order by <column> being invalid on pg, cockroach, mysql, mssql (fixes #6673). Changes that came with it:

    • Returned data:
      • Queries decoded by codecs (with a mapper - not db.execute, db.call) request lossless output per query; the overrides are exported for proxy servers, which apply them in their own callback implementations (nodePgRawTextTypes, nodePgDsqlRawTextTypes, neonServerlessRawTextTypes, neonHttpRawTextTypes, vercelPgRawTextTypes, netlifyDbRawTextTypes, nodeCockroachRawTextTypes, pgliteRawTextParsers, decodePostgresJsRawRows, makeMySql2RawTextTypeCast, makeSingleStoreRawTextTypeCast, makePlanetscaleRawTextCast, tidbRawTextDecoders, awsDataApiRawTextResultSetOptions):
        • node-postgres, node-postgres/dsql, neon-serverless, neon-http, vercel-postgres, netlify-db, cockroach: per-query types returning date, timestamp, timestamptz, interval, numeric[] and their arrays as text (fixes #6290); pglite: per-query parsers for the same types; postgres-js: raw mode, decoding the same types as text and others with the client's own parsers
        • mysql2, singlestore: per-query typeCast (bigint, decimal, date, datetime, timestamp as text, json parsed, other fields through the client's own typeCast); planetscale-serverless: per-query cast; tidb-serverless: per-query decoders; aws-data-api/pg: longReturnType: 'STRING'
        • better-sqlite3, node-sqlite, bun-sqlite, tursodatabase, tursodatabase-sync, tursodatabase-serverless, effect-sqlite-node, effect-sqlite-bun: integers as bigints per statement, so numeric keeps integers past the safe range. ❗ Integer sql fields without .mapWith() are bigints on these drivers
      • Other drivers' output is decoded as returned. Column types the driver returns with data already lost throw Column type "<type>" is not supported with the <driver> driver: <reason> (each driver's drizzle() docs list them, with quirks):
        • pg, cockroach drivers decoding text: temporal values in sessions with non-ISO DateStyle
        • bun-sql/postgres, effect-postgres, effect-pglite, aws-data-api/pg, postgres/aurora: timestamptz in string mode (offset of the session's time zone dropped)
        • effect-pglite: timestamp (process-local time)
        • effect-postgres: macaddr, macaddr8, enum[], geometry, vector, halfvec, sparsevec (binary format decoded as corrupted text); point, line, bit, interval[], multidimensional arrays fail in the driver
        • aws-data-api/pg, postgres/aurora: timetz (offset dropped), bytea[] (returned empty)
        • node-mssql: decimal, numeric in string mode, values past the safe range in bigint mode
        • d1, sql-js, expo-sqlite, op-sqlite, durable-sqlite, sqlite-cloud, effect-d1, effect-sqlite-do: numeric integers past the safe range (libsql, effect-libsql with intMode: 'number' fail in the driver)
      • Driver quirks, decoded as returned: float rounded to 6 significant digits (mysql2, singlestore, planetscale-serverless; bun-sql/mysql in queries without bound parameters); time cut to milliseconds, BC dropped from fractional timestamps, null array elements dropped (aws-data-api/pg, postgres/aurora); BC dates read as Invalid Dates, years 1 - 99 of timestamptz read as 19xx (effect-pglite); microseconds of string-mode timestamp, datetime (bun-sql/postgres, bun-sql/mysql, effect-postgres)
      • Set operation fields are decoded by the left-hand side's codec (pg, cockroach, mssql, singlestore) or the codec of the combined type (mysql, sqlite); sqlite blob ∪ numeric bigint fields are decoded per row by the storage class they came in
      • bun-sql/postgres: infinity, -infinity dates and timestamps (Infinity numbers from bun) are decoded to Invalid Dates, 'infinity' / '-infinity' in string mode
    • Drizzle instance creation:
      • effect-mysql2: make rejects clients created without dateStrings: true (poolConfig, or ?dateStrings=true in url) or with decimalNumbers: true
      • bun-sql/sqlite: drizzle() rejects SQL clients created without safeIntegers: true (or bigint: true), clients it creates from connection strings set it
    • Corrections of earlier release notes:
      • rc.4 "Fixed mysql float rounding": holds for effect-mysql2 only, other drivers round per the quirk above
      • rc.4 "Fixed mysql cropping .000 from timestamp(3)": holds except for effect-mysql2, bun-sql/mysql, which drop trailing zeros of fractional seconds
      • rc.4 set operator drizzle_union wrapping and combined-type codecs: see set operations above
      • rc.5 bun-sql/mysql, mysql2, singlestore "cast codecs": replaced by per-query typeCast (mysql2, singlestore) and decoding as returned (bun-sql/mysql)
      • rc.5 withCastCodecs switch, "Fixed cast codecs being applied to selection fields of inner queries", "Fixed sqlite generating View, Subquery queries with cast on numeric columns": no longer apply
      • rc.5 "Fixed mysql date column being affected by server's timezone" (#1442): effect-mysql2 requires dateStrings: true for it
      • rc.5 "Fixed effect-mysql, bun-sql/mysql drivers losing time fraction": effect-mysql2 drops trailing zeros of the fraction
      • rc.5 aws-data-api/pg time({ withTimezone: true }) results converted to UTC: such columns throw now (see above)
  • postgres-js: supported postgres 4 (json[], jsonb[] params are sent as typed elements on 4, as array literals on 3); bumped the tested version to 4.1.1 - postgres before 4.0.0 decodes null array elements as NaN, 'NULL', false or throws (json, jsonb)

  • Changed postgresJsCodecs (drizzle-orm/postgres-js, drizzle-orm/postgres-js/dsql), bunSqlPgCodecs (drizzle-orm/bun-sql/postgres) from plain objects to (client) => codecs functions due to json param wrapper functions only being accessible from drivers via client.json(param)

  • Fixed bun-sql/mysql datetime in string returning trailing zeroes for empty second fractions

  • Bumped minimal supported version of @types/mssql peer dependency from 9.1.4 to 9.1.11 to match declarations of mssql@11.0.1; changed mssql, @types/mssql peer dependency version requirements from ^ to>=

  • Changed shapes of dialect-specific concat, substring expressions (drizzle-orm/<dialect>-core/expressions) to match their dialects' functions:

    • mysql, singlestore, mssql: concat(a, b, ...rest) now accepts any number of values (string, number, bigint, Placeholder, SQLWrapper) and emits concat(...) instead of ||, which is a logical OR in mysql, singlestore and is unsupported by mssql before SQL Server 2025
    • mysql, singlestore: substring(column, { from, for? }) - from is now required (substring(x for n) is a syntax error); from, for accept bigint
    • pg, cockroach: substring(column, { from?, for? }) now requires at least one of from, for (substring(x) is an error); from is cast to integer (pg) / int8 (cockroach) due to substring(text from pattern) overload being picked by default; cockroach positions accept bigint
    • pg, cockroach: added regular expression substring overloads:
      • substring(column, { fromPattern }) - POSIX regular expression (substring(x from pattern))
      • pg: substring(column, { similar, escape }) - SQL regular expression (substring(x similar pattern escape escape))
      • cockroach: substring(column, { fromPattern, escape }) - POSIX regular expression with escape in place of \ (substring(input, regex, escape_char))
    • sqlite: substring(column, { from?, for? }) -> substring(column, start, length?), emits substr(x, start[, length]) instead of unsupported substring(x from ... for ...); start, length accept bigint
    • mssql: substring(column, { from?, for? }) -> substring(column, start, length), emits substring(x, start, length) instead of unsupported substring(x from ... for ...)
    • concat values and substring arguments are no longer encoded with the column's encoder - they are not expected to share the column's type
  • Fixed subqueries selected as fields being inferred as non-nullable - a subquery can return no rows, so their values are now typed as | null. This also applies to such fields re-selected from views and subqueries built from these selections:

    const res = await db.select({
      id: users.id,
      // before: number, now: number | null
      lastPostId: db.select({ id: posts.id }).from(posts).where(eq(posts.authorId, users.id)).orderBy(desc(posts.id)).limit(1).as('last_post_id'),
    }).from(users);
  • Removed query caching: drizzle-orm/cache/core and drizzle-orm/cache/upstash modules, cache option of drizzle constructors, db.$cache, .$withCache() of select queries, withCache option of relational queries, EffectCache service of Effect drivers (DefaultServices now provides only EffectLogger)

  • mysql, singlestore: $returningId can no longer be combined with onDuplicateKeyUpdate as the result can't report updated rows' ids

  • pg, cockroach, mysql, singlestore, sqlite no longer silently drop non-positive pagination params

  • pg: removed .concurrently() from indexes - migrations run inside a transaction, where create index concurrently can't be executed

  • Fixed Effect drivers waiting for query logger to finish execution to execute query: logging is now detached with Effect.forkDetach

  • Removed migrations table upgrade helpers, replaced by migrators shared across runtimes and drivers:

    • drizzle-orm/up-migrations/mysql, drizzle-orm/up-migrations/mysql-proxy, drizzle-orm/up-migrations/singlestore, drizzle-orm/up-migrations/singlestore-proxy, drizzle-orm/up-migrations/pg-proxy, drizzle-orm/up-migrations/effect-mysql, drizzle-orm/up-migrations/effect-pg, drizzle-orm/up-migrations/effect-sqlite modules (upgradeIfNeeded), drizzle-orm/up-migrations/sqlite-proxy module (upgradeAsyncIfNeeded)
    • upgradeIfNeeded from drizzle-orm/up-migrations/pg, upgradeSyncIfNeeded and upgradeAsyncIfNeeded from drizzle-orm/up-migrations/sqlite
    • drizzle-orm is published as ESM only: CommonJS output (.cjs, .d.cts) and require export conditions were removed. Added engines.node: ^20.19.0 || >=22.12.0 - Node versions that can require() ES modules, so CommonJS projects on them keep working through require(esm)
  • drizzle-orm/postgres: the Drizzle Postgres driver (formerly @drizzle-team/minipg) now ships inside drizzle-orm:

    • removed the @drizzle-team/minipg peer dependency - the driver's API is re-exported from drizzle-orm/postgres entries, it's own entries are available as drizzle-orm/postgres/client/*
    • renamed minipgCodecs, minipgShapeCodecs -> postgresCodecs; minipgAuroraCodecs, minipgAuroraShapeCodecs -> postgresAuroraCodecs
    • moved the Neon HTTP driver from drizzle-orm/postgres/http/neon to drizzle-orm/postgres/neon-http

New features

  • drizzle-orm/postgres (postgres, postgres/http, postgres/neon-http):

    • added db.pipeline([...]) - runs queries back-to-back on one pooled connection without a transaction, db.parallel([...]) - runs them concurrently across pooled connections (postgres/neon-http: parallel only); both resolve with one PromiseSettledResult per query instead of throwing
    • db.batch([...], options) takes transaction options (isolation, readOnly, deferrable, snapshot) and metrics: true | 'ms' | 'us' to return the driver's telemetry as response.metrics; postgres sends the whole batch in one round trip
    • postgres: added db.bulkInsert(table, rows, options?) (multi-row values statements) and db.bulkUpdate(table, rows, { by }) (driver-side unnest, matched by key column(s)) - both fill $defaultFn / $onUpdateFn, split rows into chunks pipelined in one transaction, atomic: false commits per chunk
  • Added drizzle-orm/postgres/pglite - Drizzle Postgres over an in-process PGlite instance (named statements, pipelining, batch, pipeline, bulk methods):

    import { drizzle } from 'drizzle-orm/postgres/pglite';
    
    const db = drizzle(); // in memory
    const db = drizzle('./data'); // in a data directory
    const db = drizzle({ connection: await PGlite.create() }); // on your own instance, left open when the pool closes
  • Added Effect drivers for Drizzle Postgres: drizzle-orm/postgres/effect, drizzle-orm/postgres/effect/http, drizzle-orm/postgres/effect/neon-http, drizzle-orm/postgres/effect/aurora (make, makeWithDefaults), with the same batch, pipeline, parallel, bulkInsert, bulkUpdate methods as their async counterparts, as Effects (pipeline and parallel give a Result per query). The Effect SqlClient layers they run on are re-exported from the same entries (DrizzlePostgresClient; Neon WebSocket and PGlite variants in drizzle-orm/postgres/client/effect/neon-ws, drizzle-orm/postgres/client/effect/pglite). Require effect 4.1.3 or later

    import * as PostgresDrizzle from 'drizzle-orm/postgres/effect';
    import { DrizzlePostgresClient } from 'drizzle-orm/postgres/effect';
    
    const program = Effect.gen(function*() {
      const db = yield* PostgresDrizzle.makeWithDefaults({ relations });
      return yield* db.select().from(users);
    }).pipe(Effect.provide(DrizzlePostgresClient.layer({ url: Redacted.make(process.env.DATABASE_URL!) })));
  • Added drizzle-orm/postgres/cdc - change data capture over logical replication (replicate(options), pool.replicate(options))

  • drizzle-orm/postgres: the driver detects transaction-mode poolers of more vendors from host and port (Supabase transaction mode, PgBouncer on port 6432, PlanetScale Postgres, Prisma Postgres, Neon / Vercel pooled hosts, Vercel serverless runtime) and adjusts named statements and pipelining to them; undetectable poolers are declared with pooler: true or ?pooler=true / ?pgbouncer=true. Pipelining depth defaults to 'auto' - picked from the connection's measured round trip

  • sqlite: added rowId.big() for row ids past Number.MAX_SAFE_INTEGER; rowId() is mapped with Number, so it stays a number on drivers that now read integer sql fields as bigints (see cast codecs removal)

Other changes

  • Fixed effect-postgres failing to encode empty array params (Cannot infer the type of an empty array) of text, varchar, char, bool, smallint, int, bigint, serial types, float4, float8, bytea columns (fixes #6566)

  • Fixed effect-postgres bigint, bigserial columns in bigint mode returning strings when PgClient decodes int8 as text (fixes #6566)

  • Fixed db.$client of effect drivers being typed as the client's interface instead of it's service's shape on effect >=4.1.3 (fixes #6685)

  • Fixed bun-sql postgres bigint, bigserial columns in bigint mode returning strings since bun started ignoring options.bigint set after client's construction

  • Fixed bun-sql postgres empty multidimensional integer arrays being returned as Int32Array

  • Fixed is() narrowing columns to never:

    • pg: text, varchar, char with enum (is(column, PgText)), plain varchar, char
    • cockroach: cockroachEnum columns (is(column, CockroachEnumColumn))
    • mysql: blob, tinyblob, mediumblob, longblob in buffer mode (is(column, MySqlBufferBlob))
  • Fixed mysql, singlestore enum columns narrowed by is() having column.enumValues typed as | undefined

  • Fixed cockroach cockroachEnum columns being typed with string dataType instead of string enum, which made validators infer string instead of the enum's values

  • Fixed mysql blob, tinyblob, mediumblob, longblob in buffer mode having string dataType instead of object buffer, which made validators generate string schemas for Buffer values

  • Fixed validators inferring string instead of enum members for columns of enums made from TS enums (pgEnum, cockroachEnum, mysqlEnum)

  • Fixed drizzle-orm/zod createSchemaFactory without coerce option breaking refine callbacks' parameter type inference (Parameter 'schema' implicitly has an 'any' type) (fixes #5968)

  • Fixed postgres-js errors on json, jsonb columns' params with boolean, Date, Buffer, Uint8Array values and arrays starting with them (column "..." is of type jsonb but expression is of type ...) (fixes #6582)

  • Fixed bun-sql/postgres errors on json, jsonb columns' params with top-level number, boolean, Buffer, Uint8Array values (fixes #6591)

  • Fixed bun-sql/postgres with prepare: false errors on json, jsonb columns' params (fixes #6132)

  • Fixed node-postgres, neon-serverless, vercel-postgres, netlify-db errors on json, jsonb columns' params with Date, Buffer, Uint8Array values (invalid input syntax for type json)

  • Fixed type errors in emitted declarations with skipLibCheck: false (fixes #5187):

    • Cannot find module 'mysql2' in projects without mysql2 installed - general modules (drizzle-orm, drizzle-orm/pg-core, ...) no longer reference driver packages' types
    • Class 'PgRole' incorrectly implements interface 'PgRoleConfig' (same for PgPolicy, CockroachRole, CockroachPolicy) with exactOptionalPropertyTypes
    • Type 'Buffer' is not generic on TypeScript 5.6 and older in mysql-core blob codecs and drizzle-orm/arktype's bufferSchema
  • Fixed query buidlers dropping offset with 0 value (fixes #6599)

  • Fixed node-postgres, cockroach, neon-serverless, netlify-db, vercel-postgres transactions returning client to the pool after failed begin (fixes #6622)

  • Fixed durable-sqlite .get() and .run() leaving statements unfinished on multi-row results; .run() result is now typed as finished cursor's columnNames, rowsRead, rowsWritten (fixes #6550)

  • Fixed effect-sqlite-do, effect-sqlite-bun, effect-sqlite-wasm .run() result type: [] -> readonly Record<string, unknown>[]

  • Fixed sqlite-core onConflictDoNothing({ target, where }) placing where after do nothing (fixes #6531)

  • Fixed pg, cockroach timestamp, date columns failing to encode Date values outside of year 1 - 9999 range (fixes #6552):

    • years past 9999 (+010000-01-01T00:00:00.000Z) are sent without the expanded-year sign: 10000-01-01T00:00:00.000Z
    • years before 1 AD (0000-01-01T00:00:00.000Z, -000001-...) are sent with the BC suffix: 0001-01-01T00:00:00.000Z BC
  • Fixed pg, cockroach timestamp, date columns in date mode decoding values that new Date(text) misreads:

    • years 1 - 99 were read as two-digit years (0099-12-31 23:59:59+00 -> 1999)
    • date values past year 9999 were read in process' local time
    • values with the BC suffix and with seconds-precision UTC offsets were decoded as Invalid Date
  • Fixed pg timestamp, date columns in date mode being decoded as wrong dates or Invalid Date in sessions with non-ISO DateStyle (fixes #6496): drivers decoding text now throw on such values instead (see cast codecs removal)

  • Documented aws-data-api/pg, postgres/aurora time columns losing fractional seconds past milliseconds and timestamp columns losing the BC suffix of values with fractional seconds as driver quirks: columns are no longer cast in selections, Data API formats them itself with no per-query alternative

  • Fixed not returning SQL | undefined for SQLWrapper input (fixes #6625)

  • Fixed pg transaction config allowing snapshot without isolationLevel: 'repeatable read' | 'serializable'

    // before: compiled, failed at runtime; now: type error
    await db.transaction(async (tx) => { /* ... */ }, { snapshot });
    // ok
    await db.transaction(async (tx) => { /* ... */ }, { isolationLevel: 'repeatable read', snapshot });
  • Fixed null elements of pg, cockroach array columns being passed into decoders\encoders instead of being kept as null (fixes #6460):

  • Fixed json, jsonb pg, cockroach array elements being written as JSON null instead of SQL null

  • Fixed: [BUG]: durable-sqlite migrate hides the error of a failed migration behind TransactionRollbackError

  • Fixed $dynamic() builders being rejected by helpers constrained by generic builder types when .returning(), .from() or joins were applied before $dynamic()

    const withFilter = <T extends PgDelete>(qb: T) => qb.where(eq(users.id, 1));
    // before: type error; now: { id: number }[]
    await withFilter(db.delete(users).returning({ id: users.id }).$dynamic());
  • Fixed cockroach insert().$dynamic(), update().$dynamic() builders losing .returning() result type and joins' nullability for update

  • Fixed pg db.$count() not being accepted as an item of batch, pipeline, parallel

drizzle-kit

Breaking changes

  • postgres snapshot format bumped to 10 following removal of .concurrently() from pg indexes: concurrently is dropped from format 9 index entries and index create / alter deltas on upgrade
  • drizzle-kit is published as ESM only: the drizzle-kit binary, drizzle-kit/api-*, drizzle-kit/cli and drizzle-kit/payload/* entries lost their CommonJS builds and require export conditions. Added engines.node: ^20.19.0 || >=22.12.0 - Node versions that can require() ES modules

Improvements:

  • Faster pull / push introspection on large schemas (PostgreSQL, CockroachDB, MySQL, SQLite, MSSQL) and faster PostgreSQL schema diffing
  • pull errors now carry their underlying cause for every dialect: printed after the message in text output, returned as error.cause in JSON output
  • MSSQL pull returns indexes sharing one name across tables in a stable order

Fixed

drizzle-pulse

drizzle-pulse is a type-safe realtime SDK for Drizzle ORM: it streams row changes from PostgreSQL's write-ahead log
(wal_level = logical) to consumers subscribed to queries you define on the server. Its version now follows the other
Drizzle packages.

import { drizzle } from 'drizzle-orm/postgres';
import { pulse } from 'drizzle-pulse';
import { createRuntime } from 'drizzle-pulse/embedded';
import { z } from 'zod';
import { orders } from './schema.ts';

// Queries are defined once, on the server; `.args()` takes any Standard Schema
const ordersByStatus = pulse(orders)
  .args(z.object({ status: z.enum(['requested', 'accepted', 'completed', 'cancelled']) }))
  .query((ctx) => ctx.query({ status: ctx.args.status }));

const runtime = createRuntime({
  queries: { ordersByStatus },
  databaseUrl: process.env.DATABASE_URL!,
  // the app's own connection: baseline reads keep it's session context (RLS, `search_path`)
  sourceDb: drizzle(process.env.DATABASE_URL!),
});

// provisions the publication, replication slot and events tables, then starts reading the WAL
await runtime.start();

// Live collection: current result, kept up to date
const accepted = await runtime.client.ordersByStatus({ status: 'accepted' });
console.log(accepted.list());
accepted.onChange(({ events, state }) => console.log(events, state));

// CDC event stream: `insert` / `update` / `delete` relative to the query's result
const unsubscribe = runtime.events.ordersByStatus({ status: 'accepted' }, (event, lsn) => console.log(event.op, lsn));

Breaking changes:

  • Peer dependencies: drizzle-orm raised to ^1.0.0-rc.6; removed @drizzle-team/minipg - Pulse uses the Drizzle Postgres driver that drizzle-orm bundles (drizzle-orm/postgres, drizzle-orm/postgres/cdc); removed zod - query arguments take any Standard Schema
  • CDC event stream and live collection events are relative to the query result: insert has row, update has the full row and oldRow, delete has oldRow. matchesNew and old_row were removed from the embedded event types, PulseDeleteEvent takes the row type parameter
  • .args() takes any Standard Schema instead of only a zod schema; it's validation must be synchronous. Invalid args throw an error listing the issue messages
  • PulseBuilder type parameters are now TTable, TSelection, TArgsInput, TArgsOutput, TResult, TFlags: callers pass the input type of the args schema, ctx.args is it's output type. PulseBuilder.config and it's constructor are internal
  • pulse(t).query(fn) types ctx.args as Record<never, never>; .args() throws after a where-function
  • Queries built with .transform() or .limit() are missing from runtime.client and runtime.events at compile time
  • Opening a CDC event stream with a where on a column excluded by .columns() throws, as opening a live collection does
  • Opening a live collection or a CDC event stream takes no auth option; removed PulseCollectionOptions
  • TelemetryEvent: committedAt, appliedAt renamed to committedAtMicros, appliedAtMicros (epoch microseconds)
  • QueryDescriptor moved from drizzle-pulse to drizzle-pulse/client; PulseAuthContext is exported from drizzle-pulse only
  • PulseCollection has a private constructor
  • EmbeddedRuntimeConfig is a type alias, as it takes either databaseUrl or client
  • start() only adds tables to the publication: dropping unregistered tables from it and resetting their replica identity is done by provisioning only
  • Removed the drizzle-pulse/package.json export

New features:

  • drizzle-pulse/embedded: added standalone provision({ queries, databaseUrl, wal }) - does the same as runtime.provision() without a runtime or sourceDb, for deploy steps
  • createRuntime() and provision() take an optional client - a Drizzle Postgres Pool (drizzle-orm/postgres) - in place of databaseUrl. Pulse runs it's admin queries on the pool and replication through client.replicate(), and doesn't close the pool. Without client, the driver bundled with drizzle-orm is only imported when the runtime starts or provisions
  • Added onResync, onError options for CDC event streams
  • drizzle-pulse exports PulseAuthContext, PulseQueryContext, WhereClause types

Other changes:

  • ColumnOperators.in accepts readonly arrays
  • Errors and JSDoc use the terms live collection and CDC event stream, and document microsecond units, the slot name prefix and the publication rules