Skip to main content

Getting started with StackQL

This tutorial goes from installation to live queries in three stages: an unauthenticated query against public GitHub data (no credentials needed), schema discovery with the meta-commands, and an authenticated cloud query against AWS.

1. Install​

macOS (Homebrew):

brew install stackql

Linux:

curl -L https://bit.ly/stackql-zip -O && unzip stackql-zip

Windows, packages, and Docker images are covered on the downloads page. Verify with stackql --version, then start the interactive shell:

stackql shell

2. First query - no credentials required​

Pull the GitHub provider and query a public organization:

REGISTRY PULL github;

SELECT name, description, language, stargazers_count
FROM github.repos.repos
WHERE org = 'stackql';

The rows that come back - including the stackql engine repository itself - are live GitHub API responses relationalized at query time. Nothing was synced, cached, or imported. (Unauthenticated GitHub access is limited to 60 requests per hour; a personal access token raises this.)

3. Discover the schema​

The provider surface is self-describing - this is how you (or an AI agent) learn what is queryable without reading provider documentation:

SHOW PROVIDERS;                        -- installed providers
SHOW SERVICES IN github;               -- services in a provider
SHOW RESOURCES IN github.repos;        -- tables in a service
SHOW METHODS IN github.repos.repos;    -- operations + required parameters
DESCRIBE github.repos.repos;           -- columns

SHOW METHODS is the one to remember: its RequiredParams column tells you exactly what each operation needs in the WHERE clause, and which SQL verb (SELECT, INSERT, UPDATE, DELETE, EXEC) invokes it.

4. Query a cloud provider​

Export credentials (AWS shown; Azure and Google Cloud are equivalent), pull the provider, and query:

export AWS_ACCESS_KEY_ID=YOURACCESSKEYID
export AWS_SECRET_ACCESS_KEY=YOURSECRETACCESSKEY
REGISTRY PULL aws;

SELECT instance_id, instance_type, launch_time
FROM aws.ec2.instances
WHERE region = 'us-east-1';

Aggregations fan out automatically - this runs as parallel per-region API calls:

SELECT region, COUNT(*) as num_instances
FROM aws.ec2.instances
WHERE region IN ('us-east-1','us-west-2','eu-west-1')
GROUP BY region;

5. Where to go next​

  • Mutations: SHOW INSERT INTO <resource> generates creation templates; INSERT/UPDATE/DELETE operate on the same tables you query.
  • Server mode: stackql srv exposes the PostgreSQL wire protocol for psql, DBeaver, BI tools, and pandas.
  • AI agents: stackql mcp runs the built-in MCP server - see How to use StackQL with AI agents.
  • Python: pip install pystackql for notebook and pipeline use.