NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm
npm, #4415 most downloaded on npm
Mongoose MongoDB ODM
Latest stable
9.12.2
Last release 6 days ago
16 Nov 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 55 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
16 years old
1038 releases · first in 2010
Drag across the ruler to compare, or tap a release to open it.
fix(query): make sanitizeFilter catch any fields that start with $ in top-level filter to avoid bypass using $_internalSchemaXor and other MongoDB int
Your coding agent can read these notes before it upgrades. Set up the MCP server →
perf(update): avoid quadratic ancestor lookup in update validators and validate nested array subdocs once #16586 https://github.com/Re-cool
feat: upgrade to mongodb driver 7.8 #16772 #16667
fix: avoid walking into inherited properties like toString when hydrating documents, setting dotted paths, and merging updates
toString when hydrating documents, setting dotted paths, and merging updates__proto__ as paths in where() and mod()fix(update): honor overwriteImmutable in upserts and nested timestamps #16614 #15781 #8619 AbdelrahmanHafez
perf: avoid applying saveSubdocs and sharding plugins to subdocuments #16585
fix(document): call recursive toObject() when setting a path to a nested object #16571
feat: use MongoDB Node.js driver 7.7.x #16550
fix: handle MongoDB server 9.x returning collation: { locale: 'simple' } on all indexes #16557
fix(model): preserve unsaved documents after ordered bulkSave errors #16533 #16532 IbrahimHafez1
fix(schema): drop subpaths and singleNestedPaths when a path is removed #16521 #16520 luantaraschi
types: relax populate Model generics to allow typed virtuals to be passed to populate in TypeScript 7 with skipLibCheck #16503
feat: upgrade mongodb driver -> 7.6.0
fix(query): pass schema through when casting a nested $expr comparison #16496 rajanpanth
fix(query): set strictQuery and strict on _mongooseOptions consistently #16451 #16447
docs: document new/returnOriginal deprecation from 9.2.0 #16449 #16008 #15972 alimughal95
fix(query): apply sanitizeFilter on countDocuments and cursor()
fix(query): avoid path collision when excluding subdocuments with nested select: false paths #12798
perf(document): improve toObject perf with faster string checks and avoiding unnecessary isSelected on paths with no getters #16407 #16373 #16385
perf(document): avoid rebuilding modified paths during required path validation #16379 xianjianlf2
toString() results in array.unique to avoid redundant allocations #16390 vivek180905_id option when inferring StandardSchema types #16402Model.schema typed when TSchema is omitted samuelmbabhazistrictQuery handling of filter paths not in the schema #16397 MuhammadFarhantahirfeat(schema): add strictRead option to filter or throw on unknown fields during document hydration #16345 #4279 GourabSingha
strictRead option to filter or throw on unknown fields during document hydration #16345 #4279 GourabSinghabulkSave() inserts new documents #16386 #15800 AbdelrahmanHafezpathsToSave to SaveOptions #16375 AbdelrahmanHafezhydrate() with strict: false #16374 #15940 AbdelrahmanHafezperDocumentLimit for populate() #16371 Wnayarsample() example to show sampling from a filtered subset #16369 Wnayartypes(create): fix handling of nested objects typed as interfaces #16363 #16362
this parameter handling for methods with versionKey #16344 #16046querySrv ECONNREFUSED errors on Windows with mongodb+srv:// connections #16342 ajay naiktypes(model): correct Model.validate() return type to Promise #16340 #16338
fix(documentarray): reindex subdocs after array reordering and removal so subsequent nested changes save using the correct path #16282 AbdelrahmanHafe
Document.prototype.get()perf(document+model): improve save performance by avoiding unnecessary promise allocations and reducing path/default/dirty-state overhead #16331
toJSONSchema() output #16335 #16334 AbdelrahmanHafez$in filter has more than 50k elements to reduce risk of BSON size errors #16333 #5890llms.txt generation #16326 #16327 #16329feat: add Node.js TracingChannel support for APM instrumentation #16275 #16105 logaretm
$slice #16313 #2432validateSync() union fallback #16310 #16291 AbdelrahmanHafezllms.txt #16312 #15687model.validate() casting #16308 #16280fix(clone): isolate cloned arrays from source documents #16281 AbdelrahmanHafez
$setOnInsert.createdAt with overwriteImmutable: true #16278 #15781 AbdelrahmanHafez$percentile to TypeScript aggregation expression types #16290 #16288fix(document): correctly handle modified subpaths when parent path is unset after modifying #16271 #16252
types(objectid): fix _id getter helper on ObjectId #16251 noseworthy
_id getter helper on ObjectId #16251 noseworthyfeat: upgrade mongodb node driver to 7.2 #16245
allowNull option to disallow null values even if not required #16237 #15905feat(debug): add timestamp option to debug output #16216 rejunp
timestamp option to debug output #16216 rejunpcloneUpdate option to explicitly disable update cloning #16230 #16202defaults query option to find() #16226 sderrow__proto__ #16230 #16202$set() method as objects with a $set property when casting updates #16230ObjectParameterError in insertOne() if doc is not an object #16221 IshitaSingh0822CastError message after setModel() #16167 White-Devil2839findOneAndUpdate() #16230Revert "fix(setDefaultsOnInsert): run setters on default values during upsert" #16218 #16051
feat(document): add $getChanges() alias, deprecate getChanges() #15959 techcodie
id to HydratedDocument virtuals by default unless explicitly set #16178fix(schemaType): standardize to use MongooseError instead of plain Error #16172 VIPAX-JIT
fix(mongoose): throw error when trying to set null or undefined as options #16130 #16140
fix(model): handle passing string projection to hydrate() #16082
hydrate() #16082bulkWrite() sorting #16079 #16080 pnkovthis context in QueryCursor close callback #16104 techcodieHydratedDocType in autoTypedVirtuals #16083Schema.prototype.plugin() #16090 #16086MongooseError instead of Error in schema, model, and aggregate #15995 mahmoodhamdiparseProjection()feat(schema): support discriminators option inline for better TypeScript support #16053
discriminators option inline for better TypeScript support #16053pipelineForUnionWith() helper to allow reusing pipelines with $unionWith in TypeScript #16033Document#$model() and Document#model() mrazauskastypes(models): allow unknown keys in subdocs while retaining autocomplete suggestions #16048
@returns declarations #16036 #16018types(model): make bulkSave() correctly take array of THydratedDocumentType #16032
fix(document): make pathsToSave filter all update operators and preserve unsaved state #16027
pathsToSave filter all update operators and preserve unsaved state #16027refPath work as a function, including map paths with $* #16035 #16028pathsToSave and indexed-path checks for subdocumentsUUIDToJSON type #16029extraOptions under autoEncryption #16026 #16015types(query): allow assigning QueryFilter to QueryFilter #16020
QueryFilter<DocType> to QueryFilter<any> #16020feat: add option to skip middleware #15883 #8768 AbdelrahmanHafez
fix: handle other top-level query operators in sanitizeFilter
fix(map): validate map subdocument when loaded with init #15960 #15957 AbdelrahmanHafez
fix: attach sessions to docs retrieved by cursor #15953 #15949 mjfwalsh
fix(model): support timestamps option to insertMany() as both boolean and QueryTimestampsConfig #15941 #15938
fix(subdocs): pass options to pre-save hooks for subdocs #15921 #15920 AbdelrahmanHafez
fix(document): avoid 'Cannot mix array and object updates' on doc.updateOne() with pipeline #15928
feat(model): make pathsToSave handle saving just a subpath of a modified path #15896
fix(model): trigger error post hook on bulkwrite when pre-hook throws an error #15882 AbdelrahmanHafez
perf: use native Buffer.equals() for buffer comparison #15821 AbdelrahmanHafez
BREAKING CHANGE: drop support for callback-based pre middleware, e.g. next() in pre() hooks
next() in pre() hooksthis to HydratedDocument for default() and required(), HydratedDocument | Query for validate() #15020 #14696fix(populate): correctly populate embedded discriminators on subdocuments #15774
BREAKING CHANGE: drop support for callback-based pre middleware, e.g. next() in pre() hooks
next() in pre() hooksthis to HydratedDocument for default() and required(), HydratedDocument | Query for validate() #15020 #14696fix(query): make sanitizeFilter catch any fields that start with $ in top-level filter to avoid bypass using $_internalSchemaXor and other MongoDB int
fix(document): allow setting dotted paths 3+ levels deep underneath single nested subdocuments #16691 RagedPanda
fix(schema): remove map paths cleanly, including maps under nested paths (backport to 8.x) #16625 #16461 #16457 mrityunjay-pandey
fix: avoid walking into inherited properties like toString when hydrating documents, setting dotted paths, and merging updates
toString when hydrating documents, setting dotted paths, and merging updates__proto__ as paths in where() and mod()fix(array): compare dates by value in indexOf() so pull() removes them #16590 #16535 mrityunjay-pandey
fix: handle MongoDB server 9.x returning collation: { locale: 'simple' } on all indexes #16557
One column per quarter.