Skip to main content

How to authenticate StackQL to AWS

StackQL authenticates to AWS using the standard AWS credential environment variables. Set them before starting a StackQL shell, exec command, server, or MCP server; no configuration file is required.

Steps​

  1. Create or identify an IAM principal (user or role) with the permissions your queries need. For read-only querying, the ReadOnlyAccess managed policy or a narrower equivalent is sufficient.

  2. Export the credentials as environment variables:

export AWS_ACCESS_KEY_ID=YOURACCESSKEYID
export AWS_SECRET_ACCESS_KEY=YOURSECRETACCESSKEY

For temporary credentials (an assumed role via sts assume-role, or an AWS CloudShell session, which sets these automatically), the session token is exported as well:

export AWS_SESSION_TOKEN=YOURSESSIONTOKEN
  1. Pull the AWS provider (first use only):
REGISTRY PULL aws;
  1. Verify with a query:
SELECT instance_id, instance_type
FROM aws.ec2.instances
WHERE region = 'us-east-1';

A successful result set confirms authentication. Note that AWS queries require a region predicate in the WHERE clause - this is a routing parameter, not a credential setting.

Where the variables apply​

The same environment variables work in every StackQL execution mode:

  • Interactive shell: stackql shell
  • Batch: stackql exec "..."
  • Server mode: stackql srv (PostgreSQL wire protocol)
  • MCP server: stackql mcp, or via the env block of an MCP client configuration such as claude_desktop_config.json

In CI systems, source the variables from the platform's secret store rather than hardcoding them. Metadata operations (SHOW, DESCRIBE, REGISTRY) work without credentials; only data operations (SELECT, INSERT, UPDATE, DELETE, EXEC) require an authenticated session.