Home

Awesome

Please note: this is an EXPERIMENTAL non production package. We do not provide official support for this package. See SUPPORT.md for details.

Our official package azcosmos is ready for production use.

gocosmos

PkgGoDev Actions Status codecov Release Status

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

database/sql driver

Summary of supported SQL statements:

StatementSyntax
Create a new databaseCREATE DATABASE [IF NOT EXISTS] <db-name>
Change database's throughputALTER DATABASE <db-name> WITH RU/MAXRU=<ru>
Delete an existing databaseDROP DATABASE [IF EXISTS] <db-name>
List all existing databasesLIST DATABASES
Create a new collectionCREATE COLLECTION [IF NOT EXISTS] [<db-name>.]<collection-name> <WITH PK=partitionKey>
Change collection's throughputALTER COLLECTION [<db-name>.]<collection-name> WITH RU/MAXRU=<ru>
Delete an existing collectionDROP COLLECTION [IF EXISTS] [<db-name>.]<collection-name>
List all existing collections in a databaseLIST COLLECTIONS [FROM <db-name>]
Insert a new document into collectionINSERT INTO [<db-name>.]<collection-name> ...
Insert or replace a documentUPSERT INTO [<db-name>.]<collection-name> ...
Delete an existing documentDELETE FROM [<db-name>.]<collection-name> WHERE id=<id-value>
Update an existing documentUPDATE [<db-name>.]<collection-name> SET ... WHERE id=<id-value>
Query documents in a collectionSELECT [CROSS PARTITION] ... FROM <collection-name> ... [WITH database=<db-name>]

See supported SQL statements for details.

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

Example usage:

package main

import (
	"database/sql"
	_ "github.com/microsoft/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

Note: line-break is for readability only!

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

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 Data Source Name (for database/sql driver) or the connection string (for REST client). If not specified, default value is AutoId=true.

Known issues

GROUP BY combined with ORDER BY is not supported

Azure Cosmos DB does not support GROUP BY combined with ORDER BY yet. You will receive the following error message:

'ORDER BY' is not supported in presence of GROUP BY.

Cross-partition paging

Cross-partition paging can be done with the OFFSET...LIMIT clause. However, the query is not stable without ORDER BY. The returned results may not be consistent from query to query.

Queries that may consume a large amount of memory

These queries may consume a large amount of memory if executed against a large table:

REST client

See the REST.md file for details.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.