NAME

       kyua db-exec — Executes a SQL statement in a results file

SYNOPSIS

       kyua db-exec [--no-headers] [--results-file file] statement

DESCRIPTION

       The  kyua db-exec command provides a way to execute an arbitrary SQL statement within the database.  This
       command is mostly intended to aid in debugging, but can also be used  to  extract  information  from  the
       database when the current interfaces do not provide the desired functionality.

       The input database must exist.  It makes no sense to use kyua db-exec on a nonexistent or empty database.

       The  kyua db-exec command takes one or more arguments, all of which are concatenated to form a single SQL
       statement.  Once the statement is executed, kyua db-exec prints the resulting table  on  the  screen,  if
       any.

       The following subcommand options are recognized:

       --no-headers
           Avoids printing the headers of the table in the output of the command.

       --results-file path, -s path
           Specifies  the  results  file  to  operate  on.   Defaults  to ‘LATEST’, which causes kyua db-exec to
           automatically load the latest results file from the current test suite.

           The following values are accepted:

           ‘LATEST’
               Requests the load of the latest results file available for the test suite rooted at  the  current
               directory.

           Directory
               Requests  the  load  of  the latest results file available for the test suite rooted at the given
               directory.

           Test suite name
               Requests the load of the latest results file available for the given test suite.

           Results identifier
               Requests the load of a specific results file.

           Explicit file name (aka everything else)
               Load the specified results file.

           See “Results files” for more details.

   Results files
       Results files contain, as their name implies, the results of the execution of a test  suite.   Each  test
       suite  executed  by kyua-test(1) generates a new results file, and such results files can be loaded later
       on by inspection commands such as kyua-report(1) to analyze their contents.

       Results files support identifier-based lookups and also path name lookups.  The differences  between  the
       two are described below.

       The  default naming scheme for the results files provides simple support for identifier-based lookups and
       historical recording of test suite runs.  Each results file is given an identifier derived from the  test
       suite  that  generated  it  and the time the test suite was run.  Kyua can later look up results files by
       these fields.

       The identifier follows this pattern:

             <test_suite>.<YYYYMMDD>-<HHMMSS>-<uuuuuu>

       where ‘test_suite’ is the path to the root of the test suite that was run with all  slashes  replaced  by
       underscores and ‘YYYYMMDD-HHMMSS-uuuuuu’ is a timestamp with microsecond resolution.

       When  using  the  default  naming scheme, results files are stored in the ~/.kyua/store/ subdirectory and
       each file holds a name of the form:

             ~/.kyua/store/results.<identifier>.db

       Results   files   are    simple    SQLite    databases    with    the    schema    described    in    the
       /usr/share/kyua/store/schema_v?.sql  files.   For  details  on  the  schema,  please refer to the heavily
       commented SQL file.

EXIT STATUS

       The kyua db-exec command returns 0 on success or 1 if the SQL statement is invalid or fails to run.

       Additional exit codes may be returned as described in kyua(1).

SEE ALSO

       kyua(1), kyua-test(1)

Debian                                          October 13, 2014                                 KYUA-DB-EXEC(1)