Wrap Readers with an in-memory caching layer

[georgestagg]

Add an in-memory caching layer for readers

This PR adds a caching layer that wraps any reader with an in-memory caching reader, for now supporting duckdb or sqlite.
This allows us to visualise with read-only databases, and caching improves the experience for very slow remote databases.

A CachingReader wraps a primary reader, splitting the API into two surfaces:

• source (execute_sql) — base reads of the user's data, hitting the primary.
• compute (execute_sql_cached) — all dialect-generated / derived SQL over __ggsql_* tables, hitting the cache.

When caching is off, the default execute_sql_cached just calls execute_sql, so the single execution path works unchanged.

Cached reads are tracked in a __ggsql_cache_meta__ table inside the cache reader, itself queryable for introspection.
The cache is bounded by a TTL and an LRU budget. Entries older than the TTL are re-fetched, and once the total size exceeds the budget the least-recently-used entries are evicted until it fits.

Usage

Opt in with the --cache flag when using the ggsql CLI, or otherwise set a composite <primary>+<cache>:// connection string:

# simplest: cache the default duckdb reader
ggsql exec "<query>" --cache duckdb

# composite URI, with per-connection tuning
ggsql exec "<query>" --reader "odbc+duckdb://<dsn>?cache_ttl=600&cache_max_bytes=256mb"

In Jupyter et al., use a composite connection string:

-- @connect: odbc+duckdb://DSN=example_db_dsn
SELECT region, revenue FROM sales
VISUALISE region AS x, revenue AS y
DRAW bar

Force clear the cache mid-session with a meta-command:

-- @uncache

Configuration comes from env vars (GGSQL_CACHE_DISABLED, GGSQL_CACHE_TTL, GGSQL_CACHE_MAX_BYTES)
or connection URI query params (?cache_ttl=300&cache_max_bytes=32mb&cache_disabled=0).
Defaults: enabled, 300s TTL, 512 MB.

Reader trait changes

There are four new Reader methods, all with defaults so existing drivers are unaffected:

• execute_sql_cached -- the compute surface. Defaults to just execute_sql.
• materialize_table -- materialize a query body. Default is CREATE … TEMP TABLE on the reader.
• caches_sources -- defaults to false, true for CachingReader.
• clear_cache -- no-op by default, backs the -- @uncache meta-command.

Because SQL runs on cache-resident _ggsql* tables via the compute surface, it must be emitted by ggsql in the cache backend's dialect, not the primary's, so CachingReader::dialect() returns the cache dialect.

Read-only guarantee

When the cache is active, the primary connection is never written to:

• materialize_table is overridden by CachingReader to register() the resulting data frame into the cache, rather than using temp tables.
• All dialect-generated/derived SQL runs on the compute surface using execute_sql_cached, i.e. the cache backend.
• The primary sees only base reads of the user's data.

Grammar

The grammar has been changed to parse joins structured nodes, so every joined table is discoverable. This allows for parser-based SQL rewriting

• CTE- and source-reference rewriting now runs off the tree-sitter parse tree instead of ad-hoc regex. This correctly handles comma joins, quoted / schema-qualified / whitespace- and case-variant names.

• Moved the SQL-structural helpers out of reader/data.rs into a new file parser/sql.rs.

Mixed-residency staging

When a query body mixes cache-resident tables (CTEs, ggsql: builtins) with primary base tables, the primary tables are
staged into the cache so the whole body can run on the compute surface. This allows one to run queries like,

-- @connect: odbc+duckdb://DSN=example_db_dsn
CREATE TEMP TABLE sales AS SELECT * FROM (VALUES
  ('North', 150), ('South', 250), ('East', 180)) AS t(region, revenue);
WITH targets AS (
  SELECT * FROM (VALUES ('North', 140), ('South', 260), ('East', 160)) AS v(region, target)
)
SELECT sales.region, sales.revenue - targets.target AS delta
FROM sales JOIN targets ON sales.region = targets.region
VISUALISE region AS x, delta AS y
DRAW point

sales lives on the primary (via the DSN). targets is a CTE, materialised in the local cache. The join mixes the two, so sales is transparently staged into the cache and the join runs locally.

Similarly, setup (CREATE/INSERT/UPDATE/DELETE) queries runs before CTE materialisation and staging, so a query that creates a table and then uses it works OK with caching enabled.

The same routing applies to per-layer sources. Each layer can bring its own FROM, and with caching enabled those sources are resolved against the cache rather than the primary,
so you can point one layer at a 'local_file.csv' even when the primary is a remote database:

-- @connect: odbc+duckdb://DSN=example_db_dsn
VISUALISE
DRAW line  MAPPING month AS x, revenue AS y FROM sales
DRAW point MAPPING month AS x, target  AS y FROM 'targets.csv'

sales is read from the remote primary, targets.csv is read locally by the cache backend. Both layers render together; nothing is written back to the primary. Without caching, FROM 'targets.csv' would only work if the primary reader itself could read that path.

Bookeeping

Initially based on #423 and jimhester#2. Jim should be added as a co-author on the final merge commit.

[thomasp85]

This is a very preliminary review based on a first read through. Some comments in the code. Further, a more general question: How does the caching setup works in terms of e.g. a user loading a spatial extension. Is this somehow mirrored in the cache (I think not but asking because I can see issues down the line here)

[thomasp85]

Part of me want the cache to come before the primary, so that the primary sits next to the arguments that define it

[georgestagg]

Good idea, I've flipped them in 049e38a.

[thomasp85]

What is the rationale for including this grammar change in the PR? I know some of the changes addresses the need to join across primary and cache but I'm not sure why we would suddenly allow this in FROM? I can fear we open the door for extremely complex FROM queries

[georgestagg]

As discussed, consider the following statement,

  WITH t AS (SELECT 1 AS k, 100 AS v)
  SELECT t.v, base.w FROM t JOIN base ON t.k = base.k
  VISUALISE v AS x, w AS y DRAW point

Once the CTE is materialised, we have a situation where t.v is rewritten as __ggsql_cte_[...] and materialised in the cache, but base.w remains in the primary. So, we need a way to capture such tables JOINed in this way and materialise them in the cache also.

The current machinery for all this is based on string matching a bag of tokens, which works OK when we know we're looking for tables with names like __ggsql_cte_*. But, when we have arbitrary tables, potentially living in subqueries, we need to do proper parsing.

So, we switch to read parsing and as part of that work we extend the grammar to properly recognise ANSI SQL JOINs and windowing here.

[georgestagg]

I have pushed a further commit to separate out VISUALISE's FROM rule from SELECTs FROM. Now, VISUALISE [...] FROM [...] creates a different node when parsing that no longer accepts the additional JOIN and windowing children.

With this additional change, VISUALISE [...] FROM [...] with anything other than a table/CTE is a parse error.

[georgestagg]

How does the caching setup works in terms of e.g. a user loading a spatial extension

As discussed, non-data returning statements like INSTALL spatial are forwarded to the primary verbatim.

For the caching reader, during computation ggsql automatically enables the relevant spatial extensions when needed.

The above magic can lead to confusing errors where a VISUALISE with e.g. Snowflake primary leads to duckdb installation errors. To attempt to reduce confusion, ed7aee5 adds an error message wrapper around computational SQL queries in the caching reader. The error is still raised, but there is a short message prepended explaining the error is from the caching reader, rather than the backend.