SqllineDocs

From Eigenpedia

Jump to: navigation, search

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.