Add schema options

simolus3 · simolus3 · commit 5e639542188f · 2025-05-07T13:39:10.000+02:00
diff --git a/Package.resolved b/Package.resolved
diff --git a/Package.swift b/Package.swift
@@ -17,7 +17,6 @@ let package = Package(
             targets: ["PowerSync"]),
     ],
     dependencies: [
-        .package(url: "https://github.com/powersync-ja/powersync-kotlin.git", "1.0.1+SWIFT.0"..<"1.1.0+SWIFT.0"),
         .package(url: "https://github.com/powersync-ja/powersync-sqlite-core-swift.git", "0.3.14"..<"0.4.0")
     ],
     targets: [
@@ -26,12 +25,24 @@ let package = Package(
         .target(
             name: packageName,
             dependencies: [
-                .product(name: "PowerSyncKotlin", package: "powersync-kotlin"),
+                .target(name: "PowerSyncKotlin"),
                 .product(name: "PowerSyncSQLiteCore", package: "powersync-sqlite-core-swift")
             ]),
         .testTarget(
             name: "PowerSyncTests",
             dependencies: ["PowerSync"]
         ),
+        // If you want to use a local build, comment out this reference and update the other.
+        // See docs/LocalBuild.md
+        .binaryTarget(
+            name: "PowerSyncKotlin",
+            // TODO: Use GitHub release once https://github.com/powersync-ja/powersync-kotlin/releases/tag/untagged-fde4386dec502ec27067 is published
+            url: "https://fsn1.your-objectstorage.com/simon-public/powersync.zip",
+            checksum: "b6770dc22ae31315adc599e653fea99614226312fe861dbd8764e922a5a83b09"
+        ),
+        // .binaryTarget(
+        //     name: "PowerSyncKotlin",
+        //     path: "/path/to/powersync-kotlin/PowerSyncKotlin/build/XCFrameworks/debug/PowerSyncKotlin.xcframework"
+        // )
     ]
 )
diff --git a/Sources/PowerSync/Kotlin/KotlinAdapter.swift b/Sources/PowerSync/Kotlin/KotlinAdapter.swift
@@ -23,13 +23,25 @@ enum KotlinAdapter {
 
     struct Table {
         static func toKotlin(_ table: TableProtocol) -> PowerSyncKotlin.Table {
-            PowerSyncKotlin.Table(
+            let trackPreviousKotlin: PowerSyncKotlin.TrackPreviousValuesOptions? = if let track = table.trackPreviousValues {
+                PowerSyncKotlin.TrackPreviousValuesOptions(
+                    columnFilter: track.columnFilter,
+                    onlyWhenChanged: track.onlyWhenChanged
+                )
+            } else {
+                nil
+            }
+            
+            return PowerSyncKotlin.Table(
                 name: table.name,
                 columns: table.columns.map { Column.toKotlin($0) },
                 indexes: table.indexes.map { Index.toKotlin($0) },
                 localOnly: table.localOnly,
                 insertOnly: table.insertOnly,
-                viewNameOverride: table.viewNameOverride
+                viewNameOverride: table.viewNameOverride,
+                trackMetadata: table.trackMetadata,
+                trackPreviousValues: trackPreviousKotlin,
+                ignoreEmptyUpdates: table.ignoreEmptyUpdates,
             )
         }
     }
diff --git a/Sources/PowerSync/Kotlin/db/KotlinCrudEntry.swift b/Sources/PowerSync/Kotlin/db/KotlinCrudEntry.swift
@@ -28,9 +28,17 @@ struct KotlinCrudEntry : CrudEntry {
         entry.transactionId?.int64Value
     }
     
+    var metadata: String? {
+        entry.metadata
+    }
+    
     var opData: [String : String?]? {
         /// Kotlin represents this as Map<String, String?>, but this is
         /// converted to [String: Any] by SKIEE
         entry.opData?.mapValues { $0 as? String }
     }
+    
+    var previousValues: [String : String?]? {
+        entry.previousValues?.mapValues { $0 as? String }
+    }
 }
diff --git a/Sources/PowerSync/Protocol/Schema/Table.swift b/Sources/PowerSync/Protocol/Schema/Table.swift
@@ -26,6 +26,46 @@ public protocol TableProtocol {
     ///
     var viewNameOverride: String? { get }
     var viewName: String { get }
+    
+    /// Whether to add a hidden `_metadata` column that will ne abled for updates to
+    /// attach custom information about writes.
+    ///
+    /// When the `_metadata` column is written to for inserts or updates, its value will not be
+    /// part of ``CrudEntry/opData``. Instead, it is reported as ``CrudEntry/metadata``,
+    /// allowing ``PowerSyncBackendConnector``s to handle these updates specially.
+    var trackMetadata: Bool { get }
+    
+    /// When set to a non-`nil` value, track old values of columns for ``CrudEntry/previousValues``.
+    ///
+    /// See ``TrackPreviousValuesOptions`` for details
+    var trackPreviousValues: TrackPreviousValuesOptions? { get }
+    
+    /// Whether an `UPDATE` statement that doesn't change any values should be ignored entirely when
+    /// creating CRUD entries.
+    ///
+    /// This is disabled by default, meaning that an `UPDATE` on a row that doesn't change values would
+    /// create a ``CrudEntry`` with an empty ``CrudEntry/opData`` and ``UpdateType/patch``.
+    var ignoreEmptyUpdates: Bool { get }
+}
+
+/// Options to include old values in ``CrudEntry/previousValues`` for update statements.
+///
+/// These options are enabled by passing them to a non-local ``Table`` constructor.
+public struct TrackPreviousValuesOptions {
+    /// A filter of column names for which updates should be tracked.
+    ///
+    /// When set to a non-`nil` value, columns not included in this list will not appear in
+    /// ``CrudEntry/previousValues``. By default, all columns are included.
+    public let columnFilter: [String]?;
+    
+    /// Whether to only include old values when they were changed by an update, instead of always including
+    /// all old values.
+    public let onlyWhenChanged: Bool;
+    
+    public init(columnFilter: [String]? = nil, onlyWhenChanged: Bool = false) {
+        self.columnFilter = columnFilter
+        self.onlyWhenChanged = onlyWhenChanged
+    }
 }
 
 private let MAX_AMOUNT_OF_COLUMNS = 63
@@ -40,6 +80,9 @@ public struct Table: TableProtocol {
     public let localOnly: Bool
     public let insertOnly: Bool
     public let viewNameOverride: String?
+    public let trackMetadata: Bool
+    public let trackPreviousValues: TrackPreviousValuesOptions?
+    public let ignoreEmptyUpdates: Bool
 
     public var viewName: String {
         viewNameOverride ?? name
@@ -60,14 +103,20 @@ public struct Table: TableProtocol {
         indexes: [Index] = [],
         localOnly: Bool = false,
         insertOnly: Bool = false,
-        viewNameOverride: String? = nil
+        viewNameOverride: String? = nil,
+        trackMetadata: Bool = false,
+        trackPreviousValues: TrackPreviousValuesOptions? = nil,
+        ignoreEmptyUpdates: Bool = false
     ) {
         self.name = name
         self.columns = columns
         self.indexes = indexes
         self.localOnly = localOnly
         self.insertOnly = insertOnly
         self.viewNameOverride = viewNameOverride
+        self.trackMetadata = trackMetadata
+        self.trackPreviousValues = trackPreviousValues
+        self.ignoreEmptyUpdates = ignoreEmptyUpdates
     }
 
     private func hasInvalidSqliteCharacters(_ string: String) -> Bool {
@@ -82,11 +131,20 @@ public struct Table: TableProtocol {
         if columns.count > MAX_AMOUNT_OF_COLUMNS {
             throw TableError.tooManyColumns(tableName: name, count: columns.count)
         }
-
+        
         if let viewNameOverride = viewNameOverride,
            hasInvalidSqliteCharacters(viewNameOverride) {
             throw TableError.invalidViewName(viewName: viewNameOverride)
         }
+        
+        if localOnly {
+            if trackPreviousValues != nil {
+                throw TableError.trackPreviousForLocalTable(tableName: name)
+            }
+            if trackMetadata {
+                throw TableError.metadataForLocalTable(tableName: name)
+            }
+        }
 
         var columnNames = Set<String>(["id"])
 
@@ -156,4 +214,8 @@ public enum TableError: Error {
     case duplicateIndex(tableName: String, indexName: String)
     case invalidIndexName(tableName: String, indexName: String)
     case columnNotFound(tableName: String, columnName: String, indexName: String)
+    /// Local-only tables can't enable ``Table/trackMetadata`` because no updates are tracked for those tables at all.
+    case metadataForLocalTable(tableName: String)
+    /// Local-only tables can't enable ``Table/trackPreviousValues`` because no updates are tracked for those tables at all.
+    case trackPreviousForLocalTable(tableName: String)
 }
diff --git a/Sources/PowerSync/Protocol/db/CrudEntry.swift b/Sources/PowerSync/Protocol/db/CrudEntry.swift
@@ -44,6 +44,20 @@ public protocol CrudEntry {
     /// The transaction ID associated with the entry, if any.
     var transactionId: Int64? { get }
     
+    /// User-defined metadata that can be attached to writes.
+    ///
+    /// This is the value the `_metadata` column had when the write to the database was made,
+    /// allowing backend connectors to e.g. identify a write and tear it specially.
+    ///
+    /// Note that the `_metadata` column and this field are only available when ``Table/trackMetadata``
+    /// is enabled.
+    var metadata: String? { get }
+    
     /// The operation data associated with the entry, represented as a dictionary of column names to their values.
     var opData: [String: String?]? { get }
+
+    /// Previous values before this change.
+    ///
+    /// These values can be tracked for `UPDATE` statements when ``Table/trackPreviousValues`` is enabled.
+    var previousValues: [String: String?]? { get }
 }
diff --git a/Tests/PowerSyncTests/CrudTests.swift b/Tests/PowerSyncTests/CrudTests.swift
@@ -33,6 +33,95 @@ final class CrudTests: XCTestCase {
         database = nil
         try await super.tearDown()
     }
+    
+    func testTrackMetadata() async throws {
+        try await database.updateSchema(schema: Schema(tables: [
+            Table(name: "lists", columns: [.text("name")], trackMetadata: true)
+        ]))
+
+        try await database.execute("INSERT INTO lists (id, name, _metadata) VALUES (uuid(), 'test', 'so meta')")
+        guard let batch = try await database.getNextCrudTransaction() else {
+            return XCTFail("Should have batch after insert")
+        }
+        
+        XCTAssertEqual(batch.crud[0].metadata, "so meta")
+    }
+    
+    func testTrackPreviousValues() async throws {
+        try await database.updateSchema(schema: Schema(tables: [
+            Table(
+                name: "lists",
+                columns: [.text("name"), .text("content")],
+                trackPreviousValues: TrackPreviousValuesOptions()
+            )
+        ]))
+        
+        try await database.execute("INSERT INTO lists (id, name, content) VALUES (uuid(), 'entry', 'content')")
+        try await database.execute("DELETE FROM ps_crud")
+        try await database.execute("UPDATE lists SET name = 'new name'")
+        
+        guard let batch = try await database.getNextCrudTransaction() else {
+            return XCTFail("Should have batch after update")
+        }
+        
+        XCTAssertEqual(batch.crud[0].previousValues, ["name": "entry", "content": "content"])
+    }
+    
+    func testTrackPreviousValuesWithFilter() async throws {
+        try await database.updateSchema(schema: Schema(tables: [
+            Table(
+                name: "lists",
+                columns: [.text("name"), .text("content")],
+                trackPreviousValues: TrackPreviousValuesOptions(
+                    columnFilter: ["name"]
+                )
+            )
+        ]))
+        
+        try await database.execute("INSERT INTO lists (id, name, content) VALUES (uuid(), 'entry', 'content')")
+        try await database.execute("DELETE FROM ps_crud")
+        try await database.execute("UPDATE lists SET name = 'new name'")
+        
+        guard let batch = try await database.getNextCrudTransaction() else {
+            return XCTFail("Should have batch after update")
+        }
+        
+        XCTAssertEqual(batch.crud[0].previousValues, ["name": "entry"])
+    }
+    
+    func testTrackPreviousValuesOnlyWhenChanged() async throws {
+        try await database.updateSchema(schema: Schema(tables: [
+            Table(
+                name: "lists",
+                columns: [.text("name"), .text("content")],
+                trackPreviousValues: TrackPreviousValuesOptions(
+                    onlyWhenChanged: true
+                )
+            )
+        ]))
+        
+        try await database.execute("INSERT INTO lists (id, name, content) VALUES (uuid(), 'entry', 'content')")
+        try await database.execute("DELETE FROM ps_crud")
+        try await database.execute("UPDATE lists SET name = 'new name'")
+        
+        guard let batch = try await database.getNextCrudTransaction() else {
+            return XCTFail("Should have batch after update")
+        }
+        
+        XCTAssertEqual(batch.crud[0].previousValues, ["name": "entry"])
+    }
+    
+    func testIgnoreEmptyUpdate() async throws {
+        try await database.updateSchema(schema: Schema(tables: [
+            Table(name: "lists", columns: [.text("name")], ignoreEmptyUpdates: true)
+        ]))
+        try await database.execute("INSERT INTO lists (id, name) VALUES (uuid(), 'test')")
+        try await database.execute("DELETE FROM ps_crud")
+        try await database.execute("UPDATE lists SET name = 'test'") // Same value!
+        
+        let batch = try await database.getNextCrudTransaction()
+        XCTAssertNil(batch)
+    }
 
     func testCrudBatch() async throws {
         // Create some items
diff --git a/Tests/PowerSyncTests/Schema/TableTests.swift b/Tests/PowerSyncTests/Schema/TableTests.swift
@@ -190,6 +190,35 @@ final class TableTests: XCTestCase {
         }
     }
     
+    func testInvalidLocalOnlyTrackMetadata() {
+        let table = Table(name: "test", columns: [Column.text("name")], localOnly: true, trackMetadata: true)
+        
+        XCTAssertThrowsError(try table.validate()) { error in
+            guard case TableError.metadataForLocalTable(let tableName) = error else {
+                XCTFail("Expected metadataForLocalTable error")
+                return
+            }
+            XCTAssertEqual(tableName, "test")
+        }
+    }
+    
+    func testInvalidLocalOnlyTrackPrevious() {
+        let table = Table(
+            name: "test_prev",
+            columns: [Column.text("name")],
+            localOnly: true,
+            trackPreviousValues: TrackPreviousValuesOptions()
+        )
+        
+        XCTAssertThrowsError(try table.validate()) { error in
+            guard case TableError.trackPreviousForLocalTable(let tableName) = error else {
+                XCTFail("Expected trackPreviousForLocalTable error")
+                return
+            }
+            XCTAssertEqual(tableName, "test_prev")
+        }
+    }
+    
     func testValidTableValidation() throws {
         let table = Table(
             name: "users",
diff --git a/docs/LocalBuild.md b/docs/LocalBuild.md
@@ -1,12 +1,23 @@
 # PowerSync Swift SDK
 
-## Run against a local kotlin build
+## Run against a local Kotlin build
 
-* To run using the local kotlin build you need to apply the following change in the `Package.swift` file:
+Especially when working on the Kotlin SDK, it may be helpful to test your local changes
+with the Swift SDK too.
+To do this, first create an XCFramework from your Kotlin checkout:
 
-  ```swift
-      dependencies: [
-          .package(url: "https://github.com/powersync-ja/powersync-kotlin.git", exact: "x.y.z"), <-- Comment this
-  //        .package(path: "../powersync-kotlin"), <-- Include this line and put in the path to you powersync-kotlin repo
-  ```
-* To quickly make a local build to apply changes you made in `powersync-kotlin` for local development in the Swift SDK run the gradle task `spmDevBuild` in `PowerSyncKotlin` in the `powersync-kotlin` repo. This will update the files and the changes will be reflected in the Swift SDK.
+```bash
+./gradlew PowerSyncKotlin:assemblePowerSyncKotlinDebugXCFramework
+```
+
+Then, point the `binaryTarget` dependency in `Package.swift` towards the path of your generated
+XCFramework:
+
+```Swift
+.binaryTarget(
+    name: "PowerSyncKotlin",
+    path: "/path/to/powersync-kotlin/PowerSyncKotlin/build/XCFrameworks/debug/PowerSyncKotlin.xcframework"
+)
+```
+
+Subsequent Kotlin changes should get picked up after re-assembling the Kotlin XCFramework.

Original file line number	Diff line number	Diff line change
`@@ -28,9 +28,17 @@ struct KotlinCrudEntry : CrudEntry {`
`28`	`28`	`entry.transactionId?.int64Value`
`29`	`29`	`}`
`30`	`30`
	`31`	`+ var metadata: String? {`
	`32`	`+ entry.metadata`
	`33`	`+ }`
	`34`	`+`
`31`	`35`	`var opData: [String : String?]? {`
`32`	`36`	`/// Kotlin represents this as Map<String, String?>, but this is`
`33`	`37`	`/// converted to [String: Any] by SKIEE`
`34`	`38`	`entry.opData?.mapValues { $0 as? String }`
`35`	`39`	`}`
	`40`	`+`
	`41`	`+ var previousValues: [String : String?]? {`
	`42`	`+ entry.previousValues?.mapValues { $0 as? String }`
	`43`	`+ }`
`36`	`44`	`}`