MongoDB targets

View as Markdown

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

Image loading...

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

Info

Fields like Host, Username, Password, and Database can use custom variables 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 below.

Using the MongoDB target in YAML pipelines

Reference the target by ID in a MongoDB CLI action:

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 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 in MongoDB Atlas Network Access or on your firewall, or route through a proxy SSH 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.