Skip to content

AGENTS.md

Latest commit

 

History

History
136 lines (96 loc) · 5.52 KB

AGENTS.md

File metadata and controls

136 lines (96 loc) · 5.52 KB

MongoDB Tools — Agent Instructions

Working Style

We prefer that AI agents start by planning their work, documenting their plan as a Markdown file, and then iterating on that plan with the human operator. Don't just jump straight to coding in most cases. For small, well-scoped tasks (e.g., a one or two file change), it's fine to skip the planning step.

Plans should be broken up into multiple steps. For larger projects, the plan should consider how to break the work up into multiple pull requests as well. We prefer PRs to be 200-400 lines. The exception would be a large rename or refactoring (like a type change), where the PR is very large in terms of lines but conceptually small.

When you create a plan, include this in the PR as a comment with an attachment. If the user creates the PR themselves, remind them to include this.

Requirements

The most important thing for these tools is that they must not corrupt or lose user data. This is particularly important for mongodump and mongorestore. When we make changes to these tools, we should ensure that data is preserved via a dump and restore round trip.

Project Overview

This repo contains the official MongoDB command-line tools: bsondump, mongodump, mongorestore, mongoimport, mongoexport, mongostat, mongotop, and mongofiles.

Each tool lives in its own top-level directory (e.g., /mongodump/). Shared utilities are in /common/.

Build

go run build.go build            # build all tools
go run build.go build pkgs=<pkg> # build a specific tool

Binaries are written to ./bin/.

Tests

Tests use environment variables to control which test types run.

go run build.go test:unit                     # unit tests (no mongod required)
go run build.go test:integration              # requires mongod on localhost:33333
go run build.go test:sharded-integration      # requires mongos (sharded cluster)

Optional flags for test:integration: ssl=true, auth=true, topology=replset, race=true.

All tests use testtype.SkipUnlessTestType(t, testtype.XxxTestType) at the top to gate on the relevant env var. When writing new tests, match the existing pattern.

Integration tests default to connecting to localhost:33333. Override with TOOLS_TESTING_MONGOD=<uri>.

Before running integration or sharded integration tests, you must have a MongoDB server or cluster running and accessible. For basic integration tests, start a standalone mongod on port 33333. For sharded integration tests, start a mongos fronting a sharded cluster. These servers are not started automatically by the test runner.

Use mlaunch (from the mtools Python package) to manage clusters during development:

mlaunch init --single --port 33333          # standalone mongod for integration tests
mlaunch init --sharded 1 --port 33333       # sharded cluster for sharded integration tests
mlaunch stop                                 # stop all launched processes
mlaunch start                                # restart previously initialized cluster

Static Analysis

Our static analysis tools are managed locally by mise. Always modify the mise.toml file to add or update tools. But we also manage these in CI via code in buildscript, so this must be updated in sync with the mise.toml file.

go run build.go sa:lint      # runs precious (golangci-lint, gosec, goimports, golines)
go run build.go sa:modtidy   # go mod tidy

Code Conventions

  • Use any instead of interface{}.
  • Avoid comments that describe what code does; only comment on why when the reason isn't obvious.
  • Break large functions into smaller named functions rather than adding explanatory comments.
  • Write test assertion messages that describe what is being tested.
  • New tests should use testify (github.com/stretchr/testify/require and assert). The codebase is actively migrating away from GoConvey — do not add new GoConvey tests.

Linting

Run go run build.go sa:lint to check for lint errors. Ignore LSP diagnostics that are suppressed by .golangci.yml — in particular, bson.E struct literal uses unkeyed fields is explicitly allowed and should not be treated as an error.

Architecture

/common/          shared utilities (auth, db, bsonutil, options, testutil, testtype, …)
/<tool>/          tool implementation
/<tool>/main/     CLI entry point (main package)
/<tool>/options.go  CLI flag definitions
/<tool>/*_test.go   tests co-located with source

Shared connection and session management lives in common/db/. CLI options are parsed via common/options/ using github.com/urfave/cli/v2.

CI

CI runs on Evergreen (config: common.yml). Do not edit common.yml by hand for test topology changes — consult the existing pattern for integration-X.Y and integration-X.Y-sharded task variants.

Minimal Change Principle

Make minimal, incremental changes. Do not refactor surrounding code when fixing a bug or adding a feature. Do not add error handling for scenarios that cannot occur; instead, add a panic to handle that case.

Code in common is Used in Other Projects

The code in common is used by other projects at MongoDB. If you want to modify public APIs in that package, double check with the human directing you before doing this.

Trust These Instructions

These instructions are comprehensive and tested. Only perform additional exploration if:

  • Information here is incomplete for your specific task
  • Instructions are found to be incorrect or outdated
  • You need details about internal implementation not covered here
⚡