SqllineDocs
From Eigenpedia
SQLLine is a command-line SQL shell which executes statements and retrieves results via JDBC. The version at Sourceforge is not being actively developed, so this page explains how we maintain a fork within Eigenbase.
Contents |
Source Code
The source code for sqlline is maintained in perforce.eigenbase.org under //open/sqlline/....
This BSD codebase was forked out of its original location in the sf.net CVS repository for ease of maintenance. It remains under the BSD license, with the original copyright held by Marc Prud'hommeaux, plus additional Eigenbase copyrights for contributions before the fork and additions after the fork.
Any Eigenbase committer with write access to //open/dev/... automatically has write access to //open/sqlline/... as well.
Build
To build sqlline, just run ant jars after syncing //open/sqlline/.... This will create a file with a name like sqlline/release/sqlline-1_0_5-eb.jar.
To test the new .jar with Farrago:
p4 edit dev/thirdparty/sqlline.jar cp sqlline/release/sqlline-1_0_5-eb.jar dev/thirdparty/sqlline.jar
When done testing, if you're only planning to check in sqlline source for now, then:
p4 revert dev/thirdparty/sqlline.jar
When checking in sqlline sources, prefix your comment with SQLLINE: like this:
Change 10913 on 2008/04/17 by jvs@jvs.kotick.eigenbase
SQLLINE: add support for !set rowlimit (calls Statement.setMaxRows)
Affected files ...
... //open/sqlline/README#2 edit
... //open/sqlline/build.xml#2 edit
... //open/sqlline/doc/manual.xml#2 edit
... //open/sqlline/src/sqlline/SqlLine.java#2 edit
sqlline does not currently have any unit tests of its own; instead, it gets exercised by many Farrago unit tests (a few specific sqlline features are tested by cases in dev/farrago/unitsql/sqlline). In the future, we may want to start adding unit tests under the sqlline project too.
Eigenbase Inclusion
Eigenbase sub-projects under //open/dev (such as Farrago) depend on the sqlline .jar, but they do not build it from source. Instead, we check in the .jar directly as //open/dev/thirdparty/sqlline.jar. To do this, follow the steps in the previous section, but do not revert at the end.
In addition, we also check in a corresponding source distribution for every sqlline update. The reason for this is so that when we build a full Eigenbase source distribution, it includes the source for the correct version of sqlline as well.
Before starting on upgrading the inclusion, p4 edit sqlline/project.properties and increase the patch number (keeping the -eb suffix to mark it as the Eigenbase fork). For example, if you currently see this line:
version.patch: 5-eb
Change it to
version.patch: 6-eb
(For large changes, an update to the major or minor version may be more appropriate; raise it on the farrago-dev mailing list.)
Before continuing, submit the Perforce change for bumping up the version.
Now, the source distribution can be generated by running the following from //open/sqlline:
ant -Ddocbook.skip=yes srcjar
This will produce a file like sqlline/release/sqlline-src-1_0_6-eb.jar.
Here's how to upgrade the inclusion (this example matches the move from patch version 5 to 6, so make the appropriate adjustments):
p4 delete dev/thirdparty/sqlline-src-1_0_5-eb.jar cp sqlline/release/sqlline-src-1_0_6-eb.jar dev/thirdparty p4 add dev/thirdparty/sqlline-src-1_0_6-eb.jar p4 edit dev/thirdparty/Makefile
Now, in dev/thirdparty/Makefile, you have to update the sqlline target version:
sqlline: sqlline-src-1_0_6-eb.jar -rm -rf $@ jar xf $< mv sqlline-1_0_6-eb sqlline touch $@
Finally, run make all under dev/thirdparty to unpack the new sources for completeness.
After running/updating all tests appropriate for the Eigenbase branch you are modifying, p4 submit to check in both the binary and source simultaneously. Your changelist should look like this:
Description:
DEV/THIRDPARTY/FARRAGO: upgrade sqlline to 1.0.6, and add
Farrago unit tests for new !set thatisfail feature
Files:
//open/dev/farrago/unitsql/sqlline/display.ref # edit
//open/dev/farrago/unitsql/sqlline/display.sql # edit
//open/dev/thirdparty/Makefile # edit
//open/dev/thirdparty/sqlline-src-1_0_5-eb.jar # delete
//open/dev/thirdparty/sqlline-src-1_0_6-eb.jar # add
//open/dev/thirdparty/sqlline.jar # edit
Dependency on jline
A separate project, jline, is required by sqlline as part of implementing console tricks such as up-arrow/down-arrow for visiting the command history. A copy of this is checked in as //open/sqlline/lib/jline.jar for build purposes. However, this .jar is not included in the sqlline distribution. Instead, it is currently checked in separately into Eigenbase thirdparty. The currently checked-in version is //open/dev/thirdparty/jline-0_9_5.jara, which gets copied as dev/thirdparty/jline.jar (stripping off the version number) by dev/thirdparty/Makefile.
When upgrading jline, the correct procedure is to first upgrade the build copy (//open/sqlline/lib/jline.jar), testing it out to make sure that everything still works, and making any corresponding changes to the sqlline source code. Then, upgrade in //open/dev/thirdparty (including an upgrade to the sqlline archive in the same checkin if necessary due to dependency changes).
--Jvs 18:53, 17 April 2008 (PDT): The version of jline we are using is quite old; we might want to look into upgrading to the latest.
