{"id":20821803,"url":"https://github.com/huanshankeji/exposed-vertx-sql-client","last_synced_at":"2025-05-07T16:25:18.758Z","repository":{"id":42132969,"uuid":"491117246","full_name":"huanshankeji/exposed-vertx-sql-client","owner":"huanshankeji","description":"Exposed on top of Vert.x Reactive SQL Client","archived":false,"fork":false,"pushed_at":"2025-03-15T10:21:22.000Z","size":561,"stargazers_count":5,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T11:51:12.688Z","etag":null,"topics":["jetbrains-exposed","kotlin","postgresql-client","vertx-sql-client"],"latest_commit_sha":null,"homepage":"https://huanshankeji.github.io/exposed-vertx-sql-client/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/huanshankeji.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-11T13:12:44.000Z","updated_at":"2025-03-15T10:21:28.000Z","dependencies_parsed_at":"2025-01-18T07:22:51.427Z","dependency_job_id":"dd813c04-994b-4606-a8fb-7a74d6b00cb9","html_url":"https://github.com/huanshankeji/exposed-vertx-sql-client","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huanshankeji%2Fexposed-vertx-sql-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huanshankeji%2Fexposed-vertx-sql-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huanshankeji%2Fexposed-vertx-sql-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huanshankeji%2Fexposed-vertx-sql-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/huanshankeji","download_url":"https://codeload.github.com/huanshankeji/exposed-vertx-sql-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252914036,"owners_count":21824300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jetbrains-exposed","kotlin","postgresql-client","vertx-sql-client"],"created_at":"2024-11-17T22:13:09.400Z","updated_at":"2025-05-07T16:25:18.750Z","avatar_url":"https://github.com/huanshankeji.png","language":"Kotlin","funding_links":[],"categories":["Database Clients"],"sub_categories":[],"readme":"# Exposed Vert.x SQL Client\n\n[![Maven Central](https://img.shields.io/maven-central/v/com.huanshankeji/exposed-vertx-sql-client-postgresql)](https://search.maven.org/artifact/com.huanshankeji/exposed-vertx-sql-client-postgresql)\n\n[Exposed](https://github.com/JetBrains/Exposed) on top of [Vert.x Reactive SQL Client](https://github.com/eclipse-vertx/vertx-sql-client)\n\n## Note\n\nOnly PostgreSQL with [Reactive PostgreSQL Client](https://vertx.io/docs/vertx-pg-client/java/) is currently supported.\n\n## Experimental\n\nThis library is experimental now. The APIs are subject to change (especially those marked with `@ExperimentalEvscApi`), the tests are incomplete, and please expect bugs and report them.\n\n## Add to your dependencies\n\n### The Maven coordinates\n\n```kotlin\n\"com.huanshankeji:exposed-vertx-sql-client-$module:$libraryVersion\"\n```\n\n### **Important note**\n\nAs Exposed is a library that has not reached stability yet and often has incompatible changes, you are recommended to stick to the same version of Exposed used by this library. The current version is v0.56.0.\n\n## API documentation\n\nSee the [hosted API documentation](https://huanshankeji.github.io/exposed-vertx-sql-client/) for the APIs.\n\n## Basic usage guide\n\nHere is a basic usage guide.\n\n### Before v0.5.0\n\nAdd the PostgreSQL module, which was the only module, to your dependencies with the Gradle build script:\n\n```kotlin\nimplementation(\"com.huanshankeji:exposed-vertx-sql-client-postgresql:$libraryVersion\")\n```\n\n### Since v0.5.0\n\nAdd the core module to your dependencies with the Gradle build script:\n\n```kotlin\nimplementation(\"com.huanshankeji:exposed-vertx-sql-client-core:$libraryVersion\")\n```\n\nAnd add an RDBMS module, for example, the PostgreSQL module:\n\n```kotlin\nimplementation(\"com.huanshankeji:exposed-vertx-sql-client-postgresql:$libraryVersion\")\n```\n\n### Create a `DatabaseClient`\n\nCreate an `EvscConfig` as the single source of truth:\n\n```kotlin\nval evscConfig = ConnectionConfig.Socket(\"localhost\", user = \"user\", password = \"password\", database = \"database\")\n    .toUniversalEvscConfig()\n```\n\nLocal alternative with Unix domain socket:\n\n```kotlin\nval evscConfig = defaultPostgresqlLocalConnectionConfig(\n    user = \"user\",\n    socketConnectionPassword = \"password\",\n    database = \"database\"\n).toPerformantUnixEvscConfig()\n```\n\nCreate an Exposed `Database` with the `ConnectionConfig.Socket`, which can be shared and reused in multiple `Verticle`s:\n\n```kotlin\nval exposedDatabase = evscConfig.exposedConnectionConfig.exposedDatabaseConnectPostgresql()\n```\n\nCreate a Vert.x `SqlClient` with the `ConnectionConfig`, preferably in a `Verticle`:\n\n```kotlin\nval sqlClient = createPgClient(vertx, evscConfig.vertxSqlClientConnectionConfig)\nval pool = createPgPool(vertx, evscConfig.vertxSqlClientConnectionConfig)\nval sqlConnection = createPgClient(vertx, evscConfig.vertxSqlClientConnectionConfig)\n```\n\nCreate a `Database` with the provided Vert.x `SqlClient` and Exposed `Database`, preferably in a `Verticle`:\n\n```kotlin\nval databaseClient = DatabaseClient(vertxSqlClient, exposedDatabase, PgDatabaseClientConfig())\n```\n\n### Example table definitions\n\n```kotlin\nobject Examples : IntIdTable(\"examples\") {\n    val name = varchar(\"name\", 64)\n}\n\nval tables = arrayOf(Examples)\n```\n\n### Use `exposedTransaction` to execute original blocking Exposed code\n\nFor example, to create tables:\n\n```kotlin\ndatabaseClient.exposedTransaction {\n    SchemaUtils.create(*tables)\n}\n```\n\nIf you execute blocking Exposed statements inside `Verticle`s or event loop threads that you shouldn't block, you should use Vert.x `Vertx.executeBlocking` or Coroutines `Dispatchers.IO`.\n\n### CRUD (DML and DQL) operations with `DatabaseClient`\n\n#### Core APIs\n\nWith these core APIs, you create and execute Exposed `Statement`s. You don't need to learn many new APIs, and the\n`Statement`s are more composable and easily editable. For example, you can move a query into an adapted subquery.\n\n```kotlin\n// The Exposed `Table` extension functions `insert`, `update`, and `delete` execute eagerly so `insertStatement`, `updateStatement`, `deleteStatement` have to be used.\n\nval insertRowCount = databaseClient.executeUpdate(Examples.insertStatement { it[name] = \"A\" })\nassert(insertRowCount == 1)\n// `executeSingleUpdate` function requires that there is only 1 row updated and returns `Unit`.\ndatabaseClient.executeSingleUpdate(Examples.insertStatement { it[name] = \"B\" })\n// `executeSingleOrNoUpdate` requires that there is 0 or 1 row updated and returns `Boolean`.\nval isInserted = databaseClient.executeSingleOrNoUpdate(Examples.insertIgnoreStatement { it[name] = \"B\" })\nassert(isInserted)\n\nval updateRowCount =\n    databaseClient.executeUpdate(Examples.updateStatement({ Examples.id eq 1 }) { it[name] = \"AA\" })\nassert(updateRowCount == 1)\n\n// The Exposed `Table` extension function `select` doesn't execute eagerly so it can also be used directly.\nval exampleName = databaseClient.executeQuery(Examples.selectStatement(Examples.name).where(Examples.id eq 1))\n    .single()[Examples.name]\n\ndatabaseClient.executeSingleUpdate(Examples.deleteWhereStatement { id eq 1 })\ndatabaseClient.executeSingleUpdate(Examples.deleteIgnoreWhereStatement { id eq 2 })\n```\n\n#### Extension SQL DSL APIs\n\nWith the extension SQL DSL APIs, your code becomes more concise, but it might be more difficult when you need to compose statements or edit the code.\n\nGradle dependency configuration (only needed since v0.5.0):\n\n```kotlin\nimplementation(\"com.huanshankeji:exposed-vertx-sql-client-sql-dsl:$libraryVersion\")\n```\n\nExample code:\n\n```kotlin\ndatabaseClient.insert(Examples) { it[name] = \"A\" }\nval isInserted = databaseClient.insertIgnore(Examples) { it[name] = \"B\" }\n\nval updateRowCount = databaseClient.update(Examples, { Examples.id eq 1 }) { it[name] = \"AA\" }\n\nval exampleName1 =\n    databaseClient.select(Examples) { select(Examples.name).where(Examples.id eq 1) }.single()[Examples.name]\nval exampleName2 =\n    databaseClient.selectSingleColumn(Examples, Examples.name) { where(Examples.id eq 2) }.single()\n\nval examplesExist = databaseClient.selectExpression(exists(Examples.selectAll()))\n\nval deleteRowCount1 = databaseClient.deleteWhere(Examples) { id eq 1 }\nassert(deleteRowCount1 == 1)\nval deleteRowCount2 = databaseClient.deleteIgnoreWhere(Examples) { id eq 2 }\nassert(deleteRowCount2 == 1)\n```\n\n#### Extension SQL DSL APIs with [Exposed GADT mapping](https://github.com/huanshankeji/exposed-adt-mapping)\n\nPlease read [that library's basic usage guide](https://github.com/huanshankeji/exposed-adt-mapping?tab=readme-ov-file#basic-usage-guide) first. Here are examples of this library that correspond to [that library's CRUD operations](https://github.com/huanshankeji/exposed-adt-mapping?tab=readme-ov-file#crud-operations).\n\nGradle dependency configuration (only needed since v0.5.0):\n\n```kotlin\nimplementation(\"com.huanshankeji:exposed-vertx-sql-client-sql-dsl-with-mapper:$libraryVersion\")\n```\n\nExample code:\n\n```kotlin\nval directorId = 1\nval director = Director(directorId, \"George Lucas\")\ndatabaseClient.insertWithMapper(Directors, director, Mappers.director)\n\nval episodeIFilmDetails = FilmDetails(1, \"Star Wars: Episode I – The Phantom Menace\", directorId)\n// insert without the ID since it's `AUTO_INCREMENT`\ndatabaseClient.insertWithMapper(Films, episodeIFilmDetails, Mappers.filmDetailsWithDirectorId)\n\nval filmId = 2\nval episodeIIFilmDetails = FilmDetails(2, \"Star Wars: Episode II – Attack of the Clones\", directorId)\nval filmWithDirectorId = FilmWithDirectorId(filmId, episodeIIFilmDetails)\ndatabaseClient.insertWithMapper(Films, filmWithDirectorId, Mappers.filmWithDirectorId) // insert with the ID\n\nval fullFilms = databaseClient.selectWithMapper(filmsLeftJoinDirectors, Mappers.fullFilm) {\n    where(Films.filmId inList listOf(1, 2))\n}\n```\n\n### About the code\n\nAlso see \u003chttps://github.com/huanshankeji/kotlin-common/tree/main/exposed\u003e for some dependency code which serves this library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuanshankeji%2Fexposed-vertx-sql-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuanshankeji%2Fexposed-vertx-sql-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuanshankeji%2Fexposed-vertx-sql-client/lists"}