Duckex (duckex v0.1.0)

A naive DuckDB binding for Elixir via Rust port. Provides basic functionality to execute SQL queries against DuckDB, primarily for testing DuckLake functionality.

Summary

Types

attach()
connection_option()
secret()

Functions

attach(conn, path, opts \\ [], conn_opts \\ [])
attach!(conn, path, opts \\ [], conn_opts \\ [])
close(pid, query, opts \\ [])

See DBConnection.close/3.

close!(pid, query, opts \\ [])

See DBConnection.close!/3.

create_secret(conn, name, spec, opts \\ [])
create_secret!(conn, path, spec, opts \\ [])
execute(pid, query, values, opts \\ [])

See DBConnection.execute/4.

execute!(pid, query, values, opts \\ [])

See DBConnection.execute!/4.

install_extensions(extensions, opts \\ [])

Install extensions for DuckDB.

prepare(conn, statement, opts \\ [])

Prepares query.

prepare!(conn, statement, opts \\ [])

Prepares query and returns the prepared query or raises Duckex.Error if there is an error. See prepare/3.

prepare_execute(conn, statement, params, opts \\ [])

Prepares and executes query in the single step.

prepare_execute!(conn, statement, params, opts \\ [])

Prepares and executes query in the single step and returns the prepared query or raises Duckex.Error if there is an error. See prepare_execute/5.

query(conn, statement, params, opts \\ [])
query!(conn, statement, params, opts \\ [])
rollback(conn, reason)

See DBConnection.rollback/2.

start_link(opts \\ [])

Starts the DuckDB process.

transaction(conn, fun, opts \\ [])

See DBConnection.transaction/3.

Types

attach()

@type attach() ::
  {path :: String.t(), keyword()} | {path :: String.t(), keyword(), keyword()}

connection_option()

@type connection_option() :: {:attach, [attach()]} | DBConnection.connection_option()

secret()

@type secret() :: {atom(), keyword()} | {atom(), {keyword(), keyword()}}

Functions

attach(conn, path, opts \\ [], conn_opts \\ [])

attach!(conn, path, opts \\ [], conn_opts \\ [])

close(pid, query, opts \\ [])

See DBConnection.close/3.

close!(pid, query, opts \\ [])

See DBConnection.close!/3.

create_secret(conn, name, spec, opts \\ [])

create_secret!(conn, path, spec, opts \\ [])

execute(pid, query, values, opts \\ [])

See DBConnection.execute/4.

execute!(pid, query, values, opts \\ [])

See DBConnection.execute!/4.

install_extensions(extensions, opts \\ [])

@spec install_extensions([extension], [connection_option()]) :: :ok | {:error, term()}
when extension_opt:
       {:source, :default | :core | :nightly | String.t()} | {:force, boolean()},
     extension: atom() | {atom(), [extension_opt]}

Install extensions for DuckDB.

This will spawn temporary connection and will install extensions within that connection. After that each new DuckDB instance is capable of using that extensions.

It is a helper function to provide a cleaner syntax - extensions use similar syntax to Mix.install/2 and are either:

  • atom containing name of the extension to be installed
  • tuple in form of {atom(), opts}

Options

  • :source - source from which the extension should be installed. Supported options are:
    • :default (used when option is not specified) - uses default registry configured for connection
    • :core
    • :nightly - equivalent of core_nightly from DuckDB
    • String representing URL from which the extension should be installed
  • :force - forcefully install extension, even when it is already installed. Can be used to update extension.

prepare(conn, statement, opts \\ [])

@spec prepare(DBConnection.conn(), String.t(), list()) ::
  {:ok, Duckex.Query.t()} | {:error, Duckex.Error.t()}

Prepares query.

prepare!(conn, statement, opts \\ [])

@spec prepare!(DBConnection.conn(), String.t(), list()) :: Duckex.Query.t()

Prepares query and returns the prepared query or raises Duckex.Error if there is an error. See prepare/3.

prepare_execute(conn, statement, params, opts \\ [])

@spec prepare_execute(DBConnection.conn(), String.t(), list(), list()) ::
  {:ok, Duckex.Query.t(), Duckex.Result.t()} | {:error, Duckex.Error.t()}

Prepares and executes query in the single step.

prepare_execute!(conn, statement, params, opts \\ [])

@spec prepare_execute!(DBConnection.conn(), String.t(), list(), list()) ::
  {Duckex.Query.t(), Duckex.Result.t()}

Prepares and executes query in the single step and returns the prepared query or raises Duckex.Error if there is an error. See prepare_execute/5.

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

@spec query(DBConnection.conn(), String.t(), list(), list()) ::
  {:ok, Duckex.Result.t()} | {:error, Duckex.Error.t()}

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

@spec query!(DBConnection.conn(), String.t(), list(), list()) :: Duckex.Result.t()

rollback(conn, reason)

@spec rollback(DBConnection.t(), reason :: any()) :: no_return()

See DBConnection.rollback/2.

start_link(opts \\ [])

@spec start_link([connection_option()]) :: Supervisor.on_start()

Starts the DuckDB process.

Options

Duckex provides some helper options to setup connection before it is available.

  • :secrets - secrets to be set up before instance is made ready. It is list of tuples where first element is name of secret and second is keyword lists containing secret details.
  • :attach - list of tuples where first element is the attach string and the second one is list of options, optional 3rd element contains connection options, see attach/4.

Secrets are set up before attaching connections, so you can use these secrets for attaching (like S3 secrets).

transaction(conn, fun, opts \\ [])

See DBConnection.transaction/3.