Document postgresql environment variables

dbprocessing/DButils.py

@@ -139,7 +139,10 @@ def __init__(self, mission='Test', db_var=None, echo=False, engine=None):
         Parameters
         ----------
         mission : :class:`str`
-            Name of the mission
+            Name of the mission. This may be the name of a .sqlite file
+            or the name of a Postgresql database; see
+            :ref:`scripts_specifying_database` for Postgresql support
+            (implemented by :func:`postgresql_url`).
         echo : :class:`bool`, default False
             if True, the Engine will log all statements as well as a
             repr() of their parameter lists to the logger

docs/developer/tests.rst

@@ -22,6 +22,17 @@ Of course, instead of ``test_all.py``, you can specify the name of the module yo
 Unit tests use the version of dbprocessing modules in the ``build`` directory,
 i.e. run ``python setup.py build`` before running the unit tests.
 
+Some unit tests access databases of sample information. These are built
+on the fly. Sqlite databases are used unless :envvar:`PGDATABASE` is defined.
+In that case, it is the name of a Postgresql database to use instead.
+
+.. envvar:: PGDATABASE
+
+   Name of a Postgresql database to use for unit testing. Must exist but
+   be empty (i.e., no tables). See :ref:`scripts_specifying_database` for
+   other environment variables controlling this connection. All tables
+   will be removed from this database at the end of unit testing!
+
 .. _functional:
 
 Functional Tests

docs/scripts.rst

@@ -6,6 +6,45 @@ Scripts
    :depth: 1
    :local:
 
+.. _scripts_specifying_database:
+
+Specifying a database
+=====================
+Most scripts require a mission database to be specified. If this is an
+existing file, this is usually interpreted as an sqlite database. Otherwise
+it is assumed to be the name of a Postgresql database, and the following
+environment variables are used. Unless otherwise specified, these are
+optional and the Postgresql default is used if not specified (i.e.,
+there is no special dbprocessing-based handling.)
+
+.. note::
+
+   This can result in unusual behavior when a filename that doesn't exist
+   is specified as a mission database, as the "fall through" assumes
+   Postgresql and might raise unexpected errors if these environment
+   variables are not defined.
+
+.. envvar:: PGUSER
+
+   Username to use to connect to the database. This is required when using
+   Postgresql databases.
+
+.. envvar:: PGHOST
+
+   Hostname of the database. If not specified, will use ``''``, which is
+   usually treated as a domain socket connection on ``localhost``.
+
+.. envvar:: PGPORT
+
+   Port to connect to.
+
+.. envvar:: PGPASSWORD
+
+   User's database password. If not specified, no password provided.
+
+Postgresql support is not as heavily tested and argument handling is not
+yet normalized across all scripts.
+
 Maintained scripts
 ==================
 These scripts are of general use in dbprocessing and either are fully