Reference
The tables below list every call in both SDKs and the settings they read. The full reference, with every field of every result, is in the SDK repository on GitHub, and every command of the command line has --help.
SDK calls
Construct a client with new Litebackup({ token, session }) in TypeScript and litebackup.Connect(ctx, &litebackup.ConnectArgs{Token: token, Session: session}) in Go. Go passes a context first and a pointer to the call's Args struct last, and nil uses the defaults.
| TypeScript | Go | Returns when |
|---|---|---|
backups.start(pathOrHandle, options) |
StartBackup(ctx, path, args) |
The backup rule is saved on this machine. |
backups.once(pathOrHandle, options) |
Backup(ctx, path, args) |
The version is on your server, or in your bucket with wait: "cloud". |
backups.stop(name), rules.stop(id) |
StopBackup, StopBackupRule |
The backup or the whole rule has stopped. |
databases.restore(name, { to, version, time }) |
Restore(ctx, name, args) |
The new file is written and checked. |
databases.versions(name, { after, limit }) |
Versions(ctx, name, args) |
It has every kept version, oldest first. |
replicas.start(name, { to }) |
Replicate(ctx, name, args) |
The first version is on this machine. |
replicas.startPrefix(prefix, { to }) |
ReplicatePrefix(ctx, prefix, args) |
The prefix is followed, and files arrive in the background. |
failovers.start(path, options) |
Failover(ctx, path, args) |
This machine has a role, and events report each change. |
databases.acquire(name, { to }) |
client.Acquire(ctx, name, args) |
This machine holds the database and has its newest version. |
databases.release(name, { wait, offload }) |
client.Release(ctx, name, args) |
The final changes are safe and the database is free. |
databases.offload(name) |
client.Offload(ctx, name) |
A released local copy is removed once your bucket holds it. |
databases.writer(name) |
client.Writer(ctx, name) |
It knows which machine writes the database and until when. |
session.status(), databases.get(name), databases.sync(name) |
Status, Database, Sync |
It has the state of this machine's databases, and databases.sync waits for your server. |
conflicts.list(), conflicts.delete(id) |
Conflicts, DeleteConflict |
It has listed or removed conflict copies. |
close(), session.shutdown() |
Close, Shutdown |
This connection is closed, or the whole client has stopped. |
Options
Go fields have the same names, capitalized. TypeScript durations are milliseconds or strings such as "30s" and "2m", and Go uses time.Duration.
| Call | Options |
|---|---|
backups.start |
name for an exact name, prefix for a namespace, and maximumLocalDatabases to offload idle files above a count |
backups.once |
name, prefix, wait ("server" by default, or "cloud"), timeout, and in TypeScript signal |
replicas.start |
to, timeout, and writeProtection: "lock" (the default), "detect", or "none" |
failovers.start |
name and timeout, with the events origin, replica, conflictSaved, and error (Go: OnRoleChange, OnConflictSaved, OnError) |
databases.acquire |
to, timeout, machineLabel, offload: "released" (Go: OffloadReleased), maintenance for a checkpoint and VACUUM on release, and onLost: "block" (Go: BlockOnLost) to block writes instead of saving a conflict copy |
databases.release |
wait ("server" by default, or "cloud"), offload, and timeout |
databases.restore |
to, and either version or time |
Environment
| Variable | What it sets |
|---|---|
LITEBACKUP_TOKEN |
The join token and server address, JOIN_TOKEN@HOST, used the first time a client joins. |
LITEBACKUP_SESSION |
The client session, default when unset. Separate sessions keep separate local settings. |
LITEBACKUP_PATH |
The litebackup binary the SDKs start, instead of the one npm installed or the one on PATH. |
XDG_STATE_HOME |
Where a per-user client keeps its identity and backup rules. Put it on a volume in containers. |
XDG_RUNTIME_DIR |
Where a per-user client puts its socket when no service install recorded one. |
States and errors
Every database on a machine has a role, origin or replica, and one of these states.
| State | What it means |
|---|---|
syncing |
Changes are on their way to your server. |
synced |
Your server has every change. |
waiting |
Another machine writes the database. |
offloaded |
The local copy was removed, and your bucket holds it. |
stopped |
Litebackup no longer follows the file. |
conflicted |
A conflict copy needs a decision. |
error |
The database's last error says what to fix. |
Errors from the client are LitebackupError in TypeScript and *litebackup.Error in Go, which litebackup.IsCode(err, "in_use") checks. Their code is one of busy, in_use, not_found, exists, still_open, timeout, not_configured, or sdk_unsupported, and the troubleshooting section above explains each.
Command line
Top-level commands such as start, backup, restore, replicate, failover, acquire, and status go to the client on this machine. litebackup server runs on your Litebackup server's own host, litebackup admin reaches your instance over HTTPS after litebackup admin login, and litebackup account manages your litebackup.com account. Add --stdout-format json to any command for JSON output. The command line page has the flags for each task.
Guides
| Guide | What it covers |
|---|---|
| Back up SQLite | Continuous backup for a running app, step by step |
| Point-in-time restore | Choosing the right version and checking the copy |
| Restore a deleted row | Bringing back a few rows without replacing the database |
| Replicate SQLite | Readonly copies for reporting and search |
| High availability | Failover between servers behind a load balancer |
| SQLite in Docker | A pinned image, persistent volumes, and a Compose example |
| Cron and Kubernetes | Scheduled backups that alert when a run fails |
| Temporal | Databases inside Temporal activities and schedules |
When you report a problem, include the SDK and client versions, the operating system and architecture, whether the client runs as a service, the call or command, and the error code. Leave out join tokens, bucket credentials, recovery material, and the contents of your databases.
Install
Install your Litebackup server and back up a first database in minutes: install, or see pricing.