Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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
- Host: GitHub
- URL: https://github.com/btnguyen2k/gocosmos
- Owner: btnguyen2k
- License: mit
- Created: 2020-12-06T07:03:43.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-05-12T05:59:23.000Z (7 months ago)
- Last Synced: 2024-07-31T20:50:46.221Z (5 months ago)
- Language: Go
- Homepage:
- Size: 9.53 MB
- Stars: 22
- Watchers: 4
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-go - gocosmos - REST client and standard `database/sql` driver for Azure Cosmos DB. (Database Drivers / NoSQL Database Drivers)
- awesome-go-extra - gocosmos - 12-06T07:03:43Z|2022-06-15T19:10:02Z| (Generators / NoSQL Database Drivers)
README
# gocosmos
[](https://goreportcard.com/report/github.com/btnguyen2k/gocosmos)
[](https://pkg.go.dev/github.com/btnguyen2k/gocosmos)
[](https://github.com/btnguyen2k/gocosmos/actions)
[](https://codecov.io/gh/btnguyen2k/gocosmos)
[](RELEASE-NOTES.md)
[](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.