- Home
- Skills
- Data & Databases
- Catch Mongoose schema changes that break old documents
Works with the AI Agents you already use
Catch Mongoose schema changes that break old documents
Once you deploy a Mongoose schema change it is live, and every document already in the collection keeps its old shape.
$6
Catch Mongoose schema changes that break old documents
Example session with this skill installed
Here's my diff to src/models/User.ts (Mongoose 9): email gets lowercase, trim and unique; fullName is replaced by a required name; role enum goes from admin/editor/viewer to admin/member; I added status with default 'active', removed inviteToken and turned on timestamps. Is it safe to deploy?
- Read your context and instructions
- Compiled the catch mongoose schema
Schema change check: User (src/models/User.ts)
Mongoose version: ^9.10.0 (package.json)
Verdict: NEEDS BACKFILL FIRST
Findings (abridged)
[Blocker] Every existing user fails to log in: the login handler's save() rejects old documents
- Change:
nameadded as required with no default (fullNamewas optional and is gone). - What happens to old documents: save() validates the whole document, so setting lastLoginAt on a user without
namethrows a ValidationError. Users with role editor/viewer also fail onrole. - Where it bites: src/routes/users.ts:9 (POST /login), :21 (PATCH /users/:id)
- Data check:
db.users.countDocuments({ name: { $exists: false } }) - Fix: backfill
namefromfullName, batched by _id (with Mongoose 9, pipeline updates needupdatePipeline: true). (Backfill first)
[Blocker] Login stops finding users whose stored email has capitals or spaces
- Change: email gets lowercase: true, trim: true.
- What happens to old documents: setters run on the query filter but not on stored data, so findOne({ email: 'Anna@Corp.com' }) sends 'anna@corp.com' and misses the stored 'Anna@Corp.com'.
- Where it bites: src/routes/users.ts:6
- Data check:
db.users.aggregate([{ $match: { $expr: { $ne: ["$email", { $toLower: { $trim: { input: "$email" } } }] } } }, { $count: "n" }]) - Fix: normalize stored emails after resolving duplicates. (Backfill first)
[Blocker] The unique email index may fail to build (check duplicates by the normalized value)
[Blocker] Users with role editor/viewer can no longer be saved
[High] POST /users/:id/role uses updateOne without runValidators and bypasses the new enum
[High] The removed inviteToken still appears in res.json(user) and the lean list
[High] ?status=active misses all old users (the default isn't stored; the lean list shows no status)
[Medium] Sorting by name puts unnamed old users first
[Medium] Saved users get status/updatedAt, untouched ones don't; createdAt is never added
Deploy order
- Run the data checks.
- Resolve email duplicates.
- Backfill name, email, role, status; $unset inviteToken.
- Build the unique index deliberately.
- Deploy with runValidators on the role endpoint.
Open questions
- Is fullName → name a rename? Which new role should editor/viewer become? How are indexes built in production?
Connects securely to your tools. The creator never sees your data.
About this skill
Why
MongoDB has no migration step. Once you deploy a Mongoose schema change it is live, and every document already in the collection keeps its old shape. The breakage shows up later, when someone edits an old record, logs in with an old account, or filters a list. TypeScript and linters can't see any of it, because old data never passes through the compiler.
What it checks
For every changed path (added, removed, renamed, type, required, default, enum/validators, lowercase/trim/setters, unique/indexes, select: false, timestamps, subdocuments), the skill works out what happens to existing documents in five places: hydrated reads, .lean()/aggregate reads, query filters, save() and updateOne/findOneAndUpdate. It covers, for example:
save()validates the whole document, so a newrequiredfield or a narrowerenumbreaks unrelated edits (login handlers that updatelastLoginAt, admin edit forms)lowercase/trimare applied to query filters but not to stored data, so lookups by email silently miss old mixed-case records- defaults show up on hydrated reads but aren't in the database, so filters, counts and lean reads disagree with what the UI shows
- stored values that can't be cast to a new type read as
undefinedwhile the database still holds them - fields removed from the schema still appear in
toJSON()andres.json(doc) uniqueis an index, not a validator: duplicates (including ones that only appear after normalizing) stop it from building- update queries skip the new validators unless
runValidatorsis set
These rules were checked against Mongoose 9.12 (docs plus direct tests) and ship as a reference file with the skill.
What you get
- A change inventory
- Findings ranked Blocker, High, Medium or Info, each with the mechanism, the file and line where it bites, and a read-only data-check query you can run
- The smallest fix for each finding (backfill first, code first, or code only)
- A deploy order and a verdict: SAFE TO DEPLOY, DEPLOY AFTER CHECKS or NEEDS BACKFILL FIRST
Limits
The skill reads files only and never connects to your database. It complements database-level migration tools. It does not replace them, and it does not write or run migrations.
Does not connect to MongoDB or run any queries, migrations or write commands. Doesn't cover discriminators, collection renames, versionKey changes, custom plugins or middleware that rewrites data (these go under Open questions). Doesn't review SQL databases or ORMs other than Mongoose. Severity depends on data you check yourself with the queries it provides. Doesn't do a general code review of the surrounding code.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 4 days ago
Requires
Permissions
File Scopes
read_files: to read the schema, the Mongoose version and the code that uses the changed fields. bash is optional and limited to read-only commands (git diff/log/show to get the old and new schema, grep to find usages). The skill never writes files, installs packages, connects to a database or makes network requests. The data-check queries it proposes are read-only, and you run them yourself.