# Mongodb Crud

> Use when the user wants to configure saved MongoDB connection profiles, connect directly or through SSH, inspect databases or collections, find, count, insert, update, or delete documents, run ping checks, or execute guarded MongoDB JavaScript with a Bash script, mongosh, dry-run protections, readonly profiles, local profile storage, SSH tunnel access, or remote-server MongoDB access through a saved .env MONGODB_URI.

- Skill: `finpeakinc/mongodb-crud` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add finpeakinc/mongodb-crud`
- Raw SKILL.md: https://api.skillmd.com/api/skills/finpeakinc/mongodb-crud/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: finpeakinc (https://skillmd.com/u/finpeakinc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/finpeakinc/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:

```text
~/.config/mongodb-crud/profiles/
```

The default profile name is saved at:

```text
~/.config/mongodb-crud/default_profile
```

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

```bash
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
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
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
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
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
bash <skill-path>/scripts/mongodb_crud.sh list-profiles
```

The output is redacted.

### Remove Profile

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

## Read Commands

Ping:

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

List databases:

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

List collections in the configured database:

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

Find documents:

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

## Write Commands

Dry-run insert first:

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

Execute only after explicit confirmation:

```bash
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
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
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

- "配置一个 MongoDB profile，名字叫 prod，通过 ssh alias app-prod 到服务器，进入 /server/app 后读取 .env 的 MONGODB_URI，只读。"
- "查 prod 里的 users collection，email 是 test@example.com。"
- "列出 prod 当前数据库的 collections。"
- "把 staging 的 users 里某个 email 的 active 改成 false，先 dry-run。"

### 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."