HyperSQL Utilities Guide

Hsqldb Test Utility Hsqldb Test Utility The org.hsqldb.test package contains a number of tests for various functions of the database engine. Among these, the TestUtil class performs the tests that are based on scripts. To run the tests, you should compile the hsqldbtest.jar target with Ant and JUnit. The TestUtil class should be run in the /testrun/hsqldb directory of the distributed files. It then runs the set of TestSelf*.txt files in the directory. To start the application in Windows, change to the directory and type: java org.hsqldb.test.TestUtil All files in the working directory with names matching TestSelf*.txt are processed in alphabetical order. You can add your own scripts to test different series of SQL queries. The format of the TestSelf*.txt file is simple text, with some indentation and prefixes in the form of Java-style comments. The prefixes indicate what the expected result should be. The class org.hsqldb.test.TestScriptRunner is a more general program which you can use to test any script files which you specify (with scripts of the same exact format as described below). For example, java org.hsqldb.test.TestScriptRunner --urlid=mem script1.tsql script2.sql You must have the HSQLDB classes, including the util and test classes, in your CLASSPATH. The urlid must be set up in an RC file as explained in the section. Use the rcfile= argument to specify an RC file other than the default of testscriptrunner.rc in the current directory. To see all invocation possibilities, just run TestScriptRunner with no arguments at all. TestScriptRunner can run tests sequentially (the default) or in simultaneous asynchronous threads. Comment lines must start with -- and are ignored Lines starting with spaces are the continuation of the previous line (for long SQL statements) SQL statements with no prefix are simply executed. The remaining items in this list exemplify use of the available command line-prefixes. The /*s*/ option stands for silent. It is used for executing quries regardless of results. Used for preparation of tests, not for actual tests. /*s*/ Any SQL statement - errors are ignored The /*c<rows>*/ option is for SELECT queries and asserts the number of rows in the result matches the given count. /*c<rows>*/ SQL statement returning count of <rows> The /*u*/ option is for queries that return an update count, such as DELETE and UPDATE. It asserts the update count matches. /*u<count>*/ SQL statement returning an update count equal to <count> The /*e*/ option asserts that the given query results in an erros. It is mainly used for testing the error detection capabilities of the engine. The SQL State of the expected error can be defined, for example /*e42578*/, to verify the returned error. This option can be used with syntactically valid queries to assert a certain state in the database. For example a CREATE TABLE can be used to assert the table of the same name already exists. /*e*/ SQL statement that should produce an error when executing The /*r....*/ option asserts the SELECT query returns a single row containing the given set of field values. /*r<string1>,<string2>*/ SQL statement returning a single row ResultSet equal to the specified value The extended /*r...*/ option asserts the SELECT query returns the given rows containing the given set of field values. /*r <string1>,<string2> <string1>,<string2> <string1>,<string2> */ SQL statement returning a multiple row ResultSet equal to the specified values (note that the result set lines are indented). The /*d*/ directive just displays the supplied text. /*d*/ Some message The /*w MILLIS*/ directive causes the test to Wait for a specified number of millisedonds. /*w 1000*/ Optional message The /*w ENFORCE_SEQUENCE WAITER_NAME*/ directive causes the test to Wait for the specified Waiter. A waiter is just name that is used to associate a /*w*/ directive to its corresponding /*p*/ directive. The ENFORCE_SEQUENCE argument must be set to true or false to specify whether to fail unless the /*p*/ command runs after the /*w*/ command is waiting. /*w true script4*/ Optional message The /*p ENFORCE_SEQUENC WAITER_NAME*/ directive is the peer directive to /*w*/, which causes a waiting thread to Proceed. /*p true script4*/ Optional message All the options are lowercase letters. During development, an uppercase can be used for a given test to exclude a test from the test run. The utility will just report the test blocks that have been excluded without running them. Once the code has been developed, the option can be turned into lowercase to perform the actual test. See the TestSelf*.txt files in the /testrun/hsqldb/ directory for actual examples. The String ${timestamp} may be used in script messages (like in /*d*/, /*w*/, /*p*/). It expands to the current time, down to the second. For example, /*d*/ It is now ${timestamp} Database Manager Fred Toussi The HSQL Development Group Blaine Simpson The HSQL Development Group $Revision: 4602 $ ×tamp; Hsqldb Database Manager

Brief Introduction The Database Manager tool is a simple GUI database query tool with a tree display of the tables. Both AWT and SWING versions of the tool are available and work almost identically. The AWT version class name is org.hsqldb.util.DatabaseManager; the SWING version, org.hsqldb.util.DatabaseManagerSwing. The SWING version has more refinements than the AWT version. The AWT version of the database manager can be deployed as an applet in a browser. A demo HTML file with an embedded Database Manager is included in the /demo directory. When the Database Manager is started, a dialogue allows you to enter the JDBC driver, URL, user and password for the new connection. A drop-down box, Type, offers preset values for JDBC driver and URL for most popular database engines, including HSQLDB. Once you have selected an item from this drop-down box, you should edit the URL to specify the details of the database or any additional properties to pass. You should also enter the username and password before clicking on the OK button. The connection dialogue allows you to save the settings for the connection you are about to make. You can then access the connection in future sessions. To save a connection setting, enter a name in the Setting Name box before clicking on the OK button. Next time the connection dialogue is displayed, the drop-down box labeled Recent will include the name for all the saved connection settings. When you select a name, the individual settings are displayed in the appropriate boxes. The small Clr button next to the drop-down box allows you to clear all the saved settings. If you want to modify an existing setting, first select it from the drop-down box then modify any of the text boxes before making the connection. The modified values will be saved. Most SWING menu items have context-sensitive tool tip help text which will appear if you hold the mouse cursor still over the desired menu item. (Assuming that you don't turn Tooltips off under the Help menu. The database object tree in the SWING version allows you to right click on the name of a table or column and choose from common SQL statements for the object, for example SELECT * FROM thistable ... If you click on one of the given choices, the sample statement is copied to the command window, where you can modify and complete it. The DatabaseManagers do work with HSQLDB servers serving TLS-encrypted JDBC data. See the TLS section of the Listeners chapter of the HyperSQL User Guide If you are using DatabaseManagerSwing with Oracle, you will want to make sure that Show row counts and Show row counts are both off before connecting to the database. You may also want to turn off Auto tree-update, as described in the next section.

Auto tree-update By default, the object tree in the left panel is refreshed when you execute DDL which may update those objects. If you are on a slow network or performance-challenged PC, use the view / Auto-refresh tree menu item to turn it off. You will then need to use the viewRefresh tree menu item every time that you want to refresh the tree. Auto-refresh tree does not automatically show all updates to database objects, it only refreshes when you submit DDL which may update database objects. (This behavior is a compromise between utility and performance).

Automatic Connection You can use command-line switches to supply connection information. If you use these switch(es), then the connection dialog window will be skipped and a JDBC connection will be established immediately. Assuming that the hsqldb.jar (or an alternative jar) are in your CLASSPATH, this command will list the available command-line options. java org.hsqldb.util.DatabaseManagerSwing --help It's convenient to skip the connection dialog window if you always work with the same database account. Use of the --password switch is not secure. Everything typed on command-lines is generally available to other users on the computer. The problem is compounded if you use a network connection to obtain your command line. The RC File section explains how you can set up automatic connections without supplying a password on the command line.

RC File You can skip the connection dialog window securely by putting the connection information into an RC file and then using the --urlid switch to DatabaseManager or DatabaseManagerSwing. This strategy is great for adding launch menu items and/or launch icons to your desktop. You can set up one icon for each of the database accounts which you regularly use. The default location for the RC file is dbmanager.rc in your home directory. The section explains how to put the connection information into this text file. If you also run , then you can share the RC file with SqlTool by using a sym-link (if your operating system supports sym links), or by using the --rcfile switch for either SqlTool or DatabaseManagerSwing. Use your operating system facilities to prevent others from reading your RC file, since it contains passwords. To set up launch items/icons, first experiment on your command line to find exactly what command works. For example, java -cp /path/to/hsqldb.jar org.hsqldb.util.DatabaseManagerSwing --urlid mem Then, use your window manager to add an item that runs this command.

Using the current DatabaseManagers with an older HSQLDB distribution. This procedure will allow users of a legacy version of HSQLDB to use all of the new features of the DatabaseManagers. You will also get the new version of the SqlTool! This procedure works for distros going back to 1.7.3.3 at least, probably much farther. These instructions assume that you are capable of running an Ant build. See the Building Appendix of the HyperSQL User Guide. Download and extract a current HSQLDB distribution. If you don't want to use the source code, documentation, etc., you can use a temporary directory and remove it afterwards. Cd to the build directory under the root directory where you extracted the distribution to. Run ant hsqldbutil. If you're going to wipe out the build directory, copy hsqldbutil.jar to a safe location first. For now on, whenver you are going to run DatabaseManager*, make sure that you have this hsqldbutil.jar as the first item in your CLASSPATH. Here's a UNIX example where somebody wants to use the new DatabaseManagerSwing with their older HSQLDB database, as well as with Postgresql and a local application. CLASSPATH=/path/to/hsqldbutil.jar:/home/bob/myapp/classes:/usr/local/lib/pg.jdbc3.jar export CLASSPATH java org.hsqldb.util.DatabaseManagerSwing --urlid urlid

DatabaseManagerSwing as an Applet DatabaseManagerSwing is also an applet. You can use it in HTML, JSPs, etc. Be aware that in Applet mode, actions to load or save local files will be disabled, and attempts to access any server other than the HTML-serving-host will fail. Since the Applet can not store or load locally saved preferences, the only way to have persistent preference settings is by using Applet parameters. DatabaseManagerSwing Applet Parameters jdbcUrl URL of a data source to auto-connect to. String value. jdbcDriver URL of a data source to auto-connect to. String value. Defaults to org.hsqldb.driver.JDBCDriver. jdbcUser User name for data source to auto-connect to. String value. jdbcPassword Password for data source to auto-connect to. String value. Defaults to zero-length string. schemaFilter Display only object from this schema in the object navigator. String value. laf Look-and-feel. String value. loadSampleData Auto-load sample data. Boolean value. Defaults to false. autoRefresh Auto-refresh the object navigator when DDL modifications detected in user SQL commands. Boolean value. Defaults to true. showRowCounts Show number of rows in each table in the object navigator. Boolean value. Defaults to false. showSysTables Show system tables in the object navigator. Boolean value. Defaults to false. showSchemas Show object names like schema.name in object navigator. Boolean value. Defaults to true. resultGrid Show query results in Gui grid (as opposed to in plain text). Boolean value. Defaults to true. showToolTips Show help hover-text. Boolean value. Defaults to true.

Transfer Tool Fred Toussi The HSQL Development Group $Revision: 4602 $ ×tamp; Hsqldb Transfer

Brief Introduction Transfer Tool is a GUI program for transferring SQL schema and data from one JDBC source to another. Source and destination can be different database engines or different databases on the same server. Transfer Tool works in two different modes. Direct transfer maintains a connection to both source and destination and performs the transfer. Dump and Restore mode is invoked once to transfer the data from the source to a text file (Dump), then again to transfer the data from the text file to the destination (Restore). With Dump and Restore, it is possible to make any changes to database object definitions and data prior to restoring it to the target. Dump and Restore modes can be set via the command line with -d (--dump) or -r (--restore) options. Alternatively the Transfer Tool can be started with any of the three modes from the Database Manager's Tools menu. The connection dialogue allows you to save the settings for the connection you are about to make. You can then access the connection in future sessions. These settings are shared with those from the Database Manager tool. See the appendix on Database Manager for details of the connection dialogue box. From version 1.8.0 Transfer Tool is no longer part of the hsqldb.jar. You can build the hsqldbutil.jar using the Ant command of the same name, to build a jar that includes Transfer Tool and the Database Manager. When collecting meta-data, Transfer Tool performs SELECT * FROM <table> queries on all the tables in the source database. This may take a long time with some database engines. When the source database is HSQLDB, this means memory should be available for the result sets returned from the queries. Therefore, the memory allocation of the java process in which Transfer Tool is executed may have to be high. The current version of Transfer is far from ideal, as it has not been actively developed for several years. The program also lacks the ability to create UNIQUE constraints and creates UNIQUE indexes instead. However, some bugs have been fixed in the latest version and the program can be used with most of the supported databases. The best way to use the program is the DUMP and RESTORE modes, which allow you to manually change the SQL statements in the dump file before restoring to a database. A useful idea is to dump and restore the database definition separately from the database data.