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,
Dateis a calendar date.Dateis now stored as a BSON date at midnight UTC and read as a string such as"2024-02-29".DateTimeis whatDatewas: an instant read as a JavaScriptDate.DateTime(as: temporal),TimeandDurationare new. RewriteDatetoDateTimein 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-polyfillis now a required peer dependency of@prisma/orm-mongoand@prisma/orm-target-mongo; a project that installs with Yarn, or with npm andlegacy-peer-deps, adds it to its dependencies. Seemongo-date-is-a-calendar-date,temporal-polyfill-is-a-peer-dependency-of-mongoandtemporal-polyfill-with-legacy-peer-depsin 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. Writefield.scalar(type.X()), wheretypecomes from thedefineContractcallback, as PSL names the type. The app recipe ships a script that rewrites them; the contract does not change. MongoDB PSL gainsVectorandVector(length), and a type that takes no arguments, written with one, such asString(5), is now refused. Extension authors whose extension has its own MongoDB codec add a type constructor underauthoring.type. Seemongo-fields-take-a-typein 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 planordb updatewrites now checks every document first, and the apply stops withMIGRATION.PRECHECK_FAILEDwhile a document does not fit the new validator. A field type change that can lose values is now a question, answered with--convertor--delete, as on SQL. A new required field is filled with a temporary value in the documents that lack it, unless--backfillnames it. Existingmigration.tsfiles are unchanged. Seemongo-validator-change-checks-documents,mongo-type-change-is-askedandmongo-new-required-field-gets-temporary-valuein 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 totransaction(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. Seemysql-explicit-isolation-defaultin the app recipe andforward-sql-transaction-optionsin the extension recipe. (#30990) -
@prisma/orm-postgres/migrationno longer exports the free functionscreateExtensionanddataTransform. Neither could be called correctly from amigration.ts. Call the methods on the migration class instead:this.createExtension({ extension: 'btree_gist' })andthis.dataTransform(endContract, name, { check, run }). The migration'sops.jsondoes not change. Seecreate-extension-not-exportedanddata-transform-not-exportedin the app recipe. (#30988) -
Prisma 7 commands fail with
CLI.V7_COMMAND.prisma generate,validate,format,studio,db pull,db push,db seed,db executeand the sixprisma migratecommands now fail withCLI.V7_COMMANDinstead ofCLI.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/prisma7to keep running the old command. The toolchain now requires@prisma/cli-engine@0.10.0; a project that depends on it itself moves to0.10.0. Seeprisma-7-commands-answer-v7-commandandengine-pin-moves-to-0-10-0in the app recipe. (#31027) -
The CLI's
--jsonoutput lists planner warnings underplannerWarnings.db update --jsonanddb init --jsonlist the planner's warnings underplannerWarningsinstead ofwarnings, asmigration plan --jsondoes. Seeplanner-warnings-json-fieldin the app recipe. (#30970) -
Raw SQL parts can hold a statement. The
partsofRawExprandRawQueryAstcan now hold aSelectAst,InsertAst,UpdateAstorDeleteAst. Code that walkspartsand treats every non-string part as an expression must handle the four statement kinds. Seeraw-parts-hold-statement-astsin the app recipe and the extension recipe. (#30991) -
Extension authors: runtime transactions carry an
AbortSignal. Runtime connection and activity wrappers takeRuntimeTransactionOptionsand forward them unchanged, and every hand-writtenRuntimeTransaction, test doubles included, exposes asignal. Seeruntime-transaction-signalin the extension recipe. (#31012) -
Extension authors:
MongoRuntimeandMongoClienthaveprepare. An object typed as either, such as a test double, needs apreparemethod, andMongoLimitStage.limit,MongoSkipStage.skipandMongoValuecan hold a prepared-statement placeholder. Seemongo-runtime-has-prepareandmongo-limit-skip-take-placeholdersin the extension recipe. (#30967)
Features
- The CLI emits, migrates, verifies and signs against MariaDB, through the new
@prisma/orm-mariadbpackage and amariadbtarget that extends MySQL. (#30964) - SQL clients take a transaction isolation level: set a default with the client's
transactionOptions, or pass one totransaction(callback, { isolationLevel }).IsolationLevelis exported from each database's/runtimeentry. (#30990) - Callback transactions take a
timeoutin milliseconds, as a client default intransactionOptionsor 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$skipand$limitcounts. (#30967) db.raw.sqlembeds a builder query, or a builder mutation after.returning(), as a statement, such asINSERT INTO ... ${query} RETURNING .... (#30991)- A relation callback in
create()orupdate()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, withwhere(...).updateAll(...)andwhere(...).deleteAll(), on one-to-many relations (#31014) and many-to-many relations (#31016). - On a database with
RETURNING,update()anddelete()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()andupdate(), and every other SQL ORM write, run through one write graph on every database, so nested writes work the same with and withoutRETURNING. (#30734, #31004) - The
contract.d.tsthat a migration snapshot stores undermigrations/snapshots/is now written on one line, instead of about 1,400. Thecontract.d.tsyour code imports is unchanged. (#30965)
Fixes
- The
defineConfighelpers for PostgreSQL, MongoDB, MySQL and SQLite passformatterthrough, soprisma contract formatuses the indent and line endingsprisma.config.tssets. (#30960) orm initkeeps atsconfig.jsononnode16ornodenext, and scaffolds adb.tswhose contract import resolves there. (#30360)gt,lt,gteandlteaccept a nullable column to compare with. (#30477)upsert'supdateinput takes the fields of a namespaced model whose name another namespace also uses. (#30407)fullTextHeadlinerefuses word limits that PostgreSQL would refuse when only one of the two limits is given, withRUNTIME.ARGUMENT_INVALIDwhen the query is built. (#30415)db schemaon MongoDB prints a field with several BSON types asa | b. (#30476)RUNTIME.DATE_STYLE_NOT_ISOandRUNTIME.LC_MONETARY_NOT_Csay whether the write was already committed. (#30963)- The
prisma-8skill 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.tsinstead of editing it (#30987), and the rc.21 to rc.22 guide gives the fix for amigration.tsthat calls the freecreateExtension(#30988).