# `AshClickhouse.Connection`
[🔗](https://github.com/ohhi-vn/ash_clickhouse/blob/main/lib/ash_clickhouse/connection.ex#L1)

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.

# `t`

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

# `child_spec`

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

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

# `database_for`

```elixir
@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`

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

Returns the connection struct registered under `name`, if any.

# `insert_rows`

```elixir
@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`

```elixir
@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!`

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

Runs a SQL query, raising on error.

# `start_link`

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

Starts a ClickHouse connection as part of a supervision tree.

# `stop`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*