Installation Instructions=========================The following installation instructions were tested under a fresh installation
of Ubuntu 10.04 Server, but they could be easily adapted to other Linux
distributions and package managers.
TL;DR version-------------1. Install Python and required Python modules::
# apt-get install python
# apt-get install python-setuptools python-simplejson python-pyyaml python-psycopg2
2. Install Mercurial and download HTSQL source code::
# apt-get install mercurial
# hg clone http://bitbucket.org/prometheus/htsql
3. Build and install HTSQL::
# cd htsql
# make build
# make install
This should create a ``htsql-ctl`` script. Run:: $ htsql-ctl help for general help and list of commands. Run:: $ htsql-ctl server ENGINE://USERNAME:PASSWORD@HOST:PORT/DATABASE [HOST [PORT]] to start an HTSQL server on the address `HOST:PORT` against the specified
database. In particular, to run the HTSQL server against a PostgreSQL
database deployed on the same machine with credentials of the current
user, run:: $ htsql-ctl server pgsql:///DATABASEInstalling prerequisites------------------------HTSQL requires Python 2.5 or newer, but does not support Python 3 yet.
Python 2.6 is the recommended version. In some distributions, Python is
already installed; if not, you could install it by running:: # apt-get install pythonHTSQL depends on the following external Python packages:
*`setuptools` (0.6c9 or newer);
*`simplejson` (2.0 or newer);
*`PyYAML` (3.07 or newer, compiled with LibYAML bindings);
*`psycopg2` (2.0.10 or newer, earlier versions are known to segfault).
To install the packages, run:: # apt-get install python-setuptools python-simplejson python-pyyaml python-psycopg2Alternatively, you could install these Python modules from sources using the
`easy_install` script from `setuptools`. To do that, you need to install
header files for Python, PostgreSQL and LibYAML:: # apt-get install build-essential python-dev libpq-dev libyaml-dev # apt-get install python-setuptools # easy_install simplejson # easy_install PyYAML # easy_install psycopg2This method allows you to choose the directory where the external Python
packages will be installed. By default, `easy_install` installs packages
under ``/usr/local`` directory. To install Python packages under your home
directory, create a file ``.pydistutils.cfg`` in your home directory with
the following content:: [install] user=trueand set the environment variable ``PYTHONUSERBASE``:: export PYTHONUSERBASE=$HOMEThen running `easy_install` will install Python libraries to
``~/lib/python2.6/site-packages`` (when running under Python 2.6) and Python
scripts to ``~/bin``.
For more details on customizing the location of external Python modules, see
`distutils` and `setuptools` documentation.
Installing HTSQL----------------Once HTSQL is officially released, you will be able to install it using the
`easy_install` script:: # easy_install HTSQLThat will download, build and install the latest released version of HTSQL.
Alternatively, you can install HTSQL from the Mercurial repository at
BitBucket. You need a Mercurial client:: # apt-get install mercurialThen download HTSQL sources:: # hg clone http://bitbucket.org/prometheus/htsqlTo build and install HTSQL, run:: # cd htsql # make build # make installTo install HTSQL in the development mode, run:: # make developWhen HTSQL is installed in the development mode, any changes in the source
files are reflected immediately without having to reinstall it again.
HTSQL comes with a comprehensive test suite. Running the regression tests
requires a PostgreSQL server instance. By default, the regression tests
assume that the database server is installed locally and the current user
has administrative permissions. To install a local PostgreSQL server, run:: # apt-get install postgresqlTo add a database user with the same name as your login name, run:: # su - postgres -c "createuser -s $USER"If the host is a single user machine, it is often convenient to allow
any user on the system connect to the database under any database user
name. To do it, open the file ``/etc/postgresql/8.4/main/pg_hba.conf``(replace the version number with the actual version), find the lines:: # "local" is for Unix domain socket connections only local all all identand replace them with:: # "local" is for Unix domain socket connections only local all all trustReload the server configuration:: # service postgresql-8.4 reloadAlternatively, if you already have a PostgreSQL server installed somewhere,
you can specify the address and connection parameters explicitly. Copy the
file ``Makefile.env.sample`` to ``Makefile.env``, open the latter, and edit
the values of variables: ``PGSQL_ADMIN_USERNAME``, ``PGSQL_ADMIN_PASSWORD``,
``PGSQL_HOST``, ``PGSQL_PORT``. They should contain the credentials of
an administrative user and the address of the server respectively.
To run HTSQL regression tests, run:: # make testRunning regression tests creates a database user called ``htsql_regress``with the password ``secret``, and a database called ``htsql_regress``. Feel
free to use this database for playing with HTSQL.
To remove any database users and databases deployed by the regression tests,
run:: # make cleanupTo build the documentation that comes with HTSQL, run
# make doc
Note that this requires Sphinx 1.0+.
Running HTSQL-------------If HTSQL is installed successfully, you should be able to run the
`htsql-ctl` script:: $ htsql-ctlThe script has a number of subcommands called *routines*. In general, the
command line has the form:: htsql-ctl <routine> [options] [arguments]where ``<routine>`` is the routine name, ``options`` is any routine options
in short (``-X``) or long (``--option-name``) form, and ``arguments`` is the
routine arguments. Run:: $ htsql-ctl helpto get a list of routines and:: $ htsql-ctl help <routine>to describe a specific routine.
To start an HTSQL server, run
$ htsql-ctl server ENGINE://USERNAME:PASSWORD@HOST:PORT/DATABASE
Here `ENGINE` is either ``pgsql`` or ``sqlite``; `USERNAME:PASSWORD` are
used for authentication; `HOST:PORT` is the address of the database server;
and `DATABASE` is the name of the database to connect. All parameters
except for `ENGINE` and `DATABASE` are optional. For instance:: $ htsql-ctl server pgsql:///htsql_regresswill start the HTSQL server against the HTSQL regression database (provided
it is deployed by running the regression tests).
By default the server is listening on ``localhost:8080``. To specify a
different address of the HTSQL server, use optional arguments `HOST` and
`PORT`:: $ htsql-ctl server ENGINE://USERNAME:PASSWORD@HOST:PORT/DATABASE HOST PORTFor more help on the ``server`` routine, run:: $ htsql-ctl help serverThe script also allows you to run HTSQL queries from the console using the
``shell`` routine. To start the shell, run:: $ htsql-ctl shell ENGINE://USERNAME:PASSWORD@HOST:PORT/DATABASEThis will display the command prompt where you could type and execute HTSQL
queries. For more details, run
$ htsql-ctl help shell
or type ``help`` in the shell.
.. TODO: Installing on MS WindowsHave fun and enjoy!