Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/content/docs/guides/prepared-statements.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
#include "../NitroSQLiteMacros.hpp"
#include "../NitroSQLiteOperations.hpp"
#include "HybridNitroSQLitePreparedStatement.hpp"
#include "NitroSQLiteConnectionOperation.hpp"
#include <exception>
#include <filesystem>
#include <iostream>
Expand Down Expand Up @@ -60,36 +61,6 @@ static std::vector<BatchQuery> copyArrayBufferParamsForBackground(const std::vec
return copiedCommands;
}

template <typename Result, typename Operation>
static std::shared_ptr<Promise<Result>> enqueueConnectionOperation(const SQLiteConnectionPtr& connection, Operation&& operation) {
auto promise = Promise<Result>::create();
try {
connection->enqueueAsync([promise, operation = std::forward<Operation>(operation)]() mutable {
std::optional<Result> 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<std::string>& location) {
if (location && location->find('\0') != std::string::npos) {
throw NitroSQLiteException(NitroSQLiteExceptionType::DatabaseCannotBeOpened, "Database location contains a NUL byte");
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
#include "HybridNitroSQLitePreparedStatement.hpp"
#include "NitroSQLiteConnectionOperation.hpp"
#include <NitroModules/ArrayBuffer.hpp>

namespace margelo::nitro::rnnitrosqlite {
Expand Down Expand Up @@ -38,8 +39,10 @@ HybridNitroSQLitePreparedStatement::executeAsync(const std::optional<SQLiteQuery
const auto copiedParams = copyArrayBufferParamsForBackground(params);
const auto statement = _statement;

return Promise<NitroSQLiteQueryResult>::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<NitroSQLiteQueryResult>(
statement->connection(), [statement, copiedParams]() -> NitroSQLiteQueryResult { return statement->execute(copiedParams); });
}

NitroSQLiteRawQueryResult HybridNitroSQLitePreparedStatement::executeRaw(const std::optional<SQLiteQueryParams>& params) {
Expand All @@ -51,8 +54,8 @@ HybridNitroSQLitePreparedStatement::executeRawAsync(const std::optional<SQLiteQu
const auto copiedParams = copyArrayBufferParamsForBackground(params);
const auto statement = _statement;

return Promise<NitroSQLiteRawQueryResult>::async(
[statement, copiedParams]() -> NitroSQLiteRawQueryResult { return statement->executeRaw(copiedParams); });
return enqueueConnectionOperation<NitroSQLiteRawQueryResult>(
statement->connection(), [statement, copiedParams]() -> NitroSQLiteRawQueryResult { return statement->executeRaw(copiedParams); });
}

void HybridNitroSQLitePreparedStatement::finalize() {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,11 @@ class HybridNitroSQLitePreparedStatement : public HybridNitroSQLitePreparedState

/** Execute with new bindings on the calling thread. */
NitroSQLiteQueryResult execute(const std::optional<SQLiteQueryParams>& 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<Promise<NitroSQLiteQueryResult>> executeAsync(const std::optional<SQLiteQueryParams>& params) override;
/** Execute with new bindings on the calling thread, returning rows as arrays of column values. */
NitroSQLiteRawQueryResult executeRaw(const std::optional<SQLiteQueryParams>& 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<Promise<NitroSQLiteRawQueryResult>> executeRawAsync(const std::optional<SQLiteQueryParams>& params) override;
/** Release the native statement. */
void finalize() override;
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
#pragma once

#include "../NitroSQLiteDatabaseConnections.hpp"
#include <NitroModules/Promise.hpp>
#include <exception>
#include <memory>
#include <optional>
#include <utility>

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 <typename Result, typename Operation>
std::shared_ptr<Promise<Result>> enqueueConnectionOperation(const SQLiteConnectionPtr& connection, Operation&& operation) {
auto promise = Promise<Result>::create();
try {
connection->enqueueAsync([promise, operation = std::forward<Operation>(operation)]() mutable {
std::optional<Result> 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
23 changes: 23 additions & 0 deletions packages/react-native-nitro-sqlite/src/__tests__/prepare.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
8 changes: 5 additions & 3 deletions packages/react-native-nitro-sqlite/src/operations/prepare.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'

/**
Expand Down Expand Up @@ -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: <Row extends QueryResultRow = QueryResultRow>(
params?: SQLiteQueryParams,
): Promise<QueryResult<Row>> =>
queueOperationAsync(queueKey, () =>
queueStatementAsync(queueKey, () =>
nativeStatement
.executeAsync(params)
.then((result) => buildJSQueryResult<Row>(result)),
Expand All @@ -67,7 +69,7 @@ export function prepare(
executeRawAsync: (
params?: SQLiteQueryParams,
): Promise<NitroSQLiteRawQueryResult> =>
queueOperationAsync(queueKey, () =>
queueStatementAsync(queueKey, () =>
nativeStatement.executeRawAsync(params),
).catch(rejectWithNitroSQLiteError),
finalize: () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading