Improve handling of FTS5 hidden columns (#717)

* Define more precise synthesized columns for different FTS extension versions

* Test that it's possible to query and order by rank if using an fts5 virtual table.

* Update CHANGELOG.md

Author: watbe

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## Unreleased
 
-
+- Improve handling of FTS5 hidden columns (https://github.com/sqldelight/sql-psi/pull/717)
 
 ## [0.7.0] - 2025-09-02
 [0.7.0]: https://github.com/sqldelight/sql-psi/releases/tag/0.7.0

core/src/main/kotlin/com/alecstrong/sql/psi/core/psi/mixins/CreateVirtualTableMixin.kt

@@ -45,18 +45,31 @@ internal abstract class CreateVirtualTableMixin(
     )
       .mapNotNull { it.moduleArgumentDef?.moduleColumnDef?.columnName ?: it.moduleArgumentDef?.columnDef?.columnName }
 
-    val synthesizedColumns = if (usesFtsModule) {
-      val columnNames = columnNameElements.map { it.name }
-
-      listOf(
-        SynthesizedColumn(
-          table = this,
-          acceptableValues = listOf("docid", "rowid", "oid", "_rowid_", tableName.name)
-            .filter { it !in columnNames },
-        ),
-      )
-    } else {
-      emptyList()
+    val synthesizedColumns = when {
+      usesFts3Module || usesFts4Module -> {
+        val columnNames = columnNameElements.map { it.name }
+
+        listOf(
+          SynthesizedColumn(
+            table = this,
+            acceptableValues = listOf("docid", "rowid", "oid", "_rowid_", tableName.name)
+              .filter { it !in columnNames },
+          ),
+        )
+      }
+      usesFts5Module -> {
+        val columnNames = columnNameElements.map { it.name }
+
+        listOf(
+          SynthesizedColumn(
+            table = this,
+            acceptableValues = listOf("rowid", "_row_id_", "rank", tableName.name)
+              .filter { it !in columnNames },
+          ),
+        )
+      }
+
+      else -> emptyList()
     }
 
     return LazyQuery(tableName) {
@@ -77,3 +90,12 @@ internal class CreateVirtualTableElementType(name: String) :
 
 val SqlCreateVirtualTableStmt.usesFtsModule: Boolean
   get() = this.moduleName?.text?.startsWith(prefix = "fts", ignoreCase = true) == true
+
+val SqlCreateVirtualTableStmt.usesFts3Module: Boolean
+  get() = this.moduleName?.text?.startsWith(prefix = "fts3", ignoreCase = true) == true
+
+val SqlCreateVirtualTableStmt.usesFts4Module: Boolean
+  get() = this.moduleName?.text?.startsWith(prefix = "fts4", ignoreCase = true) == true
+
+val SqlCreateVirtualTableStmt.usesFts5Module: Boolean
+  get() = this.moduleName?.text?.startsWith(prefix = "fts5", ignoreCase = true) == true

core/src/testFixtures/resources/fixtures/fts5-hidden-columns/Test.s

@@ -0,0 +1,14 @@
+CREATE VIRTUAL TABLE data USING fts5(text, content=other_table, content_rowid=rowid, prefix='2 3 4 5 6');
+
+SELECT rank, rowid
+FROM data
+WHERE text MATCH 'fts5';
+
+SELECT rank, rowid
+FROM data
+WHERE text MATCH 'fts5' ORDER BY rank;
+
+-- Expected failure - it's not valid to query for oid or docid in FTS5 tables.
+SELECT oid
+FROM data
+WHERE text MATCH 'fts5';

core/src/testFixtures/resources/fixtures/fts5-hidden-columns/failure.txt

@@ -0,0 +1 @@
+Test.s line 12:7 - No column found with name oid