EdgeDB Go Driver

Package edgedb is the official Go EdgeDB driver. https://www.edgedb.com

Typical usage looks like this:

  1. package main
  3. import (
  4.     "context"
  5.     "log"
  7.     "github.com/edgedb/edgedb-go"
  8. )
  10. func main() {
  11.     ctx := context.Background()
  12.     client, err := edgedb.CreateClient(ctx, edgedb.Options{})
  13.     if err != nil {
  14.         log.Fatal(err)
  15.     }
  16.     defer client.Close()
  18.     var (
  19.         age   int64 = 21
  20.         users []struct {
  21.             ID   edgedb.UUID `edgedb:"id"`
  22.             Name string      `edgedb:"name"`
  23.         }
  24.     )
  26.     query := "SELECT User{name} FILTER .age = <int64>$0"
  27.     err = client.Query(ctx, query, &users, age)
  28.     ...
  29. }

You can also connect to a database using a DSN:

  1. url := "edgedb://edgedb@localhost/edgedb"
  2. client, err := edgedb.CreateClientDSN(ctx, url, opts)

Or you can use Option fields.

  1. opts := edgedb.Options{
  2.     Database:    "edgedb",
  3.     User:        "edgedb",
  4.     Concurrency: 4,
  5. }
  7. client, err := edgedb.CreateClient(ctx, opts)

# Errors

edgedb never returns underlying errors directly. If you are checking for things like context expiration use errors.Is() or errors.As().

  1. err := client.Query(...)
  2. if errors.Is(err, context.Canceled) { ... }

Most errors returned by the edgedb package will satisfy the edgedb.Error interface which has methods for introspecting.

  1. err := client.Query(...)
  3. var edbErr edgedb.Error
  4. if errors.As(err, &edbErr) && edbErr.Category(edgedb.NoDataError){
  5.     ...
  6. }

# Datatypes

The following list shows the marshal/unmarshal mapping between EdgeDB types and go types:

  1. EdgeDB                   Go
  2. ---------                ---------
  3. Set                      []anytype
  4. array<anytype>           []anytype
  5. tuple                    struct
  6. named tuple              struct
  7. Object                   struct
  8. bool                     bool, edgedb.OptionalBool
  9. bytes                    []byte, edgedb.OptionalBytes
  10. str                      string, edgedb.OptionalStr
  11. anyenum                  string, edgedb.OptionalStr
  12. datetime                 time.Time, edgedb.OptionalDateTime
  13. cal::local_datetime      edgedb.LocalDateTime,
  14.                          edgedb.OptionalLocalDateTime
  15. cal::local_date          edgedb.LocalDate, edgedb.OptionalLocalDate
  16. cal::local_time          edgedb.LocalTime, edgedb.OptionalLocalTime
  17. duration                 time.Duration, edgedb.OptionalDuration
  18. cal::relative_duraation  edgedb.RelativeDuration,
  19.                          edgedb.OptionalRelativeDuration
  20. float32                  float32, edgedb.OptionalFloat32
  21. float64                  float64, edgedb.OptionalFloat64
  22. int16                    int16, edgedb.OptionalFloat16
  23. int32                    int32, edgedb.OptionalInt16
  24. int64                    int64, edgedb.OptionalInt64
  25. uuid                     edgedb.UUID, edgedb.OptionalUUID
  26. json                     []byte, edgedb.OptionalBytes
  27. bigint                   *big.Int, edgedb.OptionalBigInt
  29. decimal                  user defined (see Custom Marshalers)

Shape fields that are not required must use optional types for receiving query results. The edgedb.Optional struct can be embedded to make structs optional.

  1. type User Struct {
  2.     edgedb.Optional
  3.     Email string `edgedb:"email"`
  4. }
  6. var result User
  7. err := client.QuerySingle(ctx, `SELECT User { email } LIMIT 0`, $result)
  8. fmt.Println(result.Missing())
  9. // Output: true
  11. err := client.QuerySingle(ctx, `SELECT User { email } LIMIT 1`, $result)
  12. fmt.Println(result.Missing())
  13. // Output: false

# Custom Marshalers

Interfaces for user defined marshaler/unmarshalers are documented in the internal/marshal package.

Usage Example

  1. package edgedb_test
  3. import (
  4.     "context"
  5.     "fmt"
  6.     "log"
  7.     "time"
  9.     "github.com/edgedb/edgedb-go"
  10. )
  12. type User struct {
  13.     ID   edgedb.UUID `edgedb:"id"`
  14.     Name string      `edgedb:"name"`
  15.     DOB  time.Time   `edgedb:"dob"`
  16. }
  18. func Example() {
  19.     opts := edgedb.Options{Concurrency: 4}
  20.     ctx := context.Background()
  21.     db, err := edgedb.CreateClientDSN(ctx, "edgedb://edgedb@localhost/test", opts)
  22.     if err != nil {
  23.         log.Fatal(err)
  24.     }
  25.     defer db.Close()
  27.     // create a user object type.
  28.     err = db.Execute(ctx, `
  29.         CREATE TYPE User {
  30.             CREATE REQUIRED PROPERTY name -> str;
  31.             CREATE PROPERTY dob -> datetime;
  32.         }
  33.     `)
  34.     if err != nil {
  35.         log.Fatal(err)
  36.     }
  38.     // Insert a new user.
  39.     var inserted struct{ id edgedb.UUID }
  40.     err = db.QuerySingle(ctx, `
  41.         INSERT User {
  42.             name := <str>$0,
  43.             dob := <datetime>$1
  44.         }
  45.     `, &inserted, "Bob", time.Date(1984, 3, 1, 0, 0, 0, 0, time.UTC))
  46.     if err != nil {
  47.         log.Fatal(err)
  48.     }
  50.     // Select users.
  51.     var users []User
  52.     args := map[string]interface{}{"name": "Bob"}
  53.     query := "SELECT User {name, dob} FILTER .name = <str>$name"
  54.     err = db.Query(ctx, query, &users, args)
  55.     if err != nil {
  56.         log.Fatal(err)
  57.     }
  59.     fmt.Println(users)
  60. }