DBeaver Athena connection setup for Amazon S3 Tables

dbeaver-athena-s3-tables.md

DBeaver + Athena + Amazon S3 Tables: connection notes

Problem

DBeaver could connect to Amazon Athena, but the database navigator only showed:

AwsDataCatalog.default

Even though Amazon S3 Tables namespaces and tables existed and could be listed with the AWS CLI.

This caused DBeaver export/import workflows to target the wrong catalog/schema.

Root cause

Amazon S3 Tables are exposed to Athena through a separate Glue child catalog, not the default AwsDataCatalog.

The S3 Tables catalog name has this form:

s3tablescatalog/<s3-table-bucket-name>

DBeaver/Athena SQL can use this catalog as an execution context, but DBeaver's UI metadata browser may still only show AwsDataCatalog.default unless the S3 Tables child catalog is registered as an Athena data catalog.

Verify the S3 Tables catalog exists

aws glue get-catalogs --region <region>

The parent catalog usually looks like:

<account-id>:s3tablescatalog

The child catalog for a table bucket is:

<account-id>:s3tablescatalog/<s3-table-bucket-name>

You can verify namespaces/databases with:

aws glue get-databases \
  --region <region> \
  --catalog-id '<account-id>:s3tablescatalog/<s3-table-bucket-name>'

Register the S3 Tables child catalog as an Athena data catalog

Use an admin-capable AWS profile.

Safer approach using a JSON file:

cat > /tmp/athena-s3tables-catalog.json <<'JSON'
{
  "Name": "my_s3tables_catalog",
  "Type": "GLUE",
  "Parameters": {
    "catalog-id": "<account-id>:s3tablescatalog/<s3-table-bucket-name>"
  }
}
JSON

aws athena create-data-catalog \
  --region <region> \
  --cli-input-json file:///tmp/athena-s3tables-catalog.json

Verify:

aws athena list-data-catalogs --region <region>

Expected:

AwsDataCatalog
my_s3tables_catalog

Then verify databases/schemas:

aws athena list-databases \
  --region <region> \
  --catalog-name my_s3tables_catalog

DBeaver Athena connection settings

Set the Athena connection to use the registered catalog alias:

Region: <region>
Catalog: my_s3tables_catalog
Database: <empty> or a specific namespace such as seek/finnhub
S3 location: s3://<normal-s3-bucket>/<athena-results-prefix>/
Workgroup: primary or your Athena workgroup

Important: the S3 location field is for Athena query results. Do not point it at the S3 Tables table bucket. Use a normal S3 bucket/prefix for Athena results.

After changing settings:

1. Save connection.
2. Invalidate/Reconnect.
3. Refresh metadata.

Useful SQL checks in DBeaver

When the catalog is set correctly in the connection, these should work:

SHOW SCHEMAS;

SHOW TABLES IN <namespace>;

SELECT * FROM <namespace>.<table_name> LIMIT 10;

Do not rely on:

SHOW DATABASES IN "s3tablescatalog/<bucket>";

Some Athena/DBeaver driver combinations do not parse that form. Prefer setting the catalog in the connection or registering it as a named Athena data catalog.

S3 Tables naming gotcha

S3 Tables table names, namespaces, and column names should be lowercase. Uppercase names may not be visible or supported correctly through Athena/Lake Formation/Glue integrations.

Use names like:

seek.securitiesv2
finnhub.countryexposure

instead of mixed-case names.

Summary

If DBeaver only shows AwsDataCatalog.default while S3 Tables exist, the likely fix is:

1. Register the S3 Tables Glue child catalog as an Athena data catalog.
2. Set DBeaver's Athena Catalog to that registered catalog name.
3. Leave Database empty, or set it to a specific S3 Tables namespace.
4. Use a normal S3 bucket/prefix for Athena query results.
5. Invalidate/reconnect and refresh DBeaver metadata.