Go Client Library

The plugport-go package provides a mongo-go-driver compatible API for Go applications.

Installation

go get github.com/plugport/plugport-go

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    plugport "github.com/plugport/plugport-go"
)

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

    client, err := plugport.Connect("http://localhost:8080")
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    coll := client.Database("myapp").Collection("users")

    // Insert
    result, err := coll.InsertOne(ctx, map[string]interface{}{
        "name":  "Alice",
        "email": "alice@example.com",
        "age":   30,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Inserted: %s\n", result.InsertedID)

    // Find
    docs, err := coll.Find(ctx, map[string]interface{}{
        "age": map[string]interface{}{"$gte": 25},
    })
    if err != nil {
        log.Fatal(err)
    }
    for _, doc := range docs {
        fmt.Printf("Found: %v\n", doc["name"])
    }
}

API Reference

Connect(uri string, opts ...ClientOptions) (*Client, error)

// Basic
client, err := plugport.Connect("http://localhost:8080")

// With options
client, err := plugport.Connect("http://localhost:8080", plugport.ClientOptions{
    APIKey:  "your-key",
    Timeout: 30 * time.Second,
})

Client

Method	Description
Database(name)	Get a *Database handle
Health(ctx)	Get server health
Close()	Close the connection

Database

Method	Description
Collection(name)	Get a *Collection handle
ListCollectionNames(ctx)	List collection names

Collection

Insert

// Single document
result, err := coll.InsertOne(ctx, doc)
// result.InsertedID, result.InsertedCount

// Multiple documents
result, err := coll.InsertMany(ctx, []interface{}{doc1, doc2})
// result.InsertedCount

Find

// Basic find
docs, err := coll.Find(ctx, filter)

// With options
docs, err := coll.Find(ctx, filter, plugport.FindOptions{
    Limit:      10,
    Skip:       0,
    Sort:       map[string]int{"age": -1},
    Projection: map[string]int{"name": 1, "age": 1},
})

// Find one
doc, err := coll.FindOne(ctx, filter)

Aggregate

Execute an aggregation pipeline. Supported stages: $match, $lookup, $project, $sort, $limit, $skip, $unwind, $count.

results, err := coll.Aggregate(ctx, []map[string]interface{}{
    {"$match": map[string]interface{}{"status": "completed"}},
    {"$lookup": map[string]interface{}{
        "from":         "users",
        "localField":   "userId",
        "foreignField": "_id",
        "as":           "user",
    }},
    {"$unwind": "$user"},
    {"$sort": map[string]interface{}{"total": -1}},
    {"$limit": 10},
})
for _, doc := range results {
    fmt.Println(doc)
}

Update

result, err := coll.UpdateOne(ctx, filter, update)
// result.MatchedCount, result.ModifiedCount

// With upsert
result, err := coll.UpdateOne(ctx, filter, update, plugport.UpdateOptions{
    Upsert: true,
})

Delete

result, err := coll.DeleteOne(ctx, filter)
// result.DeletedCount

result, err := coll.DeleteMany(ctx, filter)

Indexes

name, err := coll.CreateIndex(ctx, "email", true) // unique
err = coll.Drop(ctx)

RBAC (Access Control)

// Grant read access (role: 1 = read, 2 = write)
_, err := coll.GrantRole(ctx, "0xabc...", 1)

// Revoke access
_, err := coll.RevokeRole(ctx, "0xabc...")

Error Handling

result, err := coll.InsertOne(ctx, doc)
if err != nil {
    var plugportErr *plugport.PlugPortError
    if errors.As(err, &plugportErr) {
        fmt.Printf("Code: %d, Message: %s\n", plugportErr.Code, plugportErr.Message)
    }
}

Migration from mongo-go-driver

- import "go.mongodb.org/mongo-driver/mongo"
- import "go.mongodb.org/mongo-driver/mongo/options"
+ import plugport "github.com/plugport/plugport-go"

- client, err := mongo.Connect(ctx, options.Client().ApplyURI("mongodb://localhost:27017"))
+ client, err := plugport.Connect("http://localhost:8080")

  coll := client.Database("myapp").Collection("users")
  // All CRUD operations use the same API