Summary

Fixes SQL compilation for on-demand sync to properly encode column names using the configured columnMapper. Previously, queries with camelCase property names would generate incorrect SQL when snakeCamelMapper was configured. Also adds developer warnings when on-demand collections are passed directly to useLiveQuery without a query builder.

Root Cause

When using snakeCamelMapper (which converts between camelCase JS properties and snake_case DB columns), the SQL compiler was not applying the encoding transformation. For example:

// User writes a query using camelCase (JS convention):
q.from({ p: programs }).where(({ p }) => p.programTemplateId === someId)

// SQL was incorrectly generated as:
// WHERE "programTemplateId" = $1  ❌ (column doesn't exist in Postgres)

// Should be:
// WHERE "program_template_id" = $1  ✅

The columnMapper.encode function existed and was used during data sync, but was never passed to the SQL compilation step.

Approach

SQL Compiler Enhancement:

• Added optional encodeColumnName parameter to compileSQL()
• Threading the encoder through all expression compilation functions (compileBasicExpression, compileOrderBy, compileFunction)
• Applied encoding in quoteIdentifier() before quoting column names

Integration:

• createLoadSubsetDedupe() now receives shapeOptions.columnMapper?.encode
• All compileSQL() calls pass the compile options when encoding is available

Developer Experience:

• Added console warnings in React, Vue, and Svelte useLiveQuery hooks when an on-demand collection is passed directly (which loads no data since there's no predicate)

Key Invariants

1. Column names in generated SQL must match the actual database column names
2. The columnMapper transformation must be applied consistently: during sync (already worked) AND during query compilation (this fix)
3. When no columnMapper is configured, column names pass through unchanged

Non-goals

• Did not change how columnMapper works for data sync (already correct)
• Did not add runtime validation that column names exist in the schema
• Did not make the on-demand + direct collection usage an error (just a warning)

Trade-offs

Warning vs Error for on-demand misuse: Chose a warning because some developers might intentionally pass an on-demand collection and rely on external mechanisms to load data. An error would be breaking; a warning educates without blocking.

Verification

pnpm test --filter @tanstack/electric-db-collection

The new tests in sql-compiler.test.ts verify:

• camelCase → snake_case encoding in WHERE clauses
• Encoding in ORDER BY clauses
• Encoding in IS NULL / IS NOT NULL expressions
• Encoding in nested AND/OR expressions
• Encoding in LIKE expressions
• No transformation when encoder is absent

Files Changed