Running SQL Relay

Note: if you are using SQL Relay on Cygwin, see Cygwin Considerations below.

Starting SQL Relay

Use the sqlr-start program to start the SQL Relay server processes.

sqlr-start -id ID [-config CONFIGFILE] [-localstatedir LOCALSTATEDIR]

The sqlr-start program starts up one instance of sqlr-listener, one instance of sqlr-scaler and the number of sqlr-connection daemons specified in the config file for the given ID.

CONFIGFILE is the filename of the configuration file to use. The default configuration file is /usr/local/firstworks/etc/sqlrelay.conf

If the optional LOCALSTATEDIR argument is used, it is passed to the programs started by sqlr-start as appropriate.

Debugging and Tracing

The CONFIGFILE can be configured to load a debug logger module. When it is configured, the sqlr-listener and/or sqlr-connection daemons output debugging information to files in /usr/local/firstworks/var/sqlrelay/debug. See the SQL Relay Configuration Reference and Logger Modules for more information on debugging.

The sqlr-start program also takes an optional -strace parameter. When run as root, if the -strace parameter is used, sqlr-start starts the sqlr-connection daemons using strace -ff -o sqlr-connection-strace causing sqlr-connection-strace.pid files to be written to the root directory. See the strace man page for more information.

Stopping and Restarting SQL Relay

The sqlr-stop command is provided to kill running instances of SQL Relay. It accepts two optional arguments: the id of the instance to kill and SIGKILL.

sqlr-stop [id] [SIGKILL]

Running it with an id kills sqlrelay processes that were started with the supplied id. Running it with no arguments will kill all SQL Relay processes.

Supplying sqlr-stop with the SIGKILL option will cause it to pass the -9 option to the kill command. It is not possible to supply the SIGKILL option without supplying an id. Note that when the SIGKILL option is used, semaphores and shared memory segments will be left lying around and will need to be cleaned up. Use the ipcs and ipcrm commands to clean them up.

Using the Command Line Interfaces

Several command line utilities are provided for use with SQL Relay. The syntax for each is as follows:

backupschema HOST PORT USER PASSWORD
sqlr-query -host HOST -port PORT -socket SOCKET -user USER -password PASSWORD -query QUERY
sqlr-fields -host HOST -port PORT -socket SOCKET -user USER -password PASSWORD -table TABLE
sqlrsh -host HOST -port PORT -socket SOCKET -user USER -password PASSWORD
sqlr-export -host HOST -port PORT -socket SOCKET -user USER -password PASSWORD (-table TABLE | -sequence SEQUENCE) > exportfile.xml
sqlr-import -host HOST -port PORT -socket SOCKET -user USER -password PASSWORD -file exportfile.xml

or, if there's an sqlrelay.conf file that the client can read:

sqlr-query -id ID -query QUERY
sqlr-fields -id ID -table TABLE
sqlrsh -id ID
sqlr-export -id ID (-table TABLE | -sequence SEQUENCE) > exportfile.xml
sqlr-import -id ID -file exportfile.xml

The HOST, PORT, SOCKET, USER and PASSWORD arguments specify which listener to connect to and what authentication to use.

The ID argument refers to an entry in the sqlrelay.conf file from which host, port, socket, user and passwords can be read.

The sqlr-query command executes the query specified in the QUERY parameter and returns the result set as a quote/comma/return seperated value list to standard output.

The sqlr-fields command returns a comma seperated list of the fields in the table specified by the TABLE argument to standard output.

The backupschema command only works against oracle databases and uses the "select table_name from user_tables" query in combination with the sqlr-query and sqlr-fields commands to generate Oracle SQL Loader control files for all tables owned by the user a particular connection is logged in as. The command is useful for backing up an entire schema of data to a readily re-importable format.

sqlrsh is an interactive query tool similar to (though not as powerful as) SQL Plus, mysql, psql, isql and the like. Run it and type help; at the prompt for detailed usage instructions. When sqlrsh starts up, it reads and executes two rc files, the system rc file (most likely /usr/local/firstworks/etc/sqlrshrc) and a personal rc file .sqlrshrc in your home directory. These files should contain sqlrsh commands, ending in semicolons, seperated by carraige returns. Any sqlrsh commands may be used in the rc files, even queries.

The sqlr-export command exports the specified table or sequence to a file from which sqlr-import can later re-import it.

The sqlr-import command reads the specified file and imports the data contained in the file into the table or sequence specified in the file. Note, that sqlr-import does not create tables or sequences, it just imports data into an already-existing table or sequence.

sqlr-export and sqlr-import may be used to export data from one database and import it into another database, even if the databases are dissimilar (eg. one is PostgreSQL and the other is MySQL), if the structures of the tables in both databases are compatible.

On Windows, if you built SQL Relay natively using Visual Studio, then the command-line clients can be run from the Windows Command Line or DOS Prompt. Adding C:\Program Files\Firstworks\bin to the PATH environment variable makes this easier, though is is not essential. You could just change directories to C:\Program Files\Firstworks\bin and run the programs from there.

If you built SQL Relay under Cygwin then you must use the Cygwin shell to run the command-line clients.

Using The Status Monitor

The sqlr-status program displays statistics about a running SQL Relay instance. You can run it as follows, replacing instance with the name of the SQL Relay instance that you would like to read statistics from:

sqlr-status -id instance

Currently it generates output like:

  Open   Database Connections:  0
  Opened Database Connections:  394

  Open   Database Cursors:      0
  Opened Database Cursors:      2286

  Open   Client Connections:    0
  Opened Client Connections:    394

  Times  New Cursor Used:       267
  Times  Cursor Reused:         2571

  Total  Queries:               3542
  Total  Errors:                1

  Forked Listeners:             0

Scaler's view:
  Connections:                  0
  Connected Clients:            0

Mutexes:
  Connection Announce               : acquired     (1)
  Shared Memory Access              : acquired     (1)
  Connection Count                  : acquired     (1)
  Session Count                     : acquired     (1)
  Open Connections/Forked Listeners : acquired     (1)

Triggers:
  Accept Available Connection (l-w, c-s)         : not triggered (0)
  Done Accepting Available Connection (c-w, l-s) : not triggered (0)
  Evaluate Connection Count (s-w, l-s)           : not triggered (0)
  Done Evaluating Connection Count (l-w, s-s)    : not triggered (0)
  Connection Has Started (s-w, c-s)              : not triggered (0)

Counts:
  Busy Listener Count : 0

Raw Semaphores:
  +---------------------------------------------+
  | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |  10 |
  +---+---+---+---+---+---+---+---+---+---+-----+
  | 1 | 1 | 0 | 0 | 1 | 1 | 0 | 0 | 0 | 1 |   0 |
  +---------------------------------------------+

Here are descriptions of the statistics:

The rest of the stats are useful when reporting suspected bugs but are much more value to SQL Relay developers than users.

Common Problems Cygwin Considerations

If you are not running SQL Relay under Cygwin then you can skip this section.

If you are running SQL Relay under Cygwin then you must first install the Cygwin IPC server. SQL Relay makes extensive use of shared memory and semaphores. The Cygwin IPC server simulates these facilities on Windows. Install the server as a service and start it up following the instructions here.

After installing the Cygwin IPC server, you need to add a CYGWIN environment variable. Use the System control panel to add an environment variable called CYGWIN with the value server.

Once the IPC server is running, start up the database and follow the standard instructions below for running SQL Relay.

Make sure to execute the instructions from within a Cygwin shell rather than from the Windows Command Line or DOS shell. Do not ssh into your windows machine and run from SQL Relay from that shell. When logging in over ssh, the CYGWIN environment variable get's overridden and doesn't contain server, preventing SQL Relay from using the Cygwin IPC server.

Currently, there is no facility for installing SQL Relay as a service, so it must be started and stopped manually from a Cygwin shell.