{"record":{"id":"6f2f154801f75a6e","repo":"tursodatabase/turso","slug":"checkpoint-is-only-available-for-sync-databases","errorCode":null,"errorMessage":"checkpoint() is only available for sync databases","messagePattern":"checkpoint\\(\\) is only available for sync databases","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/react-native/src/Database.ts","lineNumber":400,"sourceCode":"   * Get sync statistics (sync databases only)\n   *\n   * @returns Sync stats\n   */\n  async stats(): Promise<SyncStats> {\n    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {\n      throw new Error('stats() is only available for sync databases');\n    }\n\n    const operation = this._nativeSyncDb.stats();\n    return driveStatsOperation(operation, this._nativeSyncDb, this._ioContext);\n  }\n\n  /**\n   * Checkpoint database (sync databases only)\n   */\n  async checkpoint(): Promise<void> {\n    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {\n      throw new Error('checkpoint() is only available for sync databases');\n    }\n\n    const operation = this._nativeSyncDb.checkpoint();\n    await driveVoidOperation(operation, this._nativeSyncDb, this._ioContext);\n  }\n\n  /**\n   * Close the database\n   */\n  close(): void {\n    if (this._closed) {\n      return;\n    }\n\n    if (this._connection) {\n      this._connection.close();\n      this._connection = null;\n    }","sourceCodeStart":382,"sourceCodeEnd":418,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/bindings/react-native/src/Database.ts#L382-L418","documentation":"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.","triggerScenarios":"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.","commonSituations":"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().","solutions":["Ensure the Database is sync-configured (url option present) and `await db.connect()` has resolved before checkpoint()","Wrap maintenance code in `if (db.isSync) { ... }` when the app also ships local-only","Schedule checkpoints from a single place that already owns the database lifecycle, after connect resolves"],"exampleFix":"// before\nAppState.addEventListener('change', async (s) => {\n  if (s === 'background') await db.checkpoint(); // throws if local-only\n});\n\n// after\nAppState.addEventListener('change', async (s) => {\n  if (s === 'background' && db.isSync) {\n    await db.checkpoint();\n  }\n});","handlingStrategy":"type-guard","validationCode":"if (!db.isSync || !db.open) {\n  return; // checkpoint() is a sync-database operation\n}\nawait db.checkpoint();","typeGuard":"function canCheckpoint(db: Database): boolean {\n  return db.isSync && db.open;\n}","tryCatchPattern":"try {\n  await db.checkpoint();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('only available for sync databases')) {\n    return; // local-only: nothing to checkpoint via sync engine\n  }\n  throw e;\n}","preventionTips":["Schedule maintenance checkpoints from code that already owns the db lifecycle and knows isSync","Await connect() before any checkpoint call"],"tags":["react-native","sync","api-misuse","checkpoint","wal"],"backgroundTag":"sync-mode-required","analyzedSha":"244cde92a7df7f9b8b8b7a4075c35a12977e303e","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}