View Source EdgeDB (EdgeDB v0.5.0)

EdgeDB client for Elixir.

EdgeDB module provides an API to run a connection pool, query EdgeDB, perform transactions and subtransactions and their rollback.

A simple example of how to use it:

iex(1)> {:ok, client} = EdgeDB.start_link()
iex(2)> EdgeDB.query!(client, "
...(2)>   select Person{
...(2)>     first_name,
...(2)>     middle_name,
...(2)>     last_name
...(2)>   } filter .last_name = <str>$last_name;
...(2)> ", last_name: "Radcliffe")
#EdgeDB.Set<{#EdgeDB.Object<first_name := "Daniel", middle_name := "Jacob", last_name := "Radcliffe">}>

Link to this section Summary

Types

Connection pool process name, pid or the separate structure that allows adjusted configuration for queries executed on the connection.

Parameters for connecting to an EdgeDB instance and configuring the connection itself.

Options for EdgeDB.query*/4 functions.

A tuple of the executed EdgeDB.Query and the received EdgeDB.Result.

The result that will be returned if the EdgeDB.query*/4 function succeeds.

Security modes for TLS connection to EdgeDB server.

Functions

Mark the client as read-only.

Creates a child specification for the supervisor to start the EdgeDB pool.

Execute an EdgeQL command or commands on the client without returning anything. If an error occurs while executing the query, it will be raised as an EdgeDB.Error exception.

Execute an EdgeQL command or commands on the client without returning anything.

Execute the query on the client and return the results as EdgeDB.Set. If an error occurs while executing the query, it will be raised as as an EdgeDB.Error exception.

Execute the query on the client and return the results as a {:ok, set} tuple if successful, where set is EdgeDB.Set.

Execute the query on the client and return the results as JSON encoded string. If an error occurs while executing the query, it will be raised as as an EdgeDB.Error exception.

Execute the query on the client and return the results as a {:ok, json} tuple if successful, where json is JSON encoded string.

Execute the query on the client and return a singleton-returning result. If an error occurs while executing the query, it will be raised as an EdgeDB.Error exception.

Execute the query on the client and return a singleton-returning result as a {:ok, result} tuple.

Execute the query on the client and return a singleton-returning result as JSON string. If an error occurs while executing the query, it will be raised as an EdgeDB.Error exception.

Execute the query on the client and return a singleton-returning result as a {:ok, json} tuple.

Execute the query on the client and return an optional singleton-returning result. If an error occurs while executing the query, it will be raised as an EdgeDB.Error exception.

Execute the query on the client and return an optional singleton-returning result as a {:ok, result} tuple.

Execute the query on the client and return an optional singleton-returning result as JSON encoded string. If an error occurs while executing the query, it will be raised as an EdgeDB.Error exception.

Execute the query on the client and return an optional singleton-returning result as a {:ok, json} tuple.

Rollback an open transaction or subtransaction.

Creates a pool of EdgeDB connections linked to the current process.

Creates a pool of EdgeDB connections linked to the current process.

Open a subtransaction inside an already open transaction.

Open a subtransaction inside an already open transaction.

Open a retryable transaction loop.

Returns client with adjusted session config.

Returns client with adjusted default module.

Returns client with adjusted global values.

Returns client with adjusted module aliases.

Configure the client so that futher transactions retries are executed with custom retries options.

Returns client with adjusted state.

Configure the client so that futher transactions are executed with custom transaction options.

Returns client without specified session config.

Returns client without specified globals.

Returns client without specified module aliases.

Link to this section Types

@type client() :: DBConnection.conn() | EdgeDB.Client.t()

Connection pool process name, pid or the separate structure that allows adjusted configuration for queries executed on the connection.

See EdgeDB.as_readonly/1, EdgeDB.with_retry_options/2, EdgeDB.with_transaction_options/2 for more information.

@type connect_option() ::
  {:dsn, String.t()}
  | {:credentials, String.t()}
  | {:credentials_file, Path.t()}
  | {:host, String.t()}
  | {:port, :inet.port_number()}
  | {:database, String.t()}
  | {:user, String.t()}
  | {:password, String.t()}
  | {:tls_ca, String.t()}
  | {:tls_ca_file, Path.t()}
  | {:tls_security, tls_security()}
  | {:timeout, timeout()}
  | {:command_timeout, timeout()}
  | {:server_settings, map()}
  | {:tcp, [:gen_tcp.option()]}
  | {:ssl, [:ssl.tls_client_option()]}
  | {:transaction, [EdgeDB.Client.transaction_option()]}
  | {:retry, [EdgeDB.Client.retry_option()]}
  | {:codecs, [module()]}
  | {:connection, module()}
  | {:pool, module()}
  | {:max_concurrency, pos_integer()}
  | {:state, EdgeDB.State.t()}

Parameters for connecting to an EdgeDB instance and configuring the connection itself.

EdgeDB clients allow a very flexible way to define how to connect to an instance. For more information, see the official EdgeDB documentation on connection parameters.

Supported options:

  • :dsn - DSN that defines the primary information that can be used to connect to the instance.
  • :credentials - a JSON string containing the instance parameters to connect.
  • :credentials_file - the path to the instance credentials file containing the instance parameters to connect to.
  • :host - the host name of the instance to connect to.
  • :port - the port number of the instance to connect to.
  • :database - the name of the database to connect to.
  • :user - the user name to connect to.
  • :password - the user password to connect.
  • :tls_ca - TLS certificate to be used when connecting to the instance.
  • :tls_ca_path - the path to the TLS certificate to be used when connecting to the instance.
  • :tls_security - security mode for the TLS connection. See tls_security/0.
  • :timeout - timeout for TCP operations with the database, such as connecting to it, sending or receiving data.
  • :command_timeout - not in use right now and added for compatibility with the official clients.
  • :server_settings - not in use right now and added for compatibility with the official clients.
  • :tcp - options for the TCP connection.
  • :ssl - options for TLS connection.
  • :transaction - options for EdgeDB transactions, which correspond to the EdgeQL transaction statement. See EdgeDB.Client.transaction_option/0.
  • :retry - options to retry transactions in case of errors. See t:retry_option/0.
  • :codecs - list of custom codecs for EdgeDB scalars.
  • :connection - module that implements the DBConnection behavior for EdgeDB. For tests, it's possible to use EdgeDB.Sandbox to support automatic rollback after tests are done.
  • :pool - module that will be used as pool for connections. By default EdgeDB.Pool will be used.
  • :max_concurrency - maximum number of pool connections, despite what EdgeDB recommends. Thise option take effect only if EdgeDB.Pool is used as a pool, which is the default.
  • :state - an EdgeDB.State struct that will be used in queries by default.
@type query_option() ::
  {:cardinality, EdgeDB.Protocol.Enums.cardinality()}
  | {:output_format, EdgeDB.Protocol.Enums.output_format()}
  | {:retry, [EdgeDB.Client.retry_option()]}
  | {:raw, boolean()}
  | {:script, boolean()}
  | DBConnection.option()

Options for EdgeDB.query*/4 functions.

These options can be used with the following functions:

Supported options:

  • :cardinality - expected number of items in set.
  • :output_format - preferred format of query result.
  • :retry - options for read-only queries retries.
  • :raw - flag to return internal client structures for inspecting.
  • other - check DBConnection.start_option/0.
@type raw_result() :: {EdgeDB.Query.t(), EdgeDB.Result.t()}

A tuple of the executed EdgeDB.Query and the received EdgeDB.Result.

This tuple can be useful if you want to get the internal structures of the client and inspect them, but in most cases you will not use it.

@type result() :: EdgeDB.Set.t() | term() | raw_result()

The result that will be returned if the EdgeDB.query*/4 function succeeds.

@type rollback_option() :: {:reason, term()} | {:continue, boolean()}

Options for EdgeDB.rollback/2.

Supported options:

  • :reason - the reason for the rollback. Will be returned from EdgeDB.transaction/3 or EdgeDB.subtransaction/2 as a {:error, reason} tuple in case block execution is interrupted.
  • :continue - can be used when the client is in a subtransaction and rollback should not stop further execution of the subtransaction block. See EdgeDB.subtransaction/2.
@type start_option() :: connect_option() | DBConnection.start_option()

Options for EdgeDB.start_link/1.

See connect_option/0 and DBConnection.start_option/0.

@type tls_security() :: :insecure | :no_host_verification | :strict | :default

Security modes for TLS connection to EdgeDB server.

For more information, see the official EdgeDB documentation on connection parameters.

Supported options:

  • :insecure - trust a self-signed or user-signed TLS certificate, which is useful for local development.
  • :no_host_verification - verify the TLS certificate, but not the host name.
  • :strict - verify both the TLS certificate and the hostname.
  • :default - the same as :strict.
@type transaction_option() ::
  EdgeDB.Client.transaction_option()
  | {:retry, [EdgeDB.Client.retry_option()]}
  | DBConnection.option()

Options for EdgeDB.transaction/3.

See t:edgedb_transaction_option/0 and DBConnection.start_option/0.

Link to this section Functions

@spec as_readonly(client()) :: client()

Mark the client as read-only.

This function will mark the client as read-only, so any modifying queries will return errors.

@spec child_spec([start_option()]) :: Supervisor.child_spec()

Creates a child specification for the supervisor to start the EdgeDB pool.

See start_option/0 for supported connection options.

Link to this function

execute!(client, statement, params \\ [], opts \\ [])

View Source
@spec execute!(client(), String.t(), list(), [query_option()]) :: :ok

Execute an EdgeQL command or commands on the client without returning anything. If an error occurs while executing the query, it will be raised as an EdgeDB.Error exception.

See query_option/0 for supported options.

Link to this function

execute(client, statement, params \\ [], opts \\ [])

View Source
@spec execute(client(), String.t(), list(), [query_option()]) ::
  :ok | {:error, Exception.t()}

Execute an EdgeQL command or commands on the client without returning anything.

See query_option/0 for supported options.

Link to this function

query!(client, statement, params \\ [], opts \\ [])

View Source
@spec query!(client(), String.t(), list(), [query_option()]) :: result()

Execute the query on the client and return the results as EdgeDB.Set. If an error occurs while executing the query, it will be raised as as an EdgeDB.Error exception.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

query(client, statement, params \\ [], opts \\ [])

View Source
@spec query(client(), String.t(), list() | Keyword.t(), [query_option()]) ::
  {:ok, result()} | {:error, Exception.t()}

Execute the query on the client and return the results as a {:ok, set} tuple if successful, where set is EdgeDB.Set.

iex(1)> {:ok, client} = EdgeDB.start_link()
iex(2)> {:ok, %EdgeDB.Set{} = set} = EdgeDB.query(client, "select 42")
iex(3)> set
#EdgeDB.Set<{42}>

If an error occurs, it will be returned as a {:error, exception} tuple where exception is EdgeDB.Error.

iex(1)> {:ok, client} = EdgeDB.start_link()
iex(2)> {:error, %EdgeDB.Error{} = error} = EdgeDB.query(client, "select UndefinedType")
iex(2)> raise error
** (EdgeDB.Error) InvalidReferenceError: object type or alias 'default::UndefinedType' does not exist

If a query has arguments, they can be passed as a list for a query with positional arguments or as a list of keywords for a query with named arguments.

iex(1)> {:ok, client} = EdgeDB.start_link()
iex(2)> {:ok, %EdgeDB.Set{} = set} = EdgeDB.query(client, "select <int64>$0", [42])
iex(3)> set
#EdgeDB.Set<{42}>
iex(1)> {:ok, client} = EdgeDB.start_link()
iex(2)> {:ok, %EdgeDB.Set{} = set} = EdgeDB.query(client, "select <int64>$arg", arg: 42)
iex(3)> set
#EdgeDB.Set<{42}>

automatic-retries-of-read-only-queries

Automatic retries of read-only queries

If the client is able to recognize the query as a read-only query (i.e. the query does not change the data in the database using delete, insert or other statements), then the client will try to repeat the query automatically (as long as the query is not executed in a transaction, because then retrying transactions are used).

See query_option/0 for supported options.

Link to this function

query_json!(client, statement, params \\ [], opts \\ [])

View Source
@spec query_json!(client(), String.t(), list(), [query_option()]) :: result()

Execute the query on the client and return the results as JSON encoded string. If an error occurs while executing the query, it will be raised as as an EdgeDB.Error exception.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

query_json(client, statement, params \\ [], opts \\ [])

View Source
@spec query_json(client(), String.t(), list(), [query_option()]) ::
  {:ok, result()} | {:error, Exception.t()}

Execute the query on the client and return the results as a {:ok, json} tuple if successful, where json is JSON encoded string.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

query_required_single!(client, statement, params \\ [], opts \\ [])

View Source
@spec query_required_single!(client(), String.t(), list(), [query_option()]) ::
  result()

Execute the query on the client and return a singleton-returning result. If an error occurs while executing the query, it will be raised as an EdgeDB.Error exception.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

query_required_single(client, statement, params \\ [], opts \\ [])

View Source
@spec query_required_single(client(), String.t(), list(), [query_option()]) ::
  {:ok, result()} | {:error, Exception.t()}

Execute the query on the client and return a singleton-returning result as a {:ok, result} tuple.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

query_required_single_json!(client, statement, params \\ [], opts \\ [])

View Source
@spec query_required_single_json!(client(), String.t(), list(), [query_option()]) ::
  result()

Execute the query on the client and return a singleton-returning result as JSON string. If an error occurs while executing the query, it will be raised as an EdgeDB.Error exception.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

query_required_single_json(client, statement, params \\ [], opts \\ [])

View Source
@spec query_required_single_json(client(), String.t(), list(), [query_option()]) ::
  {:ok, result()} | {:error, Exception.t()}

Execute the query on the client and return a singleton-returning result as a {:ok, json} tuple.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

query_single!(client, statement, params \\ [], opts \\ [])

View Source
@spec query_single!(client(), String.t(), list(), [query_option()]) :: result()

Execute the query on the client and return an optional singleton-returning result. If an error occurs while executing the query, it will be raised as an EdgeDB.Error exception.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

query_single(client, statement, params \\ [], opts \\ [])

View Source
@spec query_single(client(), String.t(), list(), [query_option()]) ::
  {:ok, result()} | {:error, Exception.t()}

Execute the query on the client and return an optional singleton-returning result as a {:ok, result} tuple.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

query_single_json!(client, statement, params \\ [], opts \\ [])

View Source
@spec query_single_json!(client(), String.t(), list(), [query_option()]) :: result()

Execute the query on the client and return an optional singleton-returning result as JSON encoded string. If an error occurs while executing the query, it will be raised as an EdgeDB.Error exception.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

query_single_json(client, statement, params \\ [], opts \\ [])

View Source
@spec query_single_json(client(), String.t(), list(), [query_option()]) ::
  {:ok, result()} | {:error, Exception.t()}

Execute the query on the client and return an optional singleton-returning result as a {:ok, json} tuple.

For the general usage, see EdgeDB.query/4.

See query_option/0 for supported options.

Link to this function

rollback(client, opts \\ [])

View Source
@spec rollback(EdgeDB.Client.t(), [rollback_option()]) :: :ok | no_return()

Rollback an open transaction or subtransaction.

By default EdgeDB.rollback/2 will abort the transaction/subtransaction function and return to the external scope. But subtransactions can skip this behavior and continue executing after the rollback using the :continue option.

See rollback_option/0 for supported options.

iex(1)> {:ok, client} = EdgeDB.start_link()
iex(2)> {:error, :tx_rollback} =
...(2)>  EdgeDB.transaction(client, fn tx_conn ->
...(2)>   EdgeDB.rollback(tx_conn, reason: :tx_rollback)
...(2)>  end)
iex(1)> {:ok, client} = EdgeDB.start_link()
iex(2)> {:error, :subtx_rollback} =
...(2)>  EdgeDB.transaction(client, fn tx_conn ->
...(2)>   {:error, reason} =
...(2)>     EdgeDB.subtransaction(tx_conn, fn subtx_conn ->
...(2)>      EdgeDB.rollback(subtx_conn, reason: :subtx_rollback)
...(2)>     end)
...(2)>    EdgeDB.rollback(tx_conn, reason: reason)
...(2)>  end)
iex(1)> {:ok, client} = EdgeDB.start_link()
iex(2)> {:ok, 42} =
...(2)>  EdgeDB.transaction(client, fn tx_conn ->
...(2)>   {:ok, result} =
...(2)>     EdgeDB.subtransaction(tx_conn, fn subtx_conn ->
...(2)>      EdgeDB.rollback(subtx_conn, continue: true)
...(2)>      EdgeDB.query_required_single!(subtx_conn, "select 42")
...(2)>     end)
...(2)>   result
...(2)>  end)
@spec start_link(String.t()) :: GenServer.on_start()
@spec start_link([start_option()]) :: GenServer.on_start()

Creates a pool of EdgeDB connections linked to the current process.

If the first argument is a string, it will be assumed to be the DSN and passed as [dsn: dsn] keyword list to connect.

iex(1)> {:ok, _client} = EdgeDB.start_link("edgedb://edgedb:edgedb@localhost:5656/edgedb")

Otherwise, if the first argument is a list, it will be used as is to connect. See start_option/0 for supported connection options.

iex(1)> {:ok, _client} = EdgeDB.start_link(instance: "edgedb_elixir")
@spec start_link(String.t(), [start_option()]) :: GenServer.on_start()

Creates a pool of EdgeDB connections linked to the current process.

The first argument is the string which will be assumed as the DSN and passed as [dsn: dsn] keyword list along with other options to connect. See start_option/0 for supported connection options.

iex(1)> {:ok, _client} = EdgeDB.start_link("edgedb://edgedb:edgedb@localhost:5656/edgedb", tls_security: :insecure)
Link to this function

subtransaction!(client, callback)

View Source
@spec subtransaction!(client(), (EdgeDB.Client.t() -> result())) :: result()

Open a subtransaction inside an already open transaction.

If an error in subtransaction occurs then subtransaction will automatically rollback.

See EdgeDB.subtransaction/2 for more information.

Link to this function

subtransaction(client, callback)

View Source
@spec subtransaction(client(), (EdgeDB.Client.t() -> result())) ::
  {:ok, result()} | {:error, term()}

Open a subtransaction inside an already open transaction.

The result of the subtransaction is the {:ok, result} tuple, where result is the result of the callback function executed in the subtransaction.

To rollback an open subtransaction, use EdgeDB.rollback/2. A subtransaction can be rolled back without exiting the subtransaction block. See rollback_option/0.

EdgeDB.subtransaction/2 calls can be nested multiple times. Each new call to EdgeDB.subtransaction/2 will declare a new savepoint for the current transaction.

iex(1)> {:ok, client} = EdgeDB.start_link()
iex(2)> {:ok, tickets} =
...(2)>  EdgeDB.transaction(client, fn tx_conn ->
...(2)>    {:ok, tickets} =
...(2)>      EdgeDB.subtransaction(tx_conn, fn subtx_conn1 ->
...(2)>        {:ok, tickets} =
...(2)>          EdgeDB.subtransaction(subtx_conn1, fn subtx_conn2 ->
...(2)>            EdgeDB.query!(subtx_conn2, "insert Ticket{ number := 2}")
...(2)>            EdgeDB.query!(subtx_conn2, "select Ticket{ number }")
...(2)>          end)
...(2)>        tickets
...(2)>      end)
...(2)>    tickets
...(2)>  end)
iex(3)> tickets
#EdgeDB.Set<{#EdgeDB.Object<number := 2>}>
Link to this function

transaction(client, callback, opts \\ [])

View Source
@spec transaction(client(), (EdgeDB.Client.t() -> result()), [transaction_option()]) ::
  {:ok, result()} | {:error, term()}

Open a retryable transaction loop.

EdgeDB clients support transactions that are robust to network errors, server failure, and some transaction conflicts. For more information see RFC.

The result of the transaction is the {:ok, result} tuple, where result is the result of the callback function executed in the transaction.

To rollback an open transaction, use EdgeDB.rollback/2.

EdgeDB.transaction/3 calls cannot be nested more than once. If you want to start a new transaction inside an already running one, you should use EdgeDB.subtransaction/2, which will declare a new savepoint for the current transaction.

iex(1)> {:ok, client} = EdgeDB.start_link()
iex(2)> {:ok, tickets} = EdgeDB.transaction(client, fn client ->
...(2)>  EdgeDB.query!(client, "insert Ticket{ number := 2}")
...(2)>  EdgeDB.query!(client, "select Ticket")
...(2)> end)
iex(3)> tickets
#EdgeDB.Set<{#EdgeDB.Object<>}>

See transaction_option/0 for supported options.

Link to this function

with_config(client, config \\ %{})

View Source
@spec with_config(client(), %{required(atom()) => term()}) :: client()

Returns client with adjusted session config.

This is equivalent to using the configure session set command.

Link to this function

with_default_module(client, module \\ nil)

View Source
@spec with_default_module(client(), String.t() | nil) :: client()

Returns client with adjusted default module.

This is equivalent to using the set module command, or using the reset module command when giving nil.

Link to this function

with_globals(client, globals \\ %{})

View Source
@spec with_globals(client(), %{required(String.t()) => String.t()}) :: client()

Returns client with adjusted global values.

This is equivalent to using the set global command.

Link to this function

with_module_aliases(client, aliases \\ %{})

View Source
@spec with_module_aliases(client(), %{required(String.t()) => String.t()}) :: client()

Returns client with adjusted module aliases.

This is equivalent to using the set alias command.

Link to this function

with_retry_options(client, opts)

View Source
@spec with_retry_options(client(), [EdgeDB.Client.retry_option()]) :: client()

Configure the client so that futher transactions retries are executed with custom retries options.

See t:retry_option/0 for supported options.

Link to this function

with_state(client, state)

View Source
@spec with_state(client(), EdgeDB.State.t()) :: client()

Returns client with adjusted state.

See EdgeDB.with_default_module/2, EdgeDB.with_module_aliases/2/EdgeDB.without_module_aliases/2, EdgeDB.with_config/2/EdgeDB.without_config/2, EdgeDB.with_globals/2/EdgeDB.without_globals/2 for more information.

Link to this function

with_transaction_options(client, opts)

View Source
@spec with_transaction_options(client(), [EdgeDB.Client.transaction_option()]) ::
  client()

Configure the client so that futher transactions are executed with custom transaction options.

See t:edgedb_transaction_option/0 for supported options.

Link to this function

without_config(client, config_keys \\ [])

View Source
@spec without_config(client(), [atom()]) :: client()

Returns client without specified session config.

This is equivalent to using the configure session reset command.

Link to this function

without_globals(client, global_names \\ [])

View Source
@spec without_globals(client(), [String.t()]) :: client()

Returns client without specified globals.

This is equivalent to using the reset global command.

Link to this function

without_module_aliases(client, aliases \\ [])

View Source
@spec without_module_aliases(client(), [String.t()]) :: client()

Returns client without specified module aliases.

This is equivalent to using the reset alias command.