Registry / database / athena-express-plus

athena-express-plus

library8.1.0jsnpmunverified

Athena-Express-Plus is a Node.js library (v8.1.0) that simplifies executing SQL queries in Amazon Athena and fetching cleaned-up JSON results. It wraps the AWS SDK v3 Athena and S3 clients, handling query initiation, polling, result retrieval from S3, and error retries (ThrottlingException, NetworkingError, TooManyRequestsException). Supports parameterized queries, pagination, streaming, and cost estimation. Actively maintained as a fork of the original Athena-Express, adding AWS SDK v3 support and dynamic parameters. Key differentiator: seamless JSON output and integrated error handling without manual API stitching.

database

npm install athena-express-plus

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ATHENA-EXPRESS-PLU

athena-express-plus

databasejavascriptv8.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AthenaExpressPlus

✓ import { AthenaExpressPlus } from 'athena-express-plus';

✗ const AthenaExpressPlus = require('athena-express-plus').AthenaExpressPlus;

ESM default; CommonJS users must destructure.

default

✓ import AthenaExpressPlus from 'athena-express-plus';

✗ const AthenaExpressPlus = require('athena-express-plus');

In ESM, default import works; CJS requires destructuring from .default.

AthenaExpressPlus

✓ const { AthenaExpressPlus } = require('athena-express-plus');

✗ const AthenaExpressPlus = require('athena-express-plus');

CommonJS must destructure because the package exports named exports.

Shows how to instantiate AthenaExpressPlus with AWS SDK v3 clients and execute a simple SELECT query.

import { AthenaExpressPlus } from 'athena-express-plus'; import { Athena } from '@aws-sdk/client-athena'; import { S3 } from '@aws-sdk/client-s3'; const athena = new Athena({ region: 'us-east-1' }); const s3 = new S3({ region: 'us-east-1' }); const athenaExpress = new AthenaExpressPlus({ aws: { athena, s3 }, db: 'my_database', s3Bucket: 's3://my-athena-results-bucket', getStats: true, }); async function runQuery() { try { const results = await athenaExpress.query('SELECT * FROM movies LIMIT 10'); console.log(results); } catch (error) { console.error(error); } } runQuery();

Debug

Known issues

breakingAWS SDK v3 migration: @aws-sdk/client-athena and @aws-sdk/client-s3 are now required peer dependencies instead of aws-sdk v2.

fix

Remove aws-sdk v2 and install @aws-sdk/client-athena and @aws-sdk/client-s3.

affects: >=8.0.0

breakingConstructor option change: 'aws' object now expects 'athena' and 's3' client instances, not 'config' or 'credentials' directly.

fix

Create Athena and S3 clients separately and pass them via { athena, s3 }.

affects: >=8.0.0

gotchaS3 bucket path must be in 's3://bucket-name' format; omit trailing slash.

fix

Use 's3Bucket: 's3://my-bucket'' (no trailing slash).

affects: >=1.0.0

deprecatedThe 'formatJson' option is deprecated and ignored; results are always returned as clean JSON.

fix

Remove 'formatJson' from configuration.

affects: >=8.0.0

gotchaCost estimate via 'getCost' is approximate and may vary from actual AWS billing due to rounding.

fix

Use 'getStats: true' to access cost; treat as estimate only.

affects: >=1.0.0

deprecatedThe 'retry' option has been removed; retries are now automatic for specific errors.

fix

Remove 'retry' from configuration; retry logic is built-in.

affects: >=8.0.0

gotchaQuery results may be limited by Athena's 1000-row default; use pagination or 'NextToken' for larger results.

fix

Set 'maxResults' in query or use 'startQueryExecution' with manual pagination.

affects: >=1.0.0

Errors

Common errors & fixes

Error: connect ETIMEDOUT athena.us-east-1.amazonaws.com:443

Network issue or missing IAM permissions for Athena execution.

fix

Ensure Lambda/EC2 has proper outbound internet access and IAM policy allows 'athena:StartQueryExecution' and 'athena:GetQueryResults'.

TypeError: Cannot read properties of undefined (reading 'trim')

Empty result set or query returned no columns.

fix

Check if the query is valid and the table exists. Use 'LIMIT 1' to test.

AccessDeniedException: User: arn:aws:iam::123456789:role/lambda-role is not authorized to perform: athena:StartQueryExecution

IAM role lacks permission to execute Athena queries.

fix

Attach policy 'AmazonAthenaFullAccess' or custom policy with 'athena:StartQueryExecution' and 'athena:GetQueryResults'.

Error: S3 bucket 'my-bucket' does not exist

The specified S3 bucket for query results does not exist or is inaccessible.

fix

Verify bucket name and region; ensure the role has s3:PutObject and s3:GetObject permissions on that bucket.

Upgrade

Version history

8.1.0latest on npm

Audit

Dependencies

@aws-sdk/client-athenarequiredRequired to interact with Amazon Athena API

@aws-sdk/client-s3requiredRequired to fetch query results stored in S3

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sr-26/athena-express-plus ↗

packageathena-express-plus ↗

homepagehttps://github.com/sr-26/athena-express-plus#readme ↗