AshClickhouse.Connection (AshClickhouse v0.4.0)

Process wrapper around the clickhouse client connection.

A connection is a named process that holds the configuration for a ClickHouse database. Queries are dispatched through this module so that the rest of the data layer does not need to know the details of the underlying client.

Options

:name — register the connection under this name (atom)
:url — the ClickHouse HTTP URL, e.g. "http://localhost:8123"
:username / :password — credentials
:database — the default database
:otp_app — application to read config from (used by AshClickhouse.Repo)

The clickhouse client is started as a supervised GenServer. We keep a thin wrapper so that the data layer can resolve a connection by name and run queries with consistent error handling.

Summary

Types

t()

Functions

child_spec(opts)

Returns the child spec for a connection (for supervision trees).

database_for(name)

Returns the configured database for a connection (by name, struct, or pid), or nil if unknown. Used to thread the database into per-query opts without baking it into the connection URL.

get_conn(name \\ __MODULE__)

Returns the connection struct registered under name, if any.

insert_rows(conn_or_name, table, statement, rows, opts \\ [])

Inserts rows into a table using the client's bulk insert helper.

query(conn_or_name, sql, params \\ [], opts \\ [])

Runs a SQL query against ClickHouse.

query!(conn_or_name, sql, params \\ [], opts \\ [])

Runs a SQL query, raising on error.

start_link(opts)

Starts a ClickHouse connection as part of a supervision tree.

stop(name)

Stops the connection.

Types

t()

@type t() :: %AshClickhouse.Connection{
  conn: pid() | atom(),
  database: String.t() | nil,
  name: atom() | nil,
  pid: pid() | nil
}

Functions

child_spec(opts)

@spec child_spec(keyword()) :: Supervisor.child_spec()

Returns the child spec for a connection (for supervision trees).

database_for(name)

@spec database_for(t() | atom() | pid()) :: String.t() | nil

Returns the configured database for a connection (by name, struct, or pid), or nil if unknown. Used to thread the database into per-query opts without baking it into the connection URL.

get_conn(name \\ MODULE)

@spec get_conn(atom()) :: t() | nil

Returns the connection struct registered under name, if any.

insert_rows(conn_or_name, table, statement, rows, opts \\ [])

@spec insert_rows(t() | atom(), String.t(), String.t(), [list()], keyword()) ::
  {:ok, term()} | {:error, term()}

Inserts rows into a table using the client's bulk insert helper.

statement must be a fully-formed INSERT INTO <table> (...) FORMAT JSONCompactEachRow query; rows is a list of value-lists (one per row) in the same column order as the statement. Options are forwarded to the underlying client (e.g. async_insert/wait_for_async_insert).

query(conn_or_name, sql, params \\ [], opts \\ [])

@spec query(t() | atom(), String.t(), list(), keyword()) ::
  {:ok, term()} | {:error, term()}

Runs a SQL query against ClickHouse.

Returns {:ok, %ClickHouse.Result{}} or {:error, %ClickHouse.Error{}}.

query!(conn_or_name, sql, params \\ [], opts \\ [])

@spec query!(t() | atom(), String.t(), list(), keyword()) :: term()

Runs a SQL query, raising on error.

start_link(opts)

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

Starts a ClickHouse connection as part of a supervision tree.

stop(name)

@spec stop(t() | atom()) :: :ok | {:error, term()}

Stops the connection.

Terminates the underlying ClickHouse client process (registered under name) and removes the cached connection struct from :persistent_term. Returns :ok if there was no connection to stop, or {:error, reason} if the client process could not be stopped.