Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update "Upgrading to 2.0" docs to mention sourceFolders update and Android-only projects #5292

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
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
61 changes: 47 additions & 14 deletions docs/upgrading-2.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

SQLDelight 2.0 makes some breaking changes to the gradle plugin and runtime APIs.

This page lists those breaking changes and their new 2.0 equivalents.
This page lists those breaking changes and their new 2.0 equivalents.
For a full list of new features and other changes, see the [changelog](../changelog).

## New Package Name and Artifact Group
Expand All @@ -19,6 +19,14 @@ dependencies {
- implementation("com.squareup.sqldelight:sqlite-driver:{{ versions.sqldelight }}")
+ implementation("app.cash.sqldelight:sqlite-driver:{{ versions.sqldelight }}")
}

For pure-Android SqlDelight 1.x projects, use android-driver and coroutine-extensions-jvm:
dependencies {
- implementation("com.squareup.sqldelight:android-driver:{{ versions.sqldelight }}")
+ implementation("app.cash.sqldelight:android-driver:{{ versions.sqldelight }}")
- implementation("com.squareup.sqldelight:coroutines-extensions:{{ versions.sqldelight }}")
+ implementation("app.cash.sqldelight:coroutines-extensions-jvm:{{ versions.sqldelight }}")
}
```

```diff title="In Code"
Expand All @@ -32,7 +40,7 @@ dependencies {
* The SQLDelight configuration API now uses managed properties and a `DomainObjectCollection` for the databases.

=== "Kotlin"
```kotlin
```kotlin
sqldelight {
databases { // (1)!
create("Database") {
Expand All @@ -41,7 +49,7 @@ dependencies {
}
}
```

1. New `DomainObjectCollection` wrapper.
2. Now a `Property<String>`.
=== "Groovy"
Expand All @@ -54,9 +62,34 @@ dependencies {
}
}
```

1. New `DomainObjectCollection` wrapper.

* The sourceFolders setting has been renamed srcDirs

=== "Kotlin"
```groovy
sqldelight {
databases {
create("MyDatabase") {
packageName.set("com.example")
srcDirs.setFrom("src/main/sqldelight")
}
}
}
```
=== "Groovy"
```groovy
sqldelight {
databases {
MyDatabase {
packageName = "com.example"
srcDirs = ['src/main/sqldelight']
}
}
}
```

* The SQL dialect of your database is now specified using a Gradle dependency.

=== "Kotlin"
Expand All @@ -66,11 +99,11 @@ dependencies {
create("MyDatabase") {
packageName.set("com.example")
dialect("app.cash.sqldelight:mysql-dialect:{{ versions.sqldelight }}")

// Version catalogs also work!
dialect(libs.sqldelight.dialects.mysql)
}
}
}
}
}
```
=== "Groovy"
Expand All @@ -80,14 +113,14 @@ dependencies {
MyDatabase {
packageName = "com.example"
dialect "app.cash.sqldelight:mysql-dialect:{{ versions.sqldelight }}"

// Version catalogs also work!
dialect libs.sqldelight.dialects.mysql
}
}
}
}
}
```

The currently supported dialects are `mysql-dialect`, `postgresql-dialect`, `hsql-dialect`, `sqlite-3-18-dialect`, `sqlite-3-24-dialect`, `sqlite-3-25-dialect`, `sqlite-3-30-dialect`, `sqlite-3-35-dialect`, and `sqlite-3-38-dialect`

## Runtime Changes
Expand All @@ -96,7 +129,7 @@ dependencies {

```diff
+{++import kotlin.Boolean;++}

CREATE TABLE HockeyPlayer (
name TEXT NOT NULL,
good INTEGER {==AS Boolean==}
Expand Down Expand Up @@ -128,7 +161,7 @@ dependencies {
-val schema: {--SqlDriver.Schema--}
+val schema: {++SqlSchema++}
```

* The [paging3 extension API](../2.x/extensions/androidx-paging3/app.cash.sqldelight.paging3/) has changed to only allow int types for the count.
* The [coroutines extension API](../2.x/extensions/coroutines-extensions/app.cash.sqldelight.coroutines/) now requires a dispatcher to be explicitly passed in.
```diff
Expand All @@ -146,4 +179,4 @@ dependencies {
* The [`next()`](../2.x/runtime/app.cash.sqldelight.db/-sql-cursor/next) method on the `SqlCursor` interface has also been changed to return a `QueryResult` to enable better cursor support for asynchronous drivers.
* The [`SqlSchema`](../2.x/runtime/app.cash.sqldelight.db/-sql-schema) interface now has a generic `QueryResult` type parameter. This is used to distinguish schema runtimes that were generated for use with asynchronous drivers, which may not be directly compatible with synchronous drivers.
This is only relevant for projects that are simultaneously using synchronous and asynchronous drivers together, like in a multiplatform project that has a JS target. See "[Multiplatform setup with the Web Worker Driver](js_sqlite/multiplatform.md)" for more details.
* The type of `SqlSchema.Version` changed from Int to Long to allow for server environments to leverage timestamps as version. Existing setups can safely cast between from Int and Long, and drivers that require an Int range for versions will crash before database creation for out of bounds versions.
* The type of `SqlSchema.Version` changed from Int to Long to allow for server environments to leverage timestamps as version. Existing setups can safely cast between from Int and Long, and drivers that require an Int range for versions will crash before database creation for out of bounds versions.