{"id":19454607,"url":"https://github.com/fauna/fauna-go","last_synced_at":"2026-03-06T17:05:55.429Z","repository":{"id":148190567,"uuid":"578763769","full_name":"fauna/fauna-go","owner":"fauna","description":"Go driver for Fauna v10 (current)","archived":false,"fork":false,"pushed_at":"2025-01-28T15:00:04.000Z","size":243,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-25T05:36:29.746Z","etag":null,"topics":["client","clients","database","driver","drivers","fauna","faunadb","go","golang","nosql","nosql-database","serverless"],"latest_commit_sha":null,"homepage":"https://fauna.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fauna.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-12-15T20:35:36.000Z","updated_at":"2025-03-19T19:40:37.000Z","dependencies_parsed_at":"2024-04-08T18:39:02.673Z","dependency_job_id":"a42086c0-6e7b-4d97-a15f-40eb4964e1ba","html_url":"https://github.com/fauna/fauna-go","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/fauna/fauna-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffauna-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffauna-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffauna-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffauna-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fauna","download_url":"https://codeload.github.com/fauna/fauna-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffauna-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30186781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T14:42:24.748Z","status":"ssl_error","status_checked_at":"2026-03-06T14:42:14.925Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","clients","database","driver","drivers","fauna","faunadb","go","golang","nosql","nosql-database","serverless"],"created_at":"2024-11-10T17:10:25.712Z","updated_at":"2026-03-06T17:05:50.417Z","avatar_url":"https://github.com/fauna.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Official Golang Driver for [Fauna v10](https://fauna.com/) (current)\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/fauna/fauna-go)](https://goreportcard.com/report/github.com/fauna/fauna-go)\n[![Go Reference](https://pkg.go.dev/badge/github.com/fauna/fauna-go.svg)](https://pkg.go.dev/github.com/fauna/fauna-go/v3)\n[![License](https://img.shields.io/badge/license-MPL_2.0-blue.svg?maxAge=2592000)](https://raw.githubusercontent.com/fauna/fauna-go/main/LICENSE)\n\nThis driver can only be used with FQL v10, and is not compatible with earlier versions of FQL. To query your databases with earlier API versions, see the [faunadb](https://pkg.go.dev/github.com/fauna/faunadb-go/v4) version.\n\nSee the [Fauna Documentation](https://docs.fauna.com/fauna/current/) for additional information how to configure and query your databases.\n\n## Supported Go Versions\n\nCurrently, the driver is tested on:\n- 1.19\n- 1.20\n- 1.21\n- 1.22\n- 1.23\n\n## API reference\n\nAPI reference documentation for the driver is available on [pkg.go.dev](https://pkg.go.dev/github.com/fauna/fauna-go/v3#section-documentation).\n\n## Using the Driver\n\nFor FQL templates, denote variables with `${}` and pass variables as `map[string]any` to `FQL()`. You can escape a variable with by prepending\nan additional `$`.\n\n### Basic Usage\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/fauna/fauna-go/v3\"\n)\n\nfunc main() {\n\tclient, clientErr := fauna.NewDefaultClient()\n\tif clientErr != nil {\n\t\tpanic(clientErr)\n\t}\n\n\tcreateColl, _ := fauna.FQL(`Collection.create({ name: \"Dogs\" })`, nil)\n\tif _, err := client.Query(createColl); err != nil {\n\t\tpanic(err)\n\t}\n\n\tcreateDog, _ := fauna.FQL(`Dogs.create({ name: ${name}})`, map[string]any{\"name\": \"Scout\"})\n\tres, err := client.Query(createDog)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Println(res.Data.(*fauna.Document).Data[\"name\"])\n}\n```\n\n### Using Structs\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/fauna/fauna-go/v3\"\n)\n\ntype Dog struct {\n\tName string `fauna:\"name\"`\n}\n\nfunc main() {\n\tclient, clientErr := fauna.NewDefaultClient()\n\tif clientErr != nil {\n\t\tpanic(clientErr)\n\t}\n\n\tcreateColl, _ := fauna.FQL(`Collection.create({ name: \"Dogs\" })`, nil)\n\tif _, err := client.Query(createColl); err != nil {\n\t\tpanic(err)\n\t}\n\n\tnewDog := Dog{\"Scout\"}\n\tcreateDog, _ := fauna.FQL(`Dogs.create(${dog})`, map[string]any{\"dog\": newDog})\n\tres, err := client.Query(createDog)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tvar scout Dog\n\tif err := res.Unmarshal(\u0026scout); err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Println(scout.Name)\n}\n```\n\n### Composing Multiple Queries\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/fauna/fauna-go/v3\"\n)\n\nfunc addTwo(x int) *fauna.Query {\n\tq, _ := fauna.FQL(`${x} + 2`, map[string]any{\"x\": x})\n\treturn q\n}\n\nfunc main() {\n\tclient, clientErr := fauna.NewDefaultClient()\n\tif clientErr != nil {\n\t\tpanic(clientErr)\n\t}\n\n\tq, _ := fauna.FQL(`${y} + 4`, map[string]any{\"y\": addTwo(2)})\n\tres, err := client.Query(q)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tdata := res.Data.(int64)\n\tfmt.Println(data) // 8\n}\n```\n\n## Pagination\n\nUse the `Paginate()` method to iterate sets that contain more than one page of results.\n\n`Paginate()` accepts the same query options as `Query()`.\n\nChange the default items per page using FQL's `pageSize()` method.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/fauna/fauna-go/v3\"\n)\n\ntype Product struct {\n\tDescription string `fauna:\"description\"`\n}\n\nfunc main() {\n\tclient, clientErr := fauna.NewDefaultClient()\n\tif clientErr != nil {\n\t\tpanic(clientErr)\n\t}\n\n\t// Adjust `pageSize()` size as needed.\n\tquery, _ := fauna.FQL(`\n\t\tProduct\n\t\t\t.byName(\"limes\")\n\t\t\t.pageSize(2) { description }`, nil)\n\n\tpaginator := client.Paginate(query)\n\tfor {\n\t\tpage, _ := paginator.Next()\n\n\t\tvar pageItems []Product\n\t\tpage.Unmarshal(\u0026pageItems)\n\n\t\tfor _, item := range pageItems {\n\t\t\tfmt.Println(item)\n\t\t}\n\n\t\tif !paginator.HasNext() {\n\t\t\tbreak\n\t\t}\n\t}\n}\n```\n\n## Client Configuration\n\n### Timeouts\n\n#### Query Timeout\n\nThe timeout of each query. This controls the maximum amount of time Fauna will execute your query before marking it failed.\n\n```go\npackage main\n\nimport \"github.com/fauna/fauna-go/v3\"\n\nfunc main() {\n\tclient := fauna.NewClient(\"mysecret\", fauna.Timeouts{QueryTimeout: 20 * time.Second})\n}\n```\n\n#### Client Buffer Timeout\n\nTime beyond `QueryTimeout` at which the client will abort a request if it has not received a response. The default is 5s, which should account for network latency for most clients. The value must be greater than zero. The closer to zero the value is, the more likely the client is to abort the request before the server can report a legitimate response or error.\n\n```go\npackage main\n\nimport \"github.com/fauna/fauna-go/v3\"\n\nfunc main() {\n\tclient := fauna.NewClient(\"mysecret\", fauna.Timeouts{ClientBufferTimeout: 20 * time.Second})\n}\n```\n\n#### Connection Timeout\n\nThe amount of time to wait for the connection to complete.\n\n```go\npackage main\n\nimport \"github.com/fauna/fauna-go/v3\"\n\nfunc main() {\n\tclient := fauna.NewClient(\"mysecret\", fauna.Timeouts{ConnectionTimeout: 10 * time.Second})\n}\n```\n\n#### Idle Connection Timeout\n\nThe maximum amount of time an idle (keep-alive) connection will remain idle before closing itself.\n\n```go\npackage main\n\nimport \"github.com/fauna/fauna-go/v3\"\n\nfunc main() {\n\tclient := fauna.NewClient(\"mysecret\", fauna.Timeouts{IdleConnectionTimeout: 10 * time.Second})\n}\n```\n\n### Retries\n\nBy default the client will automatically retry a query if the request results in an HTTP status code 429. Retries use an exponential backoff. The maximum number of retries and maximum wait time before a retry can be configured on the client.\n\n#### Maximum Attempts\n\nThe maximum number of times the client will try a query. The default is 3.\n\n```go\npackage main\n\nimport \"github.com/fauna/fauna-go/v3\"\n\nfunc main() {\n\tclient := fauna.NewClient(\"mysecret\", fauna.DefaultTimeouts(), fauna.MaxAttempts(1))\n}\n```\n\n#### Maximum Backoff Time\n\nThe maximum amount of time to wait before retrying a query. Retries will use an exponential backoff up to this value. The default is 20 seconds.\n\n```go\npackage main\n\nimport (\n\t\"time\"\n\n\t\"github.com/fauna/fauna-go/v3\"\n)\n\nfunc main() {\n\tclient := fauna.NewClient(\"mysecret\", fauna.DefaultTimeouts(), fauna.MaxBackoff(10 * time.Second))\n}\n```\n\n\n## Event streams\n\nThe driver supports [event streams](https://docs.fauna.com/fauna/current/reference/cdc/#event-streaming).\n\n\n### Start a stream\n\nAn event stream lets you consume events from an [event\nsource](https://docs.fauna.com/fauna/current/learn/cdc/#create-an-event-source)\nas a real-time subscription.\n\nTo get an event source, append\n[`eventSource()`](https://docs.fauna.com/fauna/current/reference/fql-api/schema-entities/set/eventsource/)\nor [`eventsOn()`](https://docs.fauna.com/fauna/current/reference/reference/schema_entities/set/eventsource)\nto a [supported Set](https://docs.fauna.com/fauna/current/reference/cdc/#sets).\n\nTo start and subscribe to the stream, pass a query that produces an event source to `StreamFromQuery()`:\n\n```go\ntype Product struct {\n\tName\t\t\tstring\t`fauna:\"name\"`\n\tDescription\t\tstring\t`fauna:\"description\"`\n\tPrice\t\t\tfloat64\t`fauna:\"price\"`\n}\n\nfunc main() {\n\tclient, clientErr := fauna.NewDefaultClient()\n\tif clientErr != nil {\n\t\tpanic(clientErr)\n\t}\n\n\tstreamQuery, _ := fauna.FQL(\"Product.all().eventSource()\", nil)\n\tevents, err := client.StreamFromQuery(streamQuery)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer events.Close()\n\n\tvar event fauna.Event\n\tfor {\n\t\terr := events.Next(\u0026event)\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tswitch event.Type {\n\t\tcase fauna.AddEvent, fauna.UpdateEvent, fauna.RemoveEvent:\n\t\t\tvar product Product\n\t\t\tif err = event.Unmarshal(\u0026product); err != nil {\n\t\t\t\tpanic(err)\n\t\t\t}\n\t\t\tfmt.Println(product)\n\t\t}\n\t}\n}\n```\n\nIn query results, the driver represents an event source as an `EventSource` value.\n\nTo start a stream from a query result, call `Stream()` and pass the `EventSource`.\nThis lets you output a stream alongside normal query results:\n\n```go\ntype Product struct {\n\tName\t\t\tstring\t`fauna:\"name\"`\n\tDescription\t\tstring\t`fauna:\"description\"`\n\tPrice\t\t\tfloat64\t`fauna:\"price\"`\n}\n\nfunc main() {\n\tclient, clientErr := fauna.NewDefaultClient()\n\tif clientErr != nil {\n\t\tpanic(clientErr)\n\t}\n\n\tdataLoad, _ := fauna.FQL(`\n\t\tlet products = Product.all()\n\t\t{\n\t\t\tProducts: products.toArray(),\n\t\t\tSource: products.eventSource()\n\t\t}\n\t`, nil)\n\n\tdata, err := client.Query(dataLoad)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tqueryResult := struct {\n\t\tProducts []Product\n\t\tSource fauna.EventSource\n\t}{}\n\n\tif err := data.Unmarshal(\u0026queryResult); err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Println(\"Existing products:\")\n\tfor _, product := range queryResult.Products {\n\t\tfmt.Println(product)\n\t}\n\n\tevents, err := client.Stream(queryResult.Source)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer events.Close()\n\n\tfmt.Println(\"Products from streaming:\")\n\tvar event fauna.Event\n\tfor {\n\t\terr := events.Next(\u0026event)\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\t\tswitch event.Type {\n\t\tcase fauna.AddEvent, fauna.UpdateEvent, fauna.RemoveEvent:\n\t\t\tvar product Product\n\t\t\tif err = event.Unmarshal(\u0026product); err != nil {\n\t\t\t\tpanic(err)\n\t\t\t}\n\t\t\tfmt.Println(product)\n\t\t}\n\t}\n}\n```\n\n\n### Stream options\n\nThe [client configuration](#client-configuration) sets default query options for\n`StreamFromQuery()` and `Stream()`. To override these options, see [query options](#query-options).\n\nThe `StreamFromQuery()` and `Stream()` methods accept\n[StreamOptFn](https://pkg.go.dev/github.com/fauna/fauna-go/v3#StreamOptFn)\nfunctions as arguments.\n\nUse `StreamStartTime()` to restart a stream at a specific timestamp:\n\n```go\nstreamQuery, _ := fauna.FQL(`Product.all().eventSource()`, nil)\ntenMinutesAgo := time.Now().Add(-10 * time.Minute)\n\nclient.StreamFromQuery(streamQuery, fauna.StreamOptFn{\n    fauna.StreamStartTime(tenMinutesAgo),\n})\n```\n\nUse `EventCursor()` to resume a stream from an event cursor after a disconnect:\n\n```go\nclient.StreamFromQuery(streamQuery, fauna.StreamOptFn{\n    fauna.EventCursor(\"\u003ccursor\u003e\"),\n})\n```\n\nFor supported functions, see\n[StreamOptFn](https://pkg.go.dev/github.com/fauna/fauna-go/v3#StreamOptFn) in\nthe API reference.\n\n## Event feeds\n\nThe driver supports [event feeds](https://docs.fauna.com/fauna/current/learn/cdc/#event-feeds). See [example](event_feed_example_test.go).\n\n## Debug logging\n\nTo enable debug logging set the `FAUNA_DEBUG` environment variable to an integer for the value of the desired [slog.Level](https://pkg.go.dev/log/slog#Level).\nFor Go versions 1.21 and earlier, the driver uses a [log.Logger](https://pkg.go.dev/log#Logger).\nFor 1.22+, the driver uses the [slog.Logger](https://pkg.go.dev/log/slog#Logger).\nYou can optionally define your own Logger.\nFor an example, see `CustomLogger` in [logging_slog_test.go](logging_slog_test.go).\n\n\u003e [!NOTE]\n\u003e The value of the `Authorization` header is redacted when logging.\n\n## Contributing\n\nGitHub pull requests are very welcome.\n\n## LICENSE\n\nCopyright 2023 [Fauna, Inc.](https://fauna.com/)\n\nLicensed under the Mozilla Public License, Version 2.0 (the\n\"License\"); you may not use this software except in compliance with\nthe License. You may obtain a copy of the License at\n\n[http://mozilla.org/MPL/2.0/](http://mozilla.org/MPL/2.0/)\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\nimplied. See the License for the specific language governing\npermissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffauna%2Ffauna-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffauna%2Ffauna-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffauna%2Ffauna-go/lists"}