{"id":16633188,"url":"https://github.com/be-hase/kuery-client","last_synced_at":"2025-11-09T00:02:50.150Z","repository":{"id":243673518,"uuid":"806354598","full_name":"be-hase/kuery-client","owner":"be-hase","description":"A Kotlin/JVM database client for those who want to write SQL","archived":false,"fork":false,"pushed_at":"2025-03-14T18:55:28.000Z","size":990,"stargazers_count":12,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-18T02:44:19.184Z","etag":null,"topics":["database-client","jdbc","kotlin","r2dbc","spring","sql"],"latest_commit_sha":null,"homepage":"https://kuery-client.hsbrysk.dev/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/be-hase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-27T03:17:06.000Z","updated_at":"2025-03-14T18:55:09.000Z","dependencies_parsed_at":"2024-06-10T15:35:34.914Z","dependency_job_id":"a8f2f985-54bc-468a-9740-3333c5f391af","html_url":"https://github.com/be-hase/kuery-client","commit_stats":null,"previous_names":["be-hase/kuery-client"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-hase%2Fkuery-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-hase%2Fkuery-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-hase%2Fkuery-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/be-hase%2Fkuery-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/be-hase","download_url":"https://codeload.github.com/be-hase/kuery-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244822663,"owners_count":20516146,"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":["database-client","jdbc","kotlin","r2dbc","spring","sql"],"created_at":"2024-10-12T05:12:26.929Z","updated_at":"2025-11-09T00:02:50.118Z","avatar_url":"https://github.com/be-hase.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003ch1\u003e\n\u003ca href=\"https://kuery-client.hsbrysk.dev/\"\u003e\u003cimg src=\"/docs/logo.png\" alt=\"kuery-client-logo\" width=\"400\" /\u003e\u003c/a\u003e\n\u003c/h1\u003e\n\u003ca href=\"https://central.sonatype.com/search?q=kuery-client\"\u003e\u003cimg alt=\"Maven Central Version\" src=\"https://img.shields.io/maven-central/v/dev.hsbrysk.kuery-client/kuery-client-core\"\u003e\u003c/a\u003e\n\u003cbr /\u003e\n\u003ca href=\"https://kuery-client.hsbrysk.dev/\"\u003e\u003cb\u003eDocument Site\u003c/b\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n## Introduction\n\n### Features\n\n- **Love SQL ♥**\n    - While ORM libraries in the world are convenient, they often require learning their own DSL, which we believe has a\n      high learning cost. Kuery Client emphasizes writing SQL as it is.\n- **Based on spring-data-r2dbc and spring-data-jdbc**\n    - Kuery Client is implemented based on spring-data-r2dbc and spring-data-jdbc. Use whichever you prefer. You can use\n      Spring's ecosystem as it is, such as `@Transactional`.\n- **Observability**\n    - It supports Micrometer Observation, so Metrics/Tracing/Logging can also be customized.\n- **Extensible**\n    - When dealing with complex data schemas, there are often cases where you want to write common query logic. Thanks\n      to Kotlin's extension functions, this becomes easier.\n\n### Motivation\n\nWe have used numerous ORM libraries, but in the end, we preferred libraries\nlike [MyBatis](https://github.com/mybatis/mybatis-3) that allow writing SQL directly.\n\nTo construct SQL dynamically, custom template syntax (such as if/foreach) is often used, but we prefer to write logic\nusing the syntax provided by the programming language as much as possible.\nwe want to write dynamic SQL using Kotlin syntax, similar to [kotlinx.html](https://github.com/Kotlin/kotlinx.html).\n\nTo meet these needs, we implemented `Kuery Client`.\n\n### Overview\n\nBy using the following SQL builder, you can easily build and execute SQL. Whether using R2DBC or JDBC, the way of\nwriting is almost the same.\n\nBy providing a Kotlin compiler plugin, we achieve binding parameters using string interpolation.\n\n```kotlin\ndata class User(...)\n\nclass UserRepository(private val kueryClient: KueryClient) {\n    suspend fun findById(userId: Int): User? = kueryClient\n        .sql { +\"SELECT * FROM users WHERE user_id = $userId\" }\n        .singleOrNull()\n\n    suspend fun search(status: String, vip: Boolean?): List\u003cUser\u003e = kueryClient\n        .sql {\n            +\"\"\"\n            SELECT * FROM users\n            WHERE\n            status = $status\n            \"\"\"\n            if (vip != null) {\n                +\"AND vip = $vip\"\n            }\n        }\n        .list()\n\n    suspend fun insertMany(users: List\u003cUser\u003e): Long = kueryClient\n        .sql {\n            +\"INSERT INTO users (username, email)\"\n            // useful helper function\n            values(users) { listOf(it.username, it.email) }\n        }\n        .rowsUpdated()\n}\n```\n\nThis SQL builder is very simple. There are only two things you need to remember:\n\n- You can concatenate SQL strings using `+`(unaryPlus).\n    - You can also directly express logic such as if statements in Kotlin.\n- By using string interpolation, it is possible to bind parameters.\n\n### Based on spring-data-r2dbc and spring-data-jdbc\n\nCurrently, it is implemented based on the well-established `spring-data-r2dbc` and `spring-data-jdbc` in the Java\ncommunity. Kuery Client simply provides the aforementioned SQL builder on this foundation.\n\nIt is designed to be used alongside both `spring-data-r2dbc` and `spring-data-jdbc`, allowing you to start small.\n\nIn the future, we may add a different foundation or possibly create a new one from scratch.\n\n## Getting Started\n\n### Install\n\n#### Gradle\n\n```kotlin\nplugins {\n    id(\"dev.hsbrysk.kuery-client\") version \"{{version}}\"\n}\n\nimplementation(\"dev.hsbrysk.kuery-client:kuery-client-spring-data-r2dbc:{{version}}\")\n// or, implementation(\"dev.hsbrysk.kuery-client:kuery-client-spring-data-jdbc:{{version}}\")\n```\n\n### Build KueryClient\n\n#### for `kuery-client-spring-data-r2dbc`\n\n```kotlin\nval connectionFactory: ConnectionFactory = ...\n\nval kueryClient = SpringR2dbcKueryClient.builder()\n    .connectionFactory(connectionFactory)\n    .build()\n```\n\n#### for `kuery-client-spring-data-jdbc`\n\n```kotlin\nval dataSource: DataSource = ...\n\nval kueryClient = SpringJdbcKueryClient.builder()\n    .dataSource(dataSource)\n    .build()\n```\n\n### Let's Use It\n\n```kotlin\nval userId = \"...\"\nval user: User = kueryClient\n    .sql { +\"SELECT * FROM users WHERE user_id = $userId\" }\n    .singleOrNull()\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbe-hase%2Fkuery-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbe-hase%2Fkuery-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbe-hase%2Fkuery-client/lists"}