Go library for parsing and executing MongoDB shell syntax using the native MongoDB driver.

Overview

gomongo parses MongoDB shell commands (e.g., db.users.find()) and executes them using the Go MongoDB driver, eliminating the need for external mongosh CLI.

Installation

go get github.com/bytebase/gomongo

Usage

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/bytebase/gomongo"
    "go.mongodb.org/mongo-driver/v2/bson"
    "go.mongodb.org/mongo-driver/v2/mongo"
    "go.mongodb.org/mongo-driver/v2/mongo/options"
)

func main() {
    ctx := context.Background()

    // Connect to MongoDB
    client, err := mongo.Connect(options.Client().ApplyURI("mongodb://localhost:27017"))
    if err != nil {
        log.Fatal(err)
    }
    defer client.Disconnect(ctx)

    // Create gomongo client
    gc := gomongo.NewClient(client)

    // Execute MongoDB shell commands
    result, err := gc.Execute(ctx, "mydb", `db.users.find({ age: { $gt: 25 } })`)
    if err != nil {
        log.Fatal(err)
    }

    // Result.Value contains []any - type depends on operation
    // For find(), each element is bson.D
    for _, val := range result.Value {
        doc, ok := val.(bson.D)
        if !ok {
            log.Printf("unexpected type %T\n", val)
            continue
        }
        fmt.Printf("%+v\n", doc)
    }

    // For countDocuments(), single element is int64
    countResult, err := gc.Execute(ctx, "mydb", `db.users.countDocuments({})`)
    if err != nil {
        log.Fatal(err)
    }
    count, ok := countResult.Value[0].(int64)
    if !ok {
        log.Fatalf("unexpected type %T\n", countResult.Value[0])
    }
    fmt.Printf("Count: %d\n", count)
}

Execute Options

The Execute method accepts optional configuration:

WithMaxRows

Limit the maximum number of rows returned by find() and countDocuments() operations. This is useful to prevent excessive memory usage or network traffic from unbounded queries.

// Cap results at 1000 rows
result, err := gc.Execute(ctx, "mydb", `db.users.find()`, gomongo.WithMaxRows(1000))

Behavior:

• If the query includes .limit(N), the effective limit is min(N, maxRows)
• Query limit 50 + MaxRows 1000 → returns up to 50 rows
• Query limit 5000 + MaxRows 1000 → returns up to 1000 rows
• aggregate() operations are not affected (use $limit stage instead)

Output Format

Results are returned as native Go types in Result.Value (a []any slice). Use Result.Operation to determine the expected type:

Command Reference

Milestone 1: Read Operations + Utility + Aggregation (Current)

Utility Commands

Read Commands

Cursor Modifiers

Aggregation

Object Constructors

Milestone 2: Write Operations (Current)

Insert Commands

Update Commands

Delete Commands

Atomic Find-and-Modify Commands

Write Operation Options

*Note: wtimeout is parsed but ignored as it's not supported in MongoDB Go driver v2.

Milestone 3: Administrative Operations

Index Management

Collection Management

Database Information

Not Planned

The following categories are recognized but not planned for support:

For deprecated methods (e.g., db.collection.insert(), db.collection.update()), gomongo returns actionable error messages directing users to modern alternatives.

Design Principles

1. No database switching - Database is set at connection time only
2. Not an interactive shell - No cursor iteration, REPL-style commands, or stateful operations
3. Syntax translator, not validator - Arguments pass directly to the Go driver; the server validates
4. Single syntax for constructors - Use ObjectId(), not new ObjectId()
5. Clear error messages - Actionable guidance for unsupported or deprecated syntax