fix(clickhouse): add validation and improve s3-tier-move-factor UX

Addresses PR review feedback:
- Add input validation to reject values outside [0.0, 1.0] range
- Fix option description to correctly describe ClickHouse move_factor
  semantics (move when free space falls BELOW threshold, not above)
- Add unit tests for boundary validation (0.0, 1.0, -0.1, 1.1)
- Update docs with s3_tier policy comparison and usage guide
- Add DROP TABLE cleanup in E2E test to prevent leftover state

Author: rustyrazorblade

bin/end-to-end-test

@@ -934,6 +934,9 @@ EOF
         return 1
     fi
 
+    echo "--- Cleaning up test table ---"
+    clickhouse-query "DROP TABLE IF EXISTS test_s3_tier"
+
     echo "=== ClickHouse S3 tier test completed ==="
 }
 

docs/user-guide/clickhouse.md

@@ -34,6 +34,8 @@ easy-db-lab clickhouse init --s3-cache-on-write false
 |--------|-------------|---------|
 | `--s3-cache` | Size of the local S3 cache | 10Gi |
 | `--s3-cache-on-write` | Cache data during write operations | true |
+| `--s3-tier-move-factor` | Move data to S3 tier when local disk free space falls below this fraction (0.0-1.0) | 0.2 |
+| `--replicas-per-shard` | Number of replicas per shard | 3 |
 
 Configuration is saved to the cluster state and applied when you run `clickhouse start`.
 
@@ -189,14 +191,14 @@ ClickHouse is configured with two storage policies. You select the policy when c
 
 ### Policy Comparison
 
-| Aspect | `local` | `s3_main` |
-|--------|---------|-----------|
-| **Storage Location** | Local NVMe disks | S3 bucket with configurable local cache |
-| **Performance** | Best latency, highest throughput | Higher latency, cache-dependent |
-| **Capacity** | Limited by disk size | Virtually unlimited |
-| **Cost** | Included in instance cost | S3 storage + request costs |
-| **Data Persistence** | Lost when cluster is destroyed | Persists independently |
-| **Best For** | Benchmarks, low-latency queries | Large datasets, cost-sensitive workloads |
+| Aspect | `local` | `s3_main` | `s3_tier` |
+|--------|---------|-----------|-----------|
+| **Storage Location** | Local NVMe disks | S3 bucket with configurable local cache | Hybrid: starts local, moves to S3 when disk fills |
+| **Performance** | Best latency, highest throughput | Higher latency, cache-dependent | Good initially, degrades as data moves to S3 |
+| **Capacity** | Limited by disk size | Virtually unlimited | Virtually unlimited |
+| **Cost** | Included in instance cost | S3 storage + request costs | S3 storage + request costs |
+| **Data Persistence** | Lost when cluster is destroyed | Persists independently | Persists independently |
+| **Best For** | Benchmarks, low-latency queries | Large datasets, cost-sensitive workloads | Mixed hot/cold workloads with automatic tiering |
 
 ### Local Storage (`local`)
 
@@ -251,6 +253,50 @@ SETTINGS storage_policy = 's3_main';
 - Cache is automatically managed by ClickHouse
 - First query on cold data will be slower; subsequent queries use cache
 
+### S3 Tiered Storage (`s3_tier`)
+
+The S3 tiered policy provides automatic data movement from local disks to S3 based on disk space availability. This policy starts with local storage and automatically moves data to S3 when local disk space runs low, providing the best of both worlds: fast local performance for hot data and unlimited S3 capacity for cold data.
+
+**Prerequisite**: Your cluster must be initialized with an S3 bucket. Set this during `init`:
+
+```bash
+easy-db-lab init my-cluster --s3-bucket my-clickhouse-data
+```
+
+Configure the tiering behavior before starting ClickHouse:
+
+```bash
+# Move data to S3 when local disk free space falls below 20% (default)
+easy-db-lab clickhouse init --s3-tier-move-factor 0.2
+
+# More aggressive tiering - move when free space < 50%
+easy-db-lab clickhouse init --s3-tier-move-factor 0.5
+```
+
+Then create tables with S3 tiered storage:
+
+```sql
+CREATE TABLE my_table (...)
+ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/default/my_table', '{replica}')
+ORDER BY id
+SETTINGS storage_policy = 's3_tier';
+```
+
+**When to use S3 tiered storage:**
+
+- Workloads with mixed hot/cold data access patterns
+- Growing datasets that may outgrow local disk capacity
+- Want automatic cost optimization without manual intervention
+- Need local performance for recent data with S3 capacity for historical data
+
+**How automatic tiering works:**
+
+- New data is written to local disks first (fast writes)
+- When local disk free space falls below the configured threshold (default: 20%), ClickHouse automatically moves the oldest data to S3
+- Data on S3 is still queryable but with higher latency
+- The local cache (configured with `--s3-cache`) helps performance for frequently accessed S3 data
+- Manual moves are also possible: `ALTER TABLE my_table MOVE PARTITION tuple() TO DISK 's3'`
+
 ## Stopping ClickHouse
 
 To remove the ClickHouse cluster:

src/main/kotlin/com/rustyrazorblade/easydblab/commands/clickhouse/ClickHouseInit.kt

@@ -42,11 +42,16 @@ class ClickHouseInit : PicoBaseCommand() {
 
     @Option(
         names = ["--s3-tier-move-factor"],
-        description = ["Fraction of local disk free space that triggers data move to S3 tier (default: \${DEFAULT-VALUE})"],
+        description = ["Move data to S3 tier when local disk free space falls below this fraction (0.0-1.0) (default: \${DEFAULT-VALUE})"],
     )
     var s3TierMoveFactor: Double = Constants.ClickHouse.DEFAULT_S3_TIER_MOVE_FACTOR
 
     override fun execute() {
+        // Validate s3TierMoveFactor range [0.0, 1.0] per ClickHouse requirements
+        require(s3TierMoveFactor in 0.0..1.0) {
+            "s3TierMoveFactor must be in range [0.0, 1.0], got: $s3TierMoveFactor"
+        }
+
         val state = clusterStateManager.load()
         val config =
             ClickHouseConfig(

src/test/kotlin/com/rustyrazorblade/easydblab/commands/clickhouse/ClickHouseInitTest.kt

@@ -6,6 +6,7 @@ import com.rustyrazorblade.easydblab.configuration.ClickHouseConfig
 import com.rustyrazorblade.easydblab.configuration.ClusterState
 import com.rustyrazorblade.easydblab.configuration.ClusterStateManager
 import org.assertj.core.api.Assertions.assertThat
+import org.assertj.core.api.Assertions.assertThatThrownBy
 import org.junit.jupiter.api.BeforeEach
 import org.junit.jupiter.api.Test
 import org.koin.core.module.Module
@@ -107,4 +108,79 @@ class ClickHouseInitTest : BaseKoinTest() {
         assertThat(savedState.clickHouseConfig!!.replicasPerShard)
             .isEqualTo(Constants.ClickHouse.DEFAULT_REPLICAS_PER_SHARD)
     }
+
+    @Test
+    fun `init rejects s3TierMoveFactor below 0`() {
+        val state = createTestState()
+        whenever(mockClusterStateManager.load()).thenReturn(state)
+
+        val command = ClickHouseInit()
+        command.s3TierMoveFactor = -0.1
+
+        assertThatThrownBy { command.execute() }
+            .isInstanceOf(IllegalArgumentException::class.java)
+            .hasMessageContaining("s3TierMoveFactor must be in range [0.0, 1.0]")
+    }
+
+    @Test
+    fun `init rejects s3TierMoveFactor above 1`() {
+        val state = createTestState()
+        whenever(mockClusterStateManager.load()).thenReturn(state)
+
+        val command = ClickHouseInit()
+        command.s3TierMoveFactor = 1.1
+
+        assertThatThrownBy { command.execute() }
+            .isInstanceOf(IllegalArgumentException::class.java)
+            .hasMessageContaining("s3TierMoveFactor must be in range [0.0, 1.0]")
+    }
+
+    @Test
+    fun `init accepts s3TierMoveFactor at lower boundary`() {
+        val state = createTestState()
+        whenever(mockClusterStateManager.load()).thenReturn(state)
+
+        val command = ClickHouseInit()
+        command.s3TierMoveFactor = 0.0
+        command.execute()
+
+        val captor = argumentCaptor<ClusterState>()
+        verify(mockClusterStateManager).save(captor.capture())
+
+        val savedState = captor.firstValue
+        assertThat(savedState.clickHouseConfig!!.s3TierMoveFactor).isEqualTo(0.0)
+    }
+
+    @Test
+    fun `init accepts s3TierMoveFactor at upper boundary`() {
+        val state = createTestState()
+        whenever(mockClusterStateManager.load()).thenReturn(state)
+
+        val command = ClickHouseInit()
+        command.s3TierMoveFactor = 1.0
+        command.execute()
+
+        val captor = argumentCaptor<ClusterState>()
+        verify(mockClusterStateManager).save(captor.capture())
+
+        val savedState = captor.firstValue
+        assertThat(savedState.clickHouseConfig!!.s3TierMoveFactor).isEqualTo(1.0)
+    }
+
+    @Test
+    fun `init uses default s3TierMoveFactor when not specified`() {
+        val state = createTestState()
+        whenever(mockClusterStateManager.load()).thenReturn(state)
+
+        val command = ClickHouseInit()
+        command.execute()
+
+        val captor = argumentCaptor<ClusterState>()
+        verify(mockClusterStateManager).save(captor.capture())
+
+        val savedState = captor.firstValue
+        assertThat(savedState.clickHouseConfig).isNotNull
+        assertThat(savedState.clickHouseConfig!!.s3TierMoveFactor)
+            .isEqualTo(Constants.ClickHouse.DEFAULT_S3_TIER_MOVE_FACTOR)
+    }
 }