diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 4227e531..c0c64d3a 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -52,6 +52,9 @@ jobs: - name: Build sqllin-dsl run: ./gradlew :sqllin-dsl:assemble -PonCICD + - name: Build sqllin-dsl-paging + run: ./gradlew :sqllin-dsl-paging:assemble -PonCICD + - name: Run sqllin-dsl macOS Arm64 Tests run: ./gradlew :sqllin-dsl-test:cleanMacosArm64Test :sqllin-dsl-test:macosArm64Test --stacktrace @@ -69,7 +72,7 @@ jobs: uses: actions/upload-artifact@v4 with: name: Test-Reports-macOS-dsl - path: sqllin-dsl/build/reports + path: sqllin-dsl-test/build/reports if: failure() build-on-windows: @@ -112,6 +115,9 @@ jobs: - name: Build sqllin-dsl run: ./gradlew :sqllin-dsl:mingwX64MainKlibrary :sqllin-dsl:jvmJar + - name: Build sqllin-dsl-paging + run: ./gradlew :sqllin-dsl-paging:mingwX64MainKlibrary :sqllin-dsl-paging:jvmJar + - name: Run sqllin-dsl MinGW X64 Tests run: ./gradlew :sqllin-dsl-test:cleanMingwX64Test && ./gradlew :sqllin-dsl-test:mingwX64Test --stacktrace @@ -129,7 +135,7 @@ jobs: uses: actions/upload-artifact@v4 with: name: Test-Reports-Windows-dsl - path: sqllin-dsl/build/reports + path: sqllin-dsl-test/build/reports if: failure() build-on-linux: @@ -175,6 +181,9 @@ jobs: - name: Build sqllin-dsl run: ./gradlew :sqllin-dsl:linuxX64MainKlibrary :sqllin-dsl:jvmJar + - name: Build sqllin-dsl-paging + run: ./gradlew :sqllin-dsl-paging:linuxX64MainKlibrary :sqllin-dsl-paging:jvmJar + - name: Run sqllin-dsl Linux X64 Tests run: ./gradlew :sqllin-dsl-test:cleanLinuxX64Test :sqllin-dsl-test:linuxX64Test --stacktrace @@ -192,7 +201,7 @@ jobs: uses: actions/upload-artifact@v4 with: name: Test-Reports-Linux-dsl - path: sqllin-dsl/build/reports + path: sqllin-dsl-test/build/reports if: failure() build-android-and-test: @@ -216,7 +225,7 @@ jobs: uses: gradle/actions/setup-gradle@v4 - name: Build Android - run: ./gradlew :sqllin-driver:assembleAndroidMain :sqllin-dsl:assembleAndroidMain + run: ./gradlew :sqllin-driver:assembleAndroidMain :sqllin-dsl:assembleAndroidMain :sqllin-dsl-paging:assembleAndroidMain - name: Cache Robolectric Android-All Jars uses: actions/cache@v4 diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 64276094..f2469ad3 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -49,5 +49,8 @@ jobs: - name: Build sqllin-dsl run: ./gradlew :sqllin-dsl:assemble + - name: Build sqllin-dsl-paging + run: ./gradlew :sqllin-dsl-paging:assemble + - name: Publish to MavenCentral run: ./publish_all.sh \ No newline at end of file diff --git a/.gitignore b/.gitignore index 857e32ee..e31af7b8 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ local.properties /sqllin-driver/build /sqllin-dsl/build +/sqllin-dsl-paging/build /sqllin-processor/build /sqllin-dsl-test/build /sample/build diff --git a/CHANGELOG.md b/CHANGELOG.md index c340c7e0..8196be12 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ ## 2.6.0 / 2026-xx-xx +### All + +* Update `AGP`'s version to `9.5.1` +* Update `Gradle`'s version to `9.9.0` +* Update `kotlinx.serialization`'s version to `1.12.0` + ### sqllin-dsl * Fix: the default `lookasideSlotSize` and `lookasideSlotCount` of `DSLDBConfiguration` disabled SQLite's lookaside memory allocator on Kotlin/Native and on Android 9 and higher, as those of `DatabaseConfiguration` did; they are now -1, see sqllin-driver @@ -11,13 +17,49 @@ * Fix documentation: the example of the guide to concurrency safety called `database suspendScope { }`, which doesn't exist, in a function that wasn't a `suspend` one; it is `database suspendedScope { }`, in a `suspend` function * Fix: `INSERT` failed with `near ")": syntax error` when the primary key that the database assigns, a `Long?` property annotated with `@PrimaryKey`, was the last property of the class: as `INSERT` leaves such a key out, the column list kept a trailing comma, and the `VALUES` tuple was never closed. A key declared before another property wasn't affected, and neither were `INSERT_WITH_ID`, `INSERT_OR_IGNORE` and `INSERT_OR_REPLACE`, which write the key * Fix documentation: examples that didn't compile. The READMEs and the query guide called `SelectStatement.getResult()`, which doesn't exist, rather than `getResults()`; the guide to getting started imported `DSLDBConfiguration` from `com.ctrip.sqllin.driver` rather than `com.ctrip.sqllin.dsl`, and, in English, the annotation `NoCase`, which doesn't exist, rather than `CollateNoCase`; and the guide to modifying the database declared an `autoIncrement` primary key as `Long = 0`, which the processor rejects, rather than `Long? = null` +* Fix: a clause appended to a statement replaced the last statement of the scope, rather than the one it completes, when another statement had been built since, as when a statement is held in a variable and completed later: the other statement didn't run, and the incomplete one still did. So an UPDATE held as `val update = table UPDATE SET { ... }`, followed by a SELECT and then completed with `update WHERE (...)`, updated every row of the table, and the SELECT returned nothing. `WHERE` also added its parameters to those of the UPDATE without it. A clause now replaces the statement it completes, wherever it is, and appending one to a statement that a clause was already appended to, or that became part of another one, as a subquery, a compound SELECT or `EXPLAIN_QUERY_PLAN` does, fails with an `IllegalStateException` before any statement of the scope runs, rather than replacing another statement +* Fix: a transaction in another one, which the documentation of `DatabaseScope` says can be nested, ended the outer one when it ended, since 2.0.0 at least: the statements after it in the outer block weren't in the transaction, so they ran on their own, and when one of them failed, those before it weren't rolled back; a second transaction in the outer one began a transaction of its own, in its own mode. `beginTransaction()` and `endTransaction()` now count how deeply transactions are nested, and only the outermost `endTransaction()` ends the transaction, so the statements of an inner transaction and those after it are the outer one's, which commits or rolls back all of them. As the fix is in these two functions, rather than in the inline `transaction { }`, it also applies to code compiled against an earlier version, and to nested calls of the two functions +* Fix: on Android 13 and higher, `PRAGMA_FOREIGN_KEYS(flag)` didn't apply to the INSERT, UPDATE and DELETE statements whose SQL had run before, which kept checking foreign keys or not as before, such as after a migration that turned them off and on again; see sqllin-driver +* Fix: on Kotlin/Native and on Android 8.1 and lower, the `journalMode` of `DSLDBConfiguration`, WAL by default, didn't take effect, since 1.2.0; see sqllin-driver +* **Breaking change**: removed the joins written as clauses of SELECT, which 2.5.0 announced would be removed: the functions `CROSS_JOIN`, `JOIN`, `INNER_JOIN`, `NATURAL_JOIN`, `NATURAL_INNER_JOIN`, `LEFT_OUTER_JOIN` and `NATURAL_LEFT_OUTER_JOIN` that took relations as arguments, the `SELECT` and `SELECT_DISTINCT` that took what they returned, and the types `BaseJoinClause`, `JoinClause`, `NaturalJoinClause`, `JoinStatementWithoutCondition` and `JoinSelectStatement`, with the `ON`, `USING`, `WHERE`, `GROUP_BY`, `ORDER_BY` and `LIMIT` that took them. To migrate, write the join as a join of relations: `table SELECT INNER_JOIN(other) USING column` becomes `(table INNER_JOIN other USING column) SELECT X()`. Its result type is checked against the joined relations when the statement is built, so a type that reads a column two relations have has to select it with `AS`, and one that reads a column an outer join can leave NULL has to make its property nullable. The guide to advanced queries describes the migration +* New experimental DSL API: a join can start with its first relation, as in `(PersonTable INNER_JOIN BookTable ON (PersonTable.id EQ BookTable.authorId)) SELECT X()`, without `FROM`, with each join operator: `INNER_JOIN`, `LEFT_OUTER_JOIN`, `RIGHT_OUTER_JOIN`, `FULL_OUTER_JOIN`, `CROSS_JOIN` and the NATURAL joins. `FROM(relation)` still starts one too +* **Breaking change**: removed the `UNION {}` and `UNION_ALL {}` blocks, and the `DatabaseScope#beginUnion`, `createUnionSelectStatement` and `endUnion` functions they used, which 2.5.0 deprecated for bugs that wouldn't be fixed: a union of projections, result columns or joins failed with a `ClassCastException`, and a nested block was flattened into the SQL, which changed its meaning. To migrate, use the infix operators: `UNION { a; b }` becomes `(a) UNION (b)`, and `UNION_ALL { a; b }` becomes `(a) UNION_ALL (b)`. The guide to advanced queries describes it +* New experimental API: table version tokens, which tell a reader when the tables it read change, such as a `PagingSource` that invalidates itself. `Database#versioned { }` runs a scope of SELECTs, and returns its result with a `TableVersions` token of the versions of the tables they read, captured under the lock that they run under, after the tables are tracked, so that no change after them is missed; a scope that writes is rejected. `Database#awaitChange(token)` suspends until a statement run through the database changes one of those tables, and `Database#onChange(token) { }` registers a callback that runs once, after the writing scope releases the lock, on the thread that wrote, and returns an `AutoCloseable` that closes the registration, or null when the token is already stale, as it registers before it checks. Tokens combine with `+`, which takes the earlier version of a table that both read, and rejects the tokens of another `Database` +* New experimental DSL API: the other conflict resolutions of a statement: `INSERT_OR_ABORT`, `INSERT_OR_FAIL` and `INSERT_OR_ROLLBACK`, for SQL syntax `INSERT OR ABORT`, `INSERT OR FAIL` and `INSERT OR ROLLBACK`, which take objects, expressions, `DEFAULT_VALUES` and a SELECT, as `INSERT` does, and write the primary key, as `INSERT_OR_IGNORE` and `INSERT_OR_REPLACE` do; and `UPDATE_OR_ABORT`, `UPDATE_OR_FAIL`, `UPDATE_OR_IGNORE`, `UPDATE_OR_REPLACE` and `UPDATE_OR_ROLLBACK`, for `UPDATE OR ...`. A statement's resolution takes the place of the conflict clause of a constraint, which `onConflict` declares. The guide to modifying the database describes them in a new section +* New experimental DSL API: `transaction(mode) { }`, which begins the transaction in a `TransactionMode` of sqllin-driver, for SQL syntax `BEGIN DEFERRED`, `BEGIN IMMEDIATE` and `BEGIN EXCLUSIVE`, rather than IMMEDIATE, the mode of `transaction { }`. A transaction in another one keeps the outer one's mode +* New experimental DSL API: `INDEXED_BY` and `NOT_INDEXED`, for SQL syntax `INDEXED BY` and `NOT INDEXED`, which make a statement look its rows up through an index, or none, rather than through the one SQLite's query planner chooses: `(PersonTable INDEXED_BY "idx_person_name") SELECT WHERE(...)` and `PersonTable.NOT_INDEXED DELETE WHERE(...)`. The `IndexedTable` they return is read by a SELECT, joins included, and written by UPDATE, the `UPDATE_OR_` ones and DELETE, but not by INSERT, which SQL doesn't allow, which is checked at compile time +* New experimental DSL API: `EXPLAIN_QUERY_PLAN(select)`, for SQL syntax `EXPLAIN QUERY PLAN`, which tells how SQLite would run a SELECT without running it: which tables it scans, which indexes it searches, and where it sorts with a temporary B-tree. Any SELECT can be planned, joins, subqueries and compound ones included; it becomes part of the statement, and is planned with its parameters. The `QueryPlanStatement` it returns gives, once the scope has run, a `QueryPlan`: its `steps`, each with its `detail` and its `children`, the `details` of all of them, and a `toString()` that writes them as a tree, as the `sqlite3` shell does. The details are SQLite's own text, which differs between SQLite versions, and a SQLite older than 3.24.0, as Android's before API 30, lists the steps without children; the plan is read by the columns SQLite returns, so the same on every platform, without the version of SQLite. The guide to advanced queries describes it in a new section +* New experimental DSL API: the PRAGMAs that check the database, read its schema and what the SQLite has, checkpoint the WAL, read the size and the header of the file, and set how statements run: `PRAGMA_INTEGRITY_CHECK(maxErrors)` and `PRAGMA_QUICK_CHECK(maxErrors)`, which return the problems found, or an empty list rather than SQLite's `ok`; `PRAGMA_FOREIGN_KEY_CHECK()`, of all tables or of one; `PRAGMA_FOREIGN_KEYS()`, which reads what `PRAGMA_FOREIGN_KEYS(flag)` sets; `PRAGMA_TABLE_INFO(table)`, of a table, a view or a name, `PRAGMA_INDEX_LIST(table)`, `PRAGMA_INDEX_XINFO(index)` and `PRAGMA_FOREIGN_KEY_LIST(table)`; `PRAGMA_WAL_CHECKPOINT(mode)`, which throws an `IllegalStateException` inside a transaction, where SQLite can't checkpoint; `PRAGMA_PAGE_COUNT()`, `PRAGMA_FREELIST_COUNT()` and `PRAGMA_PAGE_SIZE()`; `PRAGMA_DEFER_FOREIGN_KEYS(flag)`, which throws an `IllegalStateException` outside a transaction, as SQLite turns it off when one ends; `PRAGMA_RECURSIVE_TRIGGERS(flag)`, `PRAGMA_LEGACY_ALTER_TABLE(flag)`, which Android's SQLite turns on by default, and `PRAGMA_IGNORE_CHECK_CONSTRAINTS(flag)`; `PRAGMA_APPLICATION_ID()` and `PRAGMA_APPLICATION_ID(id)`; `PRAGMA_AUTO_VACUUM()` and `PRAGMA_AUTO_VACUUM(mode)`, which VACUUM applies to a database that has tables, while `PRAGMA incremental_vacuum` is left out, as it removes a page each time it returns a row, which has no columns, and sqlite-jdbc runs such a statement only as far as its first row; `PRAGMA_COLLATION_LIST()` and `PRAGMA_DATABASE_LIST()`; and, marked with `@PlatformDependentSQLiteAPI`, `PRAGMA_TABLE_XINFO(table)`, which needs SQLite 3.26.0, Android API 30, `PRAGMA_FUNCTION_LIST()`, `PRAGMA_MODULE_LIST()` and `PRAGMA_PRAGMA_LIST()`, which need SQLite 3.30.0, Android API 31, `PRAGMA_TABLE_LIST()`, which needs SQLite 3.37.0, Android API 34, `PRAGMA_INTEGRITY_CHECK(table)` and `PRAGMA_QUICK_CHECK(table)`, which need SQLite 3.33.0, Android API 34, below which they check the whole database, and `PRAGMA_COMPILE_OPTIONS()`, which Android's SQLite is built without. A PRAGMA that SQLite lacks is ignored rather than failing, so those that only newer versions have check the columns of the rows SQLite returns, and throw an `IllegalStateException` that tells what they need, rather than return nothing, without asking SQLite for its version. auto_vacuum and page_size are read in a transaction of their own outside one, as SQLite takes them from what the connection last read of the header of the file, which on Android 13 and higher may be a connection that reads, which would tell the mode before the last VACUUM. A PRAGMA that reads returns a `PragmaStatement`, whose `getResults()` returns, once the scope has run, a list of `ColumnInfo`, `IndexInfo`, `IndexColumn`, `ForeignKeyInfo`, `ForeignKeyViolation`, `RelationInfo`, `DatabaseInfo` or `FunctionInfo`, a `CheckpointResult`, an `AutoVacuum`, or a value. Each PRAGMA runs as a query or not, as it returns rows or not, which neither Android's framework nor sqlite-jdbc would otherwise run, and a PRAGMA changes no table, so it can be in a versioned read. The guide to modifying the database describes them in a new section +* New experimental DSL API: `@CollateRTrim`, for SQL syntax `COLLATE RTRIM` in a column's definition, which compares the column's values ignoring the spaces at their ends, as its UNIQUE constraint and indexes do, while storing them as they are written; a property can't have it and `@CollateNoCase` both, which the processor reports, as it does on a property that isn't a `String` or a `Char`. A column without either compares its values as the `BINARY` collation does, which a column has by default. And the `COLLATE` operator, which 2.5.0 added for conditions and ORDER BY, gives a column of an index its collation, as in `PersonTable.CREATE_INDEX("idx_person_name_nocase", PersonTable.name COLLATE NOCASE)`, for SQL syntax `CREATE INDEX ... ON person(name COLLATE NOCASE)`, also with an order, as `(PersonTable.name COLLATE NOCASE) to DESC`, which the queries that compare by that collation use. The guides to getting started and to modifying the database describe them +* New experimental DSL API: `ORDER_BY`, `LIMIT` and `OFFSET` after a `DELETE` or an `UPDATE`, with its `WHERE` or without, which only write the first rows in an order, or as many as `LIMIT` says, as in `PersonTable DELETE WHERE(PersonTable.age LT 18) ORDER_BY (PersonTable.age to ASC) LIMIT 10`, for SQL syntax `DELETE ... ORDER BY ... LIMIT ...` and `UPDATE ... ORDER BY ... LIMIT ...`. SQLite only takes them when it is built with `SQLITE_ENABLE_UPDATE_DELETE_LIMIT`, which Android's SQLite isn't, and then turns them into a subquery of the rowids of the rows they choose, so SQLlin writes that subquery itself, which every platform runs, with the same query plan: `DELETE FROM person WHERE rowid IN (SELECT rowid FROM person WHERE person.age`, or uses an operator of `ClauseString` or `ClauseNumber` on it, as `LIKE` or `+`, has to change, and its operators, which are experimental, need an opt-in. A table created before keeps the type of its column, which holds values of any type in SQLite, so it needs no migration. An enum with its default serializer, or serialized contextually, is still stored as its ordinal +* Fix: a SELECT whose results weren't read kept its cursor, and its statement, open: its tables couldn't be dropped meanwhile, failing with `database table is locked`, and on Kotlin/Native the connection stayed open after `close()`, as `sqlite3_close_v2` waits for the statements to end, holding the database file, which Windows then couldn't delete. A SELECT now reads its rows when its scope runs it, under the scope's lock and in its transaction, so that an error decoding them is thrown by the scope, and `getResults()` returns them +* New experimental DSL API: columns of the types that SQLite doesn't store, whose serializers convert their values to those of a column: `kotlin.uuid.Uuid`, `kotlin.time.Instant` and `kotlin.time.Duration`, with their built-in serializers, value classes, types whose classes declare their serializers, as those of kotlinx-datetime do, and any type given a serializer with `@Serializable(with = ...)` on the property, on the use of its type or in a type alias, or by `@file:UseSerializers`, as a `List` stored as JSON. The serializer is the converter: the column has the type of the value it stores, which `CREATE` and `ALTER_ADD_COLUMN` compute from it, and the column's element, a `ClauseConverted`, converts the values of its conditions with it, `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE`, `IN`, of values and of a subquery, `BETWEEN`, `IS` and `ISNOT`, as `SET {}` converts the values it assigns. `literal(value, serializer)` is a literal of such a type. A comparison other than an equality, and `ORDER_BY`, compare the stored values, which are in the order of the Kotlin values only if the serializer keeps it, as the ISO-8601 strings of the built-in serializer of `Instant` aren't. A serializer that encodes a structure, as the generated one of a data class, fails `CREATE`. See the guide to getting started +* New API: the protected `Table#columnType(elementIndex, collation)` and `Table#appendConverted(...)` of `SetClause`, which the tables that sqllin-processor generates call for the columns converted by their serializers + +### sqllin-dsl-paging + +* New module, `com.ctrip.kotlin:sqllin-dsl-paging`, on every platform of sqllin-dsl, which depends on androidx.paging's `paging-common` `3.5.3`: new experimental API `Database#pagingSource(context) { }`, which returns androidx.paging's `PagingSource` of the rows of the SELECT it builds, loaded a page at a time by their offsets, as Room's `LimitOffsetPagingSource` does. A page is `SELECT * FROM (select) LIMIT ... OFFSET ...`, so the SELECT can have a WHERE, a join or compound operators; the first page also counts the rows, so that each page tells how many rows are before and after it, which placeholders show, and a refresh past the last row loads the last ones. The keys are offsets at the borders between pages, so that two pages never share a row, and a page after the first row can always prepend the rows above it, as after a `RemoteMediator` invalidates the source; a refresh starts half the initial load before the row last read, also without placeholders, whose positions don't count the rows before the first page. It is built on the table version tokens of sqllin-dsl: it registers with `Database#onChange` from its first page, weakly, so that a source its `Pager` drops can still be collected, and closes the registration when it is invalidated otherwise; a change of a table the SELECT reads invalidates it, and a page that reads rows changed since the first one is `LoadResult.Invalid()`, with which the source is invalid, also for a `TestPager` or another caller of `load`; a source invalidated before it loads reads nothing. Pages load in `Dispatchers.IO` by default. The guide to advanced queries describes it, and the guide to getting started its dependency ### sqllin-driver +* Update `sqlite-jdbc`'s version to `3.54.1.0` * Fix: the default `lookasideSlotSize` and `lookasideSlotCount` of `DatabaseConfiguration`, 0, which its documentation said left SQLite's default configuration, disabled SQLite's lookaside memory allocator on Kotlin/Native and on Android 9 and higher, as `sqlite3_db_config` and `setLookasideConfig` take 0 to disable it, while the JVM and lower versions of Android kept SQLite's default configuration. Their default is now -1, which leaves SQLite's default configuration on every platform, and 0 still disables the allocator. The guides to getting started now say so, and that sqlite-jdbc doesn't support `sqlite3_db_config()`, rather than `sqlite3_config()` * Fix: on Android, `busyTimeout` didn't take effect, so SQLite waited 2500 ms, as the framework sets it, for a lock that another connection held. On Android 9 and higher, it was given to `SQLiteDatabase.OpenParams.Builder#setIdleConnectionTimeout`, which is deprecated and means another thing, how long a connection may be idle before the framework closes it, and which `SQLiteOpenHelper` drops anyway. `busyTimeout` is now set with `PRAGMA busy_timeout`: from Android 13 on, on every connection of the database, as one in WAL mode reads through several, and below, on its only connection. The guides to getting started listed `busyTimeout`, and in Chinese `journalMode`, among the parameters that only work on Android 9 and higher; only `inMemory`, `lookasideSlotSize` and `lookasideSlotCount` do * Fix: transactions began differently on each platform, DEFERRED on the JVM and Kotlin/Native and EXCLUSIVE on Android, so on the JVM and Kotlin/Native, a transaction that read before it wrote failed at once with "database is locked" while another connection wrote, as SQLite doesn't wait for `busyTimeout` there, where waiting could deadlock. Transactions now begin IMMEDIATE on every platform, taking the write lock at once, for which SQLite waits as long as `busyTimeout`. On Android, it is what EXCLUSIVE did in WAL mode, and in DELETE mode, other connections can now read until the transaction commits. On the JVM and Kotlin/Native, a read-only connection begins a deferred transaction, as it can't take the write lock. The JVM driver begins and ends transactions with SQL rather than by leaving and entering auto-commit mode, as sqlite-jdbc then begins another transaction of the configured kind at once, which an IMMEDIATE one couldn't while another connection wrote * Fix: when SQLite rolled a transaction back itself, as it does for a constraint with `ON CONFLICT ROLLBACK`, which `onConflict = OnConflict.ROLLBACK` declares, for a trigger's `RAISE(ROLLBACK)` and for some I/O errors, ending the transaction failed too, as no transaction was active, and that failure took the place of the one that made SQLite roll it back, in `withTransaction` and so in the DSL's `transaction { }`. The failure that made SQLite roll it back is now thrown, with the failure to end the transaction added to it as a suppressed exception +* Fix: on Android 13 and higher, `execSQL("PRAGMA foreign_keys = ON")`, and `OFF`, and `PRAGMA recursive_triggers`, `legacy_alter_table` and `ignore_check_constraints`, didn't apply to the statements whose SQL had run before, which kept checking foreign keys or not, and firing triggers recursively or not, as before. A database in WAL mode has several connections there, and the framework only prepares such a PRAGMA on the connection that writes, stepping it on one that reads, as `sqlite3_stmt_readonly()` reports it doesn't write; SQLite changes the setting when it prepares the PRAGMA, but only expires the statements the connection has compiled when it steps it, so those the connection that writes had cached kept the setting they were compiled with. These PRAGMAs now run on every connection of the database, those opened later included, with `execPerConnectionSQL`, outside a transaction, and on the connection of the transaction inside one, where SQLite ignores a change of foreign_keys, as on the other platforms. Before Android 13, a database that SQLlin opens has a single connection, which wasn't affected +* Fix: on Kotlin/Native and on Android 8.1 and lower, `journalMode` didn't take effect, since 1.2.0: a database stayed in the journal mode it was in, DELETE for a new one on Kotlin/Native and that of the framework on Android, rather than that of the configuration, WAL by default. SQLlin set it there with the PRAGMA, as a query, whose cursor it never read, and a query there only runs as its cursor is read. The row it returns is now read. A connection that is read-only, as one that `isReadOnly` opens where the file can't be written, keeps the mode the file is in, as SQLite writes WAL mode to the header of the file +* New API: `TransactionMode`, `DEFERRED`, `IMMEDIATE` or `EXCLUSIVE`, which `DatabaseConnection#beginTransaction(mode)` and `withTransaction(mode) { }` begin a transaction in, rather than IMMEDIATE, the mode of `beginTransaction()`. `EXCLUSIVE` also keeps other connections from reading in DELETE journal mode, and `DEFERRED` takes no lock until the transaction reads or writes; Android's framework can't begin a deferred transaction that writes, so on Android `DEFERRED` begins an IMMEDIATE one. The new `beginTransaction` has a default implementation, which only begins an IMMEDIATE transaction, so a `DatabaseConnection` implemented outside SQLlin still compiles + +### sqllin-processor + +* Fix: only the Java classes of the processor had a JVM target, 21, so its Kotlin classes were compiled for the JDK that ran the build, as for Java 25 by JDK 25, which a KSP run on an older JDK can't load, failing with `UnsupportedClassVersionError`. The processor is now built with the JVM toolchain of the other modules, JDK 21, which its Kotlin classes target as well +* Support the properties whose serializers convert their values, see sqllin-dsl: the processor finds the serializer that kotlinx.serialization writes a property with, given on the property, on the use of its type or in a type alias, by `@file:UseSerializers` or by its class, and generates a `ClauseConverted` element with it. The objects of the tables that have such columns opt in to `ExperimentalDSLDatabaseAPI`, and to the markers that the `@OptIn`s of the entity's class, properties and file give, as the type of a column can need, as `Uuid` does. A property of a type that no column can hold, as a collection, a class serialized as a structure or a type serialized contextually, is still an error, whose message says how to give it a serializer that stores one value +* Fix: an enum, or any property, with a serializer that isn't the default one of its type, was compared and set as its type is by default; see sqllin-dsl +* Fix: the object generated for a `@DBRow` or `@DBView` class annotated with an opt-in marker, as `@ExperimentalUuidApi`, which requires the uses of the class to opt in, didn't opt in to it, so it didn't compile; it now opts in to the markers that the class, its properties and its file are annotated with ## 2.5.0 / 2026-10-11 diff --git a/README.md b/README.md index 090a21f4..9e10426d 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ The architecture design of SQLlin is shown in the figure: SQLlin has 3 major parts: _sqllin-dsl_, _sqllin-driver_ and _sqllin-processor_. The _sqllin-driver_ is a set of common multiplatform SQLite low-level APIs, most of the time it is not recommended to use it directly. The _sqllin-dsl_ is DSL implementations for SQL statements, it is based on _sqllin-driver_. The _sqllin-processor_ uses KSP to process annotations and generate code for using with _sqllin-dsl_. +The optional _sqllin-dsl-paging_ provides androidx.paging's `PagingSource` for the queries of _sqllin-dsl_. You can learn how to use _sqllin-dsl_ in these documentations: diff --git a/README_CN.md b/README_CN.md index 6612439c..33e6efcf 100644 --- a/README_CN.md +++ b/README_CN.md @@ -43,6 +43,7 @@ SQLlin 的架构设计如下图所示: SQLlin 拥有三个主要部分:_sqllin-dsl_、_sqllin-driver_ 及 _sqllin-processor_。_sqllin-driver_ 是一套通用的多平台 SQLite 低阶 API,大多数情况下不推荐直接使用。 _sqllin-dsl_ 是 SQL 语句的 DSL 实现并且它基于 _sqllin-driver_。_sqllin-processor_ 使用 KSP 处理注解并生成用于与 _sqllin-dsl_ 配合使用的代码。 +可选的 _sqllin-dsl-paging_ 为 _sqllin-dsl_ 的查询提供 androidx.paging 的 `PagingSource`。 你可以在下列文档中学习如何使用 _sqllin-dsl_: diff --git a/ROADMAP.md b/ROADMAP.md index 5f8b78b0..441fdd83 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -3,27 +3,13 @@ Each item has an ID, `Fx`, which stays the same when the item moves to another priority, and under Supported once it is done. A new item takes the next number. -## High Priority - -* F7: Remove the joins written as clauses of SELECT, such as `table SELECT INNER_JOIN(other)`, in the next version after 2.5.0, then let a join start with its first relation, as in `PersonTable INNER_JOIN BookTable`, without `FROM` - ## Medium Priority * F8: Support WASM platform DSL -* F12: Support type converters: store a property of any type through a serializer that encodes it to a type SQLite supports, with type-safe WHERE and SET on its column, e.g. to store instances of kotlinx.datetime -* F66: Provide table version tokens, which tell a reader when the tables it read change, such as a `PagingSource` that has to invalidate itself: `versioned { }` runs a read-only scope and returns its results with an opaque token of the versions of the tables its SELECTs read, captured under the lock that the read runs under, after the tables are tracked; tokens combine with `+`, which takes the earlier version of a table and rejects the tokens of another `Database`; `awaitChange(token)` suspends until one of their tables changes, and `onChange(token) { }` registers a one-shot callback, which runs after the writing scope releases the lock, and returns null instead when the token is already stale, as it registers before it checks, so that no change between the read and the registration is missed -* F13: Provide a `PagingSource` for androidx.paging built on the table version tokens of F66, like Room's `LimitOffsetPagingSource`, so that paging a query doesn't need a hand-written bridge: it registers with `onChange` from its first load, holding its callback strongly while the registry holds it weakly, so that a source that Pager abandons doesn't stay registered, keeps the previous key of an invalidated offset-keyed source, reads `anchorPosition` relative to the presented list without placeholders, and keeps offsets on a grid of the page size * F14: Support constraints in `ALTER_ADD_COLUMN`, which adds a column with its type only: DEFAULT, NOT NULL with DEFAULT, CHECK, COLLATE NOCASE and REFERENCES -* F15: Support WITHOUT ROWID tables, which save space and a lookup when the primary key isn't an INTEGER +* F15: Support WITHOUT ROWID tables, which save space and a lookup when the primary key isn't an INTEGER; the ORDER BY and LIMIT of UPDATE and DELETE (F25) then have to choose the rows by their primary key, as SQLite does, rather than by the rowid * F16: Support STRICT tables, which reject values of other types than their columns' (SQLite 3.37.0, Android API 34) -* F19: Support the collations BINARY and RTRIM besides NOCASE, and COLLATE on the columns of an index and in ORDER BY * F21: Support FILTER in aggregate functions (SQLite 3.30.0, Android API 31), and ORDER BY in them, as for `group_concat` (SQLite 3.44.0, Android API 35) -* F23: Support the other conflict resolutions: INSERT OR ABORT, OR FAIL and OR ROLLBACK, and UPDATE OR IGNORE, OR REPLACE and the others -* F25: Support ORDER BY and LIMIT in UPDATE and DELETE, which need SQLite's `SQLITE_ENABLE_UPDATE_DELETE_LIMIT` option, which Android's lacks -* F26: Support INDEXED BY and NOT INDEXED -* F27: Support choosing how a transaction begins, DEFERRED or EXCLUSIVE, besides IMMEDIATE, which every platform uses since 2.6.0 -* F29: Support EXPLAIN QUERY PLAN, to see which indexes a query uses -* F30: Support more PRAGMAs, such as integrity_check, quick_check, table_info, index_list, wal_checkpoint, defer_foreign_keys and case_sensitive_like ## Low Priority @@ -47,9 +33,28 @@ done. A new item takes the next number. * F63: Support INSTEAD OF triggers on views, together with INSERT, UPDATE and DELETE on a view, which the DSL doesn't allow, as a view isn't a `Table`, so that such a trigger can be used; left out of the first version of CREATE TRIGGER (F10) * F64: Support the JSON functions and JSON's `->` and `->>` operators (SQLite 3.38.0, Android API 34), left out of F46 * F65: Support the conflict clause of NOT NULL, as `NOT NULL ON CONFLICT REPLACE`, which writes the default value instead of NULL, left out of F17: a property's type declares NOT NULL, so no annotation can hold the clause yet; it could be a new annotation, or a parameter of `@Default`. SQLlin's statements rarely write NULL to a non-null column, so it is of little use for now +* F67: Support the PRAGMAs that set how each connection runs statements, such as cache_size, temp_store, mmap_size, query_only, automatic_index, trusted_schema, threads, cache_spill, analysis_limit, journal_size_limit, wal_autocheckpoint, max_page_count, secure_delete and cell_size_check, as parameters of `DatabaseConfiguration` and `DSLDBConfiguration` rather than as statements: Android's framework reads through several connections of a database in WAL mode from Android 13 on, while a statement sets a PRAGMA on the one connection that writes, so they have to be set on every connection, as `busyTimeout` is, and Android's framework sets journal_size_limit and wal_autocheckpoint on each connection it opens; and a change of temp_store deletes the TEMP tables and triggers, which observed queries count changes with + +## Shelved + +Items that aren't planned, as they are of little use, or would cost more than they give, until a need for them comes up. + +* F68: Support `PRAGMA incremental_vacuum`, which removes the unused pages that the INCREMENTAL mode of `PRAGMA_AUTO_VACUUM(mode)` keeps: it removes a page each time it returns a row, which has no columns, so it has to run as a query whose rows are all read. Android's framework and Kotlin/Native would run it so, but sqlite-jdbc doesn't run a statement that returns no columns as a query, and runs it as a statement only as far as its first row, removing one page, so the JVM would have to run `PRAGMA incremental_vacuum(1)` once for each page, in a transaction. Few databases are in INCREMENTAL mode, and Android's SQLite creates them in FULL mode +* F69: Support `PRAGMA data_version`, which changes when another connection or process commits to the database, so that the table version tokens of F66, and what is built on them, as the `PagingSource` of F13, could see those changes too, as they only see those made through the same `Database`. It tells that the database changed, not which tables did, and each connection has its own count, so Android's pool of connections, which can run a read on any of them, needs a design of its own; left out of F30 ## Supported +* F12: Support type converters: store a property of any type through a serializer that encodes it to a type SQLite supports, with type-safe WHERE and SET on its column. The serializer kotlinx.serialization writes the property with is the converter: built-in ones of `Uuid`, `Instant` and `Duration`, value classes, and any given with `@Serializable(with = ...)` or `@file:UseSerializers`; the column's element, `ClauseConverted`, converts the values of its conditions with it (2.6.0 ✅) +* F13: Provide a `PagingSource` for androidx.paging built on the table version tokens of F66, like Room's `LimitOffsetPagingSource`, in the new module sqllin-dsl-paging, `Database#pagingSource { }` (2.6.0 ✅) +* F25: Support ORDER BY and LIMIT in UPDATE and DELETE, which SQLite only takes with its `SQLITE_ENABLE_UPDATE_DELETE_LIMIT` option, which Android's lacks: SQLlin writes the subquery of rowids that SQLite turns them into, which every platform runs (2.6.0 ✅) +* F19: Support the collations BINARY and RTRIM besides NOCASE, and COLLATE on the columns of an index and in ORDER BY: `@CollateRTrim` for a column, which needs no `@CollateBinary`, as BINARY is a column's default, and the `COLLATE` operator of F46 for a column of an index, as it already was for conditions and ORDER BY (2.6.0 ✅) +* F30: Support more PRAGMAs: those that check the database, read its schema and what the SQLite has, checkpoint the WAL, read the size and the header of the file, and set how statements run; case_sensitive_like is left out, as SQLite deprecates it, and incremental_vacuum, shelved as F68, as sqlite-jdbc only runs it as far as the first of the rows it returns, one for each page it removes (2.6.0 ✅) +* F29: Support EXPLAIN QUERY PLAN, to see which indexes a query uses (2.6.0 ✅) +* F26: Support INDEXED BY and NOT INDEXED (2.6.0 ✅) +* F27: Support choosing how a transaction begins, DEFERRED, IMMEDIATE or EXCLUSIVE (2.6.0 ✅) +* F23: Support the other conflict resolutions: INSERT OR ABORT, OR FAIL and OR ROLLBACK, and UPDATE OR ABORT, OR FAIL, OR IGNORE, OR REPLACE and OR ROLLBACK (2.6.0 ✅) +* F66: Provide table version tokens, `versioned { }`, `awaitChange` and `onChange`, which tell a reader when the tables it read change (2.6.0 ✅) +* F7: Remove the joins written as clauses of SELECT, such as `table SELECT INNER_JOIN(other)`, and let a join start with its first relation, as in `PersonTable INNER_JOIN BookTable`, without `FROM` (2.6.0 ✅) * F17: Support conflict clauses on PRIMARY KEY and UNIQUE constraints (2.5.0 ✅) * F18: Support DEFERRABLE INITIALLY DEFERRED foreign keys (2.5.0 ✅) * F22: Support NULLS FIRST and NULLS LAST in ORDER BY (2.5.0 ✅) diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index e6da5f81..be0cc0b5 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -1,19 +1,20 @@ [versions] kotlin = "2.4.21" -agp = "9.4.1" +agp = "9.5.1" ksp = "2.3.12" -serialization = "1.11.0" +serialization = "1.12.0" coroutines = "1.11.0" androidx-annotation = "1.11.0" androidx-test = "1.7.0" robolectric = "4.17" junit = "4.13.2" -sqlite-jdbc = "3.53.4.0" +sqlite-jdbc = "3.54.1.0" jvm-toolchain = "21" android-sdk-compile = "37" android-sdk-min = "24" vanniktech-maven-publish = "0.37.0" +paging = "3.5.3" [libraries] @@ -30,6 +31,9 @@ junit = { group = "junit", name = "junit", version.ref = "junit" } sqlite-jdbc = { group = "org.xerial", name = "sqlite-jdbc", version.ref = "sqlite-jdbc" } +androidx-paging-common = { group = "androidx.paging", name = "paging-common", version.ref = "paging" } +androidx-paging-testing = { group = "androidx.paging", name = "paging-testing", version.ref = "paging" } + [plugins] kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" } diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index 96052ec1..a6d06e1f 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,6 +1,6 @@ #Tue Mar 08 15:11:46 CST 2022 distributionBase=GRADLE_USER_HOME -distributionUrl=https\://services.gradle.org/distributions/gradle-9.7.1-bin.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-9.9.0-bin.zip distributionPath=wrapper/dists zipStorePath=wrapper/dists zipStoreBase=GRADLE_USER_HOME \ No newline at end of file diff --git a/publish_all.sh b/publish_all.sh index 463ec18e..c1055833 100755 --- a/publish_all.sh +++ b/publish_all.sh @@ -1,4 +1,5 @@ # Publish artifacts on macOS env ./gradlew :sqllin-driver:publishAllPublicationsToMavenCentralRepository ./gradlew :sqllin-dsl:publishAllPublicationsToMavenCentralRepository +./gradlew :sqllin-dsl-paging:publishAllPublicationsToMavenCentralRepository ./gradlew :sqllin-processor:publishMavenPublicationToMavenCentralRepository \ No newline at end of file diff --git a/sample/src/commonMain/kotlin/com/ctrip/sqllin/sample/Sample.kt b/sample/src/commonMain/kotlin/com/ctrip/sqllin/sample/Sample.kt index cc6bdf74..e474d53e 100644 --- a/sample/src/commonMain/kotlin/com/ctrip/sqllin/sample/Sample.kt +++ b/sample/src/commonMain/kotlin/com/ctrip/sqllin/sample/Sample.kt @@ -19,7 +19,9 @@ package com.ctrip.sqllin.sample import com.ctrip.sqllin.dsl.DSLDBConfiguration import com.ctrip.sqllin.dsl.Database import com.ctrip.sqllin.dsl.annotation.DBRow +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI import com.ctrip.sqllin.dsl.annotation.PrimaryKey +import com.ctrip.sqllin.dsl.sql.X import com.ctrip.sqllin.dsl.sql.clause.* import com.ctrip.sqllin.dsl.sql.clause.OrderByWay.DESC import com.ctrip.sqllin.dsl.sql.statement.SelectStatement @@ -78,29 +80,21 @@ object Sample { } + @OptIn(ExperimentalDSLDatabaseAPI::class) fun joinSample() { db { - PersonTable { table -> - table SELECT CROSS_JOIN(TranscriptTable) - table SELECT INNER_JOIN(TranscriptTable) USING name - table SELECT NATURAL_JOIN(TranscriptTable) - table SELECT LEFT_OUTER_JOIN(TranscriptTable) USING name - table SELECT NATURAL_LEFT_OUTER_JOIN(TranscriptTable) - } + (PersonTable INNER_JOIN TranscriptTable USING PersonTable.name) SELECT X() + (PersonTable NATURAL_JOIN TranscriptTable) SELECT X() } } + @OptIn(ExperimentalDSLDatabaseAPI::class) fun concurrentSafeCall() { CoroutineScope(Dispatchers.Default).launch { db suspendedScope { - PersonTable { table -> - table SELECT CROSS_JOIN(TranscriptTable) - table SELECT INNER_JOIN(TranscriptTable) USING name - delay(100) - table SELECT NATURAL_JOIN(TranscriptTable) - table SELECT LEFT_OUTER_JOIN(TranscriptTable) USING name - table SELECT NATURAL_LEFT_OUTER_JOIN(TranscriptTable) - } + (PersonTable INNER_JOIN TranscriptTable USING PersonTable.name) SELECT X() + delay(100) + (PersonTable NATURAL_JOIN TranscriptTable) SELECT X() } } } diff --git a/settings.gradle.kts b/settings.gradle.kts index 60c10adc..768854e7 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -1,6 +1,7 @@ rootProject.name = "SQLlin" include(":sqllin-driver") include(":sqllin-dsl") +include(":sqllin-dsl-paging") include(":sqllin-processor") include(":sqllin-dsl-test") include(":sample") diff --git a/sqllin-driver/src/androidHostTest/kotlin/com/ctrip/sqllin/driver/test/AndroidTest.kt b/sqllin-driver/src/androidHostTest/kotlin/com/ctrip/sqllin/driver/test/AndroidTest.kt index c5ca7198..3cabc918 100644 --- a/sqllin-driver/src/androidHostTest/kotlin/com/ctrip/sqllin/driver/test/AndroidTest.kt +++ b/sqllin-driver/src/androidHostTest/kotlin/com/ctrip/sqllin/driver/test/AndroidTest.kt @@ -66,9 +66,18 @@ class AndroidTest { @Test fun testImmediateTransaction() = commonTest.testImmediateTransaction() + @Test + fun testTransactionModes() = commonTest.testTransactionModes(isDeferredSupported = false) + + @Test + fun testJournalMode() = commonTest.testJournalMode() + @Test fun testBusyTimeout() = commonTest.testBusyTimeout() + @Test + fun testConnectionPragmas() = commonTest.testConnectionPragmas() + @Test fun testConcurrency() = commonTest.testConcurrency() diff --git a/sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/AndroidDatabaseConnection.kt b/sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/AndroidDatabaseConnection.kt index fadc2ae8..1eb3d961 100644 --- a/sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/AndroidDatabaseConnection.kt +++ b/sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/AndroidDatabaseConnection.kt @@ -17,6 +17,7 @@ package com.ctrip.sqllin.driver import android.database.sqlite.SQLiteCursor +import android.os.Build import android.database.sqlite.SQLiteDatabase import android.database.sqlite.SQLiteQuery @@ -27,11 +28,36 @@ import android.database.sqlite.SQLiteQuery */ internal class AndroidDatabaseConnection(private val database: SQLiteDatabase) : DatabaseConnection { - override fun execSQL(sql: String, bindParams: Array?) = - if (bindParams == null) - database.execSQL(sql) - else - database.execSQL(sql, Array(bindParams.size) { unsignedAsLong(bindParams[it]) }) + /** + * Runs [sql], and a PRAGMA that sets how the connection runs statements on every connection of the database. + * + * From Android 13 on, a database in WAL mode has several connections: the one that writes, and those that read + * outside a transaction. The framework only prepares a PRAGMA such as `foreign_keys = ON` on the connection that + * writes, and steps it on one that reads, as `sqlite3_stmt_readonly()` reports it doesn't write. SQLite changes the + * setting when it prepares the PRAGMA, but only expires the statements the connection has compiled when it steps + * it, so the statements that the connection that writes has cached kept running as they were compiled, with the + * setting they had: without checking foreign keys, or with them; and the other connections that read didn't have + * it, which `PRAGMA foreign_keys` may read through. Such a PRAGMA runs on every connection, + * those opened later included, so that each steps it. In a transaction, which runs on the connection that writes, + * it runs there, where SQLite ignores a change of foreign_keys, as it does on the other platforms, and applies + * recursive_triggers to the statements after it, which only that connection runs. Before Android 13, a database + * that SQLlin opens has a single connection. + */ + override fun execSQL(sql: String, bindParams: Array?) = when { + bindParams != null -> database.execSQL(sql, Array(bindParams.size) { unsignedAsLong(bindParams[it]) }) + Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU && !database.inTransaction() && CONNECTION_SETTING.containsMatchIn(sql) -> + database.execPerConnectionSQL(sql, null) + else -> database.execSQL(sql) + } + + private companion object { + /** + * A PRAGMA that sets how the connection runs statements, which each connection has to run itself: foreign_keys, + * recursive_triggers and ignore_check_constraints, which SQLite compiles into the statements, and + * legacy_alter_table, which ALTER TABLE RENAME reads. + */ + val CONNECTION_SETTING = Regex("""^\s*PRAGMA\s+(foreign_keys|recursive_triggers|legacy_alter_table|ignore_check_constraints)\s*[=(]""", RegexOption.IGNORE_CASE) + } /** * The framework binds a value it doesn't know, such as a `UInt`, as its string, so unsigned values are bound as @@ -96,8 +122,15 @@ internal class AndroidDatabaseConnection(private val database: SQLiteDatabase) : } } - // BEGIN IMMEDIATE, as on every platform, which beginTransaction's EXCLUSIVE only is in WAL mode - override fun beginTransaction() = database.beginTransactionNonExclusive() + override fun beginTransaction() = beginTransaction(TransactionMode.IMMEDIATE) + + // beginTransactionNonExclusive begins an IMMEDIATE transaction, and beginTransaction an EXCLUSIVE one. The framework + // can't begin a DEFERRED one that writes, as it turns a BEGIN statement into an EXCLUSIVE transaction of its own, so + // that one is IMMEDIATE, which only takes the write lock earlier + override fun beginTransaction(mode: TransactionMode) = when (mode) { + TransactionMode.EXCLUSIVE -> database.beginTransaction() + TransactionMode.DEFERRED, TransactionMode.IMMEDIATE -> database.beginTransactionNonExclusive() + } override fun endTransaction() { try { database.endTransaction() diff --git a/sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/ExtensionAndroid.kt b/sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/ExtensionAndroid.kt index 8d7f27e4..a20f0cba 100644 --- a/sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/ExtensionAndroid.kt +++ b/sqllin-driver/src/androidMain/kotlin/com/ctrip/sqllin/driver/ExtensionAndroid.kt @@ -49,7 +49,8 @@ public actual fun openDatabase(config: DatabaseConfiguration): DatabaseConnectio val connection = AndroidDatabaseConnection(database) if (!isEqualsOrHigherThanAndroidP) { connection.updateSynchronousMode(config.synchronousMode) - connection.updateJournalMode(config.journalMode) + if (!database.isReadOnly) + connection.updateJournalMode(config.journalMode) } return connection } diff --git a/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/DatabaseConnection.kt b/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/DatabaseConnection.kt index 8d4abe8f..7f04a327 100644 --- a/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/DatabaseConnection.kt +++ b/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/DatabaseConnection.kt @@ -60,10 +60,24 @@ public interface DatabaseConnection { public fun query(sql: String, bindParams: Array? = null): CommonCursor /** - * Begins a database transaction. + * Begins an IMMEDIATE transaction, which takes the write lock at once, on every platform. */ public fun beginTransaction() + /** + * Begins a transaction in [mode], which decides when it takes the write lock. + * + * The default implementation, for a connection SQLlin doesn't provide, only begins an IMMEDIATE transaction, through + * [beginTransaction]; the connections of SQLlin begin one in each mode. + * + * @throws UnsupportedOperationException if this connection doesn't begin a transaction in [mode] + */ + public fun beginTransaction(mode: TransactionMode) { + if (mode != TransactionMode.IMMEDIATE) + throw UnsupportedOperationException("This connection only begins IMMEDIATE transactions, not $mode ones.") + beginTransaction() + } + /** * Marks the current transaction as successful. * diff --git a/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/Extension.kt b/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/Extension.kt index a483ccbe..12ecf1ac 100644 --- a/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/Extension.kt +++ b/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/Extension.kt @@ -59,7 +59,7 @@ public inline fun openDatabase(config: DatabaseConfiguration, block: (Databa } /** - * Executes a block within a database transaction. + * Executes a block within a database transaction, which begins in [mode], IMMEDIATE unless another is given. * * The transaction is committed if the block completes successfully, * or rolled back if an exception is thrown. @@ -68,11 +68,12 @@ public inline fun openDatabase(config: DatabaseConfiguration, block: (Databa * SQLite rolls some transactions back itself, as for a constraint with ON CONFLICT ROLLBACK or a trigger's * RAISE(ROLLBACK), and then the ROLLBACK fails, as no transaction is active. * + * @param mode How the transaction begins, which decides when it takes the write lock * @param block The block to execute within the transaction * @return The result of the block */ -public inline fun DatabaseConnection.withTransaction(block: (DatabaseConnection) -> T): T { - beginTransaction() +public inline fun DatabaseConnection.withTransaction(mode: TransactionMode = TransactionMode.IMMEDIATE, block: (DatabaseConnection) -> T): T { + beginTransaction(mode) var failure: Throwable? = null try { val result = block(this) @@ -124,16 +125,20 @@ public expect fun deleteDatabase(path: DatabasePath, name: String): Boolean * Updates the database's synchronous mode if different from current. */ internal infix fun DatabaseConnection.updateSynchronousMode(mode: SynchronousMode) { - val currentJournalMode = withQuery("PRAGMA synchronous;") { + val currentSynchronousMode = withQuery("PRAGMA synchronous;") { it.next() it.getInt(0) } - if (currentJournalMode != mode.value) + if (currentSynchronousMode != mode.value) execSQL("PRAGMA synchronous=${mode.value};") } /** * Updates the database's journal mode if different from current. + * + * The PRAGMA returns the mode as a row, which is read, as a query on Android and Kotlin/Native only runs as its cursor + * is read: without it, the mode never changed. A connection that is read-only can't change it, as SQLite writes WAL + * mode to the header of the file, so it isn't called for one. */ internal infix fun DatabaseConnection.updateJournalMode(mode: JournalMode) { val currentJournalMode = withQuery("PRAGMA journal_mode;") { @@ -141,7 +146,7 @@ internal infix fun DatabaseConnection.updateJournalMode(mode: JournalMode) { it.getString(0) } if (!currentJournalMode.equals(mode.name, ignoreCase = true)) - withQuery("PRAGMA journal_mode=${mode.name};") {} + withQuery("PRAGMA journal_mode=${mode.name};") { it.next() } } /** diff --git a/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/TransactionMode.kt b/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/TransactionMode.kt new file mode 100644 index 00000000..3935e053 --- /dev/null +++ b/sqllin-driver/src/commonMain/kotlin/com/ctrip/sqllin/driver/TransactionMode.kt @@ -0,0 +1,38 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.driver + +/** + * How a transaction begins, as `BEGIN DEFERRED`, `BEGIN IMMEDIATE` or `BEGIN EXCLUSIVE`, which decides when it takes the + * database's write lock. + * + * @property DEFERRED Takes no lock until the transaction reads, nor the write lock until it writes, so other connections + * can write until then. But a transaction that reads before it writes then fails at once with "database is locked" while + * another connection writes, as SQLite doesn't wait for the busy timeout where waiting could deadlock. Android's framework + * can't begin a deferred transaction that writes, so on Android, it begins an IMMEDIATE one + * @property IMMEDIATE Takes the write lock at once, waiting for the busy timeout while another connection holds it, so + * that the transaction can't fail later for a lock. The mode of a transaction unless another is given + * @property EXCLUSIVE Takes the write lock at once too, and in DELETE journal mode also keeps other connections from + * reading until the transaction ends; in WAL mode, it is the same as IMMEDIATE + * + * @author Yuang Qiao + */ +public enum class TransactionMode { + DEFERRED, + IMMEDIATE, + EXCLUSIVE; +} diff --git a/sqllin-driver/src/commonTest/kotlin/com/ctrip/sqllin/driver/test/CommonBasicTest.kt b/sqllin-driver/src/commonTest/kotlin/com/ctrip/sqllin/driver/test/CommonBasicTest.kt index 80b7ccde..a21fd93f 100644 --- a/sqllin-driver/src/commonTest/kotlin/com/ctrip/sqllin/driver/test/CommonBasicTest.kt +++ b/sqllin-driver/src/commonTest/kotlin/com/ctrip/sqllin/driver/test/CommonBasicTest.kt @@ -18,6 +18,8 @@ package com.ctrip.sqllin.driver.test import com.ctrip.sqllin.driver.DatabaseConfiguration import com.ctrip.sqllin.driver.DatabasePath +import com.ctrip.sqllin.driver.JournalMode +import com.ctrip.sqllin.driver.TransactionMode import com.ctrip.sqllin.driver.openDatabase import com.ctrip.sqllin.driver.withQuery import com.ctrip.sqllin.driver.withTransaction @@ -269,6 +271,95 @@ class CommonBasicTest(private val path: DatabasePath) { } } + /** + * A transaction begins in the mode given: an IMMEDIATE or EXCLUSIVE one takes the write lock at once, so another + * connection can't write until it ends, while a DEFERRED one takes none until it writes, but on Android, whose + * framework begins an IMMEDIATE one instead. + */ + fun testTransactionModes(isDeferredSupported: Boolean) { + val book = arrayOf("The Da Vinci Code", "Dan Brown", 454, 16.96, byteArrayOf()) + openDatabase(getDefaultDBConfig(false)) { + openDatabase(getDefaultDBConfig(false).copy(busyTimeout = 0)) { other -> + for (mode in listOf(TransactionMode.IMMEDIATE, TransactionMode.EXCLUSIVE)) { + it.withTransaction(mode) { + assertFails { other.executeInsert(SQL.INSERT_BOOK, book) } + } + } + it.withTransaction(TransactionMode.DEFERRED) { connection -> + if (isDeferredSupported) + other.executeInsert(SQL.INSERT_BOOK, book) + else + assertFails { other.executeInsert(SQL.INSERT_BOOK, book) } + // It takes the write lock once it writes + connection.executeInsert(SQL.INSERT_BOOK, book) + } + val books = it.withQuery("SELECT count(*) FROM book") { cursor -> cursor.next(); cursor.getLong(0) } + assertEquals(if (isDeferredSupported) 2L else 1L, books) + } + } + } + + /** + * A PRAGMA that sets how the connection runs statements, foreign_keys or recursive_triggers, applies to the + * statements that ran before it too, whose SQL the connection that writes has compiled with the setting they had: + * on Android 13 and higher, a database in WAL mode has several connections, which all have to run it. In a + * transaction, foreign_keys changes nothing, as SQLite says, and recursive_triggers applies to the statements after + * it, and to those after the transaction. + */ + fun testConnectionPragmas() { + openDatabase(getDefaultDBConfig(false)) { + fun single(sql: String): Long = it.withQuery(sql) { cursor -> cursor.next(); cursor.getLong(0) } + it.execSQL("CREATE TABLE parent(id INTEGER PRIMARY KEY)") + it.execSQL("CREATE TABLE child(id INTEGER PRIMARY KEY, parentId INTEGER REFERENCES parent(id))") + val insertChild = "INSERT INTO child (parentId) VALUES (?)" + // Compiled without the checks of foreign keys, which are off + it.executeInsert(insertChild, arrayOf(1L)) + it.execSQL("PRAGMA foreign_keys = ON") + assertEquals(1L, single("PRAGMA foreign_keys")) + assertContains(assertFails { it.executeInsert(insertChild, arrayOf(2L)) }.message.orEmpty(), "FOREIGN KEY constraint failed") + it.execSQL("PRAGMA foreign_keys = OFF") + assertEquals(0L, single("PRAGMA foreign_keys")) + it.executeInsert(insertChild, arrayOf(3L)) + it.withTransaction { connection -> connection.execSQL("PRAGMA foreign_keys = ON") } + assertEquals(0L, single("PRAGMA foreign_keys")) + it.executeInsert(insertChild, arrayOf(4L)) + assertEquals(3L, single("SELECT count(*) FROM child")) + + it.execSQL("CREATE TABLE counter(id INTEGER PRIMARY KEY, n INT)") + it.execSQL("CREATE TRIGGER counter_chain AFTER INSERT ON counter WHEN new.n < 3 BEGIN INSERT INTO counter VALUES (new.id + 1, new.n + 1); END") + val insertCounter = "INSERT INTO counter VALUES (?, ?)" + fun counters(): List = it.withQuery("SELECT id FROM counter ORDER BY id") { cursor -> + buildList { cursor.forEachRow { add(cursor.getLong(0)) } } + } + // Compiled without recursive triggers, which are off + it.executeInsert(insertCounter, arrayOf(1L, 0L)) + assertEquals(listOf(1L, 2L), counters()) + it.execSQL("PRAGMA recursive_triggers = 1") + it.executeInsert(insertCounter, arrayOf(10L, 0L)) + assertEquals(listOf(1L, 2L, 10L, 11L, 12L, 13L), counters()) + it.withTransaction { connection -> + connection.execSQL("PRAGMA recursive_triggers = 0") + connection.executeInsert(insertCounter, arrayOf(20L, 0L)) + } + it.executeInsert(insertCounter, arrayOf(30L, 0L)) + assertEquals(listOf(1L, 2L, 10L, 11L, 12L, 13L, 20L, 21L, 30L, 31L), counters()) + } + } + + /** + * The database is in the journal mode of its configuration, WAL by default, to which it is switched when it is + * opened from the mode it was left in. + */ + fun testJournalMode() { + fun journalMode(config: DatabaseConfiguration): String? = openDatabase(config) { + it.withQuery("PRAGMA journal_mode") { cursor -> cursor.next(); cursor.getString(0) } + } + val config = getDefaultDBConfig(false) + assertEquals("wal", journalMode(config)) + assertEquals("delete", journalMode(config.copy(journalMode = JournalMode.DELETE))) + assertEquals("wal", journalMode(config)) + } + /** * SQLite waits as long as `busyTimeout` for a lock that another connection holds. */ diff --git a/sqllin-driver/src/jvmMain/kotlin/com/ctrip/sqllin/driver/ConcurrentDatabaseConnection.kt b/sqllin-driver/src/jvmMain/kotlin/com/ctrip/sqllin/driver/ConcurrentDatabaseConnection.kt index 236886e5..5c925b91 100644 --- a/sqllin-driver/src/jvmMain/kotlin/com/ctrip/sqllin/driver/ConcurrentDatabaseConnection.kt +++ b/sqllin-driver/src/jvmMain/kotlin/com/ctrip/sqllin/driver/ConcurrentDatabaseConnection.kt @@ -50,6 +50,10 @@ internal class ConcurrentDatabaseConnection(private val delegateConnection: Data delegateConnection.beginTransaction() } + override fun beginTransaction(mode: TransactionMode) = accessLock.withLock { + delegateConnection.beginTransaction(mode) + } + override fun setTransactionSuccessful() = accessLock.withLock { delegateConnection.setTransactionSuccessful() } diff --git a/sqllin-driver/src/jvmMain/kotlin/com/ctrip/sqllin/driver/JdbcDatabaseConnection.kt b/sqllin-driver/src/jvmMain/kotlin/com/ctrip/sqllin/driver/JdbcDatabaseConnection.kt index 9bc2d59b..d4c0bbb1 100644 --- a/sqllin-driver/src/jvmMain/kotlin/com/ctrip/sqllin/driver/JdbcDatabaseConnection.kt +++ b/sqllin-driver/src/jvmMain/kotlin/com/ctrip/sqllin/driver/JdbcDatabaseConnection.kt @@ -57,19 +57,20 @@ internal class JdbcDatabaseConnection(private val connection: Connection) : Abst private val isTransactionSuccess = AtomicBoolean(false) /** - * Begins an IMMEDIATE transaction, which takes the write lock at once, as on every platform, or a deferred one on a - * read-only connection, which can't take it. + * Begins a transaction in [mode], or a deferred one on a read-only connection, which can't take the write lock. * * It is begun with SQL, in auto-commit mode, rather than by leaving auto-commit mode: sqlite-jdbc begins another * transaction of its configured kind as soon as one is committed or rolled back, which an IMMEDIATE one couldn't * do while another connection writes, so that a COMMIT that succeeded would fail. */ - override fun beginTransaction() { + override fun beginTransaction(mode: TransactionMode) { if (isTransactionSuccess.get()) isTransactionSuccess.set(false) - execSQL(if (connection.isReadOnly) "BEGIN" else "BEGIN IMMEDIATE", null) + execSQL(if (connection.isReadOnly) "BEGIN" else "BEGIN ${mode.name}", null) } + override fun beginTransaction() = beginTransaction(TransactionMode.IMMEDIATE) + override fun setTransactionSuccessful() { isTransactionSuccess.set(true) } diff --git a/sqllin-driver/src/jvmTest/kotlin/com/ctrip/sqllin/driver/test/JvmTest.kt b/sqllin-driver/src/jvmTest/kotlin/com/ctrip/sqllin/driver/test/JvmTest.kt index 736ebc58..beafa7a8 100644 --- a/sqllin-driver/src/jvmTest/kotlin/com/ctrip/sqllin/driver/test/JvmTest.kt +++ b/sqllin-driver/src/jvmTest/kotlin/com/ctrip/sqllin/driver/test/JvmTest.kt @@ -55,9 +55,18 @@ class JvmTest { @Test fun testImmediateTransaction() = commonTest.testImmediateTransaction() + @Test + fun testTransactionModes() = commonTest.testTransactionModes(isDeferredSupported = true) + + @Test + fun testJournalMode() = commonTest.testJournalMode() + @Test fun testBusyTimeout() = commonTest.testBusyTimeout() + @Test + fun testConnectionPragmas() = commonTest.testConnectionPragmas() + @Test fun testConcurrency() = commonTest.testConcurrency() diff --git a/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/ConcurrentDatabaseConnection.kt b/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/ConcurrentDatabaseConnection.kt index 7c0467e1..384b59fa 100644 --- a/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/ConcurrentDatabaseConnection.kt +++ b/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/ConcurrentDatabaseConnection.kt @@ -52,6 +52,10 @@ internal class ConcurrentDatabaseConnection( delegateConnection.beginTransaction() } + override fun beginTransaction(mode: TransactionMode) = accessLock.withLock { + delegateConnection.beginTransaction(mode) + } + override fun setTransactionSuccessful() = accessLock.withLock { delegateConnection.setTransactionSuccessful() } diff --git a/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/ExtensionNative.kt b/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/ExtensionNative.kt index a1f0e00b..5075c44b 100644 --- a/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/ExtensionNative.kt +++ b/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/ExtensionNative.kt @@ -34,7 +34,8 @@ public actual fun openDatabase(config: DatabaseConfiguration): DatabaseConnectio val realConnection = RealDatabaseConnection(database) realConnection.apply { updateSynchronousMode(config.synchronousMode) - updateJournalMode(config.journalMode) + if (!database.isActualReadOnly) + updateJournalMode(config.journalMode) try { migrateIfNeeded(config.create, config.upgrade, config.version, database.isActualReadOnly) } catch (e: Exception) { diff --git a/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/RealDatabaseConnection.kt b/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/RealDatabaseConnection.kt index ef1b8838..af187625 100644 --- a/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/RealDatabaseConnection.kt +++ b/sqllin-driver/src/nativeMain/kotlin/com/ctrip/sqllin/driver/RealDatabaseConnection.kt @@ -72,9 +72,11 @@ internal class RealDatabaseConnection( override fun query(sql: String, bindParams: Array?): CommonCursor = bindParamsToSQL(sql, bindParams).query() - // IMMEDIATE takes the write lock at once, as on every platform; a read-only connection can't take it - override fun beginTransaction() = transactionLock.withLock { - database.rawExecSql(if (database.isActualReadOnly) "BEGIN;" else "BEGIN IMMEDIATE;") + override fun beginTransaction() = beginTransaction(TransactionMode.IMMEDIATE) + + // A read-only connection can't take the write lock, so it begins a deferred transaction + override fun beginTransaction(mode: TransactionMode) = transactionLock.withLock { + database.rawExecSql(if (database.isActualReadOnly) "BEGIN;" else "BEGIN ${mode.name};") transaction.value = Transaction(isSuccessful = false) } diff --git a/sqllin-driver/src/nativeTest/kotlin/com/ctrip/sqllin/driver/test/NativeTest.kt b/sqllin-driver/src/nativeTest/kotlin/com/ctrip/sqllin/driver/test/NativeTest.kt index bcceb6f3..2ab0bc0b 100644 --- a/sqllin-driver/src/nativeTest/kotlin/com/ctrip/sqllin/driver/test/NativeTest.kt +++ b/sqllin-driver/src/nativeTest/kotlin/com/ctrip/sqllin/driver/test/NativeTest.kt @@ -62,9 +62,18 @@ class NativeTest { @Test fun testImmediateTransaction() = commonTest.testImmediateTransaction() + @Test + fun testTransactionModes() = commonTest.testTransactionModes(isDeferredSupported = true) + + @Test + fun testJournalMode() = commonTest.testJournalMode() + @Test fun testBusyTimeout() = commonTest.testBusyTimeout() + @Test + fun testConnectionPragmas() = commonTest.testConnectionPragmas() + @Test fun testConcurrency() = commonTest.testConcurrency() diff --git a/sqllin-dsl-paging/build.gradle.kts b/sqllin-dsl-paging/build.gradle.kts new file mode 100644 index 00000000..a3e28be1 --- /dev/null +++ b/sqllin-dsl-paging/build.gradle.kts @@ -0,0 +1,117 @@ +import org.jetbrains.kotlin.gradle.dsl.JvmTarget +import org.jetbrains.kotlin.konan.target.HostManager + +plugins { + alias(libs.plugins.kotlin.multiplatform) + alias(libs.plugins.android.library) + alias(libs.plugins.vanniktech.maven.publish) +} + +val GROUP_ID = project.property("GROUP_ID") as String +val VERSION = project.property("VERSION") as String + +group = GROUP_ID +version = VERSION + +kotlin { + explicitApi() + jvmToolchain(libs.versions.jvm.toolchain.get().toInt()) + android { + namespace = "com.ctrip.sqllin.dsl.paging" + compileSdk = libs.versions.android.sdk.compile.get().toInt() + minSdk = libs.versions.android.sdk.min.get().toInt() + } + + jvm { + compilerOptions.jvmTarget.set(JvmTarget.JVM_11) + } + + iosArm64() + iosSimulatorArm64() + + macosArm64() + + watchosArm32() + watchosArm64() + watchosSimulatorArm64() + watchosDeviceArm64() + + tvosArm64() + tvosSimulatorArm64() + + linuxX64() + linuxArm64() + + mingwX64() + + sourceSets { + all { + languageSettings { + optIn("kotlin.RequiresOptIn") + } + } + commonMain.dependencies { + api(project(":sqllin-dsl")) + // The PagingSource it provides is androidx.paging's + api(libs.androidx.paging.common) + } + } +} + +gradle.taskGraph.whenReady { + if (!project.hasProperty("onCICD")) + return@whenReady + tasks.forEach { + when { + it.name.contains("linux", true) -> it.enabled = HostManager.hostIsLinux + it.name.contains("mingw", true) -> it.enabled = HostManager.hostIsMingw + it.name.contains("ios", true) + || it.name.contains("macos", true) + || it.name.contains("watchos", true) + || it.name.contains("tvos", true) -> it.enabled = HostManager.hostIsMac + } + } +} + +mavenPublishing { + publishToMavenCentral() + signAllPublications() + + val artifactId = "sqllin-dsl-paging" + coordinates( + groupId = GROUP_ID, + artifactId = artifactId, + version = VERSION, + ) + + pom { + name.set(artifactId) + description.set("androidx.paging's PagingSource for the queries of SQLlin's DSL on Kotlin Multiplatform") + val githubURL = project.property("githubURL") as String + url.set(githubURL) + licenses { + license { + val licenseName = project.property("licenseName") as String + name.set(licenseName) + val licenseURL = project.property("licenseURL") as String + url.set(licenseURL) + } + } + developers { + developer { + val developerID = project.property("developerID") as String + id.set(developerID) + val developerName = project.property("developerName") as String + name.set(developerName) + val developerEmail = project.property("developerEmail") as String + email.set(developerEmail) + } + } + scm { + url.set(githubURL) + val scmURL = project.property("scmURL") as String + connection.set(scmURL) + developerConnection.set(scmURL) + } + } +} diff --git a/sqllin-dsl-paging/src/androidMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.android.kt b/sqllin-dsl-paging/src/androidMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.android.kt new file mode 100644 index 00000000..5bcf9994 --- /dev/null +++ b/sqllin-dsl-paging/src/androidMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.android.kt @@ -0,0 +1,24 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.paging + +import java.lang.ref.WeakReference + +internal actual fun weakReference(referent: T): () -> T? { + val reference = WeakReference(referent) + return { reference.get() } +} diff --git a/sqllin-dsl-paging/src/commonMain/kotlin/com/ctrip/sqllin/dsl/paging/LimitOffsetPagingSource.kt b/sqllin-dsl-paging/src/commonMain/kotlin/com/ctrip/sqllin/dsl/paging/LimitOffsetPagingSource.kt new file mode 100644 index 00000000..8ecf0731 --- /dev/null +++ b/sqllin-dsl-paging/src/commonMain/kotlin/com/ctrip/sqllin/dsl/paging/LimitOffsetPagingSource.kt @@ -0,0 +1,213 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.paging + +import androidx.paging.PagingSource +import androidx.paging.PagingState +import com.ctrip.sqllin.dsl.Database +import com.ctrip.sqllin.dsl.DatabaseScope +import com.ctrip.sqllin.dsl.TableVersions +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import com.ctrip.sqllin.dsl.annotation.InternalSQLlinAPI +import com.ctrip.sqllin.dsl.isStale +import com.ctrip.sqllin.dsl.loadPage +import com.ctrip.sqllin.dsl.sql.statement.SelectStatement +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.IO +import kotlinx.coroutines.withContext +import kotlin.concurrent.Volatile +import kotlin.coroutines.CoroutineContext + +/** + * Creates a [PagingSource] of the rows of the SELECT that [query] builds, which loads them a page at a time, by their + * offsets, as Room's `LimitOffsetPagingSource` does, and invalidates itself when a statement run through this database + * changes a table the SELECT reads, so that its `Pager` loads them again: + * ```kotlin + * val persons: Flow> = Pager(PagingConfig(pageSize = 20)) { + * database.pagingSource { PersonTable SELECT ORDER_BY(PersonTable.id to ASC) } + * }.flow + * ``` + * + * A page is `SELECT * FROM (select) LIMIT ... OFFSET ...`, so [query] can build any SELECT, with WHERE, a join or a + * compound SELECT, which should have an ORDER BY that orders all of its rows, as SQLite returns them in no order + * otherwise, so that the rows of two pages could be the same. [query] runs again to build it for each page, and should + * only build it. The first page also counts the rows, so that the pages tell how many rows are before and after them, + * which placeholders show, and a refresh past the last row loads the last ones. + * + * Its changes are seen as [Database.versioned] sees them: those made through this database, but not those of another + * database instance, connection or process. A change after the first page invalidates the source, and a page that + * reads rows changed since the first one is `LoadResult.Invalid`, so that no list mixes rows from before and after a + * change; the source is invalid once it returns one, whoever loads it. The source registers for the changes weakly, so that a source that its `Pager` drops without invalidating it + * can still be garbage collected. + * + * @param context The context the pages are loaded in, as a `Pager` may load them on the main thread + * @param query Builds the SELECT to page + * @return A source of the rows of the SELECT, keyed by their offsets + */ +@ExperimentalDSLDatabaseAPI +public fun Database.pagingSource( + context: CoroutineContext = Dispatchers.IO, + query: DatabaseScope.() -> SelectStatement, +): PagingSource = LimitOffsetPagingSource(this, context, query) + +/** + * The [PagingSource] that [pagingSource] creates. + * + * Its keys are offsets, the borders between pages, as Room's are: a refresh loads the rows from its key on, an append + * those from its key on, and a prepend those just before its key, at most as many as there are, so that two pages + * never share a row, wherever a refresh starts. A page after the first row has a key to prepend from, so that the rows + * above a refresh in the middle of the list can be loaded, as after a `RemoteMediator` invalidates the source. + * + * @author Yuang Qiao + */ +@OptIn(ExperimentalDSLDatabaseAPI::class, InternalSQLlinAPI::class) +internal class LimitOffsetPagingSource( + private val database: Database, + private val context: CoroutineContext, + private val query: DatabaseScope.() -> SelectStatement, +) : PagingSource() { + + /** + * The token of the first page, which a change invalidates the source by, or null before it is loaded. + */ + @Volatile + private var firstVersions: TableVersions? = null + + /** + * The number of the rows of the SELECT, which the first page counts, and the others are placed in. + */ + @Volatile + private var rowCount = 0 + + /** + * The registration that invalidates the source once a table of the first page changes. + */ + @Volatile + private var registration: AutoCloseable? = null + + init { + // So that an invalidation from elsewhere, as a refresh, doesn't leave the registration to the next change + registerInvalidatedCallback { registration?.close() } + } + + override val jumpingSupported: Boolean + get() = true + + /** + * Returns the key of a refresh around the last position read, as Room does: half the initial load before it, so + * that the rows around it load at once. With placeholders, the position counts the rows before the first page, and + * without them it doesn't, so that the first page's offset is added to it. + */ + override fun getRefreshKey(state: PagingState): Int? { + val anchor = state.anchorPosition ?: return null + val position = if (state.config.enablePlaceholders) { + anchor + } else { + val itemsBefore = state.pages.firstOrNull()?.itemsBefore ?: 0 + anchor + if (itemsBefore == LoadResult.Page.COUNT_UNDEFINED) 0 else itemsBefore + } + return maxOf(0, position - state.config.initialLoadSize / 2) + } + + override suspend fun load(params: LoadParams): LoadResult = withContext(context) { + // Invalidated before it loads, as by a refresh: there is nothing to read + if (invalid) + return@withContext LoadResult.Invalid() + val key = params.key ?: 0 + val first = firstVersions + val result = if (first == null) { + loadFirst(key, params.loadSize) + } else { + val (offset, limit) = when (params) { + // At most as many rows as there are before the key, so that the page ends where the next begins + is LoadParams.Prepend -> maxOf(0, key - params.loadSize) to minOf(key, params.loadSize) + else -> key to params.loadSize + } + val loaded = database.loadPage(offset, limit, countRows = false, query) + // The rows changed since the first page, which has already invalidated the source, or will once the scope + // that changed them ends: they don't belong with the pages already loaded + if (first.isStale) + invalidated() + else + page(loaded.rows, offset, limit) + } + if (invalid) LoadResult.Invalid() else result + } + + /** + * Loads the first page, from [key] on, with the count of the rows, and registers for the changes of its tables. + * A key past the last row, as after rows are deleted, loads the last rows instead. + */ + private suspend fun loadFirst(key: Int, loadSize: Int): LoadResult { + var loaded = database.loadPage(key, loadSize, countRows = true, query) + val count = loaded.rowCount ?: 0 + var versions = loaded.versions + var offset = key + if (key > 0 && key >= count) { + offset = maxOf(0, count - loadSize) + loaded = database.loadPage(offset, loadSize, countRows = false, query) + // The token of both reads, which a change between them makes stale + versions += loaded.versions + } + rowCount = count + firstVersions = versions + // A change since the reads registers nothing, and makes them stale + val registration = database.onChange(versions, invalidator(this)) ?: return invalidated() + this.registration = registration + // An invalidation while the page loaded ran the callback that closes the registration before it was set + if (invalid) + registration.close() + return page(loaded.rows, offset, loadSize) + } + + /** + * Invalidates the source, which it may already be, and returns the result that says so. The source returns + * `LoadResult.Invalid` for a change that no callback has invalidated it for yet through here, so that it is invalid + * once it returns one, whoever loads it: a `Pager` invalidates a source that returns one, but a `TestPager`, or a + * caller of [load], doesn't. + */ + private fun invalidated(): LoadResult { + invalidate() + return LoadResult.Invalid() + } + + /** + * The page of [rows] read from [offset], at most [limit] of them, placed among the [rowCount] rows of the SELECT. + */ + private fun page(rows: List, offset: Int, limit: Int): LoadResult.Page { + val next = offset + rows.size + return LoadResult.Page( + data = rows, + prevKey = if (offset <= 0 || rows.isEmpty()) null else offset, + nextKey = if (rows.isEmpty() || rows.size < limit || next >= rowCount) null else next, + itemsBefore = offset, + itemsAfter = maxOf(0, rowCount - next), + ) + } + + private companion object { + + /** + * The callback that invalidates [source], which only holds it weakly, as the database's registration holds the + * callback until a change runs it: a source that its `Pager` drops can be collected before then. + */ + fun invalidator(source: PagingSource<*, *>): () -> Unit { + val reference = weakReference(source) + return { reference()?.invalidate() } + } + } +} diff --git a/sqllin-dsl-paging/src/commonMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.kt b/sqllin-dsl-paging/src/commonMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.kt new file mode 100644 index 00000000..d4f06beb --- /dev/null +++ b/sqllin-dsl-paging/src/commonMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.kt @@ -0,0 +1,23 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.paging + +/** + * Returns what reads [referent] as long as something else holds it, and null once the garbage collector has collected + * it, so that what holds the returned function doesn't keep [referent] from being collected. + */ +internal expect fun weakReference(referent: T): () -> T? diff --git a/sqllin-dsl-paging/src/jvmMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.jvm.kt b/sqllin-dsl-paging/src/jvmMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.jvm.kt new file mode 100644 index 00000000..5bcf9994 --- /dev/null +++ b/sqllin-dsl-paging/src/jvmMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.jvm.kt @@ -0,0 +1,24 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.paging + +import java.lang.ref.WeakReference + +internal actual fun weakReference(referent: T): () -> T? { + val reference = WeakReference(referent) + return { reference.get() } +} diff --git a/sqllin-dsl-paging/src/nativeMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.native.kt b/sqllin-dsl-paging/src/nativeMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.native.kt new file mode 100644 index 00000000..75116f1e --- /dev/null +++ b/sqllin-dsl-paging/src/nativeMain/kotlin/com/ctrip/sqllin/dsl/paging/WeakReference.native.kt @@ -0,0 +1,26 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.paging + +import kotlin.experimental.ExperimentalNativeApi +import kotlin.native.ref.WeakReference + +@OptIn(ExperimentalNativeApi::class) +internal actual fun weakReference(referent: T): () -> T? { + val reference = WeakReference(referent) + return { reference.get() } +} diff --git a/sqllin-dsl-test/build.gradle.kts b/sqllin-dsl-test/build.gradle.kts index 7eb4e64c..0b99e3d3 100644 --- a/sqllin-dsl-test/build.gradle.kts +++ b/sqllin-dsl-test/build.gradle.kts @@ -61,10 +61,12 @@ kotlin { kotlin.srcDir("build/generated/ksp/metadata/commonMain/kotlin") dependencies { implementation(project(":sqllin-dsl")) + implementation(project(":sqllin-dsl-paging")) implementation(libs.kotlinx.serialization) implementation(libs.kotlinx.coroutines.core) implementation(kotlin("test")) implementation(libs.kotlinx.coroutines.test) + implementation(libs.androidx.paging.testing) } } getByName("androidHostTest").dependencies { diff --git a/sqllin-dsl-test/src/androidHostTest/kotlin/com/ctrip/sqllin/dsl/test/AndroidTest.kt b/sqllin-dsl-test/src/androidHostTest/kotlin/com/ctrip/sqllin/dsl/test/AndroidTest.kt index 4b08ce55..1a32b8aa 100644 --- a/sqllin-dsl-test/src/androidHostTest/kotlin/com/ctrip/sqllin/dsl/test/AndroidTest.kt +++ b/sqllin-dsl-test/src/androidHostTest/kotlin/com/ctrip/sqllin/dsl/test/AndroidTest.kt @@ -23,6 +23,8 @@ class AndroidTest { private val context = ApplicationProvider.getApplicationContext() private val commonTest = CommonBasicTest(context.toDatabasePath()) + private val pagingTest = CommonPagingTest(context.toDatabasePath()) + private val convertedTest = CommonConvertedTest(context.toDatabasePath()) @Test fun testInsert() = commonTest.testInsert() @@ -48,15 +50,18 @@ class AndroidTest { @Test fun testGroupByAndHavingClause() = commonTest.testGroupByAndHavingClause() - @Test - fun testUnionSelect() = commonTest.testUnionSelect() - @Test fun testCompoundSelect() = commonTest.testCompoundSelect() @Test fun testObserve() = commonTest.testObserve() + @Test + fun testTableVersions() = commonTest.testTableVersions() + + @Test + fun testUnreadSelect() = commonTest.testUnreadSelect() + @Test fun testObserveRestoresTracking() = commonTest.testObserveRestoresTracking() @@ -174,11 +179,35 @@ class AndroidTest { @Test fun testConflictClauses() = commonTest.testConflictClauses() + @Test + fun testConflictResolutions() = commonTest.testConflictResolutions() + + @Test + fun testTransactionModes() = commonTest.testTransactionModes() + + @Test + fun testNestedTransaction() = commonTest.testNestedTransaction() + + @Test + fun testIndexedBy() = commonTest.testIndexedBy() + + @Test + fun testExplainQueryPlan() = commonTest.testExplainQueryPlan() + + @Test + fun testClauseOnEarlierStatement() = commonTest.testClauseOnEarlierStatement() + + @Test + fun testPragmas() = commonTest.testPragmas() + + @Test + fun testMorePragmas() = commonTest.testMorePragmas() + @Test fun testFunction() = commonTest.testFunction() @Test - fun testJoinClause() = commonTest.testJoinClause() + fun testJoinWithoutFrom() = commonTest.testJoinWithoutFrom() @Test fun testConcurrency() = commonTest.testConcurrency() @@ -249,6 +278,45 @@ class AndroidTest { @Test fun testCollateNoCaseConstraint() = commonTest.testCollateNoCaseConstraint() + @Test + fun testCollations() = commonTest.testCollations() + + @Test + fun testUpdateDeleteOrderByLimit() = commonTest.testUpdateDeleteOrderByLimit() + + @Test + fun testPagingSourceLoads() = pagingTest.testPagingSourceLoads() + + @Test + fun testPagingSourceRefreshKey() = pagingTest.testPagingSourceRefreshKey() + + @Test + fun testPagingSourceInvalidation() = pagingTest.testPagingSourceInvalidation() + + @Test + fun testPagingSourceQueries() = pagingTest.testPagingSourceQueries() + + @Test + fun testPagingSourceWithPager() = pagingTest.testPagingSourceWithPager() + + @Test + fun testConvertedConditions() = convertedTest.testConvertedConditions() + + @Test + fun testConvertedStatements() = convertedTest.testConvertedStatements() + + @Test + fun testConvertedEnums() = convertedTest.testConvertedEnums() + + @Test + fun testConvertedSchema() = convertedTest.testConvertedSchema() + + @Test + fun testConvertedOptIn() = convertedTest.testConvertedOptIn() + + @Test + fun testConvertedErrors() = convertedTest.testConvertedErrors() + @Test fun testCompositeUniqueConstraint() = commonTest.testCompositeUniqueConstraint() diff --git a/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/CommonBasicTest.kt b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/CommonBasicTest.kt index 2b102775..db635970 100644 --- a/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/CommonBasicTest.kt +++ b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/CommonBasicTest.kt @@ -18,6 +18,7 @@ package com.ctrip.sqllin.dsl.test import com.ctrip.sqllin.driver.DatabaseConfiguration import com.ctrip.sqllin.driver.DatabasePath +import com.ctrip.sqllin.driver.TransactionMode import com.ctrip.sqllin.driver.deleteDatabase import com.ctrip.sqllin.driver.openDatabase import com.ctrip.sqllin.driver.withQuery @@ -28,20 +29,39 @@ import com.ctrip.sqllin.dsl.annotation.AdvancedInsertAPI import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI import com.ctrip.sqllin.dsl.annotation.PlatformDependentSQLiteAPI import com.ctrip.sqllin.dsl.sql.FtsTable +import com.ctrip.sqllin.dsl.sql.INDEXED_BY +import com.ctrip.sqllin.dsl.sql.NOT_INDEXED import com.ctrip.sqllin.dsl.sql.X import com.ctrip.sqllin.dsl.sql.withName import com.ctrip.sqllin.dsl.sql.clause.* import com.ctrip.sqllin.dsl.sql.clause.OrderByWay.ASC import com.ctrip.sqllin.dsl.sql.clause.OrderByWay.DESC +import com.ctrip.sqllin.dsl.sql.pragma.AutoVacuum +import com.ctrip.sqllin.dsl.sql.pragma.CheckpointMode +import com.ctrip.sqllin.dsl.sql.pragma.CheckpointResult +import com.ctrip.sqllin.dsl.sql.pragma.ColumnInfo +import com.ctrip.sqllin.dsl.sql.pragma.ColumnKind +import com.ctrip.sqllin.dsl.sql.pragma.ForeignKeyInfo +import com.ctrip.sqllin.dsl.sql.pragma.ForeignKeyViolation +import com.ctrip.sqllin.dsl.sql.pragma.IndexColumn +import com.ctrip.sqllin.dsl.sql.pragma.IndexInfo +import com.ctrip.sqllin.dsl.sql.pragma.IndexOrigin +import com.ctrip.sqllin.dsl.sql.pragma.RelationInfo +import com.ctrip.sqllin.dsl.sql.statement.PragmaStatement +import com.ctrip.sqllin.dsl.sql.statement.LimitUpdateDeleteStatement +import com.ctrip.sqllin.dsl.sql.statement.QueryPlanStatement +import com.ctrip.sqllin.dsl.sql.statement.UpdateDeleteStatement import com.ctrip.sqllin.dsl.sql.statement.SelectStatement import kotlinx.coroutines.DelicateCoroutinesApi import kotlinx.coroutines.ExperimentalCoroutinesApi +import kotlinx.coroutines.async import kotlinx.coroutines.channels.Channel import kotlinx.coroutines.launch import kotlinx.coroutines.newSingleThreadContext import kotlinx.coroutines.test.runCurrent import kotlinx.coroutines.test.runTest import kotlin.coroutines.EmptyCoroutineContext +import kotlin.test.assertContains import kotlin.test.assertEquals import kotlin.test.assertFails import kotlin.test.assertFailsWith @@ -387,35 +407,6 @@ class CommonBasicTest(private val path: DatabasePath) { assertEquals(true, ungrouped.message!!.contains("without GROUP BY")) } - /** - * Covers the deprecated `UNION {}` block, which keeps working for the table's own rows until it is removed. - */ - @Suppress("DEPRECATION") - fun testUnionSelect() = Database(getDefaultDBConfig(), true).databaseAutoClose { database -> - val book0 = Book(name = "The Da Vinci Code", author = "Dan Brown", pages = 454, price = 16.96) - val book1 = Book(name = "Kotlin Cookbook", author = "Ken Kousen", pages = 251, price = 37.72) - val book2 = Book(name = "The Lost Symbol", author = "Dan Brown", pages = 510, price = 19.95) - val book3 = Book(name = "Kotlin Guide Pratique", author = "Ken Kousen", pages = 398, price = 40.08) - var statement: SelectStatement? = null - database { - statement = BookTable { table -> - table INSERT listOf(book0, book1, book2, book3) - UNION_ALL { - UNION { - table SELECT WHERE (author EQ "Ken Kousen") - table SELECT WHERE (name EQ "Kotlin Cookbook" OR (name EQ "The Da Vinci Code")) - } - table SELECT X - } - } - } - assertEquals(7, statement!!.getResults().size) - assertEquals(2, statement.getResults().count { it == book0 }) - assertEquals(2, statement.getResults().count { it == book1 }) - assertEquals(1, statement.getResults().count { it == book2 }) - assertEquals(2, statement.getResults().count { it == book3 }) - } - fun testFunction() = Database(getDefaultDBConfig(), true).databaseAutoClose { database -> val book0 = Book(name = "The Da Vinci Code", author = "Dan Brown", pages = 454, price = 16.96) val book1 = Book(name = "Kotlin Cookbook", author = "Ken Kousen", pages = 251, price = 37.72) @@ -488,14 +479,19 @@ class CommonBasicTest(private val path: DatabasePath) { assertEquals(3, selectStatement17?.getResults()?.size) // Random ordering, but should return 3 results } - fun testJoinClause() = Database(getDefaultDBConfig(), true).databaseAutoClose { database -> - var crossJoinStatement: SelectStatement? = null - var innerJoinStatement: SelectStatement? = null - var naturalInnerJoinStatement: SelectStatement? = null - var innerJoinStatementWithOn: SelectStatement? = null - var outerJoinStatement: SelectStatement? = null - var naturalOuterJoinStatement: SelectStatement? = null - var outerJoinStatementWithOn: SelectStatement? = null + /** + * Covers the joins that start with their first relation, as `BookTable INNER_JOIN CategoryTable`, without FROM, of + * each kind that every platform has. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class) + fun testJoinWithoutFrom() = Database(getDefaultDBConfig(), true).databaseAutoClose { database -> + lateinit var crossJoinStatement: SelectStatement + lateinit var innerJoinStatement: SelectStatement + lateinit var naturalInnerJoinStatement: SelectStatement + lateinit var innerJoinStatementWithOn: SelectStatement + lateinit var outerJoinStatement: SelectStatement + lateinit var naturalOuterJoinStatement: SelectStatement + lateinit var outerJoinStatementWithOn: SelectStatement val categories = listOf( Category(name = "The Da Vinci Code", code = 123), Category(name = "Kotlin Cookbook", code = 456), @@ -508,27 +504,23 @@ class CommonBasicTest(private val path: DatabasePath) { Book(name = "Modern Java Recipes", author ="Ken Kousen", pages = 322, price = 25.78), ) database { - CategoryTable { table -> - table INSERT categories - } - BookTable { table -> - table INSERT books - crossJoinStatement = table SELECT_DISTINCT CROSS_JOIN(CategoryTable) - innerJoinStatement = table SELECT INNER_JOIN(CategoryTable) USING name - naturalInnerJoinStatement = table SELECT NATURAL_INNER_JOIN(CategoryTable) - innerJoinStatementWithOn = table SELECT INNER_JOIN(CategoryTable) ON (name EQ CategoryTable.name) - outerJoinStatement = table SELECT LEFT_OUTER_JOIN(CategoryTable) USING name - naturalOuterJoinStatement = table SELECT NATURAL_LEFT_OUTER_JOIN(CategoryTable) - outerJoinStatementWithOn = table SELECT LEFT_OUTER_JOIN(CategoryTable) ON (name EQ CategoryTable.name) - } - } - assertEquals(crossJoinStatement?.getResults()?.size, categories.size * books.size) - assertEquals(innerJoinStatement?.getResults()?.size, categories.size) - assertEquals(naturalInnerJoinStatement?.getResults()?.size, categories.size) - assertEquals(innerJoinStatementWithOn?.getResults()?.size, categories.size) - assertEquals(outerJoinStatement?.getResults()?.size, books.size) - assertEquals(naturalOuterJoinStatement?.getResults()?.size, books.size) - assertEquals(outerJoinStatementWithOn?.getResults()?.size, books.size) + CategoryTable INSERT categories + BookTable INSERT books + crossJoinStatement = (BookTable CROSS_JOIN CategoryTable) SELECT_DISTINCT X() + innerJoinStatement = (BookTable INNER_JOIN CategoryTable USING BookTable.name) SELECT X() + naturalInnerJoinStatement = (BookTable NATURAL_JOIN CategoryTable) SELECT X() + innerJoinStatementWithOn = (BookTable INNER_JOIN CategoryTable ON (BookTable.name EQ CategoryTable.name)) SELECT X() + outerJoinStatement = (BookTable LEFT_OUTER_JOIN CategoryTable USING BookTable.name) SELECT X() + naturalOuterJoinStatement = (BookTable NATURAL_LEFT_OUTER_JOIN CategoryTable) SELECT X() + outerJoinStatementWithOn = (BookTable LEFT_OUTER_JOIN CategoryTable ON (BookTable.name EQ CategoryTable.name)) SELECT X() + } + assertEquals(categories.size * books.size, crossJoinStatement.getResults().size) + assertEquals(categories.size, innerJoinStatement.getResults().size) + assertEquals(categories.size, naturalInnerJoinStatement.getResults().size) + assertEquals(categories.size, innerJoinStatementWithOn.getResults().size) + assertEquals(books.size, outerJoinStatement.getResults().size) + assertEquals(books.size, naturalOuterJoinStatement.getResults().size) + assertEquals(books.size, outerJoinStatementWithOn.getResults().size) } /** @@ -548,7 +540,7 @@ class CommonBasicTest(private val path: DatabasePath) { } backgroundScope.launch { database.observe(EmptyCoroutineContext) { - BookTable SELECT INNER_JOIN(CategoryTable) USING BookTable.name + (BookTable INNER_JOIN CategoryTable USING BookTable.name) SELECT X() }.collect { joined.send(it) } } fun assertNoNewBooks() { @@ -602,6 +594,99 @@ class CommonBasicTest(private val path: DatabasePath) { } } + /** + * Covers table version tokens: the token of a read-only scope, which a change to one of its tables makes stale, and + * no other change; awaitChange; onChange, which runs its callback once, after a blocking or a suspended scope, and + * returns null for a token that is already stale, and whose registration can be closed; tokens combined with the + * earlier version of a table; and the rejected writes, and tokens of another database. + */ + @OptIn(ExperimentalCoroutinesApi::class, ExperimentalDSLDatabaseAPI::class) + fun testTableVersions() = Database(getNewAPIDBConfig()).databaseAutoClose { database -> + runTest { + val book = Book(name = "Kotlin Cookbook", author = "Ken Kousen", price = 37.72, pages = 251) + database { BookTable INSERT book } + val (books, booksVersions) = database.versioned { BookTable SELECT X } + assertEquals(listOf(book), books.getResults()) + + // A change to another table leaves the token current, and one to its table makes it stale + val changed = async { database.awaitChange(booksVersions) } + database { CategoryTable INSERT Category(name = "Kotlin Cookbook", code = 1) } + runCurrent() + assertEquals(false, changed.isCompleted) + database { BookTable INSERT book.copy(name = "The Lost Symbol") } + runCurrent() + assertEquals(true, changed.isCompleted) + // and a stale token returns at once + database.awaitChange(booksVersions) + + // onChange runs its callback once, after the scope that changed a table of the token + var calls = 0 + val (_, current) = database.versioned { BookTable SELECT X } + assertNotEquals(null, database.onChange(current) { calls++ }) + database { CategoryTable INSERT Category(name = "Other", code = 2) } + assertEquals(0, calls) + database suspendedScope { BookTable DELETE WHERE(BookTable.name EQ "The Lost Symbol") } + assertEquals(1, calls) + database { BookTable INSERT book.copy(name = "Again") } + assertEquals(1, calls) + + // A token that is already stale registers nothing + val (_, stale) = database.versioned { BookTable SELECT X } + database { BookTable DELETE WHERE(BookTable.name EQ "Again") } + assertEquals(null, database.onChange(stale) { calls++ }) + assertEquals(1, calls) + + // A closed registration doesn't run its callback + val (_, closed) = database.versioned { BookTable SELECT X } + database.onChange(closed) { calls++ }!!.close() + database { BookTable INSERT book.copy(name = "Closed") } + assertEquals(1, calls) + + // A combined token takes the earlier version of a table, and covers the tables of both + val (_, booksBefore) = database.versioned { BookTable SELECT X } + database { BookTable INSERT book.copy(name = "Between") } + val (_, booksAfter) = database.versioned { BookTable SELECT X } + val (_, categories) = database.versioned { CategoryTable SELECT X } + assertEquals(null, database.onChange(booksBefore + booksAfter) { calls++ }) + assertNotEquals(null, database.onChange(booksAfter + categories) { calls++ }) + database { CategoryTable INSERT Category(name = "Combined", code = 3) } + assertEquals(2, calls) + + // A scope that writes isn't run + assertEquals(true, runCatching { database.versioned { BookTable INSERT book.copy(name = "Written") } }.isFailure) + assertEquals(false, database.versioned { BookTable SELECT X }.first.getResults().any { it.name == "Written" }) + + // The tokens of another database can't be combined with these, nor be waited for here + Database(getNewAPIDBConfig()).databaseAutoClose { other -> + val (_, otherVersions) = other.versioned { BookTable SELECT X } + assertFails { booksAfter + otherVersions } + assertFails { database.onChange(otherVersions) { calls++ } } + } + } + } + + /** + * Covers a SELECT whose results are never read: it is read when its scope runs it, so that its statement ends with + * the scope. Left open until its results were read, the statement kept reading its table, which couldn't be dropped + * then, and kept the connection of Kotlin/Native open after the database was closed, as `sqlite3_close_v2` waits for + * the statements, so that Windows couldn't delete the database file. + */ + fun testUnreadSelect() { + val book = Book(name = "Kotlin Cookbook", author = "Ken Kousen", price = 37.72, pages = 251) + lateinit var unread: SelectStatement + Database(getNewAPIDBConfig()).databaseAutoClose { database -> + database { + BookTable INSERT book + unread = BookTable SELECT X + BookTable SELECT WHERE(BookTable.pages GT 0) + } + database { DROP(BookTable) } + } + assertEquals(listOf(book), unread.getResults()) + // Nothing keeps the closed database open + assertEquals(true, deleteDatabase(path, DATABASE_NAME)) + } + /** * Covers the tracker of observed queries creating its TEMP table and triggers again where they are gone, as a * rollback on another thread can take them on the JVM and Kotlin/Native. Removing the row of a table from the TEMP @@ -1024,12 +1109,12 @@ class CommonBasicTest(private val path: DatabasePath) { table SELECT listOf(count(X) AS AuthorBooks::books) WHERE (price GT 10.0) GROUP_BY author } AS AuthorBooksView prolific = authorBooks SELECT WHERE(AuthorBooksView.books GT 1) - personBooks = PersonWithIdTable SELECT INNER_JOIN(authorBooks) ON (PersonWithIdTable.name EQ AuthorBooksView.author) + personBooks = (PersonWithIdTable INNER_JOIN authorBooks ON (PersonWithIdTable.name EQ AuthorBooksView.author)) SELECT X() // The persons under other names join their table with itself val elders = PersonWithIdTable { table -> table SELECT listOf(name AS Elder::elderName, age AS Elder::elderAge) } AS ElderView - pairs = PersonWithIdTable SELECT INNER_JOIN(elders) ON (ElderView.elderAge GT PersonWithIdTable.age) + pairs = (PersonWithIdTable INNER_JOIN elders ON (ElderView.elderAge GT PersonWithIdTable.age)) SELECT X() } assertEquals(listOf(AuthorBooks("Dan Brown", 2)), prolific.getResults()) assertEquals( @@ -1085,7 +1170,7 @@ class CommonBasicTest(private val path: DatabasePath) { backgroundScope.launch { database.observe(EmptyCoroutineContext) { val authorBooks = BookTable { table -> table SELECT listOf(count(X) AS AuthorBooks::books) GROUP_BY author } AS AuthorBooksView - PersonWithIdTable SELECT INNER_JOIN(authorBooks) ON (PersonWithIdTable.name EQ AuthorBooksView.author) + (PersonWithIdTable INNER_JOIN authorBooks ON (PersonWithIdTable.name EQ AuthorBooksView.author)) SELECT X() }.collect { books.send(it) } } backgroundScope.launch { @@ -2115,6 +2200,21 @@ class CommonBasicTest(private val path: DatabasePath) { } } + /** + * Whether the SQLite of the database, which has to exist, is [version], as `3.37.0`, or newer, which a test checks + * to know what to expect of an API that only newer versions support. + */ + private fun sqliteIsAtLeast(version: String): Boolean { + val current = sqliteString("SELECT sqlite_version()")!!.split('.').map { it.toInt() } + val required = version.split('.').map { it.toInt() } + for (i in required.indices) { + val part = current.getOrElse(i) { 0 } + if (part != required[i]) + return part > required[i] + } + return true + } + /** * Whether the SQLite of the database, which has to exist, can run [sql], as it can't use a function it doesn't have. */ @@ -2706,6 +2806,873 @@ class CommonBasicTest(private val path: DatabasePath) { assertEquals(listOf(ConflictPair(a = "k", b = "v", note = "first")), pairs.getResults()) } + /** + * Covers INDEXED BY and NOT INDEXED: a SELECT, a join, UPDATE, UPDATE OR IGNORE and DELETE of a table with them, + * which find the rows they find without them, and fail with an index that doesn't exist, which shows they are in the + * SQL. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class) + fun testIndexedBy() = Database(getNewAPIDBConfig(), true).databaseAutoClose { database -> + fun assertNoSuchIndex(block: () -> Unit) = assertContains(assertFails(block).message.orEmpty(), "no such index") + val books = listOf( + Book(name = "The Da Vinci Code", author = "Dan Brown", price = 16.96, pages = 454), + Book(name = "The Lost Symbol", author = "Dan Brown", price = 19.95, pages = 510), + Book(name = "Kotlin Cookbook", author = "Ken Kousen", price = 37.72, pages = 251), + ) + database { + BookTable.CREATE_INDEX("idx_book_author", BookTable.author) + BookTable INSERT books + CategoryTable INSERT Category(name = "Kotlin Cookbook", code = 1) + } + lateinit var byIndex: SelectStatement + lateinit var withoutIndex: SelectStatement + lateinit var joined: SelectStatement + database { + byIndex = (BookTable INDEXED_BY "idx_book_author") SELECT WHERE(BookTable.author EQ "Dan Brown") + withoutIndex = BookTable.NOT_INDEXED SELECT WHERE(BookTable.author EQ "Dan Brown") + joined = ((BookTable INDEXED_BY "idx_book_author") INNER_JOIN CategoryTable.NOT_INDEXED USING BookTable.name) SELECT WHERE(BookTable.author EQ "Ken Kousen") + } + assertEquals(books.take(2), byIndex.getResults().sortedBy { it.name }) + assertEquals(books.take(2), withoutIndex.getResults().sortedBy { it.name }) + assertEquals(listOf("Kotlin Cookbook"), joined.getResults().map { it.name }) + + database { + BookTable { table -> + (table INDEXED_BY "idx_book_author") UPDATE SET { pages = 1 } WHERE (author EQ "Dan Brown") + table.NOT_INDEXED UPDATE_OR_IGNORE SET { price = 1.0 } WHERE (author EQ "Ken Kousen") + } + (BookTable INDEXED_BY "idx_book_author") DELETE WHERE(BookTable.author EQ "Ken Kousen") + } + lateinit var rest: SelectStatement + database { rest = BookTable SELECT X } + assertEquals(listOf(1, 1), rest.getResults().map { it.pages }) + database { BookTable.NOT_INDEXED DELETE X } + database { rest = BookTable SELECT X } + assertEquals(emptyList(), rest.getResults()) + + assertNoSuchIndex { database { (BookTable INDEXED_BY "no_such_index") SELECT X } } + assertNoSuchIndex { database { BookTable { table -> (table INDEXED_BY "no_such_index") UPDATE SET { pages = 2 } WHERE (author EQ "Dan Brown") } } } + assertNoSuchIndex { database { (BookTable INDEXED_BY "no_such_index") DELETE X } } + } + + /** + * Covers EXPLAIN QUERY PLAN: the plan of a SELECT tells the index it searches, the table it scans and the sort it + * needs, which NOT INDEXED changes, and nests the steps of a compound SELECT; the SELECT itself doesn't run, and its + * parameters are bound. The details are checked by the names and phrases that every SQLite version writes. It runs + * in a transaction and in a versioned read, whose token it adds no table to, and is rejected in a trigger and with + * an incomplete SELECT. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class) + fun testExplainQueryPlan() = Database(getNewAPIDBConfig(), true).databaseAutoClose { database -> + fun List.anyHas(text: String) = any { text in it } + database { + BookTable.CREATE_INDEX("idx_book_author", BookTable.author) + BookTable INSERT Book(name = "The Da Vinci Code", author = "Dan Brown", price = 16.96, pages = 454) + } + lateinit var select: SelectStatement + lateinit var searched: QueryPlanStatement + lateinit var scanned: QueryPlanStatement + lateinit var notIndexed: QueryPlanStatement + lateinit var compound: QueryPlanStatement + database { + select = BookTable SELECT WHERE(BookTable.author EQ "Dan Brown") ORDER_BY (BookTable.price to ASC) + searched = EXPLAIN_QUERY_PLAN(select) + scanned = EXPLAIN_QUERY_PLAN(BookTable SELECT X) + notIndexed = EXPLAIN_QUERY_PLAN(BookTable.NOT_INDEXED SELECT WHERE(BookTable.author EQ "Dan Brown")) + compound = BookTable { table -> + EXPLAIN_QUERY_PLAN((table SELECT WHERE(author EQ "Dan Brown")) UNION (table SELECT WHERE(author EQ "Ken Kousen"))) + } + } + // The SELECT became part of the plan, so it didn't run + assertFailsWith { select.getResults() } + + // The search of the index, and the sort of ORDER BY, which no index gives + val searchedPlan = searched.getResults() + assertEquals(2, searchedPlan.steps.size) + assertEquals(true, searchedPlan.steps[0].detail.startsWith("SEARCH")) + assertContains(searchedPlan.steps[0].detail, "idx_book_author") + assertContains(searchedPlan.steps[1].detail, "TEMP B-TREE") + assertEquals(true, searchedPlan.steps.all { it.children.isEmpty() }) + assertEquals(searchedPlan.steps.map { it.detail }, searchedPlan.details) + assertEquals( + listOf("QUERY PLAN", "|--${searchedPlan.steps[0].detail}", "`--${searchedPlan.steps[1].detail}"), + searchedPlan.toString().lines(), + ) + + // A scan of the table, without WHERE, or with NOT INDEXED + for (plan in listOf(scanned.getResults(), notIndexed.getResults())) { + assertEquals(true, plan.details.any { it.startsWith("SCAN") && "book" in it }, plan.toString()) + assertEquals(false, plan.details.anyHas("idx_book_author"), plan.toString()) + } + + // The steps of each SELECT of a compound are children of the compound's + val compoundPlan = compound.getResults() + assertEquals(true, compoundPlan.steps.any { it.children.isNotEmpty() }, compoundPlan.toString()) + assertEquals(2, compoundPlan.details.count { "idx_book_author" in it }, compoundPlan.toString()) + assertEquals(true, compoundPlan.details.size > compoundPlan.steps.size) + assertEquals(true, compoundPlan.toString().lines().drop(1).any { it.startsWith(" ") || it.startsWith("| ") }) + + // In a transaction, and in a versioned read, which only reads + lateinit var inTransaction: QueryPlanStatement + database { + transaction { + BookTable INSERT Book(name = "The Lost Symbol", author = "Dan Brown", price = 19.95, pages = 510) + inTransaction = EXPLAIN_QUERY_PLAN(BookTable SELECT WHERE(BookTable.author EQ "Dan Brown")) + } + } + assertEquals(true, inTransaction.getResults().details.anyHas("idx_book_author")) + runTest { + val (versioned, versions) = database.versioned { EXPLAIN_QUERY_PLAN(BookTable SELECT X) } + assertEquals(true, versioned.getResults().details.anyHas("book")) + assertEquals("TableVersions()", versions.toString()) + } + + // A trigger can't run it, and an incomplete SELECT can't be planned + val inTrigger = assertFailsWith { + database { + CREATE_TRIGGER("book_inserted") AFTER INSERT ON BookTable BEGIN { + EXPLAIN_QUERY_PLAN(BookTable SELECT X) + } + } + } + assertContains(inTrigger.message.orEmpty(), "EXPLAIN QUERY PLAN") + val ungrouped = assertFailsWith { + database { + BookTable { table -> EXPLAIN_QUERY_PLAN(table SELECT (count(X) AS AuthorBookCount::books)) } + } + } + assertContains(ungrouped.message.orEmpty(), "without GROUP BY") + } + + /** + * Covers a clause appended to a statement built before another one, which replaces that statement rather than the + * last one: a SELECT built since still runs, and an UPDATE's WHERE leaves the other rows, as the UPDATE without it + * no longer runs, in a scope and in a transaction, with parameters in SET or not. A clause can't be appended twice + * to a statement, nor to one that became part of another, which fails before any statement runs. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class) + fun testClauseOnEarlierStatement() = Database(getNewAPIDBConfig(), true).databaseAutoClose { database -> + fun assertNotInScope(block: () -> Unit) = + assertContains(assertFailsWith { block() }.message.orEmpty(), "a clause was already appended") + fun pages(): List { + lateinit var books: SelectStatement + database { books = BookTable SELECT ORDER_BY(BookTable.name to ASC) } + return books.getResults().map { it.pages } + } + database { + BookTable INSERT listOf( + Book(name = "A", author = "Dan Brown", price = 2.0, pages = 1), + Book(name = "B", author = "Ken Kousen", price = 1.0, pages = 1), + ) + CategoryTable INSERT Category(name = "C", code = 1) + } + + // A SELECT built since still runs, and the one the clause completes runs once, with it + for (inTransaction in listOf(false, true)) { + lateinit var unordered: SelectStatement + lateinit var ordered: SelectStatement + lateinit var categories: SelectStatement + fun DatabaseScope.build() { + unordered = BookTable SELECT WHERE(BookTable.pages EQ 1) + categories = CategoryTable SELECT X + ordered = unordered ORDER_BY (BookTable.price to ASC) + } + database { if (inTransaction) transaction { build() } else build() } + assertEquals(listOf("B", "A"), ordered.getResults().map { it.name }) + assertEquals(listOf("C"), categories.getResults().map { it.name }) + assertFailsWith { unordered.getResults() } + } + + // An UPDATE's WHERE leaves the other rows, though a SELECT was built since, as the UPDATE without it doesn't run + lateinit var books: SelectStatement + database { + BookTable { table -> + val update = table UPDATE SET(literal(99) AS Book::pages) + books = table SELECT X + update WHERE (name EQ "A") + } + } + assertEquals(2, books.getResults().size) + assertEquals(listOf(99, 1), pages()) + // With parameters in SET, which the WHERE adds its own to without changing the UPDATE's + database { + BookTable { table -> + val update = table UPDATE SET { pages = 7 } + books = table SELECT X + update WHERE (name EQ "B") + } + } + assertEquals(2, books.getResults().size) + assertEquals(listOf(99, 7), pages()) + + // A clause can't be appended twice to a statement, nor to one that became part of another, and then no + // statement of the scope runs + assertNotInScope { + database { + val base = BookTable SELECT WHERE(BookTable.pages GT 0) + base ORDER_BY (BookTable.price to ASC) + base LIMIT 1 + } + } + assertNotInScope { + database { + BookTable { table -> + val update = table UPDATE SET { pages = 0 } + update WHERE (name EQ "A") + update WHERE (name EQ "B") + } + } + } + assertNotInScope { + database { + val planned = BookTable SELECT WHERE(BookTable.pages GT 0) + EXPLAIN_QUERY_PLAN(planned) + planned ORDER_BY (BookTable.price to ASC) + } + } + assertNotInScope { + database { + BookTable { table -> + val first = table SELECT WHERE(name EQ "A") + first UNION (table SELECT WHERE(name EQ "B")) + first LIMIT 1 + } + } + } + assertEquals(listOf(99, 7), pages()) + } + + /** + * Covers the PRAGMAs that check the database, read its schema, checkpoint the WAL and read the file's size, and + * defer foreign keys: integrity_check and quick_check of a sound database and of one with a row that violates its + * CHECK constraint, foreign_key_check of all tables and of one, table_info of a + * table, a view, a table that doesn't exist and one with default values, index_list of the indexes of CREATE INDEX, + * a partial one, and those of UNIQUE and PRIMARY KEY constraints, index_xinfo of the sort order and the collation of + * index columns, foreign_key_list, wal_checkpoint, which a transaction rejects, page_count, freelist_count, which + * VACUUM empties, and page_size, and defer_foreign_keys, which needs a transaction and fails a commit that leaves a + * violation. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class, AdvancedInsertAPI::class) + fun testPragmas() = Database(getNewAPIDBConfig(), true).databaseAutoClose { database -> + fun orderCount(): Int { + lateinit var orders: SelectStatement + database { orders = FKOrderTable SELECT X } + return orders.getResults().size + } + database { + CREATE(FKUserTable) + CREATE(FKOrderTable) + CREATE(DefaultRowTable) + CREATE(CheckedMembershipTable) + BookTable.CREATE_INDEX("idx_book_author", BookTable.author) + PersonWithIdTable.CREATE_INDEX("idx_person_age_name", PersonWithIdTable.age to DESC, PersonWithIdTable.name to ASC) + PersonWithIdTable.CREATE_UNIQUE_INDEX("idx_person_name", PersonWithIdTable.name) WHERE (PersonWithIdTable.age GT 0) + CollateNoCaseTestTable.CREATE_INDEX("idx_username", CollateNoCaseTestTable.username) + PersonWithIdTable { table -> + CREATE_VIEW(AdultPersonView) AS (table SELECT WHERE(age GTE 18)) + } + } + + // A sound database has no problems + lateinit var integrity: PragmaStatement> + lateinit var quick: PragmaStatement> + database { + integrity = PRAGMA_INTEGRITY_CHECK() + quick = PRAGMA_QUICK_CHECK(maxErrors = 1) + } + assertEquals(emptyList(), integrity.getResults()) + assertEquals(emptyList(), quick.getResults()) + assertFailsWith { database { PRAGMA_INTEGRITY_CHECK(0) } } + + // A row that a connection inserted without checking the CHECK constraints is a problem + val connection = openDatabase(DatabaseConfiguration(name = DATABASE_NAME, path = path, version = 1, create = {})) + try { + connection.execSQL("PRAGMA ignore_check_constraints=1") + connection.execSQL("INSERT INTO CheckedMembership (id, name, age, level, startDate) VALUES (1, 'a', 1, 7, '2026-01-01')") + } finally { + connection.close() + } + database { + integrity = PRAGMA_INTEGRITY_CHECK() + quick = PRAGMA_QUICK_CHECK() + } + assertEquals(1, integrity.getResults().size, integrity.getResults().toString()) + assertContains(integrity.getResults().single(), "CheckedMembership") + assertEquals(integrity.getResults(), quick.getResults()) + + // Foreign keys aren't enforced by default, so an order of a user that doesn't exist is a violation + database { + FKUserTable INSERT FKUser(id = null, email = "a@x", name = "A") + FKOrderTable INSERT FKOrder(id = null, userId = 1L, amount = 1.0, orderDate = "2026-01-01") + FKOrderTable INSERT FKOrder(id = null, userId = 9L, amount = 2.0, orderDate = "2026-01-02") + } + lateinit var violations: PragmaStatement> + lateinit var orderViolations: PragmaStatement> + lateinit var userViolations: PragmaStatement> + database { + violations = PRAGMA_FOREIGN_KEY_CHECK() + orderViolations = PRAGMA_FOREIGN_KEY_CHECK(FKOrderTable) + userViolations = PRAGMA_FOREIGN_KEY_CHECK("fk_user") + } + val violation = ForeignKeyViolation(table = "fk_order", rowid = 2L, parentTable = "fk_user", foreignKeyId = 0) + assertEquals(listOf(violation), violations.getResults()) + assertEquals(listOf(violation), orderViolations.getResults()) + assertEquals(emptyList(), userViolations.getResults()) + database { FKOrderTable DELETE WHERE(FKOrderTable.userId EQ 9L) } + + // The schema: columns, of a table, a view and a table that doesn't exist, indexes, and foreign keys + lateinit var bookColumns: PragmaStatement> + lateinit var bookColumnsByName: PragmaStatement> + lateinit var defaultColumns: PragmaStatement> + lateinit var viewColumns: PragmaStatement> + lateinit var noColumns: PragmaStatement> + lateinit var bookIndexes: PragmaStatement> + lateinit var personIndexes: PragmaStatement> + lateinit var userIndexes: PragmaStatement> + lateinit var enrollmentIndexes: PragmaStatement> + lateinit var ageNameColumns: PragmaStatement> + lateinit var usernameColumns: PragmaStatement> + lateinit var noIndexColumns: PragmaStatement> + lateinit var orderForeignKeys: PragmaStatement> + lateinit var userForeignKeys: PragmaStatement> + database { + bookColumns = PRAGMA_TABLE_INFO(BookTable) + bookColumnsByName = PRAGMA_TABLE_INFO("book") + defaultColumns = PRAGMA_TABLE_INFO(DefaultRowTable) + viewColumns = PRAGMA_TABLE_INFO(AdultPersonView) + noColumns = PRAGMA_TABLE_INFO("no_such_table") + bookIndexes = PRAGMA_INDEX_LIST(BookTable) + personIndexes = PRAGMA_INDEX_LIST(PersonWithIdTable) + userIndexes = PRAGMA_INDEX_LIST(FKUserTable) + enrollmentIndexes = PRAGMA_INDEX_LIST("enrollment") + ageNameColumns = PRAGMA_INDEX_XINFO("idx_person_age_name") + usernameColumns = PRAGMA_INDEX_XINFO("idx_username") + noIndexColumns = PRAGMA_INDEX_XINFO("no_such_index") + orderForeignKeys = PRAGMA_FOREIGN_KEY_LIST(FKOrderTable) + userForeignKeys = PRAGMA_FOREIGN_KEY_LIST("fk_user") + } + assertEquals( + listOf( + ColumnInfo(index = 0, name = "name", type = "TEXT", notNull = true, defaultValue = null, primaryKeyPosition = 0), + ColumnInfo(index = 1, name = "author", type = "TEXT", notNull = true, defaultValue = null, primaryKeyPosition = 0), + ColumnInfo(index = 2, name = "price", type = "DOUBLE", notNull = true, defaultValue = null, primaryKeyPosition = 0), + ColumnInfo(index = 3, name = "pages", type = "INT", notNull = true, defaultValue = null, primaryKeyPosition = 0), + ), + bookColumns.getResults(), + ) + assertEquals(bookColumns.getResults(), bookColumnsByName.getResults()) + assertEquals( + listOf( + ColumnInfo(index = 0, name = "id", type = "INTEGER", notNull = false, defaultValue = null, primaryKeyPosition = 1), + ColumnInfo(index = 1, name = "status", type = "TEXT", notNull = true, defaultValue = "'new'", primaryKeyPosition = 0), + ColumnInfo(index = 2, name = "count", type = "INT", notNull = true, defaultValue = "0", primaryKeyPosition = 0), + ColumnInfo(index = 3, name = "note", type = "TEXT", notNull = false, defaultValue = null, primaryKeyPosition = 0), + ), + defaultColumns.getResults(), + ) + assertEquals(listOf("name", "age"), viewColumns.getResults().map { it.name }) + assertEquals(emptyList(), noColumns.getResults()) + assertEquals(listOf(IndexInfo("idx_book_author", isUnique = false, origin = IndexOrigin.CREATE_INDEX, isPartial = false)), bookIndexes.getResults()) + assertEquals( + listOf( + IndexInfo("idx_person_age_name", isUnique = false, origin = IndexOrigin.CREATE_INDEX, isPartial = false), + IndexInfo("idx_person_name", isUnique = true, origin = IndexOrigin.CREATE_INDEX, isPartial = true), + ), + personIndexes.getResults().sortedBy { it.name }, + ) + assertEquals(listOf(IndexInfo("sqlite_autoindex_fk_user_1", isUnique = true, origin = IndexOrigin.UNIQUE, isPartial = false)), userIndexes.getResults()) + assertEquals(listOf(IndexOrigin.PRIMARY_KEY), enrollmentIndexes.getResults().map { it.origin }) + // Keyed by age, descending, then name, and holding the rowid besides + assertEquals( + listOf(Triple("age", true, true), Triple("name", false, true), Triple(null, false, false)), + ageNameColumns.getResults().map { Triple(it.name, it.isDescending, it.isKey) }, + ) + assertEquals(-1, ageNameColumns.getResults().last().columnIndex) + assertEquals("NOCASE", usernameColumns.getResults().first().collation?.uppercase()) + assertEquals("BINARY", ageNameColumns.getResults().first().collation?.uppercase()) + assertEquals(emptyList(), noIndexColumns.getResults()) + assertEquals( + listOf( + ForeignKeyInfo( + id = 0, position = 0, parentTable = "fk_user", column = "userId", parentColumn = "id", + onUpdate = "NO ACTION", onDelete = "CASCADE", match = "NONE", + ), + ), + orderForeignKeys.getResults(), + ) + assertEquals(emptyList(), userForeignKeys.getResults()) + + // A checkpoint copies all the pages of the WAL, or has none to copy outside WAL mode, and can't run in a + // transaction + lateinit var passive: PragmaStatement + lateinit var truncate: PragmaStatement + database { + passive = PRAGMA_WAL_CHECKPOINT() + truncate = PRAGMA_WAL_CHECKPOINT(CheckpointMode.TRUNCATE) + } + for (result in listOf(passive.getResults(), truncate.getResults())) { + assertEquals(false, result.isBusy, result.toString()) + assertEquals(result.walPages, result.checkpointedPages, result.toString()) + } + assertFailsWith { database { transaction { PRAGMA_WAL_CHECKPOINT() } } } + + // The file's size: deleted rows leave unused pages, which VACUUM removes, unless the database vacuums itself at + // each commit, as Android's SQLite makes a database do by default, auto_vacuum being FULL there + database { BookTable INSERT (1..300).map { Book(name = "x".repeat(500) + it, author = "A", price = 1.0, pages = it) } } + lateinit var pageSize: PragmaStatement + lateinit var pageCount: PragmaStatement + lateinit var freeBefore: PragmaStatement + lateinit var freeAfterDelete: PragmaStatement + lateinit var pageCountAfterDelete: PragmaStatement + lateinit var freeAfterVacuum: PragmaStatement + database { + pageSize = PRAGMA_PAGE_SIZE() + pageCount = PRAGMA_PAGE_COUNT() + freeBefore = PRAGMA_FREELIST_COUNT() + BookTable DELETE X + freeAfterDelete = PRAGMA_FREELIST_COUNT() + pageCountAfterDelete = PRAGMA_PAGE_COUNT() + } + database { + VACUUM() + freeAfterVacuum = PRAGMA_FREELIST_COUNT() + } + assertEquals(true, pageSize.getResults() >= 512 && pageSize.getResults().countOneBits() == 1, pageSize.getResults().toString()) + assertEquals(true, pageCount.getResults() * pageSize.getResults() > 300L * 500, pageCount.getResults().toString()) + val sizes = "pages ${pageCount.getResults()} to ${pageCountAfterDelete.getResults()}, unused ${freeBefore.getResults()} to ${freeAfterDelete.getResults()}" + if (sqliteString("PRAGMA auto_vacuum") == "0") { + assertEquals(true, freeAfterDelete.getResults() > freeBefore.getResults(), sizes) + assertEquals(pageCount.getResults(), pageCountAfterDelete.getResults(), sizes) + } else { + assertEquals(0L, freeAfterDelete.getResults(), sizes) + assertEquals(true, pageCountAfterDelete.getResults() < pageCount.getResults(), sizes) + } + assertEquals(0L, freeAfterVacuum.getResults()) + + // Deferred foreign keys: an order inserted before its user, in a transaction, which a violation left fails + database { PRAGMA_FOREIGN_KEYS(true) } + assertFails { + database { + transaction { + FKOrderTable INSERT FKOrder(id = null, userId = 2L, amount = 3.0, orderDate = "2026-01-03") + FKUserTable INSERT_WITH_ID FKUser(id = 2L, email = "b@x", name = "B") + } + } + } + assertEquals(1, orderCount()) + database { + transaction { + PRAGMA_DEFER_FOREIGN_KEYS(true) + FKOrderTable INSERT FKOrder(id = null, userId = 2L, amount = 3.0, orderDate = "2026-01-03") + FKUserTable INSERT_WITH_ID FKUser(id = 2L, email = "b@x", name = "B") + } + } + assertEquals(2, orderCount()) + assertContains( + assertFails { + database { + transaction { + PRAGMA_DEFER_FOREIGN_KEYS(true) + FKOrderTable INSERT FKOrder(id = null, userId = 99L, amount = 4.0, orderDate = "2026-01-04") + } + } + }.message.orEmpty(), + "FOREIGN KEY constraint failed", + ) + assertEquals(2, orderCount()) + assertFailsWith { database { PRAGMA_DEFER_FOREIGN_KEYS(true) } } + + // PRAGMAs only read, as a versioned read has to + runTest { + val (columns, versions) = database.versioned { PRAGMA_TABLE_INFO(BookTable) } + assertEquals(4, columns.getResults().size) + assertEquals("TableVersions()", versions.toString()) + } + } + + /** + * Covers the second part of the PRAGMAs: reading foreign_keys; recursive_triggers, ignore_check_constraints and + * legacy_alter_table, which apply to the statements whose SQL ran before them too, in a transaction as well; + * integrity_check and quick_check of a table; application_id; auto_vacuum, which VACUUM applies; table_xinfo of + * ordinary, hidden and generated columns; table_list; compile_options, + * collation_list and database_list; and function_list, module_list and pragma_list. Those that only newer versions + * of SQLite have work where the SQLite has them, and fail with a message that tells what they need where it doesn't. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class, PlatformDependentSQLiteAPI::class) + fun testMorePragmas() = Database(getNewAPIDBConfig(), true).databaseAutoClose { database -> + fun read(build: DatabaseScope.() -> PragmaStatement): R = database { build() }.getResults() + fun assertUnsupported(version: String, block: () -> Any?) = + assertContains(assertFailsWith { block() }.message.orEmpty(), version) + database { + CREATE(CheckedMembershipTable) + CREATE(TriggerCounterTable) + CREATE(ArticleTable) + PersonWithIdTable { table -> + CREATE_VIEW(AdultPersonView) AS (table SELECT WHERE(age GTE 18)) + } + PersonWithIdTable INSERT PersonWithId(id = null, name = "Adult", age = 30) + } + + // Reading foreign_keys + assertEquals(false, read { PRAGMA_FOREIGN_KEYS() }) + database { PRAGMA_FOREIGN_KEYS(true) } + assertEquals(true, read { PRAGMA_FOREIGN_KEYS() }) + database { PRAGMA_FOREIGN_KEYS(false) } + assertEquals(false, read { PRAGMA_FOREIGN_KEYS() }) + + // Recursive triggers: a trigger that inserts a row of its own table fires again only with them, for the SQL that + // ran before they were turned on too, and in a transaction, for the statements after it + fun counters(): List { + lateinit var rows: SelectStatement + database { rows = TriggerCounterTable SELECT ORDER_BY(TriggerCounterTable.id to ASC) } + return rows.getResults().map { it.id } + } + database { + CREATE_TRIGGER("counter_chain") AFTER INSERT ON TriggerCounterTable WHEN (new(TriggerCounterTable.count) LT 3) BEGIN { + TriggerCounterTable INSERT listOf( + (new(TriggerCounterTable.id) + 1) AS TriggerCounter::id, + (new(TriggerCounterTable.count) + 1) AS TriggerCounter::count, + ) + } + TriggerCounterTable INSERT TriggerCounter(id = 1, count = 0) + } + assertEquals(listOf(1L, 2L), counters()) + database { PRAGMA_RECURSIVE_TRIGGERS(true) } + database { TriggerCounterTable INSERT TriggerCounter(id = 10, count = 0) } + assertEquals(listOf(1L, 2L, 10L, 11L, 12L, 13L), counters()) + database { + transaction { + PRAGMA_RECURSIVE_TRIGGERS(false) + TriggerCounterTable INSERT TriggerCounter(id = 20, count = 0) + } + } + database { TriggerCounterTable INSERT TriggerCounter(id = 30, count = 0) } + assertEquals(listOf(1L, 2L, 10L, 11L, 12L, 13L, 20L, 21L, 30L, 31L), counters()) + + // Ignoring CHECK constraints, for the SQL that failed before too, which integrity_check finds then + val invalid = CheckedMembership(id = null, name = "a", age = 1, level = 7, startDate = "2026-01-01", endDate = null) + assertContains(assertFails { database { CheckedMembershipTable INSERT invalid } }.message.orEmpty(), "CHECK constraint failed") + database { PRAGMA_IGNORE_CHECK_CONSTRAINTS(true) } + database { CheckedMembershipTable INSERT invalid } + database { PRAGMA_IGNORE_CHECK_CONSTRAINTS(false) } + assertContains(assertFails { database { CheckedMembershipTable INSERT invalid } }.message.orEmpty(), "CHECK constraint failed") + assertEquals(1, read { PRAGMA_INTEGRITY_CHECK() }.size) + + // Checking a table, which an older SQLite can't, so it checks the whole database + if (sqliteIsAtLeast("3.33.0")) { + assertEquals(emptyList(), read { PRAGMA_INTEGRITY_CHECK(BookTable) }) + assertEquals(1, read { PRAGMA_INTEGRITY_CHECK(CheckedMembershipTable) }.size) + assertEquals(emptyList(), read { PRAGMA_QUICK_CHECK("book") }) + assertEquals(1, read { PRAGMA_QUICK_CHECK("CheckedMembership") }.size) + } else { + assertEquals(1, read { PRAGMA_INTEGRITY_CHECK(BookTable) }.size) + } + + // A legacy rename doesn't rewrite the view that reads the table, which then reads a table that doesn't exist + val legacyByDefault = sqliteString("PRAGMA legacy_alter_table") + val renamed = PersonWithIdTable.withName("person_renamed") + fun adults(): List { + lateinit var rows: SelectStatement + database { rows = AdultPersonView SELECT X } + return rows.getResults().map { it.name } + } + database { + PRAGMA_LEGACY_ALTER_TABLE(false) + PersonWithIdTable ALTER_RENAME_TABLE_TO renamed + } + assertEquals(listOf("Adult"), adults(), "legacy_alter_table by default: $legacyByDefault") + database { renamed ALTER_RENAME_TABLE_TO PersonWithIdTable } + database { PRAGMA_LEGACY_ALTER_TABLE(true) } + database { PersonWithIdTable ALTER_RENAME_TABLE_TO renamed } + assertContains(assertFails { adults() }.message.orEmpty(), "no such table") + database { renamed ALTER_RENAME_TABLE_TO PersonWithIdTable } + database { PRAGMA_LEGACY_ALTER_TABLE(legacyByDefault == "1") } + assertEquals(listOf("Adult"), adults()) + println("legacy_alter_table by default: $legacyByDefault") + + // The header of the file + assertEquals(0, read { PRAGMA_APPLICATION_ID() }) + database { PRAGMA_APPLICATION_ID(0x53514C4E) } + assertEquals(0x53514C4E, read { PRAGMA_APPLICATION_ID() }) + + // auto_vacuum, which VACUUM applies: INCREMENTAL keeps the unused pages, which FULL would remove at the commit + assertEquals(sqliteString("PRAGMA auto_vacuum"), read { PRAGMA_AUTO_VACUUM() }.ordinal.toString()) + database { + PRAGMA_AUTO_VACUUM(AutoVacuum.INCREMENTAL) + VACUUM() + } + assertEquals(AutoVacuum.INCREMENTAL, read { PRAGMA_AUTO_VACUUM() }) + database { BookTable INSERT (1..300).map { Book(name = "x".repeat(500) + it, author = "A", price = 1.0, pages = it) } } + database { BookTable DELETE X } + val unused = read { PRAGMA_FREELIST_COUNT() } + assertEquals(true, unused > 0, unused.toString()) + database { + PRAGMA_AUTO_VACUUM(AutoVacuum.NONE) + VACUUM() + } + assertEquals(AutoVacuum.NONE, read { PRAGMA_AUTO_VACUUM() }) + assertEquals(0L, read { PRAGMA_FREELIST_COUNT() }) + + // table_xinfo: ordinary, hidden and generated columns + if (sqliteIsAtLeast("3.26.0")) { + assertEquals(read { PRAGMA_TABLE_INFO(BookTable) }, read { PRAGMA_TABLE_XINFO(BookTable) }) + assertEquals(listOf("name", "age"), read { PRAGMA_TABLE_XINFO(AdultPersonView) }.map { it.name }) + val articleColumns = read { PRAGMA_TABLE_XINFO(ArticleTable) } + assertEquals(listOf("title", "body", "note"), articleColumns.filter { it.kind == ColumnKind.ORDINARY }.map { it.name }) + assertEquals(true, articleColumns.any { it.kind == ColumnKind.HIDDEN && it.name == "articles" }, articleColumns.toString()) + if (sqliteIsAtLeast("3.31.0")) { + val connection = openDatabase(DatabaseConfiguration(name = DATABASE_NAME, path = path, version = 1, create = {})) + try { + connection.execSQL("CREATE TABLE generated_columns(a INT, b INT GENERATED ALWAYS AS (a * 2) VIRTUAL, c INT GENERATED ALWAYS AS (a * 3) STORED)") + } finally { + connection.close() + } + // Read through another Database, whose connection opens after the table exists: on Robolectric API 26, + // the connection of this one doesn't see a table that another connection created + Database(getNewAPIDBConfig()).databaseAutoClose { other -> + lateinit var xinfo: PragmaStatement> + lateinit var info: PragmaStatement> + other { + xinfo = PRAGMA_TABLE_XINFO("generated_columns") + info = PRAGMA_TABLE_INFO("generated_columns") + } + assertEquals(listOf(ColumnKind.ORDINARY, ColumnKind.VIRTUAL_GENERATED, ColumnKind.STORED_GENERATED), xinfo.getResults().map { it.kind }) + assertEquals(listOf("a"), info.getResults().map { it.name }) + } + } + } else { + assertUnsupported("3.26.0") { read { PRAGMA_TABLE_XINFO(BookTable) } } + } + + // table_list: tables, a view, an FTS table and the tables it keeps its data in + if (sqliteIsAtLeast("3.37.0")) { + val relations = read { PRAGMA_TABLE_LIST() } + assertEquals(RelationInfo("main", "book", "table", 4, isWithoutRowid = false, isStrict = false), relations.single { it.name == "book" }) + assertEquals("view", relations.single { it.name == "adult_person" }.type) + assertEquals("virtual", relations.single { it.name == "articles" }.type) + assertEquals(true, relations.any { it.type == "shadow" && it.name.startsWith("articles_") }, relations.toString()) + } else { + assertUnsupported("3.37.0") { read { PRAGMA_TABLE_LIST() } } + } + + // What the SQLite and the connection have. A SQLite can be built without compile_options, as Android's is, which + // then lacks the SQL function sqlite_compileoption_used() too + if (sqliteHas("SELECT sqlite_compileoption_used('THREADSAFE')")) { + val options = read { PRAGMA_COMPILE_OPTIONS() } + assertEquals(true, options.isNotEmpty() && options.none { it.startsWith("SQLITE_") }, options.toString()) + } else { + assertContains(assertFailsWith { read { PRAGMA_COMPILE_OPTIONS() } }.message.orEmpty(), "compile_options") + } + val collations = read { PRAGMA_COLLATION_LIST() } + assertEquals(true, collations.containsAll(listOf("BINARY", "NOCASE", "RTRIM")), collations.toString()) + val databases = read { PRAGMA_DATABASE_LIST() } + assertEquals("main", databases.first().name) + assertEquals(true, databases.first().file.endsWith(DATABASE_NAME), databases.toString()) + if (sqliteIsAtLeast("3.30.0")) { + val lower = read { PRAGMA_FUNCTION_LIST() }.filter { it.name == "lower" } + assertEquals(true, lower.any { it.isBuiltin && it.type == "s" && it.argumentCount == 1 }, lower.toString()) + assertEquals(true, "fts4" in read { PRAGMA_MODULE_LIST() }) + assertEquals(true, "table_info" in read { PRAGMA_PRAGMA_LIST() }) + } else { + assertUnsupported("3.30.0") { read { PRAGMA_FUNCTION_LIST() } } + } + } + + /** + * Covers transactions in each mode, which commit their statements, and roll them back when one fails, and a + * transaction in another one, which joins it. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class) + fun testTransactionModes() = Database(getNewAPIDBConfig(), true).databaseAutoClose { database -> + fun book(name: String) = Book(name = name, author = "Author", price = 1.0, pages = 1) + for (mode in TransactionMode.entries) { + database { + transaction(mode) { + BookTable INSERT book(mode.name) + transaction(TransactionMode.DEFERRED) { + BookTable INSERT book("${mode.name} inner") + } + } + } + assertFails { + database { + transaction(mode) { + BookTable INSERT book("${mode.name} rolled back") + UniqueEmailTestTable INSERT listOf( + UniqueEmailTest(id = null, email = "same@example.com", name = "One"), + UniqueEmailTest(id = null, email = "same@example.com", name = "Two"), + ) + } + } + } + } + lateinit var books: SelectStatement + database { books = BookTable SELECT ORDER_BY(BookTable.name to ASC) } + val expected = TransactionMode.entries.flatMap { listOf(it.name, "${it.name} inner") }.sorted() + assertEquals(expected, books.getResults().map { it.name }) + } + + /** + * Covers transactions in others, which join the outer one rather than end it, with a mode or without: the statements + * after an inner one are still in the outer one, which rolls back all of them when one fails, the second of two + * inner ones joins it too, as after an inner one whose block threw, and so does a nested `beginTransaction()`, which + * returns false and which only the outermost `endTransaction()` ends. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class) + fun testNestedTransaction() = Database(getNewAPIDBConfig(), true).databaseAutoClose { database -> + fun assertConflict(block: () -> Unit) = assertContains(assertFails(block).message.orEmpty(), "constraint failed") + fun emails(): List { + lateinit var rows: SelectStatement + database { rows = UniqueEmailTestTable SELECT ORDER_BY(UniqueEmailTestTable.id to ASC) } + return rows.getResults().map { it.email } + } + fun row(email: String) = UniqueEmailTest(id = null, email = email, name = email) + database { UniqueEmailTestTable INSERT row("a@x") } + + // A statement after an inner transaction is still in the outer one, which rolls back all of them when it fails + assertConflict { + database { + transaction { + UniqueEmailTestTable INSERT row("b@x") + transaction { UniqueEmailTestTable INSERT row("c@x") } + UniqueEmailTestTable INSERT row("a@x") + } + } + } + // Two inner ones with modes, as two functions that each begin one, both join the outer one + assertConflict { + database { + transaction(TransactionMode.EXCLUSIVE) { + transaction(TransactionMode.DEFERRED) { UniqueEmailTestTable INSERT row("b@x") } + transaction(TransactionMode.DEFERRED) { UniqueEmailTestTable INSERT row("c@x") } + UniqueEmailTestTable INSERT row("a@x") + } + } + } + // An inner one whose block threw, which the outer one caught, leaves the outer one collecting statements + assertConflict { + database { + transaction { + runCatching { + transaction { + UniqueEmailTestTable INSERT row("b@x") + error("The inner block fails") + } + } + UniqueEmailTestTable INSERT row("a@x") + } + } + } + // beginTransaction() and endTransaction() nest too + assertConflict { + database { + assertEquals(true, beginTransaction()) + UniqueEmailTestTable INSERT row("b@x") + assertEquals(false, beginTransaction()) + UniqueEmailTestTable INSERT row("c@x") + endTransaction() + UniqueEmailTestTable INSERT row("a@x") + endTransaction() + } + } + assertEquals(listOf("a@x"), emails()) + + // The outer one commits the statements of the inner ones and those after them + database { + transaction { + transaction { UniqueEmailTestTable INSERT row("b@x") } + transaction(TransactionMode.IMMEDIATE) { UniqueEmailTestTable INSERT row("c@x") } + UniqueEmailTestTable INSERT row("d@x") + } + } + assertEquals(listOf("a@x", "b@x", "c@x", "d@x"), emails()) + } + + /** + * Covers the conflict resolutions of a statement, which take the place of those of the constraints: INSERT OR + * ABORT, OR FAIL and OR ROLLBACK, of objects, expressions, DEFAULT VALUES and a SELECT, and UPDATE OR each of the + * five. A failure is checked to be the constraint's, rather than one of the SQL. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class) + fun testConflictResolutions() = Database(getNewAPIDBConfig(), true).databaseAutoClose { database -> + fun assertConflict(block: () -> Unit) = assertContains(assertFails(block).message.orEmpty(), "constraint failed") + fun emails(): List { + lateinit var rows: SelectStatement + database { rows = UniqueEmailTestTable SELECT ORDER_BY(UniqueEmailTestTable.id to ASC) } + return rows.getResults().map { it.email } + } + database { UniqueEmailTestTable INSERT UniqueEmailTest(id = null, email = "a@x", name = "A") } + + // ABORT undoes the whole statement, while FAIL keeps the rows it inserted before the one that conflicts + val rows = listOf(UniqueEmailTest(null, "b@x", "B"), UniqueEmailTest(null, "a@x", "Dup"), UniqueEmailTest(null, "c@x", "C")) + assertConflict { database { UniqueEmailTestTable INSERT_OR_ABORT rows } } + assertEquals(listOf("a@x"), emails()) + assertConflict { database { UniqueEmailTestTable INSERT_OR_FAIL rows } } + assertEquals(listOf("a@x", "b@x"), emails()) + // ROLLBACK rolls back the transaction, with the statements before it + assertConflict { + database { + transaction { + UniqueEmailTestTable INSERT UniqueEmailTest(null, "d@x", "D") + UniqueEmailTestTable INSERT_OR_ROLLBACK UniqueEmailTest(null, "a@x", "Dup") + } + } + } + assertEquals(listOf("a@x", "b@x"), emails()) + + // They take expressions, DEFAULT VALUES and a SELECT as well + val copy = UniqueEmailTestTable.withName("unique_email_copy") + database { + UniqueEmailTestTable INSERT_OR_ABORT listOf(literal("e@x") AS UniqueEmailTest::email, literal("E") AS UniqueEmailTest::name) + UniqueEmailTestTable INSERT_OR_FAIL listOf(literal("f@x") AS UniqueEmailTest::email, literal("F") AS UniqueEmailTest::name) + UniqueEmailTestTable INSERT_OR_ROLLBACK listOf(literal("g@x") AS UniqueEmailTest::email, literal("G") AS UniqueEmailTest::name) + CREATE(DefaultRowTable) + DefaultRowTable INSERT_OR_ABORT DEFAULT_VALUES + DefaultRowTable INSERT_OR_FAIL DEFAULT_VALUES + DefaultRowTable INSERT_OR_ROLLBACK (literal("note") AS DefaultRow::note) + CREATE(copy) + copy INSERT_OR_ABORT (UniqueEmailTestTable SELECT X) + } + assertEquals(listOf("a@x", "b@x", "e@x", "f@x", "g@x"), emails()) + lateinit var defaults: SelectStatement + lateinit var copied: SelectStatement + database { + defaults = DefaultRowTable SELECT X + copied = copy SELECT X + } + assertEquals(listOf(DefaultRow(1, "new", 0, null), DefaultRow(2, "new", 0, null), DefaultRow(3, "new", 0, "note")), defaults.getResults()) + assertEquals(5, copied.getResults().size) + // and fail on a conflict + assertConflict { database { UniqueEmailTestTable INSERT_OR_ABORT listOf(literal("a@x") AS UniqueEmailTest::email, literal("Dup") AS UniqueEmailTest::name) } } + assertConflict { database { copy INSERT_OR_FAIL (UniqueEmailTestTable SELECT X) } } + assertConflict { database { copy INSERT_OR_ROLLBACK (UniqueEmailTestTable SELECT X) } } + + // A statement's resolution takes the place of its constraint's: email is UNIQUE ON CONFLICT IGNORE, and the key + // PRIMARY KEY ON CONFLICT REPLACE + database { + CREATE(ConflictTestTable) + ConflictTestTable INSERT ConflictTest(id = 1, email = "a@x", x = 1, y = 1) + } + assertConflict { database { ConflictTestTable INSERT_OR_ABORT ConflictTest(id = 2, email = "a@x", x = 2, y = 2) } } + assertConflict { database { ConflictTestTable INSERT_OR_FAIL ConflictTest(id = 1, email = "b@x", x = 3, y = 3) } } + database { ConflictTestTable INSERT ConflictTest(id = 2, email = "b@x", x = 2, y = 2) } + // A plain UPDATE to a taken email is skipped, as the constraint says, while UPDATE OR ABORT fails + database { ConflictTestTable { table -> table UPDATE SET { email = "a@x" } WHERE (id EQ 2L) } } + assertConflict { database { ConflictTestTable { table -> table UPDATE_OR_ABORT SET { email = "a@x" } WHERE (id EQ 2L) } } } + lateinit var conflicts: SelectStatement + database { conflicts = ConflictTestTable SELECT ORDER_BY(ConflictTestTable.id to ASC) } + assertEquals(listOf(ConflictTest(1, "a@x", 1, 1), ConflictTest(2, "b@x", 2, 2)), conflicts.getResults()) + + // UPDATE OR IGNORE leaves the row whose new email is taken, OR FAIL and OR ROLLBACK fail, and OR REPLACE deletes + // the row that has it + database { UniqueEmailTestTable { table -> table UPDATE_OR_IGNORE SET { email = "a@x" } WHERE (email EQ "b@x") } } + assertEquals(listOf("a@x", "b@x", "e@x", "f@x", "g@x"), emails()) + assertConflict { database { UniqueEmailTestTable { table -> table UPDATE_OR_FAIL SET { email = "a@x" } WHERE (email EQ "b@x") } } } + assertConflict { database { UniqueEmailTestTable { table -> table UPDATE_OR_ROLLBACK SET { email = "a@x" } WHERE (email EQ "b@x") } } } + database { UniqueEmailTestTable { table -> table UPDATE_OR_REPLACE SET { email = "a@x" } WHERE (email EQ "b@x") } } + assertEquals(listOf("a@x", "e@x", "f@x", "g@x"), emails()) + } + /** * Covers result columns: expressions, such as aggregate functions, selected into properties of a result type with * AS, as in `table SELECT listOf(count(X) AS AuthorStats::books)`, while every other property is read from its @@ -4691,6 +5658,195 @@ class CommonBasicTest(private val path: DatabasePath) { } } + /** + * The collations of columns and of the columns of indexes: `@CollateRTrim` compares a column's values ignoring the + * spaces at their ends, which its UNIQUE constraint does too, while storing them as they are; and the COLLATE + * operator gives a column of an index another collation than the column's, which a query that compares by it uses. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class) + fun testCollations() { + val config = DSLDBConfiguration( + name = DATABASE_NAME, + path = path, + version = 1, + create = { + CREATE(CollateRTrimTestTable) + CREATE(CollateNoCaseTestTable) + } + ) + Database(config, true).databaseAutoClose { database -> + assertContains(CollateRTrimTestTable.createSQL, "code TEXT NOT NULL COLLATE RTRIM UNIQUE") + lateinit var trimmed: SelectStatement + database { + CollateRTrimTestTable { table -> + table INSERT CollateRTrimTest(null, "abc ", "padded") + trimmed = table SELECT WHERE(code EQ "abc") + } + } + assertEquals(listOf("abc "), trimmed.getResults().map { it.code }) + assertFails { + database { + CollateRTrimTestTable INSERT CollateRTrimTest(null, "abc", "unpadded") + } + } + + // An index of a column that has no collation that ignores case, and one of a NOCASE column that doesn't + lateinit var noCaseIndex: PragmaStatement> + lateinit var binaryIndex: PragmaStatement> + lateinit var noCasePlan: QueryPlanStatement + database { + CollateNoCaseTestTable { table -> + table.CREATE_INDEX("idx_description_nocase", description COLLATE NOCASE) + table.CREATE_INDEX("idx_username_binary", (username COLLATE BINARY) to DESC) + noCasePlan = EXPLAIN_QUERY_PLAN(table SELECT WHERE((description COLLATE NOCASE) EQ "first user")) + } + noCaseIndex = PRAGMA_INDEX_XINFO("idx_description_nocase") + binaryIndex = PRAGMA_INDEX_XINFO("idx_username_binary") + } + assertEquals( + listOf(IndexColumn(columnIndex = 3, name = "description", isDescending = false, collation = "NOCASE", isKey = true)), + noCaseIndex.getResults().filter { it.isKey }, + ) + assertEquals( + listOf(IndexColumn(columnIndex = 1, name = "username", isDescending = true, collation = "BINARY", isKey = true)), + binaryIndex.getResults().filter { it.isKey }, + ) + assertContains(noCasePlan.getResults().details.single(), "idx_description_nocase") + } + } + + /** + * ORDER BY, LIMIT and OFFSET of UPDATE and DELETE, which SQLlin writes as the subquery of rowids that SQLite turns + * them into, so that they run on every platform, as on Android, whose SQLite doesn't take them: DELETE with WHERE + * and of every row, UPDATE with WHERE and without, with the parameters of SET before those of WHERE; a negative LIMIT, + * which is none, so that OFFSET keeps the first rows; LIMIT without ORDER BY; INDEXED BY, which only the subquery + * looks the rows up through; a column named `rowid`; a transaction; a trigger, where SQLite's own syntax isn't + * allowed; and ORDER BY without LIMIT, which fails before any statement of the scope runs, or the trigger is created. + */ + @OptIn(ExperimentalDSLDatabaseAPI::class) + fun testUpdateDeleteOrderByLimit() = Database(getNewAPIDBConfig(), true).databaseAutoClose { database -> + fun persons(): List { + lateinit var select: SelectStatement + database { select = PersonWithIdTable SELECT ORDER_BY(PersonWithIdTable.age to ASC) } + return select.getResults() + } + fun ages() = persons().map { it.age } + fun reset() = database { + PersonWithIdTable DELETE X + PersonWithIdTable INSERT (1..6).map { PersonWithId(id = null, name = "p$it", age = it) } + } + + // The two oldest of those older than 1 + reset() + lateinit var oldest: LimitUpdateDeleteStatement + database { + PersonWithIdTable { table -> + oldest = table DELETE WHERE(age GT 1) ORDER_BY (age to DESC) LIMIT 2 + } + } + assertEquals( + "DELETE FROM person_with_id WHERE rowid IN (SELECT rowid FROM person_with_id WHERE person_with_id.age>? ORDER BY person_with_id.age DESC LIMIT 2)", + oldest.sqlStr, + ) + assertEquals(listOf(1, 2, 3, 4), ages()) + + // Every row but the two youngest: no limit, after the first two + database { PersonWithIdTable DELETE X ORDER_BY (PersonWithIdTable.age to ASC) LIMIT -1 OFFSET 2 } + assertEquals(listOf(1, 2), ages()) + + // Without ORDER BY, any three of the four older than 2 + reset() + database { PersonWithIdTable DELETE WHERE(PersonWithIdTable.age GT 2) LIMIT 3 } + assertEquals(listOf(1, 2), ages().take(2)) + assertEquals(3, ages().size) + + // The second youngest, with the parameter of SET and that of WHERE + reset() + lateinit var second: UpdateDeleteStatement + database { + PersonWithIdTable { table -> + second = table UPDATE SET { name = "second" } WHERE (age GT 0) ORDER_BY (age to ASC) LIMIT 1 OFFSET 1 + } + } + assertEquals( + "UPDATE person_with_id SET name=? WHERE rowid IN (SELECT rowid FROM person_with_id WHERE person_with_id.age>? ORDER BY person_with_id.age ASC LIMIT 1 OFFSET 1)", + second.sqlStr, + ) + assertEquals(listOf("p1", "second", "p3", "p4", "p5", "p6"), persons().map { it.name }) + + // Without WHERE, in a transaction + database { + transaction { + PersonWithIdTable { table -> table UPDATE SET { name = "oldest" } ORDER_BY (age to DESC) LIMIT 1 } + } + } + assertEquals("oldest", persons().last().name) + + // INDEXED BY in the subquery only, while the statement finds the rows by their rowids + lateinit var indexed: LimitUpdateDeleteStatement + database { + PersonWithIdTable.CREATE_INDEX("idx_person_with_id_age", PersonWithIdTable.age) + indexed = (PersonWithIdTable INDEXED_BY "idx_person_with_id_age") DELETE WHERE(PersonWithIdTable.age LT 3) ORDER_BY (PersonWithIdTable.age to ASC) LIMIT 1 + } + assertEquals( + "DELETE FROM person_with_id WHERE rowid IN (SELECT rowid FROM person_with_id INDEXED BY idx_person_with_id_age WHERE person_with_id.age + lateinit var namedRows: SelectStatement + database { + CREATE(RowIdNamedTable) + RowIdNamedTable INSERT listOf(RowIdNamed(rowid = 10, name = "b"), RowIdNamed(rowid = 10, name = "a")) + named = RowIdNamedTable DELETE X ORDER_BY (RowIdNamedTable.name to ASC) LIMIT 1 + namedRows = RowIdNamedTable SELECT X + } + assertEquals("DELETE FROM row_id_named WHERE _rowid_ IN (SELECT _rowid_ FROM row_id_named ORDER BY row_id_named.name ASC LIMIT 1)", named.sqlStr) + assertEquals(listOf("b"), namedRows.getResults().map { it.name }) + + // ORDER BY without LIMIT: nothing of the scope runs, in a transaction or not + reset() + assertFailsWith { + database { + PersonWithIdTable INSERT PersonWithId(id = null, name = "p7", age = 7) + PersonWithIdTable DELETE X ORDER_BY (PersonWithIdTable.age to ASC) + } + } + assertFailsWith { + database { + transaction { + PersonWithIdTable INSERT PersonWithId(id = null, name = "p7", age = 7) + PersonWithIdTable { table -> table UPDATE SET { name = "x" } WHERE (age GT 0) ORDER_BY (age to ASC) } + } + } + } + assertEquals(listOf(1, 2, 3, 4, 5, 6), ages()) + + // A trigger that keeps the three latest rows, which SQLite's own syntax can't, and one with ORDER BY without LIMIT + reset() + database { + CREATE_TRIGGER("keep_latest_persons") AFTER INSERT ON PersonWithIdTable BEGIN { + PersonWithIdTable DELETE X ORDER_BY (PersonWithIdTable.id to DESC) LIMIT -1 OFFSET 3 + } + PersonWithIdTable INSERT (7..9).map { PersonWithId(id = null, name = "p$it", age = it) } + } + assertEquals(listOf(7, 8, 9), ages()) + assertFailsWith { + database { + CREATE_TRIGGER("unlimited") AFTER INSERT ON PersonWithIdTable BEGIN { + PersonWithIdTable DELETE X ORDER_BY (PersonWithIdTable.id to DESC) + } + } + } + database { + DROP_TRIGGER("keep_latest_persons") + PersonWithIdTable INSERT PersonWithId(id = null, name = "p10", age = 10) + } + assertEquals(listOf(7, 8, 9, 10), ages()) + } + /** * Test for @CompositeUnique annotation * Verifies multi-column uniqueness constraints with multiple groups diff --git a/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/CommonConvertedTest.kt b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/CommonConvertedTest.kt new file mode 100644 index 00000000..45f55484 --- /dev/null +++ b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/CommonConvertedTest.kt @@ -0,0 +1,375 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.test + +import com.ctrip.sqllin.driver.DatabasePath +import com.ctrip.sqllin.dsl.DSLDBConfiguration +import com.ctrip.sqllin.dsl.Database +import com.ctrip.sqllin.dsl.DatabaseScope +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import com.ctrip.sqllin.dsl.sql.X +import com.ctrip.sqllin.dsl.sql.clause.* +import com.ctrip.sqllin.dsl.sql.clause.OrderByWay.ASC +import com.ctrip.sqllin.dsl.sql.clause.OrderByWay.DESC +import com.ctrip.sqllin.dsl.sql.pragma.ColumnInfo +import com.ctrip.sqllin.dsl.sql.statement.PragmaStatement +import com.ctrip.sqllin.dsl.sql.statement.SelectStatement +import kotlinx.serialization.serializer +import kotlin.test.assertContains +import kotlin.test.assertContentEquals +import kotlin.test.assertEquals +import kotlin.test.assertFailsWith +import kotlin.time.Duration.Companion.minutes +import kotlin.time.Duration.Companion.seconds +import kotlin.time.Instant +import kotlin.uuid.ExperimentalUuidApi +import kotlin.uuid.Uuid + +/** + * The tests of the columns whose serializers convert their values, `ClauseConverted`: their types, their conditions, + * which compare what the serializers store, and SET, which stores what they do. + * + * @author Yuang Qiao + */ +@OptIn(ExperimentalDSLDatabaseAPI::class, ExperimentalUuidApi::class) +class CommonConvertedTest(private val path: DatabasePath) { + + private inline fun withDatabase(noinline create: DatabaseScope.() -> Unit, block: (Database) -> Unit) { + val database = Database(DSLDBConfiguration(name = CommonBasicTest.DATABASE_NAME, path = path, version = 1, create = create)) + try { + block(database) + } finally { + database.close() + } + } + + private val id1 = Uuid.parse("00000000-0000-0000-0000-000000000001") + private val id2 = Uuid.parse("00000000-0000-0000-0000-000000000002") + private val id3 = Uuid.parse("00000000-0000-0000-0000-000000000003") + + private val noon = Instant.parse("2024-01-01T12:00:00Z") + // Half a second later, whose ISO-8601 string, "2024-01-01T12:00:00.500Z", comes before that of noon + private val noonAndAHalf = Instant.parse("2024-01-01T12:00:00.500Z") + private val evening = Instant.parse("2024-01-01T18:00:00Z") + + private fun event(id: Uuid, startsAt: Instant, endsAt: Instant?, score: Int, bonus: Int?, email: String, code: String) = ConvertedEvent( + id = id, + startsAt = startsAt, + endsAt = endsAt, + loggedAt = startsAt, + createdAt = startsAt, + duration = if (bonus == null) null else bonus.minutes, + score = Score(score), + bonus = bonus?.let { Score(it) }, + email = Email(email), + digest = Digest(byteArrayOf(score.toByte(), 0x7F)), + code = code, + ) + + private val events = listOf( + event(id1, noon, evening, score = 1, bonus = 5, email = "a@x.com", code = "abc"), + event(id2, noonAndAHalf, null, score = 2, bonus = null, email = "b@x.com", code = "def"), + event(id3, evening, null, score = 3, bonus = 7, email = "c@x.com", code = "ghi"), + ) + + /** The ids of the events, in their order, which tells the rows apart, as a [Digest] doesn't equal another. */ + private fun SelectStatement.ids() = getResults().map { it.id } + + /** + * The columns' types are those their serializers store, and a row is read back as it was written. Conditions + * compare what the serializers store: of a Uuid primary key, instants stored as numbers, by the serializer of the + * property, and of the type alias of its type, nullable or not; an instant and a duration stored by their built-in + * serializers; value classes, one of them with NOCASE; a value class of bytes; and a String stored reversed, which + * a condition only matches if it reverses the string it compares with. + */ + fun testConvertedConditions() = withDatabase({ CREATE(ConvertedEventTable) }) { database -> + assertEquals( + "CREATE TABLE converted_event(id TEXT PRIMARY KEY NOT NULL,startsAt BIGINT NOT NULL,endsAt BIGINT,loggedAt BIGINT NOT NULL," + + "createdAt TEXT NOT NULL,duration TEXT,score INT NOT NULL,bonus INT,email TEXT NOT NULL COLLATE NOCASE," + + "digest BLOB NOT NULL,code TEXT NOT NULL)", + ConvertedEventTable.createSQL, + ) + lateinit var all: SelectStatement + lateinit var byId: SelectStatement + lateinit var afterNoon: SelectStatement + lateinit var between: SelectStatement + lateinit var byStart: SelectStatement + lateinit var unended: SelectStatement + lateinit var ended: SelectStatement + lateinit var logged: SelectStatement + lateinit var created: SelectStatement + lateinit var lasting: SelectStatement + lateinit var scored: SelectStatement + lateinit var scores: SelectStatement + lateinit var unscored: SelectStatement + lateinit var byEmail: SelectStatement + lateinit var byDigest: SelectStatement + lateinit var byCode: SelectStatement + lateinit var storedCodes: SelectStatement + lateinit var endedAfterStart: SelectStatement + lateinit var loggedAtStart: SelectStatement + lateinit var endedAsStarted: SelectStatement + database { + ConvertedEventTable { table -> + table INSERT events + all = table SELECT X + byId = table SELECT WHERE(id EQ id2) + afterNoon = table SELECT WHERE(startsAt GT noon) ORDER_BY (startsAt to ASC) + between = table SELECT WHERE(startsAt BETWEEN (noonAndAHalf to evening)) ORDER_BY (startsAt to ASC) + byStart = table SELECT ORDER_BY(startsAt to DESC) + unended = table SELECT WHERE(endsAt EQ null) ORDER_BY (startsAt to ASC) + ended = table SELECT WHERE(endsAt NEQ null) + logged = table SELECT WHERE(loggedAt LTE noonAndAHalf) ORDER_BY (loggedAt to ASC) + created = table SELECT WHERE(createdAt EQ noonAndAHalf) + lasting = table SELECT WHERE(duration EQ 7.minutes) + scored = table SELECT WHERE(score GTE Score(2)) ORDER_BY (score to ASC) + scores = table SELECT WHERE(score IN listOf(Score(1), Score(3))) ORDER_BY (score to ASC) + unscored = table SELECT WHERE(bonus EQ null) + byEmail = table SELECT WHERE(email EQ Email("C@X.COM")) + byDigest = table SELECT WHERE(digest EQ Digest(byteArrayOf(2, 0x7F))) + byCode = table SELECT WHERE(code EQ "def") + storedCodes = table SELECT listOf(CAST(code AS TEXT) AS StoredText::value) + endedAfterStart = table SELECT WHERE(endsAt GT startsAt) + loggedAtStart = table SELECT WHERE((loggedAt EQ startsAt) AND (bonus NEQ null)) ORDER_BY (score to ASC) + endedAsStarted = table SELECT WHERE(endsAt IS startsAt) + } + } + // Read back as written, but for the bytes of a Digest, which equal without the Digests equaling + val read = all.getResults() + val noDigest = Digest(ByteArray(0)) + assertEquals(events.map { it.copy(digest = noDigest) }, read.map { it.copy(digest = noDigest) }) + read.zip(events).forEach { (row, event) -> assertContentEquals(event.digest.bytes, row.digest.bytes) } + + assertEquals(listOf(id2), byId.ids()) + // As numbers, half a second after noon is after noon, which as ISO-8601 strings it isn't + assertEquals(listOf(id2, id3), afterNoon.ids()) + assertEquals(listOf(id2, id3), between.ids()) + assertEquals(listOf(id3, id2, id1), byStart.ids()) + assertEquals(listOf(id2, id3), unended.ids()) + assertEquals(listOf(id1), ended.ids()) + assertEquals(listOf(id1, id2), logged.ids()) + assertEquals(listOf(id2), created.ids()) + assertEquals(listOf(id3), lasting.ids()) + assertEquals(listOf(id2, id3), scored.ids()) + assertEquals(listOf(id1, id3), scores.ids()) + assertEquals(listOf(id2), unscored.ids()) + assertEquals(listOf(id3), byEmail.ids()) + assertEquals(listOf(id2), byDigest.ids()) + assertEquals(listOf(id2), byCode.ids()) + assertEquals(listOf("cba", "fed", "ihg"), storedCodes.getResults().map { it.value }.sortedBy { it }) + assertEquals(listOf(id1), endedAfterStart.ids()) + assertEquals(listOf(id1, id3), loggedAtStart.ids()) + assertEquals(emptyList(), endedAsStarted.ids()) + } + + /** + * SET {} stores what the serializers of the columns store, as INSERT does, as does SET of an expression, with a + * literal of a serializer; an UPDATE and a DELETE find their rows by converted columns; `max` and `coalesce` of a + * converted column are of its type; IN compares with the column of a subquery of the same serializer; and a view and + * an index can have converted columns. + */ + fun testConvertedStatements() = withDatabase({ + CREATE(ConvertedEventTable) + CREATE(ConvertedHolidayTable) + }) { database -> + lateinit var updated: SelectStatement + lateinit var storedCode: SelectStatement + lateinit var latest: SelectStatement + lateinit var latestEnd: SelectStatement + lateinit var onHolidays: SelectStatement + lateinit var starts: SelectStatement + lateinit var remaining: SelectStatement + database { + ConvertedEventTable { table -> + table INSERT events + table UPDATE SET { + endsAt = noonAndAHalf + score = Score(9) + bonus = null + code = "xyz" + } WHERE (id EQ id2) + table UPDATE SET(literal(evening, EpochMillisSerializer) AS ConvertedEvent::endsAt) WHERE (id EQ id3) + updated = table SELECT ORDER_BY(score to ASC) + storedCode = table SELECT listOf(CAST(code AS TEXT) AS StoredText::value) + latest = table SELECT listOf(max(startsAt) AS LatestStart::startsAt) + latestEnd = table SELECT listOf(coalesce(endsAt, noon) AS LatestStart::startsAt) ORDER_BY (score to ASC) + table.CREATE_INDEX("idx_converted_event_starts", startsAt) + CREATE_VIEW(ConvertedEventStartView) AS (table SELECT listOf(startsAt AS ConvertedEventStart::startsAt, score AS ConvertedEventStart::score)) + } + ConvertedHolidayTable INSERT listOf(ConvertedHoliday(null, evening), ConvertedHoliday(null, noon)) + ConvertedEventTable { table -> + onHolidays = table SELECT WHERE(startsAt IN (ConvertedHolidayTable SELECT listOf(ConvertedHolidayTable.startsAt AS LatestStart::startsAt))) ORDER_BY (startsAt to ASC) + } + ConvertedEventStartView { view -> + starts = view SELECT WHERE(startsAt GTE noonAndAHalf) ORDER_BY (startsAt to ASC) + } + } + val rows = updated.getResults() + assertEquals(listOf(id1, id3, id2), rows.map { it.id }) + assertEquals(listOf(evening, evening, noonAndAHalf), rows.map { it.endsAt }) + assertEquals(listOf(Score(1), Score(3), Score(9)), rows.map { it.score }) + assertEquals(listOf(Score(5), Score(7), null), rows.map { it.bonus }) + assertEquals("xyz", rows.last().code) + assertEquals(listOf(StoredText("cba"), StoredText("zyx"), StoredText("ihg")).sortedBy { it.value }, storedCode.getResults().sortedBy { it.value }) + assertEquals(listOf(LatestStart(evening)), latest.getResults()) + assertEquals(listOf(evening, evening, noonAndAHalf).map { LatestStart(it) }, latestEnd.getResults()) + assertEquals(listOf(id1, id3), onHolidays.ids()) + assertEquals(listOf(ConvertedEventStart(noonAndAHalf, Score(9)), ConvertedEventStart(evening, Score(3))), starts.getResults()) + + database { + ConvertedEventTable { table -> + table DELETE WHERE((startsAt LT evening) AND (score NEQ Score(9))) + remaining = table SELECT ORDER_BY(startsAt to ASC) + } + } + assertEquals(listOf(id2, id3), remaining.ids()) + } + + /** + * Enums with serializers of their own, given on the enum class or on the property, are stored as those serializers + * store them, by name here, which conditions compare with and SET stores: before 2.6.0, they were compared and set + * as their ordinals, in a column of INT, so that a condition didn't match them, and a row that SET changed couldn't + * be read. An enum with its default serializer, and one serialized contextually, are still stored as ordinals. + */ + fun testConvertedEnums() = withDatabase({ CREATE(NamedEnumRowTable) }) { database -> + lateinit var high: SelectStatement + lateinit var severities: SelectStatement + lateinit var banned: SelectStatement + lateinit var noStatus: SelectStatement + lateinit var ordinal: SelectStatement + lateinit var contextual: SelectStatement + lateinit var storedSeverities: SelectStatement + lateinit var storedContextual: SelectStatement + database { + NamedEnumRowTable { table -> + table INSERT listOf( + NamedEnumRow(null, Severity.LOW, UserStatus.ACTIVE, UserStatus.ACTIVE, UserStatus.SUSPENDED), + NamedEnumRow(null, Severity.HIGH, null, UserStatus.BANNED, UserStatus.ACTIVE), + ) + high = table SELECT WHERE(severity EQ Severity.HIGH) + table UPDATE SET { + severity = Severity.MEDIUM + status = UserStatus.BANNED + } WHERE (severity EQ Severity.LOW) + severities = table SELECT WHERE(severity IN listOf(Severity.MEDIUM, Severity.HIGH)) ORDER_BY (id to ASC) + banned = table SELECT WHERE(status EQ UserStatus.BANNED) + noStatus = table SELECT WHERE(status EQ null) + ordinal = table SELECT WHERE(ordinalStatus GT UserStatus.SUSPENDED) + contextual = table SELECT WHERE(contextualStatus EQ UserStatus.SUSPENDED) + storedSeverities = table SELECT listOf(CAST(severity AS TEXT) AS StoredText::value) ORDER_BY (id to ASC) + storedContextual = table SELECT listOf(CAST(contextualStatus AS BIGINT) AS StoredNumber::value) ORDER_BY (id to ASC) + } + } + assertEquals(listOf(Severity.HIGH), high.getResults().map { it.severity }) + assertEquals( + listOf( + NamedEnumRow(1, Severity.MEDIUM, UserStatus.BANNED, UserStatus.ACTIVE, UserStatus.SUSPENDED), + NamedEnumRow(2, Severity.HIGH, null, UserStatus.BANNED, UserStatus.ACTIVE), + ), + severities.getResults(), + ) + assertEquals(listOf(1L), banned.getResults().map { it.id }) + assertEquals(listOf(2L), noStatus.getResults().map { it.id }) + assertEquals(listOf(2L), ordinal.getResults().map { it.id }) + assertEquals(listOf(1L), contextual.getResults().map { it.id }) + assertEquals(listOf("MEDIUM", "HIGH"), storedSeverities.getResults().map { it.value }) + assertEquals(listOf(UserStatus.SUSPENDED.ordinal.toLong(), UserStatus.ACTIVE.ordinal.toLong()), storedContextual.getResults().map { it.value }) + assertEquals( + "CREATE TABLE named_enum_row(id INTEGER PRIMARY KEY,severity TEXT NOT NULL,status TEXT,ordinalStatus INT NOT NULL,contextualStatus INT NOT NULL)", + NamedEnumRowTable.createSQL, + ) + } + + /** + * The serializer that `@file:UseSerializers` gives a type converts its values, rather than its built-in one; a + * generic type, a `List`, is a column with the serializer of its property; and `ALTER_ADD_COLUMN` adds a converted + * column of the type its serializer stores, where it used to fail for any type but a basic one or an enum. + */ + fun testConvertedSchema() = withDatabase({ + CREATE(ConvertedTimerTable) + CREATE(ConvertedNoteTable) + CREATE(ConvertedEventV1Table) + }) { database -> + assertEquals("CREATE TABLE converted_timer(id INTEGER PRIMARY KEY,timeout BIGINT NOT NULL,delay BIGINT)", ConvertedTimerTable.createSQL) + assertEquals("CREATE TABLE converted_note(id INTEGER PRIMARY KEY,tags TEXT NOT NULL)", ConvertedNoteTable.createSQL) + lateinit var long: SelectStatement + lateinit var storedTimeouts: SelectStatement + lateinit var columns: PragmaStatement> + lateinit var reminded: SelectStatement + lateinit var tagged: SelectStatement + database { + ConvertedNoteTable { table -> + table INSERT listOf(ConvertedNote(null, listOf("a", "b")), ConvertedNote(null, emptyList())) + tagged = table SELECT WHERE(tags EQ listOf("a", "b")) + } + ConvertedTimerTable { table -> + table INSERT listOf(ConvertedTimer(null, 1.minutes, null), ConvertedTimer(null, 10.seconds, 5.seconds)) + long = table SELECT WHERE(timeout GT 30.seconds) + storedTimeouts = table SELECT listOf(CAST(timeout AS BIGINT) AS StoredNumber::value) ORDER_BY (id to ASC) + } + ConvertedEventV1Table INSERT ConvertedEventV1(id1, Score(1)) + ConvertedEventV2Table ALTER_ADD_COLUMN ConvertedEventV2Table.reminder + columns = PRAGMA_TABLE_INFO(ConvertedEventV2Table) + ConvertedEventV2Table { table -> + table INSERT ConvertedEventV2(id2, Score(2), evening) + reminded = table SELECT WHERE(reminder GT noon) + } + } + assertEquals(listOf(ConvertedTimer(1, 1.minutes, null)), long.getResults()) + assertEquals(listOf(ConvertedNote(1, listOf("a", "b"))), tagged.getResults()) + assertEquals(listOf(60L, 10L), storedTimeouts.getResults().map { it.value }) + assertEquals(listOf("id" to "TEXT", "score" to "INT", "reminder" to "BIGINT"), columns.getResults().map { it.name to it.type }) + assertEquals(listOf(ConvertedEventV2(id2, Score(2), evening)), reminded.getResults()) + } + + /** + * The tables of entities that propagate an opt-in requirement, with `@ExperimentalUuidApi` on their classes rather + * than `@OptIn`, opt in to it, as they use the classes, with a converted column or without: they compile, and work. + */ + fun testConvertedOptIn() = withDatabase({ + CREATE(MarkedEventTable) + CREATE(MarkedBasicTable) + }) { database -> + lateinit var event: SelectStatement + lateinit var basic: SelectStatement + database { + MarkedEventTable INSERT listOf(MarkedEvent(id1, Score(1)), MarkedEvent(id2, Score(2))) + MarkedBasicTable INSERT MarkedBasic(null, "basic") + event = MarkedEventTable SELECT WHERE(MarkedEventTable.id EQ id2) + basic = MarkedBasicTable SELECT X + } + assertEquals(listOf(MarkedEvent(id2, Score(2))), event.getResults()) + assertEquals(listOf(MarkedBasic(1, "basic")), basic.getResults()) + } + + /** + * A serializer that encodes a structure fails the CREATE statement of its column, and its conditions, as a column + * holds one value; a collation of a column whose serializer doesn't store text fails its CREATE statement; and an + * element whose serializer isn't the property's fails, as its conditions wouldn't compare what the column holds. + */ + fun testConvertedErrors() { + assertContains(assertFailsWith { StructuredColumnTable.createSQL }.message.orEmpty(), "encodes a structure") + assertContains(assertFailsWith { StructuredColumnTable.point EQ Point(1, 2) }.message.orEmpty(), "encodes a structure") + assertContains(assertFailsWith { CollatedNumberTable.createSQL }.message.orEmpty(), "has the collation NOCASE") + assertContains( + assertFailsWith { + ClauseConverted("startsAt", ConvertedEventTable, false, serializer()) + }.message.orEmpty(), + "is written by the serializer of 'com.ctrip.sqllin.dsl.test.EpochMillis'", + ) + } +} diff --git a/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/CommonPagingTest.kt b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/CommonPagingTest.kt new file mode 100644 index 00000000..531ff1c5 --- /dev/null +++ b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/CommonPagingTest.kt @@ -0,0 +1,270 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.test + +import androidx.paging.Pager +import androidx.paging.PagingConfig +import androidx.paging.PagingSource +import androidx.paging.PagingSource.LoadResult +import androidx.paging.PagingState +import androidx.paging.testing.TestPager +import androidx.paging.testing.asSnapshot +import com.ctrip.sqllin.driver.DatabasePath +import com.ctrip.sqllin.dsl.DSLDBConfiguration +import com.ctrip.sqllin.dsl.Database +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import com.ctrip.sqllin.dsl.paging.pagingSource +import com.ctrip.sqllin.dsl.sql.clause.* +import com.ctrip.sqllin.dsl.sql.clause.OrderByWay.ASC +import com.ctrip.sqllin.dsl.sql.clause.OrderByWay.DESC +import kotlinx.coroutines.test.runTest +import kotlin.test.assertEquals +import kotlin.test.assertIs +import kotlin.test.assertTrue + +/** + * The tests of sqllin-dsl-paging's PagingSource, which load it through androidx.paging's `TestPager` and `Pager`. + * + * @author Yuang Qiao + */ +@OptIn(ExperimentalDSLDatabaseAPI::class) +class CommonPagingTest(private val path: DatabasePath) { + + private fun config(placeholders: Boolean = true) = + PagingConfig(pageSize = 10, initialLoadSize = 20, enablePlaceholders = placeholders) + + /** + * Runs [block] with a database of 100 persons, whose ages are 1 to 100. + */ + private inline fun withPersons(block: (Database) -> Unit) { + val database = Database( + DSLDBConfiguration( + name = CommonBasicTest.DATABASE_NAME, + path = path, + version = 1, + create = { + CREATE(PersonWithIdTable) + CREATE(BookTable) + CREATE(CategoryTable) + }, + ) + ) + try { + database { PersonWithIdTable INSERT (1..100).map { PersonWithId(id = null, name = "p$it", age = it) } } + block(database) + } finally { + database.close() + } + } + + private fun Database.byAge(): PagingSource = + pagingSource { PersonWithIdTable SELECT ORDER_BY(PersonWithIdTable.age to ASC) } + + private fun LoadResult?.ages(): List = assertIs>(this).data.map { it.age } + + /** The keys and the counts of rows around a page, in this order. */ + private fun LoadResult?.placement(): List = + assertIs>(this).run { listOf(prevKey, nextKey, itemsBefore, itemsAfter) } + + /** + * A first page of 20, from the first row, and pages of 10 after it: the first page counts the rows, which places + * every page among them. A refresh in the middle of the rows has a key to prepend from, whose page ends where the + * refresh begins; a prepend near the first row loads only the rows before its key, so that no row is in two pages; + * and a refresh past the last row, as after rows are deleted, loads the last rows. + */ + fun testPagingSourceLoads() = runTest { + withPersons { database -> + val fromStart = TestPager(config(), database.byAge()) + val first = fromStart.refresh() + assertEquals((1..20).toList(), first.ages()) + assertEquals(listOf(null, 20, 0, 80), first.placement()) + val appended = fromStart.append() + assertEquals((21..30).toList(), appended.ages()) + assertEquals(listOf(20, 30, 20, 70), appended.placement()) + + val fromMiddle = TestPager(config(), database.byAge()) + val middle = fromMiddle.refresh(initialKey = 45) + assertEquals((46..65).toList(), middle.ages()) + assertEquals(listOf(45, 65, 45, 35), middle.placement()) + val prepended = fromMiddle.prepend() + assertEquals((36..45).toList(), prepended.ages()) + assertEquals(listOf(35, 45, 35, 55), prepended.placement()) + + val nearStart = TestPager(config(), database.byAge()) + assertEquals((6..25).toList(), nearStart.refresh(initialKey = 5).ages()) + val start = nearStart.prepend() + assertEquals((1..5).toList(), start.ages()) + assertEquals(null, start.placement().first()) + + val atEnd = TestPager(config(), database.byAge()) + val end = atEnd.refresh(initialKey = 95) + assertEquals((96..100).toList(), end.ages()) + assertEquals(listOf(95, null, 95, 0), end.placement()) + + val pastEnd = TestPager(config(), database.byAge()) + val last = pastEnd.refresh(initialKey = 150) + assertEquals((81..100).toList(), last.ages()) + assertEquals(listOf(80, null, 80, 0), last.placement()) + } + } + + /** + * The key of a refresh is half the initial load before the row last read, whether the presented list has + * placeholders, whose positions count the rows before the first page, or not, whose positions don't. + */ + fun testPagingSourceRefreshKey() = runTest { + withPersons { database -> + for (placeholders in listOf(true, false)) { + val source = database.byAge() + val pager = TestPager(config(placeholders), source) + pager.refresh(initialKey = 45) + assertEquals(40, source.getRefreshKey(pager.getPagingState { it.age == 51 }), "placeholders: $placeholders") + assertEquals(37, source.getRefreshKey(pager.getPagingState { it.age == 48 }), "placeholders: $placeholders") + } + val source = database.byAge() + val pager = TestPager(config(), source) + pager.refresh() + assertEquals(0, source.getRefreshKey(pager.getPagingState { it.age == 4 })) + assertEquals(null, source.getRefreshKey(PagingState(emptyList(), null, config(), 0))) + } + } + + /** + * A change of the table the query reads invalidates the source, after its first page, and a change of another + * table doesn't, nor one before the first page, which reads the rows as they are. An invalidated source loads no + * more pages. + */ + fun testPagingSourceInvalidation() = runTest { + withPersons { database -> + val source = database.byAge() + TestPager(config(), source).refresh() + database { CategoryTable INSERT Category(name = "Kotlin Cookbook", code = 1) } + assertEquals(false, source.invalid) + database suspendedScope { PersonWithIdTable DELETE WHERE(PersonWithIdTable.age GT 90) } + assertEquals(true, source.invalid) + assertIs>(source.load(PagingSource.LoadParams.Append(key = 20, loadSize = 10, placeholdersEnabled = true))) + + // Invalidated from elsewhere, as by a refresh, which closes its registration: a change after it is nothing + val refreshed = database.byAge() + TestPager(config(), refreshed).refresh() + refreshed.invalidate() + database { PersonWithIdTable INSERT PersonWithId(id = null, name = "p91", age = 91) } + assertEquals(true, refreshed.invalid) + + val unloaded = database.byAge() + database { PersonWithIdTable DELETE WHERE(PersonWithIdTable.age EQ 91) } + assertEquals(false, unloaded.invalid) + val first = TestPager(config(), unloaded).refresh() + assertEquals(listOf(null, 20, 0, 70), first.placement()) + + // Invalidated before it loads: it builds no SELECT, so it reads nothing + var built = 0 + val preInvalidated = database.pagingSource { + built++ + PersonWithIdTable SELECT ORDER_BY(PersonWithIdTable.age to ASC) + } + preInvalidated.invalidate() + assertIs>(TestPager(config(), preInvalidated).refresh()) + assertEquals(0, built) + + // A change between the two reads of a refresh past the last row makes their token stale, so that the source + // registers nothing, and invalidates itself as it returns LoadResult.Invalid, which a TestPager doesn't do + var reads = 0 + val clamped = database.pagingSource { + if (++reads == 2) + database { PersonWithIdTable INSERT PersonWithId(id = null, name = "p91", age = 91) } + PersonWithIdTable SELECT ORDER_BY(PersonWithIdTable.age to ASC) + } + assertIs>(TestPager(config(), clamped).refresh(initialKey = 150)) + assertEquals(2, reads) + assertEquals(true, clamped.invalid) + + // A change before a later page is read invalidates the source, which then doesn't return that page + var loads = 0 + val changing = database.pagingSource { + if (++loads == 2) + database { PersonWithIdTable DELETE WHERE(PersonWithIdTable.age EQ 91) } + PersonWithIdTable SELECT ORDER_BY(PersonWithIdTable.age to ASC) + } + val changingPager = TestPager(config(), changing) + changingPager.refresh() + assertIs>(changingPager.append()) + assertEquals(true, changing.invalid) + } + } + + /** + * A page is a subquery of any SELECT: one with a WHERE, whose parameters both the page and the count of its rows + * take, an outer join, whose rows have NULL columns, and a compound SELECT with its own ORDER BY. + */ + fun testPagingSourceQueries() = runTest { + withPersons { database -> + val older = TestPager(config(), database.pagingSource { + PersonWithIdTable SELECT WHERE(PersonWithIdTable.age GT 50) ORDER_BY (PersonWithIdTable.age to DESC) + }) + val oldest = older.refresh() + assertEquals((100 downTo 81).toList(), oldest.ages()) + assertEquals(listOf(null, 20, 0, 30), oldest.placement()) + assertEquals((80 downTo 71).toList(), older.append().ages()) + + database { + CategoryTable INSERT Category(name = "Kotlin Cookbook", code = 456) + BookTable INSERT listOf( + Book(name = "Kotlin Cookbook", author = "Ken Kousen", pages = 251, price = 37.72), + Book(name = "Modern Java Recipes", author = "Ken Kousen", pages = 322, price = 25.78), + Book(name = "The Lost Symbol", author = "Dan Brown", pages = 510, price = 19.95), + ) + } + val joined = TestPager(PagingConfig(pageSize = 2, initialLoadSize = 2), database.pagingSource { + (BookTable LEFT_OUTER_JOIN CategoryTable USING BookTable.name) SELECT WHERE(BookTable.pages GT 0) ORDER_BY (BookTable.name to ASC) + }) + val books = assertIs>(joined.refresh()) + assertEquals(listOf("Kotlin Cookbook" to 456, "Modern Java Recipes" to null), books.data.map { it.name to it.code }) + assertEquals(listOf(null, 2, 0, 1), books.placement()) + val rest = assertIs>(joined.append()) + assertEquals(listOf("The Lost Symbol" to null), rest.data.map { it.name to it.code }) + + val extremes = TestPager(config(), database.pagingSource { + ((PersonWithIdTable SELECT WHERE(PersonWithIdTable.age LTE 5)) UNION_ALL (PersonWithIdTable SELECT WHERE(PersonWithIdTable.age GT 95))) ORDER_BY (PersonWithIdTable.age to DESC) + }) + val both = extremes.refresh() + assertEquals(listOf(100, 99, 98, 97, 96, 5, 4, 3, 2, 1), both.ages()) + assertEquals(listOf(null, null, 0, 0), both.placement()) + } + } + + /** + * Through a `Pager`, without placeholders: the pages scrolled through are the rows in order, and a change reloads + * the pages around the position read, with no row twice, nor a deleted one. + */ + fun testPagingSourceWithPager() = runTest { + withPersons { database -> + val pager = Pager(PagingConfig(pageSize = 10, enablePlaceholders = false)) { database.byAge() } + val loaded = pager.flow.asSnapshot { scrollTo(index = 45) } + assertTrue(loaded.size > 45) + assertEquals((1..loaded.size).toList(), loaded.map { it.age }) + + val reloaded = pager.flow.asSnapshot { + scrollTo(index = 45) + database suspendedScope { PersonWithIdTable DELETE WHERE(PersonWithIdTable.age LTE 10) } + } + assertTrue(reloaded.isNotEmpty()) + assertTrue(reloaded.all { it.age > 10 }) + assertEquals(reloaded.sortedBy { it.age }.distinct(), reloaded) + } + } +} diff --git a/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/ConvertedEntities.kt b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/ConvertedEntities.kt new file mode 100644 index 00000000..7ef8ae28 --- /dev/null +++ b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/ConvertedEntities.kt @@ -0,0 +1,243 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +@file:OptIn(ExperimentalUuidApi::class) + +package com.ctrip.sqllin.dsl.test + +import com.ctrip.sqllin.dsl.annotation.CollateNoCase +import com.ctrip.sqllin.dsl.annotation.DBRow +import com.ctrip.sqllin.dsl.annotation.DBView +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import com.ctrip.sqllin.dsl.annotation.PrimaryKey +import kotlinx.serialization.Contextual +import kotlinx.serialization.KSerializer +import kotlinx.serialization.Serializable +import kotlinx.serialization.descriptors.PrimitiveKind +import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor +import kotlinx.serialization.encoding.Decoder +import kotlinx.serialization.encoding.Encoder +import kotlin.jvm.JvmInline +import kotlin.time.Duration +import kotlin.time.Instant +import kotlin.uuid.ExperimentalUuidApi +import kotlin.uuid.Uuid + +/* + * The entities of the columns whose serializers convert their values, which CommonConvertedTest tests. + */ + +/** + * Stores an instant as the number of its milliseconds, which keeps the order of instants, unlike the ISO-8601 string + * of the built-in serializer. + */ +object EpochMillisSerializer : KSerializer { + override val descriptor = PrimitiveSerialDescriptor("com.ctrip.sqllin.dsl.test.EpochMillis", PrimitiveKind.LONG) + override fun serialize(encoder: Encoder, value: Instant) = encoder.encodeLong(value.toEpochMilliseconds()) + override fun deserialize(decoder: Decoder): Instant = Instant.fromEpochMilliseconds(decoder.decodeLong()) +} + +/** + * Stores a string reversed, as a serializer that encodes or encrypts a string stores another one, so that a condition + * only matches if it reverses the string it compares with too. + */ +class ReversedStringSerializer : KSerializer { + override val descriptor = PrimitiveSerialDescriptor("com.ctrip.sqllin.dsl.test.ReversedString", PrimitiveKind.STRING) + override fun serialize(encoder: Encoder, value: String) = encoder.encodeString(value.reversed()) + override fun deserialize(decoder: Decoder): String = decoder.decodeString().reversed() +} + +/** An instant stored as the number of its milliseconds, as the use of its type in this type alias declares. */ +typealias EpochInstant = @Serializable(with = EpochMillisSerializer::class) Instant + +/** A value class of a number, stored as the number. */ +@JvmInline +@Serializable +value class Score(val value: Int) + +/** A value class of a string, stored as the string. */ +@JvmInline +@Serializable +value class Email(val value: String) + +/** A value class of bytes, stored as a BLOB. */ +@JvmInline +@Serializable +value class Digest(val bytes: ByteArray) + +/** + * A row of every kind of converted column: a `Uuid` primary key, stored as its string; instants stored as numbers by a + * serializer given on the property, and on the type alias of the property's type; an instant and a duration stored by + * their built-in serializers, as ISO-8601 strings; value classes, nullable or not, one of them with a collation; and a + * `String` with a serializer of its own. + */ +@Serializable +@DBRow("converted_event") +data class ConvertedEvent( + @PrimaryKey val id: Uuid, + @Serializable(with = EpochMillisSerializer::class) val startsAt: Instant, + @Serializable(with = EpochMillisSerializer::class) val endsAt: Instant?, + val loggedAt: EpochInstant, + val createdAt: Instant, + val duration: Duration?, + val score: Score, + val bonus: Score?, + @CollateNoCase val email: Email, + val digest: Digest, + @Serializable(with = ReversedStringSerializer::class) val code: String, +) + +/** + * The instants of the [ConvertedEvent]s, as a SELECT of them, and the view of them, read. + */ +@OptIn(ExperimentalDSLDatabaseAPI::class) +@DBView("converted_event_start") +@Serializable +data class ConvertedEventStart( + @Serializable(with = EpochMillisSerializer::class) val startsAt: Instant, + val score: Score, +) + +/** + * The latest instant of the [ConvertedEvent]s, which `max` selects, and is NULL without any. + */ +@Serializable +data class LatestStart(@Serializable(with = EpochMillisSerializer::class) val startsAt: Instant?) + +/** + * The instants of another table, which a subquery of [ConvertedEvent]s compares with. + */ +@Serializable +@DBRow("converted_holiday") +data class ConvertedHoliday( + @PrimaryKey val id: Long?, + @Serializable(with = EpochMillisSerializer::class) val startsAt: Instant, +) + +/** + * The severity of a [NamedEnumRow], which the serializer its class declares stores as its name, in a column of text, + * rather than as its ordinal. + */ +@Serializable(with = SeverityByNameSerializer::class) +enum class Severity { LOW, MEDIUM, HIGH } + +object SeverityByNameSerializer : KSerializer { + override val descriptor = PrimitiveSerialDescriptor("com.ctrip.sqllin.dsl.test.SeverityByName", PrimitiveKind.STRING) + override fun serialize(encoder: Encoder, value: Severity) = encoder.encodeString(value.name) + override fun deserialize(decoder: Decoder): Severity = Severity.valueOf(decoder.decodeString()) +} + +/** + * Stores a [UserStatus] by its name, as the serializer given on a property of that enum, which has none of its own. + */ +object UserStatusByNameSerializer : KSerializer { + override val descriptor = PrimitiveSerialDescriptor("com.ctrip.sqllin.dsl.test.UserStatusByName", PrimitiveKind.STRING) + override fun serialize(encoder: Encoder, value: UserStatus) = encoder.encodeString(value.name) + override fun deserialize(decoder: Decoder): UserStatus = UserStatus.valueOf(decoder.decodeString()) +} + +/** + * Enums stored by their names, with the serializer of the enum class and with that of the property, which were stored + * as their names but compared and set as their ordinals before 2.6.0; one stored as its ordinal; and one serialized + * contextually, which SQLlin, without a `SerializersModule`, stores as its ordinal too. + */ +@Serializable +@DBRow("named_enum_row") +data class NamedEnumRow( + @PrimaryKey val id: Long?, + val severity: Severity, + @Serializable(with = UserStatusByNameSerializer::class) val status: UserStatus?, + val ordinalStatus: UserStatus, + @Contextual val contextualStatus: UserStatus, +) + +/** + * Stores a list of tags as one string, the tags separated by commas, as a serializer would store a list as JSON. + */ +object TagsAsTextSerializer : KSerializer> { + override val descriptor = PrimitiveSerialDescriptor("com.ctrip.sqllin.dsl.test.TagsAsText", PrimitiveKind.STRING) + override fun serialize(encoder: Encoder, value: List) = encoder.encodeString(value.joinToString(",")) + override fun deserialize(decoder: Decoder): List = decoder.decodeString().let { if (it.isEmpty()) emptyList() else it.split(',') } +} + +/** + * A list, of a generic type, stored as one string by the serializer of its property. + */ +@Serializable +@DBRow("converted_note") +data class ConvertedNote( + @PrimaryKey val id: Long?, + @Serializable(with = TagsAsTextSerializer::class) val tags: List, +) + +/** A point, which its plugin-generated serializer encodes as a structure. */ +@Serializable +data class Point(val x: Int, val y: Int) + +/** Encodes a [Point] as a structure, which no column can hold, as a serializer given on a property can. */ +object PointAsStructureSerializer : KSerializer by Point.serializer() + +/** + * A column that can't be: a point its serializer encodes as a structure, so that its table can't be created, nor its + * conditions built. + */ +@Serializable +@DBRow("structured_column") +data class StructuredColumn( + @PrimaryKey val id: Long?, + @Serializable(with = PointAsStructureSerializer::class) val point: Point, +) + +/** + * A column that can't be: a collation of a number, which only a column of text can have, so that its table can't be + * created. + */ +@Serializable +@DBRow("collated_number") +data class CollatedNumber( + @PrimaryKey val id: Long?, + @CollateNoCase val score: Score, +) + +/** + * The value of a column as it is stored, as text, read without its serializer. + */ +@Serializable +data class StoredText(val value: String?) + +/** + * The value of a column as it is stored, as a number, read without its serializer. + */ +@Serializable +data class StoredNumber(val value: Long?) + +/** + * The table of [ConvertedEvent]s before a migration that adds its column [ConvertedEventV2.reminder]. + */ +@Serializable +@DBRow("converted_migration") +data class ConvertedEventV1(@PrimaryKey val id: Uuid, val score: Score) + +/** + * The table of [ConvertedEventV1] after the migration, with a converted column added by `ALTER_ADD_COLUMN`. + */ +@Serializable +@DBRow("converted_migration") +data class ConvertedEventV2( + @PrimaryKey val id: Uuid, + val score: Score, + @Serializable(with = EpochMillisSerializer::class) val reminder: Instant?, +) diff --git a/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/Entities.kt b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/Entities.kt index 97564b3f..58f615ad 100644 --- a/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/Entities.kt +++ b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/Entities.kt @@ -18,6 +18,7 @@ package com.ctrip.sqllin.dsl.test import com.ctrip.sqllin.dsl.annotation.Check import com.ctrip.sqllin.dsl.annotation.CollateNoCase +import com.ctrip.sqllin.dsl.annotation.CollateRTrim import com.ctrip.sqllin.dsl.annotation.CompositePrimaryKey import com.ctrip.sqllin.dsl.annotation.CompositeUnique import com.ctrip.sqllin.dsl.annotation.DBRow @@ -239,6 +240,29 @@ data class CollateNoCaseTest( val description: String, ) +/** + * A table with a column named `rowid`, which `rowid` then means in SQL rather than the table's rowid, as the ORDER BY + * and LIMIT of an UPDATE or DELETE have to tell apart. + */ +@DBRow("row_id_named") +@Serializable +data class RowIdNamed( + val rowid: Long, + val name: String, +) + +/** + * Test entity for @CollateRTrim, a column whose values compare ignoring the spaces at their ends. + */ +@OptIn(ExperimentalDSLDatabaseAPI::class) +@DBRow("collate_rtrim_test") +@Serializable +data class CollateRTrimTest( + @PrimaryKey(autoIncrement = true) val id: Long?, + @CollateRTrim @Unique val code: String, + val name: String, +) + /** * Test entity for @CompositeUnique annotation * Tests multi-column uniqueness constraints with groups diff --git a/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/OptInMarkedEntities.kt b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/OptInMarkedEntities.kt new file mode 100644 index 00000000..cfff1ee6 --- /dev/null +++ b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/OptInMarkedEntities.kt @@ -0,0 +1,46 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.test + +import com.ctrip.sqllin.dsl.annotation.DBRow +import com.ctrip.sqllin.dsl.annotation.PrimaryKey +import kotlinx.serialization.Serializable +import kotlin.uuid.ExperimentalUuidApi +import kotlin.uuid.Uuid + +/* + * Entities that propagate an opt-in requirement, rather than opting in with @OptIn, which CommonConvertedTest tests: + * their file opts in to nothing, so that the tables generated for them only compile if they opt in to the markers + * the entities are annotated with. + */ + +/** + * A row of a converted column of an experimental type, `Uuid`, whose class requires the opt-in it needs. + */ +@ExperimentalUuidApi +@Serializable +@DBRow("marked_event") +data class MarkedEvent(@PrimaryKey val id: Uuid, val score: Score) + +/** + * A row of no converted column, whose class requires an opt-in, which the table generated for it, a `Table` of it, + * needs too. + */ +@ExperimentalUuidApi +@Serializable +@DBRow("marked_basic") +data class MarkedBasic(@PrimaryKey val id: Long?, val name: String) diff --git a/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/UseSerializersEntities.kt b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/UseSerializersEntities.kt new file mode 100644 index 00000000..9c64ad38 --- /dev/null +++ b/sqllin-dsl-test/src/commonMain/kotlin/com/ctrip/sqllin/dsl/test/UseSerializersEntities.kt @@ -0,0 +1,56 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +@file:UseSerializers(DurationAsSecondsSerializer::class) + +package com.ctrip.sqllin.dsl.test + +import com.ctrip.sqllin.dsl.annotation.DBRow +import com.ctrip.sqllin.dsl.annotation.PrimaryKey +import kotlinx.serialization.KSerializer +import kotlinx.serialization.Serializable +import kotlinx.serialization.UseSerializers +import kotlinx.serialization.descriptors.PrimitiveKind +import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor +import kotlinx.serialization.encoding.Decoder +import kotlinx.serialization.encoding.Encoder +import kotlin.time.Duration +import kotlin.time.Duration.Companion.seconds + +/* + * An entity whose file gives the serializer of a type, which CommonConvertedTest tests. + */ + +/** + * Stores a duration as its whole seconds, as the serializer of the durations of this file. + */ +object DurationAsSecondsSerializer : KSerializer { + override val descriptor = PrimitiveSerialDescriptor("com.ctrip.sqllin.dsl.test.DurationAsSeconds", PrimitiveKind.LONG) + override fun serialize(encoder: Encoder, value: Duration) = encoder.encodeLong(value.inWholeSeconds) + override fun deserialize(decoder: Decoder): Duration = decoder.decodeLong().seconds +} + +/** + * Durations stored as numbers of seconds, by the serializer that `@file:UseSerializers` gives, not as the ISO-8601 + * strings of their built-in serializer. + */ +@Serializable +@DBRow("converted_timer") +data class ConvertedTimer( + @PrimaryKey val id: Long?, + val timeout: Duration, + val delay: Duration?, +) diff --git a/sqllin-dsl-test/src/jvmTest/kotlin/com/ctrip/sqllin/dsl/test/JvmTest.kt b/sqllin-dsl-test/src/jvmTest/kotlin/com/ctrip/sqllin/dsl/test/JvmTest.kt index aca4facd..5df037c1 100644 --- a/sqllin-dsl-test/src/jvmTest/kotlin/com/ctrip/sqllin/dsl/test/JvmTest.kt +++ b/sqllin-dsl-test/src/jvmTest/kotlin/com/ctrip/sqllin/dsl/test/JvmTest.kt @@ -15,6 +15,8 @@ class JvmTest { private val path = System.getProperty("user.dir").toDatabasePath() private val commonTest = CommonBasicTest(path) + private val pagingTest = CommonPagingTest(path) + private val convertedTest = CommonConvertedTest(path) @Test fun testInsert() = commonTest.testInsert() @@ -40,15 +42,18 @@ class JvmTest { @Test fun testGroupByAndHavingClause() = commonTest.testGroupByAndHavingClause() - @Test - fun testUnionSelect() = commonTest.testUnionSelect() - @Test fun testCompoundSelect() = commonTest.testCompoundSelect() @Test fun testObserve() = commonTest.testObserve() + @Test + fun testTableVersions() = commonTest.testTableVersions() + + @Test + fun testUnreadSelect() = commonTest.testUnreadSelect() + @Test fun testObserveRestoresTracking() = commonTest.testObserveRestoresTracking() @@ -166,11 +171,35 @@ class JvmTest { @Test fun testConflictClauses() = commonTest.testConflictClauses() + @Test + fun testConflictResolutions() = commonTest.testConflictResolutions() + + @Test + fun testTransactionModes() = commonTest.testTransactionModes() + + @Test + fun testNestedTransaction() = commonTest.testNestedTransaction() + + @Test + fun testIndexedBy() = commonTest.testIndexedBy() + + @Test + fun testExplainQueryPlan() = commonTest.testExplainQueryPlan() + + @Test + fun testClauseOnEarlierStatement() = commonTest.testClauseOnEarlierStatement() + + @Test + fun testPragmas() = commonTest.testPragmas() + + @Test + fun testMorePragmas() = commonTest.testMorePragmas() + @Test fun testFunction() = commonTest.testFunction() @Test - fun testJoinClause() = commonTest.testJoinClause() + fun testJoinWithoutFrom() = commonTest.testJoinWithoutFrom() @Test fun testConcurrency() = commonTest.testConcurrency() @@ -241,6 +270,45 @@ class JvmTest { @Test fun testCollateNoCaseConstraint() = commonTest.testCollateNoCaseConstraint() + @Test + fun testCollations() = commonTest.testCollations() + + @Test + fun testUpdateDeleteOrderByLimit() = commonTest.testUpdateDeleteOrderByLimit() + + @Test + fun testPagingSourceLoads() = pagingTest.testPagingSourceLoads() + + @Test + fun testPagingSourceRefreshKey() = pagingTest.testPagingSourceRefreshKey() + + @Test + fun testPagingSourceInvalidation() = pagingTest.testPagingSourceInvalidation() + + @Test + fun testPagingSourceQueries() = pagingTest.testPagingSourceQueries() + + @Test + fun testPagingSourceWithPager() = pagingTest.testPagingSourceWithPager() + + @Test + fun testConvertedConditions() = convertedTest.testConvertedConditions() + + @Test + fun testConvertedStatements() = convertedTest.testConvertedStatements() + + @Test + fun testConvertedEnums() = convertedTest.testConvertedEnums() + + @Test + fun testConvertedSchema() = convertedTest.testConvertedSchema() + + @Test + fun testConvertedOptIn() = convertedTest.testConvertedOptIn() + + @Test + fun testConvertedErrors() = convertedTest.testConvertedErrors() + @Test fun testCompositeUniqueConstraint() = commonTest.testCompositeUniqueConstraint() diff --git a/sqllin-dsl-test/src/nativeTest/kotlin/com/ctrip/sqllin/dsl/test/NativeTest.kt b/sqllin-dsl-test/src/nativeTest/kotlin/com/ctrip/sqllin/dsl/test/NativeTest.kt index 978caf67..d9ba3ce7 100644 --- a/sqllin-dsl-test/src/nativeTest/kotlin/com/ctrip/sqllin/dsl/test/NativeTest.kt +++ b/sqllin-dsl-test/src/nativeTest/kotlin/com/ctrip/sqllin/dsl/test/NativeTest.kt @@ -31,6 +31,8 @@ class NativeTest { private val path = getPlatformStringPath().toDatabasePath() private val commonTest = CommonBasicTest(path) + private val pagingTest = CommonPagingTest(path) + private val convertedTest = CommonConvertedTest(path) @Test fun testInsert() = commonTest.testInsert() @@ -56,15 +58,18 @@ class NativeTest { @Test fun testGroupByAndHavingClause() = commonTest.testGroupByAndHavingClause() - @Test - fun testUnionSelect() = commonTest.testUnionSelect() - @Test fun testCompoundSelect() = commonTest.testCompoundSelect() @Test fun testObserve() = commonTest.testObserve() + @Test + fun testTableVersions() = commonTest.testTableVersions() + + @Test + fun testUnreadSelect() = commonTest.testUnreadSelect() + @Test fun testObserveRestoresTracking() = commonTest.testObserveRestoresTracking() @@ -182,11 +187,35 @@ class NativeTest { @Test fun testConflictClauses() = commonTest.testConflictClauses() + @Test + fun testConflictResolutions() = commonTest.testConflictResolutions() + + @Test + fun testTransactionModes() = commonTest.testTransactionModes() + + @Test + fun testNestedTransaction() = commonTest.testNestedTransaction() + + @Test + fun testIndexedBy() = commonTest.testIndexedBy() + + @Test + fun testExplainQueryPlan() = commonTest.testExplainQueryPlan() + + @Test + fun testClauseOnEarlierStatement() = commonTest.testClauseOnEarlierStatement() + + @Test + fun testPragmas() = commonTest.testPragmas() + + @Test + fun testMorePragmas() = commonTest.testMorePragmas() + @Test fun testFunction() = commonTest.testFunction() @Test - fun testJoinClause() = commonTest.testJoinClause() + fun testJoinWithoutFrom() = commonTest.testJoinWithoutFrom() @Test fun testConcurrency() = commonTest.testConcurrency() @@ -257,6 +286,45 @@ class NativeTest { @Test fun testCollateNoCaseConstraint() = commonTest.testCollateNoCaseConstraint() + @Test + fun testCollations() = commonTest.testCollations() + + @Test + fun testUpdateDeleteOrderByLimit() = commonTest.testUpdateDeleteOrderByLimit() + + @Test + fun testPagingSourceLoads() = pagingTest.testPagingSourceLoads() + + @Test + fun testPagingSourceRefreshKey() = pagingTest.testPagingSourceRefreshKey() + + @Test + fun testPagingSourceInvalidation() = pagingTest.testPagingSourceInvalidation() + + @Test + fun testPagingSourceQueries() = pagingTest.testPagingSourceQueries() + + @Test + fun testPagingSourceWithPager() = pagingTest.testPagingSourceWithPager() + + @Test + fun testConvertedConditions() = convertedTest.testConvertedConditions() + + @Test + fun testConvertedStatements() = convertedTest.testConvertedStatements() + + @Test + fun testConvertedEnums() = convertedTest.testConvertedEnums() + + @Test + fun testConvertedSchema() = convertedTest.testConvertedSchema() + + @Test + fun testConvertedOptIn() = convertedTest.testConvertedOptIn() + + @Test + fun testConvertedErrors() = convertedTest.testConvertedErrors() + @Test fun testCompositeUniqueConstraint() = commonTest.testCompositeUniqueConstraint() diff --git a/sqllin-dsl/doc/advanced-query-cn.md b/sqllin-dsl/doc/advanced-query-cn.md index bcc59370..eabd66ed 100644 --- a/sqllin-dsl/doc/advanced-query-cn.md +++ b/sqllin-dsl/doc/advanced-query-cn.md @@ -50,25 +50,19 @@ a UNION (b UNION_ALL c) // a UNION SELECT * FROM (b UNION ALL c) 参与组合的语句会成为组合的一部分,因此不再单独执行,也无法读取它们各自的结果。 -### 已废弃的 `UNION {...}` 块 +### 从 `UNION {...}` 块迁移 -以前的版本用 `UNION {...}` 和 `UNION_ALL {...}` 块来合并 _SELECT_ 语句。**它们已经废弃,将在未来的版本中移除**,因为它们存在 -不会再修复的 bug: - -- 块的结果类型取自表的行类型,结果行却按第一条 _SELECT_ 的结果类型读取。所以对投影、结果列或 Join 做 UNION 时,代码能编译通过, - 但使用结果时会抛出 `ClassCastException`。 -- 嵌套的块在生成 SQL 时会被展平,而 SQLite 按从左到右的顺序计算,所以 `UNION { a; UNION_ALL { b; c } }` 实际执行的是 - `(a UNION b) UNION ALL c`,而不是嵌套所表达的含义。 - -请改用中缀运算符: +在 2.6.0 之前,还可以用 `UNION {...}` 和 `UNION_ALL {...}` 块来合并 _SELECT_ 语句。它们在 2.5.0 中因不会再修复的 bug 而废弃: +块的结果行按第一条 _SELECT_ 的结果类型读取,返回的却是表的行类型,所以对投影、结果列或 Join 做 UNION 时会抛出 +`ClassCastException`;嵌套的块在生成 SQL 时会被展平,从而改变含义。2.6.0 删除了它们,请改用中缀运算符: ```kotlin -// 已废弃 +// 2.6.0 之前 UNION { table SELECT WHERE(age LT 18) table SELECT WHERE(age GTE 65) } -// 改为 +// 现在 (table SELECT WHERE(age LT 18)) UNION (table SELECT WHERE(age GTE 65)) ``` @@ -171,8 +165,9 @@ fun sample() { ## Join -Join 把多个关系(表、视图或派生表)的行合在一起读取。用 `FROM(relation)` 开始一个 Join,用 Join 运算符扩展它,然后像查询表一样 -从中查询。Join 是实验性 API,使用时需要 `@OptIn(ExperimentalDSLDatabaseAPI::class)`。 +Join 把多个关系(表、视图或派生表)的行合在一起读取。对第一个关系直接使用 Join 运算符即可开始一个 Join,比如 +`PersonTable INNER_JOIN TranscriptTable`,也可以用 `FROM(relation)` 开始;再用更多 Join 运算符扩展它,然后像查询表一样从中查询。 +Join 是实验性 API,使用时需要 `@OptIn(ExperimentalDSLDatabaseAPI::class)`。 示例用到另一张表,以及几个表示 Join 结果的类型,它们不需要 `@DBRow`: @@ -208,10 +203,10 @@ fun joinSample() { lateinit var scores: SelectStatement database { // SELECT name,person.age,transcript.math,transcript.english FROM person INNER JOIN transcript USING (name) - students = (FROM(PersonTable) INNER_JOIN TranscriptTable USING PersonTable.name) SELECT X() + students = (PersonTable INNER_JOIN TranscriptTable USING PersonTable.name) SELECT X() // SELECT person.name AS name,count(transcript.math) AS tests,max(transcript.math) AS bestMath // FROM person LEFT OUTER JOIN transcript ON person.name = transcript.name GROUP BY person.name - scores = (FROM(PersonTable) LEFT_OUTER_JOIN TranscriptTable ON (PersonTable.name EQ TranscriptTable.name)) SELECT listOf( + scores = (PersonTable LEFT_OUTER_JOIN TranscriptTable ON (PersonTable.name EQ TranscriptTable.name)) SELECT listOf( PersonTable.name AS StudentScore::name, PersonTable.count(TranscriptTable.math) AS StudentScore::tests, PersonTable.max(TranscriptTable.math) AS StudentScore::bestMath, @@ -235,7 +230,7 @@ Join 运算符有: `@PlatformDependentSQLiteAPI`,需要按[依赖 SQLite 版本的 API](modify-database-and-transaction-cn.md#依赖-sqlite-版本的-api) 所说的 方式声明同意。 -Join 按书写的顺序执行,每一个都可以有自己的条件:`FROM(a) INNER_JOIN b ON (...) LEFT_OUTER_JOIN c ON (...)`。一个关系只能被连接 +Join 按书写的顺序执行,每一个都可以有自己的条件:`a INNER_JOIN b ON (...) LEFT_OUTER_JOIN c ON (...)`。一个关系只能被连接 一次:要让表和自身 Join,请连接由它的行构成的[派生表](#派生表),这相当于给它起了另一个名字。 Join 的行没有自己的类型,所以从 Join 查询时要指定读取成的类型:用 `X()`、`WHERE(...)` 这类子句函数,或者结果列。构建语句时, @@ -249,11 +244,13 @@ Join 的行没有自己的类型,所以从 Join 查询时要指定读取成的 SQLlin 写列时都带上关系的名字,所以条件、函数、_GROUP BY_ 和 _ORDER BY_ 都能使用其他关系中也有的列名。可观察查询会观察 Join 中的 所有关系。 -### 旧的 Join API +### 从旧的 Join API 迁移 -在 2.5.0 之前,Join 写作 _SELECT_ 的子句:`PersonTable SELECT INNER_JOIN(TranscriptTable) USING name`,以及 `CROSS_JOIN`、 -`NATURAL_JOIN`、`LEFT_OUTER_JOIN` 等。它们仍然可用,但不会检查行被读取成的类型,无法连接两个以上各带条件的关系,也不能选取结果列。 -**它们将在 2.5.0 之后的下一个版本中删除**,请按上面的方式书写 Join。 +在 2.6.0 之前,Join 还可以写作 _SELECT_ 的子句,比如 `PersonTable SELECT INNER_JOIN(TranscriptTable) USING name`, +以及 `CROSS_JOIN`、`NATURAL_JOIN`、`LEFT_OUTER_JOIN` 等。2.6.0 删除了这些写法,请按上面的方式书写: +`(PersonTable INNER_JOIN TranscriptTable USING PersonTable.name) SELECT X()`。由于现在会对照被连接的关系检查结果类型, +如果一个类型读取了两个关系都有的列,或者把外连接可能为 NULL 的列读进非空属性,构建语句时就会被拒绝:请用 `AS` 选取这样的列, +或者把属性改为可空。 ## 子查询 @@ -297,7 +294,7 @@ fun sample() { // WHERE author_books.books>? prolific = authorBooks SELECT WHERE(AuthorBooksView.books GT 1) // SELECT person.name,author_books.books FROM person INNER JOIN (SELECT ...) AS author_books ON person.id=author_books.authorId - personBooks = (FROM(PersonTable) INNER_JOIN authorBooks ON (PersonTable.id EQ AuthorBooksView.authorId)) SELECT X() + personBooks = (PersonTable INNER_JOIN authorBooks ON (PersonTable.id EQ AuthorBooksView.authorId)) SELECT X() } } ``` @@ -322,7 +319,7 @@ database { } AS ElderView // SELECT person.name,elder.elderName FROM person // INNER JOIN (SELECT person.name AS elderName,person.age AS elderAge FROM person) AS elder ON elder.elderAge>person.age - pairs = (FROM(PersonTable) INNER_JOIN elders ON (ElderView.elderAge GT PersonTable.age)) SELECT X() + pairs = (PersonTable INNER_JOIN elders ON (ElderView.elderAge GT PersonTable.age)) SELECT X() } ``` @@ -408,6 +405,75 @@ _DELETE_ 也不会。 同时影响两边的表的修改,可能会短暂地呈现一边的新结果和另一边的旧结果。如果结果来自几张表,用一条带 Join 的 _SELECT_ 可以一次 得到。 +### 表版本令牌 + +可观察查询给出的是结果。如果读取方只需要知道它读过的表何时发生变化,比如自己读取分页、需要自行失效的 `PagingSource`,就改用 +`versioned { }` 读取。它执行一个由 _SELECT_ 组成的作用域,返回作用域的结果,以及这些 _SELECT_ 读到的表的版本令牌。 +`awaitChange(token)` 会挂起,直到经由该数据库执行的语句修改了其中某张表;`onChange(token) { }` 则为此注册一个回调。它们是实验性 +API,使用时需要 `@OptIn(ExperimentalDSLDatabaseAPI::class)`。下面的示例只是演示它们如何配合使用;_sqllin-dsl-paging_ 提供了完整的 +`PagingSource`,见 [PagingSource](#pagingsource)。 + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +class PersonPagingSource(private val database: Database) : PagingSource() { + + private var registration: AutoCloseable? = null + + override suspend fun load(params: LoadParams): LoadResult { + val offset = params.key ?: 0 + val (page, since) = database.versioned { + PersonTable SELECT ORDER_BY(PersonTable.age to ASC) LIMIT params.loadSize OFFSET offset + } + if (registration == null) { + // 读取之后已有语句修改了这张表时返回 null + registration = database.onChange(since) { invalidate() } ?: return LoadResult.Invalid() + registerInvalidatedCallback { registration?.close() } + } + val persons = page.getResults() + return LoadResult.Page(persons, prevKey = null, nextKey = if (persons.isEmpty()) null else offset + persons.size) + } + + override fun getRefreshKey(state: PagingState): Int? = null +} +``` + +令牌在执行这些 _SELECT_ 时持有的锁内捕获,并且是在开始跟踪它们的表之后,所以不会漏掉它们执行之后的任何修改;它们已经包含的修改 +也可能让令牌过期。令牌覆盖作用域中每条 _SELECT_ 读到的表,视图按它读取的表计算;和可观察查询一样,只能感知经由同一个 `Database` +实例的修改。包含写入语句的作用域会被拒绝,因为它的令牌无法区分自己的修改和别人的修改。 + +* **组合令牌**:如果一条查询要用另一条查询的结果来构建,比如用第一个作用域返回的 id,它就只能在自己的作用域中执行。 + `token1 + token2` 覆盖两次读取的表;两者都读过的表取较早的版本,所以任何一边过期,组合后的令牌就过期。两个 `Database` 实例的令牌 + 不能组合。 +* **onChange** 先注册、再检查令牌,所以读取和注册之间的修改不会被漏掉:如果令牌已经过期,它不注册,直接返回 `null`,由调用方自行 + 处理,比如 `PagingSource` 返回 `LoadResult.Invalid()`。否则它的回调只执行一次:在写入的线程上,在写入作用域释放数据库的锁之后 + 执行,所以回调里可以使用数据库,但应当尽快返回。注册会一直持有回调,直到回调执行,或者它返回的 `AutoCloseable` 被关闭。 + +### PagingSource + +可选模块 _sqllin-dsl-paging_(`com.ctrip.kotlin:sqllin-dsl-paging`)为查询提供 androidx.paging 的 `PagingSource`:它像 Room 的 +`LimitOffsetPagingSource` 一样,按偏移量每次加载一页。androidx.paging 支持的平台都能用,SQLlin 支持的平台都在其中。 +`database.pagingSource { }` 像 `observe { }` 一样构建要分页的 _SELECT_,它是实验性 API: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun persons(database: Database): Flow> = + Pager(PagingConfig(pageSize = 20)) { + database.pagingSource { PersonTable SELECT ORDER_BY(PersonTable.id to ASC) } + }.flow +``` + +* **分页**:每一页都是 `SELECT * FROM (select) LIMIT ... OFFSET ...`,所以 _SELECT_ 可以带 _WHERE_、连接或组合查询运算符。它应当带有 + 能给所有行排序的 _ORDER BY_,否则 SQLite 返回的行没有固定顺序,两页可能出现相同的行。第一页还会统计总行数,这样每一页都能说明它前后 + 各有多少行,占位符依赖这些数字;刷新时如果起点已经超过最后一行(比如有行被删除了),就改为加载最后那些行。key 是相邻两页之间边界处的 + 偏移量,所以无论从哪里开始刷新,两页都不会包含同一行;而且第一行之后的页总能向前加载它上面的行,比如 `RemoteMediator` 让数据源 + 失效之后。刷新从最后读取的那一行往前退初始加载量的一半开始,开不开占位符都一样。 +* **失效**:数据源从第一页起用 `onChange` 注册,所以经由同一个 `Database` 执行的语句只要修改了 _SELECT_ 读取的表,数据源就会失效, + 它的 `Pager` 会加载一个新的数据源;如果某一页读到了第一页之后被修改过的行,就返回 `LoadResult.Invalid()`,这样列表里不会混入修改前后 + 的行。它以弱引用的方式注册,所以 `Pager` 丢弃的数据源仍然可以被垃圾回收;从别处让它失效(比如刷新)时,也会关闭这次注册。和可观察查询 + 一样,只能感知经由同一个 `Database` 实例的修改。 +* **线程**:分页在 `Dispatchers.IO` 中加载,也可以用 `pagingSource(context) { }` 指定别的上下文,因为 `Pager` 可能在主线程上加载。 + 和可观察查询一样,写入要通过 `suspendedScope` 执行,因为分页的加载和它是串行的。 + ## 全文搜索 全文搜索(FTS)表会为文本建立索引,让查询像搜索引擎一样找出包含某些词的行。SQLlin 支持 SQLite 的 FTS4 和 FTS3 表,SQLlin @@ -526,6 +592,33 @@ FTS 表是虚拟表,无法拥有[可观察查询](#可观察查询)用来计 _INSERT_、_UPDATE_ 和 _DELETE_ 来计数;由于触发器可能写入它,对任何带触发器的表执行的这些语句也会计入:用其他 SQL 所做的修改 感知不到,视图所读取的 FTS 表的修改也感知不到。回滚的事务仍会计入其中的语句,这只会让查询多执行一次。 +## 查询计划 + +`EXPLAIN_QUERY_PLAN(select)` 和 SQL 的 `EXPLAIN QUERY PLAN` 一样,告诉你 SQLite 会怎样执行一条 _SELECT_,但不会真的执行它: +扫描哪些表、查找哪些索引、在哪里用临时 B 树给行排序。它可以用来确认查询用上了为它准备的索引(比如用了 `INDEXED_BY` 之后), +也可以在测试中做这样的断言。它是实验性 API,使用时需要 `@OptIn(ExperimentalDSLDatabaseAPI::class)`: + +```kotlin +val plan = database { + EXPLAIN_QUERY_PLAN(BookTable SELECT WHERE(BookTable.author EQ "Dan Brown") ORDER_BY (BookTable.price to ASC)) +}.getResults() +println(plan) +// QUERY PLAN +// |--SEARCH book USING INDEX idx_book_author (author=?) +// `--USE TEMP B-TREE FOR ORDER BY +check(plan.details.any { "idx_book_author" in it }) +``` + +任何 _SELECT_ 都可以,包括连接、子查询和组合查询。它会成为这条语句的一部分,所以不再单独执行;规划时会绑定它的参数,和它真正 +执行时一样。和 _SELECT_ 的结果一样,计划要在作用域执行完之后才能读取。`QueryPlan` 的 `steps` 是计划的各个步骤,每一步有它的 +`detail` 和 `children`,比如子查询的步骤、组合查询中每条 _SELECT_ 的步骤;`details` 列出所有步骤的描述,`toString()` 则像 +`sqlite3` 命令行那样把它们写成一棵树。计划取决于索引,以及 `ANALYZE` 和 `PRAGMA_OPTIMIZE` 收集的统计信息。 + +步骤的描述是 SQLite 自己的文字,是给人读的,在不同的 SQLite 版本之间会有差异,比如 `SCAN TABLE book` 和 `SCAN book`。所以检查 +计划时,请看表名、索引名,以及 `USING INDEX`、`USING COVERING INDEX`、`TEMP B-TREE` 这样的短语,不要比较整条描述。低于 3.24.0 +的 SQLite(比如 API 30 之前的 Android)不会告诉你一个步骤属于哪个步骤,所以它的计划把所有步骤平铺列出,没有子步骤。这些都不需要 +你知道 SQLite 的版本:在每个平台上,计划的读取方式都一样。 + ## 最后 你已经学习了所有的 SQLlin 用法,享受你的 SQLlin 的编程旅程并对它的更新保持关注吧 :) \ No newline at end of file diff --git a/sqllin-dsl/doc/advanced-query.md b/sqllin-dsl/doc/advanced-query.md index ef4a377f..c4cf3c11 100644 --- a/sqllin-dsl/doc/advanced-query.md +++ b/sqllin-dsl/doc/advanced-query.md @@ -55,26 +55,20 @@ _LIMIT_ keeps them to itself, as SQLlin writes it as a subquery too: The statements become part of the compound, so they no longer run on their own, and their results can't be read. -### The deprecated `UNION {...}` block +### Migrating From the `UNION {...}` Block -Earlier versions combined _SELECT_ statements with `UNION {...}` and `UNION_ALL {...}` blocks. **They are deprecated -and will be removed in a future version**, because they have bugs that won't be fixed: - -- A block's result is typed by the table's row type, but its rows are read into the first _SELECT_'s result type. So - a union of projections, result columns or joins compiles, and then fails with a `ClassCastException` when its - results are used. -- A nested block is flattened into the SQL, which SQLite evaluates from left to right, so - `UNION { a; UNION_ALL { b; c } }` runs as `(a UNION b) UNION ALL c`, not as its nesting suggests. - -Use the infix operators instead: +Before 2.6.0, _SELECT_ statements could also be combined with `UNION {...}` and `UNION_ALL {...}` blocks, deprecated +in 2.5.0 for bugs that wouldn't be fixed: a block read its rows into its first _SELECT_'s result type while returning the +table's row type, so a union of projections, result columns or joins failed with a `ClassCastException`, and a nested +block was flattened into the SQL, which changed its meaning. 2.6.0 removed them. Write them with the infix operators: ```kotlin -// Deprecated +// Before 2.6.0 UNION { table SELECT WHERE(age LT 18) table SELECT WHERE(age GTE 65) } -// Instead +// Now (table SELECT WHERE(age LT 18)) UNION (table SELECT WHERE(age GTE 65)) ``` @@ -183,9 +177,10 @@ from a [join](#join) too. Arithmetic, `CASE` and subqueries that give a single v ## Join -A join reads the rows of several relations, tables, views or derived tables, together. Start one with -`FROM(relation)`, extend it with join operators, and select from it as from a table. Joins are experimental, so opt in -with `@OptIn(ExperimentalDSLDatabaseAPI::class)`. +A join reads the rows of several relations, tables, views or derived tables, together. Start one with a join operator +applied to its first relation, as `PersonTable INNER_JOIN TranscriptTable`, or with `FROM(relation)`, extend it with more +join operators, and select from it as from a table. Joins are experimental, so opt in with +`@OptIn(ExperimentalDSLDatabaseAPI::class)`. The examples use another table, and types for the rows of joins, which don't need `@DBRow`: @@ -221,10 +216,10 @@ fun joinSample() { lateinit var scores: SelectStatement database { // SELECT name,person.age,transcript.math,transcript.english FROM person INNER JOIN transcript USING (name) - students = (FROM(PersonTable) INNER_JOIN TranscriptTable USING PersonTable.name) SELECT X() + students = (PersonTable INNER_JOIN TranscriptTable USING PersonTable.name) SELECT X() // SELECT person.name AS name,count(transcript.math) AS tests,max(transcript.math) AS bestMath // FROM person LEFT OUTER JOIN transcript ON person.name = transcript.name GROUP BY person.name - scores = (FROM(PersonTable) LEFT_OUTER_JOIN TranscriptTable ON (PersonTable.name EQ TranscriptTable.name)) SELECT listOf( + scores = (PersonTable LEFT_OUTER_JOIN TranscriptTable ON (PersonTable.name EQ TranscriptTable.name)) SELECT listOf( PersonTable.name AS StudentScore::name, PersonTable.count(TranscriptTable.math) AS StudentScore::tests, PersonTable.max(TranscriptTable.math) AS StudentScore::bestMath, @@ -249,7 +244,7 @@ they are marked with `@PlatformDependentSQLiteAPI`, which you have to opt in to, [APIs That Depend on the SQLite Version](modify-database-and-transaction.md#apis-that-depend-on-the-sqlite-version). Joins are applied in the order they are written, and each can have its own condition: -`FROM(a) INNER_JOIN b ON (...) LEFT_OUTER_JOIN c ON (...)`. A relation can only be joined once: to join a table with +`a INNER_JOIN b ON (...) LEFT_OUTER_JOIN c ON (...)`. A relation can only be joined once: to join a table with itself, join a [derived table](#derived-tables) of its rows, which gives it another name. A join's rows have no type of their own, so a _SELECT_ of a join names the type it reads them into: with @@ -265,12 +260,15 @@ joined relations when the statement is built: SQLlin writes the columns with their relations' names, so that a condition, a function, _GROUP BY_ or _ORDER BY_ can name a column that another relation has too. An observed query of a join watches all its relations. -### The Old Join API +### Migrating From the Old Join API -Before 2.5.0, joins were written as clauses of _SELECT_: `PersonTable SELECT INNER_JOIN(TranscriptTable) USING name`, -with `CROSS_JOIN`, `NATURAL_JOIN`, `LEFT_OUTER_JOIN` and the others. They still work, but they don't check the type -their rows are read into, can't join more than two relations each with its own condition, and can't select result -columns. **They will be removed in the next version after 2.5.0**, so write joins as above. +Before 2.6.0, joins could also be written as clauses of _SELECT_, as +`PersonTable SELECT INNER_JOIN(TranscriptTable) USING name`, with `CROSS_JOIN`, `NATURAL_JOIN`, +`LEFT_OUTER_JOIN` and the others. 2.6.0 removed them. Such a join is now written as above: +`(PersonTable INNER_JOIN TranscriptTable USING PersonTable.name) SELECT X()`. As its result type is now +checked against the joined relations, a type that reads a column two relations have, or reads a column that an outer +join can leave NULL into a non-null property, is rejected when the statement is built: select such a column with `AS`, +or make the property nullable. ## Subqueries @@ -316,7 +314,7 @@ fun sample() { // WHERE author_books.books>? prolific = authorBooks SELECT WHERE(AuthorBooksView.books GT 1) // SELECT person.name,author_books.books FROM person INNER JOIN (SELECT ...) AS author_books ON person.id=author_books.authorId - personBooks = (FROM(PersonTable) INNER_JOIN authorBooks ON (PersonTable.id EQ AuthorBooksView.authorId)) SELECT X() + personBooks = (PersonTable INNER_JOIN authorBooks ON (PersonTable.id EQ AuthorBooksView.authorId)) SELECT X() } } ``` @@ -342,7 +340,7 @@ database { } AS ElderView // SELECT person.name,elder.elderName FROM person // INNER JOIN (SELECT person.name AS elderName,person.age AS elderAge FROM person) AS elder ON elder.elderAge>person.age - pairs = (FROM(PersonTable) INNER_JOIN elders ON (ElderView.elderAge GT PersonTable.age)) SELECT X() + pairs = (PersonTable INNER_JOIN elders ON (ElderView.elderAge GT PersonTable.age)) SELECT X() } ``` @@ -438,6 +436,88 @@ kotlinx.coroutines. As each runs its query on its own, a change to the tables of one with the old results of the other. When the results come from several tables, a single _SELECT_ with a join gives them at once. +### Table Version Tokens + +An observed query gives results. A reader that only needs to know when the tables it read change, such as a +`PagingSource` that invalidates itself and reads its pages on its own, reads through `versioned { }` instead. It runs a +scope of _SELECT_ statements, and returns the scope's result with a token of the versions of the tables they read. +`awaitChange(token)` suspends until a statement run through the database changes one of those tables, and +`onChange(token) { }` registers a callback for it. They are experimental, so opt in with +`@OptIn(ExperimentalDSLDatabaseAPI::class)`. The example only shows how they fit together: _sqllin-dsl-paging_ provides +a whole `PagingSource`, as [PagingSource](#pagingsource) describes. + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +class PersonPagingSource(private val database: Database) : PagingSource() { + + private var registration: AutoCloseable? = null + + override suspend fun load(params: LoadParams): LoadResult { + val offset = params.key ?: 0 + val (page, since) = database.versioned { + PersonTable SELECT ORDER_BY(PersonTable.age to ASC) LIMIT params.loadSize OFFSET offset + } + if (registration == null) { + // null when a statement changed the table since the read + registration = database.onChange(since) { invalidate() } ?: return LoadResult.Invalid() + registerInvalidatedCallback { registration?.close() } + } + val persons = page.getResults() + return LoadResult.Page(persons, prevKey = null, nextKey = if (persons.isEmpty()) null else offset + persons.size) + } + + override fun getRefreshKey(state: PagingState): Int? = null +} +``` + +The token is captured under the lock that the _SELECT_ statements run under, after their tables are tracked, so that no +change made after them is missed; a change that they already include may make it stale too. It covers the tables of +every _SELECT_ of the scope, a view standing for the tables it reads, and only sees the changes made through the same +`Database` instance, as an observed query does. A scope that writes is rejected, as its token couldn't tell its own +changes from others'. + +* **Combining tokens**: when a query is built from the results of another, as from ids that a first scope returned, it + runs in a scope of its own. `token1 + token2` covers the tables of both reads, with the earlier version of a table + that both read, so that it is stale when either is. The tokens of two `Database` instances can't be combined. +* **onChange** registers before it checks the token, so that a change between the read and the registration is never + missed: when the token is already stale, it registers nothing and returns `null`, and the caller acts on the change + itself, as a `PagingSource` returns `LoadResult.Invalid()`. Otherwise its callback runs once, on the thread that + wrote, after the writing scope has released the database's lock, so it may use the database, but should return + quickly. The registration holds the callback until it runs, or until the `AutoCloseable` it returns is closed. + +### PagingSource + +The optional module _sqllin-dsl-paging_, `com.ctrip.kotlin:sqllin-dsl-paging`, provides androidx.paging's +`PagingSource` of a query, which loads its rows a page at a time, by their offsets, as Room's `LimitOffsetPagingSource` +does, on every platform that androidx.paging has, which are all of SQLlin's. `database.pagingSource { }` builds the +_SELECT_ to page, as `observe { }` does, and is experimental: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun persons(database: Database): Flow> = + Pager(PagingConfig(pageSize = 20)) { + database.pagingSource { PersonTable SELECT ORDER_BY(PersonTable.id to ASC) } + }.flow +``` + +* **The pages**: a page is `SELECT * FROM (select) LIMIT ... OFFSET ...`, so the _SELECT_ can have a _WHERE_, a join or + compound operators, and should have an _ORDER BY_ that orders all of its rows, as SQLite returns them in no order + otherwise, so that two pages could have the same rows. The first page also counts the rows, so that each page tells + how many rows are before and after it, which placeholders show, and a refresh past the last row, as after rows are + deleted, loads the last ones. The keys are offsets at the borders between pages, so that two pages never share a row, + wherever a refresh starts, and a page after the first row can always prepend the rows above it, as after a + `RemoteMediator` invalidates the source. A refresh starts half the initial load before the row last read, with + placeholders or without them. +* **Invalidation**: the source registers with `onChange` from its first page, so that a statement run through the same + `Database` that changes a table the _SELECT_ reads invalidates it, and its `Pager` loads a new one; a page that reads + rows changed since the first is `LoadResult.Invalid()`, so that no list mixes rows from before and after a change. It + registers weakly, so that a source that its `Pager` drops can still be garbage collected, and an invalidation from + elsewhere, as a refresh, closes the registration. As with an observed query, only the changes made through the same + `Database` instance are seen. +* **The thread**: the pages load in `Dispatchers.IO`, or the context given to `pagingSource(context) { }`, as a `Pager` + may load them on the main thread. Write through `suspendedScope`, which the loads are serialized with, as for an + observed query. + ## Full-Text Search A full-text search (FTS) table indexes text, so that a query finds the rows containing some words, as a search engine @@ -565,6 +645,37 @@ trigger can write it, from those on any table that has triggers: a change made w is a change to an FTS table that a view reads. A rolled back transaction still counts its statements, which only runs the query once more. +## Query Plans + +`EXPLAIN_QUERY_PLAN(select)` tells how SQLite would run a _SELECT_, as the SQL `EXPLAIN QUERY PLAN` does, without +running it: which tables it scans, which indexes it searches, and where it sorts the rows with a temporary B-tree. It +helps to check that a query uses the index meant for it, as after `INDEXED_BY`, or a test that asserts so. It is +experimental, so opt in with `@OptIn(ExperimentalDSLDatabaseAPI::class)`: + +```kotlin +val plan = database { + EXPLAIN_QUERY_PLAN(BookTable SELECT WHERE(BookTable.author EQ "Dan Brown") ORDER_BY (BookTable.price to ASC)) +}.getResults() +println(plan) +// QUERY PLAN +// |--SEARCH book USING INDEX idx_book_author (author=?) +// `--USE TEMP B-TREE FOR ORDER BY +check(plan.details.any { "idx_book_author" in it }) +``` + +The _SELECT_ can be any, with joins, subqueries or compound operators. It becomes part of the statement, so it no +longer runs on its own, and it is planned with its parameters, as it would run. As with the results of a _SELECT_, the +plan is read once the scope has run. A `QueryPlan` has the `steps` of the plan, each with its `detail` and its +`children`, as the steps of a subquery or of each _SELECT_ of a compound are; `details` lists the details of all steps, +and `toString()` writes them as a tree, as the `sqlite3` shell does. The plan depends on the indexes, and on the +statistics that `ANALYZE` and `PRAGMA_OPTIMIZE` gather. + +The details are SQLite's own text, which is meant to be read, and which differs between SQLite versions, as +`SCAN TABLE book` and `SCAN book` do. So check a plan by the names of tables and indexes, and by phrases such as +`USING INDEX`, `USING COVERING INDEX` and `TEMP B-TREE`, rather than by whole details. A SQLite older than 3.24.0, as +Android's before API 30 is, doesn't tell which step another belongs to, so its plans list all steps in a row, with no +children. None of this needs the version of SQLite to be known: the plan is read the same way on every platform. + ## Finally You have learned all usages with SQLlin, enjoy it and stay Stay tuned for SQLlin's updates :) \ No newline at end of file diff --git a/sqllin-dsl/doc/getting-start-cn.md b/sqllin-dsl/doc/getting-start-cn.md index 1e59d273..a73cbcc9 100644 --- a/sqllin-dsl/doc/getting-start-cn.md +++ b/sqllin-dsl/doc/getting-start-cn.md @@ -28,6 +28,8 @@ kotlin { implementation("com.ctrip.kotlin:sqllin-dsl:$sqllinVersion") // sqllin-driver implementation("com.ctrip.kotlin:sqllin-driver:$sqllinVersion") + // 可选,2.6.0 起:为 sqllin-dsl 的查询提供 androidx.paging 的 PagingSource + implementation("com.ctrip.kotlin:sqllin-dsl-paging:$sqllinVersion") // The sqllin-dsl serialization and deserialization depends on kotlinx-serialization implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.9.0") @@ -416,6 +418,26 @@ data class User( - `ORDER BY` 子句不区分大小写排序 - 列上的索引不区分大小写 +#### @CollateRTrim - 忽略末尾空格的文本比较 + +`@CollateRTrim` 让文本列在比较时忽略值末尾的空格,对应 SQL 的 `COLLATE RTRIM`:`'abc '` 等于 `'abc'`,列上的 UNIQUE 约束和索引 +也把它们当作同一个值。值本身仍按写入时的原样存储。它是实验性 API,只能用于 `String` 和 `Char` 属性: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +@DBRow +@Serializable +data class Product( + @PrimaryKey(autoIncrement = true) val id: Long?, + @CollateRTrim @Unique val code: String, +) +// Generated SQL: CREATE TABLE Product(id INTEGER PRIMARY KEY AUTOINCREMENT,code TEXT NOT NULL COLLATE RTRIM UNIQUE) +``` + +一列只有一种排序规则,所以同一个属性不能同时使用 `@CollateNoCase` 和 `@CollateRTrim`。两者都没有的列按字节比较,即 `BINARY` +排序规则。`COLLATE` 运算符可以在单个表达式里改用别的排序规则,见[更多表达式语法](sql-functions-cn.md#更多表达式语法); +也可以给索引的某一列指定它自己的排序规则,见 [CREATE INDEX](modify-database-and-transaction-cn.md#create-index---创建索引)。 + #### 组合多个约束 你可以在同一个属性上组合多个约束注解: @@ -600,7 +622,7 @@ SQLite 的 `ALTER TABLE` 不能给表添加约束,`ALTER_ADD_COLUMN` 添加的 ### 支持的类型 -SQLlin 支持以下 Kotlin 类型用于 `@DBRow` 数据类的属性。其他任何类型的属性都会导致编译错误;如果想让这样的属性不进入表中,请为它加上 `kotlinx.serialization.Transient` 注解: +SQLlin 支持以下 Kotlin 类型用于 `@DBRow` 数据类的属性;其他类型只要它的 serializer 把它转换成其中一种,也同样支持(见[由 serializer 转换的类型](#由-serializer-转换的类型))。其他任何类型的属性都会导致编译错误;如果想让这样的属性不进入表中,请为它加上 `kotlinx.serialization.Transient` 注解: #### 数值类型 - **整数类型:** `Byte`、`Short`、`Int`、`Long` @@ -666,7 +688,76 @@ data class User( **重要注意事项:** - 枚举值存储为其序数(整数)值 - 更改枚举常量的顺序会影响存储的值 -- 如果需要更稳定的存储,考虑使用 String +- 如果需要更稳定的存储,比如按名字存,可以在枚举类或属性上给它一个这样存储的 serializer:这样它就成了[由 serializer 转换的类型](#由-serializer-转换的类型),存为 TEXT + +#### 由 serializer 转换的类型 + +kotlinx.serialization 用哪个 serializer 写一个属性,这个 serializer 就是该属性的转换器:任何类型的属性,只要它的 serializer 把它编码成上述类型中的单个值,就可以作为一列,列中存的就是这个值。以下情况无需任何额外操作: +- `kotlin.uuid.Uuid`、`kotlin.time.Instant` 和 `kotlin.time.Duration`,它们的内置 serializer 存为字符串 +- 值类(value class),存它所持有的值 +- 在类上用 `@Serializable(with = ...)` 声明了 serializer 的类型,kotlinx-datetime 的类型就是这样 +- 任何类型(包括枚举和 `String`),在属性上、类型的使用处或类型别名里用 `@Serializable(with = ...)` 指定了 serializer,或者由 `@file:UseSerializers(...)` 指定 + +```kotlin +object EpochMillisSerializer : KSerializer { + override val descriptor = PrimitiveSerialDescriptor("EpochMillis", PrimitiveKind.LONG) + override fun serialize(encoder: Encoder, value: Instant) = encoder.encodeLong(value.toEpochMilliseconds()) + override fun deserialize(decoder: Decoder) = Instant.fromEpochMilliseconds(decoder.decodeLong()) +} + +@JvmInline +@Serializable +value class Score(val value: Int) + +@DBRow +@Serializable +data class Event( + @PrimaryKey val id: Uuid, // TEXT PRIMARY KEY + @Serializable(with = EpochMillisSerializer::class) val startsAt: Instant, // BIGINT + val score: Score, // INT +) +``` + +列的类型是 serializer 所存值的类型,由 `CREATE` 根据 serializer 计算得出。条件和 `SET {}` 会用同一个 serializer 转换传给它们的值,所以比较的、写入的都和列中存的一致: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + database { + EventTable { table -> + table SELECT WHERE(startsAt GTE since) ORDER_BY (startsAt to ASC) + table UPDATE SET { score = Score(10) } WHERE (id EQ eventId) + } + } +} +``` + +这种列的元素是 `ClauseConverted`,属于实验性 API。它支持 `EQ`、`NEQ`、`LT`、`LTE`、`GT`、`GTE`、`IN`、`BETWEEN`、`IS` 和 `ISNOT`,并且和其他列一样可以用在 `max`、`min`、`coalesce`、`CASE`、`ORDER_BY`、`GROUP_BY`、索引和视图中。`literal(value, serializer)` 可以创建转换类型的字面量。 + +**重要注意事项:** +- 除相等以外的比较,以及 `ORDER_BY`,比较的都是存储的值;只有 serializer 保持了顺序,存储值的顺序才和 Kotlin 值的顺序一致。`kotlin.time.Instant` 的内置 serializer 写的是 ISO-8601 字符串,只在有小数秒时才写小数部分,因此 `2024-01-01T00:00:00.5Z` 会排在 `2024-01-01T00:00:00Z` 前面。如果要比较或排序时间,请像 `EpochMillisSerializer` 那样把它存成数字 +- 转换类型的列永远不会是 rowid:以 `Long` 值类作为主键时,它是由调用方提供值的 `BIGINT PRIMARY KEY` +- 把值编码成结构的 serializer(比如 data class 或 `List` 自动生成的 serializer)不能作为一列。处理器会拒绝它能确定是结构的类型;对于它无法判断的 serializer,`CREATE` 会失败。这类值需要存成单个值,比如用自己写的 serializer 存成 JSON 字符串: + +```kotlin +object TagsAsJsonSerializer : KSerializer> { + private val tags = ListSerializer(String.serializer()) + override val descriptor = PrimitiveSerialDescriptor("TagsAsJson", PrimitiveKind.STRING) + override fun serialize(encoder: Encoder, value: List) = encoder.encodeString(Json.encodeToString(tags, value)) + override fun deserialize(decoder: Decoder) = Json.decodeFromString(tags, decoder.decodeString()) +} + +@DBRow +@Serializable +data class Note( + @PrimaryKey val id: Long?, + @Serializable(with = TagsAsJsonSerializer::class) val tags: List, // TEXT +) +``` + +- 不支持 `@Contextual` 和 `@UseContextualSerialization`,因为 SQLlin 没有可以查找 serializer 的 `SerializersModule`:请用 `@Serializable(with = ...)` 给属性指定 serializer。以上下文方式序列化的枚举或基础类型,仍按默认方式存储 +- 带 `@CollateNoCase` 或 `@CollateRTrim` 的列必须存文本,`CREATE` 会检查这一点 +- FTS 表只能有使用默认 serializer 的 `String` 列 #### SQLite 类型映射 @@ -684,6 +775,7 @@ data class User( | String | TEXT | | ByteArray | BLOB | | Enum | INT | +| 由 serializer 转换的类型 | 它所存值的类型,比如 `Uuid` 为 TEXT | ### 外键约束 diff --git a/sqllin-dsl/doc/getting-start.md b/sqllin-dsl/doc/getting-start.md index c8475441..b0ae5dcb 100644 --- a/sqllin-dsl/doc/getting-start.md +++ b/sqllin-dsl/doc/getting-start.md @@ -30,6 +30,8 @@ kotlin { implementation("com.ctrip.kotlin:sqllin-dsl:$sqllinVersion") // sqllin-driver implementation("com.ctrip.kotlin:sqllin-driver:$sqllinVersion") + // Optional, since 2.6.0: androidx.paging's PagingSource of sqllin-dsl's queries + implementation("com.ctrip.kotlin:sqllin-dsl-paging:$sqllinVersion") // The sqllin-dsl serialization and deserialization depends on kotlinx-serialization implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.9.0") @@ -428,6 +430,29 @@ data class User( - `ORDER BY` clauses sort case-insensitively - Indexes on the column are case-insensitive +#### @CollateRTrim - Text Comparison Ignoring Trailing Spaces + +`@CollateRTrim` makes a text column compare its values ignoring the spaces at their ends, for SQL `COLLATE RTRIM`, so +that `'abc '` equals `'abc'`, and its UNIQUE constraint and indexes treat them as the same value. The values are still +stored as they are written. It is experimental, and can only be applied to `String` and `Char` properties: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +@DBRow +@Serializable +data class Product( + @PrimaryKey(autoIncrement = true) val id: Long?, + @CollateRTrim @Unique val code: String, +) +// Generated SQL: CREATE TABLE Product(id INTEGER PRIMARY KEY AUTOINCREMENT,code TEXT NOT NULL COLLATE RTRIM UNIQUE) +``` + +A column has one collation, so a property can't have both `@CollateNoCase` and `@CollateRTrim`. A column without either +compares its values by their bytes, as the `BINARY` collation does. The `COLLATE` operator compares them by another +collation in a single expression, as [More Expression Syntax](sql-functions.md#more-expression-syntax) describes, and +gives a column of an index its own collation, as +[CREATE INDEX](modify-database-and-transaction.md#create-index---creating-indexes) describes. + #### Combining Multiple Constraints You can combine multiple constraint annotations on the same property: @@ -619,7 +644,7 @@ column's constraint or the table's refers to. ### Supported Types -SQLlin supports the following Kotlin types for properties in `@DBRow` data classes. A property of any other type is a compile-time error; to keep such a property out of the table, annotate it with `kotlinx.serialization.Transient`: +SQLlin supports the following Kotlin types for properties in `@DBRow` data classes, and any other type whose serializer converts it to one of them (see [Types Converted by Serializers](#types-converted-by-serializers)). A property of any other type is a compile-time error; to keep such a property out of the table, annotate it with `kotlinx.serialization.Transient`: #### Numeric Types - **Integer types:** `Byte`, `Short`, `Int`, `Long` @@ -685,7 +710,76 @@ data class User( **Important notes:** - Enum values are stored as their ordinal (integer) values - Changing the order of enum constants will affect the stored values -- Consider using String if you need more stable storage +- To store an enum more stably, as its name, give it a serializer that does, on the enum class or on the property: it is then a [type converted by its serializer](#types-converted-by-serializers), stored as TEXT + +#### Types Converted by Serializers + +The serializer that kotlinx.serialization writes a property with is the property's converter: a property of any type can be a column if its serializer encodes it as one value of the types above, which the column holds. These need nothing more: +- `kotlin.uuid.Uuid`, `kotlin.time.Instant` and `kotlin.time.Duration`, whose built-in serializers store strings +- a value class, which stores the value it holds +- a type whose class declares its serializer with `@Serializable(with = ...)`, as the types of kotlinx-datetime do +- any type, enums and `String` included, given a serializer with `@Serializable(with = ...)` on the property, on the use of its type or in a type alias, or by `@file:UseSerializers(...)` + +```kotlin +object EpochMillisSerializer : KSerializer { + override val descriptor = PrimitiveSerialDescriptor("EpochMillis", PrimitiveKind.LONG) + override fun serialize(encoder: Encoder, value: Instant) = encoder.encodeLong(value.toEpochMilliseconds()) + override fun deserialize(decoder: Decoder) = Instant.fromEpochMilliseconds(decoder.decodeLong()) +} + +@JvmInline +@Serializable +value class Score(val value: Int) + +@DBRow +@Serializable +data class Event( + @PrimaryKey val id: Uuid, // TEXT PRIMARY KEY + @Serializable(with = EpochMillisSerializer::class) val startsAt: Instant, // BIGINT + val score: Score, // INT +) +``` + +The column has the type of the value the serializer stores, which `CREATE` computes from it, and conditions and `SET {}` convert the values given to them with the same serializer, so that they compare with, and store, what the column holds: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + database { + EventTable { table -> + table SELECT WHERE(startsAt GTE since) ORDER_BY (startsAt to ASC) + table UPDATE SET { score = Score(10) } WHERE (id EQ eventId) + } + } +} +``` + +The column's element is a `ClauseConverted`, which is experimental. It has `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE`, `IN`, `BETWEEN`, `IS` and `ISNOT`, and is taken like any column by `max`, `min`, `coalesce`, `CASE`, `ORDER_BY`, `GROUP_BY`, indexes and views. `literal(value, serializer)` is a literal of a converted type. + +**Important notes:** +- A comparison other than an equality, and `ORDER_BY`, compare the stored values, which are in the order of the Kotlin values only if the serializer keeps it. The built-in serializer of `kotlin.time.Instant` writes ISO-8601 strings, with a fraction of a second only if there is one, so that `2024-01-01T00:00:00.5Z` comes before `2024-01-01T00:00:00Z`: store instants as numbers, as `EpochMillisSerializer` does, to compare or order them +- A converted column is never the rowid: a value class of a `Long` as the primary key is a `BIGINT PRIMARY KEY` supplied by the caller +- A serializer that encodes a structure, as the generated serializer of a data class or of a `List` does, can't be a column. The processor rejects the types it knows to be structures, and `CREATE` fails for a serializer it can't tell. Store such a value as one, as JSON in a string, with a serializer of your own: + +```kotlin +object TagsAsJsonSerializer : KSerializer> { + private val tags = ListSerializer(String.serializer()) + override val descriptor = PrimitiveSerialDescriptor("TagsAsJson", PrimitiveKind.STRING) + override fun serialize(encoder: Encoder, value: List) = encoder.encodeString(Json.encodeToString(tags, value)) + override fun deserialize(decoder: Decoder) = Json.decodeFromString(tags, decoder.decodeString()) +} + +@DBRow +@Serializable +data class Note( + @PrimaryKey val id: Long?, + @Serializable(with = TagsAsJsonSerializer::class) val tags: List, // TEXT +) +``` + +- `@Contextual` and `@UseContextualSerialization` aren't supported, as SQLlin has no `SerializersModule` to find the serializer in: give the property its serializer with `@Serializable(with = ...)`. An enum or a basic type serialized contextually is stored as by default +- A `@CollateNoCase` or `@CollateRTrim` column has to store text, which `CREATE` checks +- FTS tables only have `String` columns with their default serializer #### SQLite Type Mappings @@ -703,6 +797,7 @@ data class User( | String | TEXT | | ByteArray | BLOB | | Enum | INT | +| A type converted by its serializer | The type of the value it stores, as TEXT for `Uuid` | ### Foreign Key Constraints diff --git a/sqllin-dsl/doc/modify-database-and-transaction-cn.md b/sqllin-dsl/doc/modify-database-and-transaction-cn.md index cfb9c909..04b27b46 100644 --- a/sqllin-dsl/doc/modify-database-and-transaction-cn.md +++ b/sqllin-dsl/doc/modify-database-and-transaction-cn.md @@ -119,6 +119,11 @@ fun sample() { 索引的每一列都可以像 `ORDER_BY` 那样指定排序方向:`PersonTable.CREATE_INDEX("idx_person_age", PersonTable.age to DESC)` 就是 `CREATE INDEX idx_person_age ON person(age DESC)`。它是实验性 API。按这个顺序或相反顺序排序的查询,可以按顺序读取索引。 +索引的列默认按列自己的排序规则比较,用 `COLLATE` 运算符可以给它指定另一种(同样是实验性 API): +`PersonTable.CREATE_INDEX("idx_person_name_nocase", PersonTable.name COLLATE NOCASE)` 就是 +`CREATE INDEX idx_person_name_nocase ON person(name COLLATE NOCASE)`,比较 `(name COLLATE NOCASE)` 的查询会用到它,而 `name` +在其他地方仍按字节比较。它也可以指定排序方向,例如 `(PersonTable.name COLLATE NOCASE) to DESC`。 + 在 `CREATE_INDEX` 或 `CREATE_UNIQUE_INDEX` 后面加上 `WHERE` 就是部分索引:只索引满足条件的行。它比索引所有行的索引更小,唯一的部分 索引只保证这些行之间的值不相同,例如未删除用户的邮箱。部分索引是实验性 API: @@ -146,6 +151,24 @@ fun sample() { } ``` +语句通过哪个索引查找行,由 SQLite 的查询规划器选择。`INDEXED_BY` 让它使用指定的索引,`NOT_INDEXED` 让它不使用索引,就像 SQL 的 +`INDEXED BY` 和 `NOT INDEXED` 那样。带有它们的表可以被 _SELECT_(包括 Join)读取,也可以被 _UPDATE_ 和 _DELETE_ 写入,但不能用于 +_INSERT_,因为 SQL 不允许。它们是实验性 API: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + database { + // SELECT ... FROM person INDEXED BY idx_person_name WHERE person.name = ? + (PersonTable INDEXED_BY "idx_person_name") SELECT WHERE(PersonTable.name EQ "Tom") + // DELETE FROM person NOT INDEXED WHERE person.age < ? + PersonTable.NOT_INDEXED DELETE WHERE(PersonTable.age LT 18) + } +} +``` + +如果 SQLite 无法通过指定的索引执行语句,比如索引不存在,语句会失败,并报 "no such index"。 + ### IF NOT EXISTS 与 IF EXISTS 表已存在时 `CREATE` 会失败,表不存在时 `DROP` 会失败。它们的 `IF NOT EXISTS` 和 `IF EXISTS` 版本则什么也不做,适用于表、视图和索引。 @@ -428,7 +451,8 @@ fun sample() { _INSERT_ 语句可以直接插入对象,你可以一次插入一个或多个对象。 -`INSERT_OR_IGNORE` 会跳过与表中已有行冲突的对象,`INSERT_OR_REPLACE` 则会替换那一行。它们接受的参数与 `INSERT` 相同。 +`INSERT_OR_IGNORE` 会跳过与表中已有行冲突的对象,`INSERT_OR_REPLACE` 则会替换那一行。它们接受的参数与 `INSERT` 相同,其他 +[冲突处理方式](#冲突处理)也一样。 _INSERT_ 还可以插入一条 _SELECT_ 返回的行,就像 `INSERT INTO ... SELECT` 那样,前提是这条 _SELECT_ 读出的是这张表的行类型。 这些行可以来自任意一张表,借助投影或结果列: @@ -581,6 +605,79 @@ fun sample() { 你也可以编写没有 _WHERE_ 子句的 _UPDATE_ 语句用于更新所有的行,但使用它的时候你应该谨慎。 +## 删除和更新中的 ORDER BY 与 LIMIT + +在 _DELETE_ 或 _UPDATE_ 后面(无论有没有 _WHERE_)加上 `LIMIT`,最多只删除或更新这么多行;在它前面再加上 `ORDER_BY`,就是按这个顺序 +排在前面的那些行。比如删除某个聊天中最新 100 条以外的消息,或者取出下一个要执行的任务。`LIMIT` 后面的 `OFFSET` 会先跳过这么多行; +`LIMIT` 为负数时表示不限制,这样 `OFFSET` 就会保留排在前面的行。它们是实验性 API: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + database { + MessageTable { table -> + // 删除这个聊天中最早的 10 条消息 + table DELETE WHERE(chatId EQ 1) ORDER_BY (time to ASC) LIMIT 10 + // 删除这个聊天中最新 100 条以外的消息 + table DELETE WHERE(chatId EQ 1) ORDER_BY (time to DESC) LIMIT -1 OFFSET 100 + // 最多删除 1000 条过期消息,作为分批删除中的一批 + table DELETE WHERE(expired IS true) LIMIT 1000 + } + TaskTable { table -> + // 开始执行优先级最高的待办任务 + table UPDATE SET { status = 1 } WHERE (status EQ 0) ORDER_BY (priority to DESC) LIMIT 1 + } + } +} +``` + +SQLite 只有在编译时打开 `SQLITE_ENABLE_UPDATE_DELETE_LIMIT` 选项,才接受 _DELETE_ 和 _UPDATE_ 中的 _ORDER BY_ 与 _LIMIT_,而 Android +的 SQLite 没有打开它;打开时,SQLite 会把它们改写成一个子查询,选出这些行的 rowid。所以 SQLlin 自己生成这个子查询,所有平台都能执行, +查询计划也完全相同: + +```sql +DELETE FROM message WHERE rowid IN (SELECT rowid FROM message WHERE message.chatId=? ORDER BY message.time ASC LIMIT 10) +``` + +它也可以写在触发器体里,而 SQLite 自己的语法在触发器里是不允许的,比如每次 INSERT 之后只保留最新消息的触发器。`INDEXED_BY` 和 +`NOT_INDEXED` 决定子查询如何查找这些行。如果表中有名为 `rowid` 的列,就改用 `_rowid_` 或 `oid` 读取 rowid。和 SQLite 的规定一样, +`ORDER_BY` 后面必须接 `LIMIT`:作用域中如果有 _DELETE_ 或 _UPDATE_ 的 `ORDER_BY` 后面没有接 `LIMIT`,在任何语句执行之前就会抛出 +`IllegalArgumentException`。 + +## 冲突处理 + +违反约束的语句会失败,并撤销它所做的修改,除非约束声明了别的处理方式,比如 `@Unique(onConflict = OnConflict.IGNORE)`。语句也可以 +指定自己的处理方式,它会取代约束的处理方式:`INSERT_OR_ABORT`、`INSERT_OR_FAIL`、`INSERT_OR_ROLLBACK`、`INSERT_OR_IGNORE` 和 +`INSERT_OR_REPLACE` 接受的参数与 `INSERT` 相同;`UPDATE_OR_ABORT`、`UPDATE_OR_FAIL`、`UPDATE_OR_IGNORE`、`UPDATE_OR_REPLACE` +和 `UPDATE_OR_ROLLBACK` 的写法与 `UPDATE` 相同。除了插入对象和 _SELECT_ 的 `INSERT_OR_IGNORE`、`INSERT_OR_REPLACE`,它们都是实验性 +API: + +| 处理方式 | 与 PRIMARY KEY、UNIQUE、NOT NULL 或 CHECK 约束冲突时 | +| --- | --- | +| `ABORT` | 语句失败,撤销它所做的修改,这是默认方式 | +| `FAIL` | 语句失败,但保留它在冲突行之前写入的行 | +| `ROLLBACK` | 语句失败,并回滚它所在的事务 | +| `IGNORE` | 跳过冲突的行,继续执行 | +| `REPLACE` | 删除在 PRIMARY KEY 或 UNIQUE 约束上冲突的行;NOT NULL 列要写入 NULL 时改写其默认值;违反 CHECK 约束时像 `ABORT` 一样失败 | + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + database { + // INSERT OR FAIL INTO person(id,name,age) VALUES (?,?,?),(?,?,?) + PersonTable INSERT_OR_FAIL listOf(tom, jerry) + PersonTable { table -> + // UPDATE OR IGNORE person SET name=? WHERE person.name=? + table UPDATE_OR_IGNORE SET { name = "Tom" } WHERE (name EQ "Thomas") + } + } +} +``` + +即使主键由数据库分配,_INSERT_ 语句也会写入主键,否则主键上的冲突无法被发现;主键为 null 时仍由数据库分配。无论语句指定哪种处理 +方式,违反 FOREIGN KEY 约束都会让语句失败。在 `transaction {...}` 中,失败的语句会结束事务并让它回滚,所以 `ABORT`、`FAIL` 和 +`ROLLBACK` 只在事务之外有区别:`FAIL` 会保留一条多行语句在冲突行之前写入的行,而 `ROLLBACK` 与 `ABORT` 效果相同。 + ## 事务 在 SQLlin 中使用事务非常简单,你只需要使用 `transaction {...}` 包裹你的 SQL 语句: @@ -607,6 +704,29 @@ fun sample() { 在所有平台上,事务都以 `BEGIN IMMEDIATE` 开始:它一开始就拿到写锁,所以要写入的其他连接或者其他事务,最多会按 `busyTimeout` 等待它结束。 +`transaction(mode) {...}` 可以用其他方式开始事务,它是实验性 API: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + database { + transaction(TransactionMode.EXCLUSIVE) { + PersonTable INSERT Person(age = 4, name = "Tom") + } + } +} +``` + +* `TransactionMode.IMMEDIATE` 是默认方式,一开始就拿到写锁。 +* `TransactionMode.EXCLUSIVE` 同样一开始就拿到写锁;在 `DELETE` 日志模式下,还会在事务结束前阻止其他连接读取。在 WAL 模式下,它与 + `IMMEDIATE` 相同。 +* `TransactionMode.DEFERRED` 在事务读取之前不拿任何锁,在写入之前不拿写锁,所以在此之前其他连接可以写入。但如果事务先读后写,而此时 + 另一个连接正在写入,它会立即以 "database is locked" 失败,不会按 `busyTimeout` 等待。Android 框架无法开始一个可以写入的 DEFERRED + 事务,所以在 Android 上它会以 `IMMEDIATE` 方式开始。 + +嵌套在另一个事务中的事务会并入外层事务,沿用外层的开始方式。使用 _sqllin-driver_ 时,`withTransaction(mode) {...}` 和 +`DatabaseConnection#beginTransaction(mode)` 同样可以指定开始方式。 + ## VACUUM 删除行并不会让数据库文件变小,因为 SQLite 会留着空闲页以便复用。`VACUUM()` 会重建数据库文件,把它压缩到最小的磁盘空间; @@ -648,6 +768,68 @@ fun sample() { } ``` +## PRAGMA + +SQLlin 支持用来检查数据库、读取表结构和 SQLite 自身的信息、执行 WAL 检查点、读取文件大小和文件头,以及设置语句执行方式的 +PRAGMA。读取类的 PRAGMA +返回一条语句,作用域执行完之后,用它的 `getResults()` 取得读到的内容,和 _SELECT_ 的结果一样。它们是实验性 API,结果类型 +都在 `com.ctrip.sqllin.dsl.sql.pragma` 包中: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + lateinit var problems: PragmaStatement> + lateinit var violations: PragmaStatement> + lateinit var columns: PragmaStatement> + database { + problems = PRAGMA_INTEGRITY_CHECK() + violations = PRAGMA_FOREIGN_KEY_CHECK() + columns = PRAGMA_TABLE_INFO(PersonTable) + } + if (problems.getResults().isNotEmpty()) { + // 数据库已损坏 + } + val hasEmail = columns.getResults().any { it.name == "email" } +} +``` + +* **检查数据库**:`PRAGMA_INTEGRITY_CHECK(maxErrors)` 检查页、行和索引是否完好、是否相互一致,以及行是否满足 NOT NULL 和 + CHECK 约束,返回发现的问题,没有问题时返回空列表;`PRAGMA_QUICK_CHECK(maxErrors)` 不检查索引和 UNIQUE 约束,其余相同,速度 + 更快。`PRAGMA_FOREIGN_KEY_CHECK()` 或 `PRAGMA_FOREIGN_KEY_CHECK(table)` 返回违反外键的行,不管外键是否启用,比如在关闭外键 + 做完迁移之后检查;`PRAGMA_FOREIGN_KEYS()` 返回外键是否启用。`PRAGMA_INTEGRITY_CHECK(table)` 和 `PRAGMA_QUICK_CHECK(table)` + 只检查一张表和它的索引。 +* **读取表结构**:`PRAGMA_TABLE_INFO(table)` 返回表或视图的列,可以在迁移时用来判断,`PRAGMA_INDEX_LIST(table)` 返回表的索引, + `PRAGMA_INDEX_XINFO(index)` 返回索引的列,包括排序方向和排序规则,`PRAGMA_FOREIGN_KEY_LIST(table)` 返回表的外键。它们也都可以 + 传入名字,比如应用已经不再声明的表。不存在的表或索引没有列、索引或外键。另一个连接(比如另一个进程)刚建的表或索引也可能这样, + 直到本连接执行一条读写表的语句为止:SQLite 找不到这个名字时,未必会检查之前读到的表结构是否已经过期。 + `PRAGMA_TABLE_XINFO(table)` 额外列出隐藏列和生成列,由 `ColumnInfo.kind` 区分,比如 FTS 表的隐藏列;`PRAGMA_TABLE_LIST()` + 返回 `main` 和 `temp` 中的表和视图,包括虚拟表,以及虚拟表用来存放数据的表。 +* **SQLite 自身的信息**:`PRAGMA_COMPILE_OPTIONS()` 返回 SQLite 的编译选项,`PRAGMA_COLLATION_LIST()` 返回排序规则, + `PRAGMA_DATABASE_LIST()` 返回连接上的数据库及其文件,`PRAGMA_FUNCTION_LIST()` 返回 SQL 函数,比如可以用来判断有没有数学函数, + `PRAGMA_MODULE_LIST()` 返回虚拟表模块(比如 `fts4`),`PRAGMA_PRAGMA_LIST()` 返回 SQLite 支持的 PRAGMA。 +* **数据库文件**:`PRAGMA_WAL_CHECKPOINT(mode)` 把 WAL 中的页复制进数据库文件,比如在复制数据库文件之前,因为文件里没有 WAL + 中的内容;SQLite 不能在事务中执行检查点,所以在 `transaction {...}` 中调用会抛出 `IllegalStateException`。 + `PRAGMA_PAGE_COUNT()` 乘以 `PRAGMA_PAGE_SIZE()` 就是文件的大小,`PRAGMA_FREELIST_COUNT()` 是文件中未使用的页数, + [`VACUUM()`](#vacuum) 会去掉这些页;开启了 auto_vacuum 的数据库(Android 的 SQLite 默认就这样创建数据库)每次提交都会去掉 + 它们,所以没有未使用的页。`PRAGMA_AUTO_VACUUM()` 返回是否开启了 auto_vacuum,`PRAGMA_AUTO_VACUUM(mode)` 设置它:对还没有表的 + 数据库立即生效,否则要在它之后执行一次 `VACUUM()` 重建数据库才生效。SQLlin 不执行 `PRAGMA incremental_vacuum`(`INCREMENTAL` + 模式保留的页要靠它去掉):它每返回一行才去掉一页,而这些行没有列,sqlite-jdbc 执行这样的语句只会执行到第一行。 + `PRAGMA_APPLICATION_ID()` 读取、`PRAGMA_APPLICATION_ID(id)` 设置文件头中标识文件属于哪个应用的数字。 +* **语句的执行方式**:`PRAGMA_DEFER_FOREIGN_KEYS(true)` 把外键检查推迟到提交时,这样就可以先插入引用其他行的行;SQLite 会在 + 事务结束时把它关掉,所以在 `transaction {...}` 之外调用会抛出 `IllegalStateException`。`PRAGMA_RECURSIVE_TRIGGERS(true)` + 允许触发器递归触发;`PRAGMA_LEGACY_ALTER_TABLE(true)` 让 `ALTER_RENAME_TABLE_TO` 不改写读取这张表的视图和触发器,Android 的 + SQLite 默认就是这样;`PRAGMA_IGNORE_CHECK_CONSTRAINTS(true)` 不再检查 CHECK 约束。这几个设置在数据库关闭之前一直有效,对之前 + 执行过的语句同样生效。 + +其中一些需要较新的 SQLite,有些平台没有,所以标有 [`@PlatformDependentSQLiteAPI`](#依赖-sqlite-版本的-api): +`PRAGMA_TABLE_XINFO` 需要 SQLite 3.26.0,Android 从 API 30 起才有;`PRAGMA_FUNCTION_LIST`、`PRAGMA_MODULE_LIST` 和 +`PRAGMA_PRAGMA_LIST` 需要 3.30.0,从 API 31 起;`PRAGMA_TABLE_LIST` 需要 3.37.0,从 API 34 起。SQLite 遇到不支持的 PRAGMA +不会报错,只会忽略,所以这些 API 会检查 SQLite 返回的行有没有列,没有就抛出 `IllegalStateException` 并说明需要什么,而不是 +返回空结果。`PRAGMA_INTEGRITY_CHECK(table)` 和 `PRAGMA_QUICK_CHECK(table)` 需要 SQLite 3.33.0(从 API 34 起),更早的版本会 +改为检查整个数据库。`PRAGMA_COMPILE_OPTIONS` 在 Android 上会抛出异常,因为 Android 的 SQLite 编译时去掉了它。 + +检查返回的问题描述是 SQLite 自己的文字。PRAGMA 不会修改任何表,所以可以写在 `versioned { }` 中。 + ## 接下来 你已经学习了如何使用 _INSERT_、_DELETE_ 以及 _UPDATE_ 语句,接下来你将学习 _SELECT_ 语句。 _SELECT_ 语句相比其他语句更复杂,做好准备哦 :)。 diff --git a/sqllin-dsl/doc/modify-database-and-transaction.md b/sqllin-dsl/doc/modify-database-and-transaction.md index f99982e0..0cedf39d 100644 --- a/sqllin-dsl/doc/modify-database-and-transaction.md +++ b/sqllin-dsl/doc/modify-database-and-transaction.md @@ -127,6 +127,12 @@ Each column of an index can be given the order it is sorted in, as `ORDER_BY` gi `PersonTable.CREATE_INDEX("idx_person_age", PersonTable.age to DESC)` is `CREATE INDEX idx_person_age ON person(age DESC)`. This is experimental. A query that sorts the columns in that order, or the reverse, reads the index in order. +A column of an index compares its values by the column's collation, unless the `COLLATE` operator gives it another, +which is experimental too: `PersonTable.CREATE_INDEX("idx_person_name_nocase", PersonTable.name COLLATE NOCASE)` is +`CREATE INDEX idx_person_name_nocase ON person(name COLLATE NOCASE)`, which a query that compares +`(name COLLATE NOCASE)` uses, while `name` keeps comparing its values by their bytes elsewhere. It can be given an order +too, as `(PersonTable.name COLLATE NOCASE) to DESC`. + `WHERE` after `CREATE_INDEX` or `CREATE_UNIQUE_INDEX` makes a partial index: an index of the rows that satisfy a condition only. It is smaller than an index of all rows, and a unique one keeps the values unique among those rows only, such as the emails of the users that aren't deleted. Partial indexes are experimental: @@ -156,6 +162,25 @@ fun sample() { } ``` +SQLite's query planner chooses the index a statement looks its rows up through. `INDEXED_BY` makes it use one, and +`NOT_INDEXED` none, as SQL's `INDEXED BY` and `NOT INDEXED` do. A table with them is read by a _SELECT_, joins included, +and written by _UPDATE_ and _DELETE_, but not by _INSERT_, which SQL doesn't allow. They are experimental: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + database { + // SELECT ... FROM person INDEXED BY idx_person_name WHERE person.name = ? + (PersonTable INDEXED_BY "idx_person_name") SELECT WHERE(PersonTable.name EQ "Tom") + // DELETE FROM person NOT INDEXED WHERE person.age < ? + PersonTable.NOT_INDEXED DELETE WHERE(PersonTable.age LT 18) + } +} +``` + +A statement fails when SQLite can't run it through the index given, as when the index doesn't exist, with +"no such index". + ### IF NOT EXISTS and IF EXISTS `CREATE` fails if the table already exists, and `DROP` if it doesn't. Their `IF NOT EXISTS` and `IF EXISTS` versions do @@ -458,7 +483,7 @@ fun sample() { The _INSERT_ statements could insert objects directly. You can insert one or multiple objects once. `INSERT_OR_IGNORE` skips the objects that conflict with a row already in the table, and `INSERT_OR_REPLACE` replaces -that row. They take the same arguments as `INSERT`. +that row. They take the same arguments as `INSERT`, as the other [conflict resolutions](#conflict-resolutions) do. _INSERT_ can also insert the rows a _SELECT_ returns, as `INSERT INTO ... SELECT` does, if the _SELECT_ reads rows of the table's type. They can come from any table, through a projection or result columns: @@ -618,6 +643,85 @@ statement is built. Use `literal(5)` for a value among expressions. You also could write the _UPDATE_ statements without the _WHERE_ clause that used for update all rows, but you should use it with caution. +## ORDER BY and LIMIT of DELETE and UPDATE + +`LIMIT` after a _DELETE_ or an _UPDATE_, with its _WHERE_ or without, makes it write at most as many rows, and +`ORDER_BY` before it the first of them in an order, as for the messages of a chat beyond the latest 100, or a task to +run next. `OFFSET` after `LIMIT` skips as many rows first, and a negative `LIMIT` is no limit, so that `OFFSET` keeps the +first rows. They are experimental: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + database { + MessageTable { table -> + // Deletes the 10 oldest messages of the chat + table DELETE WHERE(chatId EQ 1) ORDER_BY (time to ASC) LIMIT 10 + // Deletes the messages of the chat after the latest 100 + table DELETE WHERE(chatId EQ 1) ORDER_BY (time to DESC) LIMIT -1 OFFSET 100 + // Deletes at most 1000 expired messages, as one batch of many + table DELETE WHERE(expired IS true) LIMIT 1000 + } + TaskTable { table -> + // Starts the pending task of the highest priority + table UPDATE SET { status = 1 } WHERE (status EQ 0) ORDER_BY (priority to DESC) LIMIT 1 + } + } +} +``` + +SQLite only takes _ORDER BY_ and _LIMIT_ in a _DELETE_ or an _UPDATE_ when it is built with the +`SQLITE_ENABLE_UPDATE_DELETE_LIMIT` option, which Android's SQLite isn't, and then turns them into a subquery of the +rowids of the rows they choose. So SQLlin writes that subquery itself, which every platform runs, with the same query +plan: + +```sql +DELETE FROM message WHERE rowid IN (SELECT rowid FROM message WHERE message.chatId=? ORDER BY message.time ASC LIMIT 10) +``` + +It can also be in the body of a trigger, where SQLite's own syntax isn't allowed, as one that keeps the latest messages +after each INSERT. `INDEXED_BY` and `NOT_INDEXED` decide how the subquery looks the rows up. A table with a column named +`rowid` reads its rowid as `_rowid_`, or `oid`. `ORDER_BY` has to be followed by `LIMIT`, as SQLite says: a scope with an +`ORDER_BY` of a _DELETE_ or an _UPDATE_ that `LIMIT` doesn't follow throws an `IllegalArgumentException` before any of +its statements runs. + +## Conflict Resolutions + +A statement that violates a constraint fails, undoing what it changed, unless the constraint declares another +resolution, as `@Unique(onConflict = OnConflict.IGNORE)` does. A statement can choose its own, which takes the place of +the constraint's: `INSERT_OR_ABORT`, `INSERT_OR_FAIL`, `INSERT_OR_ROLLBACK`, `INSERT_OR_IGNORE` and `INSERT_OR_REPLACE` +take the same arguments as `INSERT`, and `UPDATE_OR_ABORT`, `UPDATE_OR_FAIL`, `UPDATE_OR_IGNORE`, `UPDATE_OR_REPLACE` and +`UPDATE_OR_ROLLBACK` are written as `UPDATE`. They are experimental, but `INSERT_OR_IGNORE` and `INSERT_OR_REPLACE` of +objects and of a _SELECT_: + +| Resolution | On a conflict with a PRIMARY KEY, UNIQUE, NOT NULL or CHECK constraint | +| --- | --- | +| `ABORT` | fails the statement, undoing what it changed, which is the default | +| `FAIL` | fails the statement, keeping the rows it wrote before the one that conflicts | +| `ROLLBACK` | fails the statement, rolling back the transaction it runs in | +| `IGNORE` | skips the row that conflicts, and goes on | +| `REPLACE` | deletes the rows that conflict on a PRIMARY KEY or UNIQUE constraint, writes the default value of a NOT NULL column instead of NULL, and fails as `ABORT` on a CHECK constraint | + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + database { + // INSERT OR FAIL INTO person(id,name,age) VALUES (?,?,?),(?,?,?) + PersonTable INSERT_OR_FAIL listOf(tom, jerry) + PersonTable { table -> + // UPDATE OR IGNORE person SET name=? WHERE person.name=? + table UPDATE_OR_IGNORE SET { name = "Tom" } WHERE (name EQ "Thomas") + } + } +} +``` + +The _INSERT_ statements write the primary key even when the database assigns it, as a conflict on it couldn't be seen +otherwise; a null key still lets the database assign one. A FOREIGN KEY violation fails the statement whatever its +resolution. In `transaction {...}`, a statement that fails ends the transaction, which is rolled back, so `ABORT`, +`FAIL` and `ROLLBACK` only differ outside one, where `FAIL` keeps the rows that a statement of several rows wrote before +the one that conflicts, and `ROLLBACK` does what `ABORT` does. + ## Transaction Using transaction is simple in SQLlin, you just need to use a `transaction {...}` wrap your SQL statements: @@ -645,6 +749,30 @@ The `transaction {...}` is a member function in `Database`, it is inside or outs A transaction begins with `BEGIN IMMEDIATE` on every platform: it takes the write lock at once, so another connection that writes, or another transaction, waits for it as long as its `busyTimeout`. +`transaction(mode) {...}` begins one in another mode, which is experimental: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + database { + transaction(TransactionMode.EXCLUSIVE) { + PersonTable INSERT Person(age = 4, name = "Tom") + } + } +} +``` + +* `TransactionMode.IMMEDIATE`, the default, takes the write lock at once. +* `TransactionMode.EXCLUSIVE` takes it at once too, and in `DELETE` journal mode also keeps other connections from + reading until the transaction ends. In WAL mode, it is the same as `IMMEDIATE`. +* `TransactionMode.DEFERRED` takes no lock until the transaction reads, nor the write lock until it writes, so other + connections can write until then. But a transaction that reads before it writes then fails at once with + "database is locked" while another connection writes, without waiting for `busyTimeout`. Android's framework can't + begin a deferred transaction that writes, so on Android it begins an `IMMEDIATE` one. + +A transaction in another one joins it, and keeps its mode. With _sqllin-driver_, `withTransaction(mode) {...}` and +`DatabaseConnection#beginTransaction(mode)` take a mode as well. + ## VACUUM Deleting rows doesn't shrink the database file, as SQLite keeps the free pages to reuse them. `VACUUM()` rebuilds the @@ -690,6 +818,80 @@ fun sample() { } ``` +## PRAGMA + +SQLlin builds the PRAGMAs that check the database, read its schema and what the SQLite has, checkpoint the WAL, read +the size and the header of the file, and set how statements run. A PRAGMA that reads returns a statement whose `getResults()` returns what it read once the scope +has run, as the results of a _SELECT_ are read. They are experimental, and their result types are in +`com.ctrip.sqllin.dsl.sql.pragma`: + +```kotlin +@OptIn(ExperimentalDSLDatabaseAPI::class) +fun sample() { + lateinit var problems: PragmaStatement> + lateinit var violations: PragmaStatement> + lateinit var columns: PragmaStatement> + database { + problems = PRAGMA_INTEGRITY_CHECK() + violations = PRAGMA_FOREIGN_KEY_CHECK() + columns = PRAGMA_TABLE_INFO(PersonTable) + } + if (problems.getResults().isNotEmpty()) { + // The database is corrupt + } + val hasEmail = columns.getResults().any { it.name == "email" } +} +``` + +* **Checking the database**: `PRAGMA_INTEGRITY_CHECK(maxErrors)` checks that the pages, rows and indexes are well-formed + and agree with each other, and that the rows satisfy their NOT NULL and CHECK constraints, and returns the problems, + or an empty list; `PRAGMA_QUICK_CHECK(maxErrors)` checks all but the indexes and UNIQUE constraints, more quickly. + `PRAGMA_FOREIGN_KEY_CHECK()`, or `PRAGMA_FOREIGN_KEY_CHECK(table)`, returns the rows that violate their foreign keys, + whether or not they are enforced, such as after a migration that turned them off, and `PRAGMA_FOREIGN_KEYS()` whether + they are. `PRAGMA_INTEGRITY_CHECK(table)` and `PRAGMA_QUICK_CHECK(table)` check a table and its indexes. +* **Reading the schema**: `PRAGMA_TABLE_INFO(table)` returns the columns of a table or a view, which a migration can + check, `PRAGMA_INDEX_LIST(table)` its indexes, `PRAGMA_INDEX_XINFO(index)` the columns of an index, with their sort + orders and collations, and `PRAGMA_FOREIGN_KEY_LIST(table)` its foreign keys. Each also takes a name, as of a table + the app no longer declares. A table or index that doesn't exist has no columns, indexes or foreign keys. One that + another connection, such as one in another process, has just created may look the same, until this one runs a + statement that reads or writes a table: when SQLite doesn't find the name, it may not check whether the schema it read + before is still current. `PRAGMA_TABLE_XINFO(table)` adds the hidden and generated columns, which `ColumnInfo.kind` + tells, as the hidden columns of an FTS table, and `PRAGMA_TABLE_LIST()` returns the tables and views, the virtual + ones, and the tables that these keep their data in, of `main` and `temp`. +* **What the SQLite has**: `PRAGMA_COMPILE_OPTIONS()` returns the options it was compiled with, `PRAGMA_COLLATION_LIST()` + its collations, `PRAGMA_DATABASE_LIST()` the databases of the connection and their files, `PRAGMA_FUNCTION_LIST()` its + SQL functions, such as to check whether it has the math functions, `PRAGMA_MODULE_LIST()` the modules of its virtual + tables, as `fts4`, and `PRAGMA_PRAGMA_LIST()` its PRAGMAs. +* **The file**: `PRAGMA_WAL_CHECKPOINT(mode)` copies the pages of the WAL into the database file, as before copying the + file, which doesn't hold what the WAL does; SQLite can't checkpoint inside a transaction, so it throws an + `IllegalStateException` inside `transaction {...}`. `PRAGMA_PAGE_COUNT()` times `PRAGMA_PAGE_SIZE()` is the size of the + file, and `PRAGMA_FREELIST_COUNT()` the number of its unused pages, which [`VACUUM()`](#vacuum) removes; a database + whose auto_vacuum is on, as Android's SQLite creates one by default, removes them at each commit, so it has none. + `PRAGMA_AUTO_VACUUM()` tells whether it is, and `PRAGMA_AUTO_VACUUM(mode)` sets it, which applies to a database that + has no tables yet, and otherwise once a `VACUUM()` after it rebuilds the database. SQLlin doesn't run + `PRAGMA incremental_vacuum`, which the `INCREMENTAL` mode keeps the pages for: it removes a page each time it returns a + row, which has no columns, and sqlite-jdbc runs such a statement only as far as its first row. + `PRAGMA_APPLICATION_ID()` reads, and `PRAGMA_APPLICATION_ID(id)` sets, the number of the header that tells the app the + file belongs to. +* **How statements run**: `PRAGMA_DEFER_FOREIGN_KEYS(true)` defers the checks of foreign keys to the commit, so that a + row can be inserted before the row it references; SQLite turns it off when the transaction ends, so it throws an + `IllegalStateException` outside `transaction {...}`. `PRAGMA_RECURSIVE_TRIGGERS(true)` lets triggers fire + recursively, `PRAGMA_LEGACY_ALTER_TABLE(true)` makes `ALTER_RENAME_TABLE_TO` leave the views and triggers that read the + table as they are, which Android's SQLite does by default, and `PRAGMA_IGNORE_CHECK_CONSTRAINTS(true)` stops checking + CHECK constraints. These last as long as the database is open, and apply to the statements that ran before them too. + +Some of them need a newer SQLite than some platforms have, so they are marked with +[`@PlatformDependentSQLiteAPI`](#apis-that-depend-on-the-sqlite-version): `PRAGMA_TABLE_XINFO` needs SQLite 3.26.0, +which Android has from API 30 on, `PRAGMA_FUNCTION_LIST`, `PRAGMA_MODULE_LIST` and `PRAGMA_PRAGMA_LIST` 3.30.0, from API +31 on, and `PRAGMA_TABLE_LIST` 3.37.0, from API 34 on. SQLite ignores a PRAGMA it doesn't have, rather than failing, so +that these check the columns of the rows SQLite returns, and throw an `IllegalStateException` that tells what they need +rather than return nothing. `PRAGMA_INTEGRITY_CHECK(table)` and `PRAGMA_QUICK_CHECK(table)` need SQLite 3.33.0, from API +34 on, below which they check the whole database. `PRAGMA_COMPILE_OPTIONS` throws on Android, whose SQLite is built +without it. + +The details of the problems that the checks return are SQLite's own text. A PRAGMA changes no table, so it can be in +a scope of `versioned { }`. + ## Next Step You have learned how to use _INSERT_, _DELETE_ and _UPDATE_ statements. Next step you will learn _SELECT_ statements. The diff --git a/sqllin-dsl/doc/sql-functions-cn.md b/sqllin-dsl/doc/sql-functions-cn.md index 01c0fffe..cd7a91d9 100644 --- a/sqllin-dsl/doc/sql-functions-cn.md +++ b/sqllin-dsl/doc/sql-functions-cn.md @@ -112,7 +112,9 @@ fun sample() { `notes ISNOT literal("vip")` 也会匹配 `notes` 为 NULL 的行,而 `notes NEQ literal("vip")` 会把它们排除掉。它们的作用和 `IS DISTINCT FROM` 相同,并且所有版本的 SQLite 都支持。 - `COLLATE` 按指定的排序规则(`BINARY`、`NOCASE` 或 `RTRIM`)比较和排序字符串:`(name COLLATE NOCASE) EQ "ann"` 也会匹配 - `'Ann'`,`ORDER_BY((name COLLATE NOCASE) to ASC)` 会忽略大小写排序。`NOCASE` 只忽略 ASCII 字母的大小写。 + `'Ann'`,`ORDER_BY((name COLLATE NOCASE) to ASC)` 会忽略大小写排序。`NOCASE` 只忽略 ASCII 字母的大小写。它还可以给索引的某一列 + 指定排序规则,见 [CREATE INDEX](modify-database-and-transaction-cn.md#create-index---创建索引);而列本身的排序规则由 + `@CollateNoCase` 和 `@CollateRTrim` 声明。 - `and`、`or`、`inv()`、`shl` 和 `shr` 是 `Int` 和 `Long` 的位运算,名字和 Kotlin 自己的一致。 - 只返回一列的 _SELECT_ 可以作为一个值,详见[标量子查询](advanced-query-cn.md#标量子查询)。 diff --git a/sqllin-dsl/doc/sql-functions.md b/sqllin-dsl/doc/sql-functions.md index 405e8a93..1699c102 100644 --- a/sqllin-dsl/doc/sql-functions.md +++ b/sqllin-dsl/doc/sql-functions.md @@ -125,7 +125,9 @@ fun sample() { `notes NEQ literal("vip")` leaves out. They do what `IS DISTINCT FROM` does, on every SQLite version. - `COLLATE` compares and sorts a string by a collation, `BINARY`, `NOCASE` or `RTRIM`: `(name COLLATE NOCASE) EQ "ann"` matches `'Ann'` too, and `ORDER_BY((name COLLATE NOCASE) to ASC)` sorts ignoring - case. `NOCASE` only ignores the case of the ASCII letters. + case. `NOCASE` only ignores the case of the ASCII letters. It also gives a column of an index its collation, as + [CREATE INDEX](modify-database-and-transaction.md#create-index---creating-indexes) describes, while `@CollateNoCase` + and `@CollateRTrim` give a column its own. - `and`, `or`, `inv()`, `shl` and `shr` are the bitwise operators of `Int` and `Long`, named as Kotlin names them. - A _SELECT_ of a single column can be a value, as described in [Scalar Subqueries](advanced-query.md#scalar-subqueries). diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/Database.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/Database.kt index 14753c88..949e08ff 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/Database.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/Database.kt @@ -18,11 +18,13 @@ package com.ctrip.sqllin.dsl import com.ctrip.sqllin.driver.DatabaseConnection import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import com.ctrip.sqllin.dsl.sql.statement.Changes import com.ctrip.sqllin.dsl.sql.statement.SelectStatement import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.IO import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.distinctUntilChanged +import kotlinx.coroutines.flow.first import kotlinx.coroutines.flow.flow import kotlinx.coroutines.flow.flowOn import kotlinx.coroutines.sync.Mutex @@ -78,13 +80,13 @@ public class Database internal constructor( public operator fun invoke(block: DatabaseScope.() -> T): T { val databaseScope = DatabaseScope(databaseConnection, enableSimpleSQLLog) val result = databaseScope.block() - execute(databaseScope) + notifyingChanges { execute(databaseScope) } return result } /** - * The tracker of the tables that observed queries read, which the first observed query creates, so that the code of - * a database that observes no query doesn't reach the tracker, which code shrinkers then remove. + * The tracker of the tables that observed queries and versioned reads read, which the first of them creates, so + * that the code of a database that uses neither doesn't reach the tracker, which code shrinkers then remove. */ @Volatile private var invalidationTracker: InvalidationTracker? = null @@ -111,6 +113,21 @@ public class Database internal constructor( invalidationTracker?.refresh(changes, writtenTables) } + /** + * Runs [run], which executes a scope, then the callbacks of [onChange] whose tables it changed. They run once the + * executive lock is released, so that a callback that uses the database doesn't wait for it forever, and even when + * a statement fails, as the ones before it may have changed something. + */ + private inline fun notifyingChanges(run: () -> Unit) { + try { + run() + } catch (e: Throwable) { + runCatching { invalidationTracker?.dispatch() }.exceptionOrNull()?.let(e::addSuppressed) + throw e + } + invalidationTracker?.dispatch() + } + private val executiveMutex by lazy { Mutex() } /** @@ -125,8 +142,10 @@ public class Database internal constructor( public suspend infix fun suspendedScope(block: suspend DatabaseScope.() -> T): T { val databaseScope = DatabaseScope(databaseConnection, enableSimpleSQLLog) val result = databaseScope.block() - executiveMutex.withLock { - execute(databaseScope) + notifyingChanges { + executiveMutex.withLock { + execute(databaseScope) + } } return result } @@ -178,4 +197,82 @@ public class Database internal constructor( emit(statement.getResults()) } }.distinctUntilChanged().flowOn(context) + + /** + * Runs the read-only scope [block], and returns its result with a token of the versions of the tables its SELECTs + * read, so that a reader such as a `PagingSource` learns when they change, which [awaitChange] and [onChange] tell. + * + * Example: + * ```kotlin + * val (page, since) = database.versioned { + * PersonTable SELECT ORDER_BY(PersonTable.age to ASC) LIMIT 20 OFFSET 40 + * } + * val persons = page.getResults() + * // Once a statement run through this database changes the person table + * database.awaitChange(since) + * ``` + * + * The tables are tracked, and their versions captured, under the lock that the SELECTs run under, before they run, + * so that no change made after them is missed; a change they already include may make the token stale too. A view + * stands for the tables it reads, and a subquery's tables count. The token only sees the changes made through this + * database, as [observe] does. To cover reads of several scopes, as when a query is built from the results of + * another, combine their tokens with [TableVersions.plus]. + * + * @param block Builds the SELECTs to run, which are its only statements + * @return The result of [block], and the token of the versions of the tables its SELECTs read + * @throws IllegalArgumentException if [block] writes, as its token couldn't tell its own changes from others', + * in which case none of its statements run + */ + @ExperimentalDSLDatabaseAPI + public suspend fun versioned(block: suspend DatabaseScope.() -> T): Pair { + val databaseScope = DatabaseScope(databaseConnection, enableSimpleSQLLog) + val result = databaseScope.block() + require(databaseScope.changes == Changes.NONE) { + "versioned { } only runs SELECTs, as its token couldn't tell its own changes from others': write in another scope." + } + val tracker = invalidationTracker() + val versions = executiveMutex.withLock { + // Tracked before the SELECTs run, so that no change after them is missed + val tables = tracker.track(databaseScope.readTables) + val versions = tables.associateWith { tracker.versions.value[it] ?: 0L } + execute(databaseScope) + versions + } + return result to TableVersions(tracker, versions) + } + + /** + * Suspends until a statement run through this database changes one of the tables of [since], or returns at once + * if one already has. + * + * @throws IllegalArgumentException if [since] is a token of another database + */ + @ExperimentalDSLDatabaseAPI + public suspend fun awaitChange(since: TableVersions) { + trackerOf(since).versions.first { since.isStaleIn(it) } + } + + /** + * Registers [callback] to run once, when a statement run through this database changes one of the tables of + * [since], unless one already has: then it registers nothing and returns null, so that the caller acts on the change + * itself, as a `PagingSource` returns `LoadResult.Invalid()`. It registers before it checks, so that a change between + * the read and the registration either makes it return null or runs [callback], never neither. + * + * [callback] runs on the thread that wrote, once the writing scope has released the database's lock, so it may use + * the database, but should return quickly, as the scope's caller waits for it. The registration holds [callback] + * until it runs or is closed. + * + * @return What closes the registration, so that [callback] no longer runs, or null when [since] is already stale + * @throws IllegalArgumentException if [since] is a token of another database + */ + @ExperimentalDSLDatabaseAPI + public fun onChange(since: TableVersions, callback: () -> Unit): AutoCloseable? = + trackerOf(since).register(since, callback) + + @OptIn(ExperimentalDSLDatabaseAPI::class) + private fun trackerOf(since: TableVersions): InvalidationTracker { + val tracker = invalidationTracker + require(tracker != null && since.tracker === tracker) { "The token belongs to another database, whose changes this one doesn't see." } + return tracker + } } \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DatabaseScope.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DatabaseScope.kt index 4984d626..d610e6da 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DatabaseScope.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DatabaseScope.kt @@ -17,6 +17,7 @@ package com.ctrip.sqllin.dsl import com.ctrip.sqllin.driver.DatabaseConnection +import com.ctrip.sqllin.driver.TransactionMode import com.ctrip.sqllin.dsl.annotation.AdvancedInsertAPI import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI import com.ctrip.sqllin.dsl.annotation.KeyWordDslMaker @@ -29,6 +30,7 @@ import com.ctrip.sqllin.dsl.sql.FtsTable import com.ctrip.sqllin.dsl.sql.ProjectedX import com.ctrip.sqllin.dsl.sql.RaiseIgnore import com.ctrip.sqllin.dsl.sql.RaiseResolution +import com.ctrip.sqllin.dsl.sql.IndexedTable import com.ctrip.sqllin.dsl.sql.Relation import com.ctrip.sqllin.dsl.sql.Table import com.ctrip.sqllin.dsl.sql.TriggerDefinition @@ -52,13 +54,13 @@ import com.ctrip.sqllin.dsl.sql.operation.Select import com.ctrip.sqllin.dsl.sql.operation.Trigger import com.ctrip.sqllin.dsl.sql.operation.Update import com.ctrip.sqllin.dsl.sql.operation.Vacuum +import com.ctrip.sqllin.dsl.sql.pragma.* import com.ctrip.sqllin.dsl.sql.statement.* import kotlinx.serialization.ExperimentalSerializationApi import kotlinx.serialization.KSerializer import kotlinx.serialization.descriptors.SerialDescriptor import kotlinx.serialization.modules.EmptySerializersModule import kotlinx.serialization.serializer -import kotlin.concurrent.Volatile import kotlin.jvm.JvmName import kotlin.reflect.KProperty1 @@ -92,6 +94,11 @@ import kotlin.reflect.KProperty1 * For the same reason a query's result cannot inform a write in the same scope: a read-modify-write * has to be split into two scopes. * + * **A scope isn't thread-safe**: use it only in the code that runs its block, and don't call its functions from + * threads or coroutines that run at the same time, as coroutines launched in the block of `suspendedScope` on a + * dispatcher of several threads would. A block that suspends may resume on another thread, which is safe, as the steps + * of a coroutine run one after another. + * * Example: * ```kotlin * // Create and modify table structure @@ -130,34 +137,50 @@ public class DatabaseScope internal constructor( // ========== Transaction Management ========== - @Volatile private var transactionStatementsGroup: TransactionStatementsGroup? = null private inline val isInTransaction get() = transactionStatementsGroup != null /** - * Begins a new transaction. + * How deeply the transactions being built are nested: 1 in the outermost one, and 0 outside any. Only the outermost + * one collects statements, and only its end ends it, so that the statements after an inner one are still in it. + */ + private var transactionDepth = 0 + + /** + * Begins a new transaction, which begins IMMEDIATE, unless one has begun already, whose statements the new ones + * join. Each call has to be followed by one of [endTransaction], as [transaction] does. + * + * @return `true` if transaction started successfully, `false` if already in a transaction + */ + public fun beginTransaction(): Boolean = beginTransaction(TransactionMode.IMMEDIATE) + + /** + * Begins a new transaction, which begins in [mode], unless one has begun already, whose statements the new ones join. * * @return `true` if transaction started successfully, `false` if already in a transaction */ - public fun beginTransaction(): Boolean { + @PublishedApi + internal fun beginTransaction(mode: TransactionMode): Boolean { check(triggerBody == null) { "A transaction can't begin in the body of a trigger, which runs in the statement that fires it." } - if (isInTransaction) + if (transactionDepth++ > 0) return false - transactionStatementsGroup = TransactionStatementsGroup(databaseConnection, enableSimpleSQLLog) + transactionStatementsGroup = TransactionStatementsGroup(databaseConnection, enableSimpleSQLLog, mode) executiveEngine.addStatement(transactionStatementsGroup!!) return true } /** - * Ends the current transaction. + * Ends the transaction that the last [beginTransaction] began, so that the statements after it aren't in it. A + * transaction in another one only ends itself: its statements are the outer one's, and so are those after it, + * until the outer one ends. * - * The transaction will be committed or rolled back based on whether - * [endTransaction] was called. + * The statements run, and the transaction commits, or rolls back if one of them fails, once the scope ends. */ public fun endTransaction() { - transactionStatementsGroup = null + if (transactionDepth > 0 && --transactionDepth == 0) + transactionStatementsGroup = null } /** @@ -166,6 +189,9 @@ public class DatabaseScope internal constructor( * If the block completes successfully, the transaction is committed. * If an exception is thrown, the transaction is rolled back. * + * A transaction in another one joins it: its statements, and those after it, are the outer one's, which commits or + * rolls back all of them. + * * @param block The block of SQL statements to execute * @return The result of the block */ @@ -178,6 +204,35 @@ public class DatabaseScope internal constructor( } } + /** + * Executes a block of SQL statements as a single transaction, which begins in [mode], as SQL's `BEGIN DEFERRED`, + * `BEGIN IMMEDIATE` or `BEGIN EXCLUSIVE` does, which decides when it takes the write lock. [transaction] without a + * mode begins IMMEDIATE. + * + * Example: + * ```kotlin + * transaction(TransactionMode.EXCLUSIVE) { + * PersonTable INSERT person + * } + * ``` + * + * A transaction in another one joins it, whose mode it keeps. Android's framework can't begin a DEFERRED transaction + * that writes, so there it begins an IMMEDIATE one. + * + * @param mode How the transaction begins + * @param block The block of SQL statements to execute + * @return The result of the block + */ + @ExperimentalDSLDatabaseAPI + public inline fun transaction(mode: TransactionMode, block: DatabaseScope.() -> T): T { + beginTransaction(mode) + try { + return block() + } finally { + endTransaction() + } + } + // ========== Statement Execution Management ========== private val executiveEngine = DatabaseExecuteEngine(enableSimpleSQLLog) @@ -197,12 +252,7 @@ public class DatabaseScope internal constructor( private val currentContainer: StatementContainer get() = triggerBody ?: transactionStatementsGroup ?: executiveEngine - private fun addSelectStatement(statement: SelectStatement) { - if (unionSelectStatementGroupStack.isNotEmpty()) - (unionSelectStatementGroupStack.last() as UnionSelectStatementGroup).addSelectStatement(statement) - else - addStatement(statement) - } + private fun addSelectStatement(statement: SelectStatement) = addStatement(statement) internal fun executeAllStatements() { check(definingTrigger == null) { @@ -223,6 +273,12 @@ public class DatabaseScope internal constructor( internal val writtenTables: Set get() = executiveEngine.writtenTables + /** + * The tables and views the SELECTs of this scope read. + */ + internal val readTables: Set + get() = executiveEngine.readTables + // ========== INSERT Operations ========== /** @@ -347,7 +403,7 @@ public class DatabaseScope internal constructor( */ @StatementDslMaker public infix fun Table.INSERT_OR_REPLACE(entities: Iterable) { - val statement = Insert.insertOrReplace(this, databaseConnection, entities) + val statement = Insert.insertOr("INSERT OR REPLACE INTO ", this, databaseConnection, entities) addStatement(statement) } @@ -396,7 +452,7 @@ public class DatabaseScope internal constructor( */ @StatementDslMaker public infix fun Table.INSERT_OR_IGNORE(entities: Iterable) { - val statement = Insert.insertOrIgnore(this, databaseConnection, entities) + val statement = Insert.insertOr("INSERT OR IGNORE INTO ", this, databaseConnection, entities) addStatement(statement) } @@ -566,6 +622,165 @@ public class DatabaseScope internal constructor( public infix fun Table.INSERT_OR_REPLACE(select: SelectStatement): Unit = insert("INSERT OR REPLACE INTO ", select) + // ========== INSERT OR ABORT, OR FAIL and OR ROLLBACK ========== + // + // Like INSERT_OR_IGNORE and INSERT_OR_REPLACE, they write the primary key even when the database assigns it, so that + // a conflict on it is seen; a null key still lets the database assign one. + + /** + * Inserts [entities], and fails the statement on a conflict with a constraint, undoing what it changed, as SQL's `INSERT OR ABORT` does: + * what a plain [INSERT] does, but in place of the conflict clause of a constraint, such as + * `@Unique(onConflict = OnConflict.IGNORE)`. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_ABORT(entities: Iterable): Unit = + addStatement(Insert.insertOr("INSERT OR ABORT INTO ", this, databaseConnection, entities)) + + /** + * Inserts [entity], and fails on a conflict, undoing the statement, as `INSERT_OR_ABORT(listOf(entity))` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_ABORT(entity: T): Unit = INSERT_OR_ABORT(listOf(entity)) + + /** + * Inserts a row of expressions, and fails on a conflict, undoing the statement, as SQL's `INSERT OR ABORT` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + @JvmName("insertOrAbortExpressions") + public infix fun Table.INSERT_OR_ABORT(values: Iterable>): Unit = + addStatement(Insert.insert("INSERT OR ABORT INTO ", this, databaseConnection, values)) + + /** + * Inserts a row of a single expression, and fails on a conflict, undoing the statement. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_ABORT(value: ResultColumn): Unit = INSERT_OR_ABORT(listOf(value)) + + /** + * Inserts a row of the default values of all columns, and fails on a conflict, undoing the statement, as SQL's + * `INSERT OR ABORT INTO table DEFAULT VALUES` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_ABORT(defaultValues: DefaultValues): Unit = + addStatement(Insert.insertDefaultValues("INSERT OR ABORT INTO ", this, databaseConnection)) + + /** + * Inserts the rows [select] returns, and fails on a conflict, undoing the statement, as SQL's `INSERT OR ABORT INTO table SELECT ...` does. + * + * @see INSERT + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_ABORT(select: SelectStatement): Unit = + insert("INSERT OR ABORT INTO ", select) + + /** + * Inserts [entities], and fails the statement on a conflict with a constraint, keeping the rows it inserted before the one that + * conflicts, as SQL's `INSERT OR FAIL` does, in place of the conflict clause of the constraint. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_FAIL(entities: Iterable): Unit = + addStatement(Insert.insertOr("INSERT OR FAIL INTO ", this, databaseConnection, entities)) + + /** + * Inserts [entity], and fails on a conflict, keeping the rows inserted before, as `INSERT_OR_FAIL(listOf(entity))` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_FAIL(entity: T): Unit = INSERT_OR_FAIL(listOf(entity)) + + /** + * Inserts a row of expressions, and fails on a conflict, keeping the rows inserted before, as SQL's `INSERT OR FAIL` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + @JvmName("insertOrFailExpressions") + public infix fun Table.INSERT_OR_FAIL(values: Iterable>): Unit = + addStatement(Insert.insert("INSERT OR FAIL INTO ", this, databaseConnection, values)) + + /** + * Inserts a row of a single expression, and fails on a conflict, keeping the rows inserted before. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_FAIL(value: ResultColumn): Unit = INSERT_OR_FAIL(listOf(value)) + + /** + * Inserts a row of the default values of all columns, and fails on a conflict, keeping the rows inserted before, as SQL's + * `INSERT OR FAIL INTO table DEFAULT VALUES` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_FAIL(defaultValues: DefaultValues): Unit = + addStatement(Insert.insertDefaultValues("INSERT OR FAIL INTO ", this, databaseConnection)) + + /** + * Inserts the rows [select] returns, and fails on a conflict, keeping the rows inserted before, as SQL's `INSERT OR FAIL INTO table SELECT ...` does. + * + * @see INSERT + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_FAIL(select: SelectStatement): Unit = + insert("INSERT OR FAIL INTO ", select) + + /** + * Inserts [entities], and rolls back the transaction it runs in on a conflict with a constraint, as SQL's `INSERT OR ROLLBACK` does, + * in place of the conflict clause of the constraint; outside a transaction, it fails as [INSERT_OR_ABORT] does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_ROLLBACK(entities: Iterable): Unit = + addStatement(Insert.insertOr("INSERT OR ROLLBACK INTO ", this, databaseConnection, entities)) + + /** + * Inserts [entity], and rolls back the transaction on a conflict, as `INSERT_OR_ROLLBACK(listOf(entity))` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_ROLLBACK(entity: T): Unit = INSERT_OR_ROLLBACK(listOf(entity)) + + /** + * Inserts a row of expressions, and rolls back the transaction on a conflict, as SQL's `INSERT OR ROLLBACK` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + @JvmName("insertOrRollbackExpressions") + public infix fun Table.INSERT_OR_ROLLBACK(values: Iterable>): Unit = + addStatement(Insert.insert("INSERT OR ROLLBACK INTO ", this, databaseConnection, values)) + + /** + * Inserts a row of a single expression, and rolls back the transaction on a conflict. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_ROLLBACK(value: ResultColumn): Unit = INSERT_OR_ROLLBACK(listOf(value)) + + /** + * Inserts a row of the default values of all columns, and rolls back the transaction on a conflict, as SQL's + * `INSERT OR ROLLBACK INTO table DEFAULT VALUES` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_ROLLBACK(defaultValues: DefaultValues): Unit = + addStatement(Insert.insertDefaultValues("INSERT OR ROLLBACK INTO ", this, databaseConnection)) + + /** + * Inserts the rows [select] returns, and rolls back the transaction on a conflict, as SQL's `INSERT OR ROLLBACK INTO table SELECT ...` does. + * + * @see INSERT + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.INSERT_OR_ROLLBACK(select: SelectStatement): Unit = + insert("INSERT OR ROLLBACK INTO ", select) + private fun Table.insert(insert: String, select: SelectStatement) { select.checkComplete() select.container removeStatement select @@ -578,46 +793,163 @@ public class DatabaseScope internal constructor( /** * Updates records in the table with SET clause. * - * Can be followed by WHERE to target specific records. + * Can be followed by WHERE to target specific records, and by ORDER BY and LIMIT, to update the first of them in + * an order. * * Example: * ```kotlin * PersonTable UPDATE SET { name = "Alice" } WHERE (age GTE 18) + * PersonTable UPDATE SET { name = "Alice" } WHERE (age GTE 18) ORDER_BY (age to ASC) LIMIT 1 * ``` */ @StatementDslMaker public infix fun Table.UPDATE(clause: SetClause): UpdateStatementWithoutWhereClause = Update.update(this, databaseConnection, currentContainer, clause).also { addStatement(it) } + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE] does, and fails the statement on a conflict with a constraint, undoing what it changed: what a plain [UPDATE] does, but in + * place of the conflict clause of a constraint, such as `@Unique(onConflict = OnConflict.IGNORE)`, as SQL's `UPDATE OR ABORT` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.UPDATE_OR_ABORT(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(this, databaseConnection, currentContainer, clause, "UPDATE OR ABORT ").also { addStatement(it) } + + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE] does, and fails the statement on a conflict with a constraint, keeping the rows it updated before the one that conflicts, as SQL's `UPDATE OR FAIL` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.UPDATE_OR_FAIL(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(this, databaseConnection, currentContainer, clause, "UPDATE OR FAIL ").also { addStatement(it) } + + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE] does, and leaves each row whose new values would conflict with a constraint as it was, and goes on, as SQL's `UPDATE OR IGNORE` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.UPDATE_OR_IGNORE(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(this, databaseConnection, currentContainer, clause, "UPDATE OR IGNORE ").also { addStatement(it) } + + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE] does, and deletes the rows that a row's new values conflict with on a PRIMARY KEY or UNIQUE constraint, writes the + * default value of a NOT NULL column it would set to NULL, and fails on a CHECK constraint, as SQL's `UPDATE OR REPLACE` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.UPDATE_OR_REPLACE(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(this, databaseConnection, currentContainer, clause, "UPDATE OR REPLACE ").also { addStatement(it) } + + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE] does, and rolls back the transaction it runs in on a conflict with a constraint, and outside a transaction fails as + * [UPDATE_OR_ABORT] does, as SQL's `UPDATE OR ROLLBACK` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun Table.UPDATE_OR_ROLLBACK(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(this, databaseConnection, currentContainer, clause, "UPDATE OR ROLLBACK ").also { addStatement(it) } + // ========== DELETE Operations ========== /** - * Deletes all records from the table. + * Deletes all records from the table, or the first in an order, which ORDER BY and LIMIT that follow choose. * * Example: * ```kotlin * PersonTable DELETE X + * PersonTable DELETE X ORDER_BY (PersonTable.age to ASC) LIMIT 10 * ``` */ @StatementDslMaker - public infix fun Table<*>.DELETE(x: X) { - val statement = Delete.deleteAllEntities(this, databaseConnection) - addStatement(statement) - } + public infix fun Table.DELETE(x: X): WhereUpdateDeleteStatement = + Delete.deleteAllEntities(this, databaseConnection, currentContainer).also { addStatement(it) } /** - * Deletes records matching the WHERE clause. + * Deletes records matching the WHERE clause, or the first of them in an order, which ORDER BY and LIMIT that follow + * choose. * * Example: * ```kotlin * PersonTable DELETE WHERE(age LT 18) + * PersonTable DELETE WHERE(age LT 18) ORDER_BY (age to ASC) LIMIT 10 * ``` */ @StatementDslMaker - public infix fun Table.DELETE(clause: WhereClause) { - val statement = Delete.delete(this, databaseConnection, clause) - addStatement(statement) - } + public infix fun Table.DELETE(clause: WhereClause): WhereUpdateDeleteStatement = + Delete.delete(this, databaseConnection, currentContainer, clause).also { addStatement(it) } + + // ========== UPDATE and DELETE of a table with INDEXED BY or NOT INDEXED ========== + + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE] does, looking them up as `INDEXED BY` or + * `NOT INDEXED` says, as SQL's `UPDATE table INDEXED BY index` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun IndexedTable.UPDATE(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(table, databaseConnection, currentContainer, clause, target = fromSQL).also { addStatement(it) } + + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE_OR_ABORT] does, looking them up as `INDEXED BY` or + * `NOT INDEXED` says. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun IndexedTable.UPDATE_OR_ABORT(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(table, databaseConnection, currentContainer, clause, "UPDATE OR ABORT ", fromSQL).also { addStatement(it) } + + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE_OR_FAIL] does, looking them up as `INDEXED BY` or + * `NOT INDEXED` says. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun IndexedTable.UPDATE_OR_FAIL(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(table, databaseConnection, currentContainer, clause, "UPDATE OR FAIL ", fromSQL).also { addStatement(it) } + + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE_OR_IGNORE] does, looking them up as `INDEXED BY` or + * `NOT INDEXED` says. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun IndexedTable.UPDATE_OR_IGNORE(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(table, databaseConnection, currentContainer, clause, "UPDATE OR IGNORE ", fromSQL).also { addStatement(it) } + + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE_OR_REPLACE] does, looking them up as `INDEXED BY` or + * `NOT INDEXED` says. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun IndexedTable.UPDATE_OR_REPLACE(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(table, databaseConnection, currentContainer, clause, "UPDATE OR REPLACE ", fromSQL).also { addStatement(it) } + + /** + * Updates the rows that WHERE selects with [clause], as [UPDATE_OR_ROLLBACK] does, looking them up as `INDEXED BY` or + * `NOT INDEXED` says. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun IndexedTable.UPDATE_OR_ROLLBACK(clause: SetClause): UpdateStatementWithoutWhereClause = + Update.update(table, databaseConnection, currentContainer, clause, "UPDATE OR ROLLBACK ", fromSQL).also { addStatement(it) } + + /** + * Deletes all rows of the table, looking them up as `INDEXED BY` or `NOT INDEXED` says. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun IndexedTable.DELETE(x: X): WhereUpdateDeleteStatement = + Delete.deleteAllEntities(table, databaseConnection, currentContainer, fromSQL).also { addStatement(it) } + + /** + * Deletes the rows that [clause] selects, looking them up as `INDEXED BY` or `NOT INDEXED` says, as SQL's + * `DELETE FROM table INDEXED BY index WHERE ...` does. + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun IndexedTable.DELETE(clause: WhereClause): WhereUpdateDeleteStatement = + Delete.delete(table, databaseConnection, currentContainer, clause, fromSQL).also { addStatement(it) } // ========== SELECT Operations ========== @@ -641,7 +973,7 @@ public class DatabaseScope internal constructor( select(kSerializer(), true) public fun Relation.select(serializer: KSerializer, isDistinct: Boolean): FinalSelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(From.of(this), isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -666,7 +998,7 @@ public class DatabaseScope internal constructor( select(kSerializer(), clause, true) public fun Relation.select(serializer: KSerializer, clause: WhereClause, isDistinct: Boolean): WhereSelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(From.of(this), clause, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -689,7 +1021,7 @@ public class DatabaseScope internal constructor( select(kSerializer(), clause, true) public fun Relation.select(serializer: KSerializer, clause: OrderByClause, isDistinct: Boolean): OrderBySelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(From.of(this), clause, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -712,7 +1044,7 @@ public class DatabaseScope internal constructor( select(kSerializer(), clause, true) public fun Relation.select(serializer: KSerializer, clause: LimitClause, isDistinct: Boolean): LimitSelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(From.of(this), clause, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -735,7 +1067,7 @@ public class DatabaseScope internal constructor( select(kSerializer(), clause, true) public fun Relation.select(serializer: KSerializer, clause: GroupByClause, isDistinct: Boolean): GroupBySelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(From.of(this), clause, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -964,7 +1296,7 @@ public class DatabaseScope internal constructor( select(getKSerializer(), columns, true) public fun Relation.select(serializer: KSerializer, columns: Iterable>, isDistinct: Boolean): ResultColumnSelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(From.of(this), columns, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -1035,7 +1367,7 @@ public class DatabaseScope internal constructor( select.checkComplete() container removeStatement this select.container removeStatement select - val statement = Select.compound(this, operator, select, getSelectStatementGroup()) + val statement = Select.compound(this, operator, select, currentContainer) addSelectStatement(statement) return statement } @@ -1076,7 +1408,7 @@ public class DatabaseScope internal constructor( @ExperimentalDSLDatabaseAPI @StatementDslMaker public infix fun SelectStatement.AS(view: View): Relation { - takeAsSubquery() + takeOut() return DerivedTable(view, this) } @@ -1121,6 +1453,25 @@ public class DatabaseScope internal constructor( public infix fun ClauseBlob.IN(select: SelectStatement<*>): SelectCondition = subqueryIn(this, select, "BLOBs") { it.serialName.removeSuffix("?") == BYTE_ARRAY_TYPE } + /** + * Whether this value is among the values the single column of [select] returns: `column IN (SELECT ...)`. The + * column has to hold the values of the same serializer as this one, so that they compare as stored, as a column of + * the same type, with the same serializer, of another table does. + * + * @throws IllegalArgumentException if [select] doesn't return one column of the values of this serializer, or is + * incomplete + * @see IN + */ + @OptIn(ExperimentalSerializationApi::class) + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public infix fun ClauseConverted.IN(select: SelectStatement<*>): SelectCondition { + val name = serializer.descriptor.serialName.removeSuffix("?") + return subqueryIn(this, select, "the values of the serializer of '$name'") { + it.serialName.removeSuffix("?") == name && it.kind == serializer.descriptor.kind + } + } + /** * Whether [select] returns any row: `EXISTS (SELECT ...)`. * @@ -1138,13 +1489,10 @@ public class DatabaseScope internal constructor( @ExperimentalDSLDatabaseAPI @StatementDslMaker public fun EXISTS(select: SelectStatement<*>): SelectCondition { - select.takeAsSubquery() + select.takeOut() return SelectCondition("EXISTS (${select.sqlStr})", select.parameters?.toMutableList(), select.tables) } - /** - * Takes this SELECT out of the statements the scope runs, as it becomes a subquery of another one. - */ // A SELECT of a single column can also be a value, a scalar subquery: `select[R::property]` names the column, so // that the value has the property's type. @@ -1209,11 +1557,49 @@ public class DatabaseScope internal constructor( require(descriptor.elementsCount == 1 && descriptor.getElementName(0) == property.name) { "A SELECT of '${descriptor.serialName}' can't be the value '${property.name}': a scalar subquery returns a single column, so its result type has to have that property only." } - select.takeAsSubquery() + select.takeOut() return element("(${inlineParameters(select.sqlStr, select.parameters)})", select.tables) } - private fun SelectStatement<*>.takeAsSubquery() { + /** + * Takes [select] out of the statements the scope runs, and runs in its place the SELECT of its rows from [offset] on, + * at most [limit] of them, `SELECT * FROM (select) LIMIT limit OFFSET offset`, and, if [countRows], the count of all + * of them, `SELECT count(*) FROM (select)`, which a PagingSource of sqllin-dsl-paging loads a page with, as Room's + * does. As a subquery, [select] can be any SELECT, with its own ORDER BY, LIMIT or compound operators, and SQLite + * returns its rows in the order of its ORDER BY; the rows keep its columns, which they are decoded by, and its tables, + * which [Database.versioned] tracks. + * + * @return The SELECT of the page, and the count of the rows, if [countRows] + */ + internal fun page(select: SelectStatement, offset: Int, limit: Int, countRows: Boolean): Pair, RowCountStatement?> { + select.takeOut() + val count = if (countRows) { + RowCountStatement("SELECT count(*) FROM (${select.sqlStr})", databaseConnection, select.parameters?.toMutableList()) + .also { addStatement(it) } + } else { + null + } + val page = FinalSelectStatement( + sqlStr = "SELECT * FROM (${select.sqlStr}) LIMIT $limit OFFSET $offset", + deserializer = select.deserializer, + connection = databaseConnection, + container = currentContainer, + parameters = select.parameters?.toMutableList(), + ungroupedError = null, + tables = select.tables, + isSimple = false, + ) + addStatement(page) + return page to count + } + + /** + * Takes this SELECT out of the statements the scope runs, as it becomes part of another one: a subquery, or the + * SELECT that `EXPLAIN QUERY PLAN` plans. + * + * @throws IllegalArgumentException if this SELECT is incomplete, as an aggregate query that needs GROUP BY + */ + private fun SelectStatement<*>.takeOut() { checkComplete() container removeStatement this } @@ -1233,7 +1619,7 @@ public class DatabaseScope internal constructor( require(holds(column)) { "$prefix: its column '${descriptor.getElementName(0)}' holds ${column.serialName.removeSuffix("?")}, while '${element.valueName}' holds $values." } - select.takeAsSubquery() + select.takeOut() val sql = buildString { element.appendSQL(this) append(" IN (") @@ -1252,115 +1638,30 @@ public class DatabaseScope internal constructor( const val BYTE_ARRAY_TYPE = "kotlin.ByteArray" } - // ========== UNION Operations (deprecated) ========== - - private val unionSelectStatementGroupStack by lazy { ArrayDeque>() } - - private fun getSelectStatementGroup(): StatementContainer = unionSelectStatementGroupStack.lastOrNull() ?: currentContainer + // ========== SELECT from Joins ========== + // + // A join of relations, such as `PersonTable INNER_JOIN BookTable ON (...)`, is selected from like a table, but has + // to be given the type its rows are read into, as rows of a join have no type of their own. /** - * Combines multiple SELECT statements with UNION (removes duplicates). - * - * Example: - * ```kotlin - * val combined = PersonTable.UNION { - * it SELECT WHERE(age LT 18) - * it SELECT WHERE(age GTE 65) - * } - * ``` + * Selects rows of this join into [R], with X(), checking [R] against the joined relations. * - * **Deprecated**: the result is typed by the table's row type, but read into the first SELECT's result type, so - * a union of projections, result columns or joins fails with a `ClassCastException` when its results are used. - * A nested block is flattened into the SQL, which SQLite evaluates from left to right, so it changes its meaning - * when it isn't the first statement. Use the infix [UNION] instead: `(select1) UNION (select2)`. - */ - @Deprecated("The UNION {} block reads the rows into its first SELECT's result type while returning the table's row type, so a union of projections, result columns or joins fails with a ClassCastException when its results are used, and a nested block is flattened into the SQL, which changes its meaning. " + - "Use the infix operators instead, as in (select1) UNION (select2), which also offer INTERSECT and EXCEPT. This block will be removed in a future version.") - @Suppress("DEPRECATION") // Its body calls the plumbing deprecated with it - public inline fun Table.UNION(block: Table.(Table) -> Unit): FinalSelectStatement { - beginUnion() - var selectStatement: SelectStatement? = null - try { - block(this) - selectStatement = createUnionSelectStatement(false) - return selectStatement - } finally { - endUnion(selectStatement) - } - } + * @throws IllegalArgumentException if [R] doesn't fit the join + * @see JoinedRelation + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public inline infix fun JoinedRelation.SELECT(x: ProjectedX): FinalSelectStatement = + select(getKSerializer(), isDistinct = false) /** - * Combines multiple SELECT statements with UNION ALL (keeps duplicates). + * Selects rows of this join into [R], with X(), returning distinct rows, checking [R] against the joined + * relations. * - * **Deprecated** for the reasons given for the `UNION {}` block. Use the infix [UNION_ALL] instead: - * `(select1) UNION_ALL (select2)`. + * @throws IllegalArgumentException if [R] doesn't fit the join + * @see JoinedRelation */ - @Deprecated("The UNION {} block reads the rows into its first SELECT's result type while returning the table's row type, so a union of projections, result columns or joins fails with a ClassCastException when its results are used, and a nested block is flattened into the SQL, which changes its meaning. " + - "Use the infix operators instead, as in (select1) UNION (select2), which also offer INTERSECT and EXCEPT. This block will be removed in a future version.") - @Suppress("DEPRECATION") // Its body calls the plumbing deprecated with it - @StatementDslMaker - public inline fun Table.UNION_ALL(block: Table.(Table) -> Unit): FinalSelectStatement { - beginUnion() - var selectStatement: SelectStatement? = null - try { - block(this) - selectStatement = createUnionSelectStatement(true) - return selectStatement - } finally { - endUnion(selectStatement) - } - } - - /** - * Begins a UNION statement group (for advanced usage). - */ - @Deprecated("Part of the deprecated UNION {} block, which will be removed in a future version. Use the infix UNION instead.") - public fun beginUnion() { - unionSelectStatementGroupStack.add(UnionSelectStatementGroup()) - } - - /** - * Creates the final UNION select statement from accumulated SELECT statements. - */ - @Deprecated("Part of the deprecated UNION {} block, which will be removed in a future version. Use the infix UNION instead.") - public fun createUnionSelectStatement(isUnionAll: Boolean): FinalSelectStatement { - check(unionSelectStatementGroupStack.isNotEmpty()) { "Please invoke the 'beginUnion' before you invoke this function!!!" } - return (unionSelectStatementGroupStack.last() as UnionSelectStatementGroup).unionStatements(isUnionAll) - } - - /** - * Ends the UNION statement group and adds the final statement. - */ - @Deprecated("Part of the deprecated UNION {} block, which will be removed in a future version. Use the infix UNION instead.") - public fun endUnion(selectStatement: SelectStatement?) { - unionSelectStatementGroupStack.removeLast() - selectStatement?.let { addSelectStatement(it) } - } - - // ========== SELECT from Joins ========== - // - // A join of relations, such as `PersonTable INNER_JOIN BookTable ON (...)`, is selected from like a table, but has - // to be given the type its rows are read into, as rows of a join have no type of their own. - - /** - * Selects rows of this join into [R], with X(), checking [R] against the joined relations. - * - * @throws IllegalArgumentException if [R] doesn't fit the join - * @see JoinedRelation - */ - @ExperimentalDSLDatabaseAPI - @StatementDslMaker - public inline infix fun JoinedRelation.SELECT(x: ProjectedX): FinalSelectStatement = - select(getKSerializer(), isDistinct = false) - - /** - * Selects rows of this join into [R], with X(), returning distinct rows, checking [R] against the joined - * relations. - * - * @throws IllegalArgumentException if [R] doesn't fit the join - * @see JoinedRelation - */ - @ExperimentalDSLDatabaseAPI + @ExperimentalDSLDatabaseAPI @StatementDslMaker public inline infix fun JoinedRelation.SELECT_DISTINCT(x: ProjectedX): FinalSelectStatement = select(getKSerializer(), isDistinct = true) @@ -1505,7 +1806,7 @@ public class DatabaseScope internal constructor( @ExperimentalDSLDatabaseAPI public fun JoinedRelation.select(serializer: KSerializer, isDistinct: Boolean): FinalSelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(from, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -1513,7 +1814,7 @@ public class DatabaseScope internal constructor( @ExperimentalDSLDatabaseAPI public fun JoinedRelation.select(serializer: KSerializer, clause: WhereClause, isDistinct: Boolean): WhereSelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(from, clause, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -1521,7 +1822,7 @@ public class DatabaseScope internal constructor( @ExperimentalDSLDatabaseAPI public fun JoinedRelation.select(serializer: KSerializer, clause: OrderByClause, isDistinct: Boolean): OrderBySelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(from, clause, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -1529,7 +1830,7 @@ public class DatabaseScope internal constructor( @ExperimentalDSLDatabaseAPI public fun JoinedRelation.select(serializer: KSerializer, clause: LimitClause, isDistinct: Boolean): LimitSelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(from, clause, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -1537,7 +1838,7 @@ public class DatabaseScope internal constructor( @ExperimentalDSLDatabaseAPI public fun JoinedRelation.select(serializer: KSerializer, clause: GroupByClause, isDistinct: Boolean): GroupBySelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(from, clause, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement @@ -1545,84 +1846,12 @@ public class DatabaseScope internal constructor( @ExperimentalDSLDatabaseAPI public fun JoinedRelation.select(serializer: KSerializer, columns: Iterable>, isDistinct: Boolean): ResultColumnSelectStatement { - val container = getSelectStatementGroup() + val container = currentContainer val statement = Select.select(from, columns, isDistinct, serializer, databaseConnection, container) addSelectStatement(statement) return statement } - // ========== JOIN Operations ========== - - /** - * Selects with JOIN clause (requires ON condition). - * - * Example: - * ```kotlin - * val joined = PersonTable SELECT INNER_JOIN(AddressTable) ON ... - * ``` - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ - @StatementDslMaker - public inline infix fun Relation.SELECT(clause: JoinClause): JoinStatementWithoutCondition = - select(getKSerializer(), clause, false) - - /** - * Selects distinct rows with a JOIN clause, which ON or USING completes. - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ - @StatementDslMaker - public inline infix fun Relation.SELECT_DISTINCT(clause: JoinClause): JoinStatementWithoutCondition = - select(getKSerializer(), clause, true) - - public fun Relation.select(serializer: KSerializer, clause: JoinClause, isDistinct: Boolean): JoinStatementWithoutCondition { - val container = getSelectStatementGroup() - return Select.select(this, clause, isDistinct, serializer, databaseConnection, container, ::addSelectStatement) - } - - /** - * Selects with NATURAL JOIN (joins on columns with same names). - * - * Example: - * ```kotlin - * val joined = PersonTable SELECT NATURAL_INNER_JOIN(AddressTable) - * ``` - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ - @StatementDslMaker - public inline infix fun Relation.SELECT(clause: NaturalJoinClause): JoinSelectStatement = - select(getKSerializer(), clause, false) - - /** - * Selects distinct rows with a NATURAL or CROSS JOIN clause. - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ - @StatementDslMaker - public inline infix fun Relation.SELECT_DISTINCT(clause: NaturalJoinClause): JoinSelectStatement = - select(getKSerializer(), clause, true) - - public fun Relation.select(serializer: KSerializer, clause: NaturalJoinClause, isDistinct: Boolean): JoinSelectStatement { - val container = getSelectStatementGroup() - val statement = Select.select(this, clause, isDistinct, serializer, databaseConnection, container) - addSelectStatement(statement) - return statement - } - // ========== CREATE Operations ========== /** @@ -1678,8 +1907,9 @@ public class DatabaseScope internal constructor( * and DELETE operations. * * A function of the table's columns makes an expression index, which the queries comparing the same expression - * use, as `lower(email)` for case-insensitive lookups. `WHERE` after it makes a partial index of the rows that - * satisfy a condition. + * use, as `lower(email)` for case-insensitive lookups. The COLLATE operator gives a column of the index another + * collation than the column's, as `email COLLATE NOCASE`, which the queries comparing `(email COLLATE NOCASE)` + * use. `WHERE` after it makes a partial index of the rows that satisfy a condition. * * Example: * ```kotlin @@ -1687,6 +1917,7 @@ public class DatabaseScope internal constructor( * UserTable.CREATE_INDEX("idx_user_email", UserTable.email) * UserTable.CREATE_INDEX("idx_user_name_age", UserTable.name, UserTable.age) * UserTable.CREATE_INDEX("idx_user_lower_email", UserTable.lower(UserTable.email)) + * UserTable.CREATE_INDEX("idx_user_email_nocase", UserTable.email COLLATE NOCASE) * } * ``` * @@ -2191,6 +2422,605 @@ public class DatabaseScope internal constructor( addStatement(PRAGMA.optimize(databaseConnection)) } + // ========== EXPLAIN QUERY PLAN ========== + + /** + * Tells how SQLite would run [select], as the SQL `EXPLAIN QUERY PLAN` does, without running it: which tables it + * scans, which indexes it searches, and where it sorts the rows with a temporary B-tree. The plan is read, as the + * results of a SELECT are, once the scope has run. + * + * Example: + * ```kotlin + * val plan = database { + * EXPLAIN_QUERY_PLAN(BookTable SELECT WHERE(BookTable.author EQ "Dan Brown") ORDER_BY (BookTable.price to ASC)) + * }.getResults() + * println(plan) + * // QUERY PLAN + * // |--SEARCH book USING INDEX idx_book_author (author=?) + * // `--USE TEMP B-TREE FOR ORDER BY + * check(plan.details.any { "idx_book_author" in it }) + * ``` + * + * [select] can be any SELECT, with joins, subqueries or compound operators. It becomes part of the statement, so + * it no longer runs on its own, and it is planned with its parameters, as it would run. The plan depends on the + * indexes, and on the statistics that [ANALYZE] and [PRAGMA_OPTIMIZE] gather. Its details are SQLite's text, which + * differs between SQLite versions, as [QueryPlan] describes. A trigger can't run it. + * + * @return The statement, whose `getResults()` returns the plan once the scope has run + * @throws IllegalArgumentException if [select] is incomplete, as an aggregate query that needs GROUP BY + * @see QueryPlan + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun EXPLAIN_QUERY_PLAN(select: SelectStatement<*>): QueryPlanStatement { + select.takeOut() + val statement = QueryPlanStatement("EXPLAIN QUERY PLAN ${select.sqlStr}", databaseConnection, select.parameters?.toMutableList()) + addStatement(statement) + return statement + } + + // ========== PRAGMAs that check the database, read its schema and its file, or set how statements run ========== + // + // A PRAGMA that reads returns a PragmaStatement, whose getResults() returns what it read once the scope has run, as + // the results of a SELECT are read. Their types are in com.ctrip.sqllin.dsl.sql.pragma. A trigger can't run them. + // A PRAGMA that only newer versions of SQLite have fails with an IllegalStateException where the SQLite lacks it, + // which ignores it rather than failing, as its rows have no columns then. + + /** + * Whether the database enforces foreign keys, as the SQL `PRAGMA foreign_keys` tells, which + * `PRAGMA_FOREIGN_KEYS(flag)` sets. + * + * @return The statement, whose `getResults()` returns whether it does once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_FOREIGN_KEYS(): PragmaStatement = pragma(PRAGMA.isForeignKeysEnabled(databaseConnection)) + + /** + * Checks the whole database, as the SQL `PRAGMA integrity_check(N)` does: that its pages, rows and indexes are + * well-formed and agree with each other, and that the rows satisfy their NOT NULL and CHECK constraints, but not + * their foreign keys, which [PRAGMA_FOREIGN_KEY_CHECK] checks. + * + * Example: + * ```kotlin + * val problems = database { PRAGMA_INTEGRITY_CHECK() }.getResults() + * if (problems.isNotEmpty()) { + * // The database is corrupt + * } + * ``` + * + * It reads the whole database, so it takes long for a large one, which [PRAGMA_QUICK_CHECK] takes less long for. + * + * @param maxErrors How many problems to report at most + * @return The statement, whose `getResults()` returns the problems, in SQLite's words, or an empty list if there + * are none, once the scope has run + * @throws IllegalArgumentException if [maxErrors] isn't positive + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_INTEGRITY_CHECK(maxErrors: Int = 100): PragmaStatement> { + require(maxErrors > 0) { "PRAGMA integrity_check needs a positive number of errors, rather than $maxErrors." } + return pragma(PRAGMA.check("integrity_check", maxErrors, databaseConnection)) + } + + /** + * Checks the whole database as [PRAGMA_INTEGRITY_CHECK] does, as the SQL `PRAGMA quick_check(N)` does, except that + * the indexes hold the rows of their tables, and that the rows satisfy their UNIQUE constraints, so that it takes + * time in proportion to the size of the database, rather than more. + * + * @param maxErrors How many problems to report at most + * @return The statement, whose `getResults()` returns the problems, in SQLite's words, or an empty list if there + * are none, once the scope has run + * @throws IllegalArgumentException if [maxErrors] isn't positive + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_QUICK_CHECK(maxErrors: Int = 100): PragmaStatement> { + require(maxErrors > 0) { "PRAGMA quick_check needs a positive number of errors, rather than $maxErrors." } + return pragma(PRAGMA.check("quick_check", maxErrors, databaseConnection)) + } + + /** + * Checks [table] and its indexes as [PRAGMA_INTEGRITY_CHECK] checks the whole database, as the SQL + * `PRAGMA integrity_check(table)` does, reporting up to 100 problems. + * + * It needs SQLite 3.33.0, which Android has from API 34 on: an older SQLite takes the name of the table for a number + * of errors, which it ignores, so that it checks the whole database instead. + * + * @return The statement, whose `getResults()` returns the problems, in SQLite's words, or an empty list if there + * are none, once the scope has run + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_INTEGRITY_CHECK(table: Table<*>): PragmaStatement> = + pragma(PRAGMA.check("integrity_check", table.tableName, databaseConnection)) + + /** + * Checks the table named [table] and its indexes, as the SQL `PRAGMA integrity_check(table)` does. + * + * @see PRAGMA_INTEGRITY_CHECK + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_INTEGRITY_CHECK(table: String): PragmaStatement> = + pragma(PRAGMA.check("integrity_check", table, databaseConnection)) + + /** + * Checks [table] and its indexes as [PRAGMA_QUICK_CHECK] checks the whole database, as the SQL + * `PRAGMA quick_check(table)` does, reporting up to 100 problems. + * + * It needs SQLite 3.33.0, which Android has from API 34 on: an older SQLite takes the name of the table for a number + * of errors, which it ignores, so that it checks the whole database instead. + * + * @return The statement, whose `getResults()` returns the problems, in SQLite's words, or an empty list if there + * are none, once the scope has run + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_QUICK_CHECK(table: Table<*>): PragmaStatement> = + pragma(PRAGMA.check("quick_check", table.tableName, databaseConnection)) + + /** + * Checks the table named [table] and its indexes, as the SQL `PRAGMA quick_check(table)` does. + * + * @see PRAGMA_QUICK_CHECK + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_QUICK_CHECK(table: String): PragmaStatement> = + pragma(PRAGMA.check("quick_check", table, databaseConnection)) + + /** + * Finds the rows of all tables that violate their foreign keys, as the SQL `PRAGMA foreign_key_check` does, such as + * after a migration that turned foreign keys off with `PRAGMA_FOREIGN_KEYS(false)`. It checks them whether or not + * the database enforces them. + * + * @return The statement, whose `getResults()` returns the violations, or an empty list if there are none, once the + * scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_FOREIGN_KEY_CHECK(): PragmaStatement> = + pragma(PRAGMA.foreignKeyCheck(null, databaseConnection)) + + /** + * Finds the rows of [table] that violate its foreign keys, as the SQL `PRAGMA foreign_key_check(table)` does. + * + * @see PRAGMA_FOREIGN_KEY_CHECK + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_FOREIGN_KEY_CHECK(table: Table<*>): PragmaStatement> = + pragma(PRAGMA.foreignKeyCheck(table.tableName, databaseConnection)) + + /** + * Finds the rows of the table named [table] that violate its foreign keys, as the SQL + * `PRAGMA foreign_key_check(table)` does. + * + * @see PRAGMA_FOREIGN_KEY_CHECK + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_FOREIGN_KEY_CHECK(table: String): PragmaStatement> = + pragma(PRAGMA.foreignKeyCheck(table, databaseConnection)) + + /** + * The columns of [table] in the database, as the SQL `PRAGMA table_info(table)` tells, such as to check in a + * migration whether a column exists. It doesn't list the hidden and generated columns. A table that doesn't exist + * has no columns. + * + * Example: + * ```kotlin + * val columns = database { PRAGMA_TABLE_INFO(PersonTable) }.getResults() + * val hasEmail = columns.any { it.name == "email" } + * ``` + * + * @return The statement, whose `getResults()` returns the columns, in the order of the table, once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_TABLE_INFO(table: Table<*>): PragmaStatement> = + pragma(PRAGMA.tableInfo(table.tableName, databaseConnection)) + + /** + * The columns of [view] in the database, as the SQL `PRAGMA table_info(view)` tells. + * + * @see PRAGMA_TABLE_INFO + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_TABLE_INFO(view: View<*>): PragmaStatement> = + pragma(PRAGMA.tableInfo(view.tableName, databaseConnection)) + + /** + * The columns of the table or view named [name], as the SQL `PRAGMA table_info(name)` tells, such as of a table + * that the app no longer declares. + * + * @see PRAGMA_TABLE_INFO + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_TABLE_INFO(name: String): PragmaStatement> = + pragma(PRAGMA.tableInfo(name, databaseConnection)) + + /** + * The columns of [table] in the database, its hidden and generated ones included, as the SQL + * `PRAGMA table_xinfo(table)` tells: [PRAGMA_TABLE_INFO] with the [ColumnInfo.kind] of each column, such as the + * hidden columns of an FTS table. A table that doesn't exist has no columns. + * + * It needs SQLite 3.26.0, which Android has from API 30 on, and fails with an [IllegalStateException] where the + * SQLite lacks it. + * + * @return The statement, whose `getResults()` returns the columns, in the order of the table, once the scope has run + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_TABLE_XINFO(table: Table<*>): PragmaStatement> = + pragma(PRAGMA.tableXinfo(table.tableName, databaseConnection)) + + /** + * The columns of [view] in the database, as the SQL `PRAGMA table_xinfo(view)` tells. + * + * @see PRAGMA_TABLE_XINFO + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_TABLE_XINFO(view: View<*>): PragmaStatement> = + pragma(PRAGMA.tableXinfo(view.tableName, databaseConnection)) + + /** + * The columns of the table or view named [name], as the SQL `PRAGMA table_xinfo(name)` tells. + * + * @see PRAGMA_TABLE_XINFO + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_TABLE_XINFO(name: String): PragmaStatement> = + pragma(PRAGMA.tableXinfo(name, databaseConnection)) + + /** + * The tables and views of the databases of the connection, as the SQL `PRAGMA table_list` tells: those of `main`, + * with the virtual tables, as FTS tables, and the tables they keep their data in, and `sqlite_schema`, and those of + * `temp`, as the TEMP table that observed queries count changes with. + * + * It needs SQLite 3.37.0, which Android has from API 34 on, and fails with an [IllegalStateException] where the + * SQLite lacks it. + * + * @return The statement, whose `getResults()` returns the tables and views once the scope has run + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_TABLE_LIST(): PragmaStatement> = pragma(PRAGMA.tableList(databaseConnection)) + + /** + * The indexes of [table], as the SQL `PRAGMA index_list(table)` tells: those that CREATE INDEX created, and those + * that SQLite created for its UNIQUE and PRIMARY KEY constraints, except for an INTEGER PRIMARY KEY, which is the + * rowid, which needs none. + * + * @return The statement, whose `getResults()` returns the indexes once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_INDEX_LIST(table: Table<*>): PragmaStatement> = + pragma(PRAGMA.indexList(table.tableName, databaseConnection)) + + /** + * The indexes of the table named [table], as the SQL `PRAGMA index_list(table)` tells. + * + * @see PRAGMA_INDEX_LIST + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_INDEX_LIST(table: String): PragmaStatement> = + pragma(PRAGMA.indexList(table, databaseConnection)) + + /** + * The columns of the index named [index], as the SQL `PRAGMA index_xinfo(index)` tells: those it is keyed by, in + * order, with their sort orders and collations, then those it holds besides, as the rowid. An index that doesn't + * exist has no columns. + * + * @return The statement, whose `getResults()` returns the columns once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_INDEX_XINFO(index: String): PragmaStatement> = + pragma(PRAGMA.indexXinfo(index, databaseConnection)) + + /** + * The foreign keys of [table], as the SQL `PRAGMA foreign_key_list(table)` tells, a row for each of their columns. + * + * @return The statement, whose `getResults()` returns the columns of the foreign keys once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_FOREIGN_KEY_LIST(table: Table<*>): PragmaStatement> = + pragma(PRAGMA.foreignKeyList(table.tableName, databaseConnection)) + + /** + * The foreign keys of the table named [table], as the SQL `PRAGMA foreign_key_list(table)` tells. + * + * @see PRAGMA_FOREIGN_KEY_LIST + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_FOREIGN_KEY_LIST(table: String): PragmaStatement> = + pragma(PRAGMA.foreignKeyList(table, databaseConnection)) + + /** + * The options the SQLite was compiled with, as the SQL `PRAGMA compile_options` tells, without their `SQLITE_` + * prefix, as `ENABLE_FTS4` or `THREADSAFE=1`, which tell what the SQLite of a platform has. + * + * A SQLite can be built without the PRAGMA, as Android's is, where it fails with an [IllegalStateException]. + * + * @return The statement, whose `getResults()` returns the options once the scope has run + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_COMPILE_OPTIONS(): PragmaStatement> = + pragma(PRAGMA.names("compile_options", "compile_options", null, databaseConnection)) + + /** + * The names of the collations of the connection, as the SQL `PRAGMA collation_list` tells: SQLite's `BINARY`, + * `NOCASE` and `RTRIM`, and those the platform or the app registers, as Android's `LOCALIZED` and `UNICODE`. + * + * @return The statement, whose `getResults()` returns the names once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_COLLATION_LIST(): PragmaStatement> = + pragma(PRAGMA.names("collation_list", "name", null, databaseConnection)) + + /** + * The databases of the connection, as the SQL `PRAGMA database_list` tells: `main`, with the path of its file, + * and `temp` once the connection has TEMP tables. + * + * @return The statement, whose `getResults()` returns the databases once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_DATABASE_LIST(): PragmaStatement> = pragma(PRAGMA.databaseList(databaseConnection)) + + /** + * The SQL functions of the connection, as the SQL `PRAGMA function_list` tells, such as to check whether the SQLite + * of a platform has the math functions, which Android's lacks. + * + * It needs SQLite 3.30.0, which Android has from API 31 on, and fails with an [IllegalStateException] where the + * SQLite lacks it. + * + * @return The statement, whose `getResults()` returns a row for each form of each function once the scope has run + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_FUNCTION_LIST(): PragmaStatement> = pragma(PRAGMA.functionList(databaseConnection)) + + /** + * The names of the modules of virtual tables of the connection, as the SQL `PRAGMA module_list` tells, as `fts4` or + * `rtree`, which tell the virtual tables the SQLite of a platform can create. + * + * It needs SQLite 3.30.0, which Android has from API 31 on, and fails with an [IllegalStateException] where the + * SQLite lacks it. + * + * @return The statement, whose `getResults()` returns the names once the scope has run + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_MODULE_LIST(): PragmaStatement> = + pragma(PRAGMA.names("module_list", "name", "SQLite 3.30.0, which Android has from API 31 on", databaseConnection)) + + /** + * The names of the PRAGMAs the SQLite has, as the SQL `PRAGMA pragma_list` tells. + * + * It needs SQLite 3.30.0, which Android has from API 31 on, and fails with an [IllegalStateException] where the + * SQLite lacks it. + * + * @return The statement, whose `getResults()` returns the names once the scope has run + */ + @PlatformDependentSQLiteAPI + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_PRAGMA_LIST(): PragmaStatement> = + pragma(PRAGMA.names("pragma_list", "name", "SQLite 3.30.0, which Android has from API 31 on", databaseConnection)) + + /** + * Checkpoints the WAL, as the SQL `PRAGMA wal_checkpoint(mode)` does: copies the pages it holds into the database + * file, as SQLite does on its own once it holds 1000 pages, such as before copying the database file, which + * doesn't hold what the WAL does. A FULL, RESTART or TRUNCATE checkpoint waits for the other connections of the + * database as long as `busyTimeout`, and tells whether they kept it from finishing. A database that isn't in WAL + * mode has nothing to checkpoint. + * + * @param mode How to checkpoint + * @return The statement, whose `getResults()` returns the result of the checkpoint once the scope has run + * @throws IllegalStateException inside a transaction, as SQLite can't checkpoint there + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_WAL_CHECKPOINT(mode: CheckpointMode = CheckpointMode.PASSIVE): PragmaStatement { + check(!isInTransaction) { "SQLite can't checkpoint the WAL inside a transaction." } + return pragma(PRAGMA.walCheckpoint(mode, databaseConnection)) + } + + /** + * The number of pages of the database file, as the SQL `PRAGMA page_count` tells, which, times + * [PRAGMA_PAGE_SIZE], is its size, without what its WAL holds. + * + * @return The statement, whose `getResults()` returns the number once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_PAGE_COUNT(): PragmaStatement = pragma(PRAGMA.size("page_count", isInTransaction, databaseConnection)) + + /** + * The number of unused pages of the database file, as the SQL `PRAGMA freelist_count` tells, which rows that were + * deleted leave, and which [VACUUM] removes, so that the file shrinks. A database whose auto_vacuum is on removes them + * at each commit, so that it has none: Android's SQLite creates a database with auto_vacuum FULL by default. + * + * @return The statement, whose `getResults()` returns the number once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_FREELIST_COUNT(): PragmaStatement = pragma(PRAGMA.size("freelist_count", isInTransaction, databaseConnection)) + + /** + * The size of a page of the database file in bytes, as the SQL `PRAGMA page_size` tells. Outside a transaction, + * it is read in a transaction of its own, as SQLite takes it from what the connection last read of the header of + * the file, which a transaction reads again. + * + * @return The statement, whose `getResults()` returns the size once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_PAGE_SIZE(): PragmaStatement = pragma(PRAGMA.size("page_size", isInTransaction, databaseConnection)) + + /** + * The number that the header of the database file holds to tell the app it belongs to, as the SQL + * `PRAGMA application_id` tells, which SQLite doesn't use, 0 unless it is set. + * + * @return The statement, whose `getResults()` returns the number once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_APPLICATION_ID(): PragmaStatement = pragma(PRAGMA.applicationId(databaseConnection)) + + /** + * Sets the number that the header of the database file holds to tell the app it belongs to, as the SQL + * `PRAGMA application_id = id` does, such as to tell a file of the app from others it opens. + * + * @param id The number + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_APPLICATION_ID(id: Int) { + pragma(PRAGMA.applicationId(id, databaseConnection)) + } + + /** + * Whether the database removes its unused pages, as the SQL `PRAGMA auto_vacuum` tells: Android's SQLite creates a + * database with [AutoVacuum.FULL] by default, and the others with [AutoVacuum.NONE]. Outside a transaction, it is + * read in a transaction of its own, as SQLite takes it from what the connection last read of the header of the + * file, which a transaction reads again: from Android 13 on, a query outside a transaction may run on a connection + * that reads, which would tell the mode before the last VACUUM. + * + * @return The statement, whose `getResults()` returns the mode once the scope has run + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_AUTO_VACUUM(): PragmaStatement = pragma(PRAGMA.autoVacuum(isInTransaction, databaseConnection)) + + /** + * Sets whether the database removes its unused pages, as the SQL `PRAGMA auto_vacuum = mode` does. It applies to a + * database that has no tables yet, as in `create` of the configuration before the first CREATE, and otherwise + * only once [VACUUM] rebuilds the database, which it has to be followed by: + * ```kotlin + * database { + * PRAGMA_AUTO_VACUUM(AutoVacuum.INCREMENTAL) + * VACUUM() + * } + * ``` + * + * @param mode Whether to remove them at each commit, or to keep them, as [AutoVacuum.INCREMENTAL] does until the + * SQL `PRAGMA incremental_vacuum` removes them, which SQLlin doesn't run: it removes a page each time it returns a + * row, which has no columns, and sqlite-jdbc runs such a statement only as far as its first row + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_AUTO_VACUUM(mode: AutoVacuum) { + pragma(PRAGMA.autoVacuum(mode, databaseConnection)) + } + + /** + * Defers the checks of foreign keys to the end of the transaction, or stops deferring them, as the SQL + * `PRAGMA defer_foreign_keys` does, so that the statements after it may violate them for a while, as when a row is + * inserted before the row it references. A violation that remains when the transaction commits fails the commit. + * + * Example: + * ```kotlin + * database { PRAGMA_FOREIGN_KEYS(true) } + * database { + * transaction { + * PRAGMA_DEFER_FOREIGN_KEYS(true) + * OrderTable INSERT Order(userId = 1) + * UserTable INSERT User(id = 1) + * } + * } + * ``` + * + * SQLite turns it off again when the transaction ends, so it can only be set in one. It only matters while the + * database enforces foreign keys, which `PRAGMA_FOREIGN_KEYS(true)` turns on, outside a transaction. + * + * @param flag Whether to defer the checks + * @throws IllegalStateException outside a transaction + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_DEFER_FOREIGN_KEYS(flag: Boolean) { + check(isInTransaction) { "PRAGMA defer_foreign_keys only lasts until the transaction ends, so it can only be set in transaction { }." } + pragma(PRAGMA.set("defer_foreign_keys", flag, databaseConnection)) + } + + /** + * Lets triggers fire recursively, or stops them, as the SQL `PRAGMA recursive_triggers` does: a statement that a + * trigger runs then fires the triggers of its table, the trigger itself included, which SQLite doesn't by default, + * up to a depth of 1000 by default. A REPLACE conflict resolution then also fires the DELETE triggers of the rows + * it deletes. + * + * It lasts as long as the database is open, for the scopes after this one too, until it is set again. In a + * transaction, it applies to the statements after it. + * + * @param flag Whether triggers fire recursively + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_RECURSIVE_TRIGGERS(flag: Boolean) { + pragma(PRAGMA.set("recursive_triggers", flag, databaseConnection)) + } + + /** + * Makes `ALTER_RENAME_TABLE_TO` rename a table as SQLite 3.25.0 and earlier did, or as it does now, as the SQL + * `PRAGMA legacy_alter_table` does: without rewriting the views and triggers that read the table, which then read + * a table of the old name, such as in a migration that rebuilds a table under the old name. + * + * It lasts as long as the database is open, for the scopes after this one too, until it is set again. Android's + * SQLite turns it on by default, so that a rename there doesn't rewrite them unless it is turned off. + * + * @param flag Whether to rename tables as SQLite 3.25.0 and earlier did + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_LEGACY_ALTER_TABLE(flag: Boolean) { + pragma(PRAGMA.set("legacy_alter_table", flag, databaseConnection)) + } + + /** + * Stops checking CHECK constraints, or checks them again, as the SQL `PRAGMA ignore_check_constraints` does, such + * as to import rows that predate a constraint; [PRAGMA_INTEGRITY_CHECK] then finds the rows that violate them. + * + * It lasts as long as the database is open, for the scopes after this one too, until it is set again. + * + * @param flag Whether to ignore CHECK constraints + */ + @ExperimentalDSLDatabaseAPI + @StatementDslMaker + public fun PRAGMA_IGNORE_CHECK_CONSTRAINTS(flag: Boolean) { + pragma(PRAGMA.set("ignore_check_constraints", flag, databaseConnection)) + } + + @OptIn(ExperimentalDSLDatabaseAPI::class) + private fun pragma(statement: PragmaStatement): PragmaStatement { + addStatement(statement) + return statement + } + // ========== CREATE TRIGGER and DROP TRIGGER ========== /** The trigger being defined, from ON to the end of BEGIN, whose rows `new()` and `old()` read. */ @@ -2321,9 +3151,10 @@ public class DatabaseScope internal constructor( val name = timing.trigger.name require(collected.statements.isNotEmpty()) { "The trigger '$name' needs at least one statement." } for (statement in collected.statements) { - require(statement is InsertStatement || statement is UpdateDeleteStatement || statement is UpdateStatementWithoutWhereClause<*> || statement is RaiseStatement) { + require(Changes.writtenTable(statement) != null || statement is RaiseStatement) { "The trigger '$name' can only run INSERT, UPDATE, DELETE and RAISE, but not: ${statement.sqlStr}" } + statement.checkComplete() } addStatement(Trigger.create(this, collected.statements, databaseConnection)) } diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/InvalidationTracker.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/InvalidationTracker.kt index 2f56a5bd..4846bdaf 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/InvalidationTracker.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/InvalidationTracker.kt @@ -19,6 +19,7 @@ package com.ctrip.sqllin.dsl import com.ctrip.sqllin.driver.DatabaseConnection import com.ctrip.sqllin.driver.withQuery import com.ctrip.sqllin.driver.withTransaction +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI import com.ctrip.sqllin.dsl.sql.statement.Changes import kotlinx.coroutines.flow.MutableStateFlow import kotlinx.coroutines.flow.StateFlow @@ -50,6 +51,7 @@ import kotlinx.coroutines.flow.update * * @author Yuang Qiao */ +@OptIn(ExperimentalDSLDatabaseAPI::class) internal class InvalidationTracker(private val connection: DatabaseConnection) { private val trackedTables = MutableStateFlow>(emptySet()) @@ -71,6 +73,71 @@ internal class InvalidationTracker(private val connection: DatabaseConnection) { */ val versions: StateFlow> = _versions + /** + * The callbacks of [register] that wait for a change of the tables of their tokens. The list is replaced as a + * whole, so that registering, closing and firing are atomic, from whichever thread they run on. + */ + private val registrations = MutableStateFlow>(emptyList()) + + private class Registration(val since: TableVersions, val callback: () -> Unit) + + /** + * Registers [callback] to run once a table of [since] changes, unless one already has, in which case it registers + * nothing and returns null. + * + * It registers before it checks, so that a change between the read that captured [since] and the registration is + * either seen here, or fires the callback: never neither, and never both. + * + * @return What closes the registration, or null when [since] is already stale + */ + fun register(since: TableVersions, callback: () -> Unit): AutoCloseable? { + val registration = Registration(since, callback) + registrations.update { it + registration } + if (since.isStaleIn(versions.value) && remove(listOf(registration)).isNotEmpty()) + return null + return object : AutoCloseable { + override fun close() { + remove(listOf(registration)) + } + } + } + + /** + * Removes [toRemove] from the registrations, and returns those of them that this call removed, rather than another + * that ran at the same time. + */ + private fun remove(toRemove: List): List { + while (true) { + val current = registrations.value + val removed = toRemove.filter { it in current } + if (removed.isEmpty() || registrations.compareAndSet(current, current - removed.toSet())) + return removed + } + } + + /** + * Runs the callbacks whose tokens are stale, once each, after a scope that may have written. It runs once the scope + * released the executive lock, so that a callback that uses the database doesn't wait for it forever, on the thread + * that wrote. A failure of a callback is thrown once the others have run. + */ + fun dispatch() { + val current = versions.value + val fired = remove(registrations.value.filter { it.since.isStaleIn(current) }) + var failure: Throwable? = null + for (registration in fired) { + try { + registration.callback() + } catch (e: Throwable) { + val first = failure + if (first == null) + failure = e + else + first.addSuppressed(e) + } + } + failure?.let { throw it } + } + /** * Starts tracking the tables that the tables and views named [relations] read, creating their triggers, unless they * are tracked already. diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/PageLoading.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/PageLoading.kt new file mode 100644 index 00000000..b522c8da --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/PageLoading.kt @@ -0,0 +1,71 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl + +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import com.ctrip.sqllin.dsl.annotation.InternalSQLlinAPI +import com.ctrip.sqllin.dsl.sql.statement.SelectStatement + +/* + * What the PagingSource of sqllin-dsl-paging loads its pages through, which needs statements that DatabaseScope only + * builds internally. + */ + +/** + * A page of the rows of a SELECT, which [loadPage] reads. + * + * @property rows The rows of the page + * @property rowCount The number of all the rows of the SELECT, if they were counted + * @property versions The token of the versions of the tables the rows were read from, as [Database.versioned] returns + * + * @author Yuang Qiao + */ +@InternalSQLlinAPI +@ExperimentalDSLDatabaseAPI +public class LoadedPage internal constructor( + public val rows: List, + public val rowCount: Int?, + public val versions: TableVersions, +) + +/** + * Reads the rows of the SELECT that [query] builds from [offset] on, at most [limit] of them, and, if [countRows], the + * number of all of them, as `SELECT * FROM (select) LIMIT limit OFFSET offset` and `SELECT count(*) FROM (select)`, in a + * read-only scope that returns the token of the versions of the tables they read, as [Database.versioned] does. + * + * @throws IllegalArgumentException if [query] writes, as [Database.versioned] does + */ +@InternalSQLlinAPI +@ExperimentalDSLDatabaseAPI +public suspend fun Database.loadPage( + offset: Int, + limit: Int, + countRows: Boolean, + query: DatabaseScope.() -> SelectStatement, +): LoadedPage { + val (statements, versions) = versioned { page(query(), offset, limit, countRows) } + val (page, count) = statements + return LoadedPage(page.getResults(), count?.getResult()?.coerceAtMost(Int.MAX_VALUE.toLong())?.toInt(), versions) +} + +/** + * Whether a table of this token has changed since its read, through its [Database], as [Database.onChange] checks. + */ +@InternalSQLlinAPI +@ExperimentalDSLDatabaseAPI +public val TableVersions.isStale: Boolean + get() = isStaleIn(tracker.versions.value) diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/TableVersions.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/TableVersions.kt new file mode 100644 index 00000000..2e4af2f5 --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/TableVersions.kt @@ -0,0 +1,63 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl + +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI + +/** + * A token of the versions of the tables a read read, which [Database.versioned] returns with its results, so that a + * reader learns when they change: [Database.awaitChange] suspends until one of them does, and [Database.onChange] + * registers a callback for it. + * + * The versions are captured under the lock that the read runs under, after the tables are tracked, so that no change + * made after the read is missed. A change made through the same [Database] makes the token stale, as a rolled back + * transaction and an UPDATE or DELETE that matches no rows don't; changes made through another database instance, + * connection or process aren't seen. A view stands for the tables it reads. A token can tell of a change that its + * read already includes, but never misses one. + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public class TableVersions internal constructor( + internal val tracker: InvalidationTracker, + internal val versions: Map, +) { + + /** + * Combines this token with [other], as of reads that depend on each other, so that the combined token is stale + * when either is: it covers the tables of both, and takes the earlier version of a table that both cover, which + * a change after either read makes stale. + * + * @throws IllegalArgumentException if [other] is a token of another [Database], whose versions count other changes + */ + public operator fun plus(other: TableVersions): TableVersions { + require(tracker === other.tracker) { "The tokens of different databases can't be combined, as each counts its own changes." } + val combined = LinkedHashMap(versions) + for ((table, version) in other.versions) + combined[table] = combined[table]?.let { minOf(it, version) } ?: version + return TableVersions(tracker, combined) + } + + /** + * Whether one of the tables of this token has changed, by [current], the versions the tracker has counted. + */ + internal fun isStaleIn(current: Map): Boolean = + versions.any { (table, version) -> (current[table] ?: 0L) > version } + + override fun toString(): String = + versions.entries.joinToString(prefix = "TableVersions(", postfix = ")") { (table, version) -> "$table=$version" } +} diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/annotation/CreateStatementModifiers.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/annotation/CreateStatementModifiers.kt index 86bd99e3..ec03cf7b 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/annotation/CreateStatementModifiers.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/annotation/CreateStatementModifiers.kt @@ -133,6 +133,37 @@ public annotation class CompositePrimaryKey(val onConflict: OnConflict = OnConfl @Retention(AnnotationRetention.BINARY) public annotation class CollateNoCase +/** + * Marks a text column to compare its values ignoring the spaces at their ends, as the SQL `COLLATE RTRIM` of the + * column's definition does, so that `'abc '` equals `'abc'`, and its UNIQUE constraint and indexes treat them as the + * same value. The values are stored as they are written, spaces included. + * + * A column has one collation, so a property can't have both this and [CollateNoCase]. A column without either compares + * its values as BINARY does, by their bytes; the COLLATE operator compares them otherwise in a single expression, as in + * `(code COLLATE BINARY) EQ "abc"`. + * + * ```kotlin + * @OptIn(ExperimentalDSLDatabaseAPI::class) + * @DBRow + * @Serializable + * data class Product( + * @PrimaryKey val id: Long?, + * @CollateRTrim @Unique val code: String, + * ) + * // CREATE TABLE Product(id INTEGER PRIMARY KEY,code TEXT NOT NULL COLLATE RTRIM UNIQUE) + * ``` + * + * It can only be applied to properties of type `String` or `Char`, and their nullable variants, which the compiler + * checks. + * + * @see CollateNoCase + * @see DBRow + */ +@ExperimentalDSLDatabaseAPI +@Target(AnnotationTarget.PROPERTY) +@Retention(AnnotationRetention.BINARY) +public annotation class CollateRTrim + /** * Marks a column as unique, enforcing a UNIQUE constraint in the database. * diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/annotation/InternalSQLlinAPI.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/annotation/InternalSQLlinAPI.kt new file mode 100644 index 00000000..ed13bbd7 --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/annotation/InternalSQLlinAPI.kt @@ -0,0 +1,36 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.annotation + +/** + * Marks the APIs of sqllin-dsl that only SQLlin's other modules use, such as sqllin-dsl-paging, which can't reach its + * internal declarations. They aren't meant for apps: they may change or be removed in any version, without notice. + * + * @see OptIn + * @see RequiresOptIn + */ +@RequiresOptIn( + message = "This API is internal to SQLlin, for its other modules, and may change or be removed in any version.", + level = RequiresOptIn.Level.ERROR +) +@Target( + AnnotationTarget.CLASS, + AnnotationTarget.FUNCTION, + AnnotationTarget.PROPERTY, +) +@Retention(AnnotationRetention.BINARY) +public annotation class InternalSQLlinAPI diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/IndexedTable.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/IndexedTable.kt new file mode 100644 index 00000000..ff9cde2a --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/IndexedTable.kt @@ -0,0 +1,67 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +@file:Suppress("DSL_MARKER_APPLIED_TO_WRONG_TARGET") + +package com.ctrip.sqllin.dsl.sql + +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import com.ctrip.sqllin.dsl.annotation.KeyWordDslMaker +import com.ctrip.sqllin.dsl.annotation.StatementDslMaker +import kotlinx.serialization.KSerializer + +/** + * A table that a statement reads or writes with SQL's `INDEXED BY index` or `NOT INDEXED`, which make SQLite look its + * rows up through that index, or through none, rather than through the one its query planner would choose: + * `PersonTable INDEXED_BY "idx_person_age"` or `PersonTable.NOT_INDEXED`. + * + * A SELECT reads it as it reads the table, joins included, and UPDATE and DELETE write it; INSERT can't, as SQL doesn't + * allow it there. Its columns are the table's. When SQLite can't run the statement through the index, as when the index + * doesn't exist, or doesn't help the WHERE clause, the statement fails, with "no query solution". + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public class IndexedTable internal constructor( + internal val table: Table, + private val clause: String, +) : Relation(table.tableName) { + + override fun kSerializer(): KSerializer = table.kSerializer() + + override val fromSQL: String + get() = "$tableName$clause" +} + +/** + * This table, which a statement looks its rows up in through [index], as SQL's `table INDEXED BY index` does. + * + * @throws IllegalArgumentException if [index] is blank + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun Table.INDEXED_BY(index: String): IndexedTable { + require(index.isNotBlank()) { "The name of an index can't be blank." } + return IndexedTable(this, " INDEXED BY $index") +} + +/** + * This table, which a statement looks its rows up in without any index, as SQL's `table NOT INDEXED` does. + */ +@ExperimentalDSLDatabaseAPI +@KeyWordDslMaker +public val Table.NOT_INDEXED: IndexedTable + get() = IndexedTable(this, " NOT INDEXED") diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/Table.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/Table.kt index f25a04dc..02dca598 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/Table.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/Table.kt @@ -17,7 +17,13 @@ package com.ctrip.sqllin.dsl.sql import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import com.ctrip.sqllin.dsl.sql.clause.SetClause +import com.ctrip.sqllin.dsl.sql.compiler.storedValueOf +import com.ctrip.sqllin.dsl.sql.operation.FullNameCache +import kotlinx.serialization.ExperimentalSerializationApi import kotlinx.serialization.KSerializer +import kotlinx.serialization.SerializationStrategy +import kotlinx.serialization.descriptors.SerialDescriptor /** * What a SELECT reads: a [Table], or a [View]. @@ -122,6 +128,8 @@ public abstract class Table(tableName: String) : Relation(tableName) { * - Kotlin types are mapped to SQLite types (Int→INT, String→TEXT, etc.) * - Annotations like [@PrimaryKey], [@Unique], [@CollateNoCase], etc. add corresponding SQL clauses * - Enum properties are stored as INTEGER (ordinal values) + * - A property whose serializer converts its values, as one of a `Uuid` or a value class, gets the type of the value + * its serializer stores, which the statement computes when it is read, as [columnType] does * * ### Example * For a data class: @@ -152,8 +160,56 @@ public abstract class Table(tableName: String) : Relation(tableName) { * @see com.ctrip.sqllin.dsl.annotation.CollateNoCase */ public abstract val createSQL: String + + /** + * Returns the SQLite type of the column of the property at [elementIndex] of the rows' descriptor, as the + * property's serializer stores it, which the CREATE statement of a generated table gives a property whose + * serializer converts its values, as `TEXT` for a `Uuid`, so that the column has the type of the values written to + * it. Such a column is never the rowid, as a `Long` primary key is. + * + * @param collation The collation of the column, as `NOCASE`, which only a column of text can have, or null + * @throws IllegalArgumentException if the serializer encodes a structure, which no column holds, or [collation] is + * given and it doesn't store text + */ + protected fun columnType(elementIndex: Int, collation: String? = null): String { + val descriptor = kSerializer().descriptor + val name = descriptor.getElementName(elementIndex) + val type = columnTypeOf(descriptor.getElementDescriptor(elementIndex), name, isPrimaryKey = false) + require(collation == null || type == "TEXT" || type == "CHAR(1)") { + "The column '$name' of table '$tableName' has the collation $collation, which compares text, but its serializer stores it as $type." + } + return type + } + + /** + * Assigns [propertyValue] to the column [propertyName] in `SET {}`, converted by [serializer], the serializer of the + * column's property, as the setter that a generated table gives a property whose serializer converts its values + * does, so that the column is set to what the serializer stores for the value, as an INSERT would. + */ + protected fun SetClause.appendConverted(propertyName: String, propertyValue: V?, serializer: SerializationStrategy): Unit = + appendAny(propertyName, propertyValue?.let { storedValueOf(serializer, it) }) } +/** + * Returns the SQLite type of the column [elementName] of this table, as the serializer of its property stores it, which + * `ALTER TABLE ... ADD COLUMN` gives it. + * + * @throws IllegalArgumentException if the serializer encodes a structure, which no column holds + */ +internal fun Table<*>.columnTypeOf(elementName: String): String { + val descriptor = kSerializer().descriptor + val elementDescriptor = descriptor.getElementDescriptor(descriptor.getElementIndex(elementName)) + return columnTypeOf(elementDescriptor, elementName, isPrimaryKey = elementName == primaryKeyInfo?.primaryKeyName) +} + +@OptIn(ExperimentalSerializationApi::class) +private fun Table<*>.columnTypeOf(descriptor: SerialDescriptor, elementName: String, isPrimaryKey: Boolean): String = + requireNotNull(FullNameCache.columnTypeOf(descriptor, isPrimaryKey)) { + "The column '$elementName' of table '$tableName' is written by the serializer of '${descriptor.serialName.removeSuffix("?")}', " + + "which encodes a structure (${descriptor.kind}), while a column holds one value: a number, a string, a Boolean or a ByteArray. " + + "Give the property a serializer that encodes it as one of them, as JSON in a string, for example." + } + /** * Returns a table with the structure of this one under another [name], as needed to rebuild a table. * diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/BaseJoinClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/BaseJoinClause.kt deleted file mode 100644 index 03db52a0..00000000 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/BaseJoinClause.kt +++ /dev/null @@ -1,117 +0,0 @@ -/* - * Copyright (C) 2022 Ctrip.com. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package com.ctrip.sqllin.dsl.sql.clause - -import com.ctrip.sqllin.dsl.sql.Relation -import com.ctrip.sqllin.dsl.annotation.StatementDslMaker -import com.ctrip.sqllin.dsl.sql.statement.JoinSelectStatement -import com.ctrip.sqllin.dsl.sql.statement.JoinStatementWithoutCondition - -/** - * Base class for JOIN clauses in SELECT statements. - * - * Generates SQL for joining multiple tables. Different JOIN types (INNER, LEFT OUTER, CROSS, - * NATURAL) extend this class with their specific SQL keywords. - * - * @param R The result entity type after JOIN - * @param tables Tables to join - * - * @author Yuang Qiao - */ -public sealed class BaseJoinClause(private vararg val joinedTables: Relation<*>) : SelectClause { - - internal abstract val clauseName: String - - /** - * The tables and views that the relations this clause joins read, which an observed query watches. - */ - internal val tables: Set - get() = joinedTables.flatMapTo(LinkedHashSet()) { it.readTables } - - /** - * The parameters of the derived tables this clause joins, in their order. - */ - internal val parameters: List - get() = joinedTables.flatMap { it.fromParameters } - - final override val clauseStr: String - get() = buildString { - append(clauseName) - joinedTables.forEachIndexed { index, table -> - append(table.fromSQL) - if (index < joinedTables.lastIndex) - append(',') - } - } -} - -/** - * NATURAL JOIN clause - automatically matches columns with the same name. - * - * Does not require ON or USING condition. - * - * @param R The result entity type after JOIN - */ -public sealed class NaturalJoinClause(vararg tables: Relation<*>) : BaseJoinClause(*tables) - -/** - * JOIN clause that requires an ON or USING condition. - * - * Returns [JoinStatementWithoutCondition] which must be completed with ON or USING. - * - * @param R The result entity type after JOIN - */ -public sealed class JoinClause(vararg tables: Relation<*>) : BaseJoinClause(*tables) - -/** - * Completes a join of the old join API with `ON condition`. - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ -@Suppress("DSL_MARKER_APPLIED_TO_WRONG_TARGET") -@StatementDslMaker -public infix fun JoinStatementWithoutCondition.ON(condition: SelectCondition): JoinSelectStatement = - convertToJoinSelectStatement(condition) - -/** - * Completes a join of the old join API with `USING (column)`. - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ -@Suppress("DSL_MARKER_APPLIED_TO_WRONG_TARGET") -@StatementDslMaker -public inline infix fun JoinStatementWithoutCondition.USING(clauseElement: ClauseElement<*>): JoinSelectStatement = - USING(listOf(clauseElement)) - -/** - * Completes a join of the old join API with `USING (columns)`. - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ -@Suppress("DSL_MARKER_APPLIED_TO_WRONG_TARGET") -@StatementDslMaker -public infix fun JoinStatementWithoutCondition.USING(clauseElements: Iterable>): JoinSelectStatement = - convertToJoinSelectStatement(clauseElements) \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseConverted.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseConverted.kt new file mode 100644 index 00000000..62973ec6 --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseConverted.kt @@ -0,0 +1,196 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.sql.clause + +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import com.ctrip.sqllin.dsl.sql.Relation +import com.ctrip.sqllin.dsl.sql.compiler.storedValueOf +import kotlinx.serialization.ExperimentalSerializationApi +import kotlinx.serialization.SerializationStrategy + +/** + * Wrapper for the column references of a type that SQLite doesn't store as it is, whose serializer converts its values + * to those of a column: a number, a string, a Boolean or a `ByteArray`. + * + * A property gets this element when its serializer isn't the one SQLlin stores its type with by default: a type with a + * built-in serializer of kotlinx.serialization, as `Uuid`, `Instant` or `Duration`; a value class; a type whose class + * declares its serializer, as `@Serializable(with = ...)` does; or a property, or a type use, annotated with + * `@Serializable(with = ...)`, of any type, an enum or a `String` included. The serializer that writes the property is + * the converter: + * ```kotlin + * object EpochMillisSerializer : KSerializer { + * override val descriptor = PrimitiveSerialDescriptor("EpochMillis", PrimitiveKind.LONG) + * override fun serialize(encoder: Encoder, value: Instant) = encoder.encodeLong(value.toEpochMilliseconds()) + * override fun deserialize(decoder: Decoder) = Instant.fromEpochMilliseconds(decoder.decodeLong()) + * } + * + * @Serializable + * @DBRow + * data class Event( + * @PrimaryKey val id: Uuid, + * @Serializable(with = EpochMillisSerializer::class) val startsAt: Instant, + * ) + * + * EventTable SELECT WHERE(EventTable.startsAt GTE since) ORDER_BY (EventTable.startsAt to ASC) + * ``` + * + * The column has the type that the serializer stores, `BIGINT` for `startsAt`, and `TEXT` for `id`, as the built-in + * serializer of `Uuid` writes a string. A value given to a condition, or assigned in `SET {}`, is converted by the same + * serializer, so that it is compared with, or stored as, what the column holds. + * + * A comparison other than an equality, as `LT` or `BETWEEN`, and ORDER BY compare the stored values, which are in the + * order of the Kotlin values only if the serializer keeps it: the built-in serializer of `kotlin.time.Instant` writes + * an ISO-8601 string, whose fraction of a second, if any, makes `2024-01-01T00:00:00.5Z` come before + * `2024-01-01T00:00:00Z`; store an instant as the number of its milliseconds, as `EpochMillisSerializer` does, to compare + * and order it. + * + * @param V The type of the element's values, as the property's type, not counting NULL + * @property serializer The serializer that converts the values, the property's + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public class ClauseConverted internal constructor( + valueName: String, + table: Relation<*>, + isFunction: Boolean, + isNullable: Boolean, + isAggregate: Boolean, + isNullOnNoRows: Boolean, + internal val serializer: SerializationStrategy, + columnTables: Set? = null, + tables: Set = emptySet(), + isDeterministic: Boolean = true, + isLiteral: Boolean = false, +) : ClauseElement(valueName, table, isFunction, isNullable, isAggregate, isNullOnNoRows, columnTables, tables, isDeterministic, isLiteral) { + + /** + * The column [valueName] of [table], whose values [serializer] converts, which has to be the serializer that + * kotlinx.serialization writes the column's property with, so that a condition compares the values the column + * holds. + * + * @throws IllegalArgumentException if [serializer] encodes another type, or as another kind of value, than the + * serializer of the property, as when sqllin-processor took another serializer than kotlinx.serialization did + */ + @OptIn(ExperimentalSerializationApi::class) + public constructor(valueName: String, table: Relation<*>, isNullable: Boolean, serializer: SerializationStrategy) : + this(valueName, table, isFunction = false, isNullable = isNullable, isAggregate = false, isNullOnNoRows = true, serializer = serializer) { + val row = table.kSerializer().descriptor + val property = row.getElementDescriptor(row.getElementIndex(valueName)) + val converter = serializer.descriptor + require(property.serialName.removeSuffix("?") == converter.serialName.removeSuffix("?") && property.kind == converter.kind) { + "The column '$valueName' of '${table.tableName}' is written by the serializer of '${property.serialName.removeSuffix("?")}', " + + "but its conditions would convert values with that of '${converter.serialName.removeSuffix("?")}', so that they wouldn't compare what it holds. " + + "Declare the serializer of the property with @Serializable(with = ...) on the property." + } + } + + override fun toAggregate(valueName: String, table: Relation<*>): ClauseConverted = + ClauseConverted(valueName, table, isFunction = true, isNullable = isNullable, isAggregate = true, isNullOnNoRows = true, serializer = serializer, columnTables = columnTables, tables = tables, isDeterministic = isDeterministic) + + override fun derive(valueName: String, traits: Traits): ClauseConverted = + ClauseConverted(valueName, table, isFunction = true, isNullable = traits.isNullable, isAggregate = traits.isAggregate, isNullOnNoRows = traits.isNullOnNoRows, serializer = serializer, columnTables = traits.columnTables, tables = traits.tables, isDeterministic = traits.isDeterministic) + + override fun literalOf(value: V): ClauseConverted = convertedLiteral(value, serializer) + + override fun rebind(relation: Relation<*>): ClauseConverted = + ClauseConverted(valueName, relation, isFunction = false, isNullable = isNullable, isAggregate = false, isNullOnNoRows = true, serializer = serializer) + + /** + * Returns [value] as the column stores it, which a condition compares the column with. + */ + internal fun stored(value: V): Any? = storedValueOf(serializer, value) + + internal infix fun eq(value: V?): SelectCondition = appendNullable("=", " IS NULL", value) + + internal infix fun eq(other: ClauseConverted): SelectCondition = appendElement("=", other) + + internal infix fun neq(value: V?): SelectCondition = appendNullable("!=", " IS NOT NULL", value) + + internal infix fun neq(other: ClauseConverted): SelectCondition = appendElement("!=", other) + + internal infix fun lt(value: V): SelectCondition = appendValue("): SelectCondition = appendElement("<", other) + + internal infix fun lte(value: V): SelectCondition = appendValue("<=?", value) + + internal infix fun lte(other: ClauseConverted): SelectCondition = appendElement("<=", other) + + internal infix fun gt(value: V): SelectCondition = appendValue(">?", value) + + internal infix fun gt(other: ClauseConverted): SelectCondition = appendElement(">", other) + + internal infix fun gte(value: V): SelectCondition = appendValue(">=?", value) + + internal infix fun gte(other: ClauseConverted): SelectCondition = appendElement(">=", other) + + internal infix fun inIterable(values: Iterable): SelectCondition { + val parameters = values.mapTo(ArrayList()) { stored(it) } + require(parameters.isNotEmpty()) { "Param 'values' must not be empty!!!" } + val sql = buildString { + appendSQL(this) + append(" IN (?") + repeat(parameters.size - 1) { + append(",?") + } + append(')') + } + return condition(sql, parameters) + } + + internal infix fun between(range: Pair): SelectCondition = + condition("$sql BETWEEN ? AND ?", mutableListOf(stored(range.first), stored(range.second))) + + /** + * The condition of this element and [value] converted: `IS NULL` or `IS NOT NULL` for null, or a value that the + * serializer stores as NULL. + */ + private fun appendNullable(notNullSymbol: String, nullSymbol: String, value: V?): SelectCondition { + val stored = value?.let { stored(it) } + return if (stored == null) + condition("$sql$nullSymbol", null) + else + condition("$sql$notNullSymbol?", mutableListOf(stored)) + } + + private fun appendValue(symbol: String, value: V): SelectCondition = + condition("$sql$symbol", mutableListOf(stored(value))) + + private fun appendElement(symbol: String, other: ClauseConverted): SelectCondition = + condition("$sql $symbol ${other.sql}", null, other) + + override fun hashCode(): Int = valueName.hashCode() + table.tableName.hashCode() + override fun equals(other: Any?): Boolean = (other as? ClauseConverted<*>)?.let { + it.valueName == valueName && it.table.tableName == table.tableName + } ?: false +} + +/** + * A literal value of a type that [serializer] converts, written as the value it stores, as the literal of a column of + * that type in `CASE`, or a value to set it to with `SET(listOf(literal(now, EpochMillisSerializer) AS Event::startsAt))`. + * Give it the serializer of the column, so that it is stored, and compared, as the column's values are. + */ +@ExperimentalDSLDatabaseAPI +public fun literal(value: V, serializer: SerializationStrategy): ClauseConverted = convertedLiteral(value, serializer) + +@OptIn(ExperimentalDSLDatabaseAPI::class) +private fun convertedLiteral(value: V, serializer: SerializationStrategy): ClauseConverted { + val stored = storedValueOf(serializer, value) + val literal = if (stored == null) "NULL" else expressionLiteral(stored) + return ClauseConverted(literal, ExpressionRelation, isFunction = true, isNullable = stored == null, isAggregate = false, isNullOnNoRows = stored == null, serializer = serializer, columnTables = emptySet(), isLiteral = true) +} diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseElement.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseElement.kt index 41df0772..2842857e 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseElement.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseElement.kt @@ -30,6 +30,8 @@ import com.ctrip.sqllin.dsl.sql.Relation * - [ClauseString]: String column/function references with text comparison operators * - [ClauseBlob]: BLOB (ByteArray) column references with comparison operators * - [ClauseEnum]: Enum column references with ordinal-based comparison operators + * - [ClauseConverted]: References to the columns of a type whose serializer converts its values, which its conditions + * compare as stored * * Used in: * - WHERE/HAVING conditions diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseEnum.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseEnum.kt index 0fe38608..accec98d 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseEnum.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ClauseEnum.kt @@ -26,6 +26,10 @@ import com.ctrip.sqllin.dsl.sql.Relation * during serialization/deserialization. `max` and `min` of an enum column are elements * of the same enum type. * + * Only an enum with its default serializer, which encodes the ordinal of an entry, is stored so: one with a serializer + * of its own, given on its class or on the property, as one that stores its name, gets a [ClauseConverted], which + * compares what that serializer stores. + * * Available operators: * - `lt`: Less than (<) - compares ordinal values * - `lte`: Less than or equal to (<=) - compares ordinal values diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/Collation.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/Collation.kt index f3faa2a1..781b2965 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/Collation.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/Collation.kt @@ -47,7 +47,9 @@ public object RTRIM : Collation("RTRIM") /** * The COLLATE operator: this string compared and sorted by [collation], as in `(name COLLATE NOCASE) EQ "ann"`, which - * matches `'Ann'` too, or in `ORDER_BY((name COLLATE NOCASE) to ASC)`. + * matches `'Ann'` too, or in `ORDER_BY((name COLLATE NOCASE) to ASC)`. Of a column, it is also a column of an index + * with that collation, as in `PersonTable.CREATE_INDEX("idx_person_name_nocase", PersonTable.name COLLATE NOCASE)`, + * which the queries comparing `(name COLLATE NOCASE)` use. */ @ExperimentalDSLDatabaseAPI @StatementDslMaker diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ConditionClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ConditionClause.kt index f1ecc79e..06052a61 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ConditionClause.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/ConditionClause.kt @@ -32,6 +32,7 @@ import com.ctrip.sqllin.dsl.annotation.StatementDslMaker * - String: LT, LTE, EQ, NEQ, GT, GTE, IN, BETWEEN, LIKE, GLOB * - Blob: LT, LTE, EQ, NEQ, GT, GTE, IN, BETWEEN * - Enum: LT, LTE, EQ, NEQ, GT, GTE + * - Converted ([ClauseConverted]): LT, LTE, EQ, NEQ, GT, GTE, IN, BETWEEN, IS, ISNOT * - Boolean: IS, ISNOT * - Logic: AND, OR * @@ -361,6 +362,90 @@ public infix fun > ClauseEnum.IS(other: ClauseEnum): SelectCon @StatementDslMaker public infix fun > ClauseEnum.ISNOT(other: ClauseEnum): SelectCondition = nullSafe("IS NOT", other) +// Conditions of a column whose serializer converts its values, which compare the values it stores with those the +// serializer stores for the values given. LT, LTE, GT, GTE and BETWEEN compare the stored values, which are in the +// order of the Kotlin values only if the serializer keeps it, as ClauseConverted explains. + +/** Whether this value, as stored, is less than [value]: `<`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.LT(value: V): SelectCondition = lt(value) + +/** Whether this value, as stored, is less than that of [other]: `<`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.LT(other: ClauseConverted): SelectCondition = lt(other) + +/** Whether this value, as stored, is less than or equal to [value]: `<=`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.LTE(value: V): SelectCondition = lte(value) + +/** Whether this value, as stored, is less than or equal to that of [other]: `<=`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.LTE(other: ClauseConverted): SelectCondition = lte(other) + +/** Whether this value equals [value]: `=`, or `IS NULL` for null. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.EQ(value: V?): SelectCondition = eq(value) + +/** Whether this value equals that of [other]: `=`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.EQ(other: ClauseConverted): SelectCondition = eq(other) + +/** Whether this value differs from [value]: `!=`, or `IS NOT NULL` for null. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.NEQ(value: V?): SelectCondition = neq(value) + +/** Whether this value differs from that of [other]: `!=`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.NEQ(other: ClauseConverted): SelectCondition = neq(other) + +/** Whether this value, as stored, is greater than [value]: `>`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.GT(value: V): SelectCondition = gt(value) + +/** Whether this value, as stored, is greater than that of [other]: `>`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.GT(other: ClauseConverted): SelectCondition = gt(other) + +/** Whether this value, as stored, is greater than or equal to [value]: `>=`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.GTE(value: V): SelectCondition = gte(value) + +/** Whether this value, as stored, is greater than or equal to that of [other]: `>=`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.GTE(other: ClauseConverted): SelectCondition = gte(other) + +/** Whether this value is one of [values]: `IN (...)`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.IN(values: Iterable): SelectCondition = inIterable(values) + +/** Whether this value, as stored, is between the two of [range], both included: `BETWEEN ... AND ...`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.BETWEEN(range: Pair): SelectCondition = between(range) + +/** Whether this value equals that of [other], NULL equaling NULL: `this IS other`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.IS(other: ClauseConverted): SelectCondition = nullSafe("IS", other) + +/** Whether this value differs from that of [other], NULL equaling NULL: `this IS NOT other`. */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun ClauseConverted.ISNOT(other: ClauseConverted): SelectCondition = nullSafe("IS NOT", other) + private fun ClauseElement<*>.nullSafe(operator: String, other: ClauseElement<*>): SelectCondition = condition("$sql $operator ${other.sql}", null, other) diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/CrossJoinClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/CrossJoinClause.kt deleted file mode 100644 index 69b0d894..00000000 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/CrossJoinClause.kt +++ /dev/null @@ -1,57 +0,0 @@ -/* - * Copyright (C) 2022 Ctrip.com. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package com.ctrip.sqllin.dsl.sql.clause - -import com.ctrip.sqllin.dsl.sql.Relation -import com.ctrip.sqllin.dsl.annotation.StatementDslMaker - -/** - * CROSS JOIN clause - returns the Cartesian product of two tables. - * - * Generates SQL: ` CROSS JOIN table` - * Does not require ON or USING condition. - * Returns every combination of rows from both tables. - * - * **Warning**: Result size = (left rows) × (right rows). Use with caution on large tables. - * - * @param R The result entity type after JOIN - * - * @author Yuang Qiao - */ -internal class CrossJoinClause(vararg tables: Relation<*>) : NaturalJoinClause(*tables) { - override val clauseName: String = " CROSS JOIN " -} - -/** - * Creates a CROSS JOIN clause (no ON/USING needed). - * - * Usage: - * ```kotlin - * SELECT(color) CROSS_JOIN (size) - * // Returns all color-size combinations - * ``` - * - * **Warning**: Returns (left rows) × (right rows) results. - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ -@Suppress("DSL_MARKER_APPLIED_TO_WRONG_TARGET") -@StatementDslMaker -public fun CROSS_JOIN(vararg tables: Relation<*>): NaturalJoinClause = CrossJoinClause(*tables) \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/GroupByClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/GroupByClause.kt index 374aa6db..f6d03f8e 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/GroupByClause.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/GroupByClause.kt @@ -20,7 +20,6 @@ package com.ctrip.sqllin.dsl.sql.clause import com.ctrip.sqllin.dsl.annotation.StatementDslMaker import com.ctrip.sqllin.dsl.sql.statement.GroupBySelectStatement -import com.ctrip.sqllin.dsl.sql.statement.JoinSelectStatement import com.ctrip.sqllin.dsl.sql.statement.ResultColumnSelectStatement import com.ctrip.sqllin.dsl.sql.statement.WhereSelectStatement @@ -66,26 +65,13 @@ public fun GROUP_BY(vararg elements: ClauseElement<*>): GroupByClause = G @StatementDslMaker public infix fun WhereSelectStatement.GROUP_BY(element: ClauseElement<*>): GroupBySelectStatement = appendToGroupBy(GroupByClause(listOf(element))).also { - container changeLastStatement it + container.replaceStatement(this, it) } @StatementDslMaker public infix fun WhereSelectStatement.GROUP_BY(elements: Iterable>): GroupBySelectStatement { val statement = appendToGroupBy(GroupByClause(elements)) - container changeLastStatement statement - return statement -} - -@StatementDslMaker -public infix fun JoinSelectStatement.GROUP_BY(element: ClauseElement<*>): GroupBySelectStatement = - appendToGroupBy(GroupByClause(listOf(element))).also { - container changeLastStatement it - } - -@StatementDslMaker -public infix fun JoinSelectStatement.GROUP_BY(elements: Iterable>): GroupBySelectStatement { - val statement = appendToGroupBy(GroupByClause(elements)) - container changeLastStatement statement + container.replaceStatement(this, statement) return statement } @@ -96,6 +82,6 @@ public infix fun ResultColumnSelectStatement.GROUP_BY(element: ClauseElem @StatementDslMaker public infix fun ResultColumnSelectStatement.GROUP_BY(elements: Iterable>): GroupBySelectStatement { val statement = appendToGroupBy(GroupByClause(elements)) - container changeLastStatement statement + container.replaceStatement(this, statement) return statement } \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/HavingClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/HavingClause.kt index 6309dbbc..7eb8393f 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/HavingClause.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/HavingClause.kt @@ -45,5 +45,5 @@ internal class HavingClause(val selectCondition: SelectCondition) : Condition @StatementDslMaker public infix fun GroupBySelectStatement.HAVING(condition: SelectCondition): HavingSelectStatement = appendToHaving(HavingClause(condition)).also { - container changeLastStatement it + container.replaceStatement(this, it) } \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/InnerJoinClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/InnerJoinClause.kt deleted file mode 100644 index bba48786..00000000 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/InnerJoinClause.kt +++ /dev/null @@ -1,111 +0,0 @@ -/* - * Copyright (C) 2022 Ctrip.com. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -@file:Suppress("DSL_MARKER_APPLIED_TO_WRONG_TARGET") - -package com.ctrip.sqllin.dsl.sql.clause - -import com.ctrip.sqllin.dsl.sql.Relation -import com.ctrip.sqllin.dsl.annotation.StatementDslMaker - -/** - * INNER JOIN clause - returns rows where there's a match in both tables. - * - * Generates SQL: ` JOIN table` - * Requires ON or USING condition. - * - * @param R The result entity type after JOIN - * - * @author Yuang Qiao - */ -internal class InnerJoinClause( - vararg tables: Relation<*>, -) : JoinClause(*tables) { - - override val clauseName: String = " JOIN " -} - -/** - * Creates an INNER JOIN clause (requires ON or USING). - * - * Usage: - * ```kotlin - * SELECT(user) JOIN (order) ON (user.id EQ order.userId) - * SELECT(user) JOIN (order) USING (user.id) - * ``` - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ -@StatementDslMaker -public fun JOIN(vararg tables: Relation<*>): JoinClause = InnerJoinClause(*tables) - -/** - * Alias for [JOIN] - creates an INNER JOIN clause. - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ -@StatementDslMaker -public inline fun INNER_JOIN(vararg tables: Relation<*>): JoinClause = JOIN(*tables) - -/** - * NATURAL INNER JOIN - automatically joins on columns with matching names. - * - * Generates SQL: ` NATURAL JOIN table` - * Does not require ON or USING. - * - * @param R The result entity type after JOIN - * - * @author Yuang Qiao - */ -internal class NaturalInnerJoinClause( - vararg tables: Relation<*>, -) : NaturalJoinClause(*tables) { - - override val clauseName: String = " NATURAL JOIN " -} - -/** - * Creates a NATURAL JOIN clause (no ON/USING needed). - * - * Usage: - * ```kotlin - * SELECT(user) NATURAL_JOIN (profile) // Joins on matching column names - * ``` - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ -@StatementDslMaker -public fun NATURAL_JOIN(vararg tables: Relation<*>): NaturalJoinClause = NaturalInnerJoinClause(*tables) - -/** - * Alias for [NATURAL_JOIN]. - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ -@StatementDslMaker -public inline fun NATURAL_INNER_JOIN(vararg tables: Relation<*>): NaturalJoinClause = NATURAL_JOIN(*tables) \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/LeftOuterJoinClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/LeftOuterJoinClause.kt deleted file mode 100644 index 0cbb7835..00000000 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/LeftOuterJoinClause.kt +++ /dev/null @@ -1,91 +0,0 @@ -/* - * Copyright (C) 2022 Ctrip.com. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package com.ctrip.sqllin.dsl.sql.clause - -import com.ctrip.sqllin.dsl.sql.Relation -import com.ctrip.sqllin.dsl.annotation.StatementDslMaker - -/** - * LEFT OUTER JOIN clause - returns all rows from the left table and matching rows from the right. - * - * Generates SQL: ` LEFT OUTER JOIN table` - * Requires ON or USING condition. - * Returns NULL for right table columns when there's no match. - * - * @param R The result entity type after JOIN - * - * @author Yuang Qiao - */ -internal class LeftOuterJoinClause( - vararg tables: Relation<*> -) : JoinClause(*tables) { - - override val clauseName: String = " LEFT OUTER JOIN " -} - -/** - * Creates a LEFT OUTER JOIN clause (requires ON or USING). - * - * Usage: - * ```kotlin - * SELECT(user) LEFT_OUTER_JOIN (order) ON (user.id EQ order.userId) - * // Returns all users, including those without orders - * ``` - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ -@Suppress("DSL_MARKER_APPLIED_TO_WRONG_TARGET") -@StatementDslMaker -public fun LEFT_OUTER_JOIN(vararg tables: Relation<*>): JoinClause = LeftOuterJoinClause(*tables) - -/** - * NATURAL LEFT OUTER JOIN - automatically joins on matching column names. - * - * Generates SQL: ` NATURAL LEFT OUTER JOIN table` - * Does not require ON or USING. - * Returns all left table rows, with NULLs for non-matching right table columns. - * - * @param R The result entity type after JOIN - * - * @author Yuang Qiao - */ -internal class NaturalLeftOuterJoinClause( - vararg tables: Relation<*> -) : NaturalJoinClause(*tables) { - - override val clauseName: String = " NATURAL LEFT OUTER JOIN " -} - -/** - * Creates a NATURAL LEFT OUTER JOIN clause (no ON/USING needed). - * - * Usage: - * ```kotlin - * SELECT(user) NATURAL_LEFT_OUTER_JOIN (profile) - * ``` - * - * **To be removed in the next version after 2.5.0**: this join API is replaced by joins of relations, such as - * `(FROM(PersonTable) INNER_JOIN BookTable ON (...)) SELECT X()`, which check the type their rows are read into - * against the joined relations, and can join more than two. See - * [JoinedRelation][com.ctrip.sqllin.dsl.sql.clause.JoinedRelation]. - */ -@Suppress("DSL_MARKER_APPLIED_TO_WRONG_TARGET") -@StatementDslMaker -public fun NATURAL_LEFT_OUTER_JOIN(vararg tables: Relation<*>): NaturalJoinClause = NaturalLeftOuterJoinClause(*tables) \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/LimitClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/LimitClause.kt index bb034c4c..d0dc9d95 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/LimitClause.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/LimitClause.kt @@ -52,38 +52,32 @@ public fun LIMIT(count: Int): LimitClause = LimitClause(count) @StatementDslMaker public infix fun WhereSelectStatement.LIMIT(count: Int): LimitSelectStatement = appendToLimit(LimitClause(count)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @StatementDslMaker public infix fun OrderBySelectStatement.LIMIT(count: Int): LimitSelectStatement = appendToLimit(LimitClause(count)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @StatementDslMaker public infix fun HavingSelectStatement.LIMIT(count: Int): LimitSelectStatement = appendToLimit(LimitClause(count)).also { - container changeLastStatement it - } - -@StatementDslMaker -public infix fun JoinSelectStatement.LIMIT(count: Int): LimitSelectStatement = - appendToLimit(LimitClause(count)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @ExperimentalDSLDatabaseAPI @StatementDslMaker public infix fun CompoundSelectStatement.LIMIT(count: Int): LimitSelectStatement = appendToLimit(LimitClause(count)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @StatementDslMaker public infix fun ResultColumnSelectStatement.LIMIT(count: Int): LimitSelectStatement = appendToLimit(LimitClause(count)).also { - container changeLastStatement it + container.replaceStatement(this, it) } /** @@ -110,5 +104,61 @@ public class OffsetClause internal constructor( @StatementDslMaker public infix fun LimitSelectStatement.OFFSET(rowNo: Int): FinalSelectStatement = appendToFinal(OffsetClause(rowNo)).also { - container changeLastStatement it - } \ No newline at end of file + container.replaceStatement(this, it) + } + +// ========== LIMIT and OFFSET of UPDATE and DELETE ========== + +/** + * Makes this UPDATE or DELETE write at most [count] rows, the first in the order of the ORDER BY before it if it has + * one, and otherwise any, as in `PersonTable DELETE WHERE(PersonTable.age LT 18) LIMIT 1000`, which deletes the rows in + * batches; a negative count is no limit, which only OFFSET then gives, as in + * `ORDER_BY (MessageTable.time to DESC) LIMIT -1 OFFSET 100`, the rows after the first 100. + * + * SQLlin writes it as the subquery that SQLite turns it into, which every platform runs, as + * [WhereUpdateDeleteStatement.ORDER_BY] describes. + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun WhereUpdateDeleteStatement.LIMIT(count: Int): LimitUpdateDeleteStatement = + LimitUpdateDeleteStatement(parts.copy(limit = count), container, connection).also { + container.replaceStatement(this, it) + } + +/** + * Makes this UPDATE or DELETE write at most [count] rows, the first in the order of its ORDER BY. + * + * @see WhereUpdateDeleteStatement.LIMIT + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun OrderByUpdateDeleteStatement.LIMIT(count: Int): LimitUpdateDeleteStatement = + LimitUpdateDeleteStatement(parts.copy(limit = count), container, connection).also { + container.replaceStatement(this, it) + } + +/** + * Makes this UPDATE without WHERE write at most [count] rows of the table. + * + * @see WhereUpdateDeleteStatement.LIMIT + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun UpdateStatementWithoutWhereClause.LIMIT(count: Int): LimitUpdateDeleteStatement = + LimitUpdateDeleteStatement(parts.copy(limit = count), statementContainer, connection).also { + statementContainer.replaceStatement(this, it) + } + +/** + * Makes this UPDATE or DELETE skip [rowNo] rows before those its LIMIT chooses, in the order of its ORDER BY. + * + * @see WhereUpdateDeleteStatement.LIMIT + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun LimitUpdateDeleteStatement.OFFSET(rowNo: Int): UpdateDeleteStatement { + val final = parts.copy(offset = rowNo) + return UpdateDeleteStatement(final.sql, connection, final.parameters, final.tableName).also { + container.replaceStatement(this, it) + } +} diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/OrderByClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/OrderByClause.kt index a18a3b70..9daea39d 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/OrderByClause.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/OrderByClause.kt @@ -157,7 +157,7 @@ public inline infix fun WhereSelectStatement.ORDER_BY(column2Way: Pair WhereSelectStatement.ORDER_BY(column2WayMap: Map, Ordering>): OrderBySelectStatement = appendToOrderBy(CompleteOrderByClause(column2WayMap)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @StatementDslMaker @@ -167,7 +167,7 @@ public inline infix fun HavingSelectStatement.ORDER_BY(column2Way: Pair HavingSelectStatement.ORDER_BY(column2WayMap: Map, Ordering>): OrderBySelectStatement = appendToOrderBy(CompleteOrderByClause(column2WayMap)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @StatementDslMaker @@ -177,17 +177,7 @@ public inline infix fun GroupBySelectStatement.ORDER_BY(column2Way: Pair< @StatementDslMaker public infix fun GroupBySelectStatement.ORDER_BY(column2WayMap: Map, Ordering>): OrderBySelectStatement = appendToOrderBy(CompleteOrderByClause(column2WayMap)).also { - container changeLastStatement it - } - -@StatementDslMaker -public inline infix fun JoinSelectStatement.ORDER_BY(column2Way: Pair, Ordering>): OrderBySelectStatement = - ORDER_BY(mapOf(column2Way)) - -@StatementDslMaker -public infix fun JoinSelectStatement.ORDER_BY(column2WayMap: Map, Ordering>): OrderBySelectStatement = - appendToOrderBy(CompleteOrderByClause(column2WayMap)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @ExperimentalDSLDatabaseAPI @@ -199,7 +189,7 @@ public infix fun CompoundSelectStatement.ORDER_BY(column2Way: Pair CompoundSelectStatement.ORDER_BY(column2WayMap: Map, Ordering>): OrderBySelectStatement = appendToOrderBy(CompleteOrderByClause(column2WayMap, isQualified = false)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @ExperimentalDSLDatabaseAPI @@ -211,7 +201,7 @@ public infix fun CompoundSelectStatement.ORDER_BY(column: ClauseElement<* @StatementDslMaker public infix fun CompoundSelectStatement.ORDER_BY(columns: Iterable>): OrderBySelectStatement = appendToOrderBy(SimpleOrderByClause(columns, isQualified = false)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @StatementDslMaker @@ -221,7 +211,7 @@ public infix fun ResultColumnSelectStatement.ORDER_BY(column2Way: Pair ResultColumnSelectStatement.ORDER_BY(column2WayMap: Map, Ordering>): OrderBySelectStatement = appendToOrderBy(CompleteOrderByClause(column2WayMap)).also { - container changeLastStatement it + container.replaceStatement(this, it) } internal class SimpleOrderByClause( @@ -259,7 +249,7 @@ public inline infix fun WhereSelectStatement.ORDER_BY(column: ClauseEleme @StatementDslMaker public infix fun WhereSelectStatement.ORDER_BY(columns: Iterable>): OrderBySelectStatement = appendToOrderBy(SimpleOrderByClause(columns)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @StatementDslMaker @@ -269,7 +259,7 @@ public inline infix fun HavingSelectStatement.ORDER_BY(column: ClauseElem @StatementDslMaker public infix fun HavingSelectStatement.ORDER_BY(columns: Iterable>): OrderBySelectStatement = appendToOrderBy(SimpleOrderByClause(columns)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @StatementDslMaker @@ -279,25 +269,68 @@ public inline infix fun GroupBySelectStatement.ORDER_BY(column: ClauseEle @StatementDslMaker public infix fun GroupBySelectStatement.ORDER_BY(columns: Iterable>): OrderBySelectStatement = appendToOrderBy(SimpleOrderByClause(columns)).also { - container changeLastStatement it + container.replaceStatement(this, it) } @StatementDslMaker -public inline infix fun JoinSelectStatement.ORDER_BY(column: ClauseElement<*>): OrderBySelectStatement = +public infix fun ResultColumnSelectStatement.ORDER_BY(column: ClauseElement<*>): OrderBySelectStatement = ORDER_BY(listOf(column)) @StatementDslMaker -public infix fun JoinSelectStatement.ORDER_BY(columns: Iterable>): OrderBySelectStatement = +public infix fun ResultColumnSelectStatement.ORDER_BY(columns: Iterable>): OrderBySelectStatement = appendToOrderBy(SimpleOrderByClause(columns)).also { - container changeLastStatement it + container.replaceStatement(this, it) } +// ========== ORDER BY of UPDATE and DELETE ========== + +/** + * Orders the rows that this UPDATE or DELETE writes by [column2Way], so that the LIMIT that has to follow chooses the + * first in that order, as in + * `PersonTable DELETE WHERE(PersonTable.age LT 18) ORDER_BY (PersonTable.age to ASC) LIMIT 10`. + * + * SQLite only takes ORDER BY and LIMIT in an UPDATE or DELETE when it is built with an option that Android's SQLite + * lacks, so SQLlin writes the subquery that SQLite turns them into, which every platform runs: + * `DELETE FROM person WHERE rowid IN (SELECT rowid FROM person WHERE person.age ResultColumnSelectStatement.ORDER_BY(column: ClauseElement<*>): OrderBySelectStatement = - ORDER_BY(listOf(column)) +public infix fun WhereUpdateDeleteStatement.ORDER_BY(column2Way: Pair, Ordering>): OrderByUpdateDeleteStatement = + ORDER_BY(mapOf(column2Way)) + +/** + * Orders the rows that this UPDATE or DELETE writes by the columns of [column2WayMap], in its order. + * + * @see WhereUpdateDeleteStatement.ORDER_BY + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun WhereUpdateDeleteStatement.ORDER_BY(column2WayMap: Map, Ordering>): OrderByUpdateDeleteStatement = + OrderByUpdateDeleteStatement(parts.copy(orderBy = CompleteOrderByClause(column2WayMap)), container, connection).also { + container.replaceStatement(this, it) + } +/** + * Orders the rows of the table that this UPDATE without WHERE writes by [column2Way], so that the LIMIT that has to + * follow chooses the first in that order. + * + * @see WhereUpdateDeleteStatement.ORDER_BY + */ +@ExperimentalDSLDatabaseAPI @StatementDslMaker -public infix fun ResultColumnSelectStatement.ORDER_BY(columns: Iterable>): OrderBySelectStatement = - appendToOrderBy(SimpleOrderByClause(columns)).also { - container changeLastStatement it - } \ No newline at end of file +public infix fun UpdateStatementWithoutWhereClause.ORDER_BY(column2Way: Pair, Ordering>): OrderByUpdateDeleteStatement = + ORDER_BY(mapOf(column2Way)) + +/** + * Orders the rows of the table that this UPDATE without WHERE writes by the columns of [column2WayMap], in its order. + * + * @see WhereUpdateDeleteStatement.ORDER_BY + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun UpdateStatementWithoutWhereClause.ORDER_BY(column2WayMap: Map, Ordering>): OrderByUpdateDeleteStatement = + OrderByUpdateDeleteStatement(parts.copy(orderBy = CompleteOrderByClause(column2WayMap)), statementContainer, connection).also { + statementContainer.replaceStatement(this, it) + } diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/RelationJoin.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/RelationJoin.kt index d18239ba..777f4fb4 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/RelationJoin.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/RelationJoin.kt @@ -35,7 +35,7 @@ import com.ctrip.sqllin.dsl.sql.Relation * * // SELECT person.name AS name,count(book.title) AS books FROM person LEFT OUTER JOIN book ON person.id=book.authorId * // GROUP BY person.id - * (FROM(PersonTable) LEFT_OUTER_JOIN BookTable ON (PersonTable.id EQ BookTable.authorId)) SELECT listOf( + * (PersonTable LEFT_OUTER_JOIN BookTable ON (PersonTable.id EQ BookTable.authorId)) SELECT listOf( * PersonTable.name AS PersonBooks::name, * PersonTable.count(BookTable.title) AS PersonBooks::books, * ) GROUP_BY PersonTable.id @@ -47,16 +47,17 @@ import com.ctrip.sqllin.dsl.sql.Relation * otherwise; and has to be nullable when its column or expression can be NULL, which an outer join makes those of a * relation it can leave without a matching row, but `count`. SQLlin writes the columns with their relations' names. * - * A join starts with `FROM(relation)`, and its joins are applied in the order they are written: - * `FROM(a) INNER_JOIN b ON (...) LEFT_OUTER_JOIN c ON (...)`. A relation can only be joined once; to join a table with - * itself, join a derived table of its rows, which gives it another name. + * A join starts with its first relation, as `a INNER_JOIN b ON (...)` does, or with `FROM(a)`, and its joins are + * applied in the order they are written: `a INNER_JOIN b ON (...) LEFT_OUTER_JOIN c ON (...)`. A relation can only be + * joined once; to join a table with itself, join a derived table of its rows, which gives it another name. * * @author Yuang Qiao */ /** * Relations joined as a FROM clause writes them, such as `person INNER JOIN book ON person.id=book.authorId`, which a - * SELECT reads, or another join extends. `FROM(relation)` starts one. + * SELECT reads, or another join extends. A join operator applied to a relation starts one, as in + * `PersonTable INNER_JOIN BookTable ON (...)`, and so does `FROM(relation)`. * * A SELECT of a join has to name the type it reads rows into, as rows of a join have no type of their own: * `joined SELECT X()`, `joined SELECT WHERE(...)`, or result columns. @@ -92,7 +93,8 @@ public class JoinWithoutCondition internal constructor( /** * Starts a join with [relation], the first relation of a FROM clause, which `INNER_JOIN`, `LEFT_OUTER_JOIN` and the - * other joins extend: `FROM(PersonTable) INNER_JOIN BookTable ON (...)`. + * other joins extend: `FROM(PersonTable) INNER_JOIN BookTable ON (...)`. A join operator applied to the relation itself + * starts the same join: `PersonTable INNER_JOIN BookTable ON (...)`. */ @ExperimentalDSLDatabaseAPI @StatementDslMaker @@ -247,3 +249,96 @@ public infix fun JoinedRelation.NATURAL_FULL_OUTER_JOIN(relation: Relation<*>): @OptIn(ExperimentalDSLDatabaseAPI::class) private fun From.naturalfullouterjoin(relation: Relation<*>): JoinedRelation = JoinedRelation(join("NATURAL FULL OUTER JOIN", relation, From.Constraint.NONE, isLeftNullable = true, isRightNullable = true, isNatural = true)) + +/** + * Starts a join with this relation, and joins [relation] to it with `INNER JOIN`, which [ON] or [USING] completes, as + * `FROM(this) INNER_JOIN relation` does. + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun Relation<*>.INNER_JOIN(relation: Relation<*>): JoinWithoutCondition = + From.of(this).innerjoin(relation) + +/** + * Starts a join with this relation, and joins [relation] to it with `LEFT OUTER JOIN`, which [ON] or [USING] completes, as + * `FROM(this) LEFT_OUTER_JOIN relation` does. + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun Relation<*>.LEFT_OUTER_JOIN(relation: Relation<*>): JoinWithoutCondition = + From.of(this).leftouterjoin(relation) + +/** + * Starts a join with this relation, and joins [relation] to it with `RIGHT OUTER JOIN`, which [ON] or [USING] completes, as + * `FROM(this) RIGHT_OUTER_JOIN relation` does. + * + * `RIGHT` and `FULL` joins need SQLite 3.39.0, which Android has from API 34 on. + */ +@ExperimentalDSLDatabaseAPI +@PlatformDependentSQLiteAPI +@StatementDslMaker +public infix fun Relation<*>.RIGHT_OUTER_JOIN(relation: Relation<*>): JoinWithoutCondition = + From.of(this).rightouterjoin(relation) + +/** + * Starts a join with this relation, and joins [relation] to it with `FULL OUTER JOIN`, which [ON] or [USING] completes, as + * `FROM(this) FULL_OUTER_JOIN relation` does. + * + * `RIGHT` and `FULL` joins need SQLite 3.39.0, which Android has from API 34 on. + */ +@ExperimentalDSLDatabaseAPI +@PlatformDependentSQLiteAPI +@StatementDslMaker +public infix fun Relation<*>.FULL_OUTER_JOIN(relation: Relation<*>): JoinWithoutCondition = + From.of(this).fullouterjoin(relation) + +/** + * Starts a join with this relation, and joins [relation] to it with `CROSS JOIN`, as + * `FROM(this) CROSS_JOIN relation` does. + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun Relation<*>.CROSS_JOIN(relation: Relation<*>): JoinedRelation = + From.of(this).crossjoin(relation) + +/** + * Starts a join with this relation, and joins [relation] to it with `NATURAL JOIN`, as + * `FROM(this) NATURAL_JOIN relation` does. + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun Relation<*>.NATURAL_JOIN(relation: Relation<*>): JoinedRelation = + From.of(this).naturaljoin(relation) + +/** + * Starts a join with this relation, and joins [relation] to it with `NATURAL LEFT OUTER JOIN`, as + * `FROM(this) NATURAL_LEFT_OUTER_JOIN relation` does. + */ +@ExperimentalDSLDatabaseAPI +@StatementDslMaker +public infix fun Relation<*>.NATURAL_LEFT_OUTER_JOIN(relation: Relation<*>): JoinedRelation = + From.of(this).naturalleftouterjoin(relation) + +/** + * Starts a join with this relation, and joins [relation] to it with `NATURAL RIGHT OUTER JOIN`, as + * `FROM(this) NATURAL_RIGHT_OUTER_JOIN relation` does. + * + * `RIGHT` and `FULL` joins need SQLite 3.39.0, which Android has from API 34 on. + */ +@ExperimentalDSLDatabaseAPI +@PlatformDependentSQLiteAPI +@StatementDslMaker +public infix fun Relation<*>.NATURAL_RIGHT_OUTER_JOIN(relation: Relation<*>): JoinedRelation = + From.of(this).naturalrightouterjoin(relation) + +/** + * Starts a join with this relation, and joins [relation] to it with `NATURAL FULL OUTER JOIN`, as + * `FROM(this) NATURAL_FULL_OUTER_JOIN relation` does. + * + * `RIGHT` and `FULL` joins need SQLite 3.39.0, which Android has from API 34 on. + */ +@ExperimentalDSLDatabaseAPI +@PlatformDependentSQLiteAPI +@StatementDslMaker +public infix fun Relation<*>.NATURAL_FULL_OUTER_JOIN(relation: Relation<*>): JoinedRelation = + From.of(this).naturalfullouterjoin(relation) diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/SelectClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/SelectClause.kt index 3aa6e1a2..4339fd13 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/SelectClause.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/SelectClause.kt @@ -29,7 +29,6 @@ package com.ctrip.sqllin.dsl.sql.clause * - [OffsetClause]: OFFSET row skipping * - [GroupByClause]: GROUP BY aggregation grouping * - [HavingClause]: HAVING condition for grouped data - * - [JoinClause], [InnerJoinClause], [LeftOuterJoinClause], [CrossJoinClause], [NaturalJoinClause]: JOIN operations * * @param T The entity type this clause operates on * @property clauseStr The SQL string representation (e.g., " WHERE id = ?", " ORDER BY name ASC") diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/WhereClause.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/WhereClause.kt index 8060c742..8f5fb36c 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/WhereClause.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/clause/WhereClause.kt @@ -21,11 +21,10 @@ package com.ctrip.sqllin.dsl.sql.clause import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI import com.ctrip.sqllin.dsl.annotation.StatementDslMaker import com.ctrip.sqllin.dsl.sql.statement.IndexStatement -import com.ctrip.sqllin.dsl.sql.statement.JoinSelectStatement import com.ctrip.sqllin.dsl.sql.statement.ResultColumnSelectStatement -import com.ctrip.sqllin.dsl.sql.statement.UpdateDeleteStatement import com.ctrip.sqllin.dsl.sql.statement.UpdateStatementWithoutWhereClause import com.ctrip.sqllin.dsl.sql.statement.WhereSelectStatement +import com.ctrip.sqllin.dsl.sql.statement.WhereUpdateDeleteStatement /** * WHERE clause for filtering rows in SELECT statements or targeting rows in UPDATE/DELETE statements. @@ -56,16 +55,10 @@ public class WhereClause internal constructor( @StatementDslMaker public fun WHERE(condition: SelectCondition): WhereClause = WhereClause(condition) -@StatementDslMaker -public infix fun JoinSelectStatement.WHERE(condition: SelectCondition): WhereSelectStatement = - appendToWhere(WhereClause(condition)).also { - container changeLastStatement it - } - @StatementDslMaker public infix fun ResultColumnSelectStatement.WHERE(condition: SelectCondition): WhereSelectStatement = appendToWhere(WhereClause(condition)).also { - container changeLastStatement it + container.replaceStatement(this, it) } /** @@ -82,26 +75,13 @@ public infix fun ResultColumnSelectStatement.WHERE(condition: SelectCondi * ``` * * @param condition The WHERE condition with its parameters - * @return The complete UPDATE statement SQL string + * @return The UPDATE statement, which ORDER BY and LIMIT can follow, so that it only updates the first rows in an order */ @StatementDslMaker -public infix fun UpdateStatementWithoutWhereClause.WHERE(condition: SelectCondition): String { - val params = when { - parameters == null && condition.parameters != null -> condition.parameters - parameters != null && condition.parameters == null -> parameters - parameters == null && condition.parameters == null -> null - else -> { - parameters!!.addAll(condition.parameters!!) - parameters - } +public infix fun UpdateStatementWithoutWhereClause.WHERE(condition: SelectCondition): WhereUpdateDeleteStatement = + WhereUpdateDeleteStatement(parts.copy(where = condition), statementContainer, connection).also { + statementContainer.replaceStatement(this, it) } - val statement = UpdateDeleteStatement(buildString { - append(sqlStr) - append(WhereClause(condition).clauseStr) - }, connection, params, table) - statementContainer changeLastStatement statement - return statement.sqlStr -} /** * Makes this index a partial index of the rows that satisfy [condition], as the SQL `CREATE INDEX ... WHERE condition` diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/compiler/StoredValueEncoder.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/compiler/StoredValueEncoder.kt new file mode 100644 index 00000000..044c76cb --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/compiler/StoredValueEncoder.kt @@ -0,0 +1,89 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.sql.compiler + +import kotlinx.serialization.ExperimentalSerializationApi +import kotlinx.serialization.SerializationStrategy +import kotlinx.serialization.descriptors.SerialDescriptor +import kotlinx.serialization.encoding.AbstractEncoder +import kotlinx.serialization.encoding.CompositeEncoder +import kotlinx.serialization.modules.EmptySerializersModule +import kotlinx.serialization.modules.SerializersModule + +/** + * Returns [value] as [serializer] writes it to the database, the value a column of its type holds, as + * [InsertValuesEncoder] writes the value of a property: a number, a string, a Boolean, a `ByteArray`, or null. An + * unsigned number is the number it is, as [storedValue] gives it, and an enum entry its ordinal, as its default + * serializer encodes it. + * + * A condition compares a column with the value a Kotlin value is stored as, so that `createdAt GT instant` compares + * what the serializer of `createdAt` wrote with what it writes for `instant`. + * + * @throws IllegalArgumentException if [serializer] doesn't encode [value] as one value, as the plugin-generated + * serializer of a class encodes each of its properties + */ +internal fun storedValueOf(serializer: SerializationStrategy, value: V): Any? { + val encoder = StoredValueEncoder(serializer) + encoder.encodeSerializableValue(serializer, value) + require(encoder.isEncoded) { + "The serializer '${serializer.descriptor.serialName}' encoded no value, while a column holds one." + } + return encoder.value +} + +/** + * The encoder of [storedValueOf], which keeps the one value a serializer encodes. + * + * @author Yuang Qiao + */ +@OptIn(ExperimentalSerializationApi::class) +private class StoredValueEncoder(private val serializer: SerializationStrategy<*>) : AbstractEncoder() { + + override val serializersModule: SerializersModule = EmptySerializersModule() + + var value: Any? = null + private set + + var isEncoded = false + private set + + private fun keep(value: Any?) { + require(!isEncoded) { + "The serializer '${serializer.descriptor.serialName}' encoded more than one value, while a column holds one." + } + this.value = value + isEncoded = true + } + + override fun encodeValue(value: Any) = keep(value) + + override fun encodeNull() = keep(null) + + override fun beginStructure(descriptor: SerialDescriptor): CompositeEncoder = + throw IllegalArgumentException( + "The serializer '${serializer.descriptor.serialName}' encodes a structure, '${descriptor.serialName}', while a column holds one value. " + + "Give the property a serializer that encodes it as a number, a string, a Boolean or a ByteArray, as JSON in a string, for example." + ) + + // As InsertValuesEncoder does: a ByteArray is a BLOB, rather than the list of bytes its serializer encodes + override fun encodeSerializableValue(serializer: SerializationStrategy, value: T) = + when (value) { + is ByteArray -> keep(value) + is UByte, is UShort, is UInt, is ULong -> keep(storedValue(value)) + else -> super.encodeSerializableValue(serializer, value) + } +} diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Alter.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Alter.kt index f0fef5b1..63b4c808 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Alter.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Alter.kt @@ -18,6 +18,7 @@ package com.ctrip.sqllin.dsl.sql.operation import com.ctrip.sqllin.driver.DatabaseConnection import com.ctrip.sqllin.dsl.sql.Table +import com.ctrip.sqllin.dsl.sql.columnTypeOf import com.ctrip.sqllin.dsl.sql.clause.ClauseElement import com.ctrip.sqllin.dsl.sql.statement.SingleStatement import com.ctrip.sqllin.dsl.sql.statement.TableStructureStatement @@ -71,12 +72,14 @@ internal object Alter : Operation { /** * Creates an ALTER TABLE ADD COLUMN statement. * - * Adds a new column to an existing table. + * Adds a new column to an existing table, of the type its property's serializer stores, as `CREATE TABLE` gives + * it. * * @param table The table to modify * @param newColumn The column definition to add * @param connection The database connection for executing the statement * @return A [TableStructureStatement] representing the ADD COLUMN operation + * @throws IllegalArgumentException if the serializer of the column's property encodes a structure */ fun addColumn(table: Table<*>, newColumn: ClauseElement<*>, connection: DatabaseConnection): SingleStatement { val sql = buildString { @@ -84,10 +87,8 @@ internal object Alter : Operation { append(table.tableName) append(ADD_COLUMN) append(newColumn.valueName) - val propertyDescriptor = table.kSerializer().descriptor - val index = propertyDescriptor.getElementIndex(newColumn.valueName) - val descriptor = propertyDescriptor.getElementDescriptor(index) - append(FullNameCache.getTypeNameBySerialName(descriptor, newColumn.valueName, table)) + append(' ') + append(table.columnTypeOf(newColumn.valueName)) } return TableStructureStatement(sql, connection) } diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Delete.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Delete.kt index 3598ae70..d25542dc 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Delete.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Delete.kt @@ -17,10 +17,11 @@ package com.ctrip.sqllin.dsl.sql.operation import com.ctrip.sqllin.driver.DatabaseConnection -import com.ctrip.sqllin.dsl.sql.statement.SingleStatement import com.ctrip.sqllin.dsl.sql.Table import com.ctrip.sqllin.dsl.sql.clause.WhereClause -import com.ctrip.sqllin.dsl.sql.statement.UpdateDeleteStatement +import com.ctrip.sqllin.dsl.sql.statement.StatementContainer +import com.ctrip.sqllin.dsl.sql.statement.UpdateDeleteParts +import com.ctrip.sqllin.dsl.sql.statement.WhereUpdateDeleteStatement /** * DELETE operation builder. @@ -36,41 +37,49 @@ internal object Delete : Operation { get() = "DELETE FROM " /** - * Builds a DELETE statement with WHERE clause. + * Builds a DELETE statement with WHERE clause, which ORDER BY and LIMIT can follow. * * Generates SQL in the format: `DELETE FROM table WHERE condition` * * @param table Table to delete from * @param connection Database connection for execution + * @param container The container the statement is added to, in which a clause that follows replaces it * @param whereClause WHERE condition specifying which rows to delete - * @return Final DELETE statement ready for execution + * @param target The table, or the table with INDEXED BY or NOT INDEXED, which the rows are looked up through + * @return DELETE statement ready for execution */ - fun delete(table: Table<*>, connection: DatabaseConnection, whereClause: WhereClause): SingleStatement { - val sql = buildString { - buildBaseDeleteStatement(table) - append(whereClause.clauseStr) - } - return UpdateDeleteStatement(sql, connection, whereClause.selectCondition.parameters, table.tableName) - } + fun delete( + table: Table, + connection: DatabaseConnection, + container: StatementContainer, + whereClause: WhereClause, + target: String = table.tableName, + ): WhereUpdateDeleteStatement = + WhereUpdateDeleteStatement(parts(table, target).copy(where = whereClause.selectCondition), container, connection) /** - * Builds a DELETE statement without WHERE clause (deletes all rows). + * Builds a DELETE statement without WHERE clause (deletes all rows), which ORDER BY and LIMIT can follow. * * Generates SQL in the format: `DELETE FROM table` * * @param table Table to delete all rows from * @param connection Database connection for execution - * @return Final DELETE statement ready for execution + * @param container The container the statement is added to, in which a clause that follows replaces it + * @param target The table, or the table with INDEXED BY or NOT INDEXED, which the rows are looked up through + * @return DELETE statement ready for execution */ - fun deleteAllEntities(table: Table<*>, connection: DatabaseConnection): SingleStatement { - val sql = buildString { - buildBaseDeleteStatement(table) - } - return UpdateDeleteStatement(sql, connection, null, table.tableName) - } + fun deleteAllEntities( + table: Table, + connection: DatabaseConnection, + container: StatementContainer, + target: String = table.tableName, + ): WhereUpdateDeleteStatement = WhereUpdateDeleteStatement(parts(table, target), container, connection) - private fun StringBuilder.buildBaseDeleteStatement(table: Table<*>) { - append(sqlStr) - append(table.tableName) - } + private fun parts(table: Table<*>, target: String) = UpdateDeleteParts( + statement = sqlStr, + table = table, + target = target, + assignments = "", + assignmentParameters = null, + ) } \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/FullNameCache.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/FullNameCache.kt index 5f5f4f64..26847ae2 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/FullNameCache.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/FullNameCache.kt @@ -16,7 +16,8 @@ package com.ctrip.sqllin.dsl.sql.operation -import com.ctrip.sqllin.dsl.sql.Table +import kotlinx.serialization.ExperimentalSerializationApi +import kotlinx.serialization.descriptors.PrimitiveKind import kotlinx.serialization.descriptors.SerialDescriptor import kotlinx.serialization.descriptors.SerialKind @@ -27,7 +28,7 @@ import kotlinx.serialization.descriptors.SerialKind * These names are matched against kotlinx.serialization descriptor serial names to determine * the appropriate SQLite column type. * - * Used by [Create.buildSQL] to map Kotlin types to SQLite types: + * Used by [columnTypeOf] to map Kotlin types to SQLite types: * - Integer types → TINYINT, SMALLINT, INT, BIGINT, INTEGER * - Floating-point types → FLOAT, DOUBLE * - Boolean → BOOLEAN @@ -59,12 +60,10 @@ internal object FullNameCache { val BYTE_ARRAY = ByteArray::class.qualifiedName!! /** - * Maps a Kotlin type's serial descriptor to its corresponding SQLite column type declaration. - * - * This function converts kotlinx.serialization descriptors into appropriate SQLite column type - * strings for use in DDL statements like CREATE TABLE and ALTER TABLE ADD COLUMN. It analyzes - * both the serial name (fully qualified type name) and the descriptor kind (e.g., ENUM) to - * determine the correct SQLite type. + * Returns the SQLite type of the column of a property, which [descriptor], the descriptor of its serializer, + * describes, without NULL: the type of SQLlin's default mapping of a Kotlin type, as `INT` for an `Int` or an enum, + * stored as its ordinal; or, for a serializer that converts the values of another type, the type of the value it + * encodes, as `TEXT` for the built-in serializer of `Uuid`, or the type of the value of a value class. * * Type mapping rules: * - **Byte/UByte** → TINYINT @@ -80,45 +79,38 @@ internal object FullNameCache { * - **String** → TEXT * - **ByteArray** → BLOB * - * Special handling for Long type: - * - Returns " INTEGER" when the column is the table's primary key (required by SQLite for auto-increment) - * - Returns " BIGINT" for non-primary key Long columns - * - * Example usage: - * ```kotlin - * val descriptor = User.serializer().descriptor.getElementDescriptor(0) - * val sqlType = getSerialNameBySerialName(descriptor, "username", userTable) - * // Returns: " TEXT" - * - * val pkDescriptor = User.serializer().descriptor.getElementDescriptor(1) - * val pkType = getSerialNameBySerialName(pkDescriptor, "id", userTable) - * // Returns: " INTEGER" (if "id" is the primary key) or " BIGINT" (if not) - * - * val enumDescriptor = User.serializer().descriptor.getElementDescriptor(2) - * val enumType = getSerialNameBySerialName(enumDescriptor, "status", userTable) - * // Returns: " INT" (enum stored as ordinal) - * ``` + * A serializer of another type stores the values of the kind of its descriptor, as a `PrimitiveKind.LONG`, which is + * BIGINT, as it isn't a `Long` property that can be the rowid. A value class stores the value it holds. * - * @param descriptor The kotlinx.serialization serial descriptor for the type - * @param elementName The property/column name being processed - * @param table The table definition, used to check primary key information - * @return A string starting with a space followed by the SQLite type name (e.g., " TEXT", " INTEGER", " INT") - * @throws IllegalStateException if the type is not supported by SQLlin + * @param descriptor The descriptor of the serializer of the property, nullable or not + * @param isPrimaryKey Whether the property is the table's primary key, which makes a `Long` the rowid + * @return The SQLite type, as `TEXT`, or null if the serializer encodes a structure, which no column holds */ - fun getTypeNameBySerialName(descriptor: SerialDescriptor, elementName: String, table: Table<*>): String = with(descriptor.serialName) { - when { - startsWith(BYTE) || startsWith(UBYTE) -> " TINYINT" - startsWith(SHORT) || startsWith(USHORT) -> " SMALLINT" - startsWith(INT) || startsWith(UINT) || descriptor.kind == SerialKind.ENUM -> " INT" - startsWith(LONG) -> if (elementName == table.primaryKeyInfo?.primaryKeyName) " INTEGER" else " BIGINT" - startsWith(ULONG) -> " BIGINT" - startsWith(FLOAT) -> " FLOAT" - startsWith(DOUBLE) -> " DOUBLE" - startsWith(BOOLEAN) -> " BOOLEAN" - startsWith(CHAR) -> " CHAR(1)" - startsWith(STRING) -> " TEXT" - startsWith(BYTE_ARRAY) -> " BLOB" - else -> throw IllegalStateException("Hasn't support the type '$this' yet") + @OptIn(ExperimentalSerializationApi::class) + fun columnTypeOf(descriptor: SerialDescriptor, isPrimaryKey: Boolean): String? = when (descriptor.serialName.removeSuffix("?")) { + BYTE, UBYTE -> "TINYINT" + SHORT, USHORT -> "SMALLINT" + INT, UINT -> "INT" + LONG -> if (isPrimaryKey) "INTEGER" else "BIGINT" + ULONG -> "BIGINT" + FLOAT -> "FLOAT" + DOUBLE -> "DOUBLE" + BOOLEAN -> "BOOLEAN" + CHAR -> "CHAR(1)" + STRING -> "TEXT" + BYTE_ARRAY -> "BLOB" + else -> when (descriptor.kind) { + SerialKind.ENUM -> "INT" + PrimitiveKind.BYTE -> "TINYINT" + PrimitiveKind.SHORT -> "SMALLINT" + PrimitiveKind.INT -> "INT" + PrimitiveKind.LONG -> "BIGINT" + PrimitiveKind.FLOAT -> "FLOAT" + PrimitiveKind.DOUBLE -> "DOUBLE" + PrimitiveKind.BOOLEAN -> "BOOLEAN" + PrimitiveKind.CHAR -> "CHAR(1)" + PrimitiveKind.STRING -> "TEXT" + else -> if (descriptor.isInline) columnTypeOf(descriptor.getElementDescriptor(0), isPrimaryKey = false) else null } } } \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Insert.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Insert.kt index cc3195c6..98bf451a 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Insert.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Insert.kt @@ -64,24 +64,19 @@ internal object Insert : Operation { return InsertStatement(sql, connection, parameters, table.tableName) } - fun insertOrReplace(table: Table, connection: DatabaseConnection, entities: Iterable): SingleStatement { - val parameters = ArrayList() - val sql = buildString { - append("INSERT OR REPLACE INTO ") - append(table.tableName) - append(' ') - encodeEntities2InsertValues(table, this, entities, parameters, isInsertWithId = true) - } - return InsertStatement(sql, connection, parameters, table.tableName) - } - - fun insertOrIgnore(table: Table, connection: DatabaseConnection, entities: Iterable): SingleStatement { + /** + * Builds an INSERT statement of [entities] with a conflict resolution, which [insert] starts with, as + * `INSERT OR IGNORE INTO `. + * + * The primary key is written even when the database would assign it, as a conflict on it could never be seen + * otherwise; a null key still lets the database assign it. + */ + fun insertOr(insert: String, table: Table, connection: DatabaseConnection, entities: Iterable): SingleStatement { val parameters = ArrayList() val sql = buildString { - append("INSERT OR IGNORE INTO ") + append(insert) append(table.tableName) append(' ') - // Write the primary key even when the database would assign it, or a conflict on it could never be seen encodeEntities2InsertValues(table, this, entities, parameters, isInsertWithId = true) } return InsertStatement(sql, connection, parameters, table.tableName) diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/PRAGMA.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/PRAGMA.kt index b31b5719..8ee1db9f 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/PRAGMA.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/PRAGMA.kt @@ -16,7 +16,24 @@ package com.ctrip.sqllin.dsl.sql.operation +import com.ctrip.sqllin.driver.CommonCursor import com.ctrip.sqllin.driver.DatabaseConnection +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import com.ctrip.sqllin.dsl.sql.compiler.sqlLiteral +import com.ctrip.sqllin.dsl.sql.pragma.AutoVacuum +import com.ctrip.sqllin.dsl.sql.pragma.CheckpointMode +import com.ctrip.sqllin.dsl.sql.pragma.CheckpointResult +import com.ctrip.sqllin.dsl.sql.pragma.ColumnInfo +import com.ctrip.sqllin.dsl.sql.pragma.ColumnKind +import com.ctrip.sqllin.dsl.sql.pragma.DatabaseInfo +import com.ctrip.sqllin.dsl.sql.pragma.ForeignKeyInfo +import com.ctrip.sqllin.dsl.sql.pragma.ForeignKeyViolation +import com.ctrip.sqllin.dsl.sql.pragma.FunctionInfo +import com.ctrip.sqllin.dsl.sql.pragma.IndexColumn +import com.ctrip.sqllin.dsl.sql.pragma.IndexInfo +import com.ctrip.sqllin.dsl.sql.pragma.IndexOrigin +import com.ctrip.sqllin.dsl.sql.pragma.RelationInfo +import com.ctrip.sqllin.dsl.sql.statement.PragmaStatement import com.ctrip.sqllin.dsl.sql.statement.SingleStatement import com.ctrip.sqllin.dsl.sql.statement.TableStructureStatement @@ -28,7 +45,24 @@ import com.ctrip.sqllin.dsl.sql.statement.TableStructureStatement * that query or modify database operation parameters. * * ### Available PRAGMAs - * - **foreign_keys**: Enable or disable foreign key constraint enforcement + * - **foreign_keys**: Enable or disable foreign key constraint enforcement, or read whether it is enabled + * - **optimize**: Gather the statistics that would help the query planner + * - **integrity_check**, **quick_check**, **foreign_key_check**: Check the database, or a table + * - **table_info**, **table_xinfo**, **table_list**, **index_list**, **index_xinfo**, **foreign_key_list**: Read the + * schema + * - **compile_options**, **collation_list**, **database_list**, **function_list**, **module_list**, **pragma_list**: + * Read what the SQLite and the connection have + * - **wal_checkpoint**, **page_count**, **freelist_count**, **page_size**, **application_id**, **auto_vacuum**: + * Checkpoint the WAL, read the file's size, and read and set what its header holds + * - **defer_foreign_keys**, **recursive_triggers**, **legacy_alter_table**, **ignore_check_constraints**: Set how + * statements run + * + * The names a PRAGMA takes are written as string literals, which SQLite accepts there, so that any name is quoted. + * The columns of the rows a PRAGMA returns are looked up by name once there is a row, as an older SQLite names no + * columns for a PRAGMA that returns no rows, as `table_info` of a table that doesn't exist. An older SQLite ignores a + * PRAGMA it doesn't have, rather than failing, which then returns no columns: a PRAGMA that only newer versions have + * checks that its rows have their first column, so that it fails rather than returns nothing, without asking the + * SQLite for its version. * * ### Usage * This object is used internally by [DatabaseScope][com.ctrip.sqllin.dsl.DatabaseScope] @@ -37,6 +71,7 @@ import com.ctrip.sqllin.dsl.sql.statement.TableStructureStatement * @author Yuang Qiao * @see com.ctrip.sqllin.dsl.DatabaseScope.PRAGMA_FOREIGN_KEYS */ +@OptIn(ExperimentalDSLDatabaseAPI::class) internal object PRAGMA : Operation { override val sqlStr: String @@ -93,4 +128,265 @@ internal object PRAGMA : Operation { * `PRAGMA optimize`, which runs ANALYZE on the tables whose statistics would help the query planner, if any. */ fun optimize(connection: DatabaseConnection): SingleStatement = TableStructureStatement("${sqlStr}optimize", connection) + + /** + * `PRAGMA foreign_keys`, whether this connection enforces foreign keys. + */ + fun isForeignKeysEnabled(connection: DatabaseConnection): PragmaStatement = + single("foreign_keys", connection) { it.getLong(0) != 0L } + + /** + * `PRAGMA integrity_check(N)` or `PRAGMA quick_check(N)`: the problems found, up to [maxErrors], or none, rather + * than the single row `ok` the PRAGMA returns when it finds none. + */ + fun check(pragma: String, maxErrors: Int, connection: DatabaseConnection): PragmaStatement> = + statement("$pragma($maxErrors)", connection, read = ::problems) + + /** + * `PRAGMA integrity_check(table)` or `PRAGMA quick_check(table)`, of the table named [table] and its indexes, + * which SQLite 3.33.0 has; an older one takes the name for a number of errors, which it ignores, so it checks the + * whole database. + */ + fun check(pragma: String, table: String, connection: DatabaseConnection): PragmaStatement> = + statement("$pragma(${sqlLiteral(table)})", connection, read = ::problems) + + private fun problems(cursor: CommonCursor): List { + val messages = buildList { cursor.forEachRow { add(cursor.getString(0).orEmpty()) } } + return if (messages == listOf("ok")) emptyList() else messages + } + + /** + * `PRAGMA foreign_key_check`, of all tables, or of the table named [table]. + */ + fun foreignKeyCheck(table: String?, connection: DatabaseConnection): PragmaStatement> = + statement(if (table == null) "foreign_key_check" else "foreign_key_check(${sqlLiteral(table)})", connection) { cursor -> + cursor.mapRows { ForeignKeyViolation(string("table")!!, longOrNull("rowid"), string("parent")!!, int("fkid")) } + } + + /** + * `PRAGMA table_info`, the columns of the table or view named [relation]. + */ + fun tableInfo(relation: String, connection: DatabaseConnection): PragmaStatement> = + statement("table_info(${sqlLiteral(relation)})", connection) { cursor -> + cursor.mapRows { + ColumnInfo(int("cid"), string("name")!!, string("type").orEmpty(), boolean("notnull"), string("dflt_value"), int("pk")) + } + } + + /** + * `PRAGMA table_xinfo`, the columns of the table or view named [relation], its hidden and generated ones included, + * which SQLite 3.26.0 has. + */ + fun tableXinfo(relation: String, connection: DatabaseConnection): PragmaStatement> = + newer("table_xinfo(${sqlLiteral(relation)})", "cid", "SQLite 3.26.0, which Android has from API 30 on", connection) { cursor -> + cursor.mapRows { + ColumnInfo( + int("cid"), string("name")!!, string("type").orEmpty(), boolean("notnull"), string("dflt_value"), int("pk"), + columnKind(int("hidden")), + ) + } + } + + /** + * `PRAGMA table_list`, the tables and views of all databases of the connection, which SQLite 3.37.0 has. + */ + fun tableList(connection: DatabaseConnection): PragmaStatement> = + newer("table_list", "schema", "SQLite 3.37.0, which Android has from API 34 on", connection) { cursor -> + cursor.mapRows { + RelationInfo(string("schema")!!, string("name")!!, string("type")!!, int("ncol"), boolean("wr"), boolean("strict")) + } + } + + /** + * `PRAGMA index_list`, the indexes of the table named [table]. + */ + fun indexList(table: String, connection: DatabaseConnection): PragmaStatement> = + statement("index_list(${sqlLiteral(table)})", connection) { cursor -> + cursor.mapRows { IndexInfo(string("name")!!, boolean("unique"), indexOrigin(string("origin")), boolean("partial")) } + } + + /** + * `PRAGMA index_xinfo`, the columns of the index named [index], those it is keyed by and those it holds besides. + */ + fun indexXinfo(index: String, connection: DatabaseConnection): PragmaStatement> = + statement("index_xinfo(${sqlLiteral(index)})", connection) { cursor -> + cursor.mapRows { IndexColumn(int("cid"), string("name"), boolean("desc"), string("coll"), boolean("key")) } + } + + /** + * `PRAGMA foreign_key_list`, the columns of the foreign keys of the table named [table]. + */ + fun foreignKeyList(table: String, connection: DatabaseConnection): PragmaStatement> = + statement("foreign_key_list(${sqlLiteral(table)})", connection) { cursor -> + cursor.mapRows { + ForeignKeyInfo( + int("id"), int("seq"), string("table")!!, string("from")!!, string("to"), + string("on_update")!!, string("on_delete")!!, string("match")!!, + ) + } + } + + /** + * `PRAGMA wal_checkpoint(mode)`, which returns a row, so that it runs as a query. + */ + fun walCheckpoint(mode: CheckpointMode, connection: DatabaseConnection): PragmaStatement = + statement("wal_checkpoint(${mode.name})", connection) { cursor -> + cursor.mapRows { CheckpointResult(boolean("busy"), int("log"), int("checkpointed")) }.single() + } + + /** + * `PRAGMA compile_options`, `PRAGMA collation_list`, `PRAGMA module_list` or `PRAGMA pragma_list`: the values of + * [column], one in each row. A SQLite can be built without compile_options, as Android's is, and the others, which + * SQLite 3.30.0 has in every build, only [requirement] has. + */ + fun names(pragma: String, column: String, requirement: String?, connection: DatabaseConnection): PragmaStatement> = + newer(pragma, column, requirement, connection) { cursor -> cursor.mapRows { string(column)!! } } + + /** + * `PRAGMA database_list`, the databases of the connection. + */ + fun databaseList(connection: DatabaseConnection): PragmaStatement> = + newer("database_list", "name", null, connection) { cursor -> + cursor.mapRows { DatabaseInfo(string("name")!!, string("file").orEmpty()) } + } + + /** + * `PRAGMA function_list`, the SQL functions of the connection, which SQLite 3.30.0 has in every build. + */ + fun functionList(connection: DatabaseConnection): PragmaStatement> = + newer("function_list", "name", "SQLite 3.30.0, which Android has from API 31 on", connection) { cursor -> + cursor.mapRows { + FunctionInfo(string("name")!!, boolean("builtin"), string("type")!!, string("enc")!!, int("narg"), longOrNull("flags") ?: 0L) + } + } + + /** + * `PRAGMA application_id`, the number at offset 68 of the header of the database file. + */ + fun applicationId(connection: DatabaseConnection): PragmaStatement = single("application_id", connection) { it.getInt(0) } + + /** + * `PRAGMA application_id = id`, which returns no row. + */ + fun applicationId(id: Int, connection: DatabaseConnection): PragmaStatement = + PragmaStatement("${sqlStr}application_id=$id", connection, null) + + /** + * `PRAGMA auto_vacuum`, as the header of the database file holds it, which SQLite takes from what the connection + * last read of the header, so that it is read in a transaction of its own unless [inTransaction]. + */ + fun autoVacuum(inTransaction: Boolean, connection: DatabaseConnection): PragmaStatement = + single("auto_vacuum", connection, inOwnTransaction = !inTransaction) { cursor -> + when (val mode = cursor.getInt(0)) { + 0 -> AutoVacuum.NONE + 1 -> AutoVacuum.FULL + 2 -> AutoVacuum.INCREMENTAL + else -> throw IllegalStateException("Unknown auto_vacuum: $mode") + } + } + + /** + * `PRAGMA auto_vacuum = mode`, which returns no row. + */ + fun autoVacuum(mode: AutoVacuum, connection: DatabaseConnection): PragmaStatement = + PragmaStatement("${sqlStr}auto_vacuum=${mode.name}", connection, null) + + /** + * `PRAGMA page_count`, `PRAGMA freelist_count` or `PRAGMA page_size`. SQLite takes page_size from what the + * connection last read of the header of the database file, so that it is read in a transaction of its own unless + * [inTransaction]. + */ + fun size(pragma: String, inTransaction: Boolean, connection: DatabaseConnection): PragmaStatement = + single(pragma, connection, inOwnTransaction = pragma == "page_size" && !inTransaction) { it.getLong(0) } + + /** + * `PRAGMA defer_foreign_keys`, `PRAGMA recursive_triggers`, `PRAGMA legacy_alter_table` or + * `PRAGMA ignore_check_constraints` set to [flag], which returns no row. Android's driver runs the last three on + * every connection of the database, as SQLite compiles them into the statements of each. + */ + fun set(pragma: String, flag: Boolean, connection: DatabaseConnection): PragmaStatement = + PragmaStatement("$sqlStr$pragma=${if (flag) 1 else 0}", connection, null) + + private fun statement( + pragma: String, + connection: DatabaseConnection, + inOwnTransaction: Boolean = false, + read: (CommonCursor) -> R, + ): PragmaStatement = PragmaStatement("$sqlStr$pragma", connection, read, inOwnTransaction) + + /** + * A PRAGMA that returns a single value, which [read] reads from its row. + */ + private fun single( + pragma: String, + connection: DatabaseConnection, + inOwnTransaction: Boolean = false, + read: (CommonCursor) -> R, + ): PragmaStatement = + statement(pragma, connection, inOwnTransaction) { cursor -> + check(cursor.next()) { "PRAGMA $pragma returned no row." } + read(cursor) + } + + /** + * A PRAGMA that only newer versions of SQLite have, or that a SQLite can be built without, which [requirement] + * describes, if it is a version: one that doesn't have it ignores it, rather than failing, so that it returns no + * columns, which the first of its columns, [column], checks, rather than the version of SQLite. + */ + private fun newer( + pragma: String, + column: String, + requirement: String?, + connection: DatabaseConnection, + read: (CommonCursor) -> R, + ): PragmaStatement = statement(pragma, connection) { cursor -> + // Every driver throws for a column that the rows don't have + val hasColumn = runCatching { cursor.getColumnIndex(column) }.getOrNull()?.let { it >= 0 } ?: false + check(hasColumn) { + val name = pragma.substringBefore('(') + if (requirement == null) "This SQLite doesn't have PRAGMA $name." else "This SQLite doesn't have PRAGMA $name, which needs $requirement." + } + read(cursor) + } + + private fun columnKind(hidden: Int): ColumnKind = when (hidden) { + 0 -> ColumnKind.ORDINARY + 1 -> ColumnKind.HIDDEN + 2 -> ColumnKind.VIRTUAL_GENERATED + 3 -> ColumnKind.STORED_GENERATED + else -> throw IllegalStateException("Unknown kind of column: $hidden") + } + + private fun indexOrigin(code: String?): IndexOrigin = when (code) { + "c" -> IndexOrigin.CREATE_INDEX + "u" -> IndexOrigin.UNIQUE + "pk" -> IndexOrigin.PRIMARY_KEY + else -> throw IllegalStateException("Unknown origin of an index: $code") + } + + /** + * Reads each row with [read], which looks the columns up by name once there is a row. + */ + private fun CommonCursor.mapRows(read: PragmaRow.() -> T): List { + val row = PragmaRow(this) + return buildList { forEachRow { add(row.read()) } } + } + + /** + * A row of a PRAGMA, whose columns it looks up by name the first time they are read. + */ + private class PragmaRow(private val cursor: CommonCursor) { + + private val columns = HashMap() + + private fun column(name: String): Int = columns.getOrPut(name) { cursor.getColumnIndex(name) } + + fun string(name: String): String? = cursor.getString(column(name)) + + fun int(name: String): Int = cursor.getInt(column(name)) + + fun longOrNull(name: String): Long? = column(name).let { if (cursor.isNull(it)) null else cursor.getLong(it) } + + fun boolean(name: String): Boolean = cursor.getLong(column(name)) != 0L + } } diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Select.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Select.kt index 3cca52e5..c38c56ab 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Select.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Select.kt @@ -113,49 +113,6 @@ internal object Select : Operation { return GroupBySelectStatement(buildSQL(from, clause, isDistinct, deserializer), deserializer, connection, container, parametersOf(from.parameters), null, from.tables + clause.elementTables) } - /** - * Builds a SELECT statement with NATURAL JOIN clause. - * - * Natural joins automatically match columns with the same name in both tables. - * - * @return Statement that can be followed by WHERE, GROUP BY, ORDER BY, or LIMIT - */ - fun select( - table: Relation<*>, - clause: NaturalJoinClause, - isDistinct: Boolean, - deserializer: DeserializationStrategy, - connection: DatabaseConnection, - container: StatementContainer, - ) : JoinSelectStatement = - JoinSelectStatement(buildSQL(From.of(table), clause, isDistinct, deserializer), deserializer, connection, container, parametersOf(table.fromParameters, clause.parameters), null, table.readTables + clause.tables) - - /** - * Builds a SELECT statement with JOIN clause (requires ON or USING). - * - * Returns an intermediate state that must be completed with either an ON or USING clause. - * - * @return Incomplete JOIN statement requiring condition - */ - fun select( - table: Relation<*>, - clause: JoinClause, - isDistinct: Boolean, - deserializer: DeserializationStrategy, - connection: DatabaseConnection, - container: StatementContainer, - addSelectStatement: (SelectStatement) -> Unit - ) : JoinStatementWithoutCondition = - JoinStatementWithoutCondition( - buildSQL(From.of(table), clause, isDistinct, deserializer), - deserializer, - connection, - container, - parametersOf(table.fromParameters, clause.parameters), - table.readTables + clause.tables, - addSelectStatement, - ) - /** * Checks that [deserializer] can read rows of [from], when it reads them into a type other than the row type of a * single table. diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Update.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Update.kt index 263cc22b..7d64c952 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Update.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/operation/Update.kt @@ -21,6 +21,7 @@ import com.ctrip.sqllin.dsl.sql.statement.StatementContainer import com.ctrip.sqllin.dsl.sql.Table import com.ctrip.sqllin.dsl.sql.clause.SetClause import com.ctrip.sqllin.dsl.sql.clause.writtenColumns +import com.ctrip.sqllin.dsl.sql.statement.UpdateDeleteParts import com.ctrip.sqllin.dsl.sql.statement.UpdateStatementWithoutWhereClause /** @@ -48,16 +49,20 @@ internal object Update : Operation { * @param clause SET clause with column assignments * @return Statement that can either execute or be refined with WHERE */ + /** + * Builds an UPDATE statement, which [update] starts with: `UPDATE `, or one with a conflict resolution, as + * `UPDATE OR IGNORE `, of [target], the table, or the table with `INDEXED BY` or `NOT INDEXED`. + */ fun update( table: Table, connection: DatabaseConnection, container: StatementContainer, clause: SetClause, + update: String = sqlStr, + target: String = table.tableName, ): UpdateStatementWithoutWhereClause { val assignments = clause.assignments val sql = buildString { - append(sqlStr) - append(table.tableName) append(" SET ") if (assignments == null) { append(clause.finalize()) @@ -71,6 +76,13 @@ internal object Update : Operation { } } } - return UpdateStatementWithoutWhereClause(sql, container, connection, clause.parameters, table.tableName) + val parts = UpdateDeleteParts( + statement = update, + table = table, + target = target, + assignments = sql, + assignmentParameters = clause.parameters, + ) + return UpdateStatementWithoutWhereClause(parts, container, connection) } } \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/pragma/PragmaResults.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/pragma/PragmaResults.kt new file mode 100644 index 00000000..22c9bf9c --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/pragma/PragmaResults.kt @@ -0,0 +1,281 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.sql.pragma + +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI + +/** + * A column of a table or a view, a row of `PRAGMA table_info`, which `PRAGMA_TABLE_INFO(table)` returns, or of + * `PRAGMA table_xinfo`, which `PRAGMA_TABLE_XINFO(table)` returns, with the hidden and generated columns. + * + * @property index The position of the column in the table, from 0, the `cid` of the PRAGMA + * @property name The name of the column + * @property type The type the column was declared with, as `TEXT` or `INT`, or an empty string if it has none + * @property notNull Whether the column is NOT NULL + * @property defaultValue The SQL of the column's default value, as `'new'` or `0`, or null if it has none, the + * `dflt_value` of the PRAGMA + * @property primaryKeyPosition The position of the column in the primary key, from 1, or 0 if it isn't part of it, the + * `pk` of the PRAGMA + * @property kind Whether the column is an ordinary one, a hidden one or a generated one, the `hidden` of + * `PRAGMA table_xinfo`: `PRAGMA table_info` only lists ordinary columns + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public data class ColumnInfo( + val index: Int, + val name: String, + val type: String, + val notNull: Boolean, + val defaultValue: String?, + val primaryKeyPosition: Int, + val kind: ColumnKind = ColumnKind.ORDINARY, +) + +/** + * What kind of column a column is, the `hidden` of `PRAGMA table_xinfo`. + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public enum class ColumnKind { + /** An ordinary column, `0` */ + ORDINARY, + /** A hidden column of a virtual table, as the column of an FTS table named after the table, `1` */ + HIDDEN, + /** A generated column that is computed when it is read, `GENERATED ALWAYS AS (...) VIRTUAL`, `2` */ + VIRTUAL_GENERATED, + /** A generated column that is stored, `GENERATED ALWAYS AS (...) STORED`, `3` */ + STORED_GENERATED, +} + +/** + * A table or a view of the database, a row of `PRAGMA table_list`, which `PRAGMA_TABLE_LIST()` returns. + * + * @property schema The database the table belongs to: `main`, `temp`, or the name of an attached database + * @property name The name of the table + * @property type What the table is, in SQLite's words: `table`, `view`, `virtual` for a virtual table, as an FTS table, + * or `shadow` for a table that a virtual table keeps its data in + * @property columnCount The number of its columns, the `ncol` of the PRAGMA + * @property isWithoutRowid Whether it is a WITHOUT ROWID table, the `wr` of the PRAGMA + * @property isStrict Whether it is a STRICT table, the `strict` of the PRAGMA + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public data class RelationInfo( + val schema: String, + val name: String, + val type: String, + val columnCount: Int, + val isWithoutRowid: Boolean, + val isStrict: Boolean, +) + +/** + * A database of the connection, a row of `PRAGMA database_list`, which `PRAGMA_DATABASE_LIST()` returns. + * + * @property name The name of the database: `main`, `temp`, or the name an attached database was attached as + * @property file The path of its file, or an empty string for a database in memory, or a TEMP one, which has none + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public data class DatabaseInfo( + val name: String, + val file: String, +) + +/** + * A form of an SQL function, a row of `PRAGMA function_list`, which `PRAGMA_FUNCTION_LIST()` returns: a function that + * takes several numbers of arguments has a row for each. + * + * @property name The name of the function + * @property isBuiltin Whether SQLite has it, rather than the app, the `builtin` of the PRAGMA + * @property type What it is, in SQLite's words: `s` for a scalar function, `a` for an aggregate one, and `w` for a + * window one + * @property encoding The text encoding it takes, as `utf8`, the `enc` of the PRAGMA + * @property argumentCount The number of arguments it takes, or -1 if it takes any number, the `narg` of the PRAGMA + * @property flags The flags SQLite registered it with, as `SQLITE_DETERMINISTIC` + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public data class FunctionInfo( + val name: String, + val isBuiltin: Boolean, + val type: String, + val encoding: String, + val argumentCount: Int, + val flags: Long, +) + +/** + * Whether the database removes its unused pages, the `auto_vacuum` of the database file, which + * `PRAGMA_AUTO_VACUUM(mode)` sets. + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public enum class AutoVacuum { + /** It keeps them, until a VACUUM removes them, `0` */ + NONE, + /** It removes them at each commit, `1` */ + FULL, + /** It keeps them, until the SQL `PRAGMA incremental_vacuum` removes them, `2` */ + INCREMENTAL, +} + +/** + * An index of a table, a row of `PRAGMA index_list`, which `PRAGMA_INDEX_LIST(table)` returns. + * + * @property name The name of the index, which SQLite chooses for that of a UNIQUE or PRIMARY KEY constraint, as + * `sqlite_autoindex_person_1` + * @property isUnique Whether the index is unique + * @property origin What created the index + * @property isPartial Whether the index is a partial index, of the rows that satisfy its WHERE + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public data class IndexInfo( + val name: String, + val isUnique: Boolean, + val origin: IndexOrigin, + val isPartial: Boolean, +) + +/** + * What created an index, the `origin` of `PRAGMA index_list`. + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public enum class IndexOrigin { + /** `CREATE INDEX`, `c` */ + CREATE_INDEX, + /** A UNIQUE constraint, `u` */ + UNIQUE, + /** A PRIMARY KEY constraint, `pk` */ + PRIMARY_KEY, +} + +/** + * A column of an index, a row of `PRAGMA index_xinfo`, which `PRAGMA_INDEX_XINFO(index)` returns: a column it is keyed + * by, or one it holds besides, as the rowid of a table's row. + * + * @property columnIndex The position of the column in the table, from 0, the `cid` of the PRAGMA: -1 for the rowid, + * and -2 for an expression + * @property name The name of the column, or null for the rowid or an expression + * @property isDescending Whether the index sorts the column in descending order, the `desc` of the PRAGMA + * @property collation The collation the index compares the column with, as `BINARY` or `NOCASE`, the `coll` of the + * PRAGMA + * @property isKey Whether the index is keyed by the column, rather than holding it besides, the `key` of the PRAGMA + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public data class IndexColumn( + val columnIndex: Int, + val name: String?, + val isDescending: Boolean, + val collation: String?, + val isKey: Boolean, +) + +/** + * A column of a foreign key of a table, a row of `PRAGMA foreign_key_list`, which `PRAGMA_FOREIGN_KEY_LIST(table)` + * returns. A foreign key of several columns has a row for each, with the same [id]. + * + * @property id The foreign key's number in the table, from 0, which the [ForeignKeyViolation.foreignKeyId] of a + * violation of it is + * @property position The position of the column in the foreign key, from 0, the `seq` of the PRAGMA + * @property parentTable The table the foreign key references, the `table` of the PRAGMA + * @property column The column of the table, the `from` of the PRAGMA + * @property parentColumn The column it references, or null if the foreign key names no columns, so that it references + * the parent table's primary key, the `to` of the PRAGMA + * @property onUpdate The action of ON UPDATE, as `NO ACTION` or `CASCADE` + * @property onDelete The action of ON DELETE, as `NO ACTION` or `CASCADE` + * @property match The MATCH clause, which SQLite parses but ignores, `NONE` if it has none + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public data class ForeignKeyInfo( + val id: Int, + val position: Int, + val parentTable: String, + val column: String, + val parentColumn: String?, + val onUpdate: String, + val onDelete: String, + val match: String, +) + +/** + * A row that violates a foreign key, a row of `PRAGMA foreign_key_check`, which `PRAGMA_FOREIGN_KEY_CHECK()` returns. + * + * @property table The table of the row + * @property rowid The rowid of the row, or null if the table is a WITHOUT ROWID one + * @property parentTable The table the foreign key references, the `parent` of the PRAGMA + * @property foreignKeyId The number of the foreign key in the table, the [ForeignKeyInfo.id] of its columns, the + * `fkid` of the PRAGMA + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public data class ForeignKeyViolation( + val table: String, + val rowid: Long?, + val parentTable: String, + val foreignKeyId: Int, +) + +/** + * How `PRAGMA_WAL_CHECKPOINT(mode)` checkpoints the WAL, copying its pages into the database file. + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public enum class CheckpointMode { + /** Copies as many pages as it can without waiting for readers or writers, as SQLite's automatic checkpoints do. */ + PASSIVE, + /** Waits until no connection writes, and until every reader reads the latest pages, then copies all of them. */ + FULL, + /** As FULL, then waits until no reader reads the WAL, so that the next writer starts it over. */ + RESTART, + /** As RESTART, then truncates the WAL file to zero bytes. */ + TRUNCATE, +} + +/** + * The result of a checkpoint, the row of `PRAGMA wal_checkpoint`, which `PRAGMA_WAL_CHECKPOINT(mode)` returns. + * + * @property isBusy Whether the checkpoint couldn't finish, as another connection read or wrote, which only a FULL, + * RESTART or TRUNCATE checkpoint tells, the `busy` of the PRAGMA + * @property walPages The number of pages in the WAL, or -1 if the database isn't in WAL mode, the `log` of the PRAGMA + * @property checkpointedPages The number of them copied into the database file, or -1 if the database isn't in WAL + * mode, the `checkpointed` of the PRAGMA + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public data class CheckpointResult( + val isBusy: Boolean, + val walPages: Int, + val checkpointedPages: Int, +) diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/Changes.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/Changes.kt index 3bb0e467..f8a7c3f5 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/Changes.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/Changes.kt @@ -16,6 +16,8 @@ package com.ctrip.sqllin.dsl.sql.statement +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI + /** * What the statements of a scope may change when they run, from least to most. * @@ -23,7 +25,7 @@ package com.ctrip.sqllin.dsl.sql.statement */ internal enum class Changes { - /** Nothing: the statements only read. */ + /** Nothing: the statements only read, count the rows of a query, plan one, or run a PRAGMA of those that DatabaseScope builds as [PragmaStatement]. */ NONE, /** The rows of tables: INSERT, UPDATE or DELETE. */ @@ -34,20 +36,26 @@ internal enum class Changes { companion object { + @OptIn(ExperimentalDSLDatabaseAPI::class) fun of(statement: SingleStatement): Changes = when (statement) { - is SelectStatement<*>, is RaiseStatement -> NONE + is SelectStatement<*>, is QueryPlanStatement, is PragmaStatement<*>, is RaiseStatement, is RowCountStatement -> NONE is TableStructureStatement -> SCHEMA - is InsertStatement, is UpdateDeleteStatement, is UpdateStatementWithoutWhereClause<*> -> ROWS + is InsertStatement, is UpdateDeleteStatement, is UpdateStatementWithoutWhereClause<*>, is WhereUpdateDeleteStatement<*>, + is OrderByUpdateDeleteStatement<*>, is LimitUpdateDeleteStatement<*> -> ROWS } /** * The table [statement] writes rows to, or null if it writes none. */ + @OptIn(ExperimentalDSLDatabaseAPI::class) fun writtenTable(statement: SingleStatement): String? = when (statement) { is InsertStatement -> statement.table is UpdateDeleteStatement -> statement.table is UpdateStatementWithoutWhereClause<*> -> statement.table - is SelectStatement<*>, is TableStructureStatement, is RaiseStatement -> null + is WhereUpdateDeleteStatement<*> -> statement.table + is OrderByUpdateDeleteStatement<*> -> statement.table + is LimitUpdateDeleteStatement<*> -> statement.table + is SelectStatement<*>, is QueryPlanStatement, is PragmaStatement<*>, is TableStructureStatement, is RaiseStatement, is RowCountStatement -> null } } } diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/DatabaseExecuteEngine.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/DatabaseExecuteEngine.kt index 373b51ef..25e14e0e 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/DatabaseExecuteEngine.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/DatabaseExecuteEngine.kt @@ -33,18 +33,9 @@ internal class DatabaseExecuteEngine( private val statementList = ArrayDeque() - override infix fun changeLastStatement(statement: SingleStatement) { - if (statementList.lastOrNull() is UpdateStatementWithoutWhereClause<*> - || statementList.lastOrNull() is SelectStatement<*>) { - statementList.removeLast() - statementList.add(statement) - } else - throw IllegalStateException("Current statement can't append clause.") - } - override fun replaceStatement(statement: SingleStatement, newStatement: SingleStatement) { val index = statementList.indexOf(statement) - check(index >= 0) { "The statement to replace isn't one of the scope's." } + check(index >= 0) { "The statement isn't one of the scope's: a clause was already appended to it, which replaced it, or it became part of another statement, as a subquery does." } statementList[index] = newStatement } @@ -68,6 +59,19 @@ internal class DatabaseExecuteEngine( if (it is TransactionStatementsGroup) it.writtenTables else Changes.writtenTable(it as SingleStatement)?.let(::setOf).orEmpty() } + /** + * The tables and views the SELECTs of the scope read, their subqueries' included, which a token of their versions + * covers. + */ + val readTables: Set + get() = statementList.flatMapTo(LinkedHashSet()) { + when (it) { + is TransactionStatementsGroup -> it.readTables + is SelectStatement<*> -> it.tables + else -> emptySet() + } + } + override infix fun removeStatement(statement: SingleStatement) { statementList.remove(statement) } @@ -77,9 +81,8 @@ internal class DatabaseExecuteEngine( // failing one runs nothing. statementList.forEach { when (it) { - is SelectStatement<*> -> it.checkComplete() + is SingleStatement -> it.checkComplete() is TransactionStatementsGroup -> it.checkComplete() - else -> Unit } } statementList.forEach { diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/JoinStatementWithoutCondition.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/JoinStatementWithoutCondition.kt deleted file mode 100644 index 9c8ffd0e..00000000 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/JoinStatementWithoutCondition.kt +++ /dev/null @@ -1,95 +0,0 @@ -/* - * Copyright (C) 2022 Ctrip.com. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package com.ctrip.sqllin.dsl.sql.statement - -import com.ctrip.sqllin.driver.DatabaseConnection -import com.ctrip.sqllin.dsl.sql.clause.ClauseElement -import com.ctrip.sqllin.dsl.sql.clause.SelectCondition -import com.ctrip.sqllin.dsl.sql.operation.parametersOf -import kotlinx.serialization.DeserializationStrategy - -/** - * Intermediate JOIN statement requiring an ON or USING condition. - * - * Represents a JOIN operation that has been initiated but not yet completed. In SQL, a JOIN - * must specify how tables relate through either: - * - USING clause: Lists common column names to join on - * - ON clause: Specifies a join condition expression - * - * This class enforces the requirement at compile time by not extending [SelectStatement]. - * It converts to [JoinSelectStatement] only after a condition is added. - * - * @param R The result entity type after JOIN - * - * @author Yuang Qiao - */ -public class JoinStatementWithoutCondition internal constructor( - private val sqlStr: String, - private val deserializer: DeserializationStrategy, - private val connection: DatabaseConnection, - private val container: StatementContainer, - private val parameters: MutableList?, - private val tables: Set, - private val addSelectStatement: (SelectStatement) -> Unit -) { - /** - * Completes the JOIN by adding a USING clause. - * - * Generates SQL in the format: `JOIN table USING (column1, column2, ...)`. - * The USING clause specifies columns that exist in both tables with the same name. - * - * @param clauseElements Column elements to join on (must not be empty) - * @return Completed JOIN statement that can accept further clauses - */ - internal infix fun convertToJoinSelectStatement(clauseElements: Iterable>): JoinSelectStatement { - val iterator = clauseElements.iterator() - require(iterator.hasNext()) { "Param 'clauseElements' must not be empty!!!" } - val sql = buildString { - append(sqlStr) - append(" USING (") - append(iterator.next().valueName) - while (iterator.hasNext()) { - append(',') - append(iterator.next().valueName) - } - append(')') - } - val joinStatement = JoinSelectStatement(sql, deserializer, connection, container, parameters, null, tables) - addSelectStatement(joinStatement) - return joinStatement - } - - /** - * Completes the JOIN by adding an ON clause. - * - * Generates SQL in the format: `JOIN table ON condition`. - * The ON clause specifies an arbitrary boolean expression for joining tables. - * - * @param condition Join condition (e.g., table1.id = table2.foreign_id) - * @return Completed JOIN statement that can accept further clauses - */ - internal infix fun convertToJoinSelectStatement(condition: SelectCondition): JoinSelectStatement { - val sql = buildString { - append(sqlStr) - append(" ON ") - append(condition.conditionSQL) - } - val joinStatement = JoinSelectStatement(sql, deserializer, connection, container, parametersOf(parameters, condition.parameters), null, tables + condition.tables) - addSelectStatement(joinStatement) - return joinStatement - } -} \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/OtherStatement.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/OtherStatement.kt index b671abd2..f99aa10f 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/OtherStatement.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/OtherStatement.kt @@ -17,13 +17,105 @@ package com.ctrip.sqllin.dsl.sql.statement import com.ctrip.sqllin.driver.DatabaseConnection +import com.ctrip.sqllin.dsl.sql.Table +import com.ctrip.sqllin.dsl.sql.clause.CompleteOrderByClause +import com.ctrip.sqllin.dsl.sql.clause.SelectCondition +import com.ctrip.sqllin.dsl.sql.clause.WhereClause +import com.ctrip.sqllin.dsl.sql.operation.parametersOf + +/** + * The parts of an UPDATE or DELETE, from which it is written with the WHERE, ORDER BY, LIMIT and OFFSET it has. + * + * SQLite only takes ORDER BY and LIMIT in an UPDATE or DELETE when it is built with `SQLITE_ENABLE_UPDATE_DELETE_LIMIT`, + * which Android's isn't, nor the libraries SQLlin links on Linux and Windows, and then turns them into a subquery of the + * rowids of the rows they select, as its `sqlite3LimitWhere()` does. So SQLlin writes that subquery itself, which every + * SQLite runs, as in + * `DELETE FROM person WHERE rowid IN (SELECT rowid FROM person WHERE person.age, + val target: String, + val assignments: String, + val assignmentParameters: List?, + val where: SelectCondition? = null, + val orderBy: CompleteOrderByClause<*>? = null, + val limit: Int? = null, + val offset: Int? = null, +) { + + val tableName: String + get() = table.tableName + + val sql: String = buildString { + append(statement) + if (limit == null) { + append(target) + append(assignments) + appendSelection() + } else { + val rowId = rowIdName() + append(table.tableName) + append(assignments) + append(" WHERE ") + append(rowId) + append(" IN (SELECT ") + append(rowId) + append(" FROM ") + append(target) + appendSelection() + append(" LIMIT ") + append(limit) + offset?.let { + append(" OFFSET ") + append(it) + } + append(')') + } + } + + /** + * The parameters of the SET and of the WHERE, in the order of the SQL, in a new list, so that each statement that a + * clause completes has its own. + */ + val parameters: MutableList? + get() = parametersOf(assignmentParameters, where?.parameters) + + private fun StringBuilder.appendSelection() { + where?.let { append(WhereClause(it).clauseStr) } + orderBy?.let { append(it.clauseStr) } + } + + /** + * The name the table's rowid can be read by: `rowid`, unless a column has that name, which then means the column, + * and otherwise `_rowid_` or `oid`, which SQLite names it by too. + */ + private fun rowIdName(): String { + val descriptor = table.kSerializer().descriptor + val columns = (0 ..< descriptor.elementsCount).mapTo(HashSet()) { descriptor.getElementName(it).lowercase() } + return ROW_ID_NAMES.firstOrNull { it !in columns } ?: throw IllegalArgumentException( + "Table '${table.tableName}' has columns named rowid, _rowid_ and oid, so its rowid can't be read, which ORDER BY and LIMIT of an UPDATE or DELETE select its rows by." + ) + } + + private companion object { + val ROW_ID_NAMES = listOf("rowid", "_rowid_", "oid") + } +} /** * UPDATE statement without WHERE clause. * * Represents an UPDATE operation that can either: * - Execute immediately (updates all rows in the table) - * - Be refined by adding a WHERE clause to target specific rows + * - Be refined by adding a WHERE clause to target specific rows, or ORDER BY and LIMIT to update some of them * * This intermediate state enables the DSL to support both: * ```kotlin @@ -36,20 +128,81 @@ import com.ctrip.sqllin.driver.DatabaseConnection * @author Yuang Qiao */ public class UpdateStatementWithoutWhereClause internal constructor( - preSQLStr: String, + internal val parts: UpdateDeleteParts, internal val statementContainer: StatementContainer, internal val connection: DatabaseConnection, - override val parameters: MutableList?, - internal val table: String, -) : SingleStatement(preSQLStr) { +) : SingleStatement(parts.sql) { + override val parameters: MutableList? = parts.parameters + internal val table: String + get() = parts.tableName public override fun execute(): Unit = connection.executeUpdateDelete(sqlStr, params) } /** - * UPDATE or DELETE statement with WHERE clause applied (final form). + * An UPDATE with its WHERE, or a DELETE with its WHERE or of every row, which ORDER BY and LIMIT can follow, so that it + * only writes the first rows in an order, as in + * `PersonTable DELETE WHERE(PersonTable.age LT 18) ORDER_BY (PersonTable.age to ASC) LIMIT 10`. * - * Represents a complete UPDATE or DELETE operation ready for execution. The WHERE clause - * has already been applied, so the statement targets specific rows. + * @param T The entity type of the table + * + * @author Yuang Qiao + */ +public class WhereUpdateDeleteStatement internal constructor( + internal val parts: UpdateDeleteParts, + internal val container: StatementContainer, + internal val connection: DatabaseConnection, +) : SingleStatement(parts.sql) { + override val parameters: MutableList? = parts.parameters + internal val table: String + get() = parts.tableName + public override fun execute(): Unit = connection.executeUpdateDelete(sqlStr, params) +} + +/** + * An UPDATE or DELETE with ORDER BY, which has to be followed by LIMIT, as the order only decides which rows LIMIT + * chooses: SQLite rejects ORDER BY without LIMIT in an UPDATE or DELETE, so the scope that has it fails before any of + * its statements runs. + * + * @param T The entity type of the table + * + * @author Yuang Qiao + */ +public class OrderByUpdateDeleteStatement internal constructor( + internal val parts: UpdateDeleteParts, + internal val container: StatementContainer, + internal val connection: DatabaseConnection, +) : SingleStatement(parts.sql) { + override val parameters: MutableList? = parts.parameters + internal val table: String + get() = parts.tableName + + override fun checkComplete(): Unit = + throw IllegalArgumentException("An UPDATE or DELETE with ORDER BY needs LIMIT, which chooses the rows in that order: $sqlStr") + + public override fun execute(): Unit = checkComplete() +} + +/** + * An UPDATE or DELETE with LIMIT, which only writes as many rows as it says, the first in the order of its ORDER BY if + * it has one, and which OFFSET can follow, to skip as many before them. + * + * @param T The entity type of the table + * + * @author Yuang Qiao + */ +public class LimitUpdateDeleteStatement internal constructor( + internal val parts: UpdateDeleteParts, + internal val container: StatementContainer, + internal val connection: DatabaseConnection, +) : SingleStatement(parts.sql) { + override val parameters: MutableList? = parts.parameters + internal val table: String + get() = parts.tableName + public override fun execute(): Unit = connection.executeUpdateDelete(sqlStr, params) +} + +/** + * UPDATE or DELETE statement with all of its clauses (final form), as after OFFSET. * * @author Yuang Qiao */ diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/PragmaStatement.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/PragmaStatement.kt new file mode 100644 index 00000000..b17fdc3c --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/PragmaStatement.kt @@ -0,0 +1,80 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.sql.statement + +import com.ctrip.sqllin.driver.CommonCursor +import com.ctrip.sqllin.driver.DatabaseConnection +import com.ctrip.sqllin.driver.withTransaction +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import kotlin.concurrent.Volatile + +/** + * A PRAGMA that reads something of the database, as `PRAGMA_INTEGRITY_CHECK()` or `PRAGMA_TABLE_INFO(table)` builds, + * whose result [getResults] returns once the scope has run, or one that sets how statements run, which returns none. + * + * Whether a PRAGMA returns rows is a property of the PRAGMA, which decides how it runs, as no driver runs both kinds + * the same way: Android's framework doesn't run a statement that returns rows with `execSQL`, and sqlite-jdbc doesn't + * run one that returns none as a query. A PRAGMA that returns rows is read when it runs, and its cursor closed, as its + * result is small, rather than when [getResults] is called, as the results of a SELECT are. + * + * A PRAGMA changes no table, so a scope of PRAGMAs and SELECTs only reads, as a versioned read has to. + * + * @param read Reads the rows the PRAGMA returns, or null for a PRAGMA that returns none, which runs with `execSQL` + * @param inOwnTransaction Whether to read in a transaction of its own, for a PRAGMA whose value SQLite takes from what + * the connection last read of the database file's header, which it reads again when a transaction begins: from + * Android 13 on, a query outside a transaction may run on a connection that reads, whose header may be older than the + * connection that wrote it + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public class PragmaStatement internal constructor( + sqlStr: String, + private val connection: DatabaseConnection, + private val read: ((CommonCursor) -> R)?, + private val inOwnTransaction: Boolean = false, +) : SingleStatement(sqlStr) { + + override val parameters: MutableList? = null + + @Volatile + private var result: Any? = NOT_RUN + + override fun execute() { + result = when { + read == null -> connection.execSQL(sqlStr) + inOwnTransaction -> connection.withTransaction { it.query(sqlStr).use(read) } + else -> connection.query(sqlStr).use(read) + } + } + + /** + * Returns what the PRAGMA read. + * + * @throws IllegalStateException if the statement hasn't run yet, as within the scope that builds it + */ + @Suppress("UNCHECKED_CAST") + public fun getResults(): R { + val result = result + check(result !== NOT_RUN) { "You have to call 'execute' function before call 'getResults'!!!" } + return result as R + } + + private companion object { + val NOT_RUN = Any() + } +} diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/QueryPlan.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/QueryPlan.kt new file mode 100644 index 00000000..33d85959 --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/QueryPlan.kt @@ -0,0 +1,117 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.sql.statement + +import com.ctrip.sqllin.driver.CommonCursor +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI + +/** + * How SQLite runs a query, as `EXPLAIN QUERY PLAN` tells, which `EXPLAIN_QUERY_PLAN(select)` returns: the steps of + * its plan, such as the scan of a table, the search of an index, or a temporary B-tree that sorts the rows. + * + * Its `toString()` writes the plan as a tree, as the `sqlite3` command-line shell does: + * ``` + * QUERY PLAN + * |--SEARCH book USING INDEX idx_book_author (author=?) + * `--USE TEMP B-TREE FOR ORDER BY + * ``` + * + * The details are the text SQLite writes, which is meant to be read, and which differs between SQLite versions, as + * `SCAN TABLE book` and `SCAN book` do. A check of a plan should therefore look for the names of tables and indexes, + * and for phrases such as `USING INDEX`, `USING COVERING INDEX` and `TEMP B-TREE`, rather than compare whole details. + * The steps of subqueries and compound SELECTs are the children of the steps they belong to, except with a SQLite + * older than 3.24.0, such as Android's before API 30, which lists all steps in a row, with no children. + * + * @property steps The steps of the plan, each with the steps it consists of + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public class QueryPlan internal constructor( + public val steps: List, +) { + + /** + * A step of a plan. + * + * @property detail What the step does, in SQLite's words, as `SCAN book` + * @property children The steps it consists of, as those of a subquery + */ + public class Step internal constructor( + public val detail: String, + public val children: List, + ) { + override fun toString(): String = detail + } + + /** + * The details of all steps, each before those of its children. + */ + public val details: List = buildList { addDetails(steps) } + + private fun MutableList.addDetails(steps: List) { + for (step in steps) { + add(step.detail) + addDetails(step.children) + } + } + + override fun toString(): String = buildString { + append("QUERY PLAN") + appendSteps(steps, "") + } + + private fun StringBuilder.appendSteps(steps: List, indent: String) { + steps.forEachIndexed { index, step -> + val isLast = index == steps.lastIndex + append('\n').append(indent).append(if (isLast) "`--" else "|--").append(step.detail) + appendSteps(step.children, indent + if (isLast) " " else "| ") + } + } + + internal companion object { + + /** + * Reads the plan from the rows of `EXPLAIN QUERY PLAN`, whose columns tell its format, rather than the version + * of SQLite: since 3.24.0, they are `id`, `parent`, `notused` and `detail`, and a step's `parent` is the `id` + * of the step it belongs to, or 0; before, they are `selectid`, `order`, `from` and `detail`, which tell no + * such relation, so that the steps are listed as they are. + */ + fun of(cursor: CommonCursor): QueryPlan { + // Every driver throws for a column that the rows don't have + val parentColumn = runCatching { cursor.getColumnIndex("parent") }.getOrNull()?.takeIf { it >= 0 } + val detailColumn = cursor.getColumnIndex("detail") + if (parentColumn == null) + return QueryPlan(buildList { + cursor.forEachRow { add(Step(cursor.getString(detailColumn).orEmpty(), emptyList())) } + }) + val idColumn = cursor.getColumnIndex("id") + val rows = buildList { + cursor.forEachRow { + add(Row(cursor.getLong(idColumn), cursor.getLong(parentColumn), cursor.getString(detailColumn).orEmpty())) + } + } + // Grouped rather than read in a row, so that a step listed before the one it belongs to is still its child + val rowsByParent = rows.groupBy { it.parent } + val ids = rows.mapTo(HashSet()) { it.id } + fun stepsOf(rows: List): List = rows.map { Step(it.detail, stepsOf(rowsByParent[it.id].orEmpty())) } + return QueryPlan(stepsOf(rows.filter { it.parent !in ids })) + } + + private class Row(val id: Long, val parent: Long, val detail: String) + } +} diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/QueryPlanStatement.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/QueryPlanStatement.kt new file mode 100644 index 00000000..eca2898c --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/QueryPlanStatement.kt @@ -0,0 +1,53 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.sql.statement + +import com.ctrip.sqllin.driver.DatabaseConnection +import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI +import kotlin.concurrent.Volatile + +/** + * `EXPLAIN QUERY PLAN` of a SELECT, as `EXPLAIN_QUERY_PLAN(select)` builds: it doesn't run the SELECT, but tells how + * SQLite would run it, which [getResults] returns once the scope has run. + * + * The plan is read when the statement runs, and its cursor closed, as the plan is small, rather than when + * [getResults] is called, as the results of a SELECT are. + * + * @author Yuang Qiao + */ +@ExperimentalDSLDatabaseAPI +public class QueryPlanStatement internal constructor( + sqlStr: String, + private val connection: DatabaseConnection, + override val parameters: MutableList?, +) : SingleStatement(sqlStr) { + + @Volatile + private var plan: QueryPlan? = null + + override fun execute() { + plan = connection.query(sqlStr, params).use { QueryPlan.of(it) } + } + + /** + * Returns the plan of the SELECT. + * + * @throws IllegalStateException if the statement hasn't run yet, as within the scope that builds it + */ + public fun getResults(): QueryPlan = + plan ?: throw IllegalStateException("You have to call 'execute' function before call 'getResults'!!!") +} diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/RowCountStatement.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/RowCountStatement.kt new file mode 100644 index 00000000..53303785 --- /dev/null +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/RowCountStatement.kt @@ -0,0 +1,51 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.dsl.sql.statement + +import com.ctrip.sqllin.driver.DatabaseConnection +import kotlin.concurrent.Volatile + +/** + * The number of the rows of a SELECT, `SELECT count(*) FROM (select)`, which a PagingSource of sqllin-dsl-paging reads + * with its first page, so that it tells how many rows are before and after each page. It is read when it runs, under + * the lock its scope runs under. + * + * @author Yuang Qiao + */ +internal class RowCountStatement( + sqlStr: String, + private val connection: DatabaseConnection, + override val parameters: MutableList?, +) : SingleStatement(sqlStr) { + + @Volatile + private var count: Long? = null + + override fun execute() { + count = connection.query(sqlStr, params).use { + it.next() + it.getLong(0) + } + } + + /** + * Returns the number of rows the SELECT returned. + * + * @throws IllegalStateException if the statement hasn't run yet + */ + fun getResult(): Long = checkNotNull(count) { "You have to call 'execute' function before call 'getResult'!!!" } +} diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/SelectStatement.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/SelectStatement.kt index ee129c99..6449a6ac 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/SelectStatement.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/SelectStatement.kt @@ -16,7 +16,6 @@ package com.ctrip.sqllin.dsl.sql.statement -import com.ctrip.sqllin.driver.CommonCursor import com.ctrip.sqllin.driver.DatabaseConnection import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI import com.ctrip.sqllin.dsl.sql.clause.elementTables @@ -33,8 +32,9 @@ import kotlin.concurrent.Volatile * The class hierarchy enforces SQL clause ordering at compile time - each subclass accepts only valid * subsequent clauses (e.g., WHERE can be followed by GROUP BY, ORDER BY, or LIMIT). * - * Results are lazily evaluated and cached after [execute] is called. Use [getResults] to retrieve - * the deserialized entities. + * [execute] reads the rows, and decodes them, when the statement runs, in its scope, under the lock of the scope and + * in its transaction, and closes the cursor, so that the statement ends with the scope that runs it. Use [getResults] + * to retrieve the deserialized entities. * * @param T The entity type returned by this query * @property deserializer kotlinx.serialization strategy for decoding cursor rows to entities @@ -62,30 +62,32 @@ public sealed class SelectStatement( @Volatile private var result: List? = null - @Volatile - private var cursor: CommonCursor? = null - + /** + * Runs the query, and reads its rows at once. A cursor left open until the results were read would keep its + * statement, and with it a read of its tables, which couldn't be dropped meanwhile, and on Kotlin/Native the + * connection itself, as `sqlite3_close_v2` only closes it once its statements end, so that a database whose results + * weren't all read kept its file open after it was closed, which Windows then couldn't delete. + */ final override fun execute() { - cursor = connection.query(sqlStr, params) + result = connection.query(sqlStr, params).use { cursor -> + val decoder = QueryDecoder(cursor) + buildList { + cursor.forEachRow { + add(decoder.decodeSerializableValue(deserializer)) + } + } + } } /** - * Retrieves the query results as a list of deserialized entities. + * Retrieves the query results as a list of deserialized entities, which [execute] read. * - * Results are lazily computed on first call and cached for subsequent calls. * Throws [IllegalStateException] if called before [execute]. * * @return List of entities matching the query */ - public fun getResults(): List = result ?: cursor?.use { - val decoder = QueryDecoder(it) - result = buildList { - it.forEachRow { - add(decoder.decodeSerializableValue(deserializer)) - } - } - result!! - } ?: throw IllegalStateException("You have to call 'execute' function before call 'getResults'!!!") + public fun getResults(): List = + result ?: throw IllegalStateException("You have to call 'execute' function before call 'getResults'!!!") /** * Checks what can only be checked once no clause can be appended anymore: that a statement that needs GROUP BY has @@ -93,7 +95,7 @@ public sealed class SelectStatement( * * @throws IllegalArgumentException if the statement isn't complete */ - internal fun checkComplete() { + override fun checkComplete() { ungroupedError?.let { throw IllegalArgumentException(it) } } @@ -167,40 +169,6 @@ public class ResultColumnSelectStatement internal constructor( GroupBySelectStatement(buildSQL(clause), deserializer, connection, container, parameters, null, tables + clause.elementTables) } -/** - * SELECT statement with JOIN clause applied. - * - * Can be followed by: - * - WHERE - * - GROUP BY - * - ORDER BY - * - LIMIT - * - * @author Yuang Qiao - */ -public class JoinSelectStatement internal constructor( - sqlStr: String, - deserializer: DeserializationStrategy, - connection: DatabaseConnection, - container: StatementContainer, - parameters: MutableList?, - ungroupedError: String?, - tables: Set, -) : SelectStatement(sqlStr, deserializer, connection, container, parameters, ungroupedError, tables) { - - internal infix fun appendToWhere(clause: WhereClause): WhereSelectStatement = - WhereSelectStatement(buildSQL(clause), deserializer, connection, container, parametersOf(parameters, clause.selectCondition.parameters), ungroupedError, tables + clause.selectCondition.tables) - - internal infix fun appendToLimit(clause: LimitClause): LimitSelectStatement = - LimitSelectStatement(buildSQL(clause), deserializer, connection, container, parameters, ungroupedError, tables) - - internal infix fun appendToOrderBy(clause: OrderByClause): OrderBySelectStatement = - OrderBySelectStatement(buildSQL(clause), deserializer, connection, container, parameters, ungroupedError, tables + clause.elementTables) - - internal infix fun appendToGroupBy(clause: GroupByClause): GroupBySelectStatement = - GroupBySelectStatement(buildSQL(clause), deserializer, connection, container, parameters, null, tables + clause.elementTables) -} - /** * SELECT statement with GROUP BY clause applied. * @@ -304,7 +272,7 @@ public class LimitSelectStatement internal constructor( * The statement is ready for execution. * * @property isSimple Whether the statement is a single SELECT without LIMIT, as `SELECT X` builds, rather than one - * with OFFSET, or a compound built by the deprecated `UNION {}` block + * with OFFSET * * @author Yuang Qiao */ diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/SingleStatement.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/SingleStatement.kt index 8bec5ee2..69dad39c 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/SingleStatement.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/SingleStatement.kt @@ -47,6 +47,15 @@ public sealed class SingleStatement( internal val params: Array? get() = parameters?.toTypedArray() + /** + * Checks what can only be checked once no clause can be appended anymore, as that an ORDER BY of an UPDATE or + * DELETE is followed by LIMIT. Called for every statement of a scope before any of them runs, so that a failing + * check runs nothing. + * + * @throws IllegalArgumentException if the statement isn't complete + */ + internal open fun checkComplete(): Unit = Unit + /** * Logs the SQL string and parameters for debugging. */ diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/StatementContainer.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/StatementContainer.kt index adc7a500..33de18d2 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/StatementContainer.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/StatementContainer.kt @@ -19,27 +19,19 @@ package com.ctrip.sqllin.dsl.sql.statement /** * Container for managing and modifying SQL statements. * - * Used by statement builders (e.g., UPDATE, JOIN) to replace or update the last statement - * in a collection when DSL operations refine or extend it. For example, when an UPDATE - * statement adds a WHERE clause, it replaces the initial UPDATE statement. A SELECT that - * becomes part of an `INSERT INTO ... SELECT` is removed, as it no longer runs on its own. + * Used by statement builders to replace a statement when DSL operations refine or extend it. For example, when an + * UPDATE statement adds a WHERE clause, it replaces the initial UPDATE statement, wherever it is among the statements, + * rather than the last one, which another statement built since may be. A SELECT that becomes part of an + * `INSERT INTO ... SELECT` is removed, as it no longer runs on its own. * * Implementations: * - [DatabaseExecuteEngine]: Executes standalone statements * - [TransactionStatementsGroup]: Groups statements within a transaction - * - [UnionSelectStatementGroup]: Accumulates SELECT statements for UNION operations * * @author Yuang Qiao */ internal interface StatementContainer { - /** - * Replaces the most recently added statement with a modified version. - * - * Used when DSL operations progressively build up a statement (e.g., adding WHERE to UPDATE). - */ - infix fun changeLastStatement(statement: SingleStatement) - /** * Removes [statement] if this container holds it, wherever it is. */ @@ -47,6 +39,9 @@ internal interface StatementContainer { /** * Replaces [statement] with [newStatement], where [statement] is, as when a clause completes it. + * + * @throws IllegalStateException if this container doesn't hold [statement]: a clause was already appended to it, + * which replaced it, or it became part of another statement, as a subquery does */ fun replaceStatement(statement: SingleStatement, newStatement: SingleStatement) } \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/TransactionStatementsGroup.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/TransactionStatementsGroup.kt index f790db92..1b165911 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/TransactionStatementsGroup.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/TransactionStatementsGroup.kt @@ -17,6 +17,7 @@ package com.ctrip.sqllin.dsl.sql.statement import com.ctrip.sqllin.driver.DatabaseConnection +import com.ctrip.sqllin.driver.TransactionMode import com.ctrip.sqllin.driver.withTransaction /** @@ -28,12 +29,14 @@ import com.ctrip.sqllin.driver.withTransaction * * @property databaseConnection Connection for executing the transactional operations * @property enableSimpleSQLLog Whether to log each statement's SQL before execution + * @property mode How the transaction begins * * @author Yuang Qiao */ internal class TransactionStatementsGroup( private val databaseConnection: DatabaseConnection, private val enableSimpleSQLLog: Boolean, + private val mode: TransactionMode, ) : ExecutableStatement, StatementContainer { private val statementList = ArrayDeque() @@ -58,39 +61,36 @@ internal class TransactionStatementsGroup( val writtenTables: Set get() = statementList.mapNotNullTo(LinkedHashSet()) { Changes.writtenTable(it) } + /** + * The tables and views the SELECTs of the transaction read. + * + * @see DatabaseExecuteEngine.readTables + */ + val readTables: Set + get() = statementList.flatMapTo(LinkedHashSet()) { (it as? SelectStatement<*>)?.tables.orEmpty() } + override infix fun removeStatement(statement: SingleStatement) { statementList.remove(statement) } override fun replaceStatement(statement: SingleStatement, newStatement: SingleStatement) { val index = statementList.indexOf(statement) - check(index >= 0) { "The statement to replace isn't one of the transaction's." } + check(index >= 0) { "The statement isn't one of the transaction's: a clause was already appended to it, which replaced it, or it became part of another statement, as a subquery does." } statementList[index] = newStatement } /** * Checks that every statement of the transaction is complete, before any of them runs. * - * @see SelectStatement.checkComplete + * @see SingleStatement.checkComplete */ - fun checkComplete() = statementList.forEach { - (it as? SelectStatement<*>)?.checkComplete() - } + fun checkComplete() = statementList.forEach { it.checkComplete() } - override fun execute() = databaseConnection.withTransaction { + override fun execute() = databaseConnection.withTransaction(mode) { statementList.forEach { if (enableSimpleSQLLog) it.printlnSQL() it.execute() } } - - override infix fun changeLastStatement(statement: SingleStatement) { - if (statementList.lastOrNull() is UpdateStatementWithoutWhereClause<*> - || statementList.lastOrNull() is SelectStatement<*>) { - statementList.removeLast() - statementList.add(statement) - } else - throw IllegalStateException("Current statement can't append clause.") - } } \ No newline at end of file diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/TriggerBody.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/TriggerBody.kt index c628f9bd..cdf23dbc 100644 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/TriggerBody.kt +++ b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/TriggerBody.kt @@ -30,21 +30,13 @@ internal class TriggerBody : StatementContainer { statements.add(statement) } - override infix fun changeLastStatement(statement: SingleStatement) { - if (statements.lastOrNull() is UpdateStatementWithoutWhereClause<*> || statements.lastOrNull() is SelectStatement<*>) { - statements.removeLast() - statements.add(statement) - } else - throw IllegalStateException("Current statement can't append clause.") - } - override infix fun removeStatement(statement: SingleStatement) { statements.remove(statement) } override fun replaceStatement(statement: SingleStatement, newStatement: SingleStatement) { val index = statements.indexOf(statement) - check(index >= 0) { "The statement to replace isn't one of the trigger's." } + check(index >= 0) { "The statement isn't one of the trigger's: a clause was already appended to it, which replaced it, or it became part of another statement, as a subquery does." } statements[index] = newStatement } } diff --git a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/UnionSelectStatementGroup.kt b/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/UnionSelectStatementGroup.kt deleted file mode 100644 index 606dbd87..00000000 --- a/sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/sql/statement/UnionSelectStatementGroup.kt +++ /dev/null @@ -1,95 +0,0 @@ -/* - * Copyright (C) 2022 Ctrip.com. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package com.ctrip.sqllin.dsl.sql.statement - -/** - * Container for building UNION queries from multiple SELECT statements. - * - * Accumulates SELECT statements written inside a UNION DSL scope and combines them - * with UNION or UNION ALL operators. Supports progressive clause building on individual - * SELECT statements before they are unioned. - * - * @param T The entity type returned by all SELECT statements (must be compatible) - * - * @author Yuang Qiao - */ -internal class UnionSelectStatementGroup : StatementContainer { - - private val statementList = ArrayDeque>() - - infix fun addSelectStatement(selectStatement: SelectStatement) { - statementList.add(selectStatement) - } - - override infix fun removeStatement(statement: SingleStatement) { - statementList.remove(statement) - } - - override fun replaceStatement(statement: SingleStatement, newStatement: SingleStatement): Unit = - error("A UNION block only holds SELECT statements, which aren't replaced.") - - /** - * Combines all accumulated SELECT statements into a single UNION query. - * - * Merges parameters from all statements and joins their SQL with UNION or UNION ALL operators. - * Requires at least two SELECT statements. - * - * @param isUnionAll If true, uses UNION ALL (includes duplicates); otherwise uses UNION (distinct rows) - * @return Final SELECT statement representing the complete UNION query - */ - internal fun unionStatements(isUnionAll: Boolean): FinalSelectStatement { - require(statementList.isNotEmpty()) { "Please write at least two 'select' statements on 'UNION' scope" } - var parameters: MutableList? = null - val unionSqlStr = buildString { - check(statementList.size > 1) { "Please write at least two 'select' statements on 'UNION' scope" } - val unionKeyWord = if (isUnionAll) " UNION ALL " else " UNION " - statementList.forEachIndexed { index, statement -> - statement.checkComplete() - append(statement.sqlStr) - if (parameters == null) - parameters = statement.parameters - else statement.parameters?.let { - parameters!!.addAll(it) - } - if (index != statementList.lastIndex) - append(unionKeyWord) - } - } - - return statementList.first().run { - FinalSelectStatement( - sqlStr = unionSqlStr, - deserializer = deserializer, - connection = connection, - container = container, - parameters, - ungroupedError = null, - tables = statementList.flatMapTo(LinkedHashSet()) { it.tables }, - isSimple = false, - ) - } - } - - @Suppress("UNCHECKED_CAST") - override fun changeLastStatement(statement: SingleStatement) { - if (statementList.lastOrNull() is SelectStatement<*>) { - statementList.removeLast() - statementList.add(statement as SelectStatement) - } else - throw IllegalStateException("Current statement can't append clause") - } -} \ No newline at end of file diff --git a/sqllin-processor/build.gradle.kts b/sqllin-processor/build.gradle.kts index 09d1fffc..22473fe0 100644 --- a/sqllin-processor/build.gradle.kts +++ b/sqllin-processor/build.gradle.kts @@ -13,9 +13,10 @@ repositories { mavenCentral() } -java { - sourceCompatibility = JavaVersion.VERSION_21 - targetCompatibility = JavaVersion.VERSION_21 +// The JDK of the other modules, which compiles both the Java and the Kotlin classes for it, rather than the Kotlin ones +// for the JDK that runs the build +kotlin { + jvmToolchain(libs.versions.jvm.toolchain.get().toInt()) } dependencies { diff --git a/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ClauseProcessor.kt b/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ClauseProcessor.kt index 87a5a684..6e56f4b2 100644 --- a/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ClauseProcessor.kt +++ b/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ClauseProcessor.kt @@ -43,13 +43,17 @@ import java.io.OutputStreamWriter * - PRIMARY KEY with optional AUTOINCREMENT * - NOT NULL constraints * - UNIQUE constraints (single and composite) - * - COLLATE NOCASE for case-insensitive text columns + * - COLLATE NOCASE for case-insensitive text columns, and COLLATE RTRIM for those that ignore trailing spaces * - CHECK constraints of columns and of the table, optionally named * - **Type support**: * - All Kotlin primitive types and unsigned variants * - String, Char, Boolean, ByteArray * - Enum classes (stored as integers) * - Typealiases of supported types + * - Any type whose serializer encodes it as one of these: a type with a built-in serializer, as `Uuid`, a value + * class, or a type given a serializer with `@Serializable(with = ...)`, whose column has the type of the values the + * serializer stores and whose element, a `ClauseConverted`, converts the values of its conditions with it; see + * [ColumnTypes] * * A `@DBRow` class annotated with [@Fts4][com.ctrip.sqllin.dsl.annotation.Fts4] or * [@Fts3][com.ctrip.sqllin.dsl.annotation.Fts3] gets an `FtsTable` object instead, whose statement is a @@ -66,6 +70,7 @@ import java.io.OutputStreamWriter * @see com.ctrip.sqllin.dsl.annotation.Unique * @see com.ctrip.sqllin.dsl.annotation.CompositeUnique * @see com.ctrip.sqllin.dsl.annotation.CollateNoCase + * @see com.ctrip.sqllin.dsl.annotation.CollateRTrim * @see com.ctrip.sqllin.dsl.annotation.Check */ class ClauseProcessor( @@ -90,10 +95,15 @@ class ClauseProcessor( /** The annotations that declare constraints, which only a table's columns can have. */ val CONSTRAINT_ANNOTATIONS = listOf( - "PrimaryKey", "CompositePrimaryKey", "CollateNoCase", "Unique", "CompositeUnique", + "PrimaryKey", "CompositePrimaryKey", "CollateNoCase", "CollateRTrim", "Unique", "CompositeUnique", "ForeignKeyGroup", "References", "ForeignKey", "Default", "Check", ).map { "$ANNOTATION_PACKAGE.$it" }.toSet() const val ANNOTATION_SERIALIZABLE = "kotlinx.serialization.Serializable" + const val ANNOTATION_OPT_IN = "kotlin.OptIn" + const val ANNOTATION_REQUIRES_OPT_IN = "kotlin.RequiresOptIn" + const val EXPERIMENTAL_API = "com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI" + const val EXPERIMENTAL_API_NAME = "ExperimentalDSLDatabaseAPI" + const val CLAUSE_CONVERTED = "com.ctrip.sqllin.dsl.sql.clause.ClauseConverted" const val ANNOTATION_TRANSIENT = "kotlinx.serialization.Transient" /** @@ -158,22 +168,13 @@ class ClauseProcessor( // Every stored property needs a column. A property of a type no column can hold used to be skipped silently: // left out of CREATE TABLE while its serializer still wrote and read it, so it only failed at runtime, and as // the last property it left a trailing comma that made CREATE TABLE itself invalid. Report all of them here. - val unsupportedProperties = propertyList.filter { getClauseElementTypeStr(it) == null } - unsupportedProperties.forEach { property -> - environment.logger.error( - "The property '${property.simpleName.asString()}' of '@DBRow' class '$className' has the type " + - "'${property.type.resolve()}', which no column can hold. Supported types are Byte, Short, Int, Long, " + - "Float, Double and their unsigned variants, Boolean, Char, String, ByteArray, enum classes, and type " + - "aliases of these. To keep the property out of the table, annotate it with @kotlinx.serialization.Transient.", - property, - ) - } - if (unsupportedProperties.isNotEmpty()) + val columnTypes = propertyList.map { ColumnTypes.of(it, classDeclaration.containingFile) } + if (!reportUnsupported(propertyList, columnTypes, "'@DBRow' class '$className'")) continue val ftsAnnotations = classDeclaration.annotations.filter { it.qualifiedName == ANNOTATION_FTS4 || it.qualifiedName == ANNOTATION_FTS3 }.toList() if (ftsAnnotations.isNotEmpty()) { - processFtsTable(classDeclaration, ftsAnnotations, propertyList, tableName as String, visibilityModifier) + processFtsTable(classDeclaration, ftsAnnotations, propertyList, columnTypes, tableName as String, visibilityModifier) continue } @@ -202,6 +203,11 @@ class ClauseProcessor( // The column properties carry @ColumnNameDslMaker for IntelliJ IDEA's DSL highlighting, a target the compiler // flags as having no effect on scope control. This code is compiled in the user's module, so keep it quiet. writer.write("@Suppress(\"DSL_MARKER_APPLIED_TO_WRONG_TARGET\")\n") + // ClauseConverted is experimental, and so can be the type of a converted column, as Uuid is, and the + // entity itself, which its declarations opt in to or propagate + val hasConverted = columnTypes.any { it is ColumnType.Converted } + optInAnnotation(classDeclaration, propertyList, hasConverted, if (hasConverted) listOf(EXPERIMENTAL_API) else emptyList()) + ?.let { writer.write(it) } writer.write("${visibilityModifier}object $objectName : Table<$className>(\"$tableName\") {\n\n") writer.write(" override fun kSerializer() = $className.serializer()\n\n") @@ -218,7 +224,7 @@ class ClauseProcessor( // Process each property to generate column definitions propertyList.forEachIndexed { index, property -> - val clauseElementTypeName = checkNotNull(getClauseElementTypeStr(property)) // Rejected above + val columnType = columnTypes[index] val propertyName = property.simpleName.asString() val elementName = "$className.serializer().descriptor.getElementName($index)" val isNotNull = property.type.resolve().nullability == Nullability.NOT_NULL @@ -227,7 +233,7 @@ class ClauseProcessor( with(createSQLBuilder) { append(propertyName) - columnConstraintParser.parseProperty(this, property, propertyName, isNotNull) + columnConstraintParser.parseProperty(this, property, propertyName, isNotNull, columnType, index) // Before @References, whose constraint name SQLite would give the CHECK constraints after it appendColumnChecks(this, property) @@ -242,13 +248,14 @@ class ClauseProcessor( // Write 'SelectClause' code. writer.write(" @ColumnNameDslMaker\n") writer.write(" val $propertyName\n") - writer.write(" get() = $clauseElementTypeName($elementName, this, ${!isNotNull})\n\n") + writer.write(" get() = ${clauseElement(columnType, elementName, isNotNull)}\n\n") writer.write(" @ColumnNameDslMaker\n") - writer.write(" var SetClause<$className>.$propertyName: ${property.typeName}") + // A converted type, which can be generic, as a List, with its arguments + writer.write(" var SetClause<$className>.$propertyName: ${(columnType as? ColumnType.Converted)?.typeName ?: property.typeName}") writer.write(if (isNotNull) "\n" else "?\n") writer.write(SET_CLAUSE_GETTER_DEPRECATION) - writer.write(" get() = ${getSetClauseGetterValue(property)}\n") - writer.write(" set(value) = ${appendFunction(elementName, property, isNotNull)}\n\n") + writer.write(" get() = ${getSetClauseGetterValue(columnType)}\n") + writer.write(" set(value) = ${appendFunction(elementName, columnType, isNotNull)}\n\n") } columnConstraintParser.generateCodeForPrimaryKey(writer, createSQLBuilder) @@ -259,8 +266,19 @@ class ClauseProcessor( } createSQLBuilder.append(')') - // A CHECK expression or a DEFAULT value can hold characters that a Kotlin string literal escapes - writer.write(" override val createSQL = \"${kotlinStringContent(createSQLBuilder.toString())}\"\n") + // A CHECK expression or a DEFAULT value can hold characters that a Kotlin string literal escapes. The type + // of a converted column is the one its serializer stores, which the statement computes when it is read. + val createSQL = kotlinStringContent(createSQLBuilder.toString()) + if (CONVERTED_TYPE.containsMatchIn(createSQL)) { + val template = CONVERTED_TYPE.replace(createSQL) { + val (index, collation) = it.destructured + "\${columnType($index${if (collation.isEmpty()) "" else ", \"$collation\""})}" + } + writer.write(" override val createSQL: String\n") + writer.write(" get() = \"$template\"\n") + } else { + writer.write(" override val createSQL = \"$createSQL\"\n") + } writer.write("}\n") } @@ -289,6 +307,7 @@ class ClauseProcessor( classDeclaration: KSClassDeclaration, ftsAnnotations: List, propertyList: List, + columnTypes: List, tableName: String, visibilityModifier: String, ) { @@ -309,7 +328,7 @@ class ClauseProcessor( var rowIdProperty: KSPropertyDeclaration? = null val columns = ArrayList() - for (property in propertyList) { + for ((property, columnType) in propertyList.zip(columnTypes)) { val propertyName = property.simpleName.asString() val constraints = property.annotations.filter { it.qualifiedName in CONSTRAINT_ANNOTATIONS }.toList() val primaryKey = constraints.find { it.qualifiedName == ANNOTATION_PRIMARY_KEY } @@ -320,8 +339,8 @@ class ClauseProcessor( error("The property '$propertyName' of FTS table '$className' is named as the rowid. $rules.", property) primaryKey == null -> error("The property '$propertyName' of FTS table '$className' has to be annotated with '@PrimaryKey'. $rules.", property) - resolvedTypeName(property) != FullNameCache.LONG -> - error("The property '$propertyName' of FTS table '$className' has the type '${property.type.resolve()}'. $rules.", property) + columnType != ColumnType.Basic(FullNameCache.LONG) -> + error("The property '$propertyName' of FTS table '$className' has the type '${property.type.resolve()}', or a serializer of its own. $rules, with its default serializer.", property) primaryKey.arguments.any { it.name?.asString() == "autoIncrement" && it.value == true } -> error("The rowid of FTS table '$className' can't be AUTOINCREMENT, which only a table's INTEGER PRIMARY KEY can be.", property) rowIdProperty != null -> @@ -338,8 +357,8 @@ class ClauseProcessor( (constraints - primaryKey).filterNotNull().forEach { error("The property '$propertyName' of FTS table '$className' can't be annotated with '@${it.shortName.asString()}': an FTS table's columns have no constraints.", property) } - if (resolvedTypeName(property) != FullNameCache.STRING) - error("The property '$propertyName' of FTS table '$className' has the type '${property.type.resolve()}', but FTS indexes text, so its columns are String or String?.", property) + if (columnType != ColumnType.Basic(FullNameCache.STRING)) + error("The property '$propertyName' of FTS table '$className' has the type '${property.type.resolve()}', or a serializer of its own, but FTS indexes text, so its columns are String or String? with their default serializer.", property) columns.add(propertyName) } if (columns.isEmpty()) @@ -389,24 +408,26 @@ class ClauseProcessor( writer.write("import com.ctrip.sqllin.dsl.sql.FtsTable\n") writer.write("import com.ctrip.sqllin.dsl.sql.PrimaryKeyInfo\n\n") // As for table objects, the column properties carry @ColumnNameDslMaker for IntelliJ IDEA's DSL - // highlighting. FtsTable is experimental, and the table object opts in so that its users don't have to. + // highlighting. FtsTable is experimental, and the table object opts in so that its users don't have to, as + // it does to the markers that the entity propagates, as its columns are never converted. writer.write("@Suppress(\"DSL_MARKER_APPLIED_TO_WRONG_TARGET\")\n") - writer.write("@OptIn(ExperimentalDSLDatabaseAPI::class)\n") + writer.write(checkNotNull(optInAnnotation(classDeclaration, propertyList, hasConverted = false, listOf(EXPERIMENTAL_API_NAME)))) writer.write("${visibilityModifier}object $objectName : FtsTable<$className>(\"$tableName\") {\n\n") writer.write(" override fun kSerializer() = $className.serializer()\n\n") writer.write(" inline operator fun invoke(block: $objectName.(table: $objectName) -> R): R = this.block(this)\n\n") propertyList.forEachIndexed { index, property -> + val columnType = columnTypes[index] // A String or a Long, checked above val propertyName = property.simpleName.asString() val elementName = "$className.serializer().descriptor.getElementName($index)" val isNotNull = property.type.resolve().nullability == Nullability.NOT_NULL writer.write(" @ColumnNameDslMaker\n") writer.write(" val $propertyName\n") - writer.write(" get() = ${checkNotNull(getClauseElementTypeStr(property))}($elementName, this, ${!isNotNull})\n\n") + writer.write(" get() = ${clauseElement(columnType, elementName, isNotNull)}\n\n") writer.write(" @ColumnNameDslMaker\n") writer.write(" var SetClause<$className>.$propertyName: ${property.typeName}${if (isNotNull) "" else "?"}\n") writer.write(SET_CLAUSE_GETTER_DEPRECATION) - writer.write(" get() = ${getSetClauseGetterValue(property)}\n") - writer.write(" set(value) = ${appendFunction(elementName, property, isNotNull)}\n\n") + writer.write(" get() = ${getSetClauseGetterValue(columnType)}\n") + writer.write(" set(value) = ${appendFunction(elementName, columnType, isNotNull)}\n\n") } val rowId = rowIdProperty if (rowId == null) { @@ -497,14 +518,6 @@ class ClauseProcessor( return isValid } - /** - * Returns the qualified name of a property's type, without nullability, through a type alias. - */ - private fun resolvedTypeName(property: KSPropertyDeclaration): String? = when (val declaration = property.type.resolve().declaration) { - is KSTypeAlias -> declaration.type.resolve().declaration.typeName - else -> declaration.typeName - } - /** * Escapes [string] to be the content of a Kotlin string literal. */ @@ -551,7 +564,8 @@ class ClauseProcessor( !property.annotations.any { ksAnnotation -> ksAnnotation.annotationType.resolve().isAssignableFrom(transientName) } }.toList() - var isValid = true + val columnTypes = propertyList.map { ColumnTypes.of(it, classDeclaration.containingFile) } + var isValid = reportUnsupported(propertyList, columnTypes, "'@DBView' class '$className'") classDeclaration.annotations.filter { it.qualifiedName in CONSTRAINT_ANNOTATIONS }.forEach { environment.logger.error("The view '$className' can't be annotated with '@${it.shortName.asString()}': a view has no constraints.", classDeclaration) isValid = false @@ -565,15 +579,6 @@ class ClauseProcessor( ) isValid = false } - if (getClauseElementTypeStr(property) == null) { - environment.logger.error( - "The property '$propertyName' of '@DBView' class '$className' has the type '${property.type.resolve()}', which no column can hold. " + - "Supported types are Byte, Short, Int, Long, Float, Double and their unsigned variants, Boolean, Char, String, ByteArray, enum classes, " + - "and type aliases of these. To leave the property out of the view, annotate it with @kotlinx.serialization.Transient.", - property, - ) - isValid = false - } } if (!isValid) continue @@ -601,16 +606,16 @@ class ClauseProcessor( // As for table objects, the column properties carry @ColumnNameDslMaker for IntelliJ IDEA's DSL // highlighting. View is experimental, and the view object opts in so that its users don't have to. writer.write("@Suppress(\"DSL_MARKER_APPLIED_TO_WRONG_TARGET\")\n") - writer.write("@OptIn(ExperimentalDSLDatabaseAPI::class)\n") + val hasConverted = columnTypes.any { it is ColumnType.Converted } + writer.write(checkNotNull(optInAnnotation(classDeclaration, propertyList, hasConverted, listOf(EXPERIMENTAL_API_NAME)))) writer.write("${visibilityModifier}object $objectName : View<$className>(\"$viewName\") {\n\n") writer.write(" override fun kSerializer() = $className.serializer()\n\n") writer.write(" inline operator fun invoke(block: $objectName.(view: $objectName) -> R): R = this.block(this)\n\n") propertyList.forEachIndexed { index, property -> - val clauseElementTypeName = checkNotNull(getClauseElementTypeStr(property)) // Rejected above val isNotNull = property.type.resolve().nullability == Nullability.NOT_NULL writer.write(" @ColumnNameDslMaker\n") writer.write(" val ${property.simpleName.asString()}\n") - writer.write(" get() = $clauseElementTypeName($className.serializer().descriptor.getElementName($index), this, ${!isNotNull})\n\n") + writer.write(" get() = ${clauseElement(columnTypes[index], "$className.serializer().descriptor.getElementName($index)", isNotNull)}\n\n") } writer.write("}\n") } @@ -622,33 +627,67 @@ class ClauseProcessor( get() = annotationType.resolve().declaration.qualifiedName?.asString() /** - * Maps a property's Kotlin type to the corresponding clause element type name. - * - * Handles three categories: - * - **Typealiases**: Resolves to underlying type and maps to appropriate clause type - * - **Enum classes**: Maps to `ClauseEnum` for type-safe enum operations - * - **Standard types**: Maps to `ClauseNumber`, `ClauseString`, ClauseBoolean, or ClauseBlob - * - * The type argument is the property's type without nullability, as an element knows the type of its values, so - * that `AS` only selects it into a property of that type. + * Reports the properties that no column can hold, as [columnTypes] give them, of [owner], as `'@DBRow' class 'Person'`. * - * @param property The property declaration to analyze - * @return The clause type (such as `ClauseNumber` or `ClauseEnum`), or null if unsupported + * @return Whether there are none */ - private fun getClauseElementTypeStr(property: KSPropertyDeclaration): String? = when ( - val declaration = property.type.resolve().declaration - ) { - is KSTypeAlias -> { - val realDeclaration = declaration.type.resolve().declaration - getClauseElementTypeStrByTypeName(realDeclaration.typeName) ?: kotlin.run { - if (realDeclaration is KSClassDeclaration && realDeclaration.classKind == ClassKind.ENUM_CLASS) - "ClauseEnum<${realDeclaration.typeName}>" - else - null + private fun reportUnsupported(propertyList: List, columnTypes: List, owner: String): Boolean { + var isValid = true + propertyList.zip(columnTypes).forEach { (property, columnType) -> + if (columnType is ColumnType.Unsupported) { + environment.logger.error("The property '${property.simpleName.asString()}' of $owner ${columnType.reason}.", property) + isValid = false } } - is KSClassDeclaration if declaration.classKind == ClassKind.ENUM_CLASS -> "ClauseEnum<${declaration.typeName}>" - else -> getClauseElementTypeStrByTypeName(declaration.typeName) + return isValid + } + + /** + * Returns the `@OptIn` annotation of the object generated for [classDeclaration], with a line break, which opts in + * to [markers], as they are written, and to the markers that the object needs because of the entity's declarations: + * those that the class, its [properties] or its file are annotated with, which propagate their requirement to the + * uses of the class, as the object's are; and, if the table [hasConverted] columns, those that their `@OptIn`s give, + * as the type of a converted column, as `Uuid`, can need, as it is written in the object. Null if there are none. + */ + private fun optInAnnotation( + classDeclaration: KSClassDeclaration, + properties: List, + hasConverted: Boolean, + markers: List, + ): String? { + val annotations = classDeclaration.annotations + properties.asSequence().flatMap { it.annotations } + + classDeclaration.containingFile?.annotations.orEmpty() + val propagated = annotations + .map { it.annotationType.resolve().declaration } + .filter { declaration -> declaration.annotations.any { it.qualifiedName == ANNOTATION_REQUIRES_OPT_IN } } + .mapNotNull { it.qualifiedName?.asString() } + val optedIn = if (hasConverted) { + annotations + .filter { it.qualifiedName == ANNOTATION_OPT_IN } + .flatMap { annotation -> annotation.arguments.flatMap { (it.value as? List<*>).orEmpty() } } + .mapNotNull { (it as? KSType)?.declaration?.qualifiedName?.asString() } + } else { + emptySequence() + } + // ExperimentalDSLDatabaseAPI is written by its simple name where the object imports it + val all = (markers.asSequence() + propagated + optedIn) + .distinctBy { if (it == EXPERIMENTAL_API_NAME) EXPERIMENTAL_API else it } + .toList() + return if (all.isEmpty()) null else "@OptIn(${all.joinToString { "$it::class" }})\n" + } + + /** + * Returns the Kotlin expression of the element of a column of [columnType], named [elementName], as + * `ClauseNumber(name, this, false)`. + * + * The type argument is the property's type without nullability, as an element knows the type of its values, so + * that `AS` only selects it into a property of that type. A converted column's element gets its serializer. + */ + private fun clauseElement(columnType: ColumnType, elementName: String, isNotNull: Boolean): String = when (columnType) { + is ColumnType.Basic -> "${checkNotNull(getClauseElementTypeStrByTypeName(columnType.typeName))}($elementName, this, ${!isNotNull})" + is ColumnType.DefaultEnum -> "ClauseEnum<${columnType.declaration.typeName}>($elementName, this, ${!isNotNull})" + is ColumnType.Converted -> "$CLAUSE_CONVERTED<${columnType.typeName}>($elementName, this, ${!isNotNull}, ${columnType.serializer})" + is ColumnType.Unsupported -> error("The unsupported column has been reported") // Rejected before generating } /** @@ -660,7 +699,7 @@ class ClauseProcessor( * - Boolean → ClauseBoolean * - ByteArray → ClauseBlob * - * Note: Enum types are handled separately by [getClauseElementTypeStr]. + * Note: Enum types are handled separately by [clauseElement]. * * @param typeName The fully qualified type name to map * @return The clause type (such as `ClauseNumber`), or null if unsupported @@ -688,29 +727,18 @@ class ClauseProcessor( } /** - * Generates the default getter value for SetClause properties based on type. - * Supports typealiases by resolving them to their underlying types. - * - * @return The default value string for the property type, or null if unsupported + * Generates the getter value of a SetClause property, a placeholder that is never read, as reading it is an error: + * a default value of its type, the first entry of an enum, or, for a converted type, which has no known value, a + * call that throws. */ - private fun getSetClauseGetterValue(property: KSPropertyDeclaration): String? { - fun KSClassDeclaration.firstEnum() = declarations + private fun getSetClauseGetterValue(columnType: ColumnType): String? = when (columnType) { + is ColumnType.Basic -> getDefaultValueByType(columnType.typeName) + is ColumnType.DefaultEnum -> columnType.declaration.declarations .filterIsInstance() .firstOrNull { it.classKind == ClassKind.ENUM_ENTRY } ?.qualifiedName?.asString() - return when (val declaration = property.type.resolve().declaration) { - is KSTypeAlias -> { - val realDeclaration = declaration.type.resolve().declaration - getDefaultValueByType(realDeclaration.typeName) ?: kotlin.run { - if (realDeclaration is KSClassDeclaration && realDeclaration.classKind == ClassKind.ENUM_CLASS) - realDeclaration.firstEnum() - else - null - } - } - is KSClassDeclaration if declaration.classKind == ClassKind.ENUM_CLASS -> declaration.firstEnum() - else -> getDefaultValueByType(declaration.typeName) - } + is ColumnType.Converted -> "error(\"A column in SET {} can only be assigned.\")" + is ColumnType.Unsupported -> null } /** @@ -741,33 +769,20 @@ class ClauseProcessor( } /** - * Generates the appropriate append function call for SetClause setters. - * Supports typealiases by resolving them to their underlying types. - * - * For enum types, converts the enum value to its ordinal before appending, with a safe call only - * when the enum is nullable. + * Generates the call of a SetClause setter that appends its value: as it is, as the ordinal of an enum entry, with a + * safe call only when the enum is nullable, or converted by the serializer of a converted column, as it is stored. * * @param elementName The serialized element name - * @param property The property declaration + * @param columnType What the column holds * @param isNotNull Whether the setter's `value` is non-null, as for the SetClause property it belongs to * @return The append function call string, or null if unsupported type */ - private fun appendFunction(elementName: String, property: KSPropertyDeclaration, isNotNull: Boolean): String? { + private fun appendFunction(elementName: String, columnType: ColumnType, isNotNull: Boolean): String? = when (columnType) { + is ColumnType.Basic -> appendFunctionByTypeName(elementName, columnType.typeName) // A safe call on a non-null value is reported as unnecessary, in the module compiling the generated code - val appendEnum = "appendAny($elementName, value${if (isNotNull) "" else "?"}.ordinal)" - return when (val declaration = property.type.resolve().declaration) { - is KSTypeAlias -> { - val realDeclaration = declaration.type.resolve().declaration - appendFunctionByTypeName(elementName, realDeclaration.typeName) ?: kotlin.run { - if (realDeclaration is KSClassDeclaration && realDeclaration.classKind == ClassKind.ENUM_CLASS) - appendEnum - else - null - } - } - is KSClassDeclaration if declaration.classKind == ClassKind.ENUM_CLASS -> appendEnum - else -> appendFunctionByTypeName(elementName, declaration.typeName) - } + is ColumnType.DefaultEnum -> "appendAny($elementName, value${if (isNotNull) "" else "?"}.ordinal)" + is ColumnType.Converted -> "appendConverted($elementName, value, ${columnType.serializer})" + is ColumnType.Unsupported -> null } /** diff --git a/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ColumnConstraintParser.kt b/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ColumnConstraintParser.kt index 54251ee8..dc8dd200 100644 --- a/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ColumnConstraintParser.kt +++ b/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ColumnConstraintParser.kt @@ -23,9 +23,17 @@ import com.google.devtools.ksp.symbol.KSAnnotation import com.google.devtools.ksp.symbol.KSClassDeclaration import com.google.devtools.ksp.symbol.KSPropertyDeclaration import com.google.devtools.ksp.symbol.KSType -import com.google.devtools.ksp.symbol.KSTypeAlias import java.io.Writer +/** + * The placeholder of the type of a converted column in the CREATE statement, `\u0001index\u0002collation\u0001`, which + * the table computes from the serializer at the element index, and checks to be text if it has the collation. A + * placeholder contains none of the characters a Kotlin string literal escapes. + */ +internal val CONVERTED_TYPE = Regex("\u0001(\\d+)\u0002([A-Z]*)\u0001") + +private fun convertedType(elementIndex: Int, collation: String?) = "\u0001$elementIndex\u0002${collation.orEmpty()}\u0001" + /** * Parser for column constraint annotations during CREATE TABLE statement generation. * @@ -49,6 +57,7 @@ import java.io.Writer * * #### Collation * - **[@CollateNoCase][com.ctrip.sqllin.dsl.annotation.CollateNoCase]**: Case-insensitive text comparison (for String/Char only) + * - **[@CollateRTrim][com.ctrip.sqllin.dsl.annotation.CollateRTrim]**: Text comparison ignoring trailing spaces (for String/Char only) * * ### Example Usage * ```kotlin @@ -71,7 +80,7 @@ import java.io.Writer * to assign, while a non-null `Long` or a key of any other type is supplied by the caller * - Only one [@PrimaryKey] annotation allowed per table * - AUTOINCREMENT requires a `Long?` key, the only kind of key the database assigns - * - [@CollateNoCase] can only be applied to String or Char properties + * - [@CollateNoCase] and [@CollateRTrim] can only be applied to String or Char properties, and not both to one * - [@CompositePrimaryKey] properties must be non-nullable * - [@CompositePrimaryKey] needs at least two properties; a single-column key uses [@PrimaryKey] * @@ -84,6 +93,7 @@ import java.io.Writer * @see com.ctrip.sqllin.dsl.annotation.Unique * @see com.ctrip.sqllin.dsl.annotation.CompositeUnique * @see com.ctrip.sqllin.dsl.annotation.CollateNoCase + * @see com.ctrip.sqllin.dsl.annotation.CollateRTrim */ class ColumnConstraintParser(resolver: Resolver) { @@ -93,6 +103,7 @@ class ColumnConstraintParser(resolver: Resolver) { const val ANNOTATION_UNIQUE = "com.ctrip.sqllin.dsl.annotation.Unique" const val ANNOTATION_COMPOSITE_UNIQUE = "com.ctrip.sqllin.dsl.annotation.CompositeUnique" const val ANNOTATION_NO_CASE = "com.ctrip.sqllin.dsl.annotation.CollateNoCase" + const val ANNOTATION_RTRIM = "com.ctrip.sqllin.dsl.annotation.CollateRTrim" const val PROMPT_CANT_ADD_BOTH_ANNOTATION = "You can't add both @PrimaryKey and @CompositePrimaryKey to the same property." const val PROMPT_PRIMARY_KEY_MUST_NOT_NULL = "The primary key must be not-null." @@ -101,11 +112,14 @@ class ColumnConstraintParser(resolver: Resolver) { const val PROMPT_COMPOSITE_PRIMARY_KEY_SINGLE_COLUMN = "A composite primary key needs at least two columns. Use @PrimaryKey for a single-column primary key, such as `@PrimaryKey val id: Long` for a numeric key you supply yourself." const val PROMPT_PRIMARY_KEY_USE_COUNT = "You only could use PrimaryKey to annotate one property in a class." const val PROMPT_NO_CASE_MUST_FOR_TEXT = "You only could add annotation @CollateNoCase for a String or Char typed property." + const val PROMPT_RTRIM_MUST_FOR_TEXT = "You only could add annotation @CollateRTrim for a String or Char typed property." + const val PROMPT_ONE_COLLATION = "A column has one collation, so a property can't have both @CollateNoCase and @CollateRTrim." } private val primaryKeyAnnotationName = resolver.getClassDeclarationByName(ANNOTATION_PRIMARY_KEY)!!.asStarProjectedType() private val compositePrimaryKeyName = resolver.getClassDeclarationByName(ANNOTATION_COMPOSITE_PRIMARY_KEY)!!.asStarProjectedType() private val noCaseAnnotationName = resolver.getClassDeclarationByName(ANNOTATION_NO_CASE)!!.asStarProjectedType() + private val rTrimAnnotationName = resolver.getClassDeclarationByName(ANNOTATION_RTRIM)!!.asStarProjectedType() private val uniqueAnnotationName = resolver.getClassDeclarationByName(ANNOTATION_UNIQUE)!!.asStarProjectedType() // Primary key tracking for metadata generation @@ -178,12 +192,18 @@ class ColumnConstraintParser(resolver: Resolver) { * // Later appended: ,UNIQUE(email,phone),UNIQUE(email,username) * ``` * + * #### Converted Type + * ```kotlin + * val id: Uuid + * // Generated: id ${columnType(0)} NOT NULL, the type the serializer stores, TEXT for Uuid + * ``` + * * ### Processing Order * 1. Determine SQLite type via [getSQLiteType] * 2. Apply PRIMARY KEY constraint if [@PrimaryKey] present * 3. Collect [@CompositePrimaryKey] columns for table-level constraint * 4. Apply NOT NULL to every non-nullable column except a rowid alias, primary key columns included - * 5. Apply COLLATE NOCASE if [@CollateNoCase] present + * 5. Apply COLLATE NOCASE if [@CollateNoCase] present, or COLLATE RTRIM if [@CollateRTrim] is * 6. Apply UNIQUE if [@Unique] present * 7. Collect [@CompositeUnique] groups for table-level constraints * @@ -198,6 +218,9 @@ class ColumnConstraintParser(resolver: Resolver) { * @param property The property declaration to process * @param propertyName The name of the database column (may differ from property name) * @param isNotNull Whether the property type is non-nullable in Kotlin + * @param columnType What the property's column holds + * @param elementIndex The index of the property in the serializer's descriptor, which a converted column's type is + * computed from * * @throws IllegalArgumentException if validation fails (see class-level documentation for rules) * @@ -210,16 +233,29 @@ class ColumnConstraintParser(resolver: Resolver) { property: KSPropertyDeclaration, propertyName: String, isNotNull: Boolean, + columnType: ColumnType, + elementIndex: Int, ) { // Collect the information of the primary key(s). val annotationKSType = property.annotations.map { it.annotationType.resolve() } val isPrimaryKey = annotationKSType.any { it.isAssignableFrom(primaryKeyAnnotationName) } with(createSQLBuilder) { - val type = getSQLiteType(property, isPrimaryKey) + val isNoCase = annotationKSType.any { it.isAssignableFrom(noCaseAnnotationName) } + val isRTrim = annotationKSType.any { it.isAssignableFrom(rTrimAnnotationName) } + check(!(isNoCase && isRTrim)) { PROMPT_ONE_COLLATION } + + // The type of a converted column is the one its serializer stores, which the statement computes, and checks + // to be text if the column has a collation + val isConverted = columnType is ColumnType.Converted + val type = if (isConverted) + " " + convertedType(elementIndex, if (isNoCase) "NOCASE" else if (isRTrim) "RTRIM" else null) + else + getSQLiteType(columnType, isPrimaryKey) append(type) - // Only a Long @PrimaryKey becomes `INTEGER PRIMARY KEY`, an alias of SQLite's rowid + // Only a Long @PrimaryKey becomes `INTEGER PRIMARY KEY`, an alias of SQLite's rowid, which a converted + // column never is, as its type isn't known before it is created val isRowIdAlias = isPrimaryKey && type == " INTEGER" // Handle @PrimaryKey annotation @@ -256,11 +292,16 @@ class ColumnConstraintParser(resolver: Resolver) { if (isNotNull && !isRowIdAlias) append(" NOT NULL") - // Handle @CollateNoCase annotation - must be on text columns - if (annotationKSType.any { it.isAssignableFrom(noCaseAnnotationName) }) { - check(type == " TEXT" || type == " CHAR(1)") { PROMPT_NO_CASE_MUST_FOR_TEXT } + // Handle @CollateNoCase and @CollateRTrim annotations - must be on text columns, which have one collation + val isText = isConverted || type == " TEXT" || type == " CHAR(1)" + if (isNoCase) { + check(isText) { PROMPT_NO_CASE_MUST_FOR_TEXT } append(" COLLATE NOCASE") } + if (isRTrim) { + check(isText) { PROMPT_RTRIM_MUST_FOR_TEXT } + append(" COLLATE RTRIM") + } // Handle @Unique annotation - single column uniqueness if (annotationKSType.any { it.isAssignableFrom(uniqueAnnotationName) }) { @@ -455,16 +496,12 @@ class ColumnConstraintParser(resolver: Resolver) { } /** - * Determines the SQLite type declaration for a given property. - * - * This function resolves the Kotlin type of a property to its corresponding SQLite type - * string, handling type aliases and enum classes. The result is used in compile-time - * CREATE TABLE statement generation. + * Determines the SQLite type declaration of a column of a basic type, or of an enum, which a converted column's + * type, computed from its serializer, isn't. * * ### Type Resolution Strategy - * 1. **Type Aliases**: Resolves to the underlying type, then maps to SQLite type - * 2. **Enum Classes**: Maps to SQLite INT type (enums are stored as ordinals) - * 3. **Standard Types**: Direct mapping via [FullNameCache.getSQLTypeName] + * 1. **Enum Classes**: Maps to SQLite INT type (enums are stored as ordinals) + * 2. **Basic Types**: Direct mapping via [FullNameCache.getSQLTypeName], which a type alias of one is too * * ### Primary Key Special Handling * When `isPrimaryKey` is true and the property is of type [Long], the function returns @@ -484,28 +521,16 @@ class ColumnConstraintParser(resolver: Resolver) { * val status: Status // → " INT" * ``` * - * @param property The KSP property declaration to analyze + * @param columnType What the column holds * @param isPrimaryKey Whether this property is annotated with [@PrimaryKey] * @return SQLite type declaration string with leading space (e.g., " INT", " TEXT") * @throws IllegalStateException if the property type is not supported by SQLlin * * @see FullNameCache.getSQLTypeName */ - private fun getSQLiteType(property: KSPropertyDeclaration, isPrimaryKey: Boolean): String { - val declaration = property.type.resolve().declaration - return when (declaration) { - is KSTypeAlias -> { - val realDeclaration = declaration.type.resolve().declaration - FullNameCache.getSQLTypeName(realDeclaration.typeName, isPrimaryKey) ?: kotlin.run { - if (realDeclaration is KSClassDeclaration && realDeclaration.classKind == ClassKind.ENUM_CLASS) - FullNameCache.getSQLTypeName(FullNameCache.INT, isPrimaryKey) - else - null - } - } - is KSClassDeclaration if declaration.classKind == ClassKind.ENUM_CLASS -> - FullNameCache.getSQLTypeName(FullNameCache.INT, isPrimaryKey) - else -> FullNameCache.getSQLTypeName(declaration.typeName, isPrimaryKey) - } ?: throw IllegalStateException("Hasn't support the type '${declaration.typeName}' yet") - } -} \ No newline at end of file + private fun getSQLiteType(columnType: ColumnType, isPrimaryKey: Boolean): String = when (columnType) { + is ColumnType.Basic -> FullNameCache.getSQLTypeName(columnType.typeName, isPrimaryKey) + is ColumnType.DefaultEnum -> FullNameCache.getSQLTypeName(FullNameCache.INT, isPrimaryKey) + is ColumnType.Converted, is ColumnType.Unsupported -> null + } ?: throw IllegalStateException("Hasn't support the type '$columnType' yet") +} diff --git a/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ColumnType.kt b/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ColumnType.kt new file mode 100644 index 00000000..e11d4eff --- /dev/null +++ b/sqllin-processor/src/main/kotlin/com/ctrip/sqllin/processor/ColumnType.kt @@ -0,0 +1,236 @@ +/* + * Copyright (C) 2026 Ctrip.com. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.ctrip.sqllin.processor + +import com.google.devtools.ksp.getAllSuperTypes +import com.google.devtools.ksp.getConstructors +import com.google.devtools.ksp.getVisibility +import com.google.devtools.ksp.symbol.ClassKind +import com.google.devtools.ksp.symbol.KSAnnotation +import com.google.devtools.ksp.symbol.KSClassDeclaration +import com.google.devtools.ksp.symbol.KSFile +import com.google.devtools.ksp.symbol.KSPropertyDeclaration +import com.google.devtools.ksp.symbol.KSType +import com.google.devtools.ksp.symbol.KSTypeAlias +import com.google.devtools.ksp.symbol.Modifier +import com.google.devtools.ksp.symbol.Variance +import com.google.devtools.ksp.symbol.Visibility + +/** + * What the column of a property of a `@DBRow` or `@DBView` class holds, as the serializer that kotlinx.serialization + * writes the property with stores it. + * + * SQLlin maps a property of a basic type, or of an enum class, with its default serializer, to a column of its own, + * whose type is known when the table is generated. Any other serializer converts the values: the column holds what it + * encodes, and the column's element converts the values given to its conditions with it, so that they compare what is + * stored. + * + * @author Yuang Qiao + */ +sealed interface ColumnType { + + /** + * A property of a basic type with its default serializer: a number, Boolean, Char, String or ByteArray. + * + * @property typeName The qualified name of the type, as `kotlin.Int` + */ + data class Basic(val typeName: String) : ColumnType + + /** + * A property of an enum class with its default serializer, which stores the ordinal of an entry. + */ + data class DefaultEnum(val declaration: KSClassDeclaration) : ColumnType + + /** + * A property whose serializer converts its values to those of a column. + * + * @property typeName The type, with qualified names, as `kotlin.uuid.Uuid` or `kotlin.collections.List` + * @property serializer The Kotlin expression of the serializer, as `com.example.EpochMillisSerializer` + */ + data class Converted(val typeName: String, val serializer: String) : ColumnType + + /** + * A property that no column can hold, for [reason], which completes a sentence about the property. + */ + data class Unsupported(val reason: String) : ColumnType +} + +/** + * Finds the [ColumnType] of a property, through the serializer that the kotlinx.serialization plugin writes it with, + * which it looks for as the plugin does, first found first: + * 1. `@Serializable(with = ...)` on the property; + * 2. `@Contextual` on the property; + * 3. `@Serializable(with = ...)` on the use of its type, directly or in the type alias it is declared with; + * 4. a serializer of its type in the `@file:UseSerializers` of the class's file; + * 5. `@Contextual` on the use of its type, or its type in the `@file:UseContextualSerialization` of the file; + * 6. the serializer of its type: the default of a basic type or an enum class, or that of a class that declares one with + * `@Serializable(with = ...)`, of a value class, or one of the built-in serializers of `Uuid`, `Instant` and + * `Duration`. + * + * A contextual serializer is the one the encoder's `SerializersModule` gives, and SQLlin's has none, so it is the + * default serializer of the type, which only a basic type and an enum class without a serializer of its own can have + * here: any other serializer is converting, and its column's type is computed from it, which a contextual one doesn't + * describe. + * + * @author Yuang Qiao + */ +object ColumnTypes { + + private const val SERIALIZABLE = "kotlinx.serialization.Serializable" + private const val CONTEXTUAL = "kotlinx.serialization.Contextual" + private const val USE_SERIALIZERS = "kotlinx.serialization.UseSerializers" + private const val USE_CONTEXTUAL_SERIALIZATION = "kotlinx.serialization.UseContextualSerialization" + private const val K_SERIALIZER = "kotlinx.serialization.KSerializer" + + /** The types whose serializers kotlinx.serialization has built in, which encode them as strings. */ + private val BUILT_IN_SERIALIZED = setOf("kotlin.uuid.Uuid", "kotlin.time.Instant", "kotlin.time.Duration") + + private val BASIC_TYPES = with(FullNameCache) { + setOf(BYTE, SHORT, INT, LONG, UBYTE, USHORT, UINT, ULONG, FLOAT, DOUBLE, BOOLEAN, CHAR, STRING, BYTE_ARRAY) + } + + private val KSAnnotation.qualifiedName: String? + get() = annotationType.resolve().declaration.qualifiedName?.asString() + + /** + * The serializer that `@Serializable(with = ...)` gives, or null for `@Serializable` without one, whose default + * `with` is `KSerializer` itself, or another annotation. + */ + private fun KSAnnotation.serializerWith(): KSType? { + if (qualifiedName != SERIALIZABLE) + return null + val with = arguments.firstOrNull { it.name?.asString() == "with" }?.value as? KSType ?: return null + return with.takeIf { it.declaration.qualifiedName?.asString() != K_SERIALIZER } + } + + private fun Sequence.serializerWith(): KSType? = firstNotNullOfOrNull { it.serializerWith() } + + private fun Sequence.isContextual(): Boolean = any { it.qualifiedName == CONTEXTUAL } + + /** + * The classes that the arguments of the annotations [name] of [file] give, as the serializers of + * `@file:UseSerializers(...)`. + */ + private fun classesOf(file: KSFile?, name: String): List = + file?.annotations.orEmpty() + .filter { it.qualifiedName == name } + .flatMap { annotation -> annotation.arguments.flatMap { (it.value as? List<*>).orEmpty() } } + .mapNotNull { (it as? KSType)?.declaration as? KSClassDeclaration } + .toList() + + /** + * Returns the [ColumnType] of [property], declared in [file]. + */ + fun of(property: KSPropertyDeclaration, file: KSFile?): ColumnType { + // The type, through its type aliases, and the annotations of its uses, the outermost first + var type = property.type.resolve() + val typeAnnotations = ArrayList() + typeAnnotations += property.type.annotations + typeAnnotations += type.annotations + while (true) { + val alias = type.declaration as? KSTypeAlias ?: break + typeAnnotations += alias.type.annotations + type = alias.type.resolve() + typeAnnotations += type.annotations + } + val declaration = type.declaration as? KSClassDeclaration + ?: return ColumnType.Unsupported("has the type '$type', which is a type parameter, of which no serializer is known") + val className = declaration.qualifiedName?.asString() + ?: return ColumnType.Unsupported("has the type '$type', which has no qualified name") + // The type with its arguments, as `kotlin.collections.List`, which the column's element has + val typeName = type.makeNotNullable().qualifiedString() + + property.annotations.serializerWith()?.let { return converted(typeName, it) } + var isContextual = property.annotations.isContextual() + if (!isContextual) { + typeAnnotations.asSequence().serializerWith()?.let { return converted(typeName, it) } + classesOf(file, USE_SERIALIZERS).firstOrNull { serializedTypeName(it) == className }?.let { + return converted(typeName, it.asStarProjectedType()) + } + isContextual = typeAnnotations.asSequence().isContextual() || + classesOf(file, USE_CONTEXTUAL_SERIALIZATION).any { it.qualifiedName?.asString() == className } + } + + val classSerializer = declaration.annotations.serializerWith() + return when { + className in BASIC_TYPES -> ColumnType.Basic(className) + declaration.classKind == ClassKind.ENUM_CLASS && classSerializer == null -> ColumnType.DefaultEnum(declaration) + isContextual -> ColumnType.Unsupported( + "is serialized contextually, with @Contextual or @UseContextualSerialization, while SQLlin has no SerializersModule to find its serializer in. " + + "Give it its serializer with @Serializable(with = ...) on the property" + ) + classSerializer != null + || Modifier.VALUE in declaration.modifiers || Modifier.INLINE in declaration.modifiers + || className in BUILT_IN_SERIALIZED -> ColumnType.Converted(typeName, "kotlinx.serialization.serializer<$typeName>()") + else -> ColumnType.Unsupported( + "has the type '$type', which no column can hold. A column holds Byte, Short, Int, Long, Float, Double and their unsigned variants, Boolean, Char, String, " + + "ByteArray, an enum class, or a type whose serializer encodes it as one of these: Uuid, Instant or Duration, a value class, or a type given a serializer with " + + "@Serializable(with = ...) on the property, the use of the type or its class, or by @file:UseSerializers. A collection, or a class serialized as a structure, needs a serializer that " + + "encodes it as one value, as JSON in a string. To keep the property out of the table, annotate it with @kotlinx.serialization.Transient" + ) + } + } + + /** + * The column of a property of [typeName] whose serializer is [serializer], created as the plugin creates it: an object + * as it is, and a class with its constructor without arguments. + */ + private fun converted(typeName: String, serializer: KSType): ColumnType { + val declaration = serializer.declaration as? KSClassDeclaration + ?: return ColumnType.Unsupported("has the serializer '$serializer', which isn't a class") + val name = declaration.qualifiedName?.asString() + ?: return ColumnType.Unsupported("has the serializer '$serializer', which has no qualified name") + val visibility = declaration.getVisibility() + if (visibility == Visibility.PRIVATE || visibility == Visibility.LOCAL) + return ColumnType.Unsupported("has the serializer '$name', which is ${visibility.name.lowercase()}, so that the table generated for it can't use it. Make it internal or public") + val expression = when { + declaration.classKind == ClassKind.OBJECT -> name + declaration.getConstructors().none() || declaration.getConstructors().any { constructor -> constructor.parameters.all { it.hasDefault } } -> "$name()" + else -> return ColumnType.Unsupported("has the serializer '$name', a class without a constructor that takes no arguments, which the table generated for it creates it with") + } + return ColumnType.Converted(typeName, expression) + } + + /** + * This type as Kotlin code, with qualified names: its class, or type alias, its arguments, and whether it is + * nullable, as `kotlin.collections.Map`. + */ + private fun KSType.qualifiedString(): String = buildString { + append(declaration.qualifiedName?.asString() ?: declaration.simpleName.asString()) + if (arguments.isNotEmpty()) { + append(arguments.joinToString(prefix = "<", postfix = ">") { argument -> + val argumentType = argument.type?.resolve() + when { + argument.variance == Variance.STAR || argumentType == null -> "*" + argument.variance == Variance.COVARIANT -> "out ${argumentType.qualifiedString()}" + argument.variance == Variance.CONTRAVARIANT -> "in ${argumentType.qualifiedString()}" + else -> argumentType.qualifiedString() + } + }) + } + if (isMarkedNullable) + append('?') + } + + /** + * The qualified name of the type [serializer] serializes, the argument of its `KSerializer`. + */ + private fun serializedTypeName(serializer: KSClassDeclaration): String? = + serializer.getAllSuperTypes() + .firstOrNull { it.declaration.qualifiedName?.asString() == K_SERIALIZER } + ?.arguments?.firstOrNull()?.type?.resolve()?.declaration?.qualifiedName?.asString() +}