tursodatabase/turso · error · Error

checkpoint() is only available for sync databases

Error message

checkpoint() is only available for sync databases

What it means

checkpoint() flushes the local WAL into the database file via the native sync database handle; the guard requires _isSync, _nativeSyncDb, and _ioContext. Checkpointing in this binding is tied to the sync engine's lifecycle, so a local-only Database (no `url` option) rejects the call before doing anything.

Solutions

1. Ensure the Database is sync-configured (url option present) and `await db.connect()` has resolved before checkpoint()
2. Wrap maintenance code in `if (db.isSync) { ... }` when the app also ships local-only
3. Schedule checkpoints from a single place that already owns the database lifecycle, after connect resolves

Example fix

// before
AppState.addEventListener('change', async (s) => {
  if (s === 'background') await db.checkpoint(); // throws if local-only
});

// after
AppState.addEventListener('change', async (s) => {
  if (s === 'background' && db.isSync) {
    await db.checkpoint();
  }
});

if (!db.isSync || !db.open) {
  return; // checkpoint() is a sync-database operation
}
await db.checkpoint();

function canCheckpoint(db: Database): boolean {
  return db.isSync && db.open;
}

try {
  await db.checkpoint();
} catch (e) {
  if (e instanceof Error && e.message.includes('only available for sync databases')) {
    return; // local-only: nothing to checkpoint via sync engine
  }
  throw e;
}

When it happens

Trigger: Calling await db.checkpoint() on a Database created with only `{ path }`, or on a sync database before connect() has built the native sync handle and IO context.

Common situations: Background maintenance tasks (periodic checkpoint on app background) written for the sync configuration but running in local-only builds; calling checkpoint right after constructing the Database without awaiting connect().

Related errors

• pull() is only available for sync databases
• push() is only available for sync databases
• stats() is only available for sync databases
• getAllRows: exceeded
• HTTP request failed: . URL: , Method: , Body size: bytes

AI-assisted analysis of tursodatabase/turso@244cde92a7 (2026-08-20). Data as JSON: /api/errors/6f2f154801f75a6e. Report an issue: GitHub.

Appendix: source

Thrown at bindings/react-native/src/Database.ts:400

   * Get sync statistics (sync databases only)
   *
   * @returns Sync stats
   */
  async stats(): Promise<SyncStats> {
    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {
      throw new Error('stats() is only available for sync databases');
    }

    const operation = this._nativeSyncDb.stats();
    return driveStatsOperation(operation, this._nativeSyncDb, this._ioContext);
  }

  /**
   * Checkpoint database (sync databases only)
   */
  async checkpoint(): Promise<void> {
    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {
      throw new Error('checkpoint() is only available for sync databases');
    }

    const operation = this._nativeSyncDb.checkpoint();
    await driveVoidOperation(operation, this._nativeSyncDb, this._ioContext);
  }

  /**
   * Close the database
   */
  close(): void {
    if (this._closed) {
      return;
    }

    if (this._connection) {
      this._connection.close();
      this._connection = null;
    }

View on GitHub (pinned to 244cde92a7)