support multipart requests

.typos.toml

@@ -1,3 +1,4 @@
 [default.extend-words]
 "som" = "som" # ./test/ch/ecto_type_test.exs
 "ECT" = "ECT" # ./test/ch/query_test.exs
+"Evn" = "Evn" # ./CHANGELOG.md

CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## Unreleased
+
+- added support for `multipart/form-data` in queries: https://github.com/plausible/ch/pull/290 -- which allows bypassing URL length limits sometimes imposed by reverse proxies when sending queries with many parameters.
+
+  ⚠️ This is currently **opt-in** per query ⚠️
+
+  Global support for the entire connection pool is planned for a future release.
+
+  **Usage**
+
+  Pass `multipart: true` in the options list for `Ch.query/4`
+
+  ```elixir
+  # Example usage
+  Ch.query(pool, "SELECT {a:String}, {b:String}", %{"a" => "A", "b" => "B"}, multipart: true)
+  ```
+
+  <details>
+  <summary>View raw request format reference</summary>
+
+  ```http
+  POST / HTTP/1.1
+  content-length: 387
+  host: localhost:8123
+  user-agent: ch/0.6.2-dev
+  x-clickhouse-format: RowBinaryWithNamesAndTypes
+  content-type: multipart/form-data; boundary="ChFormBoundaryZZlfchKTcd8ToWjEvn66i3lAxNJ_T9dw"
+
+  --ChFormBoundaryZZlfchKTcd8ToWjEvn66i3lAxNJ_T9dw
+  content-disposition: form-data; name="param_a"
+
+  A
+  --ChFormBoundaryZZlfchKTcd8ToWjEvn66i3lAxNJ_T9dw
+  content-disposition: form-data; name="param_b"
+
+  B
+  --ChFormBoundaryZZlfchKTcd8ToWjEvn66i3lAxNJ_T9dw
+  content-disposition: form-data; name="query"
+
+  select {a:String}, {b:String}
+  --ChFormBoundaryZZlfchKTcd8ToWjEvn66i3lAxNJ_T9dw--
+  ```
+
+  </details>
+
 ## 0.6.1 (2025-12-04)
 
 - handle disconnect during stream https://github.com/plausible/ch/pull/283

README.md

@@ -67,6 +67,24 @@ Note on datetime encoding in query parameters:
 - `%NaiveDateTime{}` is encoded as text to make it assume the column's or ClickHouse server's timezone
 - `%DateTime{}` is encoded as unix timestamp and is treated as UTC timestamp by ClickHouse
 
+#### Select rows (lots of params, reverse proxy)
+
+For queries with many parameters the resulting URL can become too long for some reverse proxies, resulting in a `414 Request-URI Too Large` error.
+
+To avoid this, you can use the `multipart: true` option to send the query and parameters in the request body.
+
+```elixir
+{:ok, pid} = Ch.start_link()
+
+# Moves parameters from the URL to a multipart/form-data body
+%Ch.Result{rows: [[[1, 2, 3 | _rest]]]} =
+  Ch.query!(pid, "SELECT {ids:Array(UInt64)}", %{"ids" => Enum.to_list(1..10_000)}, multipart: true)
+```
+
+> [!NOTE]
+>
+> `multipart: true` is currently required on each individual query. Support for pool-wide configuration is planned for a future release.
+
 #### Insert rows
 
 ```elixir

lib/ch.ex

@@ -59,6 +59,7 @@ defmodule Ch do
           # TODO remove
           | {:encode, boolean}
           | {:decode, boolean}
+          | {:multipart, boolean}
           | DBConnection.connection_option()
 
   @doc """
@@ -76,6 +77,7 @@ defmodule Ch do
     * `: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
     * [`DBConnection.connection_option()`](https://hexdocs.pm/db_connection/DBConnection.html#t:connection_option/0)
 
   """

lib/ch/query.ex

@@ -1,16 +1,30 @@
 defmodule Ch.Query do
   @moduledoc "Query struct wrapping the SQL statement."
-  defstruct [:statement, :command, :encode, :decode]
+  defstruct [:statement, :command, :encode, :decode, :multipart]
 
-  @type t :: %__MODULE__{statement: iodata, command: command, encode: boolean, decode: boolean}
+  @type t :: %__MODULE__{
+          statement: iodata,
+          command: command,
+          encode: boolean,
+          decode: boolean,
+          multipart: boolean
+        }
 
   @doc false
   @spec build(iodata, [Ch.query_option()]) :: t
   def build(statement, opts \\ []) do
     command = Keyword.get(opts, :command) || extract_command(statement)
     encode = Keyword.get(opts, :encode, true)
     decode = Keyword.get(opts, :decode, true)
-    %__MODULE__{statement: statement, command: command, encode: encode, decode: decode}
+    multipart = Keyword.get(opts, :multipart, false)
+
+    %__MODULE__{
+      statement: statement,
+      command: command,
+      encode: encode,
+      decode: decode,
+      multipart: multipart
+    }
   end
 
   statements = [
@@ -72,6 +86,7 @@ defmodule Ch.Query do
 end
 
 defimpl DBConnection.Query, for: Ch.Query do
+  @dialyzer :no_improper_lists
   alias Ch.{Query, Result, RowBinary}
 
   @spec parse(Query.t(), [Ch.query_option()]) :: Query.t()
@@ -128,13 +143,82 @@ defimpl DBConnection.Query, for: Ch.Query do
     end
   end
 
+  def encode(%Query{multipart: true, statement: statement}, params, opts) do
+    types = Keyword.get(opts, :types)
+    default_format = if types, do: "RowBinary", else: "RowBinaryWithNamesAndTypes"
+    format = Keyword.get(opts, :format) || default_format
+
+    boundary = "ChFormBoundary" <> Base.url_encode64(:crypto.strong_rand_bytes(24))
+    content_type = "multipart/form-data; boundary=\"#{boundary}\""
+    enc_boundary = "--#{boundary}\r\n"
+    multipart = multipart_params(params, enc_boundary)
+    multipart = add_multipart_part(multipart, "query", statement, enc_boundary)
+    multipart = [multipart | "--#{boundary}--\r\n"]
+
+    {_no_query_params = [],
+     [{"x-clickhouse-format", format}, {"content-type", content_type} | headers(opts)], multipart}
+  end
+
   def encode(%Query{statement: statement}, params, opts) do
     types = Keyword.get(opts, :types)
     default_format = if types, do: "RowBinary", else: "RowBinaryWithNamesAndTypes"
     format = Keyword.get(opts, :format) || default_format
     {query_params(params), [{"x-clickhouse-format", format} | headers(opts)], statement}
   end
 
+  defp multipart_params(params, boundary) when is_map(params) do
+    multipart_named_params(Map.to_list(params), boundary, [])
+  end
+
+  defp multipart_params(params, boundary) when is_list(params) do
+    multipart_positional_params(params, 0, boundary, [])
+  end
+
+  defp multipart_named_params([{name, value} | params], boundary, acc) do
+    acc =
+      add_multipart_part(
+        acc,
+        "param_" <> URI.encode_www_form(name),
+        encode_param(value),
+        boundary
+      )
+
+    multipart_named_params(params, boundary, acc)
+  end
+
+  defp multipart_named_params([], _boundary, acc), do: acc
+
+  defp multipart_positional_params([value | params], idx, boundary, acc) do
+    acc =
+      add_multipart_part(
+        acc,
+        "param_$" <> Integer.to_string(idx),
+        encode_param(value),
+        boundary
+      )
+
+    multipart_positional_params(params, idx + 1, boundary, acc)
+  end
+
+  defp multipart_positional_params([], _idx, _boundary, acc), do: acc
+
+  @compile inline: [add_multipart_part: 4]
+  defp add_multipart_part(multipart, name, value, boundary) do
+    part = [
+      boundary,
+      "content-disposition: form-data; name=\"",
+      name,
+      "\"\r\n\r\n",
+      value,
+      "\r\n"
+    ]
+
+    case multipart do
+      [] -> part
+      _ -> [multipart | part]
+    end
+  end
+
   defp format_row_binary?(statement) when is_binary(statement) do
     statement |> String.trim_trailing() |> String.ends_with?("RowBinary")
   end

test/ch/aggregation_test.exs

@@ -1,5 +1,5 @@
 defmodule Ch.AggregationTest do
-  use ExUnit.Case
+  use ExUnit.Case, async: true
 
   setup do
     conn = start_supervised!({Ch, database: Ch.Test.database()})