simPod · simPod · Aug 9, 2025 · Aug 8, 2025
diff --git a/infection.json.dist b/infection.json.dist
@@ -17,5 +17,5 @@
         "text": "infection-log.txt"
     },
     "minMsi": 90,
-    "minCoveredMsi": 94
+    "minCoveredMsi": 93
 }
diff --git a/src/Client/ClickHouseAsyncClient.php b/src/Client/ClickHouseAsyncClient.php
@@ -7,29 +7,32 @@
 use GuzzleHttp\Promise\PromiseInterface;
 use SimPod\ClickHouseClient\Format\Format;
 use SimPod\ClickHouseClient\Output\Output;
+use SimPod\ClickHouseClient\Settings\EmptySettingsProvider;
+use SimPod\ClickHouseClient\Settings\SettingsProvider;
 
-/** @see Output hack for IDE to preserve `use` */
 interface ClickHouseAsyncClient
 {
     /**
      * @param Format<O> $outputFormat
-     * @param array<string, float|int|string> $settings
      *
      * @template O of Output
      */
-    public function select(string $query, Format $outputFormat, array $settings = []): PromiseInterface;
+    public function select(
+        string $query,
+        Format $outputFormat,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): PromiseInterface;
 
     /**
      * @param array<string, mixed>            $params
      * @param Format<O>                       $outputFormat
-     * @param array<string, float|int|string> $settings
      *
      * @template O of Output
      */
     public function selectWithParams(
         string $query,
         array $params,
         Format $outputFormat,
-        array $settings = [],
+        SettingsProvider $settings = new EmptySettingsProvider(),
     ): PromiseInterface;
 }
diff --git a/src/Client/ClickHouseClient.php b/src/Client/ClickHouseClient.php
@@ -13,30 +13,33 @@
 use SimPod\ClickHouseClient\Format\Format;
 use SimPod\ClickHouseClient\Output\Output;
 use SimPod\ClickHouseClient\Schema\Table;
+use SimPod\ClickHouseClient\Settings\EmptySettingsProvider;
+use SimPod\ClickHouseClient\Settings\SettingsProvider;
 
+/** @phpstan-import-type Settings from SettingsProvider */
 interface ClickHouseClient
 {
     /**
-     * @param array<string, float|int|string> $settings
-     *
      * @throws ClientExceptionInterface
      * @throws ServerError
      */
-    public function executeQuery(string $query, array $settings = []): void;
+    public function executeQuery(string $query, SettingsProvider $settings = new EmptySettingsProvider()): void;
 
     /**
      * @param array<string, mixed> $params
-     * @param array<string, float|int|string> $settings
      *
      * @throws ClientExceptionInterface
      * @throws ServerError
      * @throws UnsupportedParamType
      * @throws UnsupportedParamValue
      */
-    public function executeQueryWithParams(string $query, array $params, array $settings = []): void;
+    public function executeQueryWithParams(
+        string $query,
+        array $params,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): void;
 
     /**
-     * @param array<string, float|int|string> $settings
      * @param Format<O> $outputFormat
      *
      * @return O
@@ -46,10 +49,13 @@ public function executeQueryWithParams(string $query, array $params, array $sett
      *
      * @template O of Output
      */
-    public function select(string $query, Format $outputFormat, array $settings = []): Output;
+    public function select(
+        string $query,
+        Format $outputFormat,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): Output;
 
     /**
-     * @param array<string, float|int|string> $settings
      * @param array<string, mixed> $params
      * @param Format<O> $outputFormat
      *
@@ -62,23 +68,31 @@ public function select(string $query, Format $outputFormat, array $settings = []
      *
      * @template O of Output
      */
-    public function selectWithParams(string $query, array $params, Format $outputFormat, array $settings = []): Output;
+    public function selectWithParams(
+        string $query,
+        array $params,
+        Format $outputFormat,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): Output;
 
     /**
      * @param array<array<mixed>> $values
      * @param list<string>|array<string, string>|null $columns
-     * @param array<string, float|int|string> $settings
      *
      * @throws CannotInsert
      * @throws ClientExceptionInterface
      * @throws ServerError
      * @throws UnsupportedParamType
      * @throws UnsupportedParamValue
      */
-    public function insert(Table|string $table, array $values, array|null $columns = null, array $settings = []): void;
+    public function insert(
+        Table|string $table,
+        array $values,
+        array|null $columns = null,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): void;
 
     /**
-     * @param array<string, float|int|string> $settings
      * @param Format<O> $inputFormat
      *
      * @throws ClientExceptionInterface
@@ -90,11 +104,10 @@ public function insertWithFormat(
         Table|string $table,
         Format $inputFormat,
         string $data,
-        array $settings = [],
+        SettingsProvider $settings = new EmptySettingsProvider(),
     ): void;
 
     /**
-     * @param array<string, float|int|string> $settings
      * @param list<string> $columns
      * @param Format<Output<mixed>> $inputFormat
      *
@@ -107,6 +120,6 @@ public function insertPayload(
         Format $inputFormat,
         StreamInterface $payload,
         array $columns = [],
-        array $settings = [],
+        SettingsProvider $settings = new EmptySettingsProvider(),
     ): void;
 }
diff --git a/src/Client/Http/RequestSettings.php b/src/Client/Http/RequestSettings.php
@@ -4,19 +4,18 @@
 
 namespace SimPod\ClickHouseClient\Client\Http;
 
+use SimPod\ClickHouseClient\Settings\SettingsProvider;
+
+/** @phpstan-import-type Settings from SettingsProvider */
 final readonly class RequestSettings
 {
-    /** @var array<string, float|int|string> */
+    /** @phpstan-var Settings */
     public array $settings;
 
-    /**
-     * @param array<string, float|int|string> $defaultSettings
-     * @param array<string, float|int|string> $querySettings
-     */
     public function __construct(
-        array $defaultSettings,
-        array $querySettings,
+        SettingsProvider $defaultSettings,
+        SettingsProvider $querySettings,
     ) {
-        $this->settings = $querySettings + $defaultSettings;
+        $this->settings = $querySettings->get() + $defaultSettings->get();
     }
 }
diff --git a/src/Client/PsrClickHouseAsyncClient.php b/src/Client/PsrClickHouseAsyncClient.php
@@ -16,6 +16,8 @@
 use SimPod\ClickHouseClient\Format\Format;
 use SimPod\ClickHouseClient\Logger\SqlLogger;
 use SimPod\ClickHouseClient\Output\Output;
+use SimPod\ClickHouseClient\Settings\EmptySettingsProvider;
+use SimPod\ClickHouseClient\Settings\SettingsProvider;
 use SimPod\ClickHouseClient\Sql\SqlFactory;
 use SimPod\ClickHouseClient\Sql\ValueFormatter;
 
@@ -25,12 +27,11 @@
 {
     private SqlFactory $sqlFactory;
 
-    /** @param array<string, float|int|string> $defaultSettings */
     public function __construct(
         private HttpAsyncClient $asyncClient,
         private RequestFactory $requestFactory,
         private SqlLogger|null $sqlLogger = null,
-        private array $defaultSettings = [],
+        private SettingsProvider $defaultSettings = new EmptySettingsProvider(),
     ) {
         $this->sqlFactory = new SqlFactory(new ValueFormatter());
     }
@@ -40,8 +41,11 @@
      *
      * @throws Exception
      */
-    public function select(string $query, Format $outputFormat, array $settings = []): PromiseInterface
-    {
+    public function select(
+        string $query,
+        Format $outputFormat,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): PromiseInterface {
         return $this->selectWithParams($query, [], $outputFormat, $settings);
     }
 
@@ -54,7 +58,7 @@
         string $query,
         array $params,
         Format $outputFormat,
-        array $settings = [],
+        SettingsProvider $settings = new EmptySettingsProvider(),
     ): PromiseInterface {
         $formatClause = $outputFormat::toSql();
 
@@ -75,16 +79,15 @@
 
     /**
      * @param array<string, mixed> $params
-     * @param array<string, float|int|string> $settings
      * @param (callable(ResponseInterface):mixed)|null $processResponse
      *
      * @throws Exception
      */
     private function executeRequest(
         string $sql,
         array $params,
-        array $settings = [],
-        callable|null $processResponse = null,
+        SettingsProvider $settings,
+        callable|null $processResponse,
     ): PromiseInterface {
         $request = $this->requestFactory->prepareSqlRequest(
             $sql,
@@ -98,14 +101,14 @@
        );

        $id = uniqid('', true);
        $this->sqlLogger?->startQuery($id, $sql);

        return Create::promiseFor(
            $this->asyncClient->sendAsyncRequest($request),
        )
            ->then(
                function (ResponseInterface $response) use ($id, $processResponse) {
                    $this->sqlLogger?->stopQuery($id);

                    if ($response->getStatusCode() !== 200) {
                        throw ServerError::fromResponse($response);

diff --git a/src/Client/PsrClickHouseClient.php b/src/Client/PsrClickHouseClient.php
@@ -21,6 +21,8 @@
 use SimPod\ClickHouseClient\Logger\SqlLogger;
 use SimPod\ClickHouseClient\Output\Output;
 use SimPod\ClickHouseClient\Schema\Table;
+use SimPod\ClickHouseClient\Settings\EmptySettingsProvider;
+use SimPod\ClickHouseClient\Settings\SettingsProvider;
 use SimPod\ClickHouseClient\Sql\SqlFactory;
 use SimPod\ClickHouseClient\Sql\ValueFormatter;
 
@@ -42,18 +44,17 @@ class PsrClickHouseClient implements ClickHouseClient
 
     private SqlFactory $sqlFactory;
 
-    /** @param array<string, float|int|string> $defaultSettings */
     public function __construct(
         private ClientInterface $client,
         private RequestFactory $requestFactory,
         private SqlLogger|null $sqlLogger = null,
-        private array $defaultSettings = [],
+        private SettingsProvider $defaultSettings = new EmptySettingsProvider(),
     ) {
         $this->valueFormatter = new ValueFormatter();
         $this->sqlFactory     = new SqlFactory($this->valueFormatter);
     }
 
-    public function executeQuery(string $query, array $settings = []): void
+    public function executeQuery(string $query, SettingsProvider $settings = new EmptySettingsProvider()): void
     {
         try {
             $this->executeRequest($query, params: [], settings: $settings);
@@ -62,26 +63,36 @@ public function executeQuery(string $query, array $settings = []): void
         }
     }
 
-    public function executeQueryWithParams(string $query, array $params, array $settings = []): void
-    {
+    public function executeQueryWithParams(
+        string $query,
+        array $params,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): void {
         $this->executeRequest(
             $this->sqlFactory->createWithParameters($query, $params),
             params: $params,
             settings: $settings,
         );
     }
 
-    public function select(string $query, Format $outputFormat, array $settings = []): Output
-    {
+    public function select(
+        string $query,
+        Format $outputFormat,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): Output {
         try {
             return $this->selectWithParams($query, params: [], outputFormat: $outputFormat, settings: $settings);
         } catch (UnsupportedParamValue | UnsupportedParamType) {
             absurd();
         }
     }
 
-    public function selectWithParams(string $query, array $params, Format $outputFormat, array $settings = []): Output
-    {
+    public function selectWithParams(
+        string $query,
+        array $params,
+        Format $outputFormat,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): Output {
         $formatClause = $outputFormat::toSql();
 
         $sql = $this->sqlFactory->createWithParameters($query, $params);
@@ -98,8 +109,12 @@ public function selectWithParams(string $query, array $params, Format $outputFor
         return $outputFormat::output($response->getBody()->__toString());
     }
 
-    public function insert(Table|string $table, array $values, array|null $columns = null, array $settings = []): void
-    {
+    public function insert(
+        Table|string $table,
+        array $values,
+        array|null $columns = null,
+        SettingsProvider $settings = new EmptySettingsProvider(),
+    ): void {
         if ($values === []) {
             throw CannotInsert::noValues();
         }
@@ -192,7 +207,7 @@ public function insertWithFormat(
         Table|string $table,
         Format $inputFormat,
         string $data,
-        array $settings = [],
+        SettingsProvider $settings = new EmptySettingsProvider(),
     ): void {
         $formatSql = $inputFormat::toSql();
 
@@ -220,7 +235,7 @@ public function insertPayload(
         Format $inputFormat,
         StreamInterface $payload,
         array $columns = [],
-        array $settings = [],
+        SettingsProvider $settings = new EmptySettingsProvider(),
     ): void {
         if ($payload->getSize() === 0) {
             throw CannotInsert::noValues();
@@ -259,13 +274,12 @@ public function insertPayload(
 
     /**
      * @param array<string, mixed> $params
-     * @param array<string, float|int|string> $settings
      *
      * @throws ServerError
      * @throws ClientExceptionInterface
      * @throws UnsupportedParamType
      */
-    private function executeRequest(string $sql, array $params, array $settings): ResponseInterface
+    private function executeRequest(string $sql, array $params, SettingsProvider $settings): ResponseInterface
     {
         $request = $this->requestFactory->prepareSqlRequest(
             $sql,

diff --git a/src/Settings/ArraySettingsProvider.php b/src/Settings/ArraySettingsProvider.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SimPod\ClickHouseClient\Settings;
+
+/** @phpstan-import-type Settings from SettingsProvider */
+final readonly class ArraySettingsProvider implements SettingsProvider
+{
+    /** @phpstan-param Settings $settings */
+    public function __construct(private array $settings = [])
+    {
+    }
+
+    public function get(): array
+    {
+        return $this->settings;
+    }
+}