{"id":37021457,"url":"https://github.com/burtcorp/athena-jdbc","last_synced_at":"2026-01-14T02:32:11.047Z","repository":{"id":49266994,"uuid":"184233440","full_name":"burtcorp/athena-jdbc","owner":"burtcorp","description":"A JDBC driver for AWS Athena","archived":true,"fork":false,"pushed_at":"2024-05-25T20:37:59.000Z","size":403,"stargazers_count":23,"open_issues_count":0,"forks_count":17,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-07-04T13:22:54.870Z","etag":null,"topics":["aws-athena","java","jdbc","jdbc-driver"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/burtcorp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-30T09:30:53.000Z","updated_at":"2024-10-31T13:09:44.000Z","dependencies_parsed_at":"2022-09-17T16:01:37.628Z","dependency_job_id":null,"html_url":"https://github.com/burtcorp/athena-jdbc","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/burtcorp/athena-jdbc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burtcorp%2Fathena-jdbc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burtcorp%2Fathena-jdbc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burtcorp%2Fathena-jdbc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burtcorp%2Fathena-jdbc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/burtcorp","download_url":"https://codeload.github.com/burtcorp/athena-jdbc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burtcorp%2Fathena-jdbc/sbom","scorecard":{"id":258838,"data":{"date":"2025-08-11","repo":{"name":"github.com/burtcorp/athena-jdbc","commit":"700e3cc447e63605f0877699552c040a28f46587"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.5,"checks":[{"name":"Code-Review","score":3,"reason":"Found 5/13 approved changesets -- score normalized to 3","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"project is archived","details":["Warn: Repository is archived."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.txt:0","Info: FSF or OSI recognized license: BSD 3-Clause \"New\" or \"Revised\" License: LICENSE.txt:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 22 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"20 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-h46c-h94j-95f3","Warn: Project is vulnerable to: GHSA-wf8f-6423-gfxg","Warn: Project is vulnerable to: GHSA-288c-cq4h-88gq","Warn: Project is vulnerable to: GHSA-3x8x-79m2-3w2w","Warn: Project is vulnerable to: GHSA-57j2-w4cx-62h2","Warn: Project is vulnerable to: GHSA-jjjh-jjxp-wpff","Warn: Project is vulnerable to: GHSA-rgv9-q543-rqg4","Warn: Project is vulnerable to: GHSA-9vjp-v76f-g363","Warn: Project is vulnerable to: GHSA-grg4-wf29-r9vv","Warn: Project is vulnerable to: GHSA-269q-hmxg-m83q","Warn: Project is vulnerable to: GHSA-5jpm-x58v-624v","Warn: Project is vulnerable to: GHSA-5mcr-gq6c-3hq2","Warn: Project is vulnerable to: GHSA-wx5j-54mm-rqqq","Warn: Project is vulnerable to: GHSA-f256-j965-7f32","Warn: Project is vulnerable to: GHSA-wm47-8v5p-wjpj","Warn: Project is vulnerable to: GHSA-xpw8-rcwv-8f8p","Warn: Project is vulnerable to: GHSA-389x-839f-4rhx","Warn: Project is vulnerable to: GHSA-xq3w-v528-46rv","Warn: Project is vulnerable to: GHSA-6mjq-h674-j845","Warn: Project is vulnerable to: GHSA-7r82-7xv7-xcpj"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-17T10:18:46.889Z","repository_id":49266994,"created_at":"2025-08-17T10:18:46.889Z","updated_at":"2025-08-17T10:18:46.889Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["aws-athena","java","jdbc","jdbc-driver"],"created_at":"2026-01-14T02:32:10.286Z","updated_at":"2026-01-14T02:32:11.034Z","avatar_url":"https://github.com/burtcorp.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# athena-jdbc\n\nIf you are looking for the best JDBC driver for Amazon Athena, have a look at [Amazon Athena JDBC driver v3](https://docs.aws.amazon.com/athena/latest/ug/jdbc-v3-driver.html). The driver in this repo is no longer maintained, but one of the authors was the lead on the new official driver.\n\n---\n\n[![Build Status](https://travis-ci.org/burtcorp/athena-jdbc.png?branch=master)](https://travis-ci.org/burtcorp/athena-jdbc) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.burt/athena-jdbc/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.burt/athena-jdbc)\n\n\n_If you're reading this on GitHub, please note that this is the readme for the development version and that some features described here might not yet have been released. You can find the readme for a specific version via the release tags ([here is an example](https://github.com/burtcorp/athena-jdbc/releases/tag/athena-jdbc-0.1.0))._\n\nThis is a JDBC driver for AWS Athena.\n\n## Installation\n\nUsing Maven you can add this to your dependencies:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.burt\u003c/groupId\u003e\n  \u003cartifactId\u003eathena-jdbc\u003c/artifactId\u003e\n  \u003cversion\u003e${athena-jdbc.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nCheck the [releases page](https://github.com/burtcorp/athena-jdbc/releases) for the value of `${athena-jdbc.version}`.\n\n### Dependencies\n\nThe driver requires Java 8 or later.\n\nThe only dependency is [AWS SDK](https://github.com/aws/aws-sdk-java-v2), specifically `software.amazon.awssdk:athena`. See `pom.xml` for more details.\n\n## Usage\n\n### JDBC URLs\n\nThe driver registers itself with `java.sql.DriverManager` automatically, and accepts JDBC URLs with the subprotocol `athena`. The subname is the default database name for the connection, and is optional. The simplest possible JDBC URL is `\"jdbc:athena\"`, which is equivalent to `\"jdbc:athena:default\"`. To use a database called \"test\" as the default database for the connection use the URL `\"jdbc:athena:test\"`.\n\n### Driver and data source classes\n\nWhen using a JDBC URL to connect you shouldn't need the driver class name, but if you for some reason need them, driver class name is `io.burt.athena.AthenaDriver` and the data source class name is `io.burt.athena.AthenaDataSource`.\n\n### Connection properties\n\nThere are three connection properties:\n\n* `region`: the AWS region to connecto to. The AWS SDK will automatically pick up the value of the `AWS_REGION` environment variable if it is set.\n* `outputLocation`: the location in Amazon S3 where the query results will be stored. This property is required unless `workGroup` is set to a work group that has a configured output location. See [the API docs for more information](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html#athena-Type-ResultConfiguration-OutputLocation).\n* `workGroup`: the name of the work group in which to run the query. See [the API docs for more information](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html#athena-StartQueryExecution-request-WorkGroup).\n\nThese properties are the same for both the `java.sql.DriverManager` and `javax.sql.DataSource` APIs.\n\n### Examples\n\n#### Connecting with `DriverManager`\n\n```java\nimport java.sql.Connection;\nimport java.sql.DriverManager;\nimport java.util.Properties;\n\nProperties properties = new Properties();\nproperties.setProperty(\"region\", \"us-east-1\"); // or set AWS_REGION\nproperties.setProperty(\"outputLocation\", \"s3://some-bucket/and/a/prefix\");\n\ntry (Connection connection = DriverManager.getConnection(\"jdbc:athena:default\", properties)) {\n  // use connection\n}\n```\n\nCurrently the `java.sql.Connection` returned by the driver is thread safe and doesn't need to be closed until the application stops, if at all.\n\n#### Creating a `DataSource`\n\nThis is the least amount of code needed to obtain a connection, and you also get type safe configuration:\n\n```java\nimport io.burt.athena.AthenaDataSource;\nimport java.sql.Connection;\nimport javax.sql.DataSource;\n\nAthenaDataSource dataSource = new AthenaDataSource();\ndataSource.setRegion(\"us-east-1\");\ndataSource.setOutputLocation(\"s3://some-bucket/and/a/prefix\")\n\ntry (Connection connection = dataSource.getConnection()) {\n}\n```\n\n#### Connecting with a connection pool\n\nThis example uses [HikariCP](https://github.com/brettwooldridge/HikariCP), but of course other connection pools work too. The driver supports both JDBC URL and `javax.sql.DataSource` based configurations, and both use the same property names.\n\n```java\nimport com.zaxxer.hikari.HikariConfig;\nimport com.zaxxer.hikari.HikariDataSource;\nimport java.sql.Connection;\nimport javax.sql.DataSource;\n\nHikariConfig config = new HikariConfig();\nconfig.setJdbcUrl(\"jdbc:athena:default\"); // or setDataSourceClassName(\"io.burt.athena.AthenaDataSource\")\nconfig.addDataSourceProperty(\"region\", \"us-east-1\"); // or set AWS_REGION\nconfig.addDataSourceProperty(\"outputLocation\", \"s3://some-bucket/and/a/prefix\");\nDataSource dataSource = new HikariDataSource(config);\n\ntry (Connection connection = dataSource.getConnection()) {\n  // use connection\n}\n```\n\n#### Using a connection\n\nOnce you have a `java.sql.Connection` instance you can use it as you would one from any other JDBC driver.\n\n```java\nimport java.sql.ResultSet;\nimport java.sql.Statement;\n\ntry (\n  Statement statement = connection.createStatement();\n  ResultSet resultSet = statement.executeQuery(\"SELECT 'Hello from Athena'\")\n) {\n  resultSet.next();\n  System.out.println(resultSet.getString(1));\n}\n```\n\n#### Getting the query execution ID from a `ResultSet`\n\n```java\nimport io.burt.athena.AthenaResultSet;\nimport java.sql.ResultSet;\nimport java.sql.ResultSetMetaData;\nimport java.sql.Statement;\n\ntry (\n  Statement statement = connection.createStatement();\n  ResultSet resultSet = statement.executeQuery(\"SELECT 'Hello from Athena'\")\n) {\n  ResultSetMetaData metaData = resultSet.getMetaData();\n  if (metaData.isWrapperFor(AthenaResultSetMetaData.class)) {\n    AthenaResultSetMetaData unwrappedMetaData = metaData.unwrap(AthenaResultSetMetaData.class);\n    String queryExecutionId = unwrappedMetaData.getQueryExecutionId();\n    System.out.println(queryExecutionId);\n  }\n}\n```\n\n#### Providing client request tokens\n\nBy setting a client request token on a query execution you can make Athena reuse a previous result set if the exact same query has already been run. If you run the same query multiple times this can save money and improve performance.\n\n```java\nimport io.burt.athena.AthenaStatement;\nimport java.sql.ResultSet;\nimport java.sql.Statement;\nimport org.apache.commons.codec.binary.Hex;\n\ntry (Statement statement = connection.createStatement()) {\n  if (statement.isWrapperFor(AthenaStatement.class)) {\n    AthenaStatement unwrappedStatement = statement.unwrap(AthenaStatement.class);\n    unwrappedStatement.setClientRequestTokenProvider(sql -\u003e Optional.ofNullable(Hex.encodeHexString(sql)));\n  }\n  for (int i = 0; i \u003c 10; i++) {\n    try (ResultSet resultSet = statement.executeQuery(\"SELECT 'Hello from Athena'\")) {\n        resultSet.next();\n        System.err.println(resultSet.getString(1));\n      }\n    }\n  }\n}\n```\n\nThe client request token provider is a `Function\u003cString, Optional\u003cString\u003e\u003e`, and receives the SQL that will be executed, and should return the token to use for the request, wrapped in an `java.util.Optional`.\n\n## Description\n\n### Why another Athena JDBC driver?\n\nThere is already an [existing JDBC driver for Athena](https://docs.aws.amazon.com/athena/latest/ug/connect-with-jdbc.html), so why another one?\n\nThere is nothing fundamentally wrong with the existing driver. It was developed by Simba, who have a lot of experience building JDBC drivers, but who do not have much experience with Athena. Just providing a JDBC layer for running queries in Athena is not enough.\n\nThese are some of the issues we have found with the existing driver:\n\n* There is no way to get hold of the query execution ID of a query. This means that you can't get query statistics, or log the query ID for debugging, and many other things.\n* There is no support for things like client request tokens, which means that probably the best way to achieve good performance and avoid costs in Athena is not possible to use.\n* The polling strategy is poor. Initially it was more or less calling `GetQueryExecution` in a loop with a 5ms delay, which caused a lot of throttling errors if you had a few applications using the driver. In later versions it uses a backoff strategy of sorts; it starts at 5ms and increases the delay to a configurable max value. The increase is by a factor of 20, though, which means that with the defaults it will start at 5ms and then go to 100ms, the default max, which is more or less equivalent to a fixed delay of 100ms. If you give it a higher max, say 2000ms, there will only be one more call before the max delay is reached.\n* It shades the Athena and Glue AWS SDKs, which, among other things, causes issues with logging (see below) and with exceptions. A JDBC driver throws `SQLException`, of course, but the original exceptions are usually available as the exception cause. However, since the AWS SDK is shaded these exceptions have internal class names instead of the well-known AWS SDK names, making it hard to deal with unwrapping exceptions and deal with the underlying cause.\n* The driver uses its own home-grown logging framework, which does not interact with any regular Java logging framework. It's hard to configure, and most things you can't even configure. You'd be forgiven for thinking that properties like `UseAwsLogger` meant that it would use the AWS SDK logging facilities, but instead it means that it will log all the AWS SDK calls it makes to its own logger. Also, to add insult to injury, because it shades the AWS SDK configuring logging for that becomes much harder. The driver does not document how the AWS SDK has been shaded, so you'll have to figure out yourself what the class names are. You'll also get a shaded log4j bundled in the JAR, which means makes the situation even more of a mess since you can't override it with, for example, the SLF4J log4j bridge.\n* The driver is also not available in any Maven repository, which means that any project depending on it will have to find its own way to get hold of the JAR. This complicates automated testing and deployment.\n* Finally, most of the shortcomings above could have been fixed easily if the driver was open source. We would have loved to provide patches that fixed the issues we have found over the last few years, instead of having to write our own.\n\nThis alternative Athena JDBC driver aims to fix these issues, and hopefully even more things that we haven't even thought of yet.\n\n## Limitations \u0026 known issues\n\nIf you get a `java.lang.UnsupportedOperationException` it means that you've found a feature that hasn't been implemented yet. Some of these will eventually get implemented, but some may not make sense for Athena. If you rely on one of these open an issue and describe your use case.\n\nIf you get a `java.sql.SQLFeatureNotSupportedException` exception it means that the feature or operation either is not supported by Athena, or that it's unclear how it could be supported. Feel free to open pull requests that adds support for it if you have an idea for how it could be done.\n\nBefore you open an issue, check the API documentation and tests, there might be clues and hints there. Looking at the commit history of a method can also lead to insights.\n\nThese are some specific limitations and known issues that you might run into:\n\n* `ResultSet#getArray` always returns string arrays, because Athena does not return any type information beyond `\"array\"`. It also does it's best splitting the array, but there is no way to tell the arrays `[\"hello\", \"world\"]` and `[\"hello, world\"]` apart. We recommend always casting to JSON for complex types, extract them using `ResultSet#getString` and parse them in your own code.\n* Similarly to arrays, maps and structs don't have unambiguous serializations in the Athena output format, but there is also no support in the JDBC API for these types. Cast to JSON, and use `ResultSet#getString` and parse them in your own code.\n* `Connection#prepareStatement` is not supported. The official Athena driver tries to support prepared statements and interpolation on the client side (it's unclear if it even works), but it's not the goal of this alternative driver to do that. Athena itself does not support prepared statements or interpolation, and there is no performance gain to be had from preparing statements.\n* The current mechanism for loading results loads them from S3 directly, instead of using the `GetQueryResult` and undocumented `GetQueryResultsStream` API calls. This is slower for small, but significantly faster for large result sets. In the future an optimized implementation, or an implementation that uses the fastest mechanism for a given result will be used to ensure good performance for all result set sizes.\n* There is currently limited support for the [`DatabaseMetadata` JDBC API](https://docs.oracle.com/javase/8/docs/api/java/sql/DatabaseMetaData.html), which is used by some UI tools to list databases, tables, etc. This API could be implemented, but represents a significant effort. If you want to contribute to the driver this may be a good place to start.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Copyright\n\n© 2019 Theo Hultberg and contributors, see LICENSE.txt (BSD 3-Clause).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fburtcorp%2Fathena-jdbc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fburtcorp%2Fathena-jdbc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fburtcorp%2Fathena-jdbc/lists"}