DuckdbEx.Port (DuckdbEx v0.2.0)

View Source

Manages the DuckDB CLI process using erlexec.

This module provides a simple wrapper around the DuckDB CLI binary, managing it as an OS process via erlexec. Communication happens through JSON-formatted commands and responses.

Architecture

Instead of using Rust NIFs, we use the DuckDB CLI in JSON mode to communicate with the database:

Elixir Process <--> erlexec <--> DuckDB CLI (JSON mode)

This approach is simpler and avoids the complexity of NIF development while still providing full DuckDB functionality.

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear_last_result(port)
connection_info(port)
execute(port, sql, opts \\ [])

Executes a SQL query and returns the result.

last_result(port)
last_sql(port)
start_link(opts \\ [])

Starts a DuckDB process.

stop(port)

Stops the DuckDB process.

Types

t()

@type t() :: pid()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear_last_result(port)

@spec clear_last_result(t()) :: :ok

connection_info(port)

@spec connection_info(t()) :: map()

execute(port, sql, opts \\ [])

@spec execute(t(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Executes a SQL query and returns the result.

Examples

DuckdbEx.Port.execute(port, "SELECT 1 as num, 'hello' as text")
#=> {:ok, %{columns: ["num", "text"], rows: [{1, "hello"}]}}

last_result(port)

@spec last_result(t()) :: {:ok, map() | nil}

last_sql(port)

@spec last_sql(t()) :: {:ok, String.t() | nil}

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts a DuckDB process.

Options

  • :database - Path to database file or :memory: (default: :memory:)
  • :read_only - Open database in read-only mode (default: false)

Examples

{:ok, port} = DuckdbEx.Port.start_link()
{:ok, port} = DuckdbEx.Port.start_link(database: "/path/to/db.duckdb")

stop(port)

@spec stop(t()) :: :ok

Stops the DuckDB process.