View Source EdgeDB (EdgeDB v0.1.0)
EdgeDB driver 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, pid} = EdgeDB.start_link()
iex(2)> EdgeDB.query!(pid, "
...(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
Parameters for connecting to an EdgeDB instance and configuring the connection itself.
Connection process name, pid or the same but wrapped in a separate structure that allows special actions on the connection.
Options for EdgeDB transactions.
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.
Options for transactions and read-only queries retries.
Options for a retry rule for transactions retries.
Options for EdgeDB.rollback/2
.
Options for EdgeDB.start_link/1
.
Security modes for TLS connection to EdgeDB server.
Options for EdgeDB.transaction/3
.
Functions
Mark the connection as read-only.
Creates a child specification for the supervisor to start the EdgeDB pool.
Execute the query on the connection and return the results as a {:ok, set}
tuple
if successful, where set
is EdgeDB.Set
.
Execute the query on the connection 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 connection and return the results as a {:ok, json}
tuple
if successful, where json
is JSON encoded string.
Execute the query on the connection 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 connection and return a singleton-returning result
as a {:ok, result}
tuple.
Execute the query on the connection 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 connection and return a singleton-returning result
as a {:ok, json}
tuple.
Execute the query on the connection 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 connection and return an optional singleton-returning
result as a {:ok, result}
tuple.
Execute the query on the connection 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 connection and return an optional singleton-returning
result as a {:ok, json}
tuple.
Execute the query on the connection 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.
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 retryable transaction loop.
Configure the connection so that futher transactions retries are executed with custom retries options.
Configure the connection so that futher transactions are executed with custom transaction options.
Link to this section Types
Specs
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_transaction_option()]} | {:retry, [retry_option()]} | {:codecs, [module()]}
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. Seetls_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 drivers.:server_settings
- not in use right now and added for compatibility with the official drivers.:tcp
- options for the TCP connection.:ssl
- options for TLS connection.:transaction
- options for EdgeDB transactions, which correspond to the EdgeQL transaction statement. Seeedgedb_transaction_option/0
.:retry
- options to retry transactions in case of errors. Seeretry_option/0
.:codecs
- list of custom codecs for EdgeDB scalars.
Specs
connection() :: DBConnection.conn() | EdgeDB.WrappedConnection.t()
Connection process name, pid or the same but wrapped in a separate structure that allows special actions on the connection.
See EdgeDB.as_readonly/1
, EdgeDB.with_retry_options/2
, EdgeDB.with_transaction_options/2
for more information.
Specs
edgedb_transaction_option() :: {:isolation, :repeatable_read | :serializable} | {:readonly, boolean()} | {:deferrable, boolean()}
Options for EdgeDB transactions.
These options are responsible for building the appropriate EdgeQL statement to start transactions and they correspond to the EdgeQL transaction statement.
Supported options:
:isolation
- If:serializable
is used, the built statement will use theISOLATION SERIALIZABLE
mode. Otherwise, if:repeatable_read
is used, the built statement will use theISOLATION REPEATABLE READ
mode. The default is:repeatable_read
.:readonly
- if set totrue
then the built statement will useREAD ONLY
mode, otherwiseREAD WRITE
will be used. The default isfalse
.:deferrable
- if set totrue
then the built statement will useDEFERRABLE
mode, otherwiseNOT DEFERRABLE
will be used. The default isfalse
.
Specs
query_option() :: {:cardinality, EdgeDB.Protocol.Enums.Cardinality.t()} | {:io_format, EdgeDB.Protocol.Enums.IOFormat.t()} | {:retry, [retry_option()]} | {:raw, boolean()} | DBConnection.option()
Options for EdgeDB.query*/4
functions.
These options can be used with the following functions:
EdgeDB.query/4
EdgeDB.query!/4
EdgeDB.query_single/4
EdgeDB.query_single!/4
EdgeDB.query_required_single/4
EdgeDB.query_required_single!/4
EdgeDB.query_json/4
EdgeDB.query_json!/4
EdgeDB.query_single_json/4
EdgeDB.query_single_json!/4
EdgeDB.query_required_single_json/4
EdgeDB.query_required_single_json!/4
Supported options:
:cardinality
- expected number of items in set.:io_format
- preferred format of query result.:retry
- options for read-only queries retries.:raw
- flag to return internal driver structures for inspecting.- other - check
DBConnection.start_option/0
.
Specs
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 driver and inspect them, but in most cases you will not use it.
Specs
result() :: EdgeDB.Set.t() | term() | raw_result()
The result that will be returned if the EdgeDB.query*/4
function succeeds.
Specs
retry_option() :: {:transaction_conflict, retry_rule()} | {:network_error, retry_rule()}
Options for transactions and read-only queries retries.
See EdgeDB.transaction/3
.
Supported options:
:transaction_conflict
- the rule that will be used in case of any transaction conflict.:network_error
- rule which will be used when any network error occurs on the client.
Specs
retry_rule() :: {:attempts, pos_integer()} | {:backoff, (pos_integer() -> timeout())}
Options for a retry rule for transactions retries.
See EdgeDB.transaction/3
.
Supported options:
:attempts
- the number of attempts to retry the transaction in case of an error.:backoff
- function to determine the backoff before the next attempt to run a transaction.
Specs
Options for EdgeDB.rollback/2
.
Supported options:
:reason
- the reason for the rollback. Will be returned fromEdgeDB.transaction/3
orEdgeDB.subtransaction/2
as a{:error, reason}
tuple in case block execution is interrupted.:continue
- can be used when the connection is in a subtransaction and rollback should not stop further execution of the subtransaction block. SeeEdgeDB.subtransaction/2
.
Specs
start_option() :: connect_option() | DBConnection.start_option()
Options for EdgeDB.start_link/1
.
Specs
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
.
Specs
transaction_option() :: edgedb_transaction_option() | {:retry, [retry_option()]} | DBConnection.option()
Options for EdgeDB.transaction/3
.
See edgedb_transaction_option/0
and DBConnection.start_option/0
.
Link to this section Functions
Specs
as_readonly(connection()) :: connection()
Mark the connection as read-only.
This function will mark the connection as read-only, so any modifying queries will return errors.
Specs
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.
Specs
query(connection(), String.t(), list() | Keyword.t(), [query_option()]) :: {:ok, result()} | {:error, Exception.t()}
Execute the query on the connection and return the results as a {:ok, set}
tuple
if successful, where set
is EdgeDB.Set
.
iex(1)> {:ok, pid} = EdgeDB.start_link()
iex(2)> {:ok, %EdgeDB.Set{} = set} = EdgeDB.query(pid, "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, pid} = EdgeDB.start_link()
iex(2)> {:error, %EdgeDB.Error{} = error} = EdgeDB.query(pid, "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, pid} = EdgeDB.start_link()
iex(2)> {:ok, %EdgeDB.Set{} = set} = EdgeDB.query(pid, "SELECT <int64>$0", [42])
iex(3)> set
#EdgeDB.Set<{42}>
iex(1)> {:ok, pid} = EdgeDB.start_link()
iex(2)> {:ok, %EdgeDB.Set{} = set} = EdgeDB.query(pid, "SELECT <int64>$arg", arg: 42)
iex(3)> set
#EdgeDB.Set<{42}>
Automatic retries of read-only queries
If the driver 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 driver 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.
Specs
query!(connection(), String.t(), list(), [query_option()]) :: result()
Execute the query on the connection 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.
Specs
query_json(connection(), String.t(), list(), [query_option()]) :: {:ok, result()} | {:error, Exception.t()}
Execute the query on the connection 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.
Specs
query_json!(connection(), String.t(), list(), [query_option()]) :: result()
Execute the query on the connection 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.
Specs
query_required_single(connection(), String.t(), list(), [query_option()]) :: {:ok, result()} | {:error, Exception.t()}
Execute the query on the connection 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.
Specs
query_required_single!(connection(), String.t(), list(), [query_option()]) :: result()
Execute the query on the connection 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.
query_required_single_json(conn, statement, params \\ [], opts \\ [])
View SourceSpecs
query_required_single_json(connection(), String.t(), list(), [query_option()]) :: {:ok, result()} | {:error, Exception.t()}
Execute the query on the connection 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.
query_required_single_json!(conn, statement, params \\ [], opts \\ [])
View SourceSpecs
query_required_single_json!(connection(), String.t(), list(), [query_option()]) :: result()
Execute the query on the connection 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.
Specs
query_single(connection(), String.t(), list(), [query_option()]) :: {:ok, result()} | {:error, Exception.t()}
Execute the query on the connection 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.
Specs
query_single!(connection(), String.t(), list(), [query_option()]) :: result()
Execute the query on the connection 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.
Specs
query_single_json(connection(), String.t(), list(), [query_option()]) :: {:ok, result()} | {:error, Exception.t()}
Execute the query on the connection 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.
Specs
query_single_json!(connection(), String.t(), list(), [query_option()]) :: result()
Execute the query on the connection 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.
Specs
rollback(connection(), [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, pid} = EdgeDB.start_link()
iex(2)> {:error, :tx_rollback} =
...(2)> EdgeDB.transaction(pid, fn tx_conn ->
...(2)> EdgeDB.rollback(tx_conn, reason: :tx_rollback)
...(2)> end)
iex(1)> {:ok, pid} = EdgeDB.start_link()
iex(2)> {:error, :subtx_rollback} =
...(2)> EdgeDB.transaction(pid, 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, pid} = EdgeDB.start_link()
iex(2)> {:ok, 42} =
...(2)> EdgeDB.transaction(pid, 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)
Specs
start_link(String.t()) :: GenServer.on_start()
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, _pid} = 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, _pid} = EdgeDB.start_link(instance: "edgedb_elixir")
Specs
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, _pid} = EdgeDB.start_link("edgedb://edgedb:edgedb@localhost:5656/edgedb", tls_security: :insecure)
Specs
subtransaction(DBConnection.conn(), (DBConnection.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, pid} = EdgeDB.start_link()
iex(2)> {:ok, tickets} =
...(2)> EdgeDB.transaction(pid, 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>}>
Specs
subtransaction!(DBConnection.conn(), (DBConnection.conn() -> result())) :: result()
Specs
transaction(connection(), (DBConnection.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, pid} = EdgeDB.start_link()
iex(2)> {:ok, tickets} = EdgeDB.transaction(pid, fn conn ->
...(2)> EdgeDB.query!(conn, "INSERT Ticket{ number := 2}")
...(2)> EdgeDB.query!(conn, "SELECT Ticket")
...(2)> end)
iex(3)> tickets
#EdgeDB.Set<{#EdgeDB.Object<>}>
See transaction_option/0
for supported options.
Specs
with_retry_options(connection(), [retry_option()]) :: connection()
Configure the connection so that futher transactions retries are executed with custom retries options.
See retry_option/0
for supported options.
Specs
with_transaction_options(connection(), [edgedb_transaction_option()]) :: connection()
Configure the connection so that futher transactions are executed with custom transaction options.
See edgedb_transaction_option/0
for supported options.