feat(sql): add opt-in partitioned reads to scan_db

Add a `partitions=` argument to `scan_db` that splits a read into independent
slices pulled over parallel connections and concatenated in order, speeding up
large scan-like extracts whose single-cursor transfer is the bottleneck.

`scan_db` consumes the shared read-partition vocabulary from
`io_sources.partitions` (the same `ReadPartition` / `by_time` / `by_value` /
`by_range` used by the distributed executor). Each slice's predicate is
translated to a SQL `WHERE` and injected as an innermost subquery so it
survives outer projection; a predicate that does not translate to SQL raises
rather than silently reading the whole slice. Concurrency is capped by the
Polars thread pool (`POLARS_MAX_THREADS`), with an optional `max_concurrency`
to throttle below it. The path is fully opt-in and falls back to a single query
when a partitioner cannot derive a bounded split.

By default slices are concatenated in partition order, matching an unpartitioned
read. Pass `preserve_partition_order=False` to yield each slice as it finishes
instead, lowering time-to-first-row and avoiding head-of-line blocking behind a
slow slice, at the cost of a nondeterministic row order.

Add unit tests for the partitioned reader and a how-to section in the Reading
and Writing Data wiki.

Signed-off-by: Pascal Tomecek <40371786+ptomecek@users.noreply.github.com>

Author: ptomecek

docs/wiki/Reading-and-Writing-Data.md

@@ -67,6 +67,52 @@ example SQL Server can still seek on `CAST(datetime AS date)`) while others fall
 full scan. When a filtered column is indexed and on a hot path, prefer filtering the
 physical column directly over its cast form.
 
+## Speed up a large SQL read by partitioning it
+
+When a scan-like extract is bounded by an indexed column, a single ODBC cursor is often the
+bottleneck. Pass `partitions=` and `scan_db` splits the read into independent slices and pulls
+them over parallel connections, concatenating the results in order. Build the slices from the
+filter you push down with `by_time`, `by_value`, or `by_range`:
+
+```python
+from polars_io_tools import scan_db, by_time
+
+lf = scan_db(
+    "SELECT * FROM daily_prices",
+    connection="Driver={PostgreSQL};Server=db.example.com;Database=mkt;Uid=reader;******",
+    partitions=by_time("price_date", every="1mo"),
+)
+
+# One slice per month, taken from the pushed-down date range:
+result = lf.filter(
+    (pl.col("price_date") >= pl.date(2025, 1, 1)) & (pl.col("price_date") < pl.date(2025, 7, 1))
+).collect()
+```
+
+- `by_time(column, every=)` — calendar windows; `every` is an interval string (`"1mo"`, `"2w"`,
+  `"5d"`, `"1q"`, `"1y"`) or an integer number of days.
+- `by_value(column, values=None)` — one slice per discrete value; with `values=None` the values
+  are read from the `IN` filter you push down.
+- `by_range(column, every=)` — fixed-width numeric buckets over the pushed-down range.
+
+How many slices run at once is capped by a process-wide SQL connection budget
+(`POLARS_IO_TOOLS_MAX_SQL_CONNECTIONS`; default `min(pl.thread_pool_size(), 8)` — a modest 8 on a
+normal machine, self-throttling to 1 in fan-out clusters that pin `POLARS_MAX_THREADS=1`, since
+these reads are IO-bound and the cap is a connection budget, not the CPU thread pool); pass
+`max_concurrency=` to throttle below it on a busy server. Partitioning is fully opt-in — with no
+`partitions=`, or when a partitioner cannot derive a bounded split, `scan_db` runs the query over
+a single connection. Prefer a handful of medium slices over many tiny ones: each slice is a
+separate query with its own planning and round-trip cost.
+
+For hand-built slices, pass an iterable of `ReadPartition(predicate, key)`. Predicates that
+translate to SQL are pushed to the database; any part that cannot (for example an arbitrary
+Python UDF) is still enforced client-side, so each slice stays exact.
+
+By default the slices are concatenated in partition order, so a partitioned read has the same row
+order as the unpartitioned one. Pass `preserve_partition_order=False` to yield each slice as soon
+as it finishes instead — this lowers time-to-first-row and avoids a slow slice blocking the rest,
+at the cost of a nondeterministic row order (and, with a row limit, a nondeterministic subset).
+
 ## Read from ClickHouse
 
 `scan_clickhouse` streams query results over ClickHouse's HTTP interface as Arrow IPC.