<div align="center">

badge3 badge4

</div> <div align="center">

homebrew downloads homebrew version GitHub Downloads (all assets, all releases) GitHub Release Docker Pulls Docker Image Version Chocolatey Downloads Chocolatey Version PyPI - Downloads

</div> <div align="center">

Deploy, manage and query cloud resources and interact with APIs using SQL

<p align="center">

Read the docs »
Raise an Issue · Request a Feature · Developer Guide · BYO Providers

</p> </div> <details open="open"> <summary>Contents</summary> <ol> <li><a href="#about-the-project">About The Project</a></li> <li><a href="#installation">Installation</a></li> <li><a href="#usage">Usage</a></li>  <li><a href="#contributing">Contributing</a></li> <li><a href="#license">License</a></li> <li><a href="#contact">Contact</a></li> <li><a href="#acknowledgements">Acknowledgements</a></li> </ol> </details>

About The Project

StackQL is an open-source project built with Golang that allows you to create, modify and query the state of services and resources across different local and remote interfaces, using SQL semantics. Such interfaces canonically include, but are not limited to, cloud and SaaS providers (Google, AWS, Azure, Okta, GitHub, etc.). <br /> <br />

stackql-shell

How it works

StackQL is a standalone application that can be used in client mode (via exec or shell) or accessed via a Postgres wire protocol client (psycopg2, etc.) using server mode (srv).

StackQL parses SQL statements and transpiles them into API requests to the (cloud) resource provider. The API calls are then executed and the results are returned to the user.

StackQL provider interfaces are canonically defined in OpenAPI extensions to the providers' specification. These definitions are then used to generate the SQL schema and the API client. The source for the provider definitions are stored in the StackQL Registry. The semantics of provider interactions are defined in our any-sdk library. For more detail on nuts and bolts, please see the local AGENTS.md file and that of any-sdk.

<details> <summary><b>StackQL Context Diagram</b></summary> <br /> The following context diagram describes the StackQL architecture at a high level:

flowchart LR
  subgraph StackQL
    direction BT
    subgraph ProviderDefs
        Registry[Provider Registry Docs]    
    end
    subgraph App
        Proc[$ stackql exec\n$ stackql shell\n$ stackql srv]
        style Proc fill:#000,stroke:#000,color:#fff,text-align:left;

        %% ,font-family:'Courier New', Courier, monospace
    end
  end
  User((User)) <--> StackQL <--> Provider[Cloud Provider API]
  ProviderDefs --> App

More detailed design documentation can be found in the here.

</details>

Installation

StackQL is available for Windows, MacOS, Linux, Docker, GitHub Actions and more. See the installation instructions below for your platform.

<details> <summary><b>Installing on MacOS</b></summary>

Homebrew (amd64 and arm64)
- brew install stackql or brew tap stackql/tap && brew install stackql/tap/stackql
MacOS PKG Installer (amd64 and arm64)
- download the latest MacOS PKG installer for StackQL
- run the installer and follow the prompts

</details> <details> <summary><b>Installing on Windows</b></summary>

MSI Installer
- download the latest MSI installer for StackQL
- run the installer and follow the prompts
Chocolatey
- install Chocolatey
- run choco install stackql
ZIP Archive
- download the latest Windows ZIP archive for StackQL
- extract the archive (code signed stackql.exe file) to a directory of your choice
- add the directory to your PATH environment variable (optional)

</details> <details> <summary><b>Installing on Linux</b></summary>

ZIP Archive
- download the latest Linux ZIP archive for StackQL
  - or via curl -L https://bit.ly/stackql-zip -O && unzip stackql-zip
- extract the archive (stackql file) to a directory of your choice
- add the directory to your PATH environment variable (optional)

</details> <details> <summary><b>Getting StackQL from DockerHub</b></summary>

View all available StackQL images on DockerHub. Images available include stackql, stackql-jupyter-demo and more. Pull the latest StackQL base image using:

docker pull stackql/stackql

</details> <details> <summary><b>Using StackQL with GitHub Actions</b></summary>

Use StackQL in your GitHub Actions workflows to automate cloud infrastructure provisioning, IaC assurance, or compliance/security. Available GitHub Actions include: setup-stackql, stackql-exec and more

</details>

Usage

StackQL can be used via the interactive REPL shell, or via the exec command or ran as a server using the Postgres wire protocol.

ℹ️ StackQL does not require or install a database.

Interactive Shell

# run interactive stackql queries
stackql shell --auth="${AUTH}"

Execute a statement or file
```
stackql exec --auth="${AUTH}" -i myscript.iql --iqldata vars.jsonnet --output json

# or

stackql exec --auth="${AUTH}" "SELECT id, status FROM aws.ec2.instances WHERE region = 'us-east-1'"
```
ℹ️ output options of json, csv, table and text are available for the exec command using the --output flag

ℹ️ StackQL supports passing parameters using jsonnet or json, see Using Variables

Server

# serve client requests over the Postgres wire protocol (psycopg2, etc.) 
stackql srv --auth="${AUTH}"

For more examples, please check our Blog

Contributing

Contributions are welcome and encouraged. For more information on how to contribute, please see our contributing guide.

License

Distributed under the MIT License. See LICENSE for more information. Licenses for third party software we are using are included in the /docs/licenses directory.

Contact

Get in touch with us via Twitter at @stackql, email us at info@stackql.io or start a convers

Stackql

Install / Use

README