Drizzle ORM

Breaking changes

• Fixed postgres-js transparent parsers set by drizzle() constructors breaking driver’s own serializers for timestamptz, timestamp, date, time, json, jsonb types (fixes #3171, #4426, #5789) Note: Any existing workarounds with manual JSON.stringify(jsonValue) in raw sql or raw driver calls must be removed to prevent double stringification of JSON params; For array-type JSON params in sql use sql.param(jsonArrayValue) to avoid it being parsed as value list instead of param.
• Restricted undefined value passed to fields in relational queries’ where - now throws an error upon encountering undefined in filters, added EmptyFilter symbol (import { EmptyFilter } from 'drizzle-orm/relations') that can be used as an explicit replacement of undefined where possibly absent filter is desired by design rather than possible bug (fixes #5636) Example:

    db.query.users.findMany({ where: { isActive: params.isActive ?? EmptyFilter } })

• Relation filters without conditions ({}, or containing only empty conditions) are now skipped like any other empty filter instead of generating exists (...) check of relation’s presence - use true to filter by relation’s presence, false - by its absence Example:

    // Previously: `where exists (select * from "posts" ...)`, now: no filter
    db.query.users.findMany({ where: { posts: {} } })
    // Users with at least one post
    db.query.users.findMany({ where: { posts: true } })

• Updated postgres codecs: now generic codecs contain only in-json codecs (mirroring mysql), contents of drivers’ codecs remain unchanged
• Switched pg bytea in-json codecs from encode(..., 'base64') casts to decoding to_json’s native hex output
• Made nested select join nullification consider SQL field data during nullification
• Fixed sqlite ignoring .$defaultFn(...) on insert when .default(...) is present
• Untied bun-sql/mysql, mysql2, singlestore column mapping from connection config, removed forced bigint params on their respective configs, replaced with more stable cast codecs
• Reworked cockroach column builders to mirror pg - now both have same .array('[][]...') syntax
• Moved View exports from drizzle-orm/sql/sql to drizzle-orm/view
• getTableUniqueName no longer prefixes aliased views or tables with their schema
• getTableUniqueName no longer sets public. prefix for entities without schema
• Updated View class: switched to Table-like object config for type template, typed schema property
• Updated withReplicas (indirectly fixes #4185):
  • Now every query goes to primary db by default
  • To query replica, explicitly call db.$replica
• Added withCastCodecs = false switch to getSQL(), withCastCodecs = true switch to toSQL() of non-relational query builders - now db.select(...).from(...).getSQL() emits query without cast codecs by default
• Reworked sqlite-proxy:
  • Added rowMode: 'array' | 'object' switch for 'all' | 'get' execute methods
  • Dropped { rows: Result[] } callback result wrapping - now expected direct return of expected data
  • Replaced callback, batchCallback with SqliteProxyExecutors object - must provide run, all, get handlers & optional batch handler
  • Dropped values execute method due to it being duplicate of array-mode all
  • Added TRunResult type inference based on return type of run executor, updated SqliteRemoteDatabase template with TRunResult argument
  • Added per-item rowMode: 'array' | 'object' to batch, batch is expected to mirror executors’ return types per query
• Fixed the sqlite-proxy result type for get (data | undefined at runtime, previously data[] in types) (fixes #5461, #3394)
• Fixed sqlite db.get(sql) return type lacking | undefined for queries without returned rows
• Omitted query params from DrizzleQueryError by default, added paramsInErrors option to drizzle constructor to enable query params in DrizzleQueryError (fixes #5939) Example:

  const db = drizzle({
    connection: 'postgres://...',
    paramsInErrors: true
  })

• For mysql, postgres, cockroach, mssql set RQBv2 to new query build strategy to fix slow query plans (fixes #5245) Can be opted out of per query via strategy switch: db.query.users.findMany({ strategy: 'basic' }) When used, may break direct references to relations in raw SQL syntax where, orderBy:

  // posts with the most comments first
  db.query.posts.findMany({
    with: { author: true, comments: true },
    orderBy: (t, { sql }) => sql`json_array_length("comments"."r") desc, ${t.id}`, // "comments" becomes unreachable due to query nesting
    limit: 2,
  });
  
  // posts of verified authors
  db.query.posts.findMany({
    with: { author: true },
    where: { RAW: (t, { sql }) => sql`("author"."r"->>'verified')::boolean` }, // "author" becomes unreachable due to query nesting
  });

• Moved StringChunk, commonStringChunks exports from drizzle-orm/sql/sql to drizzle-orm/sql/common-chunks (still exported from drizzle-orm/sql)
• Switched RQBv2 build functions to chunk collection: each accepts optional trailing collectTo: SQLChunk[] array to push chunks to and returns chunk arrays instead of SQL Note: Chunk arrays embedded into sql directly are rendered as value lists - wrap them in new SQL(chunks) to use them as query parts
  • relationsFilterToSQL(...).sql: SQL | undefined -> SQLChunk[] | undefined, added collectTo parameter
  • relationsOrderToSQL(...): SQL | undefined -> SQLChunk[] | undefined, added collectTo parameter
  • relationsOrderEntriesToSQL(...): replaced parts: SQL[] parameter with collectTo: SQLChunk[], start?: number; RelationsOrderSource’s from, filters are now SQLChunk[], SQLChunk[][]
  • relationExtrasToSQL(...).sql: SQL | undefined -> SQLChunk[] | undefined, added collectTo parameter
  • relationToSQL(...): { filter?: SQL; joinCondition?: SQL } -> { filter: SQLChunk[]; joinCondition?: SQLChunk[] }, added filterTo, joinConditionTo parameters
  • getTableAsAliasSQL(...): SQL -> SQLChunk[], added collectTo parameter
• Relational queries are now cached by caches with all strategy (global: true), opt out per query via withCache: false
• Replaced DBQueryConfigWithComment type with DBQueryConfigRoot - config of root relational query containing all root-only options (strategy, comment, withCache); dialects’ relational query builders accept it with options they don’t support omitted

Improvements and fixes

• Updated RQB filters to allow branded types in shortcut-form eq filter (fixes #5298)
• Fixed $onUpdateFn being executed without need (fixes #5780)
• Fixed $onUpdateFn potentially overriding explicit nulls
• Fixed zod schema generator returning unknown-templated coerced types (fixes #5659)
• Fixed mysql2 constructor setting param in potentially undefined mistyped config (fixes #5972)
• Fixed non-jit mapper nullification triggering on single null column (fixes #1603)
• Preserved qualifiers for column chunks of sql fields in selection when non-current table’s column is referenced (fixes #5734)
• Optimized query building, mapper generation
• Allowed empty returns in callback-style orderBy, extras, RAW of relational queries
• Removed unused _ field in RelationsHelperStatic
• Fixed naming: isReversed to isFilterReversed in Relation
• objects, arrays db.execute modes (db.all, db.get in sqlite) (bypasses #4464)
• Fixed jit mapper nullifying nested selection objects with columns from different tables
• Fixed selection group nullification not triggering on objects with deeply nested fields (joined view or subquery)
• Fixed geometry, geography & box array types data getting reduced to one item due to wrong delimiter used during pgArray construction\parsing
• Added delimiter customization to makePgArray, parsePgArray utilities
• Optional explicit column lists for db.insert (workaround for #5001, #5309)
  • Usage: db.insert(users, 'name', 'email').values([{ name: 'First', email: 'first@example.com' }, { name: 'Second', email: 'second@example.com' }])
• Transaction snapshot support for pg dialect
• Fixed pg transaction config related errors on empty but present config (fixes #1772)
• Supported transaction config in effect pg drivers
• Bump tursodatabase library versions
• Supported transaction configs for tursodatabase drivers
• Fixed mysql transaction options being joined on wrong separator
• Supported isolationLevel in bun-sql/mysql transactions
• Removed transaction config from effect-sqlite, effect-mysql due to lack of support in drivers
• Explicit error throws on unsupported transaction configs
• Partial transaction config support for libsql, tidb drivers
• Improved error messages on unknown fields in RQBv2 selection (fixes #5367)
• Fixed op-sqlite transaction being handled as synchronous
• Fixed broken op-sqlite query executors (fixes #5936)
• Bumped op-sqlite to v17 (fixes #5928)
• Fixed expo-sqlite not finalizing prepared statements
• Added expo-sqlite/async for async querying (fixes #5240)
• Added local sha256 hash function as a fallback for cache query hashing in environments without globalThis.crypto available
• Fixed dynamic query builders blocking query builder’s variable reassignment after applying nullable joins by defaulting to not-null behavior on not yet joined column groups in selection (fixes #4232)
• Fixed bytea not being included in pg table creation callback format column list
• Moved SQL.usedTables calculation from constructor to getter
• Fixed false relation name collision error and relational filter misrouting for relation names shadowing Object.prototype properties like constructor (fixes #6076)
• Updated neon-http migrator to automatically rollback failed migrations
• Bump effect to 4.0.0 (fixes #6162, #6403, #6412)
• Improved hash for query name generation & query cache key
• Bump typebox to 1.2.0 (fixes #5981)
• Fixed internal type errors in built code
• Updated mssql, cockroach, singlestore sessions to new format
• Added missing lateral (apply), cross joins, insert ... select, db.$count to mssql
• Added explicit error on attempt to insert multiple default-only rows in mssql
• Fixed blob columns on React Native drivers: writes no longer require Buffer, op-sqlite and expo-sqlite reads normalized to Uint8Array. Use blob(...).$type<Uint8Array>() to override column’s type
• Fixed cast codecs being applied to selection fields of inner queries in pg, mysql
• Fixed double space following order by in set operation queries
• Fixed MSSQL, MySQL, SingleStore serial types returning different types based on column’s value
• Fixed sqlite generating View,Subquery queries with cast on numeric columns
• Codec system for sqlite, cockroach, mssql, singlestore
• Migrated mssql, cockroach to RQBv2
• Removed redundant limit 1 from relational where, coalesce for json arrays in sqlite in RQBv2
• Removed RQBv1 schema from DrizzleConfig
• Fixed mysql2 not using codecs from config over driver’s default when provided
• Added delimiter customization to makeCockroachArray, parseCockroachArray utilities, mirroring their pg counterparts
• Fixed cockroach geometry arrays being unwritable due to wrong delimiter
• Fixed cockroach array parser dropping backslashes from string values
• Fixed cockroach int4[] being parsed to string[]
• Added mapper caching for queries reused without .prepare()
• Fixed table extra config not rejecting unsuitable for field values (fixes #6140)
• Fixed subquery derived from .$dynamic() query builder being unusable with .from, .*Join (fixes #4069)
• Fixed Placeholder value field described as declare protected: TValue instead of declared protected value: TValue; Set name field to protected and marked getSQL as @deprecated to prevent field from bleeding into relational filters’ autocomplete
• Fixed Subquery.getSQL() (fixes #2174)
• Fixed relational queries not supporting Subquery type fields in Views
• Fixed alias function returning materialized views typed as regular views
• Added typed isAlias: boolean type config property to View, Table to identify if it was aliased
• Added isTableAlias, getTableSchema utils, supported View in getTableName util
• Supported Subquery as relational entity in RQBv2:
  • Subquery must have flat selection, same as View
  • Every used Subquery will be invoked only once in WITH section on root level of relational query, every reference will use it’s alias
  • Same query can’t have reference multiple Subquery instances with same alias
• Fixed excessive memory consumption on mysql, mssql, singlestore iterators
• Fixed mysql2 iterators leaving connection un-drained & deadlocked on errors
• Fixed mysql2 iterators hanging when connection is dropped mid-stream
• Fixed ExtraConfigColumn.getSQL() recursing into stack overflow (fixes #6050)
• Fixed sqlite dropping | undefined from .get() return type of db.update(table).set(...).returning()
• Fixed sqlite dropping | undefined from .get() return type of db.insert(table).values(...).returning() with .onConflictDoNothing() or .onConflictDoUpdate({ where: ... }) present, db.insert(table).select(...).returning() (fixes #6107)
• Fixed select codecs leaking into builders passed as sql operator argument
• Fixed undefined = null, bigint = mimic string, different data view type collisions in hashQuery (fixes #5842)
• Fixed concurrent query + cache invalidation run (fixes #5828)
• Fixed cached query invalidation for:
  • tables in nested SQL & subqueries
  • aliased and tableCreator-prefixed tables
  • tables defined on schemas
  • joined & aliased tables of query builders embedded into raw sql
  • tables used in filters, selected fields, order clause, set operators, CTE-s
• Added getCacheKey(table) util returning the name query cache tracks a table by (schema.name, or name for tables without schema; aliases resolve to their original tables)
• Fixed orderBy of set operations dropping table qualifiers in passed sql objects (e.g. desc(column))
• Supported DSQL adapters for postgres-js (@aws/aurora-dsql-postgresjs-connector) - drizzle-orm/postgres-js/dsql, node-postgres (@aws/aurora-dsql-node-postgres-connector) - drizzle-orm/node-postgres/dsql
• Fixed param codecs getting applied to inlined params
• Reworked db.execute types (fixes #661):
  • Plain db.execute(sql) - returns union every possible response type by driver
  • db.execute<never>(sql) - returns rowless response type (i.e. insert without returning)
  • db.execute<ReturnedObject> - driver response with rows typed as ReturnedObject[]
• Fixed db.execute<IReturnedObject>(sql) type template rejecting interfaces
• Typed effect drivers’ raw db.execute, db.run (fixes #6382)
• Fixed RQBv2 query config lacking type errors with typescript@6 and above (fixes #5644, #6383)
• Fixed mysql date column being affected by server’s timezone (fixes #1442)
• Fixed effect-mysql, bun-sql/mysql drivers losing time fraction
• Fixed SQLiteBigInt attempting to use Buffer in encoder without Buffer present in environment (fixes #2043)
• Fixed durable-sqlite db.get(sql) throwing on queries returning zero or more than one row instead of returning undefined or the first row
• Fixed node-postgres transaction crashing process if connection is dropped mid-transaction (fixes #6437)
• Fixed node-postgres transaction leaking the pool client on BEGIN error (fixes #6341)
• Fixed failed transaction rollback error replacing the original error that triggered it
• Added ordering by relations to RQBv2:

  // Select users sorted by last post
  db.query.users.findMany({ orderBy: { posts: { createdAt: 'desc(max)' } } })
  
  // Select users sorted by post count
  db.query.users.findMany({ orderBy: { posts: 'asc(count)' } })
  
  // Select admin posts first, sort rest by creation date
  db.query.posts.findMany({ orderBy: { author: { isAdmin: 'desc' }, createdAt: 'desc' } })

• Added cache support to RQBv2 via withCache switch:
  • true - cache query
  • false - never cache query
  • undefined - cache only with all cache strategy

  db.query.users.findMany({ with: { posts: true }, withCache: true })

• Fixed instanceof not working reliably for drizzle classes in monorepos with multiple library instances
• Fixed aws-data-api/pg:
  • Array params throwing Unknown type error - now sent as pg array literals
  • Object params throwing Unknown type error - now sent as JSON with JSON type hint
  • Multidimensional arrays in results being returned as raw ArrayValue objects
  • char(n) params being truncated to a single character by ::char cast
  • inet values gaining full-width netmask (/32, /128) in results
  • time({ withTimezone: true }) values losing their offset: params were cast to ::time, results were converted to UTC by Data API
• Fixed pg time({ withTimezone: true }) columns using time codecs instead of timetz ones
• Fixed inArray/notInArray empty arrays do not work with SQL Server
• Fixed node-postgres pool client is not released when transaction BEGIN rejects
• Fixed Batch insert crashes with RangeError when row-count × column-count exceeds ~8 k rows × 15 cols (~120 k params)
• Fixed Composition of not and or/and yields compile error
• Fixed Negative limit not working in SQLite
• Fixed Pooled transaction() leaks the pool client when BEGIN fails (node-postgres / neon-serverless / vercel-postgres)
• Fixed node-postgres transaction() leaks the client on a rejected BEGIN and returns broken clients to the pool. node-postgres: transaction() runs BEGIN before try/finally, leaking the pool client when BEGIN fails

Drizzle Kit

• Added incremental PostgreSQL snapshots. The initial snapshot stores the full schema; subsequent snapshots store structured diffs and metadata for migration commutativity checks across branches.
• Added support for custom PGLite options (fixes #2995, #4476 and #3222)
• Fixed defineConfig allowing fields from every config variant simultaneously
• Fixed SQLite push glues the table’s FOREIGN KEY clause onto a generated-column ALTER ADD, breaking all inserts
• Fixed SQLite push table recreate silently drops UNIQUE from a column that also has a plain index
• Fixed drizzle-kit generates DROP COLUMN before DROP INDEX causing PostgreSQL error 42704
• Fixed false positive detection of schema changes for default values
• Fixed drizzle-kit pull rewrites “character” inside public enum type names to “char”
• Fixed drizzle-kit pull error when there are comments in a view definition
• Fixed Invalid schema default value generated for sequence-based primary keys in Postgres
• Fixed Small typo in drizzle-kit/src/index.ts
• Fixed drizzle-kit pull reports index_duplicate for valid MSSQL index names reused across tables
• Fixed drizzle-kit pull generates many() instead of one() for one-to-one relations (unique FK columns)
• Fixed AWS Data API Postgres - incompatibility with latest @aws-sdk/client-rds-data (3.932.0)
• drizzle-kit pull for SQLite Generates Constraints from Comments in Schema
• Fixed drizzle-kit pull fails with column_unsupported_unique for unique indexes on text/mediumtext/longtext columns
• Fixed drizzle-kit CLI pull/introspect schemaFilters parameter is ignored
• Fixed Changing a view to materialized view doesn’t generate correct migration
• Fixed SQLite incorrectly scaffolds boolean column with drizzle-kit pull
• Fixed Introspection fails if SQLite database has a references without column name
• Fixed SQLite pull drops or merges CHECK constraints depending on DDL formatting
• Fixed SQLite pull reads a partial index’s WHERE off the table’s DDL, losing real predicates and inventing false ones
• Fixed drizzle-kit pull generates a many-to-many whose junction table is one of its own endpoints, and drops the one-relations the foreign keys describe
• Fixed SQLite pull crashes on any expression index, because .on() doesn’t filter the keys the line above it does
• Fixed drizzle-kit push tries to DROP Neon system roles despite provider: “neon”
• Fixed drizzle-kit pull crashes on MSSQL when tablesFilter excludes referenced FK table
• Fixed drizzle-kit pull generates invalid through relations for composite foreign keys
• Fixed drizzle-kit pull: schema and relations disagree on camelCase for acronym columns (CallID → callId vs callID)
• Fixed drizzle-kit pull drops single-column PK/FK constraint names from schema.ts (kept nameExplicit in snapshot): pull→generate demands rename-or-create hints for every legacy-named constraint + Drizzle Kit introspection creates different foreign key names than migration
• Filtered PlanetScale’s __neki schema for postgresql dialect
• Fixed drizzle-kit pull treats domain tables with exactly two foreign keys as junction tables
• Fixed drizzle-kit pull fails with a confusing error if the database can’t be reached
• Fixed drizzle-kit generate drops column alterations when a column with the same name is renamed in another table
• Updates in pull command - migration.sql is no longer has comments when running pull --init
• Fixed drizzle-kit v1 generateMigration cannot resolve create/delete ambiguity programmatically (no HintsHandler). generateMigration and pushSchema from drizzle-kit/payload/* and drizzle-kit/api-postgres accept { hints } as the last argument: an array of the hint objects that the CLI --hints flag takes. If a rename question or a data loss confirmation has no hint, they throw an error with code: 'missing_hints' and the list of entities in missingHints. Entity ids use public as the schema for SQLite and MySQL and dbo as the default schema for MSSQL
• Fixed generateMigration from drizzle-kit/payload/sqlite and drizzle-kit/payload/mysql changing the snapshots that it gets when an indexed column is renamed
• Fixed SQLite introspection failing with chalk is not defined when a foreign key references a table that has no primary key and the foreign key names no column
• Fixed drizzle-kit push failing with a database error when a renamed table, a table moved to another schema or a table in a renamed schema also needed a data loss check
• Updated the data loss warnings of drizzle-kit push: all dialects use the same texts and quote every name as in SQL. A warning shows the table by the name that the database has before the push, and adds (would become ...) when the push renames or moves the table
• drizzle-kit push asks to confirm a dropped column only when the column has a non-null value. Before, PostgreSQL, CockroachDB, MySQL, SingleStore and SQLite asked when the table had a row
• Fixed drizzle-kit pull writing SQL text with a backslash, a backtick or ${ into the schema file without escaping it. The pulled schema now compiles and keeps this text in these places. PostgreSQL and CockroachDB: check constraints, views, generated columns, policies, index expressions, index predicates, and default expressions that pull writes as a sql template. CockroachDB: enum values. MSSQL: check constraints, views, generated columns, index predicates, and default expressions that pull writes as a sql template. SQLite: generated columns, and default expressions of integer and text columns. For MySQL the pulled schema now compiles when a check constraint, or a default expression that pull writes as a sql template, has a backtick or ${. MySQL returns a backslash in this text already escaped, so pull writes it unchanged
• The postgresql dialect rejects --ignore-conflicts in generate, check and migrate. drizzle-kit generate --fix-conflicts replaces it
• The bundled agent skills are one skill named drizzle now. After drizzle-kit skills adds it, the command removes the seven older skills from the project without a question: drizzle-generate, drizzle-push, drizzle-pull, drizzle-migrations, drizzle-hints, drizzle-output-modes and drizzle-responses-and-errors
• Fixed drizzle-orm not being listed as peer dependency
• Fixed dev dependencies being listed as production
• Fixed composition of not with or or and causing compile errors.
• Fixed snakeCase.table converting Korean column names to empty identifiers.
• Fixed the missing decimal property when using pgTable.

Sources

• Published release
• Drizzle ORM changelog
• Drizzle Kit changelog