support deferrable FK clauses in schema parsing and document INITIALLY DEFERRED guidance for oversqlite

mobiletoly · mobiletoly · commit 81ab8374ac4e · 2026-03-26T12:51:55.000-05:00
diff --git a/docs/sync/core-concepts.md b/docs/sync/core-concepts.md
@@ -120,6 +120,24 @@ configuration obey the same runtime contract:
 - the local sync key type must be `TEXT` or `BLOB`
 - local sync-enabled tables must not include the reserved server column `_sync_scope_id`
 
+### Foreign Key Recommendation For Sync Schemas
+
+For foreign keys between sync-managed tables, prefer `DEFERRABLE INITIALLY DEFERRED`.
+
+Why this is the default recommendation:
+
+- oversqlite apply transactions already defer foreign-key checks while authoritative bundles are
+  replayed
+- `INITIALLY DEFERRED` makes ordinary app writes behave more like sync apply, which reduces
+  surprises
+- it is more tolerant of valid multi-step local transactions that temporarily create rows out of
+  parent/child order before commit
+
+Use `DEFERRABLE INITIALLY IMMEDIATE` only when you specifically want non-sync application writes
+to fail on foreign-key violations at statement time unless those transactions explicitly defer
+checks themselves. In practice, `INITIALLY IMMEDIATE` is mainly a stricter rule for your own local
+write paths, not a sync feature.
+
 ### Change Metadata
 Each change includes:
 - **What changed**: The actual data that was modified
diff --git a/docs/sync/getting-started.md b/docs/sync/getting-started.md
@@ -63,7 +63,7 @@ CREATE TABLE note (
     id BLOB PRIMARY KEY NOT NULL DEFAULT (randomblob(16)),  -- BLOB with UUID bytes
     title TEXT NOT NULL,
     content TEXT,
-    person_id TEXT REFERENCES person(id),  -- Foreign key matches referenced table type
+    person_id TEXT REFERENCES person(id) DEFERRABLE INITIALLY DEFERRED,
     updated_at INTEGER NOT NULL DEFAULT (unixepoch())
 );
 ```
@@ -102,6 +102,23 @@ CREATE TABLE users (
   performance
 - **Foreign keys**: Must match the type of the referenced primary key
 
+### Recommended Foreign Key Mode For Sync-Managed Tables
+
+When a sync-managed table references another sync-managed table, prefer:
+
+```sql
+person_id TEXT REFERENCES person(id) DEFERRABLE INITIALLY DEFERRED
+```
+
+Why:
+
+- oversqlite apply already defers foreign-key checks while remote bundles are replayed
+- `INITIALLY DEFERRED` keeps your normal application writes closer to that behavior
+- local transactions that insert related rows in multiple steps are less likely to fail
+
+Use `INITIALLY IMMEDIATE` only if you deliberately want ordinary non-sync writes to fail earlier
+when they temporarily violate FK ordering inside a transaction.
+
 
 ### Custom Primary Key Column Names
 
@@ -135,6 +152,7 @@ CREATE TABLE orders (
 - Use `syncKeyColumnName` annotation for custom primary key column names
 - The system can auto-detect primary key columns if not explicitly specified
 - **Foreign keys must match the type of the referenced primary key** (TEXT or BLOB)
+- **For sync-managed foreign keys, prefer `DEFERRABLE INITIALLY DEFERRED`**
 - Sync-enabled local tables must not include the reserved server column `_sync_scope_id`
 
 ### UUID Generation in Your App
diff --git a/docs/sync/sync-operations.md b/docs/sync/sync-operations.md
@@ -32,6 +32,15 @@ client.bootstrap(userId = userId, sourceId = deviceId).getOrThrow()
 Call bootstrap after authentication and before any sync operation. Client construction alone does
 not create sync metadata or install triggers.
 
+Note on foreign keys:
+
+- oversqlite apply runs inside a transaction that defers foreign-key checks while authoritative
+  remote bundles are replayed
+- because of that, `DEFERRABLE INITIALLY DEFERRED` is the recommended schema default for
+  sync-managed foreign keys
+- `INITIALLY IMMEDIATE` mainly changes how your own non-sync local writes behave outside apply
+  transactions
+
 ## Push Pending
 
 `pushPending()` freezes all currently dirty rows into one logical outbound bundle, uploads that
diff --git a/library-oversqlite-test/composeApp/src/commonMain/sql/RealServerGeneratedDatabase/schema/posts.sql b/library-oversqlite-test/composeApp/src/commonMain/sql/RealServerGeneratedDatabase/schema/posts.sql
@@ -3,7 +3,7 @@ CREATE TABLE posts (
     id TEXT PRIMARY KEY NOT NULL,
     title TEXT NOT NULL,
     content TEXT NOT NULL,
-    author_id TEXT REFERENCES users(id),
+    author_id TEXT REFERENCES users(id) DEFERRABLE INITIALLY DEFERRED,
     created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
     updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
diff --git a/sqlitenow-gradle-plugin/src/main/kotlin/dev/goquick/sqlitenow/gradle/sqlinspect/SchemaInspector.kt b/sqlitenow-gradle-plugin/src/main/kotlin/dev/goquick/sqlitenow/gradle/sqlinspect/SchemaInspector.kt
@@ -28,6 +28,8 @@ import net.sf.jsqlparser.schema.Table
 import net.sf.jsqlparser.statement.create.table.CreateTable
 import net.sf.jsqlparser.statement.create.view.CreateView
 
+private enum class NormalizationState { OUTSIDE, LINE_COMMENT, BLOCK_COMMENT, SINGLE_QUOTE, DOUBLE_QUOTE }
+
 internal class SchemaInspector(
     schemaDirectory: File
 ) {
@@ -138,13 +140,112 @@ internal class SchemaInspector(
 
     /**
      * JSqlParser doesn't understand some SQLite-specific tail modifiers like "WITHOUT ROWID".
-     * We strip such suffixes for parsing only, but we keep the original SQL for execution
+     * It also rejects foreign-key deferrable clauses that SQLite accepts. We strip only the
+     * parser-hostile syntax for parsing, but keep the original SQL for execution
      * (CreateTableStatement stores the original sql passed in SchemaInspector).
      */
     private fun normalizeForParser(sql: String): String {
-        // Remove trailing WITHOUT ROWID (case-insensitive), optionally before semicolon
-        val regex = Regex("(?is)\\s+WITHOUT\\s+ROWID\\s*;?\\s*$")
-        return sql.replace(regex, ";")
+        val withoutRowId = sql.replace(Regex("(?is)\\s+WITHOUT\\s+ROWID\\s*;?\\s*$"), ";")
+        return stripParserUnsupportedForeignKeyClauses(withoutRowId)
+    }
+
+    private fun stripParserUnsupportedForeignKeyClauses(sql: String): String {
+        val unsupportedClause = Regex(
+            "(?i)\\b(?:NOT\\s+DEFERRABLE|DEFERRABLE)(?:\\s+INITIALLY\\s+(?:DEFERRED|IMMEDIATE))?\\b"
+        )
+        val normalized = StringBuilder(sql.length)
+        var outsideStart = 0
+        var state = NormalizationState.OUTSIDE
+        var i = 0
+
+        fun appendNormalizedOutside(endExclusive: Int) {
+            if (outsideStart >= endExclusive) return
+            normalized.append(sql.substring(outsideStart, endExclusive).replace(unsupportedClause, ""))
+        }
+
+        while (i < sql.length) {
+            val c = sql[i]
+            val c2 = sql.getOrNull(i + 1)
+
+            when (state) {
+                NormalizationState.OUTSIDE -> when {
+                    c == '-' && c2 == '-' -> {
+                        appendNormalizedOutside(i)
+                        normalized.append("--")
+                        state = NormalizationState.LINE_COMMENT
+                        i += 2
+                    }
+                    c == '/' && c2 == '*' -> {
+                        appendNormalizedOutside(i)
+                        normalized.append("/*")
+                        state = NormalizationState.BLOCK_COMMENT
+                        i += 2
+                    }
+                    c == '\'' -> {
+                        appendNormalizedOutside(i)
+                        normalized.append(c)
+                        state = NormalizationState.SINGLE_QUOTE
+                        i++
+                    }
+                    c == '"' -> {
+                        appendNormalizedOutside(i)
+                        normalized.append(c)
+                        state = NormalizationState.DOUBLE_QUOTE
+                        i++
+                    }
+                    else -> i++
+                }
+
+                NormalizationState.LINE_COMMENT -> {
+                    normalized.append(c)
+                    i++
+                    if (c == '\n' || c == '\r') {
+                        state = NormalizationState.OUTSIDE
+                        outsideStart = i
+                    }
+                }
+
+                NormalizationState.BLOCK_COMMENT -> if (c == '*' && c2 == '/') {
+                    normalized.append("*/")
+                    i += 2
+                    state = NormalizationState.OUTSIDE
+                    outsideStart = i
+                } else {
+                    normalized.append(c)
+                    i++
+                }
+
+                NormalizationState.SINGLE_QUOTE -> if (c == '\'' && c2 == '\'') {
+                    normalized.append("''")
+                    i += 2
+                } else {
+                    normalized.append(c)
+                    i++
+                    if (c == '\'') {
+                        state = NormalizationState.OUTSIDE
+                        outsideStart = i
+                    }
+                }
+
+                NormalizationState.DOUBLE_QUOTE -> if (c == '"' && c2 == '"') {
+                    normalized.append("\"\"")
+                    i += 2
+                } else {
+                    normalized.append(c)
+                    i++
+                    if (c == '"') {
+                        state = NormalizationState.OUTSIDE
+                        outsideStart = i
+                    }
+                }
+            }
+        }
+
+        if (state == NormalizationState.OUTSIDE) {
+            appendNormalizedOutside(sql.length)
+        }
+
+        return normalized.toString()
     }
 }
 
diff --git a/sqlitenow-gradle-plugin/src/test/kotlin/dev/goquick/sqlitenow/gradle/GenerateDatabaseFilesDeferrableForeignKeyTest.kt b/sqlitenow-gradle-plugin/src/test/kotlin/dev/goquick/sqlitenow/gradle/GenerateDatabaseFilesDeferrableForeignKeyTest.kt
@@ -0,0 +1,63 @@
+package dev.goquick.sqlitenow.gradle
+
+import java.io.File
+import java.sql.DriverManager
+import kotlin.io.path.createTempDirectory
+import kotlin.test.assertNotNull
+import kotlin.test.assertTrue
+import org.junit.jupiter.api.Test
+
+class GenerateDatabaseFilesDeferrableForeignKeyTest {
+
+    @Test
+    fun generateDatabaseFilesSupportsDeferrableForeignKeys() {
+        val root = createTempDirectory(prefix = "deferrable-fk-").toFile()
+        val schemaDir = File(root, "schema").apply { mkdirs() }
+        val queryDir = File(root, "queries/posts").apply { mkdirs() }
+        val outDir = File(root, "out").apply { mkdirs() }
+        val schemaDatabaseFile = File(root, "schema.db")
+
+        File(schemaDir, "users.sql").writeText(
+            """
+            CREATE TABLE users (
+                id TEXT PRIMARY KEY NOT NULL
+            );
+            """.trimIndent()
+        )
+        File(schemaDir, "posts.sql").writeText(
+            """
+            CREATE TABLE posts (
+                id TEXT PRIMARY KEY NOT NULL,
+                author_id TEXT REFERENCES users(id) DEFERRABLE INITIALLY DEFERRED
+            );
+            """.trimIndent()
+        )
+        File(queryDir, "selectAll.sql").writeText(
+            """
+            SELECT id, author_id FROM posts;
+            """.trimIndent()
+        )
+
+        generateDatabaseFiles(
+            dbName = "TestDbDeferrable",
+            sqlDir = root,
+            packageName = "dev.test.deferrable",
+            outDir = outDir,
+            schemaDatabaseFile = schemaDatabaseFile,
+            debug = false,
+        )
+
+        val generatedSource = outDir.walkTopDown().firstOrNull { it.extension == "kt" }
+        assertNotNull(generatedSource, "Expected generateDatabaseFiles to emit Kotlin sources")
+
+        DriverManager.getConnection("jdbc:sqlite:${schemaDatabaseFile.absolutePath}").use { conn ->
+            val createdSql = conn.createStatement().use { stmt ->
+                stmt.executeQuery("SELECT sql FROM sqlite_master WHERE type='table' AND name='posts'").use { rs ->
+                    assertTrue(rs.next(), "posts table should exist in the generated schema database")
+                    rs.getString("sql")
+                }
+            }
+            assertTrue(createdSql.contains("DEFERRABLE INITIALLY DEFERRED"))
+        }
+    }
+}
diff --git a/sqlitenow-gradle-plugin/src/test/kotlin/dev/goquick/sqlitenow/gradle/SchemaInspectorTest.kt b/sqlitenow-gradle-plugin/src/test/kotlin/dev/goquick/sqlitenow/gradle/SchemaInspectorTest.kt
@@ -11,6 +11,7 @@ import org.junit.jupiter.api.BeforeEach
 import kotlin.test.assertTrue
 import kotlin.test.assertEquals
 import kotlin.test.assertFailsWith
+import kotlin.test.assertNotNull
 
 class SchemaInspectorTest {
 
@@ -209,4 +210,70 @@ class SchemaInspectorTest {
             }
         }
     }
+
+    @Test
+    @DisplayName("Test SchemaInspector supports deferrable foreign key clauses")
+    fun testSchemaInspectorSupportsDeferrableForeignKeys() {
+        File(schemaDir, "01_users.sql").writeText(
+            """
+            CREATE TABLE users (
+                id TEXT PRIMARY KEY NOT NULL
+            );
+            """.trimIndent()
+        )
+        File(schemaDir, "02_posts.sql").writeText(
+            """
+            CREATE TABLE posts (
+                id TEXT PRIMARY KEY NOT NULL,
+                author_id TEXT REFERENCES users(id) DEFERRABLE INITIALLY DEFERRED
+            );
+            """.trimIndent()
+        )
+        File(schemaDir, "03_comments.sql").writeText(
+            """
+            CREATE TABLE comments (
+                id TEXT PRIMARY KEY NOT NULL,
+                post_id TEXT NOT NULL,
+                FOREIGN KEY (post_id) REFERENCES posts(id) NOT DEFERRABLE
+            );
+            """.trimIndent()
+        )
+        File(schemaDir, "04_likes.sql").writeText(
+            """
+            CREATE TABLE likes (
+                id TEXT PRIMARY KEY NOT NULL,
+                post_id TEXT NOT NULL,
+                FOREIGN KEY (post_id) REFERENCES posts(id) DEFERRABLE INITIALLY IMMEDIATE
+            );
+            """.trimIndent()
+        )
+
+        val inspector = SchemaInspector(schemaDirectory = schemaDir)
+        val createdTables = inspector.getCreateTableStatements(conn)
+
+        assertEquals(4, createdTables.size, "Should execute all CREATE TABLE statements with deferrable clauses")
+        assertTrue(inspector.sqlStatements.any { it.sql.contains("DEFERRABLE INITIALLY DEFERRED") })
+        assertTrue(inspector.sqlStatements.any { it.sql.contains("NOT DEFERRABLE") })
+        assertTrue(inspector.sqlStatements.any { it.sql.contains("DEFERRABLE INITIALLY IMMEDIATE") })
+
+        fun tableSql(name: String): String {
+            return conn.createStatement().use { stmt ->
+                stmt.executeQuery("SELECT sql FROM sqlite_master WHERE type='table' AND name='$name'").use { rs ->
+                    assertTrue(rs.next(), "$name table should exist")
+                    rs.getString("sql")
+                }
+            }
+        }
+
+        val postsSql = tableSql("posts")
+        val commentsSql = tableSql("comments")
+        val likesSql = tableSql("likes")
+
+        assertNotNull(postsSql)
+        assertNotNull(commentsSql)
+        assertNotNull(likesSql)
+        assertTrue(postsSql.contains("DEFERRABLE INITIALLY DEFERRED"))
+        assertTrue(commentsSql.contains("NOT DEFERRABLE"))
+        assertTrue(likesSql.contains("DEFERRABLE INITIALLY IMMEDIATE"))
+    }
 }
