{"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/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/react-native/src/Database.ts#L382-L418","documentation":"checkpoint() runs the native sync database's checkpoint operation to truncate the local WAL after synchronization. As with the other sync-only methods, it requires _isSync (url present in opts), plus the _nativeSyncDb and _ioContext that connect() creates in sync mode; otherwise it throws. A local-only database manages its WAL through the regular query path, not through this API.","triggerScenarios":"`new Database({ path })` with no url followed by `await db.checkpoint()`; maintenance code that checkpoints on a schedule or after N writes running against a local-mode handle; calling checkpoint() before connect() completes.","commonSituations":"Porting WAL-management logic from the WASM sync binding to React Native without enabling sync config; background jobs that treat every database as synced; startup sequences that checkpoint before connect resolves.","solutions":["Construct the database with `url` and `authToken` so sync mode is active","Call `await db.connect()` before checkpoint(), typically after push/pull cycles","Remove the call for databases that intentionally stay local-only"],"exampleFix":"// before\nconst db = new Database({ path: 'app.db' });\nawait db.checkpoint(); // throws\n\n// after\nconst db = new Database({ path: 'app.db', url, authToken });\nawait db.connect();\nawait db.pull();\nawait db.checkpoint();","handlingStrategy":"validation","validationCode":"if (isSyncConfig(opts)) {\n  await db.connect();\n  await db.push();\n  await db.checkpoint(); // only after a successful sync-mode connect\n}","typeGuard":null,"tryCatchPattern":"try { await db.checkpoint(); } catch (e) { if (e instanceof Error && e.message.includes('only available for sync databases')) return; throw e; }","preventionTips":["Run checkpoint as part of the sync maintenance cycle, not generic schedulers","Verify url was passed before wiring WAL management calls","Await connect() before any sync-lifecycle operation"],"tags":["react-native","sync","checkpoint","wal","configuration"],"backgroundTag":"feature-not-enabled","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}