{"id":19281868,"url":"https://github.com/elide-dev/planetscale-java","last_synced_at":"2025-04-22T01:31:14.740Z","repository":{"id":206300048,"uuid":"715993796","full_name":"elide-dev/planetscale-java","owner":"elide-dev","description":"Planetscale Connector for Java","archived":false,"fork":false,"pushed_at":"2024-03-20T20:55:44.000Z","size":781,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-03-20T21:56:33.221Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://planetscale.com","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/elide-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-11-08T08:59:03.000Z","updated_at":"2024-04-15T06:33:55.073Z","dependencies_parsed_at":"2024-02-14T09:30:49.628Z","dependency_job_id":"85d9f356-0771-4dc4-87be-576446b353d6","html_url":"https://github.com/elide-dev/planetscale-java","commit_stats":null,"previous_names":["elide-dev/planetscale-java"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elide-dev%2Fplanetscale-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elide-dev%2Fplanetscale-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elide-dev%2Fplanetscale-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elide-dev%2Fplanetscale-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elide-dev","download_url":"https://codeload.github.com/elide-dev/planetscale-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250161991,"owners_count":21385020,"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":[],"created_at":"2024-11-09T21:24:29.886Z","updated_at":"2025-04-22T01:31:14.443Z","avatar_url":"https://github.com/elide-dev.png","language":"Kotlin","readme":"\n# Planetscale Connector/J\n\n[![CI](https://github.com/elide-dev/planetscale-java/actions/workflows/on.push.yml/badge.svg)](https://github.com/elide-dev/planetscale-java/actions/workflows/on.push.yml)\n[![codecov](https://codecov.io/gh/elide-dev/planetscale-java/graph/badge.svg?token=MRUx3BHbMG)](https://codecov.io/gh/elide-dev/planetscale-java)\n[![Java 21](https://img.shields.io/badge/Java-21-blue.svg?logo=oracle)](https://openjdk.org/projects/jdk/21/)\n[![Kotlin](https://img.shields.io/badge/Kotlin-1.9.22-blue.svg?logo=kotlin)](http://kotlinlang.org)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8053/badge)](https://www.bestpractices.dev/projects/8053)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=elide-dev_planetscale-java\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=elide-dev_planetscale-java)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=elide-dev_planetscale-java\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=elide-dev_planetscale-java)\n\n\u003e **Note**\n\u003e Under construction; use at your own risk\n\nThis library implements a [JDBC adapter](https://www.oracle.com/database/technologies/appdev/jdbc.html) for\n[Planetscale][1].\n\nPlanetscale uses [Vitess][2] as a backend, which is wire-compatible with MySQL; thus, this library is a wrapper around\nthe [MySQL Connector/J][3] library, which is used for the actual work of connecting and running queries.\n\nThis library adds several features, using the MySQL/J connector, to make it easier to work with Planetscale.\n\n- [Installation](#installation)\n- [Features](#features)\n- [Integration Libraries](#integration-libraries)\n  - [Micronaut Integration](#micronaut-integration)\n  - [Kotlin Integration](#kotlin-integration)\n  - [GraalVM Integration](#graalvm-integration)\n- [Library Hygiene](#library-hygiene)\n  - [Build caching](#build-caching)\n\n## Installation\n\n\u003e **Warning**\n\u003e This is *not* endorsed by Planetscale, and is not yet published to Maven Central.\n\n| Coordinates                           | Driver                       |\n|---------------------------------------|------------------------------|\n| ```com.planetscale:planetscale-jvm``` | ```com.planetscale.Driver``` |\n\n**Gradle (Kotlin DSL, via Version Catalogs):**\n```kotlin\n// in settings.gradle.kts\n\ndependencyResolutionManagement {\n    versionCatalogs {\n        create(\"planetscale\") {\n            from(\"com.planetscale:planetscale-catalog:(latest version)\")\n        }\n    }\n}\n```\n```kotlin\n// in build.gradle.kts\n\ndependencies {\n    implementation(planetscale.driver)\n}\n```\n\n**Gradle (Kotlin DSL, one library at a time):**\n```kotlin\ndependencies {\n    implementation(\"com.planetscale:planetscale-jvm:\u003cversion\u003e\")\n}\n```\n\n**Maven:**\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.planetscale\u003c/groupId\u003e\n    \u003cartifactId\u003eplanetscale-jvm\u003c/artifactId\u003e\n    \u003cversion\u003e\u003c!-- use the latest version --\u003e\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n# Features\n\n- **Easy Planetscale connection strings.**\n\n  Use `jdbc:planetscale://aws` or `jdbc:planetscale://gcp` or connect to a specific region with something like\n  `jdbc:planetscale://us-east-1.aws`. The adapter builds the right URL for you. These examples become:\n\n```\njdbc:mysql://aws.connect.psdb.cloud:3306/dbname?...\njdbc:mysql://gcp.connect.psdb.cloud:3306/dbname?...\njdbc:mysql://us-east-1.aws.connect.psdb.cloud:3306/dbname?...\n```\n\n\n- **Load balanced reads.**\n\n  Use more than one endpoint with URLs like: `jdbc:planetscale://us-west-1.aws..aws`. In this case, the MySQL/J driver\n  is configured with:\n\n```\njdbc:mysql:replication://us-west-1.aws.connect.psdb.cloud:3306,aws.connect.psdb.cloud:3306/dbname?roundRobinLoadBalance=true\u0026...\n```\n\n\n- **Eager driver cache and solid defaults.**\n\n  The Planetscale driver configures the MySQL/J driver for client-side caching of server configuration, result set\n  metadata, and so on. SSL verification is turned on, as is auto-reconnection. Equivalent driver options:\n\n```\nautoReconnect=true\ncacheServerConfiguration=true\ncacheResultSetMetadata=true\nsslMode=VERIFY_IDENTITY\nroundRobinLoadBalance=true\n```\n\n\n- **Support for Planetscale's options.**\n\n  Planetscale options like `enableBoost` can be applied to configure the underlying URL properly. For example, adding\n  `enableBoost=true` to the AWS sample URL above, like so: `jdbc:planetscale://aws?enableBoost=true`, becomes:\n\n```\njdbc:mysql://aws.connect.psdb.cloud:3306/dbname?sessionVariables=boost_cached_queries=true\u0026...\n```\n\n\n- **Configure credentials via env vars, properties, or connection URL.**\n\n  `PLANETSCALE_USERNAME`, `-Dplanetscale.username`, and `jdbc:planetscale://user:pass@...` are all supported, as are the \n  same variables for the connection password. These are consulted if no user/pass are found in the connection string.\n\n# Integration Libraries\n\nThere are a few libraries shipped with this repo which make integration easier with various frameworks or systems:\n\n## Micronaut Integration\n\nAdds [Micronaut][5] property source support for Planetscale configuration. Effectively, the module configures itself as\na driver (when enabled), and provides connection parameters as configuration. Otherwise the driver is identical to using\nthe MySQL/J driver library directly.\n\n\n### Usage\n\nConfiguration in Micronaut is pretty easy:\n\n```yaml\nplanetscale:\n  enabled: true\n  databases:\n    default:\n        db: dbname\n        username: username-here\n        password: password-here\n        endpoints:\n          - us-west-1.aws\n          - aws\n        features:\n          boost: true\n```\n\n`PLANETSCALE_DB`, `-Dplanetscale.db`, and so on, also work. This is roughly equivalent to:\n\n```yaml\ndatasources:\n  default:\n    url: jdbc:mysql://username-here:password-here@us-west-1.aws.connect.psdb.cloud:3306,aws.connect.psdb.cloud:3306/dbname?cacheServerConfiguration=true\u0026cacheResultSetMetadata=true\u0026sslMode=VERIFY_IDENTITY\u0026roundRobinLoadBalance=true\u0026sessionVariables=boost_cached_queries=true\n    driverClassName: com.planetscale.Driver\n    db-type: mysql\n    name: dbname\n    username: username-here\n    password: password-here\n    maximum-pool-size: 32\n```\n\n### Installation\n\n**Coordinates:**\n```\ncom.planetscale:planetscale-micronaut\n```\n\n**Maven:**\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.planetscale\u003c/groupId\u003e\n    \u003cartifactId\u003eplanetscale-micronaut\u003c/artifactId\u003e\n    \u003cversion\u003e\u003c!-- use the latest version --\u003e\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**Gradle (Version Catalog):**\n```kotlin\ndependencies {\n    implementation(planetscale.integration.micronaut)\n}\n```\n\n## Kotlin Integration\n\nAdds [Kotlin][6]-focused API support for Planetscale. Easily load credentials and configuration, and then obtain a driver\ninstance or connection.\n\n### Installation\n\n**Coordinates:**\n```\ncom.planetscale:planetscale-kotlin\n```\n\n**Maven:**\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.planetscale\u003c/groupId\u003e\n    \u003cartifactId\u003eplanetscale-kotlin\u003c/artifactId\u003e\n    \u003cversion\u003e\u003c!-- use the latest version --\u003e\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**Gradle (Version Catalog):**\n```kotlin\ndependencies {\n    implementation(planetscale.integration.kotlin)\n}\n```\n\n\n## GraalVM Integration\n\nAdds metadata and a supporting feature configuration for [GraalVM][4] native image compilation. Reflection configuration\nis embedded which supports both this adapter and MySQL/J.\n\n### Usage\n\nReflection and resource configuration is automatic. Otherwise, during a `native-image` build:\n\n```\nnative-image ... --features=com.planetscale.PlanetscaleFeature\n```\n\n### Installation\n\n**Coordinates:**\n```\ncom.planetscale:planetscale-graalvm\n```\n\n**Maven:**\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.planetscale\u003c/groupId\u003e\n    \u003cartifactId\u003eplanetscale-graalvm\u003c/artifactId\u003e\n    \u003cversion\u003e\u003c!-- use the latest version --\u003e\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**Gradle (Version Catalog):**\n```kotlin\ndependencies {\n    implementation(planetscale.integration.graalvm)\n}\n```\n\n## Library Hygiene\n\nThis library is built with **Java 21**, targeting **Java 17** as a minimum baseline. If you need an earlier version of\nJava, let us know, and we can probably ship one for you (within reason).\n\nThe following devops features are baked into the library's code or process:\n\n- **CI/CD:** Built, tested, and shipped from a cleanroom environment in Github Actions. CI runners are [monitored][7]\n  for security and compliance and updated regularly.\n\n- **Testing:** The library has reasonable [test coverage][8], and can be mocked under the hood with [H2][9].\n\n- **Analysis:** Linting and static analysis with [CodeQL][16], [Detekt][17], and [ktlint][18].\n\n- **Integrity:** Dependencies are locked, hash-sealed and signature-checked. We also ship [SBOMs][15] with each release.\n\n- **Provenance:** [SLSA provenance][10] is issued during the release process, and releases are published to\n  [Sigstore][11]. Of course, releases are also signed with [PGP][12].\n\n- **API checks:** Each release of the library is stamped with API layout information, so that library consumer breakage\n  can be checked and enforced.\n\n- **Dependencies:** Depends on [MySQL/J][3] and [Kotlin][6]. Each integration library may have other dependencies, like\n  [Micronaut][5] or [GraalVM][4].\n\n- **Versioning:** Uses [Semantic Versioning](https://semver.org/).\n\n- **Contributions:** Uses [Developer Certificate of Origin][13] and [Contributor License Agreement][14] to ensure\n  contributions are properly licensed.\n\n- **Humans:** We are friendly people who are open to contributions, and we adopt a\n  [Code of Conduct](./CODE_OF_CONDUCT.md) which encourages good faith collaboration.\n\n- **License:** [MIT license](./LICENSE).\n\n\n### Build caching\n\nThis library uses [Buildless][19] to cache build artifacts and accelerate builds. This cache project is public, so\nopen-source contributors can use it, too. No setup is needed.\n\n\nMade with ❤️ by [Elide](https://elide.dev)\n\n[1]: https://planetscale.com/\n[2]: https://vitess.io/\n[3]: https://dev.mysql.com/downloads/connector/j/\n[4]: https://www.graalvm.org/\n[5]: https://micronaut.io/\n[6]: https://kotlinlang.org/\n[7]: https://app.stepsecurity.io\n[8]: https://app.codecov.io/gh/elide-dev/planetscale-java\n[9]: https://www.h2database.com/html/main.html\n[10]: https://slsa.dev/\n[11]: https://sigstore.dev/\n[12]: https://www.gnupg.org/\n[13]: https://developercertificate.org/\n[14]: ./.github/CLA.md\n[15]: https://spdx.dev/\n[16]: https://securitylab.github.com/tools/codeql\n[17]: https://detekt.github.io/detekt/\n[18]: https://ktlint.github.io/\n[19]: https://less.build/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felide-dev%2Fplanetscale-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felide-dev%2Fplanetscale-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felide-dev%2Fplanetscale-java/lists"}