{"record":{"id":"f21b4c22ec341e15","repo":"tursodatabase/turso","slug":"push-is-only-available-for-sync-databases","errorCode":null,"errorMessage":"push() is only available for sync databases","messagePattern":"push\\(\\) is only available for sync databases","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/react-native/src/Database.ts","lineNumber":348,"sourceCode":"  async transaction<T>(fn: () => T | Promise<T>): Promise<T> {\n    this.checkOpen();\n    await this.exec('BEGIN');\n    try {\n      const result = await fn();\n      await this.exec('COMMIT');\n      return result;\n    } catch (error) {\n      await this.exec('ROLLBACK');\n      throw error;\n    }\n  }\n\n  /**\n   * Push local changes to remote (sync databases only)\n   */\n  async push(): Promise<void> {\n    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {\n      throw new Error('push() is only available for sync databases');\n    }\n\n    const operation = this._nativeSyncDb.pushChanges();\n    await driveVoidOperation(operation, this._nativeSyncDb, this._ioContext);\n  }\n\n  /**\n   * Pull remote changes and apply locally (sync databases only)\n   *\n   * @returns true if changes were applied, false if no changes\n   */\n  async pull(): Promise<boolean> {\n    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {\n      throw new Error('pull() is only available for sync databases');\n    }\n\n    // Wait for changes\n    const waitOperation = this._nativeSyncDb.waitChanges();","sourceCodeStart":330,"sourceCodeEnd":366,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/react-native/src/Database.ts#L330-L366","documentation":"push() on the React Native Database uploads local changes through the native sync database object. The guard requires three things that only exist on a connected sync database: _isSync (set in the constructor when opts.url is non-null), _nativeSyncDb, and _ioContext (both created during connect() in sync mode). If the database is local-only, or sync mode was configured but connect() has not completed, the call throws.","triggerScenarios":"`new Database({ path: 'app.db' })` with no url followed by `await db.push()`; constructing with url but calling push() before `await db.connect()` finishes; a sync-call helper invoked on a database whose connect() failed earlier (leaving _nativeSyncDb null).","commonSituations":"Adding sync calls to an app first built as local-only; race conditions at app startup where sync runs before connect resolves; code shared between local and synced screens; error paths where connect() threw and later code still attempts to push.","solutions":["Pass `url` (and `authToken`) to the Database constructor so it is created in sync mode","Always `await db.connect()` before any push/pull/stats/checkpoint call","Guard the call site: keep a typed 'synced database' wrapper so push() is unreachable for local handles"],"exampleFix":"// before\nconst db = new Database({ path: 'app.db' }); // no url -> local mode\nawait db.push(); // throws\n\n// after\nconst db = new Database({ path: 'app.db', url, authToken });\nawait db.connect();\nawait db.push();","handlingStrategy":"validation","validationCode":"// Mode is decided by url presence in the constructor opts — check it, and gate on connect()\nfunction isSyncConfig(opts: DatabaseOpts): boolean {\n  return opts.url !== undefined && opts.url !== null;\n}\n\nif (isSyncConfig(opts)) {\n  await db.connect(); // creates _nativeSyncDb + _ioContext\n  await db.push();\n}","typeGuard":null,"tryCatchPattern":"try { await db.push(); } catch (e) { if (e instanceof Error && e.message.includes('only available for sync databases')) { /* wrong mode or not connected: fix config/lifecycle */ } throw e; }","preventionTips":["Await connect() once and share that promise; never let sync calls race it","Only enable push in app flavors where url is configured","After a failed connect(), reconnect before retrying push"],"tags":["react-native","sync","push","configuration","lifecycle"],"backgroundTag":"feature-not-enabled","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}