more docs

README.md

@@ -1,9 +1,9 @@
 # Ecto ClickHouse Adapter
 
-<!-- [![Hex Package](https://img.shields.io/hexpm/v/chto.svg)](https://hex.pm/packages/chto)
-     [![Hex Docs](https://img.shields.io/badge/hex-docs-blue.svg)](https://hexdocs.pm/chto) -->
+[![Hex Package](https://img.shields.io/hexpm/v/chto.svg)](https://hex.pm/packages/chto)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-blue.svg)](https://hexdocs.pm/chto)
 
-Uses [`:ch`](https://github.com/plausible/ch) as driver.
+Uses [`Ch`](https://github.com/plausible/ch) as driver.
 
 ## Installation
 
@@ -17,86 +17,72 @@ end
 
 ## Usage
 
-<details>
-<summary>Define repo and start <code>DBConnection</code> pool</summary>
+In your `config/config.exs`
+
+```elixir
+config :my_app, ecto_repos: [MyApp.Repo]
+
+config :my_app, MyApp.Repo,
+  url: "http://username:password@localhost:8123/default"
+  # or :database, :hostname, :username, etc.
+```
+
+In your application code
 
 ```elixir
 defmodule MyApp.Repo do
   use Ecto.Repo,
-    adapter: Ecto.Adapters.ClickHouse,
-    otp_app: :my_app
+    otp_app: :my_app,
+    adapter: Ecto.Adapters.ClickHouse
 end
 ```
 
-```elixir
-config :my_app, ecto_repos: [MyApp.Repo]
-config :my_app, MyApp.Repo,
-  url: "http://username:password@localhost:8123/default"
-```
+## Caveats
+
+#### Ecto schemas
+
+For automatic RowBinary encoding some schema fields need to use custom types:
 
 ```elixir
-MyApp.Repo.start_link()
+defmodule MyApp.Example do
+  use Ecto.Schema
+
+  @primary_key false
+  schema "example" do
+    field :numeric_types_need_size, Ch.Types.UInt32
+    field :no_custom_type_for_strings, :string
+    field :datetime, :naive_datetime
+    field :maybe_name, Ch.Types.Nullable, type: :string
+    field :country_code, Ch.Types.FixedString, size: 2
+    field :price, Ch.Types.Decimal32, scale: 2
+  end
+end
+
+MyApp.Repo.insert_all(MyApp.Example, rows)
 ```
 
-</details>
+#### Schemaless inserts
+
+For schemaless inserts `:types` option needs to be provided
 
 ```elixir
-## speedrun
-
-iex> Mix.install([{:chto, github: "plausible/chto"}])
-
-iex>
-
-iex> import Ecto.Query
-iex> Repo.start_link()
-
-iex> Repo.query!("create table example(a UInt32, b String, c DateTime) engine=MergeTree order by tuple()")
-
-iex> defmodule Example do
-       use Ecto.Schema
-
-       @primary_key false
-       schema "example" do
-         field :a, Ch.Types.UInt32
-         field :b, :string
-         field :c, :naive_datetime
-       end
-     end
-
-iex> Repo.insert_all("example", [%{a: 1, b: "2"}, %{a: 3, c: nil}], types: [a: :u32, b: :string, c: :datetime])
-{2, nil}
-
-iex> Repo.insert_all(Example, [%{a: 5, b: "5"}, %{a: 6}])
-{2, nil}
-
-iex> Example |> order_by(desc: :a) |> limit(2) |> Repo.all()
-[
-  %Example{
-    a: 6,
-    b: "",
-    c: ~N[1970-01-01 00:00:00]
-  }
-  %Example{
-    a: 5,
-    b: "5",
-    c: ~N[1970-01-01 00:00:00]
-  }
+types = [
+  numeric_types_need_size: :u32,
+  no_custom_type_for_strings: :string,
+  datetime: :datetime,
+  maybe_name: {:nullable, :string},
+  country_code: {:string, _size = 2},
+  price: {:decimal, _size = 32, _scale = 2}
 ]
 
-iex> Repo.insert_all(Example, select(Example, [e], %{a: e.a, b: e.b}))
-{4, nil}
-
-iex> Repo.update_all(Example, set: [a: 2])
-# ** (Ecto.QueryError) ClickHouse does not support UPDATE statements -- use ALTER TABLE instead in query:
-# from e0 in Dev.Example,
-#   update: [set: [a: ^...]]
+MyApp.Repo.insert_all("example", rows, types: types)
+```
 
-# count is 0 since clickhouse doesn't (seem to) respond with how many rows been deleted
-iex> Repo.delete_all(Example, settings: [allow_experimental_lightweight_delete: 1, mutations_sync: 1])
-{0, nil}
+#### Settings
 
-iex> Repo.aggregate(Example, :count)
-0
+`:settings` option can be used to enable [asynchronous inserts](https://clickhouse.com/docs/en/optimize/asynchronous-inserts), lightweght [deletes](https://clickhouse.com/docs/en/guides/developer/lightweght-delete), and [more](https://clickhouse.com/docs/en/operations/settings/settings)
 
-iex> Repo.query!("drop table example")
+```elixir
+MyApp.Repo.insert_all(MyApp.Example, rows, settings: [async_insert: 1])
+MyApp.Repo.delete_all("example", settings: [allow_experimental_lightweight_delete: 1])
 ```

lib/ecto/adapters/clickhouse.ex

@@ -1,5 +1,5 @@
 defmodule Ecto.Adapters.ClickHouse do
-  @moduledoc "Ecto adapter for a minimal HTTP ClickHouse client"
+  @moduledoc "Ecto adapter for HTTP ClickHouse client"
 
   @behaviour Ecto.Adapter
   @behaviour Ecto.Adapter.Migration