Reading from SQL Databases

With appropriate configuration, TOPCAT can be used to examine the results of queries on a relational database such as MySQL. This requires the installation of an appropriate JDBC driver specific to that database, as well as, of course, access to such a database locally or over a network.

To use TOPCAT in this way you must:

Have access to an SQL-compatible database locally or over the network
Have a JDBC driver appropriate for that database available
Install this driver for use with TOPCAT
Know the format the driver uses for URLs to access database tables

To install the driver you can do the following. First, add an entry giving the name of the Driver class itself to the "jdbc.drivers" property by ensuring there is a suitable line in a file called ".starjava.properties" in your home directory. For the Connector/J driver for MySQL this would look like:

   jdbc.drivers=com.mysql.jdbc.Driver

Secondly, make sure that the named class is on your classpath when TOPCAT is run. On Unix, do this by ensuring that the jar file containing the driver class is one of the colon-separated entries in your CLASSPATH environment variable.

Database queries have the form

   jdbc:<driver-specific-url>#<sql-query>

The exact form is dependent on the driver. Here is an example for MySQL:

   jdbc:mysql://localhost/astro1?user=mbt
       #SELECT ra, dec FROM swaa WHERE vmag<18

which would get a two-column table (the columns being "ra" and "dec"), constructed from certain rows from the table "swaa" in the database "astro1" on the local host, using the access privileges of user mbt.

Fortunately you do not have to construct this by hand, there is a dialogue box to assist in putting it together. You can use this by pressing the "SQL Database" button in the "Open Table" dialogue. This box includes optional username and password inputs for establishing the connection with the database. If you do not specify them and the database server rejects the connection you will be prompted for these separately.

Note that TOPCAT does not view a table in the database directly, but the result of an SQL query on that table. If you want to view the whole table you may use the query "SELECT * FROM table-name", but be aware that such a query may be expensive on a large table.

TOPCAT has so far only been tested with the MySQL database and its Connector/J JDBC driver. Other databases and drivers may or may not work.