AshClickhouse.Connection (AshClickhouse v0.6.2)

Copy Markdown View Source

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)
  • :ipv4_only — when true, resolve the URL host to an IPv4 address and connect using that literal IP. Useful in environments where the DNS server returns NXDOMAIN for AAAA queries (e.g. clusters with IPv6 disabled), which otherwise makes the underlying hackney client fail with :nxdomain even though the A record resolves. Defaults to false.

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, %AshClickhouse.Error.ClickhouseError{}}. The non-bang variant never raises: any exception raised by the client is converted to a normalized error tuple.

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

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

Runs a SQL query, raising on error.

Returns the %ClickHouse.Result{} on success and raises an AshClickhouse.Error.ClickhouseError on failure.

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.