Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Catch Mongoose schema changes that break old documents

    1

    Once you deploy a Mongoose schema change it is live, and every document already in the collection keeps its old shape.

    $6

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    Catch Mongoose schema changes that break old documents

    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: name added as required with no default (fullName was optional and is gone).
    • What happens to old documents: save() validates the whole document, so setting lastLoginAt on a user without name throws a ValidationError. Users with role editor/viewer also fail on role.
    • Where it bites: src/routes/users.ts:9 (POST /login), :21 (PATCH /users/:id)
    • Data check: db.users.countDocuments({ name: { $exists: false } })
    • Fix: backfill name from fullName, batched by _id (with Mongoose 9, pipeline updates need updatePipeline: 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

    1. Run the data checks.
    2. Resolve email duplicates.
    3. Backfill name, email, role, status; $unset inviteToken.
    4. Build the unique index deliberately.
    5. 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?
    package.json

    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 new required field or a narrower enum breaks unrelated edits (login handlers that update lastLoginAt, admin edit forms)
    • lowercase/trim are 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 undefined while the database still holds them
    • fields removed from the schema still appear in toJSON() and res.json(doc)
    • unique is an index, not a validator: duplicates (including ones that only appear after normalizing) stop it from building
    • update queries skip the new validators unless runValidators is 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. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 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

    Mongoose project (Node.js)
    Git

    Permissions

    File Scopes

    Mongoose
    model/schema
    files
    package.json
    (to
    read
    the
    mongoose
    version)
    Source
    that
    query
    or
    write
    changed
    fields

    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.

    Listed4 days ago

    What's inside

    Frequently Asked Questions

    No. It only reads your schema, package.json and the code that uses the changed fields. It writes read-only queries (countDocuments, find with limit, aggregate with $group/$match) for you to run yourself, and a count of zero tells you the finding can't happen with your data.

    The behavior rules were checked against Mongoose 9.12, and most of them have been stable for years. The skill reads your version from package.json. On versions older than 7 it warns that strictQuery behaves differently and that some findings may change.

    By default it outlines each backfill (filter, update, batching by _id) and tells you whether it has to run before or after the deploy. It writes a full script only if you ask, and running it is always up to you.

    Then you get a short report: the inventory, no findings and SAFE TO DEPLOY. The skill is told not to invent problems or pad the report with general advice.

    New in Data & Databases