# Gda SQL console's user manual

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 psql, MySQL's mysql, Oracle's sqlplus or SQLite's sqlite3 programs.

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 (`man gda-sql`).

## Getting started

### Features

The &LIBGDA;'s console tool' main features are:

- Handle more than one connection at the same time

- Report meta data in a similar way, whatever the real type of database accessed

- Create virtual connections binding several already opened connections (to run SQL commands across multiple connections)

- Allow one to define variables which can be referenced in any SQL statement (using a common syntax)

- One query buffer per connection to edit complex queries (uses a parameter-able external editor)

- Easy command line editing and output using the Readline library and a (parameter-able) pager

- Work on any platform on which &LIBGDA; has been ported to.

- List, define or remove named data sources (DSN)

- Import and export BLOBS (binary large objects) from and to local files

- On command embedded HTTP server

### Execution

The &LIBGDA;'s SQL console tool runs is a terminal emulator, and can be launched using the `gda-sql` (or `gda-sql-<version>` for a specific version):

    	gda-sql
    	--help
    	-l
    	-L
    	-C command
    	-f commands file
    	-o output file
    	-sport to use to run embedded HTTP server
    	-tauthentication token required to authenticate clients when running the embedded HTTP server
    	connection specification

The options are the following ones:

- the `--help` option gives a short help summary

- the `-l` and `-L` options respectively output a list of the defined data sources (DSN) and of the installed database adaptaters (database providers):

      [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
      [...]

      [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
      [...]

      [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)

- the `-C` and `-f` options repectively allow one to specify a single command to be run or a filename containing the commands to run before the tool exits

- the `-o` option allows to specify a file to write the output to

- the `-s` requests the embedded HTTP server to be executed, listening on the port specified.

- the `-t` specifies a token string which clients will have to supply to authenticate themselves to the HTTP server, if running.

Connections to be opened can be specified on the command line using either:

- defined data sources (the ones listed using the `-l` option)

- connection strings which have the following format: "[<provider>://][<username>[:<password>]@]<connection_params>". 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, <username>, <password> and <provider> must be encoded as per RFC 1738

- for SQLite and MS Access files: the file name

Connections can also be opened while the tool is running using the `.c` internal command.

Examples:

    [prompt]> gda-sql Sales
    [prompt]> gda-sql Postgresql://username@DB_NAME=mydb SQLite://DB_NAME=fspot Sales
    [prompt]> gda-sql path/to/dbfile.db

### Commands

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:

    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>

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:

    cnc2> show search_path;
    search_path
    --------------
    "$user",public
    (1 row)
    cnc2>

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 `.?` to display a help message about all internal commands (with truncated output here):

    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

## DSN management

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.

They can be listed using the `.l` command, and details about a DSN can be listed using the same command with the DSN name as argument:

    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>

The `.lr DSN_NAME [DSN_NAME...]` command removes the DSN listed as arguments, and the The `.lc` command creates (or modifies an existing) DSN, such as show:

    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>

## Connections management

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 `.c` 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:

    gda> .c cnc1 SalesTest
    cnc1>

The list of connection can be listed using the same `.c` command without any argument, for example:

    ia32> .c
              List of opened connections
    Name | Provider | DSN or connection string | Username
    -----+----------+--------------------------+---------
    cnc1 | SQLite   | SalesTest                |
    ia32 | SQLite   | IA32Instructions         |
    (2 rows)
    ia32>

To switch from one connection to the other, use the `.c` command with the connection name to use as single argument, for example to switch from using the "ia32" to the "cnc1" connection:

    ia32> .c cnc1
    cnc1>

### Virtual connections

Multiple connections can be bound together into a single connection in which it is possible to runs SQL statements. This effectively allows one to run SQL statements across multiple databases.

Binding connections together is done using the `.bind CNC_NAME CNC_NAME1 CNC_NAME2 [CNC_NAME ...]` 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 "<cnc name>.<table name>".

In the following example, there are the "cnc1" and "cnc2" connections opened, and the "cnc3" connection is a virtual connection binding "cnc1" and "cnc2":

    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>

The contents of each "customers" table in each of the bound connection is accessible:

    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>

The list of customers present in both tables are available as:

    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>

### Meta data

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.

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 `.meta` 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).

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 `.c ~` command (note that the same command will return to the "cnc1" connection):

    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>

Also note that the meta data's connections are listed among the opened connections, as shown:

    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>

It is possible for any application to create some extra objects in that database for its own purposes, with the constraint that it should not 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.

#### Information about tables

Use the `.dt` command to list all the tables (or list only one table if the table name is specified as an argument to the command):

    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>

To display the details about a single table, use the `.d <table_name>` command:

    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>

Finally, the `.graph [TABLE1 [TABLE2...]]` will create a graph of all the tables (or only the tables mentioned as arguments). The graph creates a GraphViz file named "graph.dot" which can then be processed with the GraphViz'`dot` command to produce an image or a PDF file for example.

If the `GDA_SQL_VIEWER_PNG` or `GDA_SQL_VIEWER_PDF` environment variables are set (for example to eog or evince) and if the `dot` 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: Sample output from the ".graph" command

#### Information about views

The console tool can report information about views. Use the `.dv` command to list all the views (or list only one view if the view name is specified as an argument to the command):

    cnc1> .dv
                  List of views
    Schema | Name         | Type | Owner | Description
    -------+--------------+------+-------+------------
    main   | cust_summary | VIEW |       |
    (1 row)
    cnc1>

One can also get more information for a single view using the `.d <view name>` command, for example:

    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>

#### Information about schemas

Some databases feature the notion of schema which is a container for database objects such as tables, views, etc. Use the `.dn` command to get a list of all the schemas in a database. For example with a PostgreSQL database:

              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>

#### Information about other objects

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:

    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>

The meta data's database structure is described in the related section.

## Detailed features

This section explains in depth various aspects of the console tool.

### Query buffer

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 `.e` command. The query buffer can also be saved to a file and loaded back later using the `.qw` and `.qr` commands. To execute the SQL held in the current query buffer, use the `.g` command.

Query buffers can be saved to the dictionary (along with the connection's meta data) for future usage using the `.qs buffer_name` command, and loaded back later with the `.ql buffer_name`. To list all the saved query buffers in the dictionary, use the `.qa` command. The following example shows an example output of the `.qa` command where one query buffer has been saved:

    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>

The `.g` 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:

    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>

### Internal parameters

Variables can be defined using the `.set` and `.setex` 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.

When setting values, the textual representation must respect the following format:

- for booleans: "true" or "false" (case insensitive)

- for numerical types: the dot as a fraction separator

- for dates, time and timestamp: the ISO 8601 format (dates as "YYYY-MM-DD", time as "HH:MM:SS")

Use the `.set <variablename> <variable value>` command to define a variable, and the `.set` command to list all defined variables. The following example illustrates variables usage:

    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>

The `.setex` command also sets an internal parameter, it has two usages:

- The `.set <variablename> <filename>` usage loads the contents of the named filename into the named variable (usually to be used as a BLOB)

- The `.set <variablename> <table> <column> <row condition>` usage creates a named variable which contents is the value of the <table> table and <column> column for the row identified by <row condition>. Note that this command will fail if the <row condition> condition does not return exactly one value.

  The following example defined a "bl10" variable containing the value of the "blob" column in the "blobs" table for the "id=10" condition:

      .setex bl10 blobs blob "id=10"

The `.export` command exports to a file the contents of an internal variable or the the contents of a table's value:

- The `.export <variablename> <filename>` usage exports the contents of the named variable into the named filename

- The `.set <table> <column> <row condition> <filename>` usage exports the value of the <table> table and <column> column for the row identified by <row condition>. Note that this command will fail if the <row condition> condition does not return exactly one value.

### Embedded HTTP server

An embedded HTTP server can be executed using the `.http [<port> [<authentication token>]]` command, or the `-s` command line option. If no port is specified the 12345 port is used.

The web browser's features are:

- display meta information such as the lists of tables, views or triggers and their details for a connection

- open an emulated console where SQL commands (and some internal commands) can be run

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 `.http` command, or the `-t` command line option.

### Environment variables

Several environment variables can be used to customize the behaviour of the console tool (added to the general &LIBGDA;'s environment variables):

- Upon starting, if the `GDA_SQL_CNC` environment variable is defined, the console tool will try to open a connection using its contents as connection string.

- The external editor used by the `.e` command is determined by the first value present in the `GDA_SQL_EDITOR`, `EDITOR` or `VISUAL` environment variables (in that order), and defaults to "vi" under Unix and "notepad.exe" under Windows.

- The pager used when the data to display is more than one screen is determined by the value of the `PAGER` environment variable and defaults to "more" if none is defined. The paging feature can be completely disabled if the `GDA_NO_PAGER` is defined.

- When the `.graph` is run, and if the GraphViz's `dot` 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 `GDA_SQL_VIEWER_PNG` variable if defined (or convert it to a PDF and display it using the external viewer identified by the contents of the `GDA_SQL_VIEWER_PDF` variable if defined).

- The command line history file is defined by the contents of the `GDA_SQL_HISTFILE` environment variable. If its contents is set to "NO_HISTORY" then no history will be kept.