db-derby-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel John Debrunner <...@apache.org>
Subject Re: [WWD] Feedback requested on Chapters 1 and 2 of Working With Derby
Date Tue, 21 Feb 2006 05:40:25 GMT
Stanley Bradbury wrote:

> Please participate in the review of the  first two chapters of the
> Working With Derby document.  The HTML files can be downloaded for
> review from DERBY-913 using the URL:

These first two chapters seems like a clone of the getting starting
guide to me, at least along the same approach. Therefore I'm not sure
how this is making it easier for people to start using Derby.

I'll repeat my earlier comments that I wonder if there's a better
approach, aimed at having "activity 1" getting the user running SQL in
less than three pages, rather than taking seven pages to running sysinfo.

I'd like an approach of peeling the layers away, start simple with a
single configuration, get that working, then move onto others.

Your activity 1 dances around configurations, saying there are several
but not going down any single path. Then I'm left on this page:


with three setup scripts, do I run all, one only, or what? To someone
who does not know Java, databases and/or Derby I think this is confusing.

Then the last page


is meant to verify my setup, but the instructions state

"... displays the information that describes (to the trained eye) the
configuration of the Derby ..."

but I'm not a "trained eye", I'm a newcomer, how does this page help me
verify my setup and correct configuration.

I think if you focussed on complete novices then one approach would be
to hide the Java, classpath, configurations stuff as much as possible at
first, and instead work out how to get to the ij> prompt as soon as

Ideally it would be:

 1) You've just installed Derby, now start the SQL command line
processor ij.

  c:\> ij

 2) Execute this command to create a database

   ij> connect 'mydb;create=true';

 3) Create a table
   ij> create table etc. etc.

Once the activities have worked through some SQL examples etc, you can
then expand into what is happening behind the scenes, that it's
embedded, where the database is, what the class path is and what it
means, what ij is doing in terms of JDBC, etc. etc.

Another starting point would be for the person used to client/server, a
more natural start for them would be to have a start server command, and
then get into ij, don't even mention embedded, or jar files.

   1) You've just installed Derby, now start the database server
       don't worry about details, we'll explain those later

     c:\> java -jar lib\derbynet.jar start

   2) Now start the command line processor

     c:\> ij

   3) Create a database on the server

      ij> connect '//localhost/mydb;create=true';

    etc. etc.

An aside - ij is described as 'Derby's interactive JDBC scripting tool.
ij has a set of commands that provide JDBC processing capabilities and
also supports execution of SQL commands.' which is based upon its
Javadoc. I realised over the weekend when I was looking at the javadoc
that this is a really bad description of the tool, and has been for a
long long time. ij's primary purpose is a command line processor for
*SQL*, describing it as a *JDBC* scripting tool is just confusing for
folks used to other databases that have SQL command line processors.

Thanks for working on this Stan, but I really do believe that a
different approach is needed compared to existing approach taken by the
Getting Starting guide (that's been around for eight+ years).

To repeat my earlier concern, if getting to the first query is hard, we
will lose most of the newcomers in these early setup steps, the first 2%
of such a tutorial is probably the most important.


View raw message