Commits

Clark C. Evans committed 6532c1a

updating config documentation to enumerate a
few new plugins

Comments (0)

Files changed (3)

 2.2.0 beta 1 (2011-09-20)
 -------------------------
 
-* fixed silent data truncation bug on invalid values; users of SQLite
+* Fixed silent data truncation bug on invalid values; users of SQLite
   are adviced to upgrade.
-* added support for loading application configuration from a file;
+* Added support for loading application configuration from a file;
   option `-C FILE`.
-* refactored plugin architecture; added support for plugin parameters.
-* added SQLAlchemy adapter.
-* added support for statement-like functions; converted formatters
+* Refactored plugin architecture; added support for plugin parameters.
+* Added SQLAlchemy adapter.
+* Added support for statement-like functions; converted formatters
   to statements.
-* added plugin `tweak.meta`: database metadata exposed as a database.
-* added plugin `tweak.shell`: a simple web-based HTSQL editor.
-* removed plugin `tweak.schema`: functionality is implemented in
+* Added plugin `tweak.meta`: database metadata exposed as a database.
+* Added plugin `tweak.shell`: a simple web-based HTSQL editor.
+* Removed plugin `tweak.schema`: functionality is implemented in
   the core.
 
 

doc/guide/config.rst

 The following instructions assume you've installed HTSQL and wish to
 configure extensions or "tweaks".
 
-.. _addon: http://htsql.org/doc/api/htsql.html#htsql-addon
-.. _adapter: http://htsql.org/doc/api/htsql.html#htsql-adapter
-.. _tweaks: https://bitbucket.org/prometheus/htsql/src/tip/src/htsql_tweak/
-
 Plugin Mechanism
 ================
 
-HTSQL has an extensive addon_ system that can be used to override almost
-every aspect of server operation or query construction with an adapter_.  
+HTSQL has an extensive addon system that can be used to override almost
+every aspect of server operation or query construction with an adapter.  
 Extensions can live in third party modules or be included in the HTSQL
-distribution as part of our supported "tweaks_".  To list supported
+distribution as part of our supported "tweaks".  To list supported
 extensions, you could type::
 
   $ htsql-ctl extension
 
   $ htsql-ctl extension tweak.autolimit
 
-Third parties can also register extensions with their own Python EGGs
-by adding a ``htsql.addons`` section to ``ENTRY_POINTS`` entry in 
-their ``setup.py``.  Each extension would then implement HTSQL's 
-addon_ protocol. 
+Third parties can also register extensions with their own Python EGGs by
+adding a ``htsql.addons`` section to ``ENTRY_POINTS`` entry in their
+``setup.py``.  Each extension would implement HTSQL's addon protocol.
 
 
 Using Extensions
 
   $ htsql-ctl shell -E tweak.autolimit:limit=10 pgsql:htsql_regress
 
-If more than one parameter is possible, use "," to seperate them::
+If more than one parameter is possible, use "," to separate them::
 
   $ htsql-ctl shell -E tweak.hello:repeat=3,address=home pgsql:htsql_regress 
 
 Config Files
 ------------
 
-Plugins and configuration parameters can also be provided by 
-a flat YAML (or JSON) file.  
+Plugins and configuration parameters can also be provided by a flat YAML
+(or JSON) file, and then included using ``-C`` on the command line.
+Here is an example configuration file against PostgreSQL database
+with most plugins enabled.
+
+.. sourcecode:: yaml
+
+      # demo-config.yaml
+      htsql:
+        db:
+          engine: pgsql
+          database: htsql_regress
+          username: htsql_regress
+          password: secret
+          host: localhost
+          port: 5432
+      tweak.autolimit:
+        limit: 1000
+      tweak.timeout:
+        timeout: 600
+      tweak.cors:
+      tweak.meta:
+      tweak.shell:
+        server-root: http://localhost:8080
+      tweak.shell.default:
+
+You can then start the built-in demonstration web server::
+
+  $ htsql-ctl serve -C demo-config.yaml
+
+For ``htsql-ctl serve`` the webserver host and port are *not* provided
+via plugin mechanism and must be provided if something other than
+``localhost:8080`` is desired.  If both ``-E`` and ``-C`` are used,
+explicit command line options override values provided in the
+configuration file.  This permits a configuration file to be used as a
+default perhaps using a different database URI.
+
+HTSQL "tweaks"
+==============
+
+The HTSQL distribution ships with several built-in extensions
+we call ``htsql_tweaks``.   We list a few of them here.
+
+``tweak.meta``
+--------------
+
+This extension module creates an in-memory SQLite database that can be
+queried (using HTSQL) to return information about the system catalog.
+The schema has several tables:
+
+``table``
+   all tables accessable via the attached credentials
+
+``field``
+   columns and links of a given table
+
+``column``
+   all columns accessable for the given table
+
+``link``
+   all links from one table to another
+
+So, to enumerate links for a table, say ``course`` you could type:
+
+.. htsql:: /meta(/link?table_name='course')
+
+
+``tweak.autolimit``
+-------------------
+
+To help deployments ensure against accidental denial of
+service, this plugin automatically truncates output from
+a query to a given number of rows (10k default).  The 
+``limit`` parameter can be customized to change the 
+truncation limit.
+
+``tweak.timeout``
+-----------------
+
+To help deployments ensure against accidental denial of
+service, this plugin automatically limits all queries to
+a given number of ``timeout`` seconds (the default is 60s).  
+This plugin is currently only supported by PostgreSQL.
+
+
+``tweak.shell``
+---------------
+
+This extension module adds a command ``/shell()`` which takes any query
+and populates visual editor with syntax highlighting (using the
+excellent CodeMirror_ library).  As you modify the query, the URL
+changes so it can be bookmarked.
+
+The ``tweak.shell.default`` plugin will make ``/shell()`` the 
+default command, replacing the regular HTML output.
+
+.. _CodeMirror: http://codemirror.net/
 
 .. vim: set spell spelllang=en textwidth=72:
 Basic Expressions
 -----------------
 
-Every HTSQL request starts with a forward-slash ``/``.  To return all
-rows from a table, simply write the table name:
+HTSQL requests start with a forward-slash ``/``.  To return all rows and
+columns from the school table, sorted by primary key, write:
 
-.. sourcecode:: htsql
+.. htsql:: /school
+   :cut: 3
 
-   /school
-
-`The query result`__ is a list of schools in the university, including all
-columns, sorted by the primary key for the table:
-
-__ http://demo.htsql.org/school
-
- ====  ============================= ======
- code  name                          campus
- ====  ============================= ======
- art   School of Art and Design      old
- bus   School of Business            south
- edu   College of Education          old
- egn   School of Engineering         north
- la    School of Arts and Humanities old
- mus   School of Music & Dance       south
- ns    School of Natural Sciences    old
- ph    Public Honorariums
- sc    School of Continuing Studies
- ====  ============================= ======
+.. hint::
+   In this tutorial query results are shown truncated.  Click 
+   on any example request to open it at demo.htsql.org and see 
+   the complete output.
 
 Scalar expressions, including arithmetic and boolean operations, can be
 written directly: