---
name: "gda-sql-4.0"
section: "1"
platform: "linux"
package: "libgda-4.0-bin"
version: "4.0.12-1"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/gda-sql-4.0"
---

# gda-sql-4.0(1)

an SQL console based on Libgda

## NAME

gda-sql - an SQL console based on Libgda

## SYNOPSIS

**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 spec...\]

## DESCRIPTION

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.

## OPTIONS

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 specified).

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

## ENVIRONMENT

gda-sql respects a number of environment variables.

- **GDA\_SQL\_CNC**

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

- **GDA\_NO\_PAGER**

  to specify that no text pager should be used.

- **GDA\_SQL\_EDITOR EDITOR VISUAL**

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

- **GDA\_SQL\_VIEWER\_PNG**

  to define a PNG viewer.

- **GDA\_SQL\_VIEWER\_PDF**

  to define a PDF viewer.

- **GDA\_SQL\_HISTFILE**

  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.

## FILES

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\>* connection.

- **.close**

  Closes a connection. Full syntax is: **.close \<CNC\_NAME\>**.

- **.cd**

  Changes the current working directory. Full syntax is: **.cd \<DIR\_NAME\>**.

- **.copyright**

  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\>\]**.

- **.export**

  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 "gdaph.dot" 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 provider.

- **.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 removed.

  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 \<QUERY\_BUFFER\_NAME\>**

- **.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 buffer.

- **.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 *\<NAME\>*.

- **.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\>*.

## SUGGESTIONS AND BUG REPORTS

Any bugs found should be reported to the online bug-tracking system available on the web at http://bugzilla.gnome.org/. 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.

## OTHER INFO

Consult the Libgda's home page at http://www.gnome-db.org/.

## AUTHORS

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

## SEE ALSO

[**psql**(1)](/psql/1.md), [**mysql**(1)](/mysql/1.md), [**sqlite3**(1)](/sqlite3/1.md)