Skip to main content

Using StackQL

See also:
[exec] [shell]

StackQL has several usage modes, these include: the StackQL interactive shell, the StackQL command line using StackQL statements, or executing one or more StackQL statements in an input file (IQL file). Each of the modes is described in more detail below:

Using the StackQL Interactive Shell

The StackQL Shell provides an interactive programming environment for engineers to deploy and interact with cloud resources, as well as enabling interactive analysis (using SELECT statements) of their cloud environment. The shell is functionally similar to the MySQL shell or other REPL (Read Evaluate Print Loop) shells. The shell accepts valid StackQL statements, and returns results to the user. Statements can span multiple lines and are executed once a semicolon terminator is entered.

The StackQL shell can be invoked using the shell command as shown below (see StackQL Provider Registry) for information about provider authentication:

# Launching the StackQL Interactive Shell
stackql shell --auth="${AUTH}"

Once in a shell authenticated to a cloud provider, you can begin running StackQL queries (SELECT queries or DDL - Infrastructure as Code - operations).

By default the StackQL shell will return tabular results, however json, csv and text output formats are available using the --output flag, see Output Modes.

You can change the color scheme for the StackQL shell using the --colorscheme flag, as shown below:

# Changing the Shell Color Scheme
./stackql shell --colorscheme light

The .stackqlrc Initialization File

Defaults for StackQL command options, such as the output format and color scheme discussed previously, can be set using the stackqlrc initialization file. If this file exists in the current directory used by the StackQL executable it will be automatically loaded, or alternatively can be referenced using the --configfile flag as shown below:

# Specifing a Initialization (.stackqlrc) File
./stackql shell --configfile /tmp/.stackqlrc

More information about command options is available in the Global Flags topic.

Using the StackQL Command Line Utility

StackQL commands can be executed non-interactively using the exec command of the StackQL executable. More than one command can be executed in a batch provided each discrete command is terminated with a semicolon (;). Command flags, such as the --output flag, can be specified at the command line or using the .stackqlrc initialization file discussed previously.

The output from the StackQL executable is sent to stdout on the system being used, this output can be parsed within a BASH or PowerShell script.

An example of a Windows PowerShell script including an StackQL command is shown here:

$gcp_project = "stackql-demo"
$gcp_zone = "australia-southeast1-a"
$keyfilepath = "C:\tmp\stackql-demo.json"

Write-Output "Selecting instances in ${gcp_zone}..."

$query = "`"select id, name, machineType `
from compute.instances `
where project = '${gcp_project}' `
and zone = '${gcp_zone}';`""
$flags = "--keyfilepath ${keyfilepath} --output json"
$cmd = "stackql.exe exec"

$select = $cmd, $query, $flags -join " "

(iex $select | ConvertFrom-Json) | Out-GridView -Title 'StackQL Query Results'

The above PowerShell command demonstrates selecting Compute Engine instances displaying the output using Out-GridView.

Using an Input File (IQL File)

StackQL input files can be used to execute several commands terminated by semicolons. This is another option for non-interactive or batch infrastructure programming. An input file is specified with the -i or --infile option as shown below:

# create an iql file
echo "select id, name from compute.instances \
where project = 'stackql-demo' \
and zone = 'australia-southeast1-a'" > listinstances.iql
# execute an iql file
./stackql exec -i listinstances.iql \
--keyfilepath /mnt/c/tmp/stackql-demo.json \
--output json | jq '.[] | .name'