This PR introduces initial protocol for bidirectional sync with conflict
resolution.
The main addition to the usual `Database` interface are two methods:
1. `push` - push all local changes to the remote. Note, that new changes
from the remote will not be visible during request execution after this
procedure.
2. `pull` - pull all remote changes and apply them locally. Note, that
this procedure require temporary block of writes to the local DB as
internally we will manipulate with opened connections and juggle with
few things under the hood.
## Limitations
* Current implementation exposes only query methods on top of the
**database** - because more careful orchestration will be needed when we
will expose `Connection` and `Statement`
* Schema changes are possible to make through synced Database - but they
are actually not synced to the remote
* Current implementation will amplify storage use by 2x
## Implementation overview
Current approach uses pretty stupid idea to maintain 2 copies of the
database and WAL files:
1. `Draft` - this copy will hold local changes and accept all writes
made to the database
2. `Synced` - this copy will hold DB file and WAL synced with remote
This obviously lead to 2x space amplification, but allow us to implement
sync with conflict resolution without changing `turso-core`.
Under the hood, implementation of main operations looks like this:
1. `push`:
a. Pull all recent changes from the remote to `Synced` DB
b. Transfer local changes from `Draft` to `Synced` with the help of
CDC table
c. Push new WAL frames from `Synced` DB to remote
2. `pull`:
a. Pull all recent changes from the remote to `Synced` DB
b. Transfer local changes from `Draft` to `Synced` with the help of
CDC table
c. Copy `Synced` files (DB and WAL) to the `Draft`
d. Reset `Synced` WAL in order to remove frames made by local changes
from it
As operation 2.c can't be made safely without extra work - `turso-sync`
package internally maintains `active` database which can be either
`Draft` or `Synced` and switch will happen exactly before/after step 2.c
as we will need to move all requests from `Draft` DB to `Synced` due to
explicit copy which we will need to perform.
This switch between Databases creates additional troubles and that's why
in this PR only `Database::query` and `Database::execute` methods are
exposed without prepared statements.
<img width="2062" height="977" alt="Untitled-2025-07-14-1259"
src="https://github.com/user-
attachments/assets/64eb5046-d7cb-4af2-87a0-810c0db7eeb5" />
<img width="2062" height="977" alt="Untitled-2025-07-14-1259(1)"
src="https://github.com/user-
attachments/assets/5c20360c-41db-4100-b0ff-9e47c2682e56" />
Closes#2334
- cargo commands invoked from workspace root do not capture custom configuration of RUSTFLAGS
from workspace members
- see relevant issue https://github.com/rust-lang/cargo/issues/7004
Various improvements:
- Make promise API the default for `@tursodatabase/turso`
- Add a compatibility test suite for database, serverless, and better-
sqlite3
- Improve serverless driver a bit to be more compatible.
Closes#2322
We need to use sequence requests to handle multiple SQL statements for exec():
```
DatabaseError {
message: 'SQL string contains more than one statement',
}
```
```
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/Users/penberg/src/tursodatabase/turso/packages/turso-serverless/dist/error' imported from /Users/penberg/src/tursodatabase/turso/packages/turso-serverless/dist/protocol.js
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/Users/penberg/src/tursodatabase/turso/packages/turso-serverless/dist/error' imported from /Users/penberg/src/tursodatabase/turso/packages/turso-serverless/dist/protocol.js
at finalizeResolution (node:internal/modules/esm/resolve:275:11)
at moduleResolve (node:internal/modules/esm/resolve:860:10)
at defaultResolve (node:internal/modules/esm/resolve:984:11)
at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:780:12)
at #cachedDefaultResolve (node:internal/modules/esm/loader:704:25)
at ModuleLoader.resolve (node:internal/modules/esm/loader:687:38)
at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:305:38)
at ModuleJob._link (node:internal/modules/esm/module_job:137:49)
✘ integration-tests/serverless.test.mjs exited with a non-zero exit code: 1
```
This package is for serverless access to the Turso Cloud using SQL over
HTTP protocol. The purpose of this package is to provide the same
interface as `@tursodatabase/turso`, but for serverless environments
that cannot host the database engine.
The package also provides a `@libsql/client` compatibility layer in the
`@tursodatabase/serverless/compat` module for drop-in replacement for
existing clients.
