diff --git a/docs/content/docs/guides/prepared-statements.mdx b/docs/content/docs/guides/prepared-statements.mdx index ed1e8fe0..297710a9 100644 --- a/docs/content/docs/guides/prepared-statements.mdx +++ b/docs/content/docs/guides/prepared-statements.mdx @@ -48,7 +48,7 @@ try { ## Connection ordering and cleanup -On a managed connection, `executeAsync()` reserves that connection's queue until it completes. It waits for earlier work and prevents later work from starting. While async work is pending, synchronous `prepare()`, `execute()`, `finalize()`, and `close()` on that connection throw a busy error. Await the last execution before finalizing, then finalize before closing the connection. `isFinalized` reports whether the statement has been finalized; executing it afterward throws. +On a managed connection, `executeAsync()` runs in submission order with the connection's other async calls. It waits for earlier work, and later work starts only after it completes. While async work is pending, synchronous `prepare()`, `execute()`, `finalize()`, and `close()` on that connection throw a busy error. Await the last execution before finalizing, then finalize before closing the connection. `isFinalized` reports whether the statement has been finalized; executing it afterward throws. Do not await a prepared statement's `executeAsync()` from inside `db.transaction()` on the same connection. It waits behind the transaction, while the transaction waits for your callback. Use the callback's `tx.execute()` or `tx.executeAsync()` instead. See [transactions](/docs/guides/transactions) and [connection ordering](/docs/guides/sync-and-async#connection-ordering). diff --git a/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.cpp b/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.cpp index 798bce81..7a12d955 100644 --- a/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.cpp +++ b/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.cpp @@ -455,6 +455,10 @@ NitroSQLiteRawQueryResult SQLitePreparedStatement::executeRaw(const std::optiona return executeBound(params, executeStatementRaw); } +const SQLiteConnectionPtr& SQLitePreparedStatement::connection() const noexcept { + return _state->connection; +} + void SQLitePreparedStatement::finalize() { std::lock_guard lock(_state->mutex); std::lock_guard connectionLock(_state->connection->mutex); diff --git a/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.hpp b/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.hpp index 9631c34e..369f6055 100644 --- a/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.hpp +++ b/packages/react-native-nitro-sqlite/cpp/NitroSQLiteOperations.hpp @@ -33,6 +33,8 @@ class SQLitePreparedStatement { void finalize(); /** Check whether the native statement has been released. */ bool isFinalized() const; + /** The connection this statement was prepared on. */ + const SQLiteConnectionPtr& connection() const noexcept; /** Report this object's native memory size to the Nitro runtime. */ size_t getExternalMemorySize() const noexcept; diff --git a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp index fd2c3c5d..342ba201 100644 --- a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp +++ b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp @@ -7,6 +7,7 @@ #include "../NitroSQLiteMacros.hpp" #include "../NitroSQLiteOperations.hpp" #include "HybridNitroSQLitePreparedStatement.hpp" +#include "NitroSQLiteConnectionOperation.hpp" #include #include #include @@ -60,36 +61,6 @@ static std::vector copyArrayBufferParamsForBackground(const std::vec return copiedCommands; } -template -static std::shared_ptr> enqueueConnectionOperation(const SQLiteConnectionPtr& connection, Operation&& operation) { - auto promise = Promise::create(); - try { - connection->enqueueAsync([promise, operation = std::forward(operation)]() mutable { - std::optional result; - try { - result.emplace(operation()); - } catch (...) { - promise->reject(std::current_exception()); - return; - } - // Resolving may dispatch to JavaScript and throw after the native promise - // has settled. Do not try to reject that same promise again. - try { - promise->resolve(std::move(*result)); - } catch (...) { - if (promise->isPending()) { - promise->reject(std::current_exception()); - return; - } - throw; - } - }); - } catch (...) { - promise->reject(std::current_exception()); - } - return promise; -} - const std::string getDocPath(const std::optional& location) { if (location && location->find('\0') != std::string::npos) { throw NitroSQLiteException(NitroSQLiteExceptionType::DatabaseCannotBeOpened, "Database location contains a NUL byte"); diff --git a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.cpp b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.cpp index 70003b71..133ca35a 100644 --- a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.cpp +++ b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.cpp @@ -1,4 +1,5 @@ #include "HybridNitroSQLitePreparedStatement.hpp" +#include "NitroSQLiteConnectionOperation.hpp" #include namespace margelo::nitro::rnnitrosqlite { @@ -38,8 +39,10 @@ HybridNitroSQLitePreparedStatement::executeAsync(const std::optional::async( - [statement, copiedParams]() -> NitroSQLiteQueryResult { return statement->execute(copiedParams); }); + // The connection's worker keeps executions in call order, so JavaScript can submit several without + // waiting for each result. + return enqueueConnectionOperation( + statement->connection(), [statement, copiedParams]() -> NitroSQLiteQueryResult { return statement->execute(copiedParams); }); } NitroSQLiteRawQueryResult HybridNitroSQLitePreparedStatement::executeRaw(const std::optional& params) { @@ -51,8 +54,8 @@ HybridNitroSQLitePreparedStatement::executeRawAsync(const std::optional::async( - [statement, copiedParams]() -> NitroSQLiteRawQueryResult { return statement->executeRaw(copiedParams); }); + return enqueueConnectionOperation( + statement->connection(), [statement, copiedParams]() -> NitroSQLiteRawQueryResult { return statement->executeRaw(copiedParams); }); } void HybridNitroSQLitePreparedStatement::finalize() { diff --git a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.hpp b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.hpp index c5e65822..0a09c138 100644 --- a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.hpp +++ b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLitePreparedStatement.hpp @@ -15,11 +15,11 @@ class HybridNitroSQLitePreparedStatement : public HybridNitroSQLitePreparedState /** Execute with new bindings on the calling thread. */ NitroSQLiteQueryResult execute(const std::optional& params) override; - /** Execute with new bindings on a background thread. */ + /** Execute with new bindings on the connection's worker, in call order. */ std::shared_ptr> executeAsync(const std::optional& params) override; /** Execute with new bindings on the calling thread, returning rows as arrays of column values. */ NitroSQLiteRawQueryResult executeRaw(const std::optional& params) override; - /** Execute with new bindings on a background thread, returning rows as arrays of column values. */ + /** Execute with new bindings on the connection's worker, returning rows as arrays of column values. */ std::shared_ptr> executeRawAsync(const std::optional& params) override; /** Release the native statement. */ void finalize() override; diff --git a/packages/react-native-nitro-sqlite/cpp/hybridObjects/NitroSQLiteConnectionOperation.hpp b/packages/react-native-nitro-sqlite/cpp/hybridObjects/NitroSQLiteConnectionOperation.hpp new file mode 100644 index 00000000..4886f8ef --- /dev/null +++ b/packages/react-native-nitro-sqlite/cpp/hybridObjects/NitroSQLiteConnectionOperation.hpp @@ -0,0 +1,45 @@ +#pragma once + +#include "../NitroSQLiteDatabaseConnections.hpp" +#include +#include +#include +#include +#include + +namespace margelo::nitro::rnnitrosqlite { + +/** Run @p operation on the connection's FIFO worker and settle the returned promise with its result. + * Calls on one connection run in submission order, one at a time. + */ +template +std::shared_ptr> enqueueConnectionOperation(const SQLiteConnectionPtr& connection, Operation&& operation) { + auto promise = Promise::create(); + try { + connection->enqueueAsync([promise, operation = std::forward(operation)]() mutable { + std::optional result; + try { + result.emplace(operation()); + } catch (...) { + promise->reject(std::current_exception()); + return; + } + // Resolving may dispatch to JavaScript and throw after the native promise + // has settled. Do not try to reject that same promise again. + try { + promise->resolve(std::move(*result)); + } catch (...) { + if (promise->isPending()) { + promise->reject(std::current_exception()); + return; + } + throw; + } + }); + } catch (...) { + promise->reject(std::current_exception()); + } + return promise; +} + +} // namespace margelo::nitro::rnnitrosqlite diff --git a/packages/react-native-nitro-sqlite/src/__tests__/prepare.test.ts b/packages/react-native-nitro-sqlite/src/__tests__/prepare.test.ts index f6902e6c..abb99d91 100644 --- a/packages/react-native-nitro-sqlite/src/__tests__/prepare.test.ts +++ b/packages/react-native-nitro-sqlite/src/__tests__/prepare.test.ts @@ -97,6 +97,29 @@ it('keeps synchronous calls from overtaking an asynchronous execution', async () statement.finalize() }) +it('submits several executions before waiting for native results', async () => { + const native = mockStatement() + let finishFirst: (() => void) | undefined + jest.mocked(native.executeAsync).mockImplementationOnce( + () => + new Promise((resolve) => { + finishFirst = () => resolve(nativeResult([{ value: 1 }])) + }), + ) + jest.mocked(HybridNitroSQLite.prepare).mockReturnValue(native) + const statement = prepare(dbName, query) + + const first = statement.executeAsync([1]) + const second = statement.executeAsync([2]) + const raw = statement.executeRawAsync([3]) + expect(native.executeAsync).toHaveBeenCalledTimes(2) + expect(native.executeRawAsync).toHaveBeenCalledTimes(1) + + finishFirst!() + await Promise.all([first, second, raw]) + statement.finalize() +}) + it('runs raw executions through the statement queue', async () => { const native = mockStatement() jest.mocked(HybridNitroSQLite.prepare).mockReturnValue(native) diff --git a/packages/react-native-nitro-sqlite/src/operations/prepare.ts b/packages/react-native-nitro-sqlite/src/operations/prepare.ts index bb82f14d..20011a7e 100644 --- a/packages/react-native-nitro-sqlite/src/operations/prepare.ts +++ b/packages/react-native-nitro-sqlite/src/operations/prepare.ts @@ -9,7 +9,7 @@ import type { import type { NitroSQLiteRawQueryResult } from '../specs/NitroSQLiteQueryResult.nitro' import { buildJSQueryResult } from './execute' import { rejectWithNitroSQLiteError } from '../nativePromise' -import { queueOperationAsync, startOperationSync } from '../DatabaseQueue' +import { queueStatementAsync, startOperationSync } from '../DatabaseQueue' import type { DatabaseQueueKey } from '../DatabaseQueue' /** @@ -47,10 +47,12 @@ export function prepare( } }, // Chained instead of `async`, which would add promise layers to every execution. + // Native code runs executions on the connection's worker in call order, so they + // queue as statements and several can be submitted without waiting for each result. executeAsync: ( params?: SQLiteQueryParams, ): Promise> => - queueOperationAsync(queueKey, () => + queueStatementAsync(queueKey, () => nativeStatement .executeAsync(params) .then((result) => buildJSQueryResult(result)), @@ -67,7 +69,7 @@ export function prepare( executeRawAsync: ( params?: SQLiteQueryParams, ): Promise => - queueOperationAsync(queueKey, () => + queueStatementAsync(queueKey, () => nativeStatement.executeRawAsync(params), ).catch(rejectWithNitroSQLiteError), finalize: () => { diff --git a/packages/react-native-nitro-sqlite/src/specs/NitroSQLitePreparedStatement.nitro.ts b/packages/react-native-nitro-sqlite/src/specs/NitroSQLitePreparedStatement.nitro.ts index e4ce3c62..c8c287bc 100644 --- a/packages/react-native-nitro-sqlite/src/specs/NitroSQLitePreparedStatement.nitro.ts +++ b/packages/react-native-nitro-sqlite/src/specs/NitroSQLitePreparedStatement.nitro.ts @@ -20,7 +20,8 @@ export interface NitroSQLitePreparedStatement * @returns Native query rows, affected row count, insert ID, and metadata. */ execute(params?: SQLiteQueryParams): NitroSQLiteQueryResult - /** Execute on a background thread, replacing the previous parameter bindings. + /** Execute on the connection's background thread, replacing the previous parameter bindings. + * Executions run in call order with the connection's other async calls. * Rejects after finalization or connection closure. * @param params Values bound to positional placeholders. * @returns A promise of the native query result.