SQ(1)

NAME
sq - sq

SYNOPSIS
sq [options...] [argument...]

DESCRIPTION
sq is a swiss-army knife for wrangling data.

  $ sq '@sakila_pg | .actor | where(.actor_id > 2) | .first_name, .last_name | .[0:10]'

Use sq to query Postgres, SQLite, SQLServer, MySQL, CSV, Excel, etc,

and output in text, JSON, CSV, Excel and so on, or write output to a

database table.

You can query using sq's own jq-like syntax, or in native SQL.

Use "sq inspect" to view schema metadata. Use the "sq tbl" commands

to copy, truncate and drop tables. Use "sq diff" to compare source

metadata and row data.

See docs and more: https://sq.io

OPTIONS

-c, --compact
    Compact instead of pretty-printed output

--config
    Load config from here

-C, --csv
    Output CSV

--debug.pprof
    pprof profiling mode

--driver.csv.delim
    Delimiter for ingest CSV data

--driver.csv.empty-as-null
    Treat ingest empty CSV fields as NULL

--error.format
    Error output format

-E, --error.stack
    Print error stack trace to stderr

-f, --format
    Specify output format

--format.date
    Date format: constant such as DateOnly or a strftime format

--format.date.number
    Render numeric date value as number instead of string

--format.datetime
    Timestamp format: constant such as RFC3339 or a strftime format

--format.datetime.number
    Render numeric datetime value as number instead of string

--format.excel.date
    Date format string for Excel date-only values

--format.excel.datetime
    Timestamp format string for Excel datetime values

--format.excel.time
    Time format string for Excel time-only values

--format.time
    Time format: constant such as TimeOnly or a strftime format

--format.time.number
    Render numeric time value as number instead of string

-h, --header
    Print header row

--help
    Show help

--html
    Output HTML table

--ingest.driver
    Explicitly specify driver to use for ingesting data

--ingest.header
    Ingest data has a header row

-i, --input
    Read input from <file> instead of stdin

--insert
    Insert query results into @HANDLE.TABLE; if not existing, TABLE will be created

-j, --json
    Output JSON

-A, --jsona
    Output LF-delimited JSON arrays

-J, --jsonl
    Output LF-delimited JSON objects

--log
    Enable logging

--log.file
    Log file path

--log.format
    Log output format (text or json)

--log.level
    Log level, one of: DEBUG, INFO, WARN, ERROR

--markdown
    Output Markdown

-M, --monochrome
    Don't print color output

--no-cache
    Don't cache ingest data

-H, --no-header
    Don't print header row

--no-progress
    Don't show progress bar

--no-redact
    Don't redact passwords in output

-o, --output
    Write output to <file> instead of stdout

-r, --raw
    Output each record field in raw format without any encoding or delimiter

--src
    Override active source for this query

--src.schema
    Override active schema (and/or catalog) for this query

-t, --text
    Output text

--tsv
    Output TSV

-v, --verbose
    Print verbose output

--version
    Print version info

-x, --xlsx
    Output Excel XLSX

--xml
    Output XML

-y, --yaml
    Output YAML

COMMANDS

add [--handle @HANDLE] LOCATION
    Add data source

OPTIONS
    -a, --active Make this the active source

    -c, --compact
        Compact instead of pretty-printed output

    -d, --driver
        Explicitly specify driver to use

    --driver.csv.delim
        Delimiter for ingest CSV data

    --driver.csv.empty-as-null
        Treat ingest empty CSV fields as NULL

    -n, --handle
        Handle for the source

    -h, --header
        Print header row

    --help
        help for add

    --ingest.header
        Ingest data has a header row

    -j, --json
        Output JSON

    -H, --no-header
        Don't print header row

    -p, --password
        Read password from stdin or prompt

    --skip-verify
        Don't ping source before adding it

    -t, --text
        Output text

    -y, --yaml
        Output YAML

EXAMPLES

    When adding a data source, LOCATION is the only required arg.

      $ sq add ./actor.csv

      @actor csv actor.csv

    Note that sq generated the handle "@actor". But you can explicitly specify

    a handle.

      # Add a postgres source with handle "@sakila/pg"

      $ sq add --handle @sakila/pg postgres://user:pass@localhost/sakila

    This handle format "@sakila/pg" includes a group, "sakila". Using a group

    is entirely optional: it is a way to organize sources. For example:

      $ sq add --handle @dev/pg postgres://user:pass@dev.db.acme.com/sakila

      $ sq add --handle @prod/pg postgres://user:pass@prod.db.acme.com/sakila

    The format of LOCATION is driver-specific, but is generally a DB connection

    string, a file path, or a URL.

      DRIVER://USER:PASS@HOST:PORT/DBNAME?PARAM=VAL

      /path/to/local/file.ext

      https://sq.io/data/test1.xlsx

    If LOCATION contains special shell characters, it's necessary to enclose

    it in single quotes, or to escape the special character. For example,

    note the "\?" in the unquoted location below.

      $ sq add postgres://user:pass@localhost/sakila\?sslmode=disable

    A significant advantage of not quoting LOCATION is that sq provides extensive

    shell completion when inputting the location value.

    If flag --handle is omitted, sq will generate a handle based

    on LOCATION and the source driver type.

    It's a security hazard to expose the data source password via

    the LOCATION string. If flag --password (-p) is set, sq prompt the

    user for the password:

      $ sq add postgres://user@localhost/sakila -p

      Password: ****

    However, if there's input on stdin, sq will read the password from

    there instead of prompting the user:

      # Add a source, but read password from an environment variable

      $ export PASSWD='open:;"_Ses@me'

      $ sq add postgres://user@localhost/sakila -p <<< $PASSWD

      # Same as above, but instead read password from file

      $ echo 'open:;"_Ses@me' > password.txt

      $ sq add postgres://user@localhost/sakila -p < password.txt

    There are various driver-specific options available. For example:

      $ sq add actor.csv --ingest.header=false --driver.csv.delim=colon

    If flag --driver is omitted, sq will attempt to determine the

    type from LOCATION via file suffix, content type, etc. If the result

    is ambiguous, explicitly specify the driver type.

      $ sq add --driver=tsv ./mystery.data

    Available source driver types can be listed via "sq driver ls". At a

    minimum, the following drivers are bundled:

      sqlite3 SQLite

      postgres PostgreSQL

      sqlserver Microsoft SQL Server / Azure SQL Edge

      mysql MySQL

      clickhouse ClickHouse

      csv Comma-Separated Values

      tsv Tab-Separated Values

      json JSON

      jsona JSON Array: LF-delimited JSON arrays

      jsonl JSON Lines: LF-delimited JSON objects

      xlsx Microsoft Excel XLSX

    DRIVER NOTES:

    The clickhouse driver will automatically apply a default port if not

    specified: 9000 for non-secure, or 9440 for secure (when "secure=true"

    is in the connection string). This differs from the underlying clickhouse-go

    library, which does not apply a default port.

    If there isn't already an active source, the newly added source becomes the

    active source (but the active group does not change). Otherwise you can

    use flag --active to make the new source active.

    More examples:

      # Add a source, but prompt user for password

      $ sq add postgres://user@localhost/sakila -p

      Password: ****

      # Explicitly set flags

      $ sq add --handle @sakila_pg --driver postgres postgres://user:pass@localhost/sakila

      # Same as above, but with short flags

      $ sq add -n @sakila_pg -d postgres postgres://user:pass@localhost/sakila

      # Specify some params (note escaped chars)

      $ sq add postgres://user:pass@localhost/sakila\?sslmode=disable\&application_name=sq

      # Specify some params, but use quoted string (no shell completion)

      $ sq add 'postgres://user:pass@localhost/sakila?sslmode=disable&application_name=sq''

      # Add a SQL Server source; will have generated handle @sakila

      $ sq add 'sqlserver://user:pass@localhost?database=sakila'

      # Add a SQLite DB, and immediately make it the active source

      $ sq add ./testdata/sqlite1.db --active

      # Add an Excel spreadsheet, with options

      $ sq add ./testdata/test1.xlsx --ingest.header=true

      # Add a CSV source, with options

      $ sq add ./testdata/person.csv --ingest.header=true

      # Add a CSV source from a URL (will be downloaded)

      $ sq add https://sq.io/testdata/actor.csv

      # Add a source, and make it the active source (and group)

      $ sq add ./actor.csv --handle @csv/actor

      # Add a currently unreachable source

      $ sq add postgres://user:pass@db.offline.com/sakila --skip-verify

cache
    Manage cache

OPTIONS
    --help help for cache

COMMANDS
    clear [@HANDLE]
        Clear cache

    OPTIONS
        --help help for clear

    EXAMPLES
          # Clear entire cache

          $ sq cache clear

          # Clear cache for @sakila

          $ sq cache clear @sakila

    disable [@HANDLE]
        Disable caching

    OPTIONS
        --help help for disable

    EXAMPLES
          # Disable caching by default

          $ sq cache disable

          # Disable caching for a particular source

          $ sq cache disable @sakila

    enable [@HANDLE]
        Enable caching

    OPTIONS
        --help help for enable

    EXAMPLES
          # Enable caching by default

          $ sq cache enable

          # Enable caching for a particular source

          $ sq cache enable @sakila

    location
        Print cache location

    OPTIONS
        -h, --header Print header row

        --help
            help for location

        -j, --json
            Output JSON

        -H, --no-header
            Don't print header row

        -t, --text
            Output text

        -y, --yaml
            Output YAML

    EXAMPLES
          $ sq cache location

          /Users/neilotoole/Library/Caches/sq/f36ac695

    stat
        Show cache info

    OPTIONS
        -h, --header Print header row

        --help
            help for stat

        -j, --json
            Output JSON

        -H, --no-header
            Don't print header row

        -t, --text
            Output text

        -y, --yaml
            Output YAML

    EXAMPLES
          $ sq cache stat

          /Users/neilotoole/Library/Caches/sq/f36ac695 enabled (472.8MB)

    tree
        Print tree view of cache dir

    OPTIONS
        --help help for tree

        -s, --size
            Show sizes in cache tree

    EXAMPLES
          # Print cache tree

          $ sq cache tree

          # Print cache tree with sizes

          $ sq cache tree --size

EXAMPLES
      # Print cache location.

      $ sq cache location

      # Show cache info.

      $ sq cache stat

      $ sq cache enable

      $ sq cache disable

      # Disable cache for an individual source.

      $ sq cache disable @sakila

      $ sq cache clear

      $ sq cache clear @sakila

      # Print tree view of cache dir.

      $ sq cache tree

completion
    Generate the autocompletion script for the specified shell

COMMANDS
    bash
        Generate the autocompletion script for bash

    fish
        Generate the autocompletion script for fish

    powershell
        Generate the autocompletion script for powershell

    zsh
        Generate the autocompletion script for zsh

config
    Manage config

OPTIONS
    --help help for config

COMMANDS
    edit [@HANDLE]
        Edit config in $EDITOR

    OPTIONS
        --help help for edit

    EXAMPLES
          # Edit default options

          $ sq config edit

          # Edit default options, but show additional help/context.

          $ sq config edit -v

          # Edit config for source @sakila

          $ sq config edit @sakila

          # Same as above, with additional help/context.

          $ sq config edit @sakila -v

          # Use a different editor

          $ SQ_EDITOR=nano sq config edit

    get
        Show config option

    OPTIONS
        -c, --compact Compact instead of pretty-printed output

        -h, --header
            Print header row

        --help
            help for get

        -j, --json
            Output JSON

        -H, --no-header
            Don't print header row

        --src
            Config for source

        -t, --text
            Output text

        -y, --yaml
            Output YAML

    EXAMPLES
          # Show individual base option

          $ sq config get conn.max-open

          # Show more detail, in YAML

          $ sq config get conn.max-open -yv

          # Show option for src

          $ sq config get --src @sakila conn.max-open

    location
        Print config location

    OPTIONS
        -h, --header Print header row

        --help
            help for location

        -j, --json
            Output JSON

        -H, --no-header
            Don't print header row

        -t, --text
            Output text

        -y, --yaml
            Output YAML

    EXAMPLES
          # Print config location

          $ sq config location

          /Users/neilotoole/.config/sq

          # Print location, also show origin (flag, env, default)

          $ sq config location -v

          /Users/neilotoole/.config/sq

          Origin: env

    ls [--src @HANDLE]
        List config options

    OPTIONS
        -c, --compact Compact instead of pretty-printed output

        -h, --header
            Print header row

        --help
            help for ls

        -j, --json
            Output JSON

        -H, --no-header
            Don't print header row

        --src
            Config for source

        -t, --text
            Output text

        -y, --yaml
            Output YAML

    EXAMPLES
          # Show base config

          $ sq config ls

          # Also show defaults and unset options

          $ sq config ls -v

          # Show all config in YAML

          $ sq config ls -yv

          # Show config for source

          $ sq config ls --src @sakila

          # Show config for source, including defaults and unset options

          $ sq config ls --src @sakila -v

          # Show config for active source

          $ sq config ls --src @active

    set OPTION VALUE
        Set config value

    OPTIONS
        -c, --compact Compact instead of pretty-printed output

        -D, --delete
            Reset this option to default value

        -h, --header
            Print header row

        --help
            help for set

        -j, --json
            Output JSON

        -H, --no-header
            Don't print header row

        --src
            Config for source

        -t, --text
            Output text

        -y, --yaml
            Output YAML

    EXAMPLES
          # Set base output format

          $ sq config set format json

          # Set base max DB connections

          $ sq config set conn.max-open 10

          # Set max DB connections for source @sakila

          $ sq config set --src @sakila conn.max-open 50

          # Delete an option (resets to default value)

          $ sq config set -D conn.max-open

          # Help for an individual option

          $ sq config set conn.max-open --help

EXAMPLES
      # Print config location

      $ sq config location

      # Show base config

      $ sq config ls

      # Show base config including unset and default values.

      $ sq config ls -v

      # Show base config in maximum detail (YAML format)

      $ sq config ls -yv

      # Get base value of an option

      $ sq config get format

      # Get source-specific value of an option

      $ sq config get --src @sakila conn.max-open

      # Set base option value

      $ sq config set format json

      # Set source-specific option value

      $ sq config set --src @sakila conn.max-open 50

      # Help for an option

      $ sq config set format --help

      # Edit base config in $EDITOR

      $ sq config edit

      # Edit config for source in $EDITOR

      $ sq config edit @sakila

      # Delete option (reset to default value)

      $ sq config set -D log.level

db
    Useful database actions

OPTIONS
    --help help for db

COMMANDS
    dump
        Dump db catalog or cluster

    OPTIONS
        --help help for dump

    COMMANDS
        catalog @src [--print]
            Dump db catalog

        OPTIONS
            --catalog Dump the named catalog

            --help
                help for catalog

            --no-owner
                Don't set ownership or ACL

            -o, --output
                Write output to <file> instead of stdout

            --print
                Print the db-native tool command, but don't execute it

            --print-long
                Print the long-form db-native tool command, but don't execute it

        EXAMPLES
              # Dump @sakila_pg to file sakila.dump using pg_dump

              $ sq db dump catalog @sakila_pg -o sakila.dump

              # Same as above, but verbose mode, and dump via stdout

              $ sq db dump catalog @sakila_pg -v > sakila.dump

              # Dump without ownership or ACL

              $ sq db dump catalog --no-owner @sakila_pg > sakila.dump

              # Print the dump command, but don't execute it

              $ sq db dump catalog @sakila_pg --print

              # Dump a catalog (db) other than the source's current catalog

              $ sq db dump catalog @sakila_pg --catalog sales > sales.dump

        cluster @src [--print]
            Dump entire db cluster

        OPTIONS
            --help help for cluster

            --no-owner
                Don't set ownership or ACL

            -o, --output
                Write output to <file> instead of stdout

            --print
                Print the db-native tool command, but don't execute it

            --print-long
                Print the long-form db-native tool command, but don't execute it

        EXAMPLES
              # Dump all catalogs in @sakila_pg's cluster using pg_dumpall

              $ sq db dump cluster @sakila_pg -f all.dump

              # Same as above, but verbose mode and using stdout

              $ sq db dump cluster @sakila_pg -v > all.dump

              # Dump without ownership or ACL

              $ sq db dump cluster @sakila_pg --no-owner > all.dump

              # Print the dump command, but don't execute it

              $ sq db dump cluster @sakila_pg -f all.dump --print

    exec [@src] [--f SCRIPT.sql] [-c 'SQL'] [--print]
        Execute SQL script or command

    OPTIONS
        -c, --command Execute SQL command string

        -f, --file
            Read SQL from <file> instead of stdin

        --help
            help for exec

        --print
            Print the db-native tool command, but don't execute it

        --print-long
            Print the long-form db-native tool command, but don't execute it

        --src.schema
            Override active schema (and/or catalog) for this query

    EXAMPLES
          # Execute query.sql on @sakila_pg

          $ sq db exec @sakila_pg -f query.sql

          # Same as above, but use stdin

          $ sq db exec @sakila_pg < query.sql

          # Execute a command string against the active source

          $ sq db exec -c 'SELECT 777'

          777

          # Print the db-native command, but don't execute it

          $ sq db exec -f query.sql --print

          psql -d 'postgres://alice:abc123@db.acme.com:5432/sales' -f query.sql

          # Execute against an alternative catalog or schema

          $ sq db exec @sakila_pg --schema inventory.public -f query.sql

    restore
        Restore db catalog or cluster from dump

    OPTIONS
        --help help for restore

    COMMANDS
        catalog @src [--from file.dump] [--print]
            Restore db catalog from dump

        OPTIONS
            -f, --from Restore from dump file; if omitted, read from stdin

            --help
                help for catalog

            --no-owner
                Don't use ownership or ACL from dump

            -o, --output
                Write output to <file> instead of stdout

            --print
                Print the db-native tool command, but don't execute it

            --print-long
                Print the long-form db-native tool command, but don't execute it

        EXAMPLES
              # Restore @sakila_pg from backup.dump

              $ sq db restore catalog @sakila_pg -f backup.dump

              # With verbose output, and reading from stdin

              $ sq db restore catalog -v @sakila_pg < backup.dump

              # Don't use ownership from dump; the source user will own the restored objects

              $ sq db restore catalog @sakila_pg --no-owner < backup.dump

              # Print the db-native restore command, but don't execute it

              $ sq db restore catalog @sakila_pg -f backup.dump --print

        cluster @src [--from file.dump] [--print]
            Restore db cluster from dump

        OPTIONS
            -f, --from Restore from dump file; if omitted, read from stdin

            --help
                help for cluster

            --no-owner
                Don't use ownership or ACL from dump

            -o, --output
                Write output to <file> instead of stdout

            --print
                Print the db-native tool command, but don't execute it

            --print-long
                Print the long-form db-native tool command, but don't execute it

        EXAMPLES
              # Restore @sakila_pg from backup.dump

              $ sq db restore cluster @sakila_pg -f backup.dump

              # With verbose output, and reading from stdin

              $ sq db restore cluster -v @sakila_pg < backup.dump

              # Don't use ownership from dump; the source user will own the restored objects

              $ sq db restore cluster @sakila_pg --no-owner < backup.dump

              # Print the db-native restore command, but don't execute it

              $ sq db restore cluster @sakila_pg -f backup.dump --print

EXAMPLES
      # TBD

diff @HANDLE1[.TABLE] @HANDLE2[.TABLE] [--data]
    BETA: Compare sources, or tables

OPTIONS
    -a, --all Compare everything (caution: may be slow)

    -N, --counts
        When comparing table schema structure, include row counts

    -d, --data
        Compare values of each data row (caution: may be slow)

    -B, --dbprops
        Compare DB properties

    -f, --format
        Output format (json, csv…) when comparing data

    --help
        help for diff

    --no-cache
        Don't cache ingest data

    -O, --overview
        Compare source overview

    -S, --schema
        Compare schema structure

    -n, --stop
        Stop after <n> differences

    -U, --unified
        Generate diffs with <n> lines of context

EXAMPLES
      Metadata diff

      -------------

      # Diff sources (compare default elements).

      $ sq diff @prod/sakila @staging/sakila

      # As above, but show 7 lines surrounding each diff.

      $ sq diff @prod/sakila @staging/sakila -U7

      # Diff sources, but only compare source overview.

      $ sq diff @prod/sakila @staging/sakila --overview

      # Diff sources, but only DB properties.

      $ sq diff @prod/sakila @staging/sakila --dbprops

      # Compare source overview, and DB properties.

      $ sq diff @prod/sakila @staging/sakila -OB

      # Diff sources, but only compare schema.

      $ sq diff @prod/sakila @staging/sakila --schema

      # Compare schema table structure, and row counts.

      $ sq diff @prod/sakila @staging/sakila --SN

      # Compare everything, including table data. Caution: can be slow.

      $ sq diff @prod/sakila @staging/sakila --all

      # Compare metadata of actor table in prod vs staging.

      $ sq diff @prod/sakila.actor @staging/sakila.actor

      Row data diff

      -------------

      # Compare data in the actor tables, stopping at the first difference.

      $ sq diff @prod/sakila.actor @staging/sakila.actor --data --stop 1

      # Compare data in the actor tables, but output in JSONL.

      $ sq diff @prod/sakila.actor @staging/sakila.actor --data --format jsonl

      # Compare data in all tables and views. Caution: may be slow.

      $ sq diff @prod/sakila @staging/sakila --data --stop 0

driver
    Manage drivers

OPTIONS
    --help help for driver

COMMANDS
    ls
        List installed drivers

    OPTIONS
        -c, --compact Compact instead of pretty-printed output

        -h, --header
            Print header row

        --help
            help for ls

        -j, --json
            Output JSON

        -H, --no-header
            Don't print header row

        -t, --text
            Output text

        -y, --yaml
            Output YAML

EXAMPLES
      # List drivers

      $ sq driver ls

group [GROUP]
    Get or set active group

OPTIONS
    -c, --compact Compact instead of pretty-printed output

    -h, --header
        Print header row

    --help
        help for group

    -j, --json
        Output JSON

    -H, --no-header
        Don't print header row

    -t, --text
        Output text

    -y, --yaml
        Output YAML

EXAMPLES
      # Get active group ("dev" in this case).

      $ sq group

      dev

      # Set "prod" as active group

      $ sq group prod

      prod

      # Reset to the root group

      $ sq group /

      /

inspect [@HANDLE|@HANDLE.TABLE|.TABLE]
    Inspect data source schema and stats

OPTIONS
    -C, --catalogs List catalogs only

    -c, --compact
        Compact instead of pretty-printed output

    -p, --dbprops
        Show DB properties only

    -h, --header
        Print header row

    --help
        help for inspect

    -i, --input
        Read input from <file> instead of stdin

    -j, --json
        Output JSON

    --no-cache
        Don't cache ingest data

    -H, --no-header
        Don't print header row

    -O, --overview
        Show metadata only (no schema)

    -S, --schemata
        List schemas (in current catalog) only

    --src.schema
        Override active schema (and/or catalog) for this query

    -t, --text
        Output text

    -y, --yaml
        Output YAML

EXAMPLES
      # Inspect active data source.

      $ sq inspect

      # Inspect @pg1 data source.

      $ sq inspect @pg1

      # Inspect @pg1 data source, showing verbose output.

      $ sq inspect -v @pg1

      # Show output in JSON (useful for piping to jq).

      $ sq inspect --json @pg1

      # Show output in YAML.

      $ sq inspect --yaml @pg1

      # Show only the DB properties for @pg1.

      $ sq inspect --dbprops @pg1

      # Show only the source metadata (and not schema details).

      $ sq inspect --overview @pg1

      # List the schemas in @pg1.

      $ sq inspect --schemata @pg1

      # List the catalogs in @pg1.

      $ sq inspect --catalogs @pg1

      # Inspect table "actor" in @pg1 data source.

      $ sq inspect @pg1.actor

      # Inspect "actor" in active data source.

      $ sq inspect .actor

      # Inspect a non-default schema in source @my1.

      $ sq inspect @my1 --src.schema information_schema

      # Inspect piped data.

      $ cat data.xlsx | sq inspect

ls [GROUP]
    List sources and groups

OPTIONS
    -c, --compact Compact instead of pretty-printed output

    -g, --group
        List groups instead of sources

    -h, --header
        Print header row

    --help
        help for ls

    -j, --json
        Output JSON

    -H, --no-header
        Don't print header row

    -t, --text
        Output text

    -y, --yaml
        Output YAML

EXAMPLES
      # List sources in active group

      $ sq ls

      # List sources in the "prod" group

      $ sq ls prod

      # List sources in the root group (will list all sources)

      $ sq ls /

      # List groups (all) instead of sources

      $ sq ls -g

      # Print verbose group details

      $ sq ls -gv

      # List subgroups in "prod" group

      $ sq ls -g prod

mv OLD NEW
    Move/rename sources and groups

OPTIONS
    -c, --compact Compact instead of pretty-printed output

    -h, --header
        Print header row

    --help
        help for mv

    -j, --json
        Output JSON

    -H, --no-header
        Don't print header row

    -t, --text
        Output text

    -y, --yaml
        Output YAML

EXAMPLES
      # Rename a source

      $ sq mv @sakila_postgres @sakila_pg

      @sakila_pg

      # Move a source into a group (same as renaming)

      $ sq mv @sakila_pg @sakila/pg

      @sakila/pg

      # Move a source into a group, keep current name

      $ sq mv @sakila/pg prod

      @prod/pg

      # Rename the group "production" to "prod". This will rename

      # any sources already in that group.

      $ sq mv production prod

ping [@HANDLE|GROUP]*
    Ping data sources

OPTIONS
    -c, --compact Compact instead of pretty-printed output

    -C, --csv
        Output CSV

    -h, --header
        Print header row

    --help
        help for ping

    -j, --json
        Output JSON

    -H, --no-header
        Don't print header row

    --ping.timeout
        ping command timeout duration

    -t, --text
        Output text

    --tsv
        Output TSV

EXAMPLES
      # Ping active data source.

      $ sq ping

      # Ping @my1 and @pg1.

      $ sq ping @my1 @pg1

      # Ping sources in the root group (i.e. all sources).

      $ sq ping /

      # Ping sources in the "prod" and "staging" groups.

      $ sq ping prod staging

      # Ping @my1 with 2s timeout.

      $ sq ping @my1 --timeout 2s

      # Output in TSV format.

      $ sq ping --tsv @my1

rm @HANDLE|GROUP
    Remove data source or group

OPTIONS
    -c, --compact Compact instead of pretty-printed output

    -h, --header
        Print header row

    --help
        help for rm

    -j, --json
        Output JSON

    -H, --no-header
        Don't print header row

    -t, --text
        Output text

    -y, --yaml
        Output YAML

EXAMPLES
      # Remove @sakila source

      $ sq rm @sakila_db

      # Remove multiple data sources

      $ sq rm @sakila/pg @sakila_my

      # Remove the "prod" group (and all its children)

      $ sq rm prod

      # Remove a mix of sources and groups

      $ sq rm @staging/sakila_db @staging/backup_db dev

sql QUERY|STMT
    Execute DB-native SQL query or statement

OPTIONS
    -c, --compact Compact instead of pretty-printed output

    -C, --csv
        Output CSV

    --driver.csv.delim
        Delimiter for ingest CSV data

    --driver.csv.empty-as-null
        Treat ingest empty CSV fields as NULL

    --exec
        Execute the SQL as a statement (as opposed to query)

    -f, --format
        Specify output format

    --format.date
        Date format: constant such as DateOnly or a strftime format

    --format.date.number
        Render numeric date value as number instead of string

    --format.datetime
        Timestamp format: constant such as RFC3339 or a strftime format

    --format.datetime.number
        Render numeric datetime value as number instead of string

    --format.excel.date
        Date format string for Excel date-only values

    --format.excel.datetime
        Timestamp format string for Excel datetime values

    --format.excel.time
        Time format string for Excel time-only values

    --format.time
        Time format: constant such as TimeOnly or a strftime format

    --format.time.number
        Render numeric time value as number instead of string

    -h, --header
        Print header row

    --help
        help for sql

    --html
        Output HTML table

    --ingest.driver
        Explicitly specify driver to use for ingesting data

    --ingest.header
        Ingest data has a header row

    -i, --input
        Read input from <file> instead of stdin

    --insert
        Insert query results into @HANDLE.TABLE; if not existing, TABLE will be created

    -j, --json
        Output JSON

    -A, --jsona
        Output LF-delimited JSON arrays

    -J, --jsonl
        Output LF-delimited JSON objects

    --markdown
        Output Markdown

    --no-cache
        Don't cache ingest data

    -H, --no-header
        Don't print header row

    -o, --output
        Write output to <file> instead of stdout

    --query
        Execute the SQL as a query (as opposed to statement)

    -r, --raw
        Output each record field in raw format without any encoding or delimiter

    --src
        Override active source for this query

    --src.schema
        Override active schema (and/or catalog) for this query

    -t, --text
        Output text

    --tsv
        Output TSV

    -x, --xlsx
        Output Excel XLSX

    --xml
        Output XML

    -y, --yaml
        Output YAML

EXAMPLES
      # Select from active source

      $ sq sql 'SELECT * FROM actor'

      # Select from a specified source

      $ sq sql --src=@sakila_pg12 'SELECT * FROM actor'

      # Drop table @sakila_pg12.actor

      $ sq sql --src=@sakila_pg12 'DROP TABLE actor'

      # Select from active source and write results to @sakila_ms17.actor

      $ sq sql 'SELECT * FROM actor' --insert=@sakila_ms17.actor

src [@HANDLE]
    Get or set active data source

OPTIONS
    -c, --compact Compact instead of pretty-printed output

    -h, --header
        Print header row

    --help
        help for src

    -j, --json
        Output JSON

    -H, --no-header
        Don't print header row

    -t, --text
        Output text

    -y, --yaml
        Output YAML

EXAMPLES
      # Get active data source

      $ sq src

      # Set @my1 as active data source

      $ sq src @my1

tbl
    Useful table actions (copy, truncate, drop)

OPTIONS
    --help help for tbl

COMMANDS
    copy @HANDLE.TABLE NEWTABLE
        Make a copy of a table

    OPTIONS
        -c, --compact Compact instead of pretty-printed output

        --data
            Copy table data

        -h, --header
            Print header row

        --help
            help for copy

        -j, --json
            Output JSON

        -H, --no-header
            Don't print header row

        -t, --text
            Output text

    EXAMPLES
          # Copy table "actor" in @sakila_sl3 to new table "actor2"

          $ sq tbl copy @sakila_sl3.actor .actor2

          # Copy table "actor" in active src to table "actor2"

          $ sq tbl copy .actor .actor2

          # Copy table "actor" in active src to generated table name (e.g. "@sakila_sl3.actor_copy__1ae03e9b")

          $ sq tbl copy .actor

          # Copy table structure, but don't copy table data

          $ sq tbl copy --data=false .actor

    drop @HANDLE.TABLE
        Drop one or more tables

    OPTIONS
        --help help for drop

    EXAMPLES
          # drop table "actor" in src @sakila_sl3

          $ sq tbl drop @sakila_sl3.actor

          # drop table "payment"" in the active src

          $ sq tbl drop .payment

          # drop multiple tables

          $ sq drop .payment @sakila_sl3.actor

    truncate @HANDLE.TABLE|.TABLE
        Truncate one or more tables

    OPTIONS
        -h, --header Print header row

        --help
            help for truncate

        -j, --json
            Output JSON

        -H, --no-header
            Don't print header row

        -t, --text
            Output text

    EXAMPLES
          # truncate table "actor"" in source @sakila_sl3

          $ sq tbl truncate @sakila_sl3.actor

          # truncate table "payment"" in the active src

          $ sq tbl truncate .payment

          # truncate multiple tables

          $ sq tbl truncate .payment @sakila_sl3.actor

EXAMPLES
      # Copy table actor to new table actor2

      $ sq tbl copy @sakila_sl3.actor actor2

      # Truncate table actor2

      $ sq tbl truncate @sakila_sl3.actor2

      # Drop table actor2

      $ sq tbl drop @sakila_sl3.actor2

version
    Show version info

OPTIONS
    -c, --compact Compact instead of pretty-printed output

    -h, --header
        Print header row

    --help
        help for version

    -j, --json
        Output JSON

    -H, --no-header
        Don't print header row

    -t, --text
        Output text

    -y, --yaml
        Output YAML

EXAMPLES
      # Show version (note that an update is available)

      $ sq version

      sq v0.38.0 Update available: v0.39.0

      # Verbose output

      $ sq version -v

      sq v0.38.0

      Version: v0.38.0

      Commit: #4e176716

      Timestamp: 2023-06-21T11:39:39Z

      Latest version: v0.39.0

      Host: darwin arm64 | Darwin 22.5.0 | macOS 13.4

      [...]

      # JSON output

      $ sq version -j

      {

        "version": "v0.38.0",

        "commit": "4e176716",

        "timestamp": "2023-06-19T22:08:54Z",

        "latest_version": "v0.39.0",

        "host": {

          "platform": "darwin",

          "arch": "arm64",

          "kernel": "Darwin",

          "kernel_version": "22.5.0",

          "variant": "macOS",

          "variant_version": "13.4"

        }

      }

      # Extract just the semver string

      $ sq version -j | jq -r .version

      v0.38.0

EXAMPLES

# Add Postgres source.

  $ sq add postgres://user@localhost/sakila -p

  Password: ****

  # List available data sources.

  $ sq ls

  # Set active data source.

  $ sq src @sakila_pg

  # Get specified cols from table address in active data source.

  $ sq '.actor | .actor_id, .first_name, .last_name'

  # Ping a data source.

  $ sq ping @sakila_pg

  # View metadata (schema, stats etc) for data source.

  $ sq inspect @sakila_pg

  # View metadata for a table.

  $ sq inspect @sakila_pg.actor

  # Output all rows from 'actor' table in JSON.

  $ sq -j .actor

  # Output in text format (with header).

  $ sq -th .actor

  # Output in text format (no header).

  $ sq -tH .actor

  # Output to a HTML file.

  $ sq --html '@sakila_pg.actor' -o actor.html

  # Join across data sources.

  $ sq '@my1.person, @pg1.address | join(.uid) | .username, .email, .city'

  # Insert query results into a table in another data source.

  $ sq --insert=@pg1.person '@my1.person | .username, .email'

  # Execute a database-native SQL query, specifying the source.

  $ sq sql --src=@pg1 'SELECT uid, username, email FROM person LIMIT 2'

  # Copy a table (in the same source).

  $ sq tbl copy @sakila_pg.actor .actor2

  # Truncate table.

  $ sq tbl truncate @sakila_pg.actor2

  # Drop table.

  $ sq tbl drop @sakila_pg.actor2

  # Pipe an Excel file and output the first 10 rows from sheet1

  $ cat data.xlsx | sq '.sheet1 | .[0:10]'