SQL support for isograph

[edmondop]

Summary

This branch adds Phase 1 SQL support to Isograph using DataFusion and Substrait, enabling Isograph to execute SQL queries against SQLite databases via a compile-time query pipeline, and fixes the TypeScript type system to support both SQL and GraphQL response types.

---

What Was Built

1. SQL Query Pipeline (compile-time)

Isograph's compiler now generates a Substrait binary query plan alongside the existing GraphQL artifacts. The pipeline is:

MergedSelectionMap → DataFusion LogicalPlan → Substrait binary → Base64-encoded artifact

New crates:

• crates/sql_network_protocol — NetworkProtocol implementation for SQL; builds DataFusion LogicalPlan from Isograph's MergedSelectionMap, then serialises to Substrait binary via prost
• crates/sql_lang_types — Type aliases and newtypes for SQL-specific language constructs
• crates/sql_schema_parser — Parses SQL CREATE TABLE DDL into Isograph's schema model
• crates/isograph_server — Axum HTTP server (/query endpoint) that accepts Substrait plans at runtime, executes them against DataFusion, and returns Arrow IPC data

Modified:

• crates/artifact_content/src/entrypoint_artifact.rs — generates query_plan.bin (base64 Substrait) for SQL profiles
• crates/artifact_content/src/raw_response_type.rs — adds readonly modifiers and field-name quoting to generated TypeScript types

2. SQLite Demo (demos/sqlite-demo)

A standalone Vite + React app that uses the SQL pipeline end-to-end:

• Defines a Star Wars planets schema in schema.sql
• Uses iso to write a HomePage entrypoint that selects id, name, climate, orbital_period, surface_water
• The isograph compiler generates query_plan.bin, normalization_ast.ts, and raw_response_type.ts
• At runtime, the frontend fetches from isograph-server, which runs the Substrait plan against DataFusion and returns Arrow IPC

3. TypeScript Type System Unification

Problem: SQL-generated types like { id: number, name: string } didn't satisfy the existing NetworkResponseObject constraint, which used a branded-key mapped type designed only for GraphQL.

Solution: Widened NetworkResponseObject in libs/isograph-react/src/core/cache.ts to use a plain string index signature:

// Before: mapped type with branded keys (GraphQL-only)
export type NetworkResponseObject = {
  readonly [K in ScalarNetworkResponseKey | LinkedNetworkResponseKey]: ...
} & { readonly id?: DataId; };

// After: plain string index signature (GraphQL + SQL)
export type NetworkResponseObject = {
  readonly [key: string]: undefined | NetworkResponseValue;
} & {
  readonly id?: DataId | number;  // SQL uses numeric IDs
  readonly __typename?: TypeName;
};

This is zero-breaking-change: GraphQL types still satisfy the wider constraint due to TypeScript structural typing.

4. CI and Build Fixes

• swc / serde incompatibility: substrait 0.62 transitively pulled in serde 1.0.220+ which broke swc_common 2.0.1. Fixed by updating swc workspace deps to versions compatible with the new serde.
• Clippy needless_return: CI runs with RUSTFLAGS=-D warnings; removed the redundant return statement that was failing the build.
• pnpm frozen-lockfile: Added @playwright/test to sqlite-demo/package.json without updating the lockfile; fixed by running pnpm install.
• protoc: Substrait code generation requires protoc; added installation to the CI cargo-test and cargo-clippy jobs.
• Prettier / oxlint: Formatted files and fixed a type-only import in App.tsx.

5. Test Fixtures and E2E Tests

• test-fixtures/databases/ — SQLite schema and init scripts for Phase 1–3 test progression
• demos/sqlite-demo/e2e/phase1-sql.spec.ts — Playwright E2E tests validating:
  • Page loads and displays planet data from SQL query
  • isograph-server /query endpoint is called
  • Error handling and graceful degradation

---

Key Files

File	Purpose
crates/sql_network_protocol/src/sql_network_protocol.rs	NetworkProtocol impl for SQL
crates/sql_network_protocol/src/query_generation/logical_plan_builder.rs	MergedSelectionMap → DataFusion LogicalPlan
crates/sql_network_protocol/src/substrait/serialize.rs	LogicalPlan → Substrait binary
crates/isograph_server/src/main.rs	Axum HTTP server
crates/artifact_content/src/entrypoint_artifact.rs	Compiler: generates query_plan.bin
crates/artifact_content/src/raw_response_type.rs	Compiler: generates typed raw response types
libs/isograph-react/src/core/cache.ts	Runtime: NetworkResponseObject type widening
demos/sqlite-demo/	End-to-end demo
test-fixtures/databases/	SQLite test database fixtures

---

What Phase 1 Does NOT Include (Future Phases)

• WHERE clauses / filtering (Phase 2)

• JOINs / linked fields (Phase 3)

• Mutations (Phase 4)

• Subscriptions / live queries (Phase 5)

• Connection pooling (isograph-server currently opens a new connection per request)