@lix-js/sdk 0.6.0-preview.3 → 0.6.0-preview.4

package/SKILL.md

@@ -13,6 +13,7 @@ Current `@lix-js/sdk` capabilities:
 
 - Register JSON schemas as tracked entity tables.
 - Read and write entities through generated SQL tables.
+- Group related writes in explicit transactions so they commit once.
 - Create named versions of state and write/read across versions.
 - Merge one version into the active version.
 - Query `lix_change` for history, audit, activity feeds, and undo-style features.
@@ -34,6 +35,7 @@ Use this skill when you need to write or debug consumer code using `@lix-js/sdk`
 - Opening a persistent `.lix` file.
 - Registering schemas.
 - Writing and reading generated SQL entity tables.
+- Grouping imports, migrations, and batch writes into one transaction.
 - Reading `execute()` results.
 - Creating, switching, previewing, and merging versions.
 - Querying history through `lix_change`.
@@ -47,9 +49,10 @@ Do not use this skill for raw SQLite access, private engine/wasm internals, SDK
 2. Open with `createBetterSqlite3Backend({ path })`; do not open `.lix` with raw SQLite.
 3. Register a schema with `x-lix-key`, `x-lix-primary-key`, and `additionalProperties: false`.
 4. Write rows through the generated table named by `x-lix-key`.
-5. Use `<schema>_by_version` plus `lixcol_version_id` for side-by-side version reads/writes.
-6. Query `lix_change` for audit/history instead of hand-rolling audit tables.
-7. Wrap `mergeVersion()` in `try/catch` whenever conflicts are possible.
+5. Use `beginTransaction()` for imports, migrations, and multi-row writes that should be one commit.
+6. Use `<schema>_by_version` plus `lixcol_version_id` for side-by-side version reads/writes.
+7. Query `lix_change` for audit/history instead of hand-rolling audit tables.
+8. Wrap `mergeVersion()` in `try/catch` whenever conflicts are possible.
 
 ## Core Rules
 
@@ -58,6 +61,8 @@ Do not use this skill for raw SQLite access, private engine/wasm internals, SDK
 - Use numbered SQL placeholders: `$1`, `$2`, `$3`; bare `?` is rejected.
 - Use `lix_json($1)` when inserting JSON text into JSON-typed columns.
 - Use scalar SQL functions `SELECT lix_uuid_v7()` and `SELECT lix_timestamp()` when consumer code needs Lix-generated UUID v7 ids or ISO timestamps. Do not call them as table functions with `SELECT * FROM ...`.
+- Use `beginTransaction()` for batch writes. One `lix.execute()` write is one transaction and therefore one commit.
+- Do not call `execute()` through the parent `lix` handle while a transaction is active; use the transaction handle for reads and writes until `commit()` or `rollback()`.
 - Use stable, namespaced, lowercase schema keys like `acme_section`, not generic names like `task`.
 - Always include `x-lix-primary-key` and `additionalProperties: false` on app schemas.
 - Use version names from the user's vocabulary, such as `"Marketing edit"` or `"Q3 pricing draft"`.
@@ -203,6 +208,38 @@ Accessors return `undefined` when the cell kind does not match. Branch on `value
 
 `Row` also has convenience methods when native JS values are enough: `get(name)`, `tryGet(name)`, `getAt(index)`, `toObject()`, and `toValueMap()`.
 
+## Transactions
+
+Use `beginTransaction()` whenever several writes belong to one logical operation: CSV imports, seed scripts, migrations, bulk updates, or multi-table changes. A write through `lix.execute()` opens and commits its own transaction, so thousands of separate `execute()` writes become thousands of commits. A transaction handle stages those writes and commits them together.
+
+```ts
+const tx = await lix.beginTransaction();
+
+try {
+  for (const note of notes) {
+    await tx.execute(
+      "INSERT INTO acme_note (id, title, done) VALUES ($1, $2, $3)",
+      [note.id, note.title, false],
+    );
+  }
+
+  await tx.commit();
+} catch (error) {
+  await tx.rollback();
+  throw error;
+}
+```
+
+Transaction rules:
+
+- `tx.execute()` has the same result shape as `lix.execute()`.
+- Writes are visible to later reads on the same transaction before commit.
+- `commit()` makes the whole transaction durable as one commit.
+- `rollback()` drops the staged writes.
+- After `commit()` or `rollback()`, the transaction handle is closed and cannot be reused.
+- A Lix handle allows one active transaction at a time. While it is active, use `tx.execute()` for reads and writes; parent-handle `lix.execute()` is rejected until the transaction closes.
+- Do not use a callback-style transaction helper. The JS SDK mirrors the Rust SDK shape: explicitly `beginTransaction()`, then `commit()` or `rollback()`.
+
 ## Registering Schemas
 
 Register app schemas by inserting JSON into `lix_registered_schema.value`:
@@ -453,6 +490,8 @@ Other UDFs, such as `lix_json_get`, `lix_uuid_v7`, `lix_text_encode`, and `lix_e
 | Use public imports from `@lix-js/sdk` and `@lix-js/sdk/sqlite`. | Importing `engine-wasm` or private internals. |
 | Use `$1`, `$2`, `$3` placeholders. | Bare `?` placeholders. |
 | Use `lix_json($1)` for JSON parameters. | Inlining stringified JSON directly into SQL. |
+| Use `beginTransaction()` for imports and batch writes that should be one commit. | Loops of standalone `lix.execute()` writes for bulk imports. |
+| Use the transaction handle for reads and writes until it commits or rolls back. | Calling parent-handle `execute()` during an active transaction. |
 | Use `_by_version` for cross-version reads/writes. | Switching versions just to render a side-by-side view. |
 | Name versions in user vocabulary. | User-facing words like branch, branch-1, or generic Draft. |
 | Model collaborative data as small rows. | One giant row when multiple reviewers edit different parts. |

package/dist/engine-wasm/wasm/lix_engine.d.ts

@@ -12,6 +12,10 @@ export class Lix {
      * @returns {Promise<string>}
      */
     activeVersionId(): Promise<string>;
+    /**
+     * @returns {Promise<LixTransaction>}
+     */
+    beginTransaction(): Promise<LixTransaction>;
     /**
      * @returns {Promise<void>}
      */
@@ -25,7 +29,7 @@ export class Lix {
      * Executes one DataFusion SQL statement against this Lix session.
      *
      * The SQL dialect is DataFusion SQL, not SQLite SQL. Positional
-     * placeholders use `$1`, `$2`, and so on. SQLite-specific catalog
+     * placeholders use `?` or `$1`, `$2`, and so on. SQLite-specific catalog
      * tables and transaction statements such as `sqlite_master`, `BEGIN`,
      * and `COMMIT` are not part of this contract; use
      * `information_schema` for catalog inspection.
@@ -50,6 +54,26 @@ export class Lix {
      */
     switchVersion(args: any): Promise<any>;
 }
+export class LixTransaction {
+    static __wrap(ptr: any): any;
+    __destroy_into_raw(): number | undefined;
+    __wbg_ptr: number | undefined;
+    free(): void;
+    /**
+     * @returns {Promise<void>}
+     */
+    commit(): Promise<void>;
+    /**
+     * @param {any} sql
+     * @param {any} params
+     * @returns {Promise<any>}
+     */
+    execute(sql: any, params: any): Promise<any>;
+    /**
+     * @returns {Promise<void>}
+     */
+    rollback(): Promise<void>;
+}
 export function initSync(module: any): any;
 declare function __wbg_init(module_or_path: any): Promise<any>;
 export { __wbg_init as default };

package/dist/engine-wasm/wasm/lix_engine.js

@@ -24,6 +24,13 @@ export class Lix {
         const ret = wasm.lix_activeVersionId(this.__wbg_ptr);
         return ret;
     }
+    /**
+     * @returns {Promise<LixTransaction>}
+     */
+    beginTransaction() {
+        const ret = wasm.lix_beginTransaction(this.__wbg_ptr);
+        return ret;
+    }
     /**
      * @returns {Promise<void>}
      */
@@ -43,7 +50,7 @@ export class Lix {
      * Executes one DataFusion SQL statement against this Lix session.
      *
      * The SQL dialect is DataFusion SQL, not SQLite SQL. Positional
-     * placeholders use `$1`, `$2`, and so on. SQLite-specific catalog
+     * placeholders use `?` or `$1`, `$2`, and so on. SQLite-specific catalog
      * tables and transaction statements such as `sqlite_master`, `BEGIN`,
      * and `COMMIT` are not part of this contract; use
      * `information_schema` for catalog inspection.
@@ -82,6 +89,50 @@ export class Lix {
 }
 if (Symbol.dispose)
     Lix.prototype[Symbol.dispose] = Lix.prototype.free;
+export class LixTransaction {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(LixTransaction.prototype);
+        obj.__wbg_ptr = ptr;
+        LixTransactionFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        LixTransactionFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_lixtransaction_free(ptr, 0);
+    }
+    /**
+     * @returns {Promise<void>}
+     */
+    commit() {
+        const ret = wasm.lixtransaction_commit(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @param {any} sql
+     * @param {any} params
+     * @returns {Promise<any>}
+     */
+    execute(sql, params) {
+        const ret = wasm.lixtransaction_execute(this.__wbg_ptr, sql, params);
+        return ret;
+    }
+    /**
+     * @returns {Promise<void>}
+     */
+    rollback() {
+        const ret = wasm.lixtransaction_rollback(this.__wbg_ptr);
+        return ret;
+    }
+}
+if (Symbol.dispose)
+    LixTransaction.prototype[Symbol.dispose] = LixTransaction.prototype.free;
 /**
  * @param {any | null} [args]
  * @returns {Promise<Lix>}
@@ -295,6 +346,10 @@ function __wbg_get_imports() {
             const ret = Lix.__wrap(arg0);
             return ret;
         },
+        __wbg_lixtransaction_new: function (arg0) {
+            const ret = LixTransaction.__wrap(arg0);
+            return ret;
+        },
         __wbg_new_0_73afc35eb544e539: function () {
             const ret = new Date();
             return ret;
@@ -482,6 +537,9 @@ function wasm_bindgen__convert__closures_____invoke__h14bc79029e3672a5(arg0, arg
 const LixFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => { }, unregister: () => { } }
     : new FinalizationRegistry(ptr => wasm.__wbg_lix_free(ptr >>> 0, 1));
+const LixTransactionFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => { }, unregister: () => { } }
+    : new FinalizationRegistry(ptr => wasm.__wbg_lixtransaction_free(ptr >>> 0, 1));
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();
     wasm.__wbindgen_externrefs.set(idx, obj);

package/dist/engine-wasm/wasm/lix_engine.wasm.d.ts

@@ -2,13 +2,18 @@
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
 export const __wbg_lix_free: (a: number, b: number) => void;
+export const __wbg_lixtransaction_free: (a: number, b: number) => void;
 export const lix_activeVersionId: (a: number) => any;
+export const lix_beginTransaction: (a: number) => any;
 export const lix_close: (a: number) => any;
 export const lix_createVersion: (a: number, b: any) => any;
 export const lix_execute: (a: number, b: any, c: any) => any;
 export const lix_mergeVersion: (a: number, b: any) => any;
 export const lix_mergeVersionPreview: (a: number, b: any) => any;
 export const lix_switchVersion: (a: number, b: any) => any;
+export const lixtransaction_commit: (a: number) => any;
+export const lixtransaction_execute: (a: number, b: any, c: any) => any;
+export const lixtransaction_rollback: (a: number) => any;
 export const openLix: (a: number) => any;
 export const wasm_bindgen__closure__destroy__h259bf120b5b35fc5: (a: number, b: number) => void;
 export const wasm_bindgen__convert__closures_____invoke__h14bc79029e3672a5: (a: number, b: number, c: any, d: any) => void;

package/dist/open-lix.d.ts

@@ -185,11 +185,13 @@ export type Lix = {
      * Executes one DataFusion SQL statement against this Lix session.
      *
      * This is not SQLite SQL. Use the DataFusion SQL dialect; positional
-     * placeholders are `$1`, `$2`, and so on. SQLite-specific catalog tables and
+     * placeholders are `?` or `$1`, `$2`, and so on. SQLite-specific catalog tables and
      * transaction statements such as `sqlite_master`, `BEGIN`, and `COMMIT` are
-     * not available. Use `information_schema` for catalog inspection.
+     * not available. Use `information_schema` for catalog inspection. While a
+     * transaction is active, call `execute()` on the transaction handle instead.
      */
     execute(sql: string, params?: ReadonlyArray<LixRuntimeValue>): Promise<ExecuteResult>;
+    beginTransaction(): Promise<LixTransaction>;
     activeVersionId(): Promise<string>;
     createVersion(options: CreateVersionOptions): Promise<CreateVersionResult>;
     switchVersion(options: SwitchVersionOptions): Promise<SwitchVersionResult>;
@@ -197,4 +199,9 @@ export type Lix = {
     mergeVersion(options: MergeVersionOptions): Promise<MergeVersionResult>;
     close(): Promise<void>;
 };
+export type LixTransaction = {
+    execute(sql: string, params?: ReadonlyArray<LixRuntimeValue>): Promise<ExecuteResult>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+};
 export declare function openLix(options?: OpenLixOptions): Promise<Lix>;

package/dist/open-lix.js

@@ -125,6 +125,10 @@ function createLixHandle(wasmLix) {
             const result = await runQueued(() => wasmLix.execute(sql, values));
             return normalizeExecuteResult(result);
         },
+        async beginTransaction() {
+            const wasmTransaction = await runQueued(() => wasmLix.beginTransaction());
+            return createLixTransactionHandle(wasmTransaction, runQueued);
+        },
         async activeVersionId() {
             return await runQueued(() => wasmLix.activeVersionId());
         },
@@ -145,6 +149,41 @@ function createLixHandle(wasmLix) {
         },
     };
 }
+function createLixTransactionHandle(wasmTransaction, runQueued) {
+    let closed = false;
+    const ensureOpen = () => {
+        if (closed) {
+            throw createLixError("LIX_INVALID_TRANSACTION_STATE", "Lix transaction is closed");
+        }
+    };
+    return {
+        async execute(sql, params = []) {
+            ensureOpen();
+            validateExecuteArguments(sql, params);
+            const values = params.map((param, index) => valueFromExecuteParam(param, index));
+            const result = await runQueued(() => wasmTransaction.execute(sql, values));
+            return normalizeExecuteResult(result);
+        },
+        async commit() {
+            ensureOpen();
+            try {
+                await runQueued(() => wasmTransaction.commit());
+            }
+            finally {
+                closed = true;
+            }
+        },
+        async rollback() {
+            ensureOpen();
+            try {
+                await runQueued(() => wasmTransaction.rollback());
+            }
+            finally {
+                closed = true;
+            }
+        },
+    };
+}
 function validateExecuteArguments(sql, params) {
     if (typeof sql !== "string") {
         throw invalidArgumentError("execute", "sql", "string", sql);

package/dist-engine-src/src/lib.rs

@@ -55,7 +55,7 @@ pub use session::{
     CreateVersionOptions, CreateVersionReceipt, MergeChangeStats, MergeConflict,
     MergeConflictChangeKind, MergeConflictKind, MergeConflictSide, MergeVersionOptions,
     MergeVersionOutcome, MergeVersionPreview, MergeVersionPreviewOptions, MergeVersionReceipt,
-    SessionContext, SwitchVersionOptions, SwitchVersionReceipt,
+    SessionContext, SessionTransaction, SwitchVersionOptions, SwitchVersionReceipt,
 };
 pub use session::{ExecuteResult, Row, RowRef, TryFromValue};
 

package/dist-engine-src/src/session/context.rs

@@ -25,6 +25,8 @@ use crate::version::{
 use crate::GLOBAL_VERSION_ID;
 use crate::{LixError, NullableKeyFilter};
 
+use super::transaction::transaction_state_error;
+
 pub(crate) const WORKSPACE_VERSION_KEY: &str = "lix_workspace_version_id";
 
 #[derive(Clone)]
@@ -36,13 +38,10 @@ pub(crate) enum SessionMode {
 /// Session-context state for engine execution.
 ///
 /// A session context pins the active version selector and shared execution
-/// services. Each call to `execute(...)` projects this state into a read-only
-/// SQL context or a transaction-owned write context.
-///
-/// Write transaction invariant: any engine operation that may write must enter
-/// through `SessionContext::with_write_transaction`. Reads that influence writes
-/// are only available from that transaction capability, not from session-level
-/// helpers.
+/// services. Parent-handle `execute(...)` runs as an implicit single-statement
+/// transaction. Explicit transactions hold the session execution lease until
+/// commit or rollback, so all SQL during that window must run through the
+/// transaction handle.
 #[derive(Clone)]
 pub struct SessionContext {
     pub(super) mode: SessionMode,
@@ -54,6 +53,7 @@ pub struct SessionContext {
     pub(super) version_ctx: Arc<VersionContext>,
     pub(super) catalog_context: Arc<CatalogContext>,
     closed: Arc<AtomicBool>,
+    active_transaction: Arc<AtomicBool>,
 }
 
 impl SessionContext {
@@ -124,6 +124,7 @@ impl SessionContext {
             version_ctx,
             catalog_context,
             Arc::new(AtomicBool::new(false)),
+            Arc::new(AtomicBool::new(false)),
         )
     }
 
@@ -137,6 +138,7 @@ impl SessionContext {
         version_ctx: Arc<VersionContext>,
         catalog_context: Arc<CatalogContext>,
         closed: Arc<AtomicBool>,
+        active_transaction: Arc<AtomicBool>,
     ) -> Self {
         Self {
             mode,
@@ -148,6 +150,7 @@ impl SessionContext {
             version_ctx,
             catalog_context,
             closed,
+            active_transaction,
         }
     }
 
@@ -166,6 +169,10 @@ impl SessionContext {
         Arc::clone(&self.closed)
     }
 
+    pub(crate) fn active_transaction_flag(&self) -> Arc<AtomicBool> {
+        Arc::clone(&self.active_transaction)
+    }
+
     pub(crate) fn ensure_open(&self) -> Result<(), LixError> {
         if self.is_closed() {
             return Err(closed_error());
@@ -277,6 +284,16 @@ impl SessionContext {
         ) -> Pin<Box<dyn Future<Output = Result<T, LixError>> + 'tx>>,
     {
         self.ensure_open()?;
+        let _transaction_guard = self.reserve_session_transaction()?;
+        self.with_write_transaction_reserved(f).await
+    }
+
+    pub(crate) async fn with_write_transaction_reserved<T, F>(&self, f: F) -> Result<T, LixError>
+    where
+        F: for<'tx> FnOnce(
+            &'tx mut Transaction,
+        ) -> Pin<Box<dyn Future<Output = Result<T, LixError>> + 'tx>>,
+    {
         let opened = open_transaction(
             &self.mode,
             self.storage.clone(),
@@ -302,6 +319,19 @@ impl SessionContext {
             }
         }
     }
+
+    pub(super) fn reserve_session_transaction(&self) -> Result<SessionTransactionGuard, LixError> {
+        let active_transaction = self.active_transaction_flag();
+        if active_transaction
+            .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
+            .is_err()
+        {
+            return Err(transaction_state_error(
+                "Lix handle has an active transaction; use the transaction handle for reads and writes until it is committed or rolled back",
+            ));
+        }
+        Ok(SessionTransactionGuard { active_transaction })
+    }
 }
 
 fn closed_error() -> LixError {
@@ -309,6 +339,16 @@ fn closed_error() -> LixError {
         .with_hint("Open a new Lix handle before calling this method.")
 }
 
+pub(super) struct SessionTransactionGuard {
+    active_transaction: Arc<AtomicBool>,
+}
+
+impl Drop for SessionTransactionGuard {
+    fn drop(&mut self) {
+        self.active_transaction.store(false, Ordering::SeqCst);
+    }
+}
+
 /// Read-only SQL execution context derived from a session.
 ///
 /// Write statements re-plan against `Transaction`; this context intentionally

package/dist-engine-src/src/session/execute.rs

@@ -6,6 +6,7 @@ use crate::storage::{StorageReadScope, StorageWriteSet};
 use crate::{LixError, LixNotice, SqlQueryResult, Value};
 
 use super::context::{SessionContext, SessionSqlExecutionContext};
+use super::transaction::SessionTransaction;
 
 /// Result of executing one SQL statement through engine.
 ///
@@ -290,24 +291,27 @@ impl SessionContext {
     /// Executes one DataFusion SQL statement against this Lix session.
     ///
     /// The SQL dialect is DataFusion SQL, not SQLite SQL. Positional
-    /// placeholders use `$1`, `$2`, and so on. SQLite-specific catalog tables
+    /// placeholders use `?` or `$1`, `$2`, and so on. SQLite-specific catalog tables
     /// and transaction statements such as `sqlite_master`, `BEGIN`, and
     /// `COMMIT` are not part of this contract; use `information_schema` for
     /// catalog inspection. Lix owns transaction boundaries for each statement.
     pub async fn execute(&self, sql: &str, params: &[Value]) -> Result<ExecuteResult, LixError> {
         self.ensure_open()?;
-        let kind = sql2::classify_statement(sql)?;
+        let _transaction_guard = self.reserve_session_transaction()?;
+        let statement = sql2::parse_statement(sql)?;
+        let kind = sql2::classify_datafusion_statement(&statement);
         if kind == sql2::SqlStatementKind::Write {
-            let sql = sql.to_string();
-            let sql_for_error = sql.clone();
+            let sql_for_error = sql.to_string();
             let params = params.to_vec();
             return self
-                .with_write_transaction(|transaction| {
+                .with_write_transaction_reserved(|transaction| {
                     Box::pin(async move {
                         // Re-plan against the transaction-backed write
                         // session so provider hooks read and stage through the
                         // transaction-owned SQL write context.
-                        let tx_plan = sql2::create_write_logical_plan(transaction, &sql).await?;
+                        let tx_plan =
+                            sql2::create_write_logical_plan_from_parsed(transaction, statement)
+                                .await?;
                         let result = sql2::execute_logical_plan(tx_plan, &params).await?;
                         let affected_rows = affected_rows_from_query_result(result)?;
                         Ok(ExecuteResult::from_rows_affected(affected_rows))
@@ -316,6 +320,12 @@ impl SessionContext {
                 .await
                 .map_err(|error| normalize_sql_surface_error(error, &sql_for_error));
         }
+        if kind == sql2::SqlStatementKind::Other {
+            return Err(LixError::new(
+                LixError::CODE_UNSUPPORTED_SQL,
+                "SQL statement is not supported by Lix SQL",
+            ));
+        }
 
         let read_scope = StorageReadScope::new(self.storage.begin_read_transaction().await?);
         let read_result = async {
@@ -340,7 +350,7 @@ impl SessionContext {
                 functions: functions.clone(),
             };
 
-            let plan = sql2::create_logical_plan(&ctx, sql).await?;
+            let plan = sql2::create_logical_plan_from_parsed(&ctx, sql, statement).await?;
             let result = sql2::execute_logical_plan(plan, params).await?;
             drop(ctx);
             drop(live_state);
@@ -371,18 +381,71 @@ impl SessionContext {
         &self,
         runtime_functions: &FunctionContext,
     ) -> Result<(), LixError> {
-        let mut transaction = self.storage.begin_write_transaction().await?;
         let mut writes = StorageWriteSet::new();
         runtime_functions
             .stage_persist_if_needed(&mut writes)
             .await?;
-        if !writes.is_empty() {
-            writes.apply(&mut transaction.as_mut()).await?;
+        if writes.is_empty() {
+            return Ok(());
         }
+        let mut transaction = self.storage.begin_write_transaction().await?;
+        writes.apply(&mut transaction.as_mut()).await?;
         transaction.commit().await
     }
 }
 
+impl SessionTransaction {
+    /// Executes one SQL statement inside this transaction.
+    ///
+    /// Write statements are staged until `commit()`. Read statements use the
+    /// transaction overlay, so they can observe writes staged by earlier calls
+    /// on this transaction handle.
+    pub async fn execute(
+        &mut self,
+        sql: &str,
+        params: &[Value],
+    ) -> Result<ExecuteResult, LixError> {
+        let statement = sql2::parse_statement(sql)?;
+        let kind = sql2::classify_datafusion_statement(&statement);
+        let transaction = self.transaction_mut()?;
+        match kind {
+            sql2::SqlStatementKind::Write => {
+                execute_transaction_write(transaction, statement, params)
+                    .await
+                    .map_err(|error| normalize_sql_surface_error(error, sql))
+            }
+            sql2::SqlStatementKind::Read => {
+                let plan = sql2::create_transaction_read_logical_plan_from_parsed(
+                    transaction,
+                    sql,
+                    statement,
+                )
+                .await
+                .map_err(|error| normalize_sql_surface_error(error, sql))?;
+                let result = sql2::execute_logical_plan(plan, params)
+                    .await
+                    .map_err(|error| normalize_sql_surface_error(error, sql))?;
+                Ok(ExecuteResult::from_sql_query_result(result))
+            }
+            sql2::SqlStatementKind::Other => Err(LixError::new(
+                LixError::CODE_UNSUPPORTED_SQL,
+                "SQL statement is not supported by Lix SQL",
+            )),
+        }
+    }
+}
+
+async fn execute_transaction_write(
+    transaction: &mut crate::transaction::Transaction,
+    statement: datafusion::sql::parser::Statement,
+    params: &[Value],
+) -> Result<ExecuteResult, LixError> {
+    let tx_plan = sql2::create_write_logical_plan_from_parsed(transaction, statement).await?;
+    let result = sql2::execute_logical_plan(tx_plan, params).await?;
+    let affected_rows = affected_rows_from_query_result(result)?;
+    Ok(ExecuteResult::from_rows_affected(affected_rows))
+}
+
 fn normalize_sql_surface_error(error: LixError, sql: &str) -> LixError {
     if error.code.starts_with("LIX_ERROR_PATH_") && sql_uses_public_filesystem_path_surface(sql) {
         return LixError {

package/dist-engine-src/src/session/mod.rs

@@ -1,11 +1,9 @@
 //! Engine session boundary.
 //!
-//! Transaction invariant:
-//! any engine operation that may write must enter through
-//! `SessionContext::with_write_transaction`. Reads that influence writes are
-//! only available from the transaction capability. Session APIs must not
-//! open `Transaction` directly or use session-level read helpers inside write
-//! flows.
+//! Transaction invariant: a session has one execution lease. Parent-handle
+//! calls use it for implicit single-statement execution; explicit transactions
+//! hold it until commit or rollback. Session APIs must not open `Transaction`
+//! directly or use session-level read helpers inside write flows.
 
 mod context;
 mod create_version;
@@ -14,6 +12,7 @@ mod merge;
 #[cfg(feature = "storage-benches")]
 pub mod optimization9_sql2_bench;
 mod switch_version;
+mod transaction;
 
 pub use context::SessionContext;
 pub(crate) use context::{SessionMode, WORKSPACE_VERSION_KEY};
@@ -25,3 +24,4 @@ pub use merge::{
     MergeVersionReceipt,
 };
 pub use switch_version::{SwitchVersionOptions, SwitchVersionReceipt};
+pub use transaction::SessionTransaction;

package/dist-engine-src/src/session/switch_version.rs

@@ -75,6 +75,7 @@ impl SessionContext {
             Arc::clone(&self.version_ctx),
             Arc::clone(&self.catalog_context),
             self.closed_flag(),
+            self.active_transaction_flag(),
         );
         Ok((
             session,

package/dist-engine-src/src/session/transaction.rs

@@ -0,0 +1,76 @@
+use std::sync::Arc;
+
+use crate::functions::FunctionContext;
+use crate::transaction::{open_transaction, Transaction};
+use crate::LixError;
+
+use super::context::SessionTransactionGuard;
+use super::SessionContext;
+
+pub struct SessionTransaction {
+    pub(super) transaction: Option<Transaction>,
+    pub(super) runtime_functions: FunctionContext,
+    _transaction_guard: SessionTransactionGuard,
+}
+
+impl SessionContext {
+    pub async fn begin_transaction(&self) -> Result<SessionTransaction, LixError> {
+        self.ensure_open()?;
+        let transaction_guard = self.reserve_session_transaction()?;
+        let opened = match open_transaction(
+            &self.mode,
+            self.storage.clone(),
+            Arc::clone(&self.live_state),
+            Arc::clone(&self.tracked_state),
+            Arc::clone(&self.binary_cas),
+            Arc::clone(&self.commit_store),
+            Arc::clone(&self.version_ctx),
+            Arc::clone(&self.catalog_context),
+        )
+        .await
+        {
+            Ok(opened) => opened,
+            Err(error) => {
+                return Err(error);
+            }
+        };
+        Ok(SessionTransaction {
+            transaction: Some(opened.transaction),
+            runtime_functions: opened.runtime_functions,
+            _transaction_guard: transaction_guard,
+        })
+    }
+}
+
+impl SessionTransaction {
+    pub(super) fn transaction_mut(&mut self) -> Result<&mut Transaction, LixError> {
+        self.transaction
+            .as_mut()
+            .ok_or_else(|| transaction_state_error("Lix transaction is closed"))
+    }
+
+    pub async fn commit(mut self) -> Result<(), LixError> {
+        let transaction = self
+            .transaction
+            .take()
+            .ok_or_else(|| transaction_state_error("Lix transaction is closed"))?;
+        let result = transaction
+            .commit(&self.runtime_functions)
+            .await
+            .map(|_| ());
+        result
+    }
+
+    pub async fn rollback(mut self) -> Result<(), LixError> {
+        let transaction = self
+            .transaction
+            .take()
+            .ok_or_else(|| transaction_state_error("Lix transaction is closed"))?;
+        let result = transaction.rollback().await;
+        result
+    }
+}
+
+pub(crate) fn transaction_state_error(message: impl Into<String>) -> LixError {
+    LixError::new("LIX_INVALID_TRANSACTION_STATE", message)
+}

package/dist-engine-src/src/sql2/classify.rs

@@ -3,8 +3,6 @@ use datafusion::sql::sqlparser::ast::{
     FromTable, ObjectName, Query, SetExpr, Statement as SqlStatement, TableFactor, TableObject,
     TableWithJoins,
 };
-use datafusion::sql::sqlparser::dialect::GenericDialect;
-use datafusion::sql::sqlparser::parser::Parser;
 
 use crate::LixError;
 
@@ -15,30 +13,18 @@ pub(crate) enum SqlStatementKind {
     Other,
 }
 
-pub(crate) fn classify_statement(sql: &str) -> Result<SqlStatementKind, LixError> {
-    let statements = parse_sql_statements(sql)?;
-    let [statement] = statements.as_slice() else {
-        return Ok(SqlStatementKind::Other);
-    };
-    Ok(classify_ast_statement(statement))
-}
-
-pub(crate) fn validate_supported_statement_ast(sql: &str) -> Result<(), LixError> {
-    let statements = parse_sql_statements(sql)?;
-    let [statement] = statements.as_slice() else {
-        return Err(unsupported_sql_error(
-            "Lix SQL only supports one statement per execute() call",
-        ));
-    };
-    validate_supported_ast_statement(statement)
-}
-
 pub(crate) fn validate_supported_datafusion_statement_ast(
     statement: &DataFusionStatement,
 ) -> Result<(), LixError> {
     match statement {
         DataFusionStatement::Statement(statement) => validate_supported_ast_statement(statement),
         DataFusionStatement::Explain(explain) => {
+            if classify_datafusion_statement(explain.statement.as_ref()) == SqlStatementKind::Write
+            {
+                return Err(unsupported_sql_error(
+                    "EXPLAIN of write statements is not supported by Lix SQL",
+                ));
+            }
             validate_supported_datafusion_statement_ast(explain.statement.as_ref())
         }
         _ => Err(unsupported_sql_error(format!(
@@ -47,6 +33,14 @@ pub(crate) fn validate_supported_datafusion_statement_ast(
     }
 }
 
+pub(crate) fn classify_datafusion_statement(statement: &DataFusionStatement) -> SqlStatementKind {
+    match statement {
+        DataFusionStatement::Statement(statement) => classify_ast_statement(statement),
+        DataFusionStatement::Explain(_) => SqlStatementKind::Read,
+        _ => SqlStatementKind::Other,
+    }
+}
+
 pub(crate) fn datafusion_statement_dml_target_table_names(
     statement: &DataFusionStatement,
 ) -> Vec<String> {
@@ -55,15 +49,6 @@ pub(crate) fn datafusion_statement_dml_target_table_names(
     targets
 }
 
-fn parse_sql_statements(sql: &str) -> Result<Vec<SqlStatement>, LixError> {
-    Parser::parse_sql(&GenericDialect {}, sql).map_err(|error| {
-        LixError::new(
-            LixError::CODE_PARSE_ERROR,
-            format!("sql2 SQL parse error: {error}"),
-        )
-    })
-}
-
 fn collect_datafusion_statement_dml_target_table_names(
     statement: &DataFusionStatement,
     targets: &mut Vec<String>,
@@ -133,7 +118,7 @@ fn classify_ast_statement(statement: &SqlStatement) -> SqlStatementKind {
             SqlStatementKind::Write
         }
         SqlStatement::Query(_) => SqlStatementKind::Read,
-        SqlStatement::Explain { statement, .. } => classify_ast_statement(statement.as_ref()),
+        SqlStatement::Explain { .. } => SqlStatementKind::Read,
         _ => SqlStatementKind::Other,
     }
 }
@@ -142,7 +127,14 @@ fn validate_supported_ast_statement(statement: &SqlStatement) -> Result<(), LixE
     match statement {
         SqlStatement::Query(query) => validate_supported_query(query),
         SqlStatement::Insert(_) | SqlStatement::Update(_) | SqlStatement::Delete(_) => Ok(()),
-        SqlStatement::Explain { statement, .. } => validate_supported_ast_statement(statement),
+        SqlStatement::Explain { statement, .. } => {
+            if classify_ast_statement(statement.as_ref()) == SqlStatementKind::Write {
+                return Err(unsupported_sql_error(
+                    "EXPLAIN of write statements is not supported by Lix SQL",
+                ));
+            }
+            validate_supported_ast_statement(statement)
+        }
         _ => Err(unsupported_sql_error(format!(
             "SQL statement is not supported by Lix SQL: {statement}"
         ))),

package/dist-engine-src/src/sql2/error.rs

@@ -59,7 +59,7 @@ fn classify_datafusion_error(error: &DataFusionError) -> LixError {
 
     if looks_like_unsupported_dialect(&lower) {
         return LixError::new(LixError::CODE_DIALECT_UNSUPPORTED, message)
-            .with_hint("Lix SQL uses DataFusion syntax. Use lix_json_get(...) or lix_json_get_text(...) for JSON access, and numbered placeholders like $1, $2, ...");
+            .with_hint("Lix SQL uses DataFusion syntax. Use lix_json_get(...) or lix_json_get_text(...) for JSON access, and placeholders like ?, ? or $1, $2, ...");
     }
 
     if looks_like_unsupported_runtime_plan(&lower) {
@@ -76,9 +76,8 @@ fn classify_datafusion_error(error: &DataFusionError) -> LixError {
         || lower.contains("placeholder")
         || lower.contains("bind")
     {
-        return LixError::new(LixError::CODE_PARSE_ERROR, message).with_hint(
-            "Use numbered placeholders like $1, $2, ...; '?' placeholders are not supported.",
-        );
+        return LixError::new(LixError::CODE_PARSE_ERROR, message)
+            .with_hint("Use placeholders like ?, ? or numbered placeholders like $1, $2, ...");
     }
 
     if lower.contains("requires start_commit_id")

package/dist-engine-src/src/sql2/execute.rs

@@ -4,7 +4,9 @@ use datafusion::common::metadata::{FieldMetadata, ScalarAndMetadata};
 use datafusion::common::{ParamValues, ScalarValue};
 use datafusion::logical_expr::{Expr, LogicalPlan, WriteOp};
 use datafusion::prelude::SessionContext;
-use datafusion::sql::parser::Statement as DataFusionStatement;
+use datafusion::sql::parser::{DFParserBuilder, Statement as DataFusionStatement};
+use datafusion::sql::sqlparser::dialect::GenericDialect;
+use datafusion::sql::sqlparser::tokenizer::{Token, Tokenizer};
 use serde_json::{json, Value as JsonValue};
 use std::collections::{BTreeMap, BTreeSet, HashSet};
 
@@ -13,7 +15,7 @@ use crate::{LixError, LixNotice, SqlQueryResult, Value};
 
 use super::predicate_typecheck::validate_json_predicate_expr_with_dfschema;
 use super::result_metadata::{field_is_json, LIX_VALUE_TYPE_JSON, LIX_VALUE_TYPE_METADATA_KEY};
-use super::session::{build_read_session, build_write_session, new_sql_session_context};
+use super::session::{build_read_session, build_write_session};
 use super::write_normalization::{
     is_binary_type, lix_file_data_type_lix_error, logical_expr_is_binary_or_null,
 };
@@ -60,15 +62,24 @@ pub(crate) async fn create_logical_plan(
     ctx: &dyn SqlExecutionContext,
     sql: &str,
 ) -> Result<SqlLogicalPlan, LixError> {
-    super::validate_supported_statement_ast(sql)?;
-    super::udfs::validate_public_udf_calls(sql)?;
+    let statement = parse_statement(sql)?;
+    create_logical_plan_from_parsed(ctx, sql, statement).await
+}
+
+pub(crate) fn parse_statement(sql: &str) -> Result<DataFusionStatement, LixError> {
+    parse_datafusion_statement(sql)
+}
+
+pub(crate) async fn create_logical_plan_from_parsed(
+    ctx: &dyn SqlExecutionContext,
+    sql: &str,
+    statement: DataFusionStatement,
+) -> Result<SqlLogicalPlan, LixError> {
     validate_public_read_sql_surface(sql)?;
+    super::validate_supported_datafusion_statement_ast(&statement)?;
+    super::udfs::validate_public_udf_calls_in_datafusion_statement(&statement)?;
     let session = build_read_session(ctx).await?;
-    let plan = session
-        .state()
-        .create_logical_plan(sql)
-        .await
-        .map_err(datafusion_error_to_lix_error)?;
+    let plan = create_logical_plan_from_statement(&session, statement).await?;
     validate_supported_logical_plan(&plan)?;
     validate_json_predicates_in_logical_plan(&plan)?;
     let kind = classify_logical_plan(&plan);
@@ -88,10 +99,17 @@ pub(crate) async fn create_write_logical_plan(
     ctx: &mut dyn SqlWriteExecutionContext,
     sql: &str,
 ) -> Result<SqlLogicalPlan, LixError> {
-    super::udfs::validate_public_udf_calls(sql)?;
+    let statement = parse_statement(sql)?;
+    create_write_logical_plan_from_parsed(ctx, statement).await
+}
+
+pub(crate) async fn create_write_logical_plan_from_parsed(
+    ctx: &mut dyn SqlWriteExecutionContext,
+    statement: DataFusionStatement,
+) -> Result<SqlLogicalPlan, LixError> {
+    super::udfs::validate_public_udf_calls_in_datafusion_statement(&statement)?;
     let visible_schemas = ctx.list_visible_schemas()?;
-    super::public_bind::validate_public_dml_sql(sql, &visible_schemas)?;
-    let statement = parse_datafusion_statement(sql)?;
+    super::public_bind::validate_public_dml_statement(&statement, &visible_schemas)?;
     super::validate_supported_datafusion_statement_ast(&statement)?;
     reject_read_only_history_view_dml_from_statement(&statement, &visible_schemas)?;
     let session = build_write_session(ctx).await?;
@@ -111,6 +129,30 @@ pub(crate) async fn create_write_logical_plan(
     })
 }
 
+pub(crate) async fn create_transaction_read_logical_plan_from_parsed(
+    ctx: &mut dyn SqlWriteExecutionContext,
+    sql: &str,
+    statement: DataFusionStatement,
+) -> Result<SqlLogicalPlan, LixError> {
+    validate_public_read_sql_surface(sql)?;
+    super::validate_supported_datafusion_statement_ast(&statement)?;
+    super::udfs::validate_public_udf_calls_in_datafusion_statement(&statement)?;
+    let session = build_write_session(ctx).await?;
+    let plan = create_logical_plan_from_statement(&session, statement).await?;
+    validate_supported_logical_plan(&plan)?;
+    validate_json_predicates_in_logical_plan(&plan)?;
+    let kind = classify_logical_plan(&plan);
+    let notices = history_filter_notices(&plan);
+
+    Ok(SqlLogicalPlan {
+        session,
+        plan,
+        kind,
+        notices,
+        strict_binary_params: BTreeSet::new(),
+    })
+}
+
 fn validate_public_read_sql_surface(sql: &str) -> Result<(), LixError> {
     let normalized = sql.to_ascii_lowercase();
     if normalized.contains("lower(path)") {
@@ -131,12 +173,64 @@ fn validate_public_read_sql_surface(sql: &str) -> Result<(), LixError> {
 }
 
 fn parse_datafusion_statement(sql: &str) -> Result<DataFusionStatement, LixError> {
-    let session = new_sql_session_context();
-    let dialect = session.state().config_options().sql_parser.dialect;
-    session
-        .state()
-        .sql_to_statement(sql, &dialect)
-        .map_err(datafusion_error_to_lix_error)
+    let dialect = GenericDialect {};
+    let mut next_index = 1usize;
+    let mut has_anonymous = false;
+    let mut explicit_placeholders = Vec::new();
+
+    let mut tokens = Vec::new();
+    Tokenizer::new(&dialect, sql)
+        .tokenize_with_location_into_buf_with_mapper(&mut tokens, |mut token_span| {
+            if let Token::Placeholder(placeholder) = &token_span.token {
+                if placeholder == "?" {
+                    has_anonymous = true;
+                    token_span.token = Token::Placeholder(format!("${next_index}"));
+                    next_index += 1;
+                } else {
+                    explicit_placeholders.push(placeholder.clone());
+                }
+            }
+            token_span
+        })
+        .map_err(|error| {
+            LixError::new(
+                LixError::CODE_PARSE_ERROR,
+                format!("sql2 SQL tokenize error: {error}"),
+            )
+        })?;
+
+    if has_anonymous && !explicit_placeholders.is_empty() {
+        return Err(LixError::new(
+            LixError::CODE_PARSE_ERROR,
+            "SQL mixes anonymous and explicit parameter placeholders",
+        )
+        .with_hint("Use either anonymous placeholders like ?, ? or numbered placeholders like $1, $2, but not both.")
+        .with_details(json!({
+            "operation": "execute",
+            "explicit_placeholders": explicit_placeholders,
+        })));
+    }
+
+    let mut statements = DFParserBuilder::new(tokens)
+        .with_dialect(&dialect)
+        .build()
+        .map_err(datafusion_error_to_lix_error)?
+        .parse_statements()
+        .map_err(datafusion_error_to_lix_error)?;
+
+    if statements.len() > 1 {
+        return Err(LixError::new(
+            LixError::CODE_UNSUPPORTED_SQL,
+            "Lix SQL only supports one statement per execute() call",
+        ));
+    }
+
+    statements.pop_front().ok_or_else(|| {
+        LixError::new(
+            LixError::CODE_PARSE_ERROR,
+            "sql2 DataFusion error: No SQL statements were provided in the query string",
+        )
+    })
 }
 
 async fn create_logical_plan_from_statement(
@@ -267,7 +361,7 @@ fn placeholder_index(id: &str) -> Result<usize, LixError> {
                 LixError::CODE_PARSE_ERROR,
                 format!("unsupported SQL parameter placeholder '{id}'"),
             )
-            .with_hint("Use numbered placeholders like $1, $2, ...")
+            .with_hint("Use placeholders like ?, ? or numbered placeholders like $1, $2, ...")
         })
 }
 
@@ -362,7 +456,7 @@ fn expected_positional_parameter_count(
                 LixError::CODE_PARSE_ERROR,
                 format!("unsupported SQL parameter placeholder '{name}'"),
             )
-            .with_hint("Use numbered placeholders like $1, $2, ...")
+            .with_hint("Use placeholders like ?, ? or numbered placeholders like $1, $2, ...")
             .with_details(json!({
                 "operation": "execute",
                 "placeholder": name,
@@ -373,7 +467,7 @@ fn expected_positional_parameter_count(
                 LixError::CODE_PARSE_ERROR,
                 "SQL parameter placeholders are 1-indexed",
             )
-            .with_hint("Use numbered placeholders like $1, $2, ...")
+            .with_hint("Use placeholders like ?, ? or numbered placeholders like $1, $2, ...")
             .with_details(json!({
                 "operation": "execute",
                 "placeholder": name,
@@ -1870,7 +1964,6 @@ mod tests {
             "DELETE FROM lix_state_history",
             "DELETE FROM LIX_STATE_HISTORY",
             "DELETE FROM main.LIX_STATE_HISTORY",
-            "EXPLAIN DELETE FROM lix_state_history",
         ] {
             let blob_reader: Arc<dyn BlobDataReader> = Arc::new(DummyBlobReader);
             let live_state = Arc::new(DummyLiveStateReader);

package/dist-engine-src/src/sql2/mod.rs

@@ -30,9 +30,8 @@ mod version_scope;
 mod write_normalization;
 
 pub(crate) use classify::{
-    classify_statement, datafusion_statement_dml_target_table_names,
-    validate_supported_datafusion_statement_ast, validate_supported_statement_ast,
-    SqlStatementKind,
+    classify_datafusion_statement, datafusion_statement_dml_target_table_names,
+    validate_supported_datafusion_statement_ast, SqlStatementKind,
 };
 pub(crate) use context::{
     CommitStoreQuerySource, SqlCommitStoreQuerySource, SqlExecutionContext, SqlJsonReader,
@@ -41,6 +40,8 @@ pub(crate) use context::{
 };
 #[allow(unused_imports)]
 pub(crate) use execute::{
-    create_logical_plan, create_write_logical_plan, execute_logical_plan, execute_sql,
+    create_logical_plan, create_logical_plan_from_parsed,
+    create_transaction_read_logical_plan_from_parsed, create_write_logical_plan,
+    create_write_logical_plan_from_parsed, execute_logical_plan, execute_sql, parse_statement,
     SqlLogicalPlan,
 };

package/dist-engine-src/src/sql2/public_bind/dml.rs

@@ -1,10 +1,9 @@
 use datafusion::logical_expr::{LogicalPlan, WriteOp};
+use datafusion::sql::parser::Statement as DataFusionStatement;
 use datafusion::sql::sqlparser::ast::{
     Assignment, AssignmentTarget, Delete, FromTable, ObjectName, Statement, TableFactor,
     TableObject, TableWithJoins, Update,
 };
-use datafusion::sql::sqlparser::dialect::GenericDialect;
-use datafusion::sql::sqlparser::parser::Parser;
 use serde_json::Value as JsonValue;
 
 use crate::LixError;
@@ -30,18 +29,25 @@ impl DmlOperation {
     }
 }
 
-pub(crate) fn validate_sql(sql: &str, visible_schemas: &[JsonValue]) -> Result<(), LixError> {
-    let statements = Parser::parse_sql(&GenericDialect {}, sql).map_err(|error| {
-        LixError::new(
-            LixError::CODE_PARSE_ERROR,
-            format!("sql2 SQL parse error: {error}"),
-        )
-    })?;
-    let [statement] = statements.as_slice() else {
-        return Ok(());
-    };
+pub(crate) fn validate_datafusion_statement(
+    statement: &DataFusionStatement,
+    visible_schemas: &[JsonValue],
+) -> Result<(), LixError> {
     let contracts = PublicTableContracts::new(visible_schemas)?;
-    validate_statement(statement, &contracts)
+    validate_datafusion_statement_with_contracts(statement, &contracts)
+}
+
+fn validate_datafusion_statement_with_contracts(
+    statement: &DataFusionStatement,
+    contracts: &PublicTableContracts,
+) -> Result<(), LixError> {
+    match statement {
+        DataFusionStatement::Statement(statement) => validate_statement(statement, contracts),
+        DataFusionStatement::Explain(explain) => {
+            validate_datafusion_statement_with_contracts(explain.statement.as_ref(), contracts)
+        }
+        _ => Ok(()),
+    }
 }
 
 pub(crate) fn validate_plan(

package/dist-engine-src/src/sql2/public_bind/mod.rs

@@ -4,17 +4,18 @@ mod dml;
 mod table;
 
 use datafusion::logical_expr::LogicalPlan;
+use datafusion::sql::parser::Statement as DataFusionStatement;
 use serde_json::Value as JsonValue;
 
 use crate::LixError;
 
 pub(crate) use dml::DmlOperation;
 
-pub(crate) fn validate_public_dml_sql(
-    sql: &str,
+pub(crate) fn validate_public_dml_statement(
+    statement: &DataFusionStatement,
     visible_schemas: &[JsonValue],
 ) -> Result<(), LixError> {
-    dml::validate_sql(sql, visible_schemas)
+    dml::validate_datafusion_statement(statement, visible_schemas)
 }
 
 pub(crate) fn validate_public_dml_plan(

package/dist-engine-src/src/sql2/udfs/mod.rs

@@ -15,7 +15,7 @@ use datafusion::logical_expr::ScalarUDF;
 
 use crate::functions::FunctionProviderHandle;
 
-pub(crate) use public_call::validate_public_udf_calls;
+pub(crate) use public_call::validate_public_udf_calls_in_datafusion_statement;
 
 #[cfg(test)]
 pub(crate) fn system_sql2_function_provider() -> FunctionProviderHandle {

package/dist-engine-src/src/sql2/udfs/public_call.rs

@@ -1,14 +1,18 @@
 use std::ops::ControlFlow;
 
+use datafusion::sql::parser::Statement as DataFusionStatement;
 use datafusion::sql::sqlparser::ast::{
     Expr, Function, FunctionArg, FunctionArgExpr, FunctionArguments, ObjectNamePart, Statement,
     Value, Visit, Visitor,
 };
+#[cfg(test)]
 use datafusion::sql::sqlparser::dialect::GenericDialect;
+#[cfg(test)]
 use datafusion::sql::sqlparser::parser::Parser;
 
 use crate::LixError;
 
+#[cfg(test)]
 pub(crate) fn validate_public_udf_calls(sql: &str) -> Result<(), LixError> {
     let statements = Parser::parse_sql(&GenericDialect {}, sql).map_err(|error| {
         LixError::new(
@@ -68,6 +72,29 @@ fn validate_public_function_call(function: &Function) -> Result<(), LixError> {
     }
 }
 
+pub(crate) fn validate_public_udf_calls_in_datafusion_statement(
+    statement: &DataFusionStatement,
+) -> Result<(), LixError> {
+    let mut visitor = PublicUdfCallVisitor;
+    visit_datafusion_statement(statement, &mut visitor)
+}
+
+fn visit_datafusion_statement(
+    statement: &DataFusionStatement,
+    visitor: &mut PublicUdfCallVisitor,
+) -> Result<(), LixError> {
+    match statement {
+        DataFusionStatement::Statement(statement) => match statement.visit(visitor) {
+            ControlFlow::Continue(()) => Ok(()),
+            ControlFlow::Break(error) => Err(*error),
+        },
+        DataFusionStatement::Explain(explain) => {
+            visit_datafusion_statement(explain.statement.as_ref(), visitor)
+        }
+        _ => Ok(()),
+    }
+}
+
 fn public_lix_function_name(function: &Function) -> Option<&'static str> {
     let part = function.name.0.last()?;
     let ident = match part {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@lix-js/sdk",
 	"type": "module",
-	"version": "0.6.0-preview.3",
+	"version": "0.6.0-preview.4",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"files": [