arangolite

package module
Version: v2.0.3+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 10, 2017 License: MIT Imports: 13 Imported by: 6

README

Arangolite Build Status Coverage Status Code Climate

Arangolite is a lightweight ArangoDB driver for Go.

It focuses on pure AQL querying. See AranGO for a more ORM-like experience.

V2.0.0

Changelog

The new v2.0.0 version is a major evolution. It brings (sadly) some breaking changes and (happily) a lot of improvements:

  • A less awkward API, more focused and I hope, clearer.
  • All the goroutine magic purely and simply deleted.
  • The weird custom logger replaced by a more standard and simple one.
  • Context support allowing request cancellation.
  • JWT support added.
  • More lightweight than ever.
  • Filter generator moved to a separate repository: Arangofilters.

Operations on database clusters are not yet implemented. PRs concerning cluster support would be greatly appreciated.

Migration guide

The API being relatively small, refactoring should take only a few adjustments and find and replaces.

  • Database initialisation has to follow the new API.
  • Core method calls have to be migrated to the new API.
  • The Runnables are moved to the request package (arangolite.NewTransaction -> requests.NewTransaction).
  • A Query is now explicitely AQL (arangolite.NewQuery -> requests.NewAQL, .AddQuery -> .AddAQL).

Installation

To install Arangolite:

go get -u github.com/solher/arangolite

Basic Usage

package main

import (
  "context"
  "fmt"
  "log"

  "github.com/solher/arangolite"
  "github.com/solher/arangolite/requests"
)

type Node struct {
  arangolite.Document
}

func main() {
  ctx := context.Background()

  // We declare the database definition.
  db := arangolite.NewDatabase(
    arangolite.OptEndpoint("http://localhost:8529"),
    arangolite.OptBasicAuth("root", "rootPassword"),
    arangolite.OptDatabaseName("_system"),
  )

  // The Connect method does two things:
  // - Initializes the connection if needed (JWT authentication).
  // - Checks the database connectivity.
  if err := db.Connect(ctx); err != nil {
    log.Fatal(err)
  }

  // We create a new database.
  err := db.Run(ctx, nil, &requests.CreateDatabase{
    Name: "testDB",
    Users: []map[string]interface{}{
      {"username": "root", "passwd": "rootPassword"},
      {"username": "user", "passwd": "password"},
    },
  })
  if err != nil {
    log.Fatal(err)
  }

  // We sign in as the new created user on the new database.
  // We could eventually rerun a "db.Connect()" to confirm the connectivity.
  db.Options(
    arangolite.OptBasicAuth("user", "password"),
    arangolite.OptDatabaseName("testDB"),
  )

  // We create a new "nodes" collection.
  if err := db.Run(ctx, nil, &requests.CreateCollection{Name: "nodes"}); err != nil {
    log.Fatal(err)
  }

  // We declare a new AQL query with options and bind parameters.
  key := "48765564346"
  r := requests.NewAQL(`
    FOR n
    IN nodes
    FILTER n._key == @key
    RETURN n
  `, key).
    Bind("key", key).
    Cache(true).
    BatchSize(500) // The caching feature is unavailable prior to ArangoDB 2.7

  // The Run method returns all the query results of every pages
  // available in the cursor and unmarshal it into the given struct.
  // Cancelling the context cancels every running request. 
  nodes := []Node{}
  if err := db.Run(ctx, &nodes, r); err != nil {
    log.Fatal(err)
  }

  // The Send method gives more control to the user and doesn't follow an eventual cursor.
  // It returns a raw result object.
  result, err := db.Send(ctx, r)
  if err != nil {
    log.Fatal(err)
  }
  nodes = []Node{}
  result.UnmarshalResult(&nodes)

  for result.HasMore() {
    result, err = db.Send(ctx, &requests.FollowCursor{Cursor: result.Cursor()})
    if err != nil {
      log.Fatal(err)
    }
    tmp := []Node{}
    result.UnmarshalResult(&tmp)

    nodes = append(nodes, tmp...)
  }

  fmt.Println(nodes)
}

Document and Edge

// Document represents a basic ArangoDB document
type Document struct {
  // The document handle. Format: ':collection/:key'
  ID string `json:"_id,omitempty"`
  // The document's revision token. Changes at each update.
  Rev string `json:"_rev,omitempty"`
  // The document's unique key.
  Key string `json:"_key,omitempty"`
}

// Edge represents a basic ArangoDB edge
type Edge struct {
  Document
  // Reference to another document. Format: ':collection/:key'
  From string `json:"_from,omitempty"`
  // Reference to another document. Format: ':collection/:key'
  To string `json:"_to,omitempty"`
}

Transactions

Overview

Arangolite provides an abstraction layer to the Javascript ArangoDB transactions.

The only limitation is that no Javascript processing can be manually added inside the transaction. The queries can be connected using the Go templating conventions.

Usage
t := requests.NewTransaction([]string{"nodes"}, nil).
  AddAQL("nodes", `
    FOR n
    IN nodes
    RETURN n
`).
  AddAQL("ids", `
    FOR n
    IN {{.nodes}}
    RETURN n._id
`).
  Return("ids")

ids := []string{}
if err := db.Run(ctx, ids, t); err != nil {
  log.Fatal(err)
}

Graphs

Overview

AQL may be used for querying graph data. But to manage graphs, Arangolite offers a few specific requests:

  • CreateGraph to create a graph.
  • ListGraphs to list available graphs.
  • GetGraph to get an existing graph.
  • DropGraph to delete a graph.
Usage
// Check graph existence.
if err := db.Run(ctx, nil, &requests.GetGraph{Name: "graphName"}); err != nil {
  switch {
  case arangolite.IsErrNotFound(err):
    // If graph does not exist, create a new one.
    edgeDefinitions := []requests.EdgeDefinition{
      {
        Collection: "edgeCollectionName",
        From:       []string{"firstCollectionName"},
        To:         []string{"secondCollectionName"},
      },
    }
    db.Run(ctx, nil, &requests.CreateGraph{Name: "graphName", EdgeDefinitions: edgeDefinitions})
  default:
    log.Fatal(err)
  }
}

// List existing graphs.
list := &requests.GraphList{}
db.Run(ctx, list, &requests.ListGraphs{})
fmt.Printf("Graph list: %v\n", list)

// Destroy the graph we just created, and the related collections.
db.Run(ctx, nil, &requests.DropGraph{Name: "graphName", DropCollections: true})

Error Handling

Errors can be handled using the provided basic testers:

// IsErrInvalidRequest returns true when the database returns a 400.
func IsErrInvalidRequest(err error) bool {
  return HasStatusCode(err, 400)
}

// IsErrUnauthorized returns true when the database returns a 401.
func IsErrUnauthorized(err error) bool {
  return HasStatusCode(err, 401)
}

// IsErrForbidden returns true when the database returns a 403.
func IsErrForbidden(err error) bool {
  return HasStatusCode(err, 403)
}

// IsErrUnique returns true when the error num is a 1210 - ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED.
func IsErrUnique(err error) bool {
  return HasErrorNum(err, 1210)
}

// IsErrNotFound returns true when the database returns a 404 or when the error num is:
// 1202 - ERROR_ARANGO_DOCUMENT_NOT_FOUND
// 1203 - ERROR_ARANGO_COLLECTION_NOT_FOUND
func IsErrNotFound(err error) bool {
  return HasStatusCode(err, 404) || HasErrorNum(err, 1202, 1203)
}

Or manually via the HasStatusCode and HasErrorNum methods.

Contributing

Currently, very few methods of the ArangoDB HTTP API are implemented in Arangolite. Fortunately, it is really easy to add your own by implementing the Runnable interface. You can then use the regular Run and Send methods.

// Runnable defines requests runnable by the Run and Send methods.
// A Runnable library is located in the 'requests' package.
type Runnable interface {
  // The body of the request.
  Generate() []byte
  // The path where to send the request.
  Path() string
  // The HTTP method to use.
  Method() string
}

Please pull request when you implement some new features so everybody can use it.

License

MIT

Documentation

Overview

Package arangolite provides a lightweight ArangoDatabase driver.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetErrorNum

func GetErrorNum(err error) (errorNum int, ok bool)

GetErrorNum returns the database error num encapsulated in the error.

func GetStatusCode

func GetStatusCode(err error) (code int, ok bool)

GetStatusCode returns the status code encapsulated in the error.

func HasErrorNum

func HasErrorNum(err error, errorNum ...int) bool

HasErrorNum returns true when one of the given error num matches the one returned by the database.

func HasStatusCode

func HasStatusCode(err error, statusCode ...int) bool

HasStatusCode returns true when one of the given error status code matches the one returned by the database.

func IsErrForbidden

func IsErrForbidden(err error) bool

IsErrForbidden returns true when the database returns a 403.

func IsErrInvalidRequest

func IsErrInvalidRequest(err error) bool

IsErrInvalidRequest returns true when the database returns a 400.

func IsErrNotFound

func IsErrNotFound(err error) bool

IsErrNotFound returns true when the database returns a 404 or when the error num is: 1202 - ERROR_ARANGO_DOCUMENT_NOT_FOUND 1203 - ERROR_ARANGO_COLLECTION_NOT_FOUND

func IsErrUnauthorized

func IsErrUnauthorized(err error) bool

IsErrUnauthorized returns true when the database returns a 401.

func IsErrUnique

func IsErrUnique(err error) bool

IsErrUnique returns true when the error num is a 1210 - ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED.

Types

type Database

type Database struct {
	// contains filtered or unexported fields
}

Database represents an access to an ArangoDB database.

func NewDatabase

func NewDatabase(opts ...Option) *Database

NewDatabase returns a new Database object.

func (*Database) Connect

func (db *Database) Connect(ctx context.Context) error

Connect setups the database connection and check the connectivity.

func (*Database) Options

func (db *Database) Options(opts ...Option)

Options apply options to the database.

func (*Database) Run

func (db *Database) Run(ctx context.Context, v interface{}, q Runnable) error

Run runs the Runnable, follows the query cursor if any and unmarshal the result in the given object.

func (*Database) Send

func (db *Database) Send(ctx context.Context, q Runnable) (Response, error)

Send runs the Runnable and returns a "raw" Response object.

type Document

type Document struct {
	// The document handle. Format: ':collection/:key'
	ID string `json:"_id,omitempty"`
	// The document's revision token. Changes at each update.
	Rev string `json:"_rev,omitempty"`
	// The document's unique key.
	Key string `json:"_key,omitempty"`
}

Document represents a basic ArangoDB document

type Edge

type Edge struct {
	Document
	// Reference to another document. Format: ':collection/:key'
	From string `json:"_from,omitempty"`
	// Reference to another document. Format: ':collection/:key'
	To string `json:"_to,omitempty"`
}

Edge represents a basic ArangoDB edge

type LogVerbosity

type LogVerbosity int

LogVerbosity is the logging verbosity.

const (
	// LogNone no log output
	LogNone LogVerbosity = iota
	// LogSummary prints a simple summary of the exchanges with the database.
	LogSummary
	// LogDebug prints all the sent and received http requests.
	LogDebug
)

type Logger

type Logger interface {
	Print(v ...interface{})
}

type Option

type Option func(db *Database)

Option sets an option for the database connection.

func OptBasicAuth

func OptBasicAuth(username, password string) Option

OptBasicAuth sets the username and password used to access the database using basic authentication.

func OptDatabaseName

func OptDatabaseName(dbName string) Option

OptDatabaseName sets the name of the targeted database.

func OptEndpoint

func OptEndpoint(endpoint string) Option

OptEndpoint sets the endpoint used to access the database.

func OptHTTPClient

func OptHTTPClient(cli *http.Client) Option

OptHTTPClient sets the HTTP client used to interact with the database. It is also the current solution to set a custom TLS config.

func OptJWTAuth

func OptJWTAuth(username, password string) Option

OptJWTAuth sets the username and password used to access the database using JWT authentication.

func OptLogging

func OptLogging(logger Logger, verbosity LogVerbosity) Option

OptLogging enables logging of the exchanges with the database.

type Response

type Response interface {
	// The raw response from the database.
	Raw() json.RawMessage
	// The raw response result, if present.
	RawResult() json.RawMessage
	// The response HTTP status code.
	StatusCode() int
	// HasMore indicates if a next result page is available.
	HasMore() bool
	// The cursor ID if more result pages are available.
	Cursor() string
	// Unmarshal decodes the response into the given object.
	Unmarshal(v interface{}) error
	// UnmarshalResult decodes the value of the Result field into the given object, if present.
	UnmarshalResult(v interface{}) error
}

Response defines the response returned by the execution of a Runnable.

type Runnable added in v1.2.0

type Runnable interface {
	// The body of the request.
	Generate() []byte
	// The path where to send the request.
	Path() string
	// The HTTP method to use.
	Method() string
}

Runnable defines requests runnable by the Run and Send methods. A Runnable library is located in the 'requests' package.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL