Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/btnguyen2k/gocosmos

Go database/sql driver for Azure Cosmos DB SQL API
https://github.com/btnguyen2k/gocosmos

Last synced: about 2 months ago
JSON representation

Go database/sql driver for Azure Cosmos DB SQL API

Awesome Lists containing this project

README

        

# gocosmos

[![Go Report Card](https://goreportcard.com/badge/github.com/btnguyen2k/gocosmos)](https://goreportcard.com/report/github.com/btnguyen2k/gocosmos)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/btnguyen2k/gocosmos)](https://pkg.go.dev/github.com/btnguyen2k/gocosmos)
[![Actions Status](https://github.com/btnguyen2k/gocosmos/workflows/gocosmos/badge.svg)](https://github.com/btnguyen2k/gocosmos/actions)
[![codecov](https://codecov.io/gh/btnguyen2k/gocosmos/branch/main/graph/badge.svg)](https://codecov.io/gh/btnguyen2k/gocosmos)
[![Release](https://img.shields.io/github/release/btnguyen2k/gocosmos.svg?style=flat-square)](RELEASE-NOTES.md)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#database-drivers)

Go driver for [Azure Cosmos DB SQL API](https://azure.microsoft.com/services/cosmos-db/) which can be used with the standard [database/sql](https://golang.org/pkg/database/sql/) package. A REST client is also included.

## database/sql driver

Summary of supported SQL statements:

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

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

> Azure Cosmos DB SQL API currently supports only [SELECT statement](https://learn.microsoft.com/azure/cosmos-db/nosql/query/select).
> `gocosmos` implements other statements by translating the SQL statement to [REST API calls](https://learn.microsoft.com/rest/api/cosmos-db/).

### Example usage:

```go
package main

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

func main() {
driver := "gocosmos"
dsn := "AccountEndpoint=https://localhost:8081/;AccountKey="
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!_

```connection
AccountEndpoint=
;AccountKey=
[;TimeoutMs=]
[;Version=]
[;DefaultDb|Db=]
[;AutoId=]
[;InsecureSkipVerify=]
```

- `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 `2020-07-15` if not specified. See: https://learn.microsoft.com/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](#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](https://learn.microsoft.com/rest/api/cosmos-db/documents) 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`.

_This setting is available since [v0.1.2](RELEASE-NOTES.md)._

### 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:

- `OFFSET...LIMIT` clause with big offset or limit values.
- `SELECT DISTINCT` and `SELECT DISTINCT VALUE` queries.
- Queries with `GROUP BY` clause.

## REST client

See the [REST.md](REST.md) file for details.

## License

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

## Support and Contribution

> Disclaimer: I am also a core maintainer of [microsoft/gocosmos](https://github.com/microsoft/gocosmos/). Features and bug fixes are synchronized between the two projects.

This project uses [GitHub Issues](https://github.com/btnguyen2k/gocosmos/issues) to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new Issue.

Please create [pull requests](https://github.com/microsoft/gocosmos/pulls) in the [microsoft/gocosmos](https://github.com/microsoft/gocosmos/) repository.

If you find this project useful, please start it.