Clark C. Evans committed 48479bd

making HTSQL-CTL - HTSQL command-line administrative application
Copyright (c) 2006-2012, Prometheus Research, LLC

Run `htsql-ctl help` for general usage and list of routines.
Run `htsql-ctl help <routine>` for help on a specific routine. get prompt or use stdin

Comments (0)

Files changed (4)

 exclude these proprietary adapters.
 In this repository, some components considered broadly useful, but
-ancillary to HTSQL itself, are released under the MIT license. Example
+ancillary to HTSQL itself, are released under the MIT license.  Example
 code snippets, configuration, and applications are placed into the
-public domain using the CC0 copyright dedication. These exceptions to
+public domain using the CC0 copyright dedication.  These exceptions to
 the general license outline above are marked on a file by file basis.
 To join this project or learn about how to contribute, please read  In particular, most enhancements for HTSQL
 could be added through a runtime extension mechanism and do not require
 write access to this source code repository.
    :depth: 1
-This handbook presumes you have finished :doc:`installing
-<admin/install>` HTSQL and have had a chance to skim our
-:doc:`overview <overview>` to get a taste of HTSQL.
+This handbook presumes you have :doc:`installed <admin/install>` HTSQL
+and have had a chance to skim our :doc:`overview <overview>` to get a
+taste of HTSQL.  We also assume that you have a GNU/Linux based system,
+although Cygwin, OSX or FreeBSD might work with only a few tweaks. 
+If you need help, please see our `HTSQL Community
+<>`_ page for assistance.
+Up & Running
+In this section we work through the basics of ``htsql-ctl``.  For
+starters, you should be able to print the ``version`` information 
+and then ``help``::
+  $ htsql-ctl version
+  ...
+  $ htsql-ctl help
+  ...
+If ``htsql-ctl`` isn't found or it doesn't work, then you have an
+installation issue and should fix that first.
+First Steps
+The HTSQL interpreter requires a database, passed as a database URI on
+the command line.  The built-in SQLite database adapter has an empty,
+in-memory database, called ``:memory:``.  You could connect to it, and
+then type ``/'Hello World'`` to run your first query::
+  $ htsql-ctl shell sqlite::memory:
+  :memory:$ /'Hello World'
+  ...
+  :memory:$ quit
+The next step might be to download the ``htsql_demo`` database so that
+you could walk through :doc:`overview` and :doc:`tutorial <tutorial>`
+examples as you might wish::
+   $ fetch
+   $ htsql-ctl shell sqlite:htsql_demo.sqlite
+   htsql_demo.sqlite$ /school
+   ...
+The command ``shell`` has limited schema-based completion.  So, you
+could type ``/s<TAB>`` to see tables that start with ``'s'`` which
+include ``school``, ``semester``, and ``student``.


         The database name.
-        For SQLite, the path to the database file.
+        For SQLite, the path to the database file, or `:memory:`.
         A dictionary containing extra connection parameters.
         # If a string is given, assume it is a connection URI and parse it.
         if isinstance(value, str):
+            if value in ('sqlite:memory:', 'sqlite::memory:', 'sqlite:///:memory:'):
+                 value = 'sqlite:///%3Amemory%3A'
             match =
             if match is None:
                 raise ValueError("expected a connection URI of the form"


                      ContentTypeOption, ExtensionsOption, ConfigOption)
 from ..core.util import DB, maybe, oneof, listof, tupleof, dictof, filelike
 from ..core.validator import DBVal, StrVal
+import os
 import sys
 import wsgiref.util
 import urllib
     arguments = [
             Argument('db', DBVal(),
                      hint="""the connection URI"""),
-            Argument('query', StrVal(),
+            Argument('query', StrVal(), default=None,
                      hint="""the HTSQL query"""),
     # These are common options for both routines.  The `post` routine
+        # read query from stdin if not on command line
+        if self.query is None:
+            self.query = self.ctl.input("What is the query?")
         # Load addon configuration.
         extensions = self.extensions
         if self.config is not None: