@tursodatabase/serverless 1.0.0 → 1.1.0-pre.2

package/dist/compat.d.ts

@@ -87,11 +87,10 @@ export declare class LibsqlError extends Error {
     constructor(message: string, code: string, extendedCode?: string, rawCode?: number, cause?: Error);
 }
 /**
- * Interactive transaction interface (not implemented in serverless mode).
+ * Interactive transaction interface.
  *
  * @remarks
- * Transactions are not supported in the serverless compatibility layer.
- * Calling transaction() will throw a LibsqlError.
+ * A transaction keeps a dedicated session open until commit/rollback/close.
  */
 export interface Transaction {
     execute(stmt: InStatement): Promise<ResultSet>;

package/dist/compat.js

@@ -25,6 +25,7 @@ class LibSQLClient {
             authToken: config.authToken || '',
             remoteEncryptionKey: config.remoteEncryptionKey
         };
+        this.sessionConfig = sessionConfig;
         this.session = new Session(sessionConfig);
     }
     validateConfig(config) {
@@ -157,8 +158,124 @@ class LibSQLClient {
         // For now, just call batch - in a real implementation this would disable foreign keys
         return this.batch(stmts, "write");
     }
+    modeToBeginSql(mode) {
+        switch (mode) {
+            case "write":
+                return "BEGIN IMMEDIATE";
+            case "deferred":
+                return "BEGIN DEFERRED";
+            case "read":
+            default:
+                return "BEGIN";
+        }
+    }
     async transaction(mode) {
-        throw new LibsqlError("Transactions not implemented", "NOT_IMPLEMENTED");
+        await this.execLock.acquire();
+        if (this._closed) {
+            this.execLock.release();
+            throw new LibsqlError("Client is closed", "CLIENT_CLOSED");
+        }
+        const txSession = new Session(this.sessionConfig);
+        let txClosed = false;
+        let cleanupStarted = false;
+        const ensureOpen = () => {
+            if (txClosed) {
+                throw new LibsqlError("Transaction is closed", "TRANSACTION_CLOSED");
+            }
+        };
+        const closeTx = async () => {
+            if (cleanupStarted)
+                return;
+            cleanupStarted = true;
+            txClosed = true;
+            try {
+                await txSession.close();
+            }
+            finally {
+                this.execLock.release();
+            }
+        };
+        const executeInTx = async (stmt) => {
+            ensureOpen();
+            const normalized = this.normalizeStatement(stmt);
+            try {
+                const result = await txSession.execute(normalized.sql, normalized.args, this._defaultSafeIntegers);
+                return this.convertResult(result);
+            }
+            catch (error) {
+                throw mapDatabaseError(error, "EXECUTE_ERROR");
+            }
+        };
+        try {
+            await txSession.sequence(this.modeToBeginSql(mode));
+        }
+        catch (error) {
+            await closeTx();
+            throw mapDatabaseError(error, "BEGIN_ERROR");
+        }
+        return {
+            execute: async (stmtOrSql, args) => {
+                if (typeof stmtOrSql === "string") {
+                    const normalizedArgs = args ? (Array.isArray(args) ? args : Object.values(args)) : [];
+                    return executeInTx({ sql: stmtOrSql, args: normalizedArgs });
+                }
+                return executeInTx(stmtOrSql);
+            },
+            batch: async (stmts) => {
+                ensureOpen();
+                const results = [];
+                for (const stmt of stmts) {
+                    results.push(await executeInTx(stmt));
+                }
+                return results;
+            },
+            executeMultiple: async (sql) => {
+                ensureOpen();
+                try {
+                    await txSession.sequence(sql);
+                }
+                catch (error) {
+                    throw mapDatabaseError(error, "EXECUTE_MULTIPLE_ERROR");
+                }
+            },
+            commit: async () => {
+                ensureOpen();
+                try {
+                    await txSession.sequence("COMMIT");
+                }
+                catch (error) {
+                    throw mapDatabaseError(error, "COMMIT_ERROR");
+                }
+                finally {
+                    await closeTx();
+                }
+            },
+            rollback: async () => {
+                ensureOpen();
+                try {
+                    await txSession.sequence("ROLLBACK");
+                }
+                catch (error) {
+                    throw mapDatabaseError(error, "ROLLBACK_ERROR");
+                }
+                finally {
+                    await closeTx();
+                }
+            },
+            close: () => {
+                if (txClosed)
+                    return;
+                txClosed = true;
+                void txSession.sequence("ROLLBACK")
+                    .catch(() => undefined)
+                    .finally(() => {
+                    void closeTx();
+                });
+            },
+            get closed() {
+                return txClosed;
+            },
+        };
     }
     async executeMultiple(sql) {
         await this.execLock.acquire();

package/dist/connection.d.ts

@@ -1,5 +1,6 @@
 import { type SessionConfig } from './session.js';
 import { Statement } from './statement.js';
+import { type QueryOptions } from './protocol.js';
 /**
  * Configuration options for connecting to a Turso database.
  */
@@ -64,7 +65,7 @@ export declare class Connection {
     /**
      * Prepare a SQL statement for execution.
      *
-     * Each prepared statement gets its own session to avoid conflicts during concurrent execution.
+     * Prepared statements created from a Connection use the same underlying session so transaction boundaries are preserved.
      * This method fetches column metadata using the describe functionality.
      *
      * @param sql - The SQL statement to prepare
@@ -91,7 +92,7 @@ export declare class Connection {
      * console.log(result.rows);
      * ```
      */
-    execute(sql: string, args?: any[]): Promise<any>;
+    execute(sql: string, args?: any[], queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a SQL statement and return all results.
      *
@@ -104,7 +105,7 @@ export declare class Connection {
      * console.log(result.rows);
      * ```
      */
-    exec(sql: string): Promise<any>;
+    exec(sql: string, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute multiple SQL statements in a batch.
      *
@@ -121,14 +122,14 @@ export declare class Connection {
      * ]);
      * ```
      */
-    batch(statements: string[], mode?: string): Promise<any>;
+    batch(statements: string[], mode?: string, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a pragma.
      *
      * @param pragma - The pragma to execute
      * @returns Promise resolving to the result of the pragma
      */
-    pragma(pragma: string): Promise<any>;
+    pragma(pragma: string, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Sets the default safe integers mode for all statements from this connection.
      *

package/dist/connection.js

@@ -71,7 +71,7 @@ export class Connection {
     /**
      * Prepare a SQL statement for execution.
      *
-     * Each prepared statement gets its own session to avoid conflicts during concurrent execution.
+     * Prepared statements created from a Connection use the same underlying session so transaction boundaries are preserved.
      * This method fetches column metadata using the describe functionality.
      *
      * @param sql - The SQL statement to prepare
@@ -92,7 +92,7 @@ export class Connection {
         const session = new Session(this.config);
         const description = await session.describe(sql);
         await session.close();
-        const stmt = new Statement(this.config, sql, description.cols);
+        const stmt = Statement.fromSession(this.session, sql, description.cols, this.execLock);
         if (this.defaultSafeIntegerMode) {
             stmt.safeIntegers(true);
         }
@@ -111,13 +111,13 @@ export class Connection {
      * console.log(result.rows);
      * ```
      */
-    async execute(sql, args) {
+    async execute(sql, args, queryOptions) {
         if (!this.isOpen) {
             throw new TypeError("The database connection is not open");
         }
         await this.execLock.acquire();
         try {
-            return await this.session.execute(sql, args || [], this.defaultSafeIntegerMode);
+            return await this.session.execute(sql, args || [], this.defaultSafeIntegerMode, queryOptions);
         }
         finally {
             this.execLock.release();
@@ -135,13 +135,13 @@ export class Connection {
      * console.log(result.rows);
      * ```
      */
-    async exec(sql) {
+    async exec(sql, queryOptions) {
         if (!this.isOpen) {
             throw new TypeError("The database connection is not open");
         }
         await this.execLock.acquire();
         try {
-            return await this.session.sequence(sql);
+            return await this.session.sequence(sql, queryOptions);
         }
         finally {
             this.execLock.release();
@@ -163,13 +163,13 @@ export class Connection {
      * ]);
      * ```
      */
-    async batch(statements, mode) {
+    async batch(statements, mode, queryOptions) {
         if (!this.isOpen) {
             throw new TypeError("The database connection is not open");
         }
         await this.execLock.acquire();
         try {
-            return await this.session.batch(statements);
+            return await this.session.batch(statements, queryOptions);
         }
         finally {
             this.execLock.release();
@@ -181,14 +181,14 @@ export class Connection {
      * @param pragma - The pragma to execute
      * @returns Promise resolving to the result of the pragma
      */
-    async pragma(pragma) {
+    async pragma(pragma, queryOptions) {
         if (!this.isOpen) {
             throw new TypeError("The database connection is not open");
         }
         await this.execLock.acquire();
         try {
             const sql = `PRAGMA ${pragma}`;
-            return await this.session.execute(sql);
+            return await this.session.execute(sql, [], false, queryOptions);
         }
         finally {
             this.execLock.release();

package/dist/error.d.ts

@@ -7,3 +7,13 @@ export declare class DatabaseError extends Error {
     cause?: Error;
     constructor(message: string, code?: string, rawCode?: number, cause?: Error);
 }
+/**
+ * Error thrown when a query exceeds the configured timeout.
+ *
+ * This is a subclass of `DatabaseError` with `code` set to `"TIMEOUT"`.
+ * Catch this type to distinguish timeouts from other database errors
+ * and decide whether to retry or fail gracefully.
+ */
+export declare class TimeoutError extends DatabaseError {
+    constructor(message?: string, cause?: Error);
+}

package/dist/error.js

@@ -8,3 +8,17 @@ export class DatabaseError extends Error {
         Object.setPrototypeOf(this, DatabaseError.prototype);
     }
 }
+/**
+ * Error thrown when a query exceeds the configured timeout.
+ *
+ * This is a subclass of `DatabaseError` with `code` set to `"TIMEOUT"`.
+ * Catch this type to distinguish timeouts from other database errors
+ * and decide whether to retry or fail gracefully.
+ */
+export class TimeoutError extends DatabaseError {
+    constructor(message = 'Query timed out', cause) {
+        super(message, 'TIMEOUT', undefined, cause);
+        this.name = 'TimeoutError';
+        Object.setPrototypeOf(this, TimeoutError.prototype);
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Connection, connect, type Config } from './connection.js';
 export { Statement } from './statement.js';
 export { Session, type SessionConfig } from './session.js';
-export { DatabaseError } from './error.js';
-export { type Column, ENCRYPTION_KEY_HEADER } from './protocol.js';
+export { DatabaseError, TimeoutError } from './error.js';
+export { type Column, type QueryOptions, ENCRYPTION_KEY_HEADER } from './protocol.js';

package/dist/index.js

@@ -2,5 +2,5 @@
 export { Connection, connect } from './connection.js';
 export { Statement } from './statement.js';
 export { Session } from './session.js';
-export { DatabaseError } from './error.js';
+export { DatabaseError, TimeoutError } from './error.js';
 export { ENCRYPTION_KEY_HEADER } from './protocol.js';

package/dist/protocol.d.ts

@@ -108,8 +108,13 @@ export interface CursorEntry {
 }
 /** HTTP header key for the encryption key */
 export declare const ENCRYPTION_KEY_HEADER = "x-turso-encryption-key";
-export declare function executeCursor(url: string, authToken: string | undefined, request: CursorRequest, remoteEncryptionKey?: string): Promise<{
+/** Per-query timeout options. Overrides defaultQueryTimeout for this call. */
+export interface QueryOptions {
+    /** Per-query timeout in milliseconds. Overrides defaultQueryTimeout for this call. */
+    queryTimeout?: number;
+}
+export declare function executeCursor(url: string, authToken: string | undefined, request: CursorRequest, remoteEncryptionKey?: string, signal?: AbortSignal): Promise<{
     response: CursorResponse;
     entries: AsyncGenerator<CursorEntry>;
 }>;
-export declare function executePipeline(url: string, authToken: string | undefined, request: PipelineRequest, remoteEncryptionKey?: string): Promise<PipelineResponse>;
+export declare function executePipeline(url: string, authToken: string | undefined, request: PipelineRequest, remoteEncryptionKey?: string, signal?: AbortSignal): Promise<PipelineResponse>;

package/dist/protocol.js

@@ -1,4 +1,4 @@
-import { DatabaseError } from './error.js';
+import { DatabaseError, TimeoutError } from './error.js';
 export function encodeValue(value) {
     if (value === null || value === undefined) {
         return { type: 'null' };
@@ -53,7 +53,13 @@ export function decodeValue(value, safeIntegers = false) {
 }
 /** HTTP header key for the encryption key */
 export const ENCRYPTION_KEY_HEADER = 'x-turso-encryption-key';
-export async function executeCursor(url, authToken, request, remoteEncryptionKey) {
+function wrapAbortError(error) {
+    if (error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError')) {
+        throw new TimeoutError('Query timed out');
+    }
+    throw error;
+}
+export async function executeCursor(url, authToken, request, remoteEncryptionKey, signal) {
     const headers = {
         'Content-Type': 'application/json',
     };
@@ -63,11 +69,18 @@ export async function executeCursor(url, authToken, request, remoteEncryptionKey
     if (remoteEncryptionKey) {
         headers[ENCRYPTION_KEY_HEADER] = remoteEncryptionKey;
     }
-    const response = await fetch(`${url}/v3/cursor`, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(request),
-    });
+    let response;
+    try {
+        response = await fetch(`${url}/v3/cursor`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(request),
+            signal,
+        });
+    }
+    catch (error) {
+        wrapAbortError(error);
+    }
     if (!response.ok) {
         let errorMessage = `HTTP error! status: ${response.status}`;
         try {
@@ -90,22 +103,29 @@ export async function executeCursor(url, authToken, request, remoteEncryptionKey
     let buffer = '';
     let cursorResponse;
     // First, read until we get the cursor response (first line)
-    while (!cursorResponse) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        buffer += decoder.decode(value, { stream: true });
-        const newlineIndex = buffer.indexOf('\n');
-        if (newlineIndex !== -1) {
-            const line = buffer.slice(0, newlineIndex).trim();
-            buffer = buffer.slice(newlineIndex + 1);
-            if (line) {
-                cursorResponse = JSON.parse(line);
+    try {
+        while (!cursorResponse) {
+            const { done, value } = await reader.read();
+            if (done)
                 break;
+            buffer += decoder.decode(value, { stream: true });
+            const newlineIndex = buffer.indexOf('\n');
+            if (newlineIndex !== -1) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                buffer = buffer.slice(newlineIndex + 1);
+                if (line) {
+                    cursorResponse = JSON.parse(line);
+                    break;
+                }
             }
         }
     }
+    catch (error) {
+        reader.releaseLock();
+        wrapAbortError(error);
+    }
     if (!cursorResponse) {
+        reader.releaseLock();
         throw new DatabaseError('No cursor response received');
     }
     async function* parseEntries() {
@@ -121,10 +141,16 @@ export async function executeCursor(url, authToken, request, remoteEncryptionKey
             }
             // Continue reading from the stream
             while (true) {
-                const { done, value } = await reader.read();
-                if (done)
+                let readResult;
+                try {
+                    readResult = await reader.read();
+                }
+                catch (error) {
+                    wrapAbortError(error);
+                }
+                if (readResult.done)
                     break;
-                buffer += decoder.decode(value, { stream: true });
+                buffer += decoder.decode(readResult.value, { stream: true });
                 while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
                     const line = buffer.slice(0, newlineIndex).trim();
                     buffer = buffer.slice(newlineIndex + 1);
@@ -144,7 +170,7 @@ export async function executeCursor(url, authToken, request, remoteEncryptionKey
     }
     return { response: cursorResponse, entries: parseEntries() };
 }
-export async function executePipeline(url, authToken, request, remoteEncryptionKey) {
+export async function executePipeline(url, authToken, request, remoteEncryptionKey, signal) {
     const headers = {
         'Content-Type': 'application/json',
     };
@@ -154,11 +180,18 @@ export async function executePipeline(url, authToken, request, remoteEncryptionK
     if (remoteEncryptionKey) {
         headers[ENCRYPTION_KEY_HEADER] = remoteEncryptionKey;
     }
-    const response = await fetch(`${url}/v3/pipeline`, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(request),
-    });
+    let response;
+    try {
+        response = await fetch(`${url}/v3/pipeline`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(request),
+            signal,
+        });
+    }
+    catch (error) {
+        wrapAbortError(error);
+    }
     if (!response.ok) {
         throw new DatabaseError(`HTTP error! status: ${response.status}`);
     }

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-import { type CursorResponse, type CursorEntry, type DescribeResult } from './protocol.js';
+import { type CursorResponse, type CursorEntry, type DescribeResult, type QueryOptions } from './protocol.js';
 /**
  * Configuration options for a session.
  */
@@ -12,6 +12,8 @@ export interface SessionConfig {
      * to enable access to encrypted Turso Cloud databases.
      */
     remoteEncryptionKey?: string;
+    /** Default maximum query execution time in milliseconds before interruption. */
+    defaultQueryTimeout?: number;
 }
 /**
  * A database session that manages the connection state and baton.
@@ -24,13 +26,14 @@ export declare class Session {
     private baton;
     private baseUrl;
     constructor(config: SessionConfig);
+    private createAbortSignal;
     /**
      * Describe a SQL statement to get its column metadata.
      *
      * @param sql - The SQL statement to describe
      * @returns Promise resolving to the statement description
      */
-    describe(sql: string): Promise<DescribeResult>;
+    describe(sql: string, queryOptions?: QueryOptions): Promise<DescribeResult>;
     /**
      * Execute a SQL statement and return all results.
      *
@@ -39,7 +42,7 @@ export declare class Session {
      * @param safeIntegers - Whether to return integers as BigInt
      * @returns Promise resolving to the complete result set
      */
-    execute(sql: string, args?: any[] | Record<string, any>, safeIntegers?: boolean): Promise<any>;
+    execute(sql: string, args?: any[] | Record<string, any>, safeIntegers?: boolean, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a SQL statement and return the raw response and entries.
      *
@@ -47,7 +50,7 @@ export declare class Session {
      * @param args - Optional array of parameter values or object with named parameters
      * @returns Promise resolving to the raw response and cursor entries
      */
-    executeRaw(sql: string, args?: any[] | Record<string, any>): Promise<{
+    executeRaw(sql: string, args?: any[] | Record<string, any>, queryOptions?: QueryOptions): Promise<{
         response: CursorResponse;
         entries: AsyncGenerator<CursorEntry>;
     }>;
@@ -72,14 +75,14 @@ export declare class Session {
      * @param statements - Array of SQL statements to execute
      * @returns Promise resolving to batch execution results
      */
-    batch(statements: string[]): Promise<any>;
+    batch(statements: string[], queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a sequence of SQL statements separated by semicolons.
      *
      * @param sql - SQL string containing multiple statements separated by semicolons
      * @returns Promise resolving when all statements are executed
      */
-    sequence(sql: string): Promise<void>;
+    sequence(sql: string, queryOptions?: QueryOptions): Promise<void>;
     /**
      * Close the session.
      *

package/dist/session.js

@@ -18,13 +18,20 @@ export class Session {
         this.config = config;
         this.baseUrl = normalizeUrl(config.url);
     }
+    createAbortSignal(queryOptions) {
+        const timeout = queryOptions?.queryTimeout ?? this.config.defaultQueryTimeout;
+        if (timeout != null && timeout > 0) {
+            return AbortSignal.timeout(timeout);
+        }
+        return undefined;
+    }
     /**
      * Describe a SQL statement to get its column metadata.
      *
      * @param sql - The SQL statement to describe
      * @returns Promise resolving to the statement description
      */
-    async describe(sql) {
+    async describe(sql, queryOptions) {
         const request = {
             baton: this.baton,
             requests: [{
@@ -32,7 +39,7 @@ export class Session {
                     sql: sql
                 }]
         };
-        const response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
+        const response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -57,8 +64,8 @@ export class Session {
      * @param safeIntegers - Whether to return integers as BigInt
      * @returns Promise resolving to the complete result set
      */
-    async execute(sql, args = [], safeIntegers = false) {
-        const { response, entries } = await this.executeRaw(sql, args);
+    async execute(sql, args = [], safeIntegers = false, queryOptions) {
+        const { response, entries } = await this.executeRaw(sql, args, queryOptions);
         const result = await this.processCursorEntries(entries, safeIntegers);
         return result;
     }
@@ -69,7 +76,7 @@ export class Session {
      * @param args - Optional array of parameter values or object with named parameters
      * @returns Promise resolving to the raw response and cursor entries
      */
-    async executeRaw(sql, args = []) {
+    async executeRaw(sql, args = [], queryOptions) {
         let positionalArgs = [];
         let namedArgs = [];
         if (Array.isArray(args)) {
@@ -118,7 +125,7 @@ export class Session {
                     }]
             }
         };
-        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
+        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -202,7 +209,7 @@ export class Session {
      * @param statements - Array of SQL statements to execute
      * @returns Promise resolving to batch execution results
      */
-    async batch(statements) {
+    async batch(statements, queryOptions) {
         const request = {
             baton: this.baton,
             batch: {
@@ -216,7 +223,7 @@ export class Session {
                 }))
             }
         };
-        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
+        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -249,7 +256,7 @@ export class Session {
      * @param sql - SQL string containing multiple statements separated by semicolons
      * @returns Promise resolving when all statements are executed
      */
-    async sequence(sql) {
+    async sequence(sql, queryOptions) {
         const request = {
             baton: this.baton,
             requests: [{
@@ -257,7 +264,7 @@ export class Session {
                     sql: sql
                 }]
         };
-        const response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
+        const response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -288,9 +295,9 @@ export class Session {
                 };
                 await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
             }
-            catch (error) {
-                // Ignore errors during close, as the connection might already be closed
-                console.error('Error closing session:', error);
+            catch {
+                // Ignore errors during close — the connection might already be closed
+                // or the baton may be stale after a timeout.
             }
         }
         // Reset local state

package/dist/statement.d.ts

@@ -1,9 +1,10 @@
-import { type Column } from './protocol.js';
-import { type SessionConfig } from './session.js';
+import { type Column, type QueryOptions } from './protocol.js';
+import { Session, type SessionConfig } from './session.js';
+import { type AsyncLock } from './async-lock.js';
 /**
  * A prepared SQL statement that can be executed in multiple ways.
  *
- * Each statement has its own session to avoid conflicts during concurrent execution.
+ * Statements may either own a dedicated session or share a connection session to preserve transaction boundaries.
  * Provides three execution modes:
  * - `get(args?)`: Returns the first row or null
  * - `all(args?)`: Returns all rows as an array
@@ -15,7 +16,14 @@ export declare class Statement {
     private presentationMode;
     private safeIntegerMode;
     private columnMetadata;
+    private execLock?;
     constructor(sessionConfig: SessionConfig, sql: string, columns?: Column[]);
+    /**
+     * Create a Statement that shares an existing session and serializes execution
+     * through the given lock. Used by Connection.prepare() so prepared statements
+     * participate in the connection's transaction scope.
+     */
+    static fromSession(session: Session, sql: string, columns: Column[] | undefined, execLock: AsyncLock): Statement;
     /**
      * Whether the prepared statement returns data.
      *
@@ -81,6 +89,7 @@ export declare class Statement {
      * ```
      */
     columns(): any[];
+    private withLock;
     /**
      * Executes the prepared statement.
      *
@@ -94,7 +103,7 @@ export declare class Statement {
      * console.log(`Inserted user with ID ${result.lastInsertRowid}`);
      * ```
      */
-    run(args?: any): Promise<any>;
+    run(args?: any, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute the statement and return the first row.
      *
@@ -110,7 +119,7 @@ export declare class Statement {
      * }
      * ```
      */
-    get(args?: any): Promise<any>;
+    get(args?: any, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute the statement and return all rows.
      *
@@ -124,7 +133,7 @@ export declare class Statement {
      * console.log(`Found ${activeUsers.length} active users`);
      * ```
      */
-    all(args?: any): Promise<any[]>;
+    all(args?: any, queryOptions?: QueryOptions): Promise<any[]>;
     /**
      * Execute the statement and return an async iterator for streaming results.
      *
@@ -143,7 +152,7 @@ export declare class Statement {
      * }
      * ```
      */
-    iterate(args?: any): AsyncGenerator<any>;
+    iterate(args?: any, queryOptions?: QueryOptions): AsyncGenerator<any>;
     /**
      * Normalize arguments to handle both single values and arrays.
      * Matches the behavior of the native bindings.

package/dist/statement.js

@@ -4,7 +4,7 @@ import { DatabaseError } from './error.js';
 /**
  * A prepared SQL statement that can be executed in multiple ways.
  *
- * Each statement has its own session to avoid conflicts during concurrent execution.
+ * Statements may either own a dedicated session or share a connection session to preserve transaction boundaries.
  * Provides three execution modes:
  * - `get(args?)`: Returns the first row or null
  * - `all(args?)`: Returns all rows as an array
@@ -18,6 +18,21 @@ export class Statement {
         this.sql = sql;
         this.columnMetadata = columns || [];
     }
+    /**
+     * Create a Statement that shares an existing session and serializes execution
+     * through the given lock. Used by Connection.prepare() so prepared statements
+     * participate in the connection's transaction scope.
+     */
+    static fromSession(session, sql, columns, execLock) {
+        const stmt = Object.create(Statement.prototype);
+        stmt.session = session;
+        stmt.sql = sql;
+        stmt.columnMetadata = columns || [];
+        stmt.presentationMode = 'expanded';
+        stmt.safeIntegerMode = false;
+        stmt.execLock = execLock;
+        return stmt;
+    }
     /**
      * Whether the prepared statement returns data.
      *
@@ -99,6 +114,18 @@ export class Statement {
             type: col.decltype
         }));
     }
+    async withLock(fn) {
+        if (!this.execLock) {
+            return await fn();
+        }
+        await this.execLock.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.execLock.release();
+        }
+    }
     /**
      * Executes the prepared statement.
      *
@@ -112,10 +139,12 @@ export class Statement {
      * console.log(`Inserted user with ID ${result.lastInsertRowid}`);
      * ```
      */
-    async run(args) {
-        const normalizedArgs = this.normalizeArgs(args);
-        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode);
-        return { changes: result.rowsAffected, lastInsertRowid: result.lastInsertRowid };
+    async run(args, queryOptions) {
+        return await this.withLock(async () => {
+            const normalizedArgs = this.normalizeArgs(args);
+            const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode, queryOptions);
+            return { changes: result.rowsAffected, lastInsertRowid: result.lastInsertRowid };
+        });
     }
     /**
      * Execute the statement and return the first row.
@@ -132,28 +161,30 @@ export class Statement {
      * }
      * ```
      */
-    async get(args) {
-        const normalizedArgs = this.normalizeArgs(args);
-        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode);
-        const row = result.rows[0];
-        if (!row) {
-            return undefined;
-        }
-        if (this.presentationMode === 'pluck') {
-            // In pluck mode, return only the first column value
-            return row[0];
-        }
-        if (this.presentationMode === 'raw') {
-            // In raw mode, return the row as a plain array (it already is one)
-            // The row object is already an array with column properties added
-            return [...row];
-        }
-        // In expanded mode, convert to plain object with named properties  
-        const obj = {};
-        result.columns.forEach((col, i) => {
-            obj[col] = row[i];
+    async get(args, queryOptions) {
+        return await this.withLock(async () => {
+            const normalizedArgs = this.normalizeArgs(args);
+            const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode, queryOptions);
+            const row = result.rows[0];
+            if (!row) {
+                return undefined;
+            }
+            if (this.presentationMode === 'pluck') {
+                // In pluck mode, return only the first column value
+                return row[0];
+            }
+            if (this.presentationMode === 'raw') {
+                // In raw mode, return the row as a plain array (it already is one)
+                // The row object is already an array with column properties added
+                return [...row];
+            }
+            // In expanded mode, convert to plain object with named properties
+            const obj = {};
+            result.columns.forEach((col, i) => {
+                obj[col] = row[i];
+            });
+            return obj;
         });
-        return obj;
     }
     /**
      * Execute the statement and return all rows.
@@ -168,23 +199,25 @@ export class Statement {
      * console.log(`Found ${activeUsers.length} active users`);
      * ```
      */
-    async all(args) {
-        const normalizedArgs = this.normalizeArgs(args);
-        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode);
-        if (this.presentationMode === 'pluck') {
-            // In pluck mode, return only the first column value from each row
-            return result.rows.map((row) => row[0]);
-        }
-        if (this.presentationMode === 'raw') {
-            return result.rows.map((row) => [...row]);
-        }
-        // In expanded mode, convert rows to plain objects with named properties
-        return result.rows.map((row) => {
-            const obj = {};
-            result.columns.forEach((col, i) => {
-                obj[col] = row[i];
+    async all(args, queryOptions) {
+        return await this.withLock(async () => {
+            const normalizedArgs = this.normalizeArgs(args);
+            const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode, queryOptions);
+            if (this.presentationMode === 'pluck') {
+                // In pluck mode, return only the first column value from each row
+                return result.rows.map((row) => row[0]);
+            }
+            if (this.presentationMode === 'raw') {
+                return result.rows.map((row) => [...row]);
+            }
+            // In expanded mode, convert rows to plain objects with named properties
+            return result.rows.map((row) => {
+                const obj = {};
+                result.columns.forEach((col, i) => {
+                    obj[col] = row[i];
+                });
+                return obj;
             });
-            return obj;
         });
     }
     /**
@@ -205,9 +238,18 @@ export class Statement {
      * }
      * ```
      */
-    async *iterate(args) {
+    async *iterate(args, queryOptions) {
+        // Shared-connection statements must not hold the connection lock across
+        // `yield` points, or nested queries in the loop body can deadlock.
+        if (this.execLock) {
+            const rows = await this.all(args, queryOptions);
+            for (const row of rows) {
+                yield row;
+            }
+            return;
+        }
         const normalizedArgs = this.normalizeArgs(args);
-        const { response, entries } = await this.session.executeRaw(this.sql, normalizedArgs);
+        const { entries } = await this.session.executeRaw(this.sql, normalizedArgs, queryOptions);
         let columns = [];
         for await (const entry of entries) {
             switch (entry.type) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tursodatabase/serverless",
-  "version": "1.0.0",
+  "version": "1.1.0-pre.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",