diff --git a/CHANGELOG.md b/CHANGELOG.md index cfcf2d3..5b06dda 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,11 +2,36 @@ ## v0.5.0 / 2024-11-29 -Because of [the Exposed SELECT DSL design changes](https://github.com/JetBrains/Exposed/pull/1916), and also because the old `DatabaseClient` creation APIs were poorly designed and too cumbersome, causing an additional cognitive burden on the users, this release has been completely overhauled. Some old APIs are removed directly because deprecating and delegating them to new ones fills the code base with unused code. Therefore, this release is not source-compatible or binary-compatible with v0.4.0. We are sorry for the inconvenience. From this version on, we will try to maintain source and binary compatibility, deprecating APIs instead of removing them in the foreseeable future. +Because of [the Exposed SELECT DSL design changes](https://github.com/JetBrains/Exposed/pull/1916), and also because the old `DatabaseClient` creation APIs were poorly designed and too cumbersome, causing additional cognitive burdens on the users, this release has been completely overhauled. Some old APIs are removed directly because deprecating and delegating them to new ones fills the code base with unused code. Therefore, this release is **not source-compatible or binary-compatible** with v0.4.0. Please do not update unless you have time to adapt to the refactored changes. We are sorry for the inconvenience. From this version on, we will try to maintain source and binary compatibility, deprecating APIs instead of removing them in the foreseeable future. + +Please check out the [updated README](README.md) to upgrade to v0.5.0. Functional changes: -* ... +* adapt to [the Exposed SELECT DSL design changes](https://github.com/JetBrains/Exposed/pull/1916) (resolve #8) +* rename the SQL DSL functions taking mapper parameters, adding "withMapper" prefixes (resolve #6) +* split the library into multiple modules including "core", "postgresql", "sql-dsl", and "sql-dsl-with-mapper" +* generalize the functions with the types `PgPool` and `PgConnection` to work with different RDBMSs, replacing them with `Pool` and `SqlConnection` +* get rid of all usages of `PgPool` which was deprecated in Vert.x 4.5 +* extract some new APIs and move some existing APIs into finer-grained subpackages, including `jdbc`, `exposed`, `vertx.sqlclient`, and `local` in the "core" module, and `postgresql` in the "postgresql" module +* overhaul the APIs related to the creation of Exposed `Database`s, Vert.x SQL clients, and `DatabaseClient`s + + * remove the `create...andSetRole` functions to create Vert.x SQL Clients, with their functionalities merged into the `create...` functions to create Vert.x SQL Clients + + * refactor the Exposed `Database` and Vert.x `SqlClient` creation APIs to be more configurable and straightforward + + * remove the extra shortcut `DatabaseClient` creation APIs such as `createPgPoolDatabaseClient` as they were poorly designed and too cumbersome, causing additional cognitive burdens on the users + + There are too many different combinations with different RDMBSs such as PostgreSQL and MySQL, and different Vert.x SQL Clients such as `SqlClient`, `Pool`, and `SqlConnection`. Therefore we don't provide such shortcut APIs anymore as they are just too cumbersome and cause additional cognitive burdens on the users, and we encourage the library users to create their own (see the updated guide in README.md for instructions). In this way, the Exposed `Databse`s and Vert.x SQL Clients are also more configurable. + +* adopt `EvscConfig` as the single-source-of-truth database client config and no longer prefer local connections + + `LocalConnectionConfig` should be converted to `EvscConfig` or `ConnectionConfig` to be used. + +* mark some APIs as experimental as they are subject to change +* make `DatabaseClient` implement our new `CoroutineAutoCloseable` interface +* add a version of `selectWithMapper` without `buildQuery` +* point out in the usage guide that you are encouraged to share/reuse an Exposed `Database` which generates SQLs among multiple `DatabaseClient`s in multiple verticles, which improves performance as shown in our benchmark results Miscellaneous changes: diff --git a/README.md b/README.md index 9b12cf6..a7d6a14 100644 --- a/README.md +++ b/README.md @@ -137,11 +137,11 @@ val updateRowCount = databaseClient.executeUpdate(Examples.updateStatement({ Examples.id eq 1 }) { it[name] = "AA" }) assert(updateRowCount == 1) -// The Exposed `Table` extension function `select` doesn't execute eagerly so it can be used directly. -val exampleName = databaseClient.executeQuery(Examples.select(Examples.name).where(Examples.id eq 1)) +// The Exposed `Table` extension function `select` doesn't execute eagerly so it can also be used directly. +val exampleName = databaseClient.executeQuery(Examples.selectStatement(Examples.name).where(Examples.id eq 1)) .single()[Examples.name] -databaseClient.executeSingleUpdate(Examples.deleteWhereStatement { Examples.id eq 1 }) // The function `deleteWhereStatement` still depends on the old DSL and will be updated. +databaseClient.executeSingleUpdate(Examples.deleteWhereStatement { id eq 1 }) databaseClient.executeSingleUpdate(Examples.deleteIgnoreWhereStatement { id eq 2 }) ``` @@ -165,7 +165,6 @@ val updateRowCount = databaseClient.update(Examples, { Examples.id eq 1 }) { it[ val exampleName1 = databaseClient.select(Examples) { select(Examples.name).where(Examples.id eq 1) }.single()[Examples.name] -// This function still depends on the old SELECT DSL and will be updated. val exampleName2 = databaseClient.selectSingleColumn(Examples, Examples.name) { where(Examples.id eq 2) }.single() @@ -204,7 +203,7 @@ val filmWithDirectorId = FilmWithDirectorId(filmId, episodeIIFilmDetails) databaseClient.insertWithMapper(Films, filmWithDirectorId, Mappers.filmWithDirectorId) // insert with the ID val fullFilms = databaseClient.selectWithMapper(filmsLeftJoinDirectors, Mappers.fullFilm) { - where(Films.filmId inList listOf(1, 2)) // This API still depends on the old SELECT DSL and will be refactored. + where(Films.filmId inList listOf(1, 2)) } ``` diff --git a/integrated/src/main/kotlin/com/huanshankeji/exposedvertxsqlclient/Examples.kt b/integrated/src/main/kotlin/com/huanshankeji/exposedvertxsqlclient/Examples.kt index f0450e1..b57a5e0 100644 --- a/integrated/src/main/kotlin/com/huanshankeji/exposedvertxsqlclient/Examples.kt +++ b/integrated/src/main/kotlin/com/huanshankeji/exposedvertxsqlclient/Examples.kt @@ -70,11 +70,11 @@ suspend fun examples(vertx: Vertx) { databaseClient.executeUpdate(Examples.updateStatement({ Examples.id eq 1 }) { it[name] = "AA" }) assert(updateRowCount == 1) - // The Exposed `Table` extension function `select` doesn't execute eagerly so it can be used directly. - val exampleName = databaseClient.executeQuery(Examples.select(Examples.name).where(Examples.id eq 1)) + // The Exposed `Table` extension function `select` doesn't execute eagerly so it can also be used directly. + val exampleName = databaseClient.executeQuery(Examples.selectStatement(Examples.name).where(Examples.id eq 1)) .single()[Examples.name] - databaseClient.executeSingleUpdate(Examples.deleteWhereStatement { Examples.id eq 1 }) // The function `deleteWhereStatement` still depends on the old DSL and will be updated. + databaseClient.executeSingleUpdate(Examples.deleteWhereStatement { id eq 1 }) databaseClient.executeSingleUpdate(Examples.deleteIgnoreWhereStatement { id eq 2 }) } @@ -86,7 +86,6 @@ suspend fun examples(vertx: Vertx) { val exampleName1 = databaseClient.select(Examples) { select(Examples.name).where(Examples.id eq 1) }.single()[Examples.name] - // This function still depends on the old SELECT DSL and will be updated. val exampleName2 = databaseClient.selectSingleColumn(Examples, Examples.name) { where(Examples.id eq 2) }.single() diff --git a/integrated/src/main/kotlin/com/huanshankeji/exposedvertxsqlclient/MappingExamples.kt b/integrated/src/main/kotlin/com/huanshankeji/exposedvertxsqlclient/MappingExamples.kt index 24dac9b..fff5da1 100644 --- a/integrated/src/main/kotlin/com/huanshankeji/exposedvertxsqlclient/MappingExamples.kt +++ b/integrated/src/main/kotlin/com/huanshankeji/exposedvertxsqlclient/MappingExamples.kt @@ -95,6 +95,6 @@ suspend fun mappingExamples(databaseClient: DatabaseClient) { databaseClient.insertWithMapper(Films, filmWithDirectorId, Mappers.filmWithDirectorId) // insert with the ID val fullFilms = databaseClient.selectWithMapper(filmsLeftJoinDirectors, Mappers.fullFilm) { - where(Films.filmId inList listOf(1, 2)) // This API still depends on the old SELECT DSL and will be refactored. + where(Films.filmId inList listOf(1, 2)) } }