<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"[
<!ENTITY LIBGDA          "<application>Libgda</application>">
]>
<part id="gda-sql">
  <title>Gda SQL console's user manual</title>
<para>
  The &LIBGDA;'s console tool allow one to send SQL commands to a database server, and
  to easily browse the meta data associated to the database (ie. get information about
  tables and their columns, functions, triggers, etc). This tool has a usage similar to
  PostgreSQL's <application>psql</application>, MySQL's <application>mysql</application>, Oracle's
  <application>sqlplus</application> or SQLite's <application>sqlite3</application> programs.
</para>

<para>
  However, contrary to the programmed mentioned above, The &LIBGDA;'s console tool
  offers the same features and usage for any of the databases supported by &LIBGDA;.
  For more information, consult the man page (<command>man gda-sql</command>).
</para>


<chapter id="gda-sql-manual-run">
  <title>Getting started</title>

  <sect1>
    <title>Features</title>
    <para>
      The &LIBGDA;'s console tool' main features are:
      <itemizedlist>
	<listitem><para>Handle more than one connection at the same time</para></listitem>
	<listitem><para>Report meta data in a similar way, whatever the real type of database
	    accessed</para></listitem>
	<listitem><para>Create <emphasis>virtual</emphasis> connections binding 
	    several already opened connections (to run SQL commands across multiple 
	    connections)</para></listitem>
	<listitem><para>Allow one to define variables which can be referenced in any
	    SQL statement (using a common syntax)</para></listitem>
	<listitem><para>One query buffer per connection to edit complex queries (uses a
	    parameter-able external editor)</para></listitem>
	<listitem><para>Easy command line editing and output using the Readline library and a
	    (parameter-able) pager</para></listitem>
	<listitem><para>Work on any platform on which &LIBGDA; has been ported to.</para></listitem>
	<listitem><para>List, define or remove named data sources (DSN)</para></listitem>
	<listitem><para>Import and export BLOBS (binary large objects) from and to local files</para></listitem>
	<listitem><para>On command embedded HTTP server</para></listitem>
      </itemizedlist>
    </para>
  </sect1>

  <sect1>
    <title>Execution</title>
    <para>
      The &LIBGDA;'s SQL console tool runs is a terminal emulator, and can be launched using
      the <command>gda-sql</command> (or <command>gda-sql-&lt;version&gt;</command> for a specific version):
      <cmdsynopsis>
	<command>gda-sql</command>
	<arg>--help</arg>
	<arg>-l</arg>
	<arg>-L</arg>
	<arg>-C <replaceable>command</replaceable></arg>
	<arg>-f <replaceable>commands file</replaceable></arg>
	<arg>-o <replaceable>output file</replaceable></arg>
	<arg>-s<replaceable>port to use to run embedded HTTP server</replaceable></arg>
	<arg>-t<replaceable>authentication token required to authenticate clients when running the embedded HTTP server</replaceable></arg>
	<arg rep="repeat"><replaceable>connection specification</replaceable></arg>
      </cmdsynopsis>
      The options are the following ones:
      <itemizedlist>
	<listitem><para>the <option>--help</option> option gives a short help summary</para></listitem>
	<listitem><para>the <option>-l</option> and <option>-L</option> options respectively
	output a list of the defined data sources (DSN) and of the installed database adaptaters
	(database providers):
	    <programlisting>
[prompt]> gda-sql -l
                                                    List of defined data sources
DSN       | Provider | Description                          | Connection string            | Username | Global
----------+----------+--------------------------------------+------------------------------+----------+-------
SalesTest | SQLite   | Test database for a sales department | DB_DIR=/adir;DB_NAME=data.db |          | FALSE
[...]
	    </programlisting>
	    <programlisting>
[prompt]> gda-sql -L
                                     Installed providers list
Provider       | Description                                                                        
---------------+------------------------------------------------------------------------------------
Berkeley-DB    | Provider for Berkeley databases                                                    
Firebird       | Provider for Firebird databases                                                    
FirebirdEmbed  | Provider for embedded Firebird databases                                           
Ldap           | Provider for database where tables are based on data contained in an LDAP directory
MSAccess       | Provider for Microsoft Access files
[...]            
	    </programlisting>
	    <programlisting>
[prompt]> ./gda-sql -L PostgreSQL                                  
                                                                                       Provider 'PostgreSQL' description
Attribute      | Value                                                                                                                                 
---------------+---------------------------------------------------------------------------------------------------------------------------------------
Provider       | PostgreSQL                                                                                                                            
Description    | Provider for PostgreSQL databases                                                                                                     
DSN parameters | DB_NAME: Database name. The name of a database to connect to (string),                                                                
                 SEARCHPATH: Search Path. Search path among database's schemas ('search_path' variable) (string),                                      
                 HOST: Database server. ost on which the database server is running (for servers running on unix domain sockets, enter the socket's path (usually /tmp), or leave this field empty),
                 PORT: Port. Database server port (for servers running on unix domain sockets, enter the socket's file name extension (usually 5432), or leave this field empty),
                 OPTIONS: Options. Extra connection options (string),                                                                                  
                 USE_SSL: Require SSL. Whether or not to use SSL to establish the connection (boolean),                                                
                 CONNECT_TIMEOUT: Connection timeout. Maximum wait for connection, in seconds. Zero or not specified means wait indefinitely. It is not recommended to use a timeout of less than 2 seconds,
Authentication | USERNAME (string),                                                                                                                    
                 PASSWORD (string)                                                                                                                     
File           | /local/extra/lib/libgda-6.0/providers/libgda-postgres.so                                                                              
(5 rows)
	    </programlisting>
	</para></listitem>
	<listitem><para>the <option>-C</option> and <option>-f</option> options repectively allow
	    one to specify a single command to be run or a filename containing the commands to run
	    before the tool exits</para></listitem>
	<listitem><para>the <option>-o</option> option allows to specify a file to write the 
	    output to</para></listitem>
	<listitem><para>the <option>-s</option> requests the embedded HTTP server to be executed, listening on
	    the port specified.</para></listitem>
	<listitem><para>the <option>-t</option> specifies a token string which clients will have to
	    supply to authenticate themselves to the HTTP server, if running.</para></listitem>
      </itemizedlist>
    </para>
    <para>
      Connections to be opened can be specified on the command line using either:
      <itemizedlist>
	<listitem><para>defined data sources (the ones listed using the <option>-l</option> option)</para></listitem>
	<listitem><para>connection strings which have the following format: 
	    "[&lt;provider&gt;://][&lt;username&gt;[:&lt;password&gt;]@]&lt;connection_params&gt;". 
	    If a username or password is required, and is not specified either by a DSN's definition or in
	    the connection string, then it will be requested dynamically.
	    Note that if provided, &lt;username&gt;, &lt;password&gt; and &lt;provider&gt; must be encoded as per RFC 1738</para></listitem>
	<listitem><para>for SQLite and MS Access files: the file name</para></listitem>
      </itemizedlist>
    </para>
    <para>
      Connections can also be opened while the tool is running using the <command>.c</command> 
      internal command.
    </para>
    <para>
      Examples:
      <programlisting>
[prompt]> gda-sql Sales
[prompt]> gda-sql Postgresql://username@DB_NAME=mydb SQLite://DB_NAME=fspot Sales
[prompt]> gda-sql path/to/dbfile.db
      </programlisting>
    </para>
  </sect1>

  <sect1>
    <title>Commands</title>
    <para>
      The console tool allows the user to enter SQL commands (which can span several lines and must be terminated with
      a semi colon). The commands are executed synchronously and the results displayed right after execution, for example:
      <programlisting>
cnc1> select *
    > from customers order by name;
id | name            | last_update           | default_served_by | country | city
---+-----------------+-----------------------+-------------------+---------+-----
 2 | Ed Lamton       | 2008-08-12 00:00:00+0 |                 4 | SP      | MDR 
 9 | Greg Popoff     | 2007-12-25 00:00:00+0 |                 2 | SP      | MDR 
 3 | Lew Bonito      | 2008-08-13 00:00:00+0 |                 1 | FR      | TLS 
 4 | Mark Lawrencep  | 2007-12-25 00:00:00+0 |                   | SP      | MDR 
10 | Vladimir Zirkov | 2001-01-31 00:00:00+0 |                 4 |         |     
(5 rows)
cnc1>
      </programlisting>
      The SQL dialect to be used must be understood by the database to which the connection is opened, so
      it is possible to use database's specific commands, for example with a PostgreSQL database:
      <programlisting>
cnc2> show search_path;
search_path   
--------------
"$user",public
(1 row)
cnc2>
      </programlisting>
    </para>
    <para>
      There are also some internal commands which all start either with a dot or backslash and perform some
      actions such as changing the default output mode (to HTML for example) or getting meta information
      about the database structure. For example, use the <command>.?</command> to display a help message
      about all internal commands (with truncated output here):
      <programlisting>
gda> .?
Formatting
  \H [HTML|XML|CSV|DEFAULT]
                     Set output format

General
  \?                 List all available commands
  \bind CNC_NAME CNC_NAME1 CNC_NAME2 [CNC_NAME ...]
                     Bind several connections together into the CNC_NAME virtual connection
      </programlisting>
    </para>
  </sect1>

</chapter>

<chapter id="gda-sql-manual-dsn">
  <title>DSN management</title>
  <para>
    Named data sources (DSN) can be used (like in ODBC) to name some connections and define their connection parameters,
    it becomes easier to use them (one just has to remember the DSN name), and it becomes possible to change the 
    connection parameters without changing any code.
  </para>
  <para>
    They can be listed using the <command>.l</command> command, and details about a DSN can be listed using the same command
    with the DSN name as argument:
    <programlisting>
gda> .l
                              DSN list
DSN                  | Description                          | Provider  
---------------------+--------------------------------------+-----------
Bugzilla             | Bugzilla data source                 | MySQL     
koha                 |                                      | PostgreSQL
SalesTest            | Test database for a sales department | SQLite    
(3 rows)
gda> .l SalesTest
                              DSN 'SalesTest' description
Attribute         | Value                                                                 
------------------+-----------------------------------------------------------------------
DSN               | SalesTest                                                             
Provider          | SQLite                                                                
Description       | Test database for a sales department                                  
Connection string | DB_DIR=/home/user/name/.libgda;DB_NAME=sales_test
Username          |                                                                       
Global            | FALSE                                                                 
(6 rows)
gda>
    </programlisting>
  </para>
  <para>
    The <command>.lr DSN_NAME [DSN_NAME...]</command> command removes the DSN listed as arguments, and the
    The <command>.lc</command> command creates (or modifies an existing) DSN, such as show:
    <programlisting>
gda> .lc my_dsn PostgreSQL://DB_NAME=my_db;HOST=moon
gda> .l my_dsn
        DSN 'my_dsn' description
Attribute         | Value                  
------------------+------------------------
DSN               | my_dsn                 
Provider          | PostgreSQL             
Description       |                        
Connection string | DB_NAME=my_db;HOST=moon
Username          |                        
Global            | FALSE                  
(6 rows)
gda>
    </programlisting>
  </para>
</chapter>


<chapter id="gda-sql-manual-open">
  <title>Connections management</title>
  <para>
    The console tool is able to handle several connections at the same time, they can dynamically be opened and
    closed during a session. The current connection in use is indicated by the prompt.
    Use the <command>.c</command> command to open a connection with the connection name (the name by which
    the connection is identified within the tool) and a connection string; for example:
    <programlisting>
gda> .c cnc1 SalesTest
cnc1>
    </programlisting>
  </para>
  <para>
    The list of connection can be listed using the same <command>.c</command> command without any argument, for example:
    <programlisting>
ia32> .c
          List of opened connections
Name | Provider | DSN or connection string | Username
-----+----------+--------------------------+---------
cnc1 | SQLite   | SalesTest                |         
ia32 | SQLite   | IA32Instructions         |         
(2 rows)
ia32>
    </programlisting>
  </para>
  <para>
    To switch from one connection to the other, use the <command>.c</command> command with the connection name to use
    as single argument, for example to switch from using the "ia32" to the "cnc1" connection: 
    <programlisting>
ia32> .c cnc1
cnc1>
    </programlisting>
  </para>

  <sect1>
    <title>Virtual connections</title>
    <para>
      Multiple connections can be <emphasis>bound together</emphasis> into a single connection in which it is possible
      to runs SQL statements. This effectively allows one to run SQL statements across multiple databases.
    </para>
    <para>
      Binding connections together is done using the <command>.bind CNC_NAME CNC_NAME1 CNC_NAME2 [CNC_NAME ...]</command>
      command which creates new connection named "CNC_NAME" which binds the connections names "CNC_NAME1" and "CNC_NAME2"
      together (more connections can be bound); each connection to be bound into a virtual connection must of course
      already have been opened. The tables of each bound connection will appear into the new virtual connection as named
      "&lt;cnc name&gt;.&lt;table name&gt;".
    </para>
    <para>
      In the following example, there are the "cnc1" and "cnc2" connections opened, and the "cnc3" connection is
      a virtual connection binding "cnc1" and "cnc2":
      <programlisting>
cnc2> .bind cnc3 cnc1 cnc2
Bound connections are as:
   cnc1 in the 'cnc1' namespace
   cnc2 in the 'cnc2' namespace
cnc3> .c
          List of opened connections
Name | Provider | DSN or connection string | Username
-----+----------+--------------------------+---------
cnc1 | SQLite   | DB_DIR=.;DB_NAME=pmodel  |         
cnc2 | SQLite   | SalesTest                |         
cnc3 |          | namespace cnc1           |         
                  namespace cnc2                     
(3 rows)
cnc3> 
      </programlisting>
      The contents of each "customers" table in each of the bound connection is accessible:
      <programlisting>
cnc3> select * from cnc1.customers;
id | name            | last_update           | default_served_by | country | city
---+-----------------+-----------------------+-------------------+---------+-----
 2 | Ed Lamton       | 2008-08-12 00:00:00+0 |                 4 | SP      | MDR 
 3 | Lew Bonito      | 2008-08-13 00:00:00+0 |                 1 | FR      | TLS 
 4 | Mark Lawrencep  | 2007-12-25 00:00:00+0 |                   | SP      | MDR 
 9 | Greg Popoff     | 2007-12-25 00:00:00+0 |                 2 | SP      | MDR 
10 | Vladimir Zirkov | 2001-01-31 00:00:00+0 |                 4 |         |     
(5 rows)
cnc3>  select * from cnc2.customers;
id | name            | default_served_by | country | city
---+-----------------+-------------------+---------+-----
 2 | Ed Lamton       |                 4 | SP      | MDR 
 3 | Lew Bonito      |                 1 | FR      | TLS 
 4 | Mark Lawrencep  |                   | SP      | MDR 
 9 | Greg Popoff     |                 2 | SP      | MDR 
10 | Vladimir Zirkov |                 4 |         |     
(5 rows)
cnc3> 
      </programlisting>
      The list of customers present in both tables are available as:
      <programlisting>
cnc3> SELECT * FROM cnc1.customers WHERE name IN (SELECT name FROM cnc2.customers);
id | name            | last_update           | default_served_by | country | city
---+-----------------+-----------------------+-------------------+---------+-----
 2 | Ed Lamton       | 2008-08-12 00:00:00+0 |                 4 | SP      | MDR 
 3 | Lew Bonito      | 2008-08-13 00:00:00+0 |                 1 | FR      | TLS 
 4 | Mark Lawrencep  | 2007-12-25 00:00:00+0 |                   | SP      | MDR 
 9 | Greg Popoff     | 2007-12-25 00:00:00+0 |                 2 | SP      | MDR 
10 | Vladimir Zirkov | 2001-01-31 00:00:00+0 |                 4 |         |     
(5 rows)
cnc3>
      </programlisting>
    </para>
  </sect1>

  <sect1>
    <title>Meta data</title>
    <para>
      When a connection is opened for the first time, the tool get all the possible meta data associated to that connection (list of
      tables, table's columns and their constraints, views, etc). The meta data are referred to when the user wants for example
      to list a table's attributes, or for command line completion.
    </para>
    <para>
      If some modifications to the database structure have been made using a tool not using &LIBGDA;, then
      the meta data must be updated using the <command>.meta</command> command, which does not output
      anything unless an error occurred. Updates to the meta data are automatic when a shema change
      is done using &LIBGDA; if the connection has been opened using the GDA_CONNECTION_OPTIONS_AUTO_META_DATA flag
      (which is the case for &LIBGDA;'s own tools).
    </para>
    <para>
      As the meta data are also stored in a database, the console tool allows one to directly execute SQL commands in the
      meta data database associated to a connection. The meta data connection associated to a connection is by convention named
      as the tilde character concatenated with the connection name (for example if the connection is named "cnc1", then the connection
      to its meta data will be named "~cnc1"). To open a meta data connection, make sure the current connection is the one for which
      you want to access the meta data, and then use the <command>.c ~</command> command (note that the same command will
      return to the "cnc1" connection):
      <programlisting>
cnc1> .c ~
Getting database schema information, this may take some time... Done.
~cnc1> .dt
                           List of tables
Schema | Name                             | Type       | Owner | Description
-------+----------------------------------+------------+-------+------------
main   | _attributes                      | BASE TABLE |       |            
main   | _builtin_data_types              | BASE TABLE |       |            
main   | _character_sets                  | BASE TABLE |       |            
main   | _check_column_usage              | BASE TABLE |       |            
main   | _collations                      | BASE TABLE |       |            
main   | _columns                         | BASE TABLE |       |            
main   | _domain_constraints              | BASE TABLE |       |            
main   | _domains                         | BASE TABLE |       |            
main   | _element_types                   | BASE TABLE |       |            
main   | _enums                           | BASE TABLE |       |            
main   | _information_schema_catalog_name | BASE TABLE |       |            
main   | _key_column_usage                | BASE TABLE |       |            
main   | _parameters                      | BASE TABLE |       |            
main   | _referential_constraints         | BASE TABLE |       |            
main   | _routine_columns                 | BASE TABLE |       |            
main   | _routines                        | BASE TABLE |       |            
main   | _schemata                        | BASE TABLE |       |            
main   | _table_constraints               | BASE TABLE |       |            
main   | _tables                          | BASE TABLE |       |            
main   | _triggers                        | BASE TABLE |       |            
main   | _udt                             | BASE TABLE |       |            
main   | _udt_columns                     | BASE TABLE |       |            
main   | _view_column_usage               | BASE TABLE |       |            
main   | _views                           | BASE TABLE |       |            
main   | gda_sql_query_buffers            | BASE TABLE |       |            
(25 rows)
~cnc1> SELECT table_name FROM _tables;
table_name     
---------------
customers      
locations      
orders         
order_contents 
roles          
salesrep       
sales_orga     
warehouses     
categories     
products       
products_copied
(11 rows)
~cnc1> .c ~
cnc1>
      </programlisting>
      Also note that the meta data's connections are listed among the opened connections, as shown:
      <programlisting>
cnc1> .c
                       List of opened connections
Name  | Provider | DSN or connection string                              | Username
------+----------+-------------------------------------------------------+---------
cnc1  | SQLite   | SalesTest                                             |         
~cnc1 | SQLite   | DB_DIR=/home/vivien/.libgda;DB_NAME=gda-sql-SalesTest |         
(2 rows)
cnc1>
      </programlisting>
    </para>
    <para>
      It is possible for any application to create some extra objects in that database for its own purposes, with the
      constraint that it <emphasis>should not</emphasis> create objects with names starting with an underscore (these
      names are reserved for &LIBGDA;'s own purposes). In the previous example, the table named "gda_sql_query_buffers"
      is the table internally used by the console tool to store the contents of named query buffers.
    </para>
    
    <sect2>
      <title>Information about tables</title>
      <para>
	Use the <command>.dt</command> command to list all the tables (or list only one table if the table name is specified as
	an argument to the command):
	<programlisting>
cnc1> .dt
                  List of tables
Schema | Name            | Type       | Owner | Description
-------+-----------------+------------+-------+------------
main   | categories      | BASE TABLE |       |            
main   | customers       | BASE TABLE |       |            
main   | locations       | BASE TABLE |       |            
main   | order_contents  | BASE TABLE |       |            
main   | orders          | BASE TABLE |       |            
main   | products        | BASE TABLE |       |            
main   | products_copied | BASE TABLE |       |            
main   | roles           | BASE TABLE |       |            
main   | sales_orga      | BASE TABLE |       |            
main   | salesrep        | BASE TABLE |       |            
main   | warehouses      | BASE TABLE |       |            
(11 rows)
cnc1> .dt customers
               List of tables
Schema | Name      | Type       | Owner | Description
-------+-----------+------------+-------+------------
main   | customers | BASE TABLE |       |            
(1 row)
cnc1>
	</programlisting>
      </para>
      <para>
	To display the details about a single table, use the <command>.d &lt;table_name&gt;</command> command:
	<programlisting>
cnc1> .d customers
          List of columns for table 'customers'
Column            | Type    | Nullable | Default | Extra         
------------------+---------+----------+---------+---------------
id                | integer | no       |         | Auto increment
name              | string  | no       | ''      |               
default_served_by | integer | yes      |         |               
country           | string  | yes      |         |               
city              | string  | yes      |         |               
(5 rows)

Primary key 'primary_key' (id)
Foreign key 'fk_locations' (country, city) references  main.locations (country, city)
Foreign key 'fk_salesrep' (default_served_by) references  main.salesrep (default_served_by)
cnc1>
	</programlisting>
      </para>

      <para>
	Finally, the <command>.graph [TABLE1 [TABLE2...]]</command> will create a graph of all the tables (or
	only the tables mentioned as arguments). The graph creates a <application>GraphViz</application> file
	named "graph.dot" which can then be processed with the GraphViz'<command>dot</command> command to
	produce an image or a PDF file for example.
      </para>
      <para>
	If the <envar>GDA_SQL_VIEWER_PNG</envar> or <envar>GDA_SQL_VIEWER_PDF</envar> environment variables are set
	(for example to <application>eog</application> or <application>evince</application>) and if the <command>dot</command> command
	is installed, then the console tool will perform the transformation and display the graph (if under a graphical session).
	The following figure shows an example of graph:
	<mediaobject>
          <imageobject role="html">
            <imagedata fileref="gda-sql-graph.png" format="PNG" contentwidth="140mm"/>
          </imageobject>
          <textobject>
            <phrase>Sample output from the ".graph" command</phrase>
          </textobject>
	</mediaobject>
      </para>
    </sect2>

    <sect2>
      <title>Information about views</title>
      <para>
	The console tool can report information about views. Use the <command>.dv</command> command to list all the views
	(or list only one view if the view name is specified as	an argument to the command):
	<programlisting>
cnc1> .dv
              List of views
Schema | Name         | Type | Owner | Description
-------+--------------+------+-------+------------
main   | cust_summary | VIEW |       |            
(1 row)
cnc1>
	</programlisting>
      </para>
      <para>
	One can also get more information for a single view using the <command>.d &lt;view name&gt;</command> command, 
	for example:
	<programlisting>
cnc1> .d cust_summary 
List of columns for view 'cust_summary'
Column   | Type   | Nullable | Default | Extra
---------+--------+----------+---------+------
name     | string | yes      |         |      
shortcut | string | yes      |         |      
(2 rows)
View definition: CREATE VIEW cust_summary as SELECT c.name, l.shortcut FROM customers c LEFT JOIN locations l ON (c.country=l.country AND c.city=l.city)
cnc1>
	</programlisting>
      </para>
    </sect2>

    <sect2>
      <title>Information about schemas</title>
      <para>
	Some databases feature the notion of <emphasis>schema</emphasis> which is a container for database objects such as
	tables, views, etc. Use the <command>.dn</command> command to get a list of all the schemas in a database. For
	example with a PostgreSQL database:
	<programlisting>
          List of schemas
Schema             | Owner    | Internal
-------------------+----------+---------
information_schema | postgres | yes     
pg_catalog         | postgres | yes     
pg_temp_1          | postgres | yes     
pg_toast           | postgres | yes     
pg_toast_temp_1    | postgres | yes     
public             | postgres | no      
(6 rows)
cnc1>
	</programlisting>
      </para>
    </sect2>

    <sect2>
      <title>Information about other objects</title>
      <para>
	The meta data database holds a lot of information about the many objects which exist in a database, but the
	console tool does not provide internal commands to display all of them. The solution is to run SELECT commands
	in the meta data connection associated to a connection. For example to get a list of triggers where the "cnc2"
	is a connection opened to a PostgreSQL's database, one first needs to connection to the meta data connection
	and lookup into the "_triggers" table:
	<programlisting>
cnc2> .c ~
~cnc2> select trigger_name, event_manipulation, event_object_table from _triggers;
trigger_name            | event_manipulation | event_object_table
------------------------+--------------------+-------------------
pg_sync_pg_database     | INSERT             | pg_database       
pg_sync_pg_database     | DELETE             | pg_database       
pg_sync_pg_database     | UPDATE             | pg_database       
pg_sync_pg_authid       | INSERT             | pg_authid         
pg_sync_pg_authid       | DELETE             | pg_authid         
pg_sync_pg_authid       | UPDATE             | pg_authid         
pg_sync_pg_auth_members | INSERT             | pg_auth_members   
pg_sync_pg_auth_members | DELETE             | pg_auth_members   
pg_sync_pg_auth_members | UPDATE             | pg_auth_members   
(9 rows)
~cnc2>
	</programlisting>
      </para>
      <para>
	The meta data's database structure is described in the <link linkend="information_schema">related section</link>.
      </para>
    </sect2>
  </sect1>
</chapter>

<chapter id="gda-sql-manual-icommands">
  <title>Detailed features</title>
  <para>
    This section explains in depth various aspects of the console tool.
  </para>

  <sect1>
    <title>Query buffer</title>
    <para>
      Everytime an SQL command is entered, it is stored in the query buffer associated to the current connection. 
      The query buffer can be edited using an external editor (which can be useful for multi line SQL statements) using
      the <command>.e</command> command. The query buffer can also be saved to a file and loaded back later using the
      <command>.qw</command> and <command>.qr</command> commands. To execute the SQL held in the current query buffer,
      use the <command>.g</command> command.
    </para>
    <para>
      Query buffers can be saved to the dictionary (along with the connection's meta data) for future usage using the
      <command>.qs buffer_name</command> command, and loaded back later with the <command>.ql buffer_name</command>.
      To list all the saved query buffers in the dictionary, use the <command>.qa</command> command. The following example
      shows an example output of the <command>.qa</command> command where one query buffer has been saved:
      <programlisting>
SalesTest> .qa
Query buffer name | SQL                                                                                   
------------------+---------------------------------------------------------------------------------------
orders_status     | select c.name, o.creation_date ,                                                      
                    (select count (product_ref) from order_contents oc where oc.order_id=o.id) as '#items'
                    from customers c                                                                      
                    	inner join orders o on (o.customer = c.id)                                           
                    order by o.creation_date;                                                             
                                                                                                          
(1 row)
SalesTest>
      </programlisting>
    </para>
    <para>
      The <command>.g</command> command can also be used to load a query buffer and execute its contents simply
      by passing the name of the query buffer to use as argument:
      <programlisting>
SalesTest> .g orders_status
name           | creation_date | #items
---------------+---------------+-------
Lew Bonito     | 2003-06-28    |      1
Lew Bonito     | 2004-02-02    |      2
Mark Lawrencep | 2004-02-02    |      2
Mark Lawrencep | 2004-02-02    |      0
Greg Popoff    | 2004-02-02    |      1
Ed Lamton      | 2006-02-04    |      0
Ed Lamton      | 2006-02-05    |      0
Ed Lamton      | 2006-02-05    |      0
Ed Lamton      | 2006-03-29    |      0
(9 rows)
SalesTest>
      </programlisting>
    </para>
  </sect1>

  <sect1>
    <title>Internal parameters</title>
    <para>
      Variables can be defined using the <command>.set</command> and <command>.setex</command> commands.
      Variables are then automatically looked for
      when executing SQL statements for which a variable is required; they are not typed and are converted to 
      the correct type when needed. Note that variables are shared by all the opened connections.
    </para>
    <para>
      When setting values, the textual representation must respect the following format:
      <itemizedlist>
	<listitem><para>for booleans: "true" or "false" (case insensitive)</para></listitem>
	<listitem><para>for numerical types: the dot as a fraction separator</para></listitem>
	<listitem><para>for dates, time and timestamp: the ISO 8601 format (dates as "YYYY-MM-DD", time as "HH:MM:SS")
	</para></listitem>
      </itemizedlist>
    </para>
    <para>
      Use the <command>.set &lt;variablename&gt; &lt;variable value&gt;</command> command to define a variable,
      and the <command>.set</command> command to list all defined variables. The following example illustrates
      variables usage:
      <programlisting>
SalesTest> select * from customers where id = ##theid::int;
ERROR: No internal parameter named 'theid' required by query
SalesTest> .set theid 3
SalesTest> select * from customers where id = ##theid::int;
id | name       | default_served_by | country | city
---+------------+-------------------+---------+-----
 3 | Lew Bonito |                 1 | FR      | TLS 
(1 row)
SalesTest> .set theid 5
SalesTest> select * from customers where id = ##theid::int;
id | name | default_served_by | country | city
---+------+-------------------+---------+-----
(0 rows)
SalesTest> .set
List of defined parameters
Name  | Value
------+------
theid | 5    
(1 row)
SalesTest>
    </programlisting>
    </para>
    <para>
      The <command>.setex</command> command also sets an internal parameter, it has two usages:
      <itemizedlist>
	<listitem><para>The <command>.set &lt;variablename&gt; &lt;filename&gt;</command> usage loads the contents
	    of the named filename into the named variable (usually to be used as a BLOB)</para></listitem>
	<listitem><para>The <command>.set &lt;variablename&gt; &lt;table&gt; &lt;column&gt; &lt;row condition&gt;</command>
	    usage creates a named variable which contents is the value of the &lt;table&gt; table and
	  &lt;column&gt; column for the row identified by &lt;row condition&gt;. Note that this command will fail
	  if the &lt;row condition&gt; condition does not return exactly one value.</para>
	  <para>
	    The following example defined a "bl10" variable containing the value of the "blob" column in the "blobs" table
	    for the "id=10" condition:
	    <programlisting>
.setex bl10 blobs blob "id=10"
	    </programlisting>
	  </para>
	</listitem>
      </itemizedlist>
    </para>
    <para>
      The <command>.export</command> command exports to a file the contents of an internal variable or the
      the contents of a table's value:
      <itemizedlist>
	<listitem><para>The <command>.export &lt;variablename&gt; &lt;filename&gt;</command> usage exports the contents
	    of the named variable into the named filename</para></listitem>
	<listitem><para>The <command>.set &lt;table&gt; &lt;column&gt; &lt;row condition&gt; &lt;filename&gt;</command>
	    usage exports the value of the &lt;table&gt; table and
	  &lt;column&gt; column for the row identified by &lt;row condition&gt;. Note that this command will fail
	  if the &lt;row condition&gt; condition does not return exactly one value.</para>
	</listitem>
      </itemizedlist>
    </para>
  </sect1>

  <sect1>
    <title>Embedded HTTP server</title>
    <para>
      An embedded HTTP server can be executed using the <command>.http [&lt;port&gt; [&lt;authentication token&gt;]]</command> 
      command, or the <option>-s</option> command line option. If no port is specified the 12345 port is used.
    </para>
    <para>
      The web browser's features are:
      <itemizedlist>
	<listitem><para>display meta information such as the lists of tables, views or triggers and their details 
	    for a connection</para></listitem>
	<listitem><para>open an emulated console where SQL commands (and some internal commands) can be run</para></listitem>
      </itemizedlist>
    </para>
    <para>
      Clients must first authenticate before they can use the features mentioned above; authentication is kept simple
      as it consists of a string. By default the requested string is empty (eg. no real authentication is required), but
      an authentication string can be specified when running the web server either with the <command>.http</command> command, 
      or the <option>-t</option> command line option.
    </para>
  </sect1>

  <sect1>
    <title>Environment variables</title>
    <para>
      Several environment variables can be used to customize the behaviour of the console tool (added
      to the <link linkend="libgda_env_variables">general &LIBGDA;'s environment variables</link>):
      <itemizedlist>
	<listitem><para>Upon starting, if the <envar>GDA_SQL_CNC</envar> environment variable is defined,
	    the console tool will try to open a connection using its contents as connection string.
	</para></listitem>
	<listitem><para>The external editor used by the <command>.e</command> command is determined by the first value
	    present in the <envar>GDA_SQL_EDITOR</envar>, <envar>EDITOR</envar> or <envar>VISUAL</envar>
	    environment variables (in that order), and defaults to "vi" under Unix and "notepad.exe" under Windows.
	</para></listitem>
	<listitem><para>The pager used when the data to display is more than one screen is determined by
	    the value of the <envar>PAGER</envar> environment variable and defaults to "more" if none is defined.
	    The paging feature can be completely disabled if the <envar>GDA_NO_PAGER</envar> is defined.</para></listitem>
	<listitem><para>When the <command>.graph</command> is run, and if the GraphViz's <command>dot</command> is found,
	    the console tool will convert the graph to a PNG file and display it using the external viewer 
	    identified by the contents of the <envar>GDA_SQL_VIEWER_PNG</envar> variable if defined (or convert it to a PDF
	    and display it using the external viewer 
	    identified by the contents of the <envar>GDA_SQL_VIEWER_PDF</envar> variable if defined).
	</para></listitem>
	<listitem><para>The command line history file is defined by the contents of the <envar>GDA_SQL_HISTFILE</envar>
	    environment variable. If its contents is set to "NO_HISTORY" then no history will be kept.</para></listitem>
      </itemizedlist>
    </para>
  </sect1>

</chapter>
</part>
