README.md

DocumentDB Go

Go driver for Microsoft Azure DocumentDB

Table of contents:

• Get Started
• Examples
• Databases
  • Get
  • Query
  • List
  • Create
  • Replace
  • Delete
• Collections
  • Get
  • Query
  • List
  • Create
  • Delete
• Documents
  • Get
  • Query
  • List
  • Create
  • Replace
  • Delete
• StoredProcedures
  • Get
  • Query
  • List
  • Create
  • Replace
  • Delete
  • Execute
• UserDefinedFunctions
  • Get
  • Query
  • List
  • Create
  • Replace
  • Delete
• Iterator
  • DocumentIterator
• Authentication with Azure AD

Get Started

Installation

$ go get github.com/a8m/documentdb

Add to your project

import (
	"github.com/a8m/documentdb"
)

func main() {
	config := documentdb.NewConfig(&documentdb.Key{
		Key: "master-key",
	})
	client := documentdb.New("connection-url", config)

	// Start using DocumentDB
	dbs, err := client.ReadDatabases()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(dbs)
}

Databases

ReadDatabase

func main() {
	// ...
	db, err := client.ReadDatabase("self_link")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(db.Self, db.Id)
}

QueryDatabases

func main() {
	// ...
	dbs, err := client.QueryDatabases("SELECT * FROM ROOT r")
	if err != nil {
		log.Fatal(err)
	}
	for _, db := range dbs {
		fmt.Println("DB Name:", db.Id)
	}
}

ReadDatabases

func main() {
	// ...
	dbs, err := client.ReadDatabases()
	if err != nil {
		log.Fatal(err)
	}
	for _, db := range dbs {
		fmt.Println("DB Name:", db.Id)
	}
}

CreateDatabase

func main() {
	// ...
	db, err := client.CreateDatabase(`{ "id": "test" }`)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(db)

	// or ...
	var db documentdb.Database
	db.Id = "test"
	db, err = client.CreateDatabase(&db)
}

ReplaceDatabase

func main() {
	// ...
	db, err := client.ReplaceDatabase("self_link", `{ "id": "test" }`)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(db)

	// or ...
	var db documentdb.Database
	db, err = client.ReplaceDatabase("self_link", &db)
}

DeleteDatabase

func main() {
	// ...
	err := client.DeleteDatabase("self_link")
	if err != nil {
		log.Fatal(err)
	}
}

Collections

ReadCollection

func main() {
	// ...
	coll, err := client.ReadCollection("self_link")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(coll.Self, coll.Id)
}

QueryCollections

func main() {
	// ...
	colls, err := client.QueryCollections("db_self_link", "SELECT * FROM ROOT r")
	if err != nil {
		log.Fatal(err)
	}
	for _, coll := range colls {
		fmt.Println("Collection Name:", coll.Id)
	}
}

ReadCollections

func main() {
	// ...
	colls, err := client.ReadCollections("db_self_link")
	if err != nil {
		log.Fatal(err)
	}
	for _, coll := range colls {
		fmt.Println("Collection Name:", coll.Id)
	}
}

CreateCollection

func main() {
	// ...
	coll, err := client.CreateCollection("db_self_link", `{"id": "my_test"}`)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Collection Name:", coll.Id)

	// or ...
	var coll documentdb.Collection
	coll.Id = "test"
	coll, err = client.CreateCollection("db_self_link", &coll)
}

DeleteCollection

func main() {
	// ...
	err := client.DeleteCollection("self_link")
	if err != nil {
		log.Fatal(err)
	}
}

Documents

ReadDocument

type Document struct {
	documentdb.Document
	// Your external fields
	Name    string `json:"name,omitempty"`
	Email   string `json:"email,omitempty"`
}

func main() {
	// ...
	var doc Document
	err = client.ReadDocument("self_link", &doc)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Document Name:", doc.Name)
}

QueryDocuments

type User struct {
	documentdb.Document
	// Your external fields
	Name    string `json:"name,omitempty"`
	Email   string `json:"email,omitempty"`
}

func main() {
	// ...
	var users []User
	_, err = client.QueryDocuments(
        "coll_self_link", 
        documentdb.NewQuery("SELECT * FROM ROOT r WHERE r.name=@name", documentdb.P{"@name", "john"}),
        &users,
    )
	if err != nil {
		log.Fatal(err)
	}
	for _, user := range users {
		fmt.Print("Name:", user.Name, "Email:", user.Email)
	}
}

QueryDocuments with partition key

type User struct {
	documentdb.Document
	// Your external fields
	Name    string `json:"name,omitempty"`
	Email   string `json:"email,omitempty"`
}

func main() {
	// ...
	var users []User
	_, err = client.QueryDocuments(
        "coll_self_link", 
		documentdb.NewQuery(
			"SELECT * FROM ROOT r WHERE r.name=@name AND r.company_id = @company_id", 
			documentdb.P{"@name", "john"}, 
			documentdb.P{"@company_id", "1234"},
		),
		&users,
		documentdb.PartitionKey("1234")
    )
	if err != nil {
		log.Fatal(err)
	}
	for _, user := range users {
		fmt.Print("Name:", user.Name, "Email:", user.Email)
	}
}

ReadDocuments

type User struct {
	documentdb.Document
	// Your external fields
	Name    string `json:"name,omitempty"`
	Email   string `json:"email,omitempty"`
}

func main() {
	// ...
	var users []User
	err = client.ReadDocuments("coll_self_link", &users)
	if err != nil {
		log.Fatal(err)
	}
	for _, user := range users {
		fmt.Print("Name:", user.Name, "Email:", user.Email)
	}
}

CreateDocument

type User struct {
	documentdb.Document
	// Your external fields
	Name    string `json:"name,omitempty"`
	Email   string `json:"email,omitempty"`
}

func main() {
	// ...
	var user User
	// Note: If the `id` is missing(or empty) in the payload it will generate
	// random document id(i.e: uuid4)
	user.Id = "uuid"
	user.Name = "Ariel"
	user.Email = "[email protected]"
	err := client.CreateDocument("coll_self_link", &doc)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print("Name:", user.Name, "Email:", user.Email)
}

ReplaceDocument

type User struct {
	documentdb.Document
	// Your external fields
	IsAdmin bool   `json:"isAdmin,omitempty"`
}

func main() {
	// ...
	var user User
	user.Id = "uuid"
	user.IsAdmin = false
	err := client.ReplaceDocument("doc_self_link", &user)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print("Is Admin:", user.IsAdmin)
}

DeleteDocument

func main() {
	// ...
	err := client.DeleteDocument("doc_self_link")
	if err != nil {
		log.Fatal(err)
	}
}

ExecuteStoredProcedure

func main() {
	// ...
	var docs []Document
	err := client.ExecuteStoredProcedure("sporc_self", [...]interface{}{p1, p2}, &docs)
	if err != nil {
		log.Fatal(err)
	}
	// ...
}

Iterator

DocumentIterator

func main() {
	// ...
	var docs []Document

	iterator := documentdb.NewIterator(
		client, documentdb.NewDocumentIterator("coll_self_link", nil, &docs, documentdb.PartitionKey("1"), documentdb.Limit(1)),
	)

	for iterator.Next() {
		if err := iterator.Error(); err != nil {
			log.Fatal(err)
		}
		fmt.Println(len(docs))
	}    

	// ...
}

Authentication with Azure AD

You can authenticate with Cosmos DB using Azure AD and a service principal, including full RBAC support. To configure Cosmos DB to use Azure AD, take a look at the Cosmos DB documentation.

To use this library with a service principal:

import (
	"github.com/Azure/go-autorest/autorest/adal"
	"github.com/a8m/documentdb"
)

func main() {
	// Azure AD application (service principal) client credentials
	tenantId := "tenant-id"
	clientId := "client-id"
	clientSecret := "client-secret"

	// Azure AD endpoint may be different for sovereign clouds
	oauthConfig, err := adal.NewOAuthConfig("https://login.microsoftonline.com/", tenantId)
	if err != nil {
		log.Fatal(err)
	}
	spt, err := adal.NewServicePrincipalToken(*oauthConfig, clientId, clientSecret, "https://cosmos.azure.com") // Always "https://cosmos.azure.com"
	if err != nil {
		log.Fatal(err)
	}

	config := documentdb.NewConfigWithServicePrincipal(spt)
	client := documentdb.New("connection-url", config)
}

Examples

• Go DocumentDB Example - A users CRUD application using Martini and DocumentDB

License

Distributed under the MIT license, which is available in the file LICENSE.