@happyvertical/sql 0.111.3 → 0.111.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -473,20 +473,46 @@ Two consequences worth knowing:
|
|
|
473
473
|
connection for the life of the process, and every later transaction on it
|
|
474
474
|
fails with the queue timeout.
|
|
475
475
|
- Inside a `transaction()` callback, use the `tx` you were handed. With secure
|
|
476
|
-
SQLite, calling a top-level `db.*` or `db.client.execute()`
|
|
476
|
+
SQLite and remote LibSQL, calling a top-level `db.*` or `db.client.execute()`
|
|
477
|
+
method is rejected
|
|
477
478
|
immediately so detached work cannot escape into autocommit after the callback
|
|
478
479
|
ends. While a manual transaction handle is open, top-level calls wait on its
|
|
479
480
|
connection and reject at `transactionQueueTimeout` rather than hang forever.
|
|
480
481
|
|
|
481
482
|
Nested SQLite and PostgreSQL scopes use savepoints. If sibling nested scopes are
|
|
482
483
|
started concurrently on one transaction, they serialize so the stack-ordered
|
|
483
|
-
savepoint lifecycle remains intact.
|
|
484
|
-
|
|
484
|
+
savepoint lifecycle remains intact. On secure SQLite and remote LibSQL,
|
|
485
|
+
operations invoked through a parent handle from outside an open child
|
|
486
|
+
savepoint queue behind that child; a
|
|
485
487
|
child rollback therefore cannot silently remove a successful parent operation.
|
|
486
488
|
The enclosing commit or rollback drains all
|
|
487
489
|
accepted child scopes before ending the transaction. PostgreSQL pools separate
|
|
488
490
|
connections, so top-level transactions there run concurrently and never queue;
|
|
489
491
|
PGlite has one connection and queues them like SQLite does.
|
|
492
|
+
Remote LibSQL uses a dedicated write transaction for each callback or manual
|
|
493
|
+
handle. It acquires the write transaction before invoking the callback or
|
|
494
|
+
returning the handle, and never replays a callback. Use `tx.client.execute()`
|
|
495
|
+
for raw driver statements within that transaction; native operations on the root
|
|
496
|
+
`db.client` use separate streams. If a statement ends the transaction (for
|
|
497
|
+
example, `INSERT OR ROLLBACK` hits a conflict), the handle rejects later
|
|
498
|
+
statements and commit rather than letting work continue in autocommit.
|
|
499
|
+
An ordinary handled constraint failure can still leave the transaction active.
|
|
500
|
+
|
|
501
|
+
In remote SQLite queries with positional
|
|
502
|
+
arguments, `$1`, `$2`, and so on refer to the same argument slots as SQLite's
|
|
503
|
+
`?1`, `?2`, including repeated or reordered references. Named parameters with
|
|
504
|
+
an argument object are available through `client.execute()`.
|
|
505
|
+
|
|
506
|
+
The remote transaction integration test is opt-in. Point one or both variables
|
|
507
|
+
at a disposable writable sqld database. For a server that requires
|
|
508
|
+
authentication, also set `SDK_TEST_SQLITE_AUTH_TOKEN`.
|
|
509
|
+
|
|
510
|
+
```bash
|
|
511
|
+
SDK_TEST_SQLITE_HTTP_URL='http://127.0.0.1:8080' \
|
|
512
|
+
SDK_TEST_SQLITE_LIBSQL_URL='libsql://127.0.0.1:8080?tls=0' \
|
|
513
|
+
pnpm --filter @happyvertical/sql exec vitest --config ../../vitest.package.config.ts run src/sqlite-remote-transaction.spec.ts
|
|
514
|
+
```
|
|
515
|
+
|
|
490
516
|
PostgreSQL CRUD helpers apply the same value serialization both inside and
|
|
491
517
|
outside a transaction: objects and arrays are encoded for JSON/JSONB columns,
|
|
492
518
|
dates use ISO timestamps, binary buffers and views retain their native `bytea`
|
|
@@ -684,6 +684,75 @@ function prepareManagedStatement(statement) {
|
|
|
684
684
|
}
|
|
685
685
|
return statement;
|
|
686
686
|
}
|
|
687
|
+
var remoteParameterToken = /--[^\n]*|\/\*[\s\S]*?(?:\*\/|$)|'(?:''|[^'])*(?:'|$)|"(?:""|[^"])*(?:"|$)|`(?:``|[^`])*(?:`|$)|\[[^\]]*(?:\]|$)|[a-zA-Z_\u0080-\uFFFF][\w$\u0080-\uFFFF]*|[$:@][\w$\u0080-\uFFFF]+(?:::[\w$\u0080-\uFFFF]+)*(?:\([^)]*\))?/g;
|
|
688
|
+
function prepareRemoteStatement(statement) {
|
|
689
|
+
if (typeof statement !== "object" || !Array.isArray(statement.args)) return statement;
|
|
690
|
+
return {
|
|
691
|
+
...statement,
|
|
692
|
+
sql: statement.sql.replace(remoteParameterToken, (token) => /^\$[1-9]\d*$/.test(token) ? `?${token.slice(1)}` : token)
|
|
693
|
+
};
|
|
694
|
+
}
|
|
695
|
+
async function guardRemoteTransaction(tx) {
|
|
696
|
+
const savepoint = "SAVEPOINT hv_remote_statement";
|
|
697
|
+
const release = `RELEASE ${savepoint}`;
|
|
698
|
+
await tx.execute(savepoint);
|
|
699
|
+
let aborted;
|
|
700
|
+
const assertActive = () => {
|
|
701
|
+
if (aborted) throw aborted.error;
|
|
702
|
+
};
|
|
703
|
+
const abort = (error) => {
|
|
704
|
+
aborted = { error };
|
|
705
|
+
tx.close();
|
|
706
|
+
};
|
|
707
|
+
return {
|
|
708
|
+
get closed() {
|
|
709
|
+
return tx.closed;
|
|
710
|
+
},
|
|
711
|
+
async execute(statement) {
|
|
712
|
+
assertActive();
|
|
713
|
+
try {
|
|
714
|
+
const [, result] = await tx.batch([
|
|
715
|
+
release,
|
|
716
|
+
statement,
|
|
717
|
+
savepoint
|
|
718
|
+
]);
|
|
719
|
+
return result;
|
|
720
|
+
} catch (error) {
|
|
721
|
+
abort(error);
|
|
722
|
+
throw error;
|
|
723
|
+
}
|
|
724
|
+
},
|
|
725
|
+
async executeScoped(statement) {
|
|
726
|
+
assertActive();
|
|
727
|
+
try {
|
|
728
|
+
const [, , result] = await tx.batch([
|
|
729
|
+
release,
|
|
730
|
+
savepoint,
|
|
731
|
+
statement
|
|
732
|
+
]);
|
|
733
|
+
return result;
|
|
734
|
+
} catch (error) {
|
|
735
|
+
if (error?.statementIndex === 2) try {
|
|
736
|
+
await tx.batch([release, savepoint]);
|
|
737
|
+
} catch {
|
|
738
|
+
abort(error);
|
|
739
|
+
}
|
|
740
|
+
else abort(error);
|
|
741
|
+
throw error;
|
|
742
|
+
}
|
|
743
|
+
},
|
|
744
|
+
async commit() {
|
|
745
|
+
assertActive();
|
|
746
|
+
await tx.commit();
|
|
747
|
+
},
|
|
748
|
+
rollback: () => tx.rollback(),
|
|
749
|
+
close: () => tx.close()
|
|
750
|
+
};
|
|
751
|
+
}
|
|
752
|
+
function remoteLibSqlUrl(url) {
|
|
753
|
+
const normalized = url.replace(/[\t\n\r]/g, "").trim();
|
|
754
|
+
return /^(?:https?|libsql):/i.test(normalized) ? normalized : void 0;
|
|
755
|
+
}
|
|
687
756
|
/**
|
|
688
757
|
* Orders secure adapter calls at public invocation time.
|
|
689
758
|
*
|
|
@@ -1124,9 +1193,8 @@ function generateDbId() {
|
|
|
1124
1193
|
async function createLibSQLClient(options) {
|
|
1125
1194
|
const { url = ":memory:", authToken, encryptionKey } = options;
|
|
1126
1195
|
let libsqlUrl = url;
|
|
1127
|
-
const remoteUrl = url
|
|
1128
|
-
|
|
1129
|
-
if (hasRemoteScheme) {
|
|
1196
|
+
const remoteUrl = remoteLibSqlUrl(url);
|
|
1197
|
+
if (remoteUrl) {
|
|
1130
1198
|
libsqlUrl = remoteUrl;
|
|
1131
1199
|
let parsedRemoteUrl;
|
|
1132
1200
|
try {
|
|
@@ -1140,7 +1208,7 @@ async function createLibSQLClient(options) {
|
|
|
1140
1208
|
throw new DatabaseError(`Invalid remote database URL: ${safeUrl}`, { url: safeUrl });
|
|
1141
1209
|
}
|
|
1142
1210
|
}
|
|
1143
|
-
if (url !== ":memory:" && !
|
|
1211
|
+
if (url !== ":memory:" && !remoteUrl && !url.startsWith("file:")) {
|
|
1144
1212
|
const { resolve } = await import("node:path");
|
|
1145
1213
|
libsqlUrl = `file://${resolve(url)}`;
|
|
1146
1214
|
}
|
|
@@ -1154,7 +1222,7 @@ async function createLibSQLClient(options) {
|
|
|
1154
1222
|
authToken,
|
|
1155
1223
|
encryptionKey
|
|
1156
1224
|
});
|
|
1157
|
-
if (!
|
|
1225
|
+
if (!remoteUrl && url !== ":memory:") {
|
|
1158
1226
|
const dispose = client.close.bind(client);
|
|
1159
1227
|
let invalidated;
|
|
1160
1228
|
const guard = async (operation) => {
|
|
@@ -1274,6 +1342,30 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
1274
1342
|
return (async () => {
|
|
1275
1343
|
const connectionLock = createTransactionLock("sqlite", options.transactionQueueTimeout);
|
|
1276
1344
|
const client = await clientFactory();
|
|
1345
|
+
const remote = remoteLibSqlUrl(url) !== void 0;
|
|
1346
|
+
const reservesTransaction = remote || client.transactionReservation === "exclusive";
|
|
1347
|
+
const prepareStatement = (statement) => {
|
|
1348
|
+
const managed = prepareManagedStatement(remote && Array.isArray(statement) ? {
|
|
1349
|
+
sql: statement[0],
|
|
1350
|
+
args: statement[1]
|
|
1351
|
+
} : statement);
|
|
1352
|
+
return remote ? prepareRemoteStatement(managed) : managed;
|
|
1353
|
+
};
|
|
1354
|
+
const withExecuteArgs = (statement, args) => remote && typeof statement === "string" && args !== void 0 ? {
|
|
1355
|
+
sql: statement,
|
|
1356
|
+
args
|
|
1357
|
+
} : statement;
|
|
1358
|
+
const alreadyRolledBack = (error) => remote && error?.code === "TRANSACTION_TIMEOUT";
|
|
1359
|
+
const acquireTransaction = async () => {
|
|
1360
|
+
if (!remote) return client.transaction("write");
|
|
1361
|
+
const tx = await client.transaction("write");
|
|
1362
|
+
try {
|
|
1363
|
+
return await guardRemoteTransaction(tx);
|
|
1364
|
+
} catch (error) {
|
|
1365
|
+
tx.close();
|
|
1366
|
+
throw error;
|
|
1367
|
+
}
|
|
1368
|
+
};
|
|
1277
1369
|
const executorContext = new AsyncLocalStorage();
|
|
1278
1370
|
const transactionCallbackContext = new AsyncLocalStorage();
|
|
1279
1371
|
const currentExecutor = () => executorContext.getStore() ?? client;
|
|
@@ -1831,7 +1923,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
1831
1923
|
} catch (drainError) {
|
|
1832
1924
|
if (drainError !== error) failure = combineTransactionFailures(error, drainError);
|
|
1833
1925
|
}
|
|
1834
|
-
try {
|
|
1926
|
+
if (!remote || !transactionClient.closed) try {
|
|
1835
1927
|
await transactionClient.execute({
|
|
1836
1928
|
sql: `ROLLBACK TO SAVEPOINT ${name}`,
|
|
1837
1929
|
args: []
|
|
@@ -1841,7 +1933,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
1841
1933
|
args: []
|
|
1842
1934
|
});
|
|
1843
1935
|
} catch (teardownError) {
|
|
1844
|
-
if (teardownError !== failure) failure = combineTransactionFailures(failure, teardownError);
|
|
1936
|
+
if (teardownError !== failure && !alreadyRolledBack(teardownError)) failure = combineTransactionFailures(failure, teardownError);
|
|
1845
1937
|
}
|
|
1846
1938
|
throw failure;
|
|
1847
1939
|
}
|
|
@@ -1893,7 +1985,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
1893
1985
|
const transaction = async (callback, preAcquiredLock) => {
|
|
1894
1986
|
const releaseConnection = await (preAcquiredLock ?? connectionLock.acquire());
|
|
1895
1987
|
try {
|
|
1896
|
-
if (
|
|
1988
|
+
if (!reservesTransaction) {
|
|
1897
1989
|
let nestedTransaction;
|
|
1898
1990
|
let transactionScope;
|
|
1899
1991
|
try {
|
|
@@ -1933,7 +2025,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
1933
2025
|
throw failure;
|
|
1934
2026
|
}
|
|
1935
2027
|
}
|
|
1936
|
-
const transactionClient = await
|
|
2028
|
+
const transactionClient = await acquireTransaction();
|
|
1937
2029
|
let nestedTransaction;
|
|
1938
2030
|
let transactionScope;
|
|
1939
2031
|
try {
|
|
@@ -1960,7 +2052,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
1960
2052
|
if (!transactionClient.closed) try {
|
|
1961
2053
|
await transactionClient.rollback();
|
|
1962
2054
|
} catch (rollbackError) {
|
|
1963
|
-
failure = combineTransactionFailures(failure, rollbackError);
|
|
2055
|
+
if (!alreadyRolledBack(rollbackError)) failure = combineTransactionFailures(failure, rollbackError);
|
|
1964
2056
|
}
|
|
1965
2057
|
throw failure;
|
|
1966
2058
|
} finally {
|
|
@@ -1982,9 +2074,9 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
1982
2074
|
* transaction's work while later writes silently committed in autocommit.
|
|
1983
2075
|
*/
|
|
1984
2076
|
const createTransactionScope = (transactionClient, nestedTransaction, runOperation = nestedTransaction.runOperation, runNested = nestedTransaction.runNested) => {
|
|
1985
|
-
const
|
|
1986
|
-
|
|
1987
|
-
return transactionClient.execute(
|
|
2077
|
+
const scopedExecutor = reservesTransaction ? { execute: (statement) => {
|
|
2078
|
+
const prepared = prepareStatement(statement);
|
|
2079
|
+
return transactionClient.executeScoped ? transactionClient.executeScoped(prepared) : transactionClient.execute(prepared);
|
|
1988
2080
|
} } : transactionClient;
|
|
1989
2081
|
let accepting = true;
|
|
1990
2082
|
const pending = /* @__PURE__ */ new Set();
|
|
@@ -1993,7 +2085,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
1993
2085
|
const bind = (fn, trackFailure = true) => ((...args) => {
|
|
1994
2086
|
if (!accepting) return Promise.reject(new DatabaseError("Transaction scope is ending or ended", {}));
|
|
1995
2087
|
const run = () => Promise.resolve(executorContext.run(scopedExecutor, () => fn(...args)));
|
|
1996
|
-
const operation =
|
|
2088
|
+
const operation = reservesTransaction ? runOperation(run) : run();
|
|
1997
2089
|
const tracked = {
|
|
1998
2090
|
observed: false,
|
|
1999
2091
|
handlers: /* @__PURE__ */ new Set(),
|
|
@@ -2045,14 +2137,14 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
2045
2137
|
});
|
|
2046
2138
|
const scopedClient = {
|
|
2047
2139
|
transactionReservation: "exclusive",
|
|
2048
|
-
execute: bind((statement) => scopedExecutor.execute(statement)),
|
|
2140
|
+
execute: bind((statement, args) => scopedExecutor.execute(withExecuteArgs(statement, args))),
|
|
2049
2141
|
transaction: () => Promise.reject(new DatabaseError("Use the transaction scope transaction() method instead of client.transaction()", {})),
|
|
2050
2142
|
close: () => Promise.reject(new DatabaseError("Transaction-scoped SQLite clients cannot be closed directly", {}))
|
|
2051
2143
|
};
|
|
2052
2144
|
return {
|
|
2053
2145
|
database: {
|
|
2054
2146
|
url,
|
|
2055
|
-
client:
|
|
2147
|
+
client: reservesTransaction ? scopedClient : transactionClient,
|
|
2056
2148
|
insert: scopedInsert,
|
|
2057
2149
|
get: scopedGet,
|
|
2058
2150
|
list: scopedList,
|
|
@@ -2101,7 +2193,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
2101
2193
|
const releaseConnection = await (preAcquiredLock ?? connectionLock.acquire());
|
|
2102
2194
|
let transactionClient;
|
|
2103
2195
|
try {
|
|
2104
|
-
if (
|
|
2196
|
+
if (reservesTransaction) transactionClient = await acquireTransaction();
|
|
2105
2197
|
else await client.execute({
|
|
2106
2198
|
sql: "BEGIN TRANSACTION",
|
|
2107
2199
|
args: []
|
|
@@ -2140,7 +2232,7 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
2140
2232
|
if (transactionClient && !transactionClient.closed) try {
|
|
2141
2233
|
await transactionClient.rollback();
|
|
2142
2234
|
} catch (rollbackError) {
|
|
2143
|
-
failure = combineTransactionFailures(failure, rollbackError);
|
|
2235
|
+
if (!alreadyRolledBack(rollbackError)) failure = combineTransactionFailures(failure, rollbackError);
|
|
2144
2236
|
}
|
|
2145
2237
|
else if (!transactionClient) try {
|
|
2146
2238
|
await client.execute({
|
|
@@ -2527,10 +2619,10 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
2527
2619
|
alterTable,
|
|
2528
2620
|
close: rawClose
|
|
2529
2621
|
};
|
|
2530
|
-
if (
|
|
2622
|
+
if (!reservesTransaction) return db;
|
|
2531
2623
|
const barrier = createInvocationBarrier();
|
|
2532
2624
|
const managedRootExecutor = { execute: (statement) => {
|
|
2533
|
-
return client.execute(
|
|
2625
|
+
return client.execute(prepareStatement(statement));
|
|
2534
2626
|
} };
|
|
2535
2627
|
const rootCallbackError = (operation) => operation === "close" ? new DatabaseError("Cannot close the SQLite database from inside its active transaction callback", { hint: "Finish the transaction callback before closing the database." }) : new DatabaseError("Cannot use the root SQLite database from inside its active transaction callback", { hint: "Use the transaction-scoped database passed to the callback." });
|
|
2536
2628
|
const reservedClose = () => {
|
|
@@ -2620,15 +2712,18 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
2620
2712
|
const reservedBeginTransaction = () => reserveTransactionEntry((preAcquiredLock) => beginTransaction(preAcquiredLock));
|
|
2621
2713
|
const reservedClient = {
|
|
2622
2714
|
transactionReservation: "exclusive",
|
|
2623
|
-
execute: reserveManaged(
|
|
2624
|
-
return client.execute(prepareManagedStatement(statement));
|
|
2625
|
-
}),
|
|
2715
|
+
execute: reserveManaged((statement, args) => managedRootExecutor.execute(withExecuteArgs(statement, args))),
|
|
2626
2716
|
transaction: () => Promise.reject(new DatabaseError("Use database.transaction() or database.beginTransaction() instead of client.transaction()", {})),
|
|
2627
2717
|
close: reservedClose
|
|
2628
2718
|
};
|
|
2719
|
+
const publicClient = remote ? new Proxy(client, { get(target, property) {
|
|
2720
|
+
if (property === "execute" || property === "close") return reservedClient[property];
|
|
2721
|
+
const value = Reflect.get(target, property, target);
|
|
2722
|
+
return typeof value === "function" ? reserveManaged(value.bind(target)) : value;
|
|
2723
|
+
} }) : reservedClient;
|
|
2629
2724
|
return {
|
|
2630
2725
|
...db,
|
|
2631
|
-
client:
|
|
2726
|
+
client: publicClient,
|
|
2632
2727
|
query: reserveManaged(query),
|
|
2633
2728
|
insert: reserveManaged(insert),
|
|
2634
2729
|
update: reserveManaged(update),
|
|
@@ -2661,4 +2756,4 @@ async function createDatabase(options, url, clientFactory = () => createLibSQLCl
|
|
|
2661
2756
|
//#endregion
|
|
2662
2757
|
export { getDatabase };
|
|
2663
2758
|
|
|
2664
|
-
//# sourceMappingURL=sqlite-
|
|
2759
|
+
//# sourceMappingURL=sqlite-BVpWPLcf.js.map
|