# 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.

```json
{
  "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`:

```typescript
/**
 * 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:

```typescript
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/',
});
```