github prisma/orm v8.0.0-rc.24

pre-release32 minutes ago

v8.0.0-rc.24

MongoDB gets the convenience date and time types, and Date becomes a calendar date. A MongoDB TypeScript contract names a field's type with type.X(), as PSL does, and MongoDB clients can prepare a query. MongoDB plans check documents before a validator change and ask about type changes that can lose values. SQL clients take transaction isolation levels and callback timeouts. The CLI manages MariaDB, and answers Prisma 7 commands such as prisma migrate dev with what to run instead. Nested create() and update() gain arrays of operations and filtered updateAll and deleteAll, and db.raw.sql embeds builder queries.

The upgrade recipes for this hop: the app recipe and the extension recipe. Each breaking change below names the change ids to look for in them. The app recipe opens with the order to do the steps in. After upgrading, run prisma contract emit once, so a contract that an extension such as Supabase stamps with its version matches the installed package (contract-artifacts-restamp in the app recipe).

Breaking changes

  • On MongoDB, Date is a calendar date. Date is now stored as a BSON date at midnight UTC and read as a string such as "2024-02-29". DateTime is what Date was: an instant read as a JavaScript Date. DateTime(as: temporal), Time and Duration are new. Rewrite Date to DateTime in MongoDB schemas with the script the app recipe ships; the contract does not change. A field you miss still compiles, but @onCreate(now()) on it then writes today's date at midnight UTC and loses the time. temporal-polyfill is now a required peer dependency of @prisma/orm-mongo and @prisma/orm-target-mongo; a project that installs with Yarn, or with npm and legacy-peer-deps, adds it to its dependencies. See mongo-date-is-a-calendar-date, temporal-polyfill-is-a-peer-dependency-of-mongo and temporal-polyfill-with-legacy-peer-deps in the app recipe. (#30989)

    Before:

    model Order {
      id     ObjectId @id @map("_id")
      paidAt Date
    }

    After:

    model Order {
      id     ObjectId @id @map("_id")
      paidAt DateTime
    }
  • A MongoDB TypeScript contract names a field's type with type.X(). field.objectId(), field.string(), field.date(), field.vector(), field.scalar(codecId) and the other MongoDB field helpers are removed. Write field.scalar(type.X()), where type comes from the defineContract callback, as PSL names the type. The app recipe ships a script that rewrites them; the contract does not change. MongoDB PSL gains Vector and Vector(length), and a type that takes no arguments, written with one, such as String(5), is now refused. Extension authors whose extension has its own MongoDB codec add a type constructor under authoring.type. See mongo-fields-take-a-type in the app recipe and the extension recipe. (#30959)

    Before:

    fields: {
      _id: field.objectId(),
      embedding: field.vector({ typeParams: { length: 3 } }),
      raw: field.scalar('mongo/bson@1'),
    }

    After:

    fields: {
      _id: field.scalar(type.ObjectId()),
      embedding: field.scalar(type.Vector(3)),
      raw: field.scalar(type.Bson()),
    }
  • MongoDB plans rewrite the documents a schema change touches. A validator change that migration plan or db update writes now checks every document first, and the apply stops with MIGRATION.PRECHECK_FAILED while a document does not fit the new validator. A field type change that can lose values is now a question, answered with --convert or --delete, as on SQL. A new required field is filled with a temporary value in the documents that lack it, unless --backfill names it. Existing migration.ts files are unchanged. See mongo-validator-change-checks-documents, mongo-type-change-is-asked and mongo-new-required-field-gets-temporary-value in the app recipe. (#30970)

  • MySQL no longer sets every session to READ COMMITTED. A callback transaction with no isolation level now uses the server or session default. If your code relied on READ COMMITTED, pass transactionOptions: { isolationLevel: 'ReadCommitted' } to the MySQL client, or pass it to transaction(callback, options). Transactions the ORM opens for its own writes still use READ COMMITTED. Extension authors forward the isolation options through their SQL transaction wrappers. See mysql-explicit-isolation-default in the app recipe and forward-sql-transaction-options in the extension recipe. (#30990)

  • @prisma/orm-postgres/migration no longer exports the free functions createExtension and dataTransform. Neither could be called correctly from a migration.ts. Call the methods on the migration class instead: this.createExtension({ extension: 'btree_gist' }) and this.dataTransform(endContract, name, { check, run }). The migration's ops.json does not change. See create-extension-not-exported and data-transform-not-exported in the app recipe. (#30988)

  • Prisma 7 commands fail with CLI.V7_COMMAND. prisma generate, validate, format, studio, db pull, db push, db seed, db execute and the six prisma migrate commands now fail with CLI.V7_COMMAND instead of CLI.COMMAND_MOVED, still with exit code 2. The error names the Prisma 8 commands to run instead, or links the CLI docs when Prisma 8 has none, and says how to install Prisma 7's CLI as @prisma/prisma7 to keep running the old command. The toolchain now requires @prisma/cli-engine@0.10.0; a project that depends on it itself moves to 0.10.0. See prisma-7-commands-answer-v7-command and engine-pin-moves-to-0-10-0 in the app recipe. (#31027)

  • The CLI's --json output lists planner warnings under plannerWarnings. db update --json and db init --json list the planner's warnings under plannerWarnings instead of warnings, as migration plan --json does. See planner-warnings-json-field in the app recipe. (#30970)

  • Raw SQL parts can hold a statement. The parts of RawExpr and RawQueryAst can now hold a SelectAst, InsertAst, UpdateAst or DeleteAst. Code that walks parts and treats every non-string part as an expression must handle the four statement kinds. See raw-parts-hold-statement-asts in the app recipe and the extension recipe. (#30991)

  • Extension authors: runtime transactions carry an AbortSignal. Runtime connection and activity wrappers take RuntimeTransactionOptions and forward them unchanged, and every hand-written RuntimeTransaction, test doubles included, exposes a signal. See runtime-transaction-signal in the extension recipe. (#31012)

  • Extension authors: MongoRuntime and MongoClient have prepare. An object typed as either, such as a test double, needs a prepare method, and MongoLimitStage.limit, MongoSkipStage.skip and MongoValue can hold a prepared-statement placeholder. See mongo-runtime-has-prepare and mongo-limit-skip-take-placeholders in the extension recipe. (#30967)

Features

  • The CLI emits, migrates, verifies and signs against MariaDB, through the new @prisma/orm-mariadb package and a mariadb target that extends MySQL. (#30964)
  • SQL clients take a transaction isolation level: set a default with the client's transactionOptions, or pass one to transaction(callback, { isolationLevel }). IsolationLevel is exported from each database's /runtime entry. (#30990)
  • Callback transactions take a timeout in milliseconds, as a client default in transactionOptions or per call. There is no default timeout. A transaction that runs out of time has its connection destroyed, not returned to the pool. (#31012)
  • MongoDB clients can prepare a query once and run it many times with db.prepare(declaration, callback), as SQL clients can, including $skip and $limit counts. (#30967)
  • db.raw.sql embeds a builder query, or a builder mutation after .returning(), as a statement, such as INSERT INTO ... ${query} RETURNING .... (#30991)
  • A relation callback in create() or update() can return an array of operations, applied in order. (#31013)
  • Inside update(), a relation callback can update or delete the related rows a filter matches, with where(...).updateAll(...) and where(...).deleteAll(), on one-to-many relations (#31014) and many-to-many relations (#31016).
  • On a database with RETURNING, update() and delete() whose condition names one row by its primary key or a unique constraint send the write alone, without first selecting the row's key. Results are unchanged. (#31026)
  • Nested create() and update(), and every other SQL ORM write, run through one write graph on every database, so nested writes work the same with and without RETURNING. (#30734, #31004)
  • The contract.d.ts that a migration snapshot stores under migrations/snapshots/ is now written on one line, instead of about 1,400. The contract.d.ts your code imports is unchanged. (#30965)

Fixes

  • The defineConfig helpers for PostgreSQL, MongoDB, MySQL and SQLite pass formatter through, so prisma contract format uses the indent and line endings prisma.config.ts sets. (#30960)
  • orm init keeps a tsconfig.json on node16 or nodenext, and scaffolds a db.ts whose contract import resolves there. (#30360)
  • gt, lt, gte and lte accept a nullable column to compare with. (#30477)
  • upsert's update input takes the fields of a namespaced model whose name another namespace also uses. (#30407)
  • fullTextHeadline refuses word limits that PostgreSQL would refuse when only one of the two limits is given, with RUNTIME.ARGUMENT_INVALID when the query is built. (#30415)
  • db schema on MongoDB prints a field with several BSON types as a | b. (#30476)
  • RUNTIME.DATE_STYLE_NOT_ISO and RUNTIME.LC_MONETARY_NOT_C say whether the write was already committed. (#30963)
  • The prisma-8 skill tells agents to declare a relation's back-reference on the other model, since Prisma 8 does not derive it. (#30483)
  • The rc.20 to rc.21 upgrade guides tell users to re-emit contract.d.ts instead of editing it (#30987), and the rc.21 to rc.22 guide gives the fix for a migration.ts that calls the free createExtension (#30988).

Don't miss a new orm release

NewReleases is sending notifications on new releases.