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.
Latest release v0.1.0.
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
}
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=;AccountKey=;TimeoutMs=;Version=;DefaultDb=
AccountEndpoint
: (required) endpoint to access Cosmos DB. For example, the endpoint for Azure Cosmos DB Emulator running on local ishttps://localhost:8081/
.AccountKey
: (required) account key to authenticate.TimeoutMs
: (optional) operation timeout in milliseconds. Default value is10 seconds
if not specified.Version
: (optional) version of Cosmos DB to use. Default value is2018-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) specify the default database used in Cosmos DB operations. AliasDb
can also be used instead ofDefaultDb
.
The REST client supports:
- Database:
Create
,Get
,Delete
andList
. - Collection:
Create
,Replace
,Get
,Delete
andList
. - Document:
Create
,Replace
,Get
,Delete
,Query
andList
.
The database/sql
driver supports:
- Database:
CREATE DATABASE
DROP DATABASE
LIST DATABASES
- Table/Collection:
CREATE 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> |
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> |
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 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.
MIT - see LICENSE.md.