datahike.pg.sql — org.replikativ/pg-datahike 0.1.267

SQL → Datahike Datalog translator.

Parses SQL strings using JSqlParser and translates the AST into Datahike Datalog queries that can be executed by datahike.api/q.

The core mapping: attribute namespace prefixes become virtual table names. :person/name → table 'person', column 'name' :person/age → table 'person', column 'age'

Main entry points: (parse-sql sql schema) → {:type :select :query {...} :args [...]} | {:type :insert :tx-data [...]} | {:type :system :result QueryResult} | {:type :error :message str}

*ast-cache* clj

Server-wide JSqlParser AST cache, keyed on the preprocessed SQL string. Tests can rebind to an isolated map; nil disables caching.

*catalog-cache* clj

Tests can rebind this to an isolated java.util.Map to keep their data from polluting the global cache (or vice versa). Nil disables caching entirely. Defaults to the server-wide cache.

*parse-cache* clj

Server-wide cache for parse-sql results. Tests can rebind to an isolated map; nil disables caching entirely.

cached-result clj

(cached-result k f)

The value of (f), kept in the parse-sql result cache under k, with the same LRU bound and the same clearing on DDL. k must hold everything the value depends on. A result of :type :error, or one that reads a session value, is not kept.

catalog-basis-of clj

(catalog-basis-of db)

The exact catalog/schema comparison value of db, as the parse cache's own key takes it: what a cached translation is valid for.

cte-namespace clj

(cte-namespace n cte-name)

The synthetic storage namespace for the nth CTE named cte-name.

Deterministic — a pure function of the SQL text — because the parse caches key on [sql (hash schema)], and a gensym/nanoTime namespace would change the enriched schema on every parse and turn every CTE query into a total cache miss.

The __cte prefix is reserved: datahike.pg.schema/internal-attr? filters it so a CTE can never surface as a table in pg_class or information_schema.

enrich-db-with-catalogs clj

(enrich-db-with-catalogs db schema catalog-names)

Materialise the given catalog tables' schema + data on top of db, returning the enriched db (its :schema carries the catalog attrs). Returns db unchanged when catalog-names is empty.

Only catalog schema fragments are cached. Catalog rows are derived from this exact input DB and materialized on top of it on every call. Thus a catalog join cannot accidentally inherit another call's user rows. schema is db's user schema.

invalidate-catalog-cache! clj

(invalidate-catalog-cache!)

Clear cached catalog schema fragments. Rows and enriched database snapshots are not cached: catalog extensions may read arbitrary current user data.

invalidate-parse-cache! clj

(invalidate-parse-cache!)

Clear the server-wide parse-sql result cache. Called from every DDL exec branch (via server/invalidate-schema-cache!). Exact cache keys also detect native catalog changes. The AST cache is untouched: JSqlParser output depends only on SQL text.

parse-sql clj

(parse-sql sql schema)

(parse-sql sql schema db)

Parse a SQL statement and return a translation result.

Returns one of: {:type :select :query <datalog-map> :find-aliases [...] ...} {:type :insert :tx-data [...] :count N} {:type :update :table str :ns str :assignments [...] :where-expr expr} {:type :delete :table str :ns str :where-expr expr} {:type :ddl-create :tx-data [...]} {:type :system :system-type keyword} {:type :error :message str}

Optional db parameter enables subquery execution during translation.

Three cache levels stack:

• Result cache (*parse-cache*) — for SQL strings re-issued verbatim (pgjdbc unnamed prepared statements, ORM select-by-id).
• Lexical INSERT-VALUES templating + AST cache — for INSERT INTO t [(cols)] VALUES (lit, …) shapes the literals are captured, the SQL is normalised to (? , …), and the resulting AST is reused across all rows of the same shape. Translation still runs per row with *bound-params* bound so JdbcParameter nodes resolve to concrete values inline (no ParamRef closure captures).
• AST cache (*ast-cache*) — covers everything else that hits JSqlParser, repeated or not.

simple-query-param-error clj

(simple-query-param-error sql)

An {:type :error} map when sql uses a $N placeholder in the SIMPLE query protocol, else nil.

Simple Query has no Bind step, so there is nothing a placeholder could refer to and PostgreSQL raises 42P02. We used to translate the statement anyway and let the unresolved placeholder reach the client: SELECT $1 answered with the internal ParamRef record rendered as {"idx":1} — leaking a representation detail as if it were data.

Only reachable from the simple path; the extended path resolves placeholders at Bind. Gated on an indexOf so statements without a $ never pay for tokenising, and driven off the tokeniser's :param classification so a $ inside a string, a dollar-quoted body or a quoted identifier doesn't count.

translation-context clj

(translation-context)

What a translation depends on besides its SQL, schema and catalog: the declared parameter types, the session's temp tables, whether the SQL is nested in a statement (see params/nested-parse?), search_path, DateStyle and the database. The cache is server-wide and its keys compare by value, so two databases built by the same DDL have equal schemas and an equal catalog basis; without the name they would share a plan.

DateStyle belongs here because it is read at TRANSLATE time: a literal date is decoded and folded while translating, so '8/10/2017'::date is a different value under MDY and under DMY. Without it in the key the first execution's answer was served to the second, and SET datestyle TO dmy appeared to do nothing under any driver using the extended protocol -- psql's simple queries happened to miss the cache and looked correct.