command line. For example, to enable the :ref:`tweak.meta` addon on the
HTSQL demo database, you'd write::
- $ htsql-ctl shell -
E tweak.meta pgsql:htsql_demo
+ $ htsql-ctl shell pgsql:htsql_demo
Then, you could use the ``/meta()`` command registered by this addon:
``limit`` number of rows. The default is 10k, but this value
- $ htsql-ctl shell -E tweak.autolimit:limit=10
+ $ htsql-ctl shell -E tweak.autolimit:limit=10
If more than one parameter is possible, use "," to separate them::
- $ htsql-ctl shell -E tweak.hello:repeat=3,address=home pgsql:htsql_demo
+ $ htsql-ctl serve pgsql:htsql_demo \
+ -E "tweak.shell:server-root='http://demo.htsql.org',limit=10"
HTSQL plugins are found using Python's entry point feature. When a
Python package is installed, it can register itself as an
In this example, there are three plugins enabled, ``htsql`` (which is a
-mandatory plugin), :ref:`tweak.autolimit` and ref:`tweak.shell.default`.
+mandatory plugin), :ref:`tweak.autolimit` and ref:`tweak.shell.default`.
The ``htsql`` plugin has one argument, ``db`` which has sub-structure
providing connection information. You could then use this
configuration file using ``-C``::
values provided in the configuration file. This permits a configuration
file to be used as a default perhaps using a different database URI.
+A configuration parameter may be loaded from another file using
+``!include`` tag. In the following example, definitions of custom
+functions for :ref:`tweak.override` addon are loaded from
+ globals: !include "globals.yaml"
+ num_school: (count(@school))
+ trunc_month($d): (date(year($d), month($d), 1))
.. _YAML: http://yaml.org/
.. _JSON: http://json.org/
Every component except ``engine`` and ``database`` is optional.
+The parameter ``password`` allows you to override the database password
+keeping the other connection parameters intact.
+ Enable debugging output.
+When ``debug`` option is set, text output, as well as some error
+messages will contain a respective SQL query.
.. index:: engine.sqlite, engine.pgsql, engine.mysql, engine.oracle,
.. _CORS: http://www.w3.org/TR/cors/
+This extension provides protection against cross-site request
+A CSRF attack tricks the user to visit the attacker's website,
+which then submits database queries to the HTSQL service from
+the user's account. Even though the browser would not permit
+the malicious website to read the output of the queries, this
+form of attack can be used for denial of service or changing
+the data in the database. For background on CSRF, see
+This addon requires all HTSQL requests to submit a secret
+* as a cookie `htsql-csrf-token`;
+* as HTTP header `X-HTSQL-CSRF-Token`.
+If the token is not submitted, the addon prevents the request
+from reading or updating any data in the database.
+ If set, a request is permitted to read data from the database
+ even when the secret token is not provided.
+ If set, a request is permitted to update data in the database
+ even if the secret token is not provided.
.. index:: tweak.django, Django
.. _Django: https://www.djangoproject.com/
+.. index:: tweak.etl, ETL, CRUD
+This extension provides the following commands:
+ Adds records to a table.
+ Adds or updates records in a table.
+ Deletes records from a table.
+ Performs a series of command in a single transaction.
+ This extension is work-in-progress. The interface and
+ implementation of commands may change in the future.
+ Currently only PostgreSQL is supported.
+This extension makes a database from a set of CSV files.
+Each source CSV file becomes a table in the database.
+The name of the table is derived from the file name;
+the column names are taken from the first row of the CSV file.
+The remaining rows become the records in the table.
+The database is realized as an in-memory SQLite database.
+Use optional parameter `cache-file` to specify a persistent
+storage for the database.
+ List of entries describing the source files; each
+ entry has the following fields:
+ The path to the CSV file.
+ Persistent storage for the database.
+ cache-file: cache.sqlite
+.. index:: tweak.gateway
+This extensions allows you to create a gateway to another database
+and execute HTSQL queries against it.
+ A mapping of names to datebase configuration.
+ Each mapping entry creates a function which takes a query
+ as a parameter and execute it against the gateway database.
+ Database configuration could be either connection URI or
+ nested HTSQL configuration.
+ sqlite_gw: sqlite:database.sqlite
+The gateway name becomes a command which executes a query
+against the gateway database:
.. htsql:: /meta(/meta(/table))
.. index:: tweak.override
trunc_month($d): (date(year($d), month($d), 1))
-.. index:: tweak.resource
Use this addon with backends where opening a database connection
is an expensive operation.
+.. index:: tweak.resource
HTTP root for static files, excluding leading and trailing ``/``
+Usually you don't need to enable this extension explicitly as
+it is done by extensions with static resources.
+.. _CodeMirror: http://codemirror.net/
+.. index:: tweak.shell.default
Enable addon ``tweak.shell.default`` to make the shell the default
-.. _CodeMirror: http://codemirror.net/
.. index:: tweak.sqlalchemy, SQLAlchemy
.. _SQLAlchemy: http://www.sqlalchemy.org/
+This extension adds access to system catalog tables.
+Currently, only PostgreSQL backend is supported.