StackQL: querying cloud and SaaS APIs with SQL, and what that costs you

The gap StackQL fills between curl, SDKs and Terraform

Most teams end up with three ways to touch a cloud account. An SDK for application code, a CLI for humans, and a declarative tool for provisioning. None of them is good at ad hoc questions that span providers, such as listing every storage bucket in a project alongside the identity provider groups that can reach it. StackQL targets that gap. The README describes it as an open-source Go project that lets you create, modify and query the state of services and resources across local and remote interfaces using SQL semantics, with cloud and SaaS providers such as Google, AWS, Azure, Okta and GitHub named as canonical examples. The audience is infrastructure and security engineers who already think in SQL, plus the newer case of AI agents that need a constrained interface to cloud operations. The project's own framing is configuration-as-data and infrastructure-as-context, which is a fair description of what SQL gives you here: a uniform way to address resources and a result set you can join, filter and pipe.

How a SELECT becomes an API request

StackQL is a standalone application with two modes. In client mode you use exec or shell. In server mode you run srv and connect with a Postgres wire protocol client such as psycopg2. The README states the core mechanism plainly: StackQL parses SQL statements and transpiles them into API requests to the resource provider, then executes those calls and returns the results. Provider interfaces are defined as OpenAPI extensions to the providers' specifications, and those definitions generate both the SQL schema and the API client. The definitions themselves live in the stackql-provider-registry repository, and the semantics of provider interaction are implemented in the any-sdk library. That split matters when you debug something. A missing column or an unexpected HTTP method is usually a provider definition problem in the registry, not a bug in the engine. The go.mod file confirms the shape of the system: a stackql-parser module, any-sdk, a psql-wire fork for server mode, and the official modelcontextprotocol/go-sdk for the MCP side. The repository also ships a Dockerfile that builds with go build and a docker-compose.yml whose stackqlsrv service runs the binary with an --auth JSON document, a --registry URL and --pgsrv settings, which is the clearest picture of how the pieces are wired at runtime.

Installing StackQL and running a first query

The README links platform packages rather than documenting a build from source for end users. For macOS there is a multiarch pkg, for Windows an msi and a zip, and for Linux a zip. The project also publishes a container image, stackql/stackql, on Docker Hub. Pick the artifact for your platform and install it as you would any signed package. If you would rather not install anything, the container is the shorter path.

The Docker Hub image is the one the repository itself uses in docker-compose.yml, so it is the best documented route. The compose file runs the binary with subcommands, and the README names exec and shell for client mode and srv for server mode. Authentication is passed as a JSON document through --auth. The compose file shows the expected shape for each provider, with a type field and either credentialsenvvar or credentialsfilepath. A Google service account entry looks like this:

{
  "google": {
    "credentialsfilepath": "/opt/stackql/credentials/dummy/google/functional-test-dummy-sa-key.json",
    "type": "service_account"
  }
}

Provider definitions are resolved from a registry URL. The compose file points at a CDN copy of the stackql-provider-registry with a verifyConfig block containing nopVerify. Once a provider is pulled, the workflow is a normal SQL session: you select from a provider-namespaced table, and the engine issues the underlying HTTP calls on your behalf. Expect the first run to spend time fetching provider definitions before anything returns rows.

Server mode and the MCP surface are the parts to scrutinise

Two integrations carry most of StackQL's current positioning, and both deserve more caution than the README gives them. The first is server mode. Running srv exposes a Postgres wire endpoint, and the compose file shows it bound to 0.0.0.0 on a configurable port, with TLS material supplied through --pgsrv.tls as key and cert file paths plus a list of client CAs. That is a real database endpoint pointed at your cloud credentials. Anyone who can authenticate to it can issue statements that the engine will translate into API calls with your identity. The README does not document a read-only mode, statement allowlisting or per-user scoping, so treat network placement and the client CA list as the primary control. The second is the MCP server, published as @stackql/mcp-server on npm and listed in the MCP registry. It lets an agent drive the same SQL surface. That is a narrower interface than handing an agent raw API credentials, but it is not a safety layer: the agent still composes statements, and the engine still executes them. Neither the README nor the repository layout shows a policy engine between the two.

Where StackQL is the wrong tool

StackQL is imperative. You write the statement, it runs, and it returns. If a resource drifts after your statement completes, StackQL has no opinion about it. Teams that want a controller watching for drift, computing a plan and converging state should use a declarative tool instead. The same applies to provisioning sequences with ordering and dependency graphs: you can express them as a series of statements, but you own the ordering, the failure handling and the retry logic. A second limitation is provider coverage. Everything the engine can address comes from OpenAPI extensions held in the registry, so a resource that no provider definition describes simply is not queryable, no matter how the underlying API works. Before you design around StackQL, check the registry for the specific resources you need rather than assuming a provider's full surface is present. Third, the README is a front door, not a reference: it points at the docs site, the developer guide, the high-level design document and an AGENTS.md file in the repository root for the details. Installation and first-run material in the README itself is thin, mostly links to download artifacts.

StackQL compared with a declarative provisioning tool

The closest mental comparison is Terraform or Pulumi, and the difference is in the execution model rather than the provider list. A declarative tool stores desired state, reads actual state, and reconciles the two, which is why it can detect and correct drift and why it can plan a change before applying it. StackQL holds no state. It transpiles a statement, calls the API and returns rows. That makes it weaker for lifecycle management and stronger for interrogation: joining results across providers, filtering on attributes, and running the same query shape against several accounts. The two are not mutually exclusive. A reasonable split is to provision with a declarative tool and audit with StackQL, because the audit question usually spans providers and does not fit any single tool's state file. The trade-off is real in both directions. You give up drift correction and plan output. In exchange you get a query language and a result set, plus a Postgres endpoint that existing BI and notebook tooling can already talk to.

Licence, release cadence and upgrade cost

StackQL is MIT licensed, which permits commercial use and modification with the usual requirement to carry the licence and copyright notice. That is permissive and low friction, but it says nothing about the provider definitions in the registry, which is a separate repository with its own licensing. If you redistribute StackQL or embed it in a product, check the registry's terms separately rather than assuming MIT covers the whole stack. On maintenance, the last push to the default branch was on 2026-09-09, and the most recent releases listed are v0.11.669 on 2026-09-08, v0.10.605 on 2026-08-19 and v0.10.601 on 2026-08-15. The version numbering is worth noting: the jump from 0.10 to 0.11 arrived within a month of the 0.10 releases, and the project is still on a 0.x line. Pre-1.0 versioning means minor releases can carry breaking changes, so pin the version you deploy and read the release notes before moving. Your upgrade cost also depends on the registry: provider definitions change independently of the binary, and a definition update can alter the schema your queries are written against.

Editorial conclusion

Adopt StackQL if you need to read state across several providers in one language, or if you are exposing cloud operations to an LLM through MCP and want a typed, SQL-shaped surface instead of free-form API calls. Do not adopt it if you expect a declarative desired-state engine that converges resources on its own; StackQL executes the statements you write and does not reconcile them. Before committing, verify three things against the docs: which providers in the registry cover the resources you actually touch, how credentials are stored on your platform, and whether the Postgres wire server mode meets your connection and TLS requirements.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. stackql/stackql on GitHub