Configuration

aathena.config.json lives at your project root and marks it. init writes it; edit it afterwards as needed. Both the CLI and the runtime find it by walking up the directory tree, so it works from any subdirectory.

{
  "region": "eu-west-1",
  "database": "sampledb",
  "workgroup": "primary",
  "outputLocation": "s3://my-bucket/athena-results/",
  "tablesDir": "./tables",
  "outDir": "./generated",
  "codegen": {
    "indent": 2
  },
  "query": {
    "timeout": 300000,
    "pollingInterval": 500,
    "maxPollingInterval": 5000
  }
}

The type

This is the actual declaration, included from src/runtime/types.ts:

/**
 * Project configuration, read from `aathena.config.json` at the project root.
 *
 * `createClient()` finds and loads it by walking up from the working
 * directory. Pass a config to `createClient(config)` to skip the file
 * entirely, which is what tests and bundled deploys want.
 */
export interface AathenaConfig {
  /** AWS region. Falls back to the standard AWS SDK resolution chain. */
  region?: string;
  /**
   * Primary Athena database. Used for every query whose directory does not
   * name a different one.
   */
  database: string;
  /** Athena workgroup. Its default output location is used when set. */
  workgroup?: string;
  /**
   * S3 path for query results, for example `s3://bucket/prefix/`. Optional
   * when the workgroup already defines one.
   */
  outputLocation?: string;
  /** Where your SQL files live. Defaults to `./tables`. */
  tablesDir?: string;
  /** Where codegen writes. Defaults to `./generated`. */
  outDir?: string;
  codegen?: {
    /**
     * Number of spaces used to indent generated TypeScript files. Defaults to
     * 2, which matches Prettier and the broader TS ecosystem (Google, Airbnb,
     * Angular, NestJS templates). Values outside `[1, 8]` are clamped.
     */
    indent?: number;
  };
  query?: {
    /** How long to wait for a query before giving up, in ms. Defaults to 300000. */
    timeout?: number;
    /** First poll interval, in ms. Defaults to 500, then backs off. */
    pollingInterval?: number;
    /** Ceiling for the backing-off poll interval, in ms. Defaults to 5000. */
    maxPollingInterval?: number;
  };
  /**
   * Manual override for `parallel({ concurrency: 'auto' })` when service-quotas
   * is unreachable. When set, takes precedence over the live quota lookup and
   * the region-based fallback table.
   */
  maxConcurrency?: number;
}

Fields

Field	Default	Meaning
region	the AWS default chain	AWS region
database	required	primary Athena database, used when a query's directory does not say otherwise
workgroup	-	Athena workgroup
outputLocation	-	S3 path for query results; optional when the workgroup has a default
tablesDir	./tables	where your SQL files live
outDir	./generated	where codegen writes
codegen.indent	2	spaces used to indent generated files, clamped to [1, 8]
query.timeout	300000	query timeout in ms, 5 minutes
query.pollingInterval	500	initial poll interval in ms
query.maxPollingInterval	5000	maximum poll interval in ms
maxConcurrency	-	overrides parallel({ concurrency: 'auto' }) when Service Quotas is unreachable

Overriding at runtime

createClient() reads the file. Passing a config skips it entirely, which is what you want in tests or when the project root is not on disk:

import { createClient } from 'aathena';

// createClient() with no argument reads aathena.config.json from the project
// root. Pass a config to override it - useful in tests, or when the project
// root is not on disk (bundled Lambda deploys).
const athena = createClient({
  region: 'us-east-1',
  database: 'analytics',
  workgroup: 'primary',
  outputLocation: 's3://my-athena-results/output/',
});