TanStack · simolus3 · Jul 21, 2026 · Jul 21, 2026 · coderabbitai · Jul 21, 2026
diff --git a/.changeset/olive-guests-bathe.md b/.changeset/olive-guests-bathe.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/powersync-db-collection': minor
+---
+
+Upgrade PowerSync to version 2.
diff --git a/docs/collections/powersync-collection.md b/docs/collections/powersync-collection.md
@@ -58,7 +58,7 @@ const db = new PowerSyncDatabase({
 
 ```ts
 import {
-  AbstractPowerSyncDatabase,
+  CommonPowerSyncDatabase,
   PowerSyncBackendConnector,
   PowerSyncCredentials,
 } from "@powersync/web"
@@ -69,11 +69,11 @@ class Connector implements PowerSyncBackendConnector {
 
   /** Upload local changes to the app backend.
    *
-   * Use {@link AbstractPowerSyncDatabase.getCrudBatch} to get a batch of changes to upload.
+   * Use {@link CommonPowerSyncDatabase.getCrudBatch} to get a batch of changes to upload.
    *
    * Any thrown errors will result in a retry after the configured wait period (default: 5 seconds).
    */
-  uploadData: (database: AbstractPowerSyncDatabase) => Promise<void>
+  uploadData: (database: CommonPowerSyncDatabase) => Promise<void>
 }
 
 // Configure the client to connect to a PowerSync service and your backend

diff --git a/packages/powersync-db-collection/package.json b/packages/powersync-db-collection/package.json
@@ -59,11 +59,11 @@
     "p-defer": "^4.0.1"
   },
   "peerDependencies": {
-    "@powersync/common": "^1.41.0"
+    "@powersync/common": "^2.0.0"
   },
   "devDependencies": {
-    "@powersync/common": "1.49.0",
-    "@powersync/node": "0.18.1",
+    "@powersync/common": "^2.0.0",
+    "@powersync/node": "^0.20.0",
     "@types/debug": "^4.1.12",
     "@vitest/coverage-istanbul": "^3.2.4",
     "better-sqlite3": "^12.6.2"

diff --git a/packages/powersync-db-collection/src/PowerSyncTransactor.ts b/packages/powersync-db-collection/src/PowerSyncTransactor.ts
@@ -1,8 +1,8 @@
-import { sanitizeSQL } from '@powersync/common'
+import { LogLevels, sanitizeSQL } from '@powersync/common'
 import DebugModule from 'debug'
 import { PendingOperationStore } from './PendingOperationStore'
 import { asPowerSyncRecord, mapOperationToPowerSync } from './helpers'
-import type { AbstractPowerSyncDatabase, LockContext } from '@powersync/common'
+import type { CommonPowerSyncDatabase, LockContext } from '@powersync/common'
 import type { PendingMutation, Transaction } from '@tanstack/db'
 import type { PendingOperation } from './PendingOperationStore'
 import type {
@@ -13,7 +13,7 @@ import type {
 const debug = DebugModule.debug(`ts/db:powersync`)
 
 export type TransactorOptions = {
-  database: AbstractPowerSyncDatabase
+  database: CommonPowerSyncDatabase
 }
 
 /**
@@ -52,7 +52,7 @@ export type TransactorOptions = {
  * @returns A promise that resolves when the mutations have been persisted to PowerSync
  */
 export class PowerSyncTransactor {
-  database: AbstractPowerSyncDatabase
+  database: CommonPowerSyncDatabase
   pendingOperationStore: PendingOperationStore
 
   constructor(options: TransactorOptions) {
@@ -321,10 +321,10 @@ export class PowerSyncTransactor {
       // If it's not supported, we don't store metadata.
       if (typeof mutation.metadata != `undefined`) {
         // Log a warning if metadata is provided but not tracked.
-        this.database.logger.warn(
-          `Metadata provided for collection ${mutation.collection.id} but the PowerSync table does not track metadata. The PowerSync table should be configured with trackMetadata: true.`,
-          mutation.metadata,
-        )
+        this.database.logger.log({
+          level: LogLevels.info,
+          message: `Metadata provided for collection ${mutation.collection.id} but the PowerSync table does not track metadata. The PowerSync table should be configured with trackMetadata: true.`,
+        })
       }
       return null
     } else if (typeof mutation.metadata == `undefined`) {

diff --git a/packages/powersync-db-collection/src/helpers.ts b/packages/powersync-db-collection/src/helpers.ts
@@ -2,6 +2,7 @@ import { DiffTriggerOperation } from '@powersync/common'
 import type {
   BaseColumnType,
   ExtractColumnValueType,
+  RowType,
   Table,
 } from '@powersync/common'
 
@@ -28,11 +29,11 @@ type OptionalIfUndefined<T> = {
 /**
  * Provides the base column types for a table. This excludes the `id` column.
  */
-export type ExtractedTableColumns<TTable extends Table> = {
-  [K in keyof TTable[`columnMap`]]: ExtractColumnValueType<
-    TTable[`columnMap`][K]
-  >
-}
+export type ExtractedTableColumns<TTable extends Table<any>> = Omit<
+  RowType<TTable>,
+  'id'
+>
+
 /**
  * Utility type that extracts the typed structure of a table based on its column definitions.
  * Maps each column to its corresponding TypeScript type using ExtractColumnValueType.
@@ -48,25 +49,25 @@ export type ExtractedTableColumns<TTable extends Table> = {
  * // Results in: { id: string, name: string | null, age: number | null }
  * ```
  */
-export type ExtractedTable<TTable extends Table> =
-  ExtractedTableColumns<TTable> & {
-    id: string
-  }
+export type ExtractedTable<TTable extends Table> = RowType<TTable>
 
-export type OptionalExtractedTable<TTable extends Table> = OptionalIfUndefined<{
-  [K in keyof TTable[`columnMap`]]: WithUndefinedIfNull<
-    ExtractColumnValueType<TTable[`columnMap`][K]>
-  >
-}> & {
-  id: string
-}
+export type OptionalExtractedTable<TTable extends Table> =
+  TTable extends Table<infer Columns>
+    ? OptionalIfUndefined<{
+        [K in keyof Columns]: WithUndefinedIfNull<
+          ExtractColumnValueType<Columns[K]>
+        >
+      }> & {
+        id: string
+      }
+    : never
 
 /**
  * Maps the schema of TTable to a type which
  * requires the keys be equal, but the values can have any value type.
  */
 export type AnyTableColumnType<TTable extends Table> = {
-  [K in keyof TTable[`columnMap`]]: any
+  [K in keyof ExtractedTableColumns<TTable>]: any
 } & { id: string }
-/**
- * Maps the schema of TTable to a type which
- * requires the keys be equal, but the values can have any value type.
- */
-export type AnyTableColumnType<TTable extends Table> = {
-  [K in keyof TTable[`columnMap`]]: any
-  [K in keyof ExtractedTableColumns<TTable>]: any
-} & { id: string }
+/**
+ * Maps the schema of TTable to a type which
+ * requires the keys be equal, but the values can have any value type.
+ */
+export type AnyTableColumnType<TTable extends Table> = {
+  [K in keyof ExtractedTableColumns<TTable>]: unknown
+} & { id: string }
-/**
- * Maps the schema of TTable to a type which
- * requires the keys be equal, but the values can have any value type.
- */
-export type AnyTableColumnType<TTable extends Table> = {
-  [K in keyof TTable[`columnMap`]]: any
-  [K in keyof ExtractedTableColumns<TTable>]: any
-} & { id: string }
+/**
+ * Maps the schema of TTable to a type which
+ * requires the keys be equal, but the values can have any value type.
+ */
+export type AnyTableColumnType<TTable extends Table> = {
+  [K in keyof ExtractedTableColumns<TTable>]: unknown
+} & { id: string }
 
 export function asPowerSyncRecord(record: any): PowerSyncRecord {

diff --git a/packages/powersync-db-collection/src/powersync.ts b/packages/powersync-db-collection/src/powersync.ts
@@ -1,4 +1,4 @@
-import { DiffTriggerOperation, sanitizeSQL } from '@powersync/common'
+import { DiffTriggerOperation, LogLevels, sanitizeSQL } from '@powersync/common'
 import { or } from '@tanstack/db'
 import { compileSQLite } from './sqlite-compiler'
 import { PendingOperationStore } from './PendingOperationStore'
@@ -16,16 +16,13 @@ import type {
 import type {
   AnyTableColumnType,
   ExtractedTable,
-  ExtractedTableColumns,
-  MapBaseColumnType,
   OptionalExtractedTable,
 } from './helpers'
 import type {
   BasePowerSyncCollectionConfig,
   ConfigWithArbitraryCollectionTypes,
   ConfigWithSQLiteInputType,
   ConfigWithSQLiteTypes,
-  CustomSQLiteSerializer,
   EnhancedPowerSyncCollectionConfig,
   InferPowerSyncOutputType,
   PowerSyncCollectionConfig,
@@ -262,12 +259,15 @@ export function powerSyncCollectionOptions<
       return validation.value
     } else if (`issues` in validation) {
       const issueMessage = `Failed to validate incoming data for ${viewName}. Issues: ${validation.issues.map((issue) => `${issue.path} - ${issue.message}`)}`
-      database.logger.error(issueMessage)
+      database.logger.log({ level: LogLevels.error, message: issueMessage })
       onDeserializationError!(validation)
       throw new Error(issueMessage)
     } else {
       const unknownErrorMessage = `Unknown deserialization error for ${viewName}`
-      database.logger.error(unknownErrorMessage)
+      database.logger.log({
+        level: LogLevels.error,
+        message: unknownErrorMessage,
+      })
       onDeserializationError!({ issues: [{ message: unknownErrorMessage }] })
       throw new Error(unknownErrorMessage)
     }
@@ -358,9 +358,10 @@ export function powerSyncCollectionOptions<
                 commit()
               }
               onReady()
-              database.logger.info(
-                `Sync is ready for ${viewName} into ${trackedTableName}`,
-              )
+              database.logger.log({
+                level: LogLevels.info,
+                message: `Sync is ready for ${viewName} into ${trackedTableName}`,
+              })
             },
           },
         })
@@ -372,10 +373,11 @@ export function powerSyncCollectionOptions<
             await flushDiffRecordsWithContext(context)
           })
           .catch((error) => {
-            database.logger.error(
-              `An error has been detected in the sync handler`,
+            database.logger.log({
+              level: LogLevels.error,
+              message: `An error has been detected in the sync handler`,
               error,
-            )
+            })
           })
       }
 
@@ -422,18 +424,20 @@ export function powerSyncCollectionOptions<
           commit()
           pendingOperationStore.resolvePendingFor(pendingOperations)
         } catch (error) {
-          database.logger.error(
-            `An error has been detected in the sync handler`,
+          database.logger.log({
+            level: LogLevels.error,
+            message: `An error has been detected in the sync handler`,
             error,
-          )
+          })
         }
       }
 
       // The sync function needs to be synchronous.
       async function start(afterOnChangeRegistered?: () => Promise<void>) {
-        database.logger.info(
-          `Sync is starting for ${viewName} into ${trackedTableName}`,
-        )
+        database.logger.log({
+          level: LogLevels.info,
+          message: `Sync is starting for ${viewName} into ${trackedTableName}`,
+        })
         database.onChangeWithCallback(
           {
             onChange: async () => {
@@ -490,16 +494,18 @@ export function powerSyncCollectionOptions<
             onReady: () => markReady(),
           })
         }).catch((error) =>
-          database.logger.error(
-            `Could not start syncing process for ${viewName} into ${trackedTableName}`,
+          database.logger.log({
+            level: LogLevels.error,
+            message: `Could not start syncing process for ${viewName} into ${trackedTableName}`,
             error,
-          ),
+          }),
         )
 
         return () => {
-          database.logger.info(
-            `Sync has been stopped for ${viewName} into ${trackedTableName}`,
-          )
+          database.logger.log({
+            level: LogLevels.info,
+            message: `Sync has been stopped for ${viewName} into ${trackedTableName}`,
+          })
           abortController.abort()
           onUnload?.()
         }
@@ -511,10 +517,11 @@ export function powerSyncCollectionOptions<
         let onUnloadSubset: CleanupFn | void | null = null
 
         start().catch((error) =>
-          database.logger.error(
-            `Could not start syncing process for ${viewName} into ${trackedTableName}`,
+          database.logger.log({
+            level: LogLevels.error,
+            message: `Could not start syncing process for ${viewName} into ${trackedTableName}`,
             error,
-          ),
+          }),
         )
 
         // Tracks all active WHERE expressions for on-demand sync filtering.
@@ -651,9 +658,10 @@ export function powerSyncCollectionOptions<
 
         return {
           cleanup: () => {
-            database.logger.info(
-              `Sync has been stopped for ${viewName} into ${trackedTableName}`,
-            )
+            database.logger.log({
+              level: LogLevels.info,
+              message: `Sync has been stopped for ${viewName} into ${trackedTableName}`,
+            })
             abortController.abort()
           },
           loadSubset: (options: LoadSubsetOptions) => loadSubset(options),
@@ -672,7 +680,9 @@ export function powerSyncCollectionOptions<
     OutputType,
     TSchema
   > = {
-    ...restConfig,
+    ...(restConfig as Partial<
+      EnhancedPowerSyncCollectionConfig<TTable, OutputType, TSchema>
+    >),
     schema,
     getKey,
     // Syncing should start immediately since we need to monitor the changes for mutations
@@ -697,18 +707,7 @@ export function powerSyncCollectionOptions<
         trackedTableName,
         metadataIsTracked,
         serializeValue: (value) =>
-          serializeForSQLite(
-            value,
-            // This is required by the input generic
-            table as Table<
-              MapBaseColumnType<InferPowerSyncOutputType<TTable, TSchema>>
-            >,
-            // Coerce serializer to the shape that corresponds to the Table constructed from OutputType
-            serializer as CustomSQLiteSerializer<
-              OutputType,
-              ExtractedTableColumns<Table<MapBaseColumnType<OutputType>>>
-            >,
-          ),
+          serializeForSQLite<TTable>(value, table, serializer),
       }),
     },
   }

diff --git a/packages/powersync-db-collection/src/serialization.ts b/packages/powersync-db-collection/src/serialization.ts
@@ -2,9 +2,9 @@ import { ColumnType } from '@powersync/common'
 import type { Table } from '@powersync/common'
 import type { CustomSQLiteSerializer } from './definitions'
 import type {
+  AnyTableColumnType,
   ExtractedTable,
   ExtractedTableColumns,
-  MapBaseColumnType,
 } from './helpers'
 
 /**
@@ -37,17 +37,14 @@ import type {
  * - Throws if a key in `value` does not exist in the schema.
  * - Throws if a value cannot be converted to the required SQLite type.
  */
-export function serializeForSQLite<
-  TOutput extends Record<string, unknown>,
-  // The keys should match
-  TTable extends Table<MapBaseColumnType<TOutput>> = Table<
-    MapBaseColumnType<TOutput>
-  >,
->(
-  value: TOutput,
+export function serializeForSQLite<TTable extends Table>(
+  value: AnyTableColumnType<TTable>,
   tableSchema: TTable,
   customSerializer: Partial<
-    CustomSQLiteSerializer<TOutput, ExtractedTableColumns<TTable>>
+    CustomSQLiteSerializer<
+      AnyTableColumnType<TTable>,
+      ExtractedTableColumns<TTable>
+    >
   > = {},
 ): ExtractedTable<TTable> {
   return Object.fromEntries(
@@ -68,7 +65,7 @@ export function serializeForSQLite<
 
       const customTransform = customSerializer[key]
       if (customTransform) {
-        return [key, customTransform(value as TOutput[string])]
+        return [key, customTransform(value)]
       }
 
       // Map to the output
@@ -98,5 +95,5 @@ export function serializeForSQLite<
           }
       }
     }),
-  )
+  ) as ExtractedTable<TTable>
 }