# MongoDB targets
Connect Buddy CI/CD to MongoDB with a reusable target. Run mongosh scripts, seed data, and execute maintenance commands from any pipeline.
MongoDB targets in Buddy let you store the connection to a MongoDB instance once and reuse it across every pipeline that needs to run `mongosh` scripts, seed data, or execute maintenance commands. The target is consumed by the [MongoDB CLI action](/docs/yaml/yaml-actions/mongosh-cli.md) and can be referenced by name, by tag, or inline in YAML.
## How to add a MongoDB target in Buddy
Navigate to the **Targets** tab where all globally defined connections are listed.
Click **New target** and select MongoDB from the dropdown menu.
## MongoDB connection settings
Required fields:
- **Name** - human-readable target name; the unique ID is generated automatically and can be edited.
- **Scope** - defines which pipelines have [access](/docs/targets/target-scope.md) to the target.
- **Host** - hostname or IP of the MongoDB server (e.g. `mongo.example.com`).
- **Port** - MongoDB server port. Default: `27017`.
- **Database** - default database name.
- **Username & Password** - MongoDB authentication credentials.
Optional fields:
- **Auth source** - the authentication database. If not set, the target database is used. The most common value is `admin`, which is where MongoDB stores users created without `db.createUser` on a specific database.
- **Proxy** - an SSH target used to tunnel traffic to a private MongoDB server (useful for replica sets behind a bastion host).
- **Tags** - labels used to group and match targets.
Fields like `Host`, `Username`, `Password`, and `Database` can use [custom variables](/docs/pipelines/variables.md) defined at the workspace, project, or pipeline level. This keeps secrets out of YAML and lets you switch between environments by overriding the variable set.
## Testing the MongoDB connection
Before saving, use **Test connection** to verify the credentials and network access. The test connects from a Buddy runner to the host and port you provided, authenticates against the configured `Auth source`, and selects the target database. If the test fails, see [Troubleshooting](#troubleshooting-mongodb-connection-errors) below.
## Using the MongoDB target in YAML pipelines
Reference the target by ID in a [MongoDB CLI action](/docs/yaml/yaml-actions/mongosh-cli.md):
```yaml
- pipeline: "Seed staging database"
trigger_mode: ON_EVERY_PUSH
actions:
- action: "Seed users collection"
type: "MONGOSH_CLI"
target: "mongo-staging"
execute_commands:
- "db.users.deleteMany({})"
execute_files:
- "fixtures/users.js"
```
You can also define the target inline if you do not want to manage it in the UI:
```yaml
- action: "Smoke query"
type: "MONGOSH_CLI"
targets:
- target: "mongo-staging"
type: "MONGODB"
host: "mongo.example.com"
port: 27017
database: "$MONGO_DB"
auth_source: "admin"
username: "$MONGO_USER"
password: "$MONGO_PASSWORD"
execute_commands:
- "db.audit_log.find().sort({ created_at: -1 }).limit(10)"
```
See the [MongoDB CLI YAML reference](/docs/yaml/yaml-actions/mongosh-cli.md) for the full field list.
## Troubleshooting MongoDB connection errors
Most failures fall into one of the categories below.
- **Authentication failed** - wrong `Auth source`. MongoDB looks for the user in `Auth source`, not in the target database. If the user was created in `admin`, set `Auth source` to `admin`; for users created with `db.createUser` on a specific database, use that database name.
- **Connection timeout / host unreachable** - the cluster is not exposed to Buddy runners. Whitelist the [Buddy IP addresses](/docs/troubleshooting/ip-whitelist.md) in MongoDB Atlas Network Access or on your firewall, or route through a [proxy SSH target](/docs/targets/ssh.md#proxy-target).
- **No primary found in replica set** - the host points to a secondary that is not currently primary. Use the replica set seed list or the DNS SRV record (`mongodb+srv://...`) from your MongoDB provider so the driver can elect the primary.
- **Server selection error** - the URI host does not resolve or the port is blocked. Verify with `mongosh` from outside Buddy first.
- **Not authorized on db** - the user authenticates but has no role on the target database. Grant `readWrite` (or the minimum role your pipeline needs) via `db.grantRolesToUser`.
## See also
- [MongoDB CLI action - YAML reference](/docs/yaml/yaml-actions/mongosh-cli.md)
- [Other database targets: MSSQL](/docs/targets/mssql.md), [MySQL](/docs/targets/mysql.md), [PostgreSQL](/docs/targets/postgresql.md)
- [Targets - REST API](/docs/api/targets.md)
- [Custom variables in pipelines](/docs/pipelines/variables.md)
---
Original source: https://buddy.works/docs/targets/mongodb