# `Ch`
[🔗](https://github.com/plausible/ch/blob/v0.8.2/lib/ch.ex#L1)

Minimal HTTP ClickHouse client.

# `common_option`

```elixir
@type common_option() ::
  {:database, String.t()}
  | {:username, String.t()}
  | {:password, String.t()}
  | {:settings, Keyword.t()}
  | {:timeout, timeout()}
```

Options shared by both connection startup and query execution.

* `:database` - Database, defaults to `"default"`
* `:username` - Username
* `:password` - User password
* `:settings` - Keyword list of ClickHouse settings
* `:timeout` - HTTP request/receive timeout in milliseconds

# `query_option`

```elixir
@type query_option() ::
  common_option()
  | {:command, Ch.Query.command()}
  | {:headers, [{String.t(), String.t()}]}
  | {:format, String.t()}
  | {:types, [String.t() | atom() | tuple()]}
  | {:encode, boolean()}
  | {:decode, boolean()}
  | {:multipart, boolean()}
  | DBConnection.connection_option()
```

Options for executing a query.

Includes all keys from `t:common_option/0` and `t:DBConnection.connection_option/0` plus:

* `:command` - Command tag for the query
* `:headers` - Custom HTTP headers for the request
* `:format` - Custom response format for the request
* `:decode` - Whether to automatically decode the response
* `:multipart` - Whether to send the query as multipart/form-data

# `start_option`

```elixir
@type start_option() ::
  common_option()
  | {:scheme, String.t()}
  | {:hostname, String.t()}
  | {:port, :inet.port_number()}
  | {:transport_opts, [:gen_tcp.connect_option() | :ssl.tls_client_option()]}
  | DBConnection.start_option()
```

Options for starting the connection pool.

Includes all keys from `t:common_option/0` and `t:DBConnection.start_option/0` plus:

* `:scheme` - HTTP scheme, defaults to `"http"`
* `:hostname` - server hostname, defaults to `"localhost"`
* `:port` - HTTP port, defaults to `8123`
* `:transport_opts` - options to be given to the transport being used. See `Mint.HTTP1.connect/4` for more info

# `child_spec`

```elixir
@spec child_spec([start_option()]) :: :supervisor.child_spec()
```

Returns a supervisor child specification for a connection pool.

See `t:start_option/0` for supported options.

# `query`

```elixir
@spec query(DBConnection.conn(), iodata(), params, [query_option()]) ::
  {:ok, Ch.Result.t()} | {:error, Exception.t()}
when params: map() | [term()] | [row :: [term()]] | iodata() | Enumerable.t()
```

Runs a query and returns the result as `{:ok, %Ch.Result{}}` or
`{:error, Exception.t()}` if there was a database error.

See `t:query_option/0` for available options.

# `query!`

```elixir
@spec query!(DBConnection.conn(), iodata(), params, [query_option()]) :: Ch.Result.t()
when params: map() | [term()] | [row :: [term()]] | iodata() | Enumerable.t()
```

Runs a query and returns the result or raises `Ch.Error` if
there was an error. See `query/4`.

# `start_link`

```elixir
@spec start_link([start_option()]) :: GenServer.on_start()
```

Start the connection pool process.

See `t:start_option/0` for available options.

---

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