A Go lang driver for FaunaDB.
Currently, the driver is tested on:
- 1.13
- 1.14
- 1.15
- 1.16
To get the latest version run:
go get github.com/fauna/faunadb-go/v5/faunadb
Please note that our driver undergoes breaking changes from time to time, so depending on our main
branch is not recommended.
It is recommended to use one of the following methods instead:
For better usage, we recommend that you import this driver with an alias import.
To import a specific version when using go get
, use:
import f "github.com/fauna/faunadb-go/v5/faunadb"
package main
import (
"fmt"
f "github.com/fauna/faunadb-go/v5/faunadb"
)
type User struct {
Name string `fauna:"name"`
}
func main() {
client := f.NewFaunaClient("your-secret-here")
res, err := client.Query(f.Get(f.Ref(f.Collection("user"), "42")))
if err != nil {
panic(err)
}
var user User
if err := res.At(f.ObjKey("data")).Get(&user); err != nil {
panic(err)
}
fmt.Println(user)
}
package main
import f "github.com/fauna/faunadb-go/v5/faunadb"
func main() {
secret := ""
dbClient = f.NewFaunaClient(secret)
var ref f.RefV
value, err := dbClient.Query(f.Get(&ref))
if err != nil {
panic(err)
}
err = value.At(f.ObjKey("ref")).Get(&docRef)
var subscription f.StreamSubscription
subscription = dbClient.Stream(docRef)
err = subscription.Start()
if err != nil {
panic("Panic")
}
for a := range subscription.StreamEvents() {
switch a.Type() {
case f.StartEventT:
// do smth on start event
case f.HistoryRewriteEventT:
// do smth on historyRewrite event
case f.VersionEventT:
// do smth on version event
case f.ErrorEventT:
// do smth on error event
subscription.Close() // if you want to close streaming on errors
}
}
}
package main
import f "github.com/fauna/faunadb-go/v5/faunadb"
func main() {
secret := ""
dbClient = f.NewFaunaClient(secret)
var ref f.RefV
value, err := dbClient.Query(f.Get(&ref))
if err != nil {
panic(err)
}
type OmitStruct struct {
Name string `fauna:"name,omitempty"`
Age int `fauna:"age,omitempty"`
Payment float64 `fauna:"payment,omitempty"`
AgePointer *int `fauna:"agePointer,omitempty"`
PaymentPointer *float64 `fauna:"paymentPointer,omitempty"`
}
_, err := dbClient.Query(
f.Create(f.Collection("categories"), f.Obj{"data": OmitStruct{Name: "John", Age: 0}}))
if err != nil {
panic(err)
}
}
Result (empty/zero fields will be ignored):
{
"ref": Ref(Collection("categories"), "295143889346494983"),
"ts": 1617729997710000,
"data": {
"name": "John"
}
}
Driver uses http2 by default. To use http 1.x provide custom http client to FaunaClient
package main
import f "github.com/fauna/faunadb-go/v5/faunadb"
func main() {
secret := ""
customHttpClient := http.Client{}
dbClient = f.NewFaunaClient(secret, f.HTTP(&customHttpClient))
}
For more information about Fauna Query Language (FQL), consult our query language [reference documentation](https://docs.fauna.com/fauna/current/api/fql/).
Specific reference documentation for the driver is hosted at GoDoc.
Most users found tests for the driver as a very useful form of documentation Check it out here.
Since 5.0.0 release, we introduced wrapper types for FaunaError interface, for example:
type InvalidReferenceError struct{ FaunaError }
type MissingIdentityError struct{ FaunaError }
type InvalidTokenError struct{ FaunaError }
type StackOverflowError struct{ FaunaError }
type AuthenticationFailedError struct{ FaunaError }
where each wrapper type returned from an error result according to the error code from fauna database server, you can inspect "errors.go" file for more information on how it is implemented.
You should now notice from your error handling code that the error message has slight changes,
and you are now able to use wrapper names to check the error type,
take a look at the example of handling an error for non-existent collection
that are taken from one of the unit tests (you can see more such examples in "client_test.go"):
_, err := dbClient.Query(
f.Paginate(f.Documents(f.Collection("spells_not_exists"))),
)
if _, ok := err.(f.InvalidReferenceError); !ok {
fmt.Print("Should have returned InvalidReferenceError")
}
// should return: "Response error 400. Errors: [paginate/documents](invalid ref): Ref refers to undefined collection 'spells_not_exists', details: []"
fmt.Print(err)
// you can get some additional info about the error:
specificError := err.(f.InvalidReferenceError)
specificError.HttpStatusCode()
specificError.Errors()[0].Description
specificError.Errors()[0].Position
GitHub pull requests are very welcome.
Run go get -t ./...
in order to install project's dependencies.
Run tests against FaunaDB Cloud by passing your root database key to the
test suite, as follows: FAUNA_ROOT_KEY="your-cloud-secret" go test ./...
.
If you have access to another running FaunaDB database, use the
FAUNA_ENDPOINT
environment variable to specify its URI.
Alternatively, tests can be run via a Docker container with
FAUNA_ROOT_KEY="your-cloud-secret" make docker-test
(an alternate
Debian-based Go image can be provided via RUNTIME_IMAGE
).
Tip: Setting the FAUNA_QUERY_TIMEOUT_MS
environment variable will
set a timeout in milliseconds for all queries.
Copyright 2020 Fauna, Inc.
Licensed under the Mozilla Public License, Version 2.0 (the "License"); you may not use this software except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.