Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
f05b95c
Remove the joins written as clauses of SELECT, and start joins from a…
qiaoyuang Oct 29, 2026
0d8efdc
Remove the deprecated UNION {} block
qiaoyuang Oct 29, 2026
113cd45
Add table version tokens, versioned, awaitChange and onChange (F66)
qiaoyuang Oct 30, 2026
c432843
Add the other conflict resolutions, INSERT OR ABORT and the others (F23)
qiaoyuang Oct 30, 2026
5f7f480
Add choosing how a transaction begins, DEFERRED, IMMEDIATE or EXCLUSI…
qiaoyuang Oct 30, 2026
15175d0
Add INDEXED BY and NOT INDEXED (F26)
qiaoyuang Oct 30, 2026
087341f
Update AGP to 9.5.0, kotlinx.serialization to 1.12.0 and sqlite-jdbc …
qiaoyuang Oct 30, 2026
8a328d5
Build the processor for JDK 21, its Kotlin classes included (B9)
qiaoyuang Nov 5, 2026
36a5269
Add EXPLAIN QUERY PLAN (F29)
qiaoyuang Nov 5, 2026
01a6171
Append a clause to the statement it completes, not to the last one (B10)
qiaoyuang Nov 5, 2026
59b86cd
Keep the statements after an inner transaction in the outer one (B11)
qiaoyuang Nov 6, 2026
63628a4
Drop @Volatile from DatabaseScope, and say a scope isn't thread-safe
qiaoyuang Nov 6, 2026
8e755ea
Add the PRAGMAs that check the database and read its schema (F30, par…
qiaoyuang Nov 6, 2026
12fbbbf
Run the PRAGMAs that set how a connection runs statements on every co…
qiaoyuang Nov 6, 2026
ae7a9ec
Add the rest of the PRAGMAs (F30, part 2)
qiaoyuang Nov 6, 2026
517491e
Read the row of the PRAGMA that sets the journal mode (B13)
qiaoyuang Nov 6, 2026
340797b
Shelve incremental_vacuum as F68, and say what keeps it out
qiaoyuang Nov 6, 2026
1698c80
Say in the guide that a schema PRAGMA may miss what another connectio…
qiaoyuang Nov 7, 2026
63eb2eb
Add @CollateRTrim, and COLLATE on the columns of an index (F19)
qiaoyuang Nov 7, 2026
5ae53ce
Add ORDER BY, LIMIT and OFFSET to DELETE and UPDATE (F25)
qiaoyuang Nov 7, 2026
8dd6317
Add sqllin-dsl-paging, a PagingSource of the DSL's queries (F13)
qiaoyuang Nov 7, 2026
e617d73
Add columns converted by their serializers (F12), fixing B14
qiaoyuang Nov 8, 2026
21da315
Opt in to the markers an entity propagates, in its generated table (B15)
qiaoyuang Nov 8, 2026
f454e0a
Shelve PRAGMA data_version as F69
qiaoyuang Nov 8, 2026
691685c
Read the rows of a SELECT when its scope runs it (B16)
qiaoyuang Nov 8, 2026
de0df18
Upload the test reports of sqllin-dsl-test in CI
qiaoyuang Nov 8, 2026
22f8e62
Update AGP to 9.5.1 and Gradle to 9.9.0
qiaoyuang Nov 8, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:
Expand Down Expand Up @@ -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

Expand All @@ -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:
Expand Down Expand Up @@ -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

Expand All @@ -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:
Expand All @@ -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
Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
42 changes: 42 additions & 0 deletions CHANGELOG.md

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
1 change: 1 addition & 0 deletions README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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_:

Expand Down
35 changes: 20 additions & 15 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<R>(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

Expand All @@ -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<R>(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 ✅)
Expand Down
10 changes: 7 additions & 3 deletions gradle/libs.versions.toml
Original file line number Diff line number Diff line change
@@ -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]

Expand All @@ -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" }
Expand Down
2 changes: 1 addition & 1 deletion gradle/wrapper/gradle-wrapper.properties
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions publish_all.sh
Original file line number Diff line number Diff line change
@@ -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
24 changes: 9 additions & 15 deletions sample/src/commonMain/kotlin/com/ctrip/sqllin/sample/Sample.kt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -78,29 +80,21 @@ object Sample {

}

@OptIn(ExperimentalDSLDatabaseAPI::class)
fun joinSample() {
db {
PersonTable { table ->
table SELECT CROSS_JOIN<Student>(TranscriptTable)
table SELECT INNER_JOIN<Student>(TranscriptTable) USING name
table SELECT NATURAL_JOIN<Student>(TranscriptTable)
table SELECT LEFT_OUTER_JOIN<Student>(TranscriptTable) USING name
table SELECT NATURAL_LEFT_OUTER_JOIN<Student>(TranscriptTable)
}
(PersonTable INNER_JOIN TranscriptTable USING PersonTable.name) SELECT X<Student>()
(PersonTable NATURAL_JOIN TranscriptTable) SELECT X<Student>()
}
}

@OptIn(ExperimentalDSLDatabaseAPI::class)
fun concurrentSafeCall() {
CoroutineScope(Dispatchers.Default).launch {
db suspendedScope {
PersonTable { table ->
table SELECT CROSS_JOIN<Student>(TranscriptTable)
table SELECT INNER_JOIN<Student>(TranscriptTable) USING name
delay(100)
table SELECT NATURAL_JOIN<Student>(TranscriptTable)
table SELECT LEFT_OUTER_JOIN<Student>(TranscriptTable) USING name
table SELECT NATURAL_LEFT_OUTER_JOIN<Student>(TranscriptTable)
}
(PersonTable INNER_JOIN TranscriptTable USING PersonTable.name) SELECT X<Student>()
delay(100)
(PersonTable NATURAL_JOIN TranscriptTable) SELECT X<Student>()
}
}
}
Expand Down
1 change: 1 addition & 0 deletions settings.gradle.kts
Original file line number Diff line number Diff line change
@@ -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")
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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()

Expand Down
Loading
Loading