Man Linux: Main Page and Category List


       gda-sql - an SQL console based on Libgda


       gda-sql  [--help] [-v] [--version] [-o] [--output-file <filename>] [-C]
       [--command] [-f]  [--commands-file  <filename>]  [-i]  [--interractive]
       [-l]  [--list-dsn]  [-L]  [--list-providers]  [-s] [--http-port <port>]
       [-t] [--http-token <token phrase>]  [connection's  spec]  [connection's


       gda-sql is an SQL console based on the Libgda library.

       It  enables  you  to  type  in  queries interactively, issue them to be
       executed by a connection, and see the query results.

       Several connections can be opened at the same  time,  allowing  you  to
       switch  the  active connection to any opened connection. When starting,
       gda-sql opens a connection for each connection specified on the command
       line  (plus optionally one corresponding to the GDA_SQL_CNC environment
       variable). The  prompt  indicates  the  current  connection  used  when
       executing  commands.  See  the  .c  internal command for an explanation
       about the syntax to specify a connection on the command line.

       Alternatively, input can be from a file.  In addition,  it  provides  a
       number  of  meta-commands and various shell-like features to facilitate
       writing scripts and automating a wide variety of tasks.


       gda-sql accepts the following options:

       --help  Show command-line options.

       -o, --output-file <filename>
               Specifies a file to which outputs are redirected.

       -C, --command
               Run only single command (SQL or internal) and exit.

       -f, --commands-file <filename>
               Execute commands from  <filename>,  then  exit  (except  if  -i

       -i, --interractive
               Keep  the  console opened after executing a file (used with the
               -f option).

       -l, --list-dsn
               List configured data sources and exit.

       -L, --list-providers
               List installed database providers and exit

       -s, --http-port <port>
               Starts the embedded HTTP server on port <port>

       -t, --http-token <token phrase>
               Requires HTTP clients to authenticate by providing  the  <token
               phrase> (empty phrase by default)


       gda-sql respects a number of environment variables.

               to  define  a  connection  to systematically be opened when the
               program starts.

       PAGER   to define a text pager program to use (by default determined by
               the system).

               to specify that no text pager should be used.

               to  define  a text editor to be used (variables are examined in
               this order).

               to define a PNG viewer.

               to define a PDF viewer.

               to  define  the  history  file  name   to   use   (by   default
               .gdasql_history), set to NO_HISTORY to disable history logging.

       gda-sql can be compiled with support for binary relocatibility.
       This will cause data, plug-ins and configuration files to  be  searched
       relative to the location of the gda-sql executable file.


       gda-sql  stores  data  source definitions (DSN) in Libgda defined files
       ($HOME/.local/share/libgda and /etc/libgda-4.0/config  where  ${prefix}
       is typically /usr).

       For  each  connection  defined  by  a DSN, the meta data is stored in a
       $HOME/.local/share/libgda/gda-sql-<DSN>.db file.

SQL commands

       You can run any SQL understood by the database engine  of  the  current
       connection.    Additionnally   SQL   statement  can  contain  variables
       expressed as ##<name>::<type> where <name> is the variable's  name  and
       <type>  is  its declared type (which can be "int", "string", "boolean",
       "time", "date", "timestamp" (and other types defined by GLib's syntax).

       Use the .set internal command to set variable's values.

Internal commands

       In  addition  to SQL commands, gda-sql supports internal commands which
       differ from SQL commands  because  they  start  with  the  "."  or  "\"
       character. These commands are:

       .?     Lists all internal commands

       .bind  Bind two or more connections into a single new one (allowing SQL
              commands to be  executed  across  multiple  connections).  .bind
              <CNC_NAME>  <CNC_NAME1>  <CNC_NAME2>  [<CNC_NAME> ...] creates a
              new connection named <CNC_NAME> which binds the  tables  of  the
              <CNC_NAME1>, <CNC_NAME2> and any other connection specified.

       .c     Opens  a connection or sets the current connection. Username and
              password      can       pe       specified       using       the
              <USERNAME>[:<PASSWORD>]@<DSN_NAME>                            or
              <USERNAME>[:<PASSWORD>]@<CNC_DEFINITION>  syntax,   and   if   a
              username or a password is required but not specified, it will ba
              asked interactively.

              .c <CNC_NAME> <DSN_NAME> opens a connection internally known  as
              <CNC_NAME>, using the specified DSN.

              .c  <CNC_NAME>  <CNC_DEFINITION>]  opens a connection internally
              known  as  <CNC_NAME>,   using   a   connection   specified   by
              <CNC_DEFINITION>   which  is  similar  to  the  <DSN_DEFINITION>
              parameter of the .lc command.

              .c <CNC_NAME> sets the  current  connection  to  the  connection
              known as <CNC_NAME>.

              .c  ~  or  .c ~<CNC_NAME> set the current connection to the meta
              data corresponding to the  current  connection  (for  the  first
              notation)  or  to  the meta data corresponding to the <CNC_NAME>

       .close Closes a connection. Full syntax is: .close <CNC_NAME>.

       .cd    Changes the current  working  directory.  Full  syntax  is:  .cd

              Displays copyright information.

       .d     Lists  all  database  objects  if  no  argument  is provided. .d
              <OBJ_NAME> gives details  about  the  specified  object  and  .d
              <SCHEMA>.* lists all objects in specified schema.

       .dn    Lists  all  schemas if no argument is provided. .d <SCHEMA_NAME>
              lists specified schema.

       .dt    Lists all tables if no argument  is  provided.  .d  <TABLE_NAME>
              lists specified table.

       .dv    Lists all views if no argument is provided. .d <VIEW_NAME> lists
              specified view.

       .e     Edits the query buffer with external editor, if no  argument  is
              provided.  .e  <FILE_NAME>  edits  the  specified file name. The
              external editor can be specified using environment variables.

       .echo  Sends output to stdout, full command is: .echo [<TEXT>].

              Exports internal parameter or table's value to  the  FILE  file.
              Internal  parameters  are  named  values used when SQL statement
              containing variables are executed.

              .export <NAME> <FILE_NAME> exports the contents  of  the  <NAME>
              parameter to the specified file.

              .export <TABLE> <COLUMN> <ROW_CONDITION> <FILE_NAME> exports the
              value of the <TABLE> table, column <COLUMN> for the row selected
              by  <ROW_CONDITION>  to the specified file. This is most usefull
              to export BLOBs.

       .g     Executes the contents of the query buffer, if  no  parameter  is
              provided.  .g  <QUERY_BUFFER_NAME>  Executes the contents of the
              specified query buffer. A named query buffer  is  created  using
              the .qs command.

       .graph Creates  a  graph  of  tables  showing their relations (based on
              foreign key constraints). If no argument is provided, the  graph
              lists  all tables. .graph <TABLE_NAME> [<TABLE_NAME>...] creates
              a graph listing the specified tables.

              The generated graph is created as the "" file.  If  the
              GDA_SQL_VIEWER_PNG  or  GDA_SQL_VIEWER_PDF environment variables
              are set and if the "dot" program (from GraphViz) is found,  then
              the graph is displayed (if a display is available).

       .H     Set output format. Full syntax is: .H [HTML|XML|CSV|DEFAULT].

       .http  Starts/stops  the  embedded  HTTP  server.  Full syntax is .http
              [<port> [<authentication_token>]], where  <authentication_token>
              is  an  optional token phrase which HTTP clients are required to
              send to authenticate.

       .i     Executes commands from file the specified file: .i  <FILE_NAME>.

       .l     Lists  all  data  sources  if  no argument is provided. .l <DSN>
              lists information about the specified DSN.

       .lp    Lists  all  available  database  providers  if  no  argument  is
              provided.  .lp  <provider> lists information about the specified

       .lc    Declares a DSN. Full syntax is: .lc <DSN_NAME>  <DSN_DEFINITION>
              [<DESCRIPTION>].      The     <DSN_DEFINITION>     format    is:
              <provider>://[<username>[:<password>]@]<connection_params> where
              <connection_params>  is  a  semi-colon  (";")  separated list of
              <key>=<value> pairs  where  <key>  is  defined  when  using  .lp
              <provider>  (if  <value>  contains  non alphanumeric characters,
              they should be represented as specified by the RFC 1738).

              If a DSN with  a  similar  name  already  exists,  it  is  first

              For example: ".lc mydsn PostgreSQL://HOST=moon;DB_NAME=mydb".

       .lr    Removes a DSN declaration. Full syntax is: .lc <DSN_NAME>.

       .meta  Updates  the  current  connection's  meta data (use this command
              after having modified the database's schema).

       .o     Sends output to a file or |pipe. Full syntax is: .o  <FILE_NAME>
              or .o |<COMMAND>.

       .q     Quits the application.

       .qecho Sends  output  to  the  output  stream (stdout). Full syntax is:
              .qecho <TEXT>.

       .qa    Lists all saved query buffers in dictionary.

       .qd    Deletes a query buffer from the dictionary. Full syntax is:  .qd

       .ql    Loads  query  buffer  from  dictionary  into  the  current query
              buffer.  Full syntax is: .ql <QUERY_BUFFER_NAME>.

       .qp    Shows the contents of the current query buffer.

       .qr    Resets the query buffer to empty if no argument is provided. .qr
              <FILE _NAME> loads the specified file into the query buffer.

       .qs    Saves   query   buffer   to   dictionary,  full  syntax  is  .qs
              <QUERY_BUFFER_NAME>. This creates a new query  buffer  with  the
              specified  name  in the dictionary, containing the current query

       .qw    Writes the query buffer to the specified file,  full  syntax  is
              .qw <FILE_NAME>.

       .s     Show  commands  history. .s <FILE_NAME> saves command history to
              specified file.

       .set   Sets, shows or lists internal parameters.

              .set lists all the defined internal parameters.

              .set <NAME> <VALUE> (re)defines  the  internal  parameter  named
              <NAME>  to  the specified value (which can be the _null_ literal
              to set it to NULL).

              .set <NAME> shows the contents of the internal  parameter  named

       .setex Set  internal parameter as the contents of the FILE file or from
              an existing table's value.

              .setex <NAME> <FILE_NAME> (re)defines the the internal parameter
              named <NAME> with the contents of the specified file name.

              .setex  <NAME>  <TABLE> <COLUMN> <ROW_CONDITION> (re)defines the
              the internal parameter  named  <NAME>  with  the  value  of  the
              <TABLE>   table,   column  <COLUMN>  for  the  row  selected  by
              <ROW_CONDITION>.This is most usefull to export BLOBs.

       .unset Unset (delete) internal parameter.

              .unset unsets all the internal parameters.

              .unset <NAME> unsets the internal parameter named <NAME>.


       Any bugs found should be reported to  the  online  bug-tracking  system
       available  on  the  web at Before reporting
       bugs, please check to see if the bug has already been reported.

       When reporting bugs, it is important  to  include  a  reliable  way  to
       reproduce  the bug, version number of gda-sql, OS name and version, and
       any relevant hardware specs. If a bug is causing a crash,  it  is  very
       useful  if  a  stack  trace  can be provided. And of course, patches to
       rectify the bug are even better.


       Consult the Libgda's home page at


       Vivien Malerba (for Libgda's authors, please consult  the  AUTORS  file
       within the Libgda's sources)


       psql(1), mysql(1), sqlite3(1)