mirror of https://gitee.com/bigwinds/arangodb
149 lines
4.3 KiB
Markdown
149 lines
4.3 KiB
Markdown
---
|
|
layout: default
|
|
description: To use the driver, first fetch the sources into your GOPATH
|
|
---
|
|
|
|
# ArangoDB GO Driver - Getting Started
|
|
|
|
## Supported versions
|
|
|
|
- ArangoDB versions 3.1 and up.
|
|
- Single server & cluster setups
|
|
- With or without authentication
|
|
- Go 1.7 and up.
|
|
|
|
## Go dependencies
|
|
|
|
- None (Additional error libraries are supported).
|
|
|
|
## Configuration
|
|
|
|
To use the driver, first fetch the sources into your GOPATH.
|
|
|
|
```sh
|
|
go get github.com/arangodb/go-driver
|
|
```
|
|
|
|
Using the driver, you always need to create a `Client`.
|
|
The following example shows how to create a `Client` for a single server
|
|
running on localhost.
|
|
|
|
```go
|
|
import (
|
|
"fmt"
|
|
|
|
driver "github.com/arangodb/go-driver"
|
|
"github.com/arangodb/go-driver/http"
|
|
)
|
|
|
|
...
|
|
|
|
conn, err := http.NewConnection(http.ConnectionConfig{
|
|
Endpoints: []string{"http://localhost:8529"},
|
|
})
|
|
if err != nil {
|
|
// Handle error
|
|
}
|
|
c, err := driver.NewClient(driver.ClientConfig{
|
|
Connection: conn,
|
|
})
|
|
if err != nil {
|
|
// Handle error
|
|
}
|
|
```
|
|
|
|
Once you have a `Client` you can access/create databases on the server,
|
|
access/create collections, graphs, documents and so on.
|
|
|
|
The following example shows how to open an existing collection in an existing database
|
|
and create a new document in that collection.
|
|
|
|
```go
|
|
// Open "examples_books" database
|
|
db, err := c.Database(nil, "examples_books")
|
|
if err != nil {
|
|
// Handle error
|
|
}
|
|
|
|
// Open "books" collection
|
|
col, err := db.Collection(nil, "books")
|
|
if err != nil {
|
|
// Handle error
|
|
}
|
|
|
|
// Create document
|
|
book := Book{
|
|
Title: "ArangoDB Cookbook",
|
|
NoPages: 257,
|
|
}
|
|
meta, err := col.CreateDocument(nil, book)
|
|
if err != nil {
|
|
// Handle error
|
|
}
|
|
fmt.Printf("Created document in collection '%s' in database '%s'\n", col.Name(), db.Name())
|
|
```
|
|
|
|
## API design
|
|
|
|
### Concurrency
|
|
|
|
All functions of the driver are stricly synchronous. They operate and only return a value (or error)
|
|
when they're done.
|
|
|
|
If you want to run operations concurrently, use a go routine. All objects in the driver are designed
|
|
to be used from multiple concurrent go routines, except `Cursor`.
|
|
|
|
All database objects (except `Cursor`) are considered static. After their creation they won't change.
|
|
E.g. after creating a `Collection` instance you can remove the collection, but the (Go) instance
|
|
will still be there. Calling functions on such a removed collection will of course fail.
|
|
|
|
### Structured error handling & wrapping
|
|
|
|
All functions of the driver that can fail return an `error` value. If that value is not `nil`, the
|
|
function call is considered to be failed. In that case all other return values are set to their `zero`
|
|
values.
|
|
|
|
All errors are structured using error checking functions named `Is<SomeErrorCategory>`.
|
|
E.g. `IsNotFound(error)` return true if the given error is of the category "not found".
|
|
There can be multiple internal error codes that all map onto the same category.
|
|
|
|
All errors returned from any function of the driver (either internal or exposed) wrap errors
|
|
using the `WithStack` function. This can be used to provide detail stack trackes in case of an error.
|
|
All error checking functions use the `Cause` function to get the cause of an error instead of the error wrapper.
|
|
|
|
Note that `WithStack` and `Cause` are actually variables to you can implement it using your own error
|
|
wrapper library.
|
|
|
|
If you for example use [github.com/pkg/errors](https://github.com/pkg/errors){:target="_blank"},
|
|
you want to initialize to go driver like this:
|
|
|
|
```go
|
|
import (
|
|
driver "github.com/arangodb/go-driver"
|
|
"github.com/pkg/errors"
|
|
)
|
|
|
|
func init() {
|
|
driver.WithStack = errors.WithStack
|
|
driver.Cause = errors.Cause
|
|
}
|
|
```
|
|
|
|
### Context aware
|
|
|
|
All functions of the driver that involve some kind of long running operation or
|
|
support additional options not given as function arguments, have a `context.Context` argument.
|
|
This enables you cancel running requests, pass timeouts/deadlines and pass additional options.
|
|
|
|
In all methods that take a `context.Context` argument you can pass `nil` as value.
|
|
This is equivalent to passing `context.Background()`.
|
|
|
|
Many functions support 1 or more optional (and infrequently used) additional options.
|
|
These can be used with a `With<OptionName>` function.
|
|
E.g. to force a create document call to wait until the data is synchronized to disk,
|
|
use a prepared context like this:
|
|
```go
|
|
ctx := driver.WithWaitForSync(parentContext)
|
|
collection.CreateDocument(ctx, yourDocument)
|
|
```
|