mongodb-crud

MongoDB CRUD

Safely inspect and change MongoDB documents through saved local profiles. The skill uses a Bash script and mongosh; it does not depend on Python or jq.

Purpose

Use this skill for:

• saving reusable MongoDB connection profiles
• direct MongoDB shell connections
• SSH tunnel connections to private MongoDB hosts
• SSH remote execution where MONGODB_URI exists on a server, such as a remote .env file
• ping, database listing, collection listing, find, count, insert, update, delete, and guarded raw MongoDB JavaScript

Output:

• JSON printed to stdout
• the same JSON saved to ./out/mongodb-crud-<UTC timestamp>-<pid>.json by default

Safety Rules

• Never save MongoDB credentials in this repository.
• Use ~/.config/mongodb-crud/profiles/<profile>.conf for saved profiles.
• Do not print passwords or full MongoDB URIs; use list-profiles for redacted output.
• Prefer read-only commands unless the user clearly asks to mutate data.
• insert, update, delete, and raw write JavaScript dry-run by default.
• Run structured writes with --execute only after explicit user confirmation.
• Raw write JavaScript requires both --execute and --allow-raw-write.
• readonly profiles must not be used for write commands.
• Prefer structured commands over raw-eval.
• Pass MongoDB filters, documents, updates, projections, and sort options as JSON or MongoDB Extended JSON strings.

What This Skill Needs

• bash
• local mongosh for direct and ssh-tunnel profiles
• ssh for ssh-tunnel and ssh-remote profiles
• remote bash and mongosh for ssh-remote profiles

Profile Storage

Profiles are saved under:

~/.config/mongodb-crud/profiles/

The default profile name is saved at:

~/.config/mongodb-crud/default_profile

Each profile is a 0600 shell-style config file. Example:

MODE=ssh-remote
READONLY=true
SSH_ALIAS=app-prod
REMOTE_CWD=/server/app
ENV_FILE=.env
ENV_KEY=MONGODB_URI
DATABASE=app

Do not edit this file by hand unless needed; prefer configure.

Configure Profiles

Direct MongoDB

Prefer a full MongoDB URI when available:

bash <skill-path>/scripts/mongodb_crud.sh configure \
  --profile local \
  --mode direct \
  --uri "mongodb://user:password@127.0.0.1:27017/app?authSource=admin" \
  --database app \
  --default

Or use explicit fields:

bash <skill-path>/scripts/mongodb_crud.sh configure \
  --profile local \
  --mode direct \
  --mongo-host 127.0.0.1 \
  --mongo-port 27017 \
  --database app \
  --mongo-username app_user \
  --prompt-mongo-password \
  --auth-database admin \
  --default

Add --test-connection to verify ping before the profile is saved.

SSH Remote

Use this when the agent should SSH to a server and run the remote mongosh there. This is best when the server has access to a private MongoDB instance and MONGODB_URI is already present in a remote .env file.

bash <skill-path>/scripts/mongodb_crud.sh configure \
  --profile prod \
  --mode ssh-remote \
  --ssh-alias app-prod \
  --remote-cwd /server/app \
  --env-file .env \
  --env-key MONGODB_URI \
  --database app \
  --readonly \
  --default

The script SSHes to the server, optionally runs cd <remote_cwd>, reads MONGODB_URI from the remote .env, and runs mongosh on the remote host. It must not display the full MONGODB_URI.

Use --remote-cwd when the .env file exists only inside an application directory after SSH login. --env-file may be either relative to --remote-cwd, such as .env, or an absolute path.

SSH Tunnel

Use this when the local script should open an SSH tunnel to a private MongoDB host, then connect locally with mongosh.

bash <skill-path>/scripts/mongodb_crud.sh configure \
  --profile staging \
  --mode ssh-tunnel \
  --ssh-host staging.example.com \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/staging.pem \
  --mongo-host 10.0.1.20 \
  --mongo-port 27017 \
  --database app \
  --mongo-username app_user \
  --prompt-mongo-password \
  --auth-database admin

List Profiles

bash <skill-path>/scripts/mongodb_crud.sh list-profiles

The output is redacted.

Remove Profile

bash <skill-path>/scripts/mongodb_crud.sh remove-profile --profile staging

Read Commands

Ping:

bash <skill-path>/scripts/mongodb_crud.sh ping --profile prod

List databases:

bash <skill-path>/scripts/mongodb_crud.sh databases --profile prod

List collections in the configured database:

bash <skill-path>/scripts/mongodb_crud.sh collections --profile prod

Find documents:

bash <skill-path>/scripts/mongodb_crud.sh find \
  --profile prod \
  --collection users \
  --filter '{"email":"test@example.com"}' \
  --limit 5

Use --projection and --sort as JSON when needed:

bash <skill-path>/scripts/mongodb_crud.sh find \
  --profile prod \
  --collection orders \
  --filter '{"status":"paid"}' \
  --projection '{"_id":1,"total":1,"createdAt":1}' \
  --sort '{"createdAt":-1}' \
  --limit 20

Count documents:

bash <skill-path>/scripts/mongodb_crud.sh count \
  --profile prod \
  --collection users \
  --filter '{"active":true}'

Write Commands

Dry-run insert first:

bash <skill-path>/scripts/mongodb_crud.sh insert \
  --profile staging \
  --collection users \
  --document '{"email":"test@example.com","active":true}'

Execute only after explicit confirmation:

bash <skill-path>/scripts/mongodb_crud.sh insert \
  --profile staging \
  --collection users \
  --document '{"email":"test@example.com","active":true}' \
  --execute

Dry-run update first:

bash <skill-path>/scripts/mongodb_crud.sh update \
  --profile staging \
  --collection users \
  --filter '{"email":"test@example.com"}' \
  --update '{"$set":{"active":false}}'

Execute only after explicit confirmation:

bash <skill-path>/scripts/mongodb_crud.sh update \
  --profile staging \
  --collection users \
  --filter '{"email":"test@example.com"}' \
  --update '{"$set":{"active":false}}' \
  --execute

Use --many to update or delete multiple documents. Without --many, update and delete affect at most one document.

Dry-run delete first:

bash <skill-path>/scripts/mongodb_crud.sh delete \
  --profile staging \
  --collection sessions \
  --filter '{"userId":"123"}'

Execute only after explicit confirmation:

bash <skill-path>/scripts/mongodb_crud.sh delete \
  --profile staging \
  --collection sessions \
  --filter '{"userId":"123"}' \
  --execute

Raw Eval

Use raw eval for read-only MongoDB JavaScript when structured commands are too limited:

bash <skill-path>/scripts/mongodb_crud.sh raw-eval \
  --profile prod \
  --eval 'EJSON.stringify(db.getSiblingDB("app").users.findOne({email:"test@example.com"}))'

Raw write JavaScript requires both --execute and --allow-raw-write:

bash <skill-path>/scripts/mongodb_crud.sh raw-eval \
  --profile staging \
  --eval 'db.getSiblingDB("app").users.updateOne({email:"test@example.com"}, {$set:{active:false}})' \
  --execute \
  --allow-raw-write

Prefer structured commands when user input contains complex quoting.

Response Shape

Success responses include:

• profile
• mode
• operation
• operation-specific fields such as database, collection, filter, or limit
• dry_run for write previews
• result

Notes

• Use ssh-remote for production-style access where the server already knows MONGODB_URI.
• For ssh-remote, set --remote-cwd when the .env lives inside a project directory on the remote server.
• Use ssh-tunnel when MongoDB is private but commands should run through local mongosh.
• Use direct for local or directly reachable MongoDB.
• Use configure --test-connection when the user wants to confirm saved connection details before relying on a profile.
• For --uri, the script passes the full URI to mongosh, so query parameters such as authSource, replicaSet, tls, or retryWrites are preserved.
• The script parses filters, documents, updates, projections, and sort values with EJSON.parse, so Extended JSON such as {"_id":{"$oid":"..."}} is supported.
• This skill is not a MongoDB migration or backup tool. Do not use it for broad destructive operations unless the user explicitly asks and approves the risk.

Example Prompts

Chinese

• "Configure a MongoDB profile named prod, connect to the server via ssh alias app-prod, after entering /server/app read MONGODB_URI from .env, read-only."
• "Query the users collection in prod, email is test@example.com。"
• "List the collections in the current database of prod."
• "Change active to false for a certain email in the users of staging, dry-run first."

English

• "Configure a readonly MongoDB profile through SSH using the remote MONGODB_URI."
• "Find a user by email using the default MongoDB profile."
• "List collections in the configured database."
• "Preview updating one MongoDB document before executing it."