gocosmos

Go driver for Azure CosmosDB SQL API

Programming language: Go

License: MIT License

Tags: Database Drivers     NoSQL Databases    

Latest version: v0.1.6

README

gocosmos

[](RELEASE-NOTES.md)

Go driver for Azure Cosmos DB SQL API which can be used with the standard database/sql package. A REST client for Azure Cosmos DB SQL API is also included.

Example usage: REST client

import (
    "os"
    "database/sql"
    "github.com/btnguyen2k/gocosmos"
)

func main() {
    cosmosDbConnStr := "AccountEndpoint=https://localhost:8081/;AccountKey=<cosmosdb-account-key>"
    client, err := gocosmos.NewRestClient(nil, cosmosDbConnStr)
    if err != nil {
        panic(err)
    }

    dbSpec := gocosmos.DatabaseSpec{Id:"mydb", Ru: 400}
    result := client.CreateDatabase(dbSpec)
    if result.Error() != nil {
        panic(result.Error)
    }

    // database "mydb" has been created successfuly
}

Connection string syntax for Cosmos DB

AccountEndpoint=<cosmosdb-endpoint>;AccountKey=<cosmosdb-account-key>;TimeoutMs=<timeout-in-ms>;Version=<cosmosdb-api-version>;AutoId=<true/false>;InsecureSkipVerify=<true/false>

• AccountEndpoint: (required) endpoint to access Cosmos DB. For example, the endpoint for Azure Cosmos DB Emulator running on local is https://localhost:8081/.
• AccountKey: (required) account key to authenticate.
• TimeoutMs: (optional) operation timeout in milliseconds. Default value is 10 seconds if not specified.
• Version: (optional) version of Cosmos DB to use. Default value is 2018-12-31 if not specified. See: https://docs.microsoft.com/en-us/rest/api/cosmos-db/#supported-rest-api-versions.
• AutoId: (optional, available since [v0.1.2](RELEASE-NOTES.md)) see auto id session.
• InsecureSkipVerify: (optional, available since [v0.1.4](RELEASE-NOTES.md)) if true, disable CA verification for https endpoint (useful to run against test/dev env with local/docker Cosmos DB emulator).

Example usage: database/sql driver

import (
    "database/sql"
    _ "github.com/btnguyen2k/gocosmos"
)

func main() {
    driver := "gocosmos"
    dsn := "AccountEndpoint=https://localhost:8081/;AccountKey=<cosmosdb-account-key>"
    db, err := sql.Open(driver, dsn)
    if err != nil {
        panic(err)
    }
    defer db.Close()

    _, err := db.Exec("CREATE DATABASE mydb WITH maxru=10000")
    if err != nil {
        panic(err)
    }

    // database "mydb" has been created successfuly
}

Data Source Name (DSN) syntax for Cosmos DB

AccountEndpoint=<cosmosdb-endpoint>;AccountKey=<cosmosdb-account-key>;TimeoutMs=<timeout-in-ms>;Version=<cosmosdb-api-version>;DefaultDb=<db-name>;AutoId=<true/false>;InsecureSkipVerify=<true/false>

• AccountEndpoint: (required) endpoint to access Cosmos DB. For example, the endpoint for Azure Cosmos DB Emulator running on local is https://localhost:8081/.
• AccountKey: (required) account key to authenticate.
• TimeoutMs: (optional) operation timeout in milliseconds. Default value is 10 seconds if not specified.
• Version: (optional) version of Cosmos DB to use. Default value is 2018-12-31 if not specified. See: https://docs.microsoft.com/en-us/rest/api/cosmos-db/#supported-rest-api-versions.
• DefaultDb: (optional, available since [v0.1.1](RELEASE-NOTES.md)) specify the default database used in Cosmos DB operations. Alias Db can also be used instead of DefaultDb.
• AutoId: (optional, available since [v0.1.2](RELEASE-NOTES.md)) see auto id session.
• InsecureSkipVerify: (optional, available since [v0.1.4](RELEASE-NOTES.md)) if true, disable CA verification for https endpoint (useful to run against test/dev env with local/docker Cosmos DB emulator).

Auto-id

Azure Cosmos DB requires each document has a unique ID that identifies the document. When creating new document, if value for the unique ID field is not supplied gocosmos is able to generate one automatically. This feature is enabled by specifying setting AutoId=true in the connection string (for REST client) or Data Source Name (for database/sql driver). If not specified, default value is AutoId=true.

This settings is available since [v0.1.2](RELEASE-NOTES.md).

Features

The REST client supports:

• Database: Create, Get, Delete, List and change throughput.
• Collection: Create, Replace, Get, Delete, List and change throughput.
• Document: Create, Replace, Get, Delete, Query and List.

The database/sql driver supports:

• Database:
  • CREATE DATABASE
  • ALTER DATABASE
  • DROP DATABASE
  • LIST DATABASES
• Table/Collection:
  • CREATE TABLE/COLLECTION
  • ALTER TABLE/COLLECTION
  • DROP TABLE/COLLECTION
  • LIST TABLES/COLLECTIONS
• Item/Document:
  • INSERT
  • UPSERT
  • SELECT
  • UPDATE
  • DELETE

Summary of supported SQL statements:

Statement	Syntax
Create a new database	CREATE DATABASE [IF NOT EXISTS] <db-name>
Change database's throughput	ALTER DATABASE <db-name> WITH RU/MAXRU=<ru>
Delete an existing database	DROP DATABASE [IF EXISTS] <db-name>
List all existing databases	LIST DATABASES
Create a new collection	CREATE COLLECTION [IF NOT EXISTS] [<db-name>.]<collection-name> <WITH [LARGE]PK=partitionKey>
Change collection's throughput	ALTER COLLECTION [<db-name>.]<collection-name> WITH RU/MAXRU=<ru>
Delete an existing collection	DROP COLLECTION [IF EXISTS] [<db-name>.]<collection-name>
List all existing collections in a database	LIST COLLECTIONS [FROM <db-name>]
Insert a new document into collection	INSERT INTO [<db-name>.]<collection-name> ...
Insert or replace a document	UPSERT INTO [<db-name>.]<collection-name> ...
Delete an existing document	DELETE FROM [<db-name>.]<collection-name> WHERE id=<id-value>
Update an existing document	UPDATE [<db-name>.]<collection-name> SET ... WHERE id=<id-value>
Query documents in a collection	SELECT [CROSS PARTITION] ... FROM <collection-name> ... [WITH database=<db-name>]

See [supported SQL statements](SQL.md) for details.

Azure Cosmos DB SQL API currently supports only SELECT statement. gocosmos implements other statements by translating the SQL statement to REST API call to Azure Cosmos DB REST API.

License

MIT - see [LICENSE.md](LICENSE.md).