.. Copyright (C) 2018, 2021 The Meme Factory, Inc.  http://www.karlpinc.com/


   This file is part of PGWUI_Bulk_Upload.
  
   This program is free software: you can redistribute it and/or
   modify it under the terms of the GNU Affero General Public License
   as published by the Free Software Foundation, either version 3 of
   the License, or (at your option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Affero General Public License for more details.

   You should have received a copy of the GNU Affero General Public
   License along with this program.  If not, see
   <http://www.gnu.org/licenses/>.

   Karl O. Pinc <kop@karlpinc.com>

.. #End Of Copyright Marker#

PGWUI_Bulk_Upload
=================

Short Documentation
-------------------

PGWUI_Bulk_Upload stands for `PostgreSQL`_ Web User Interface Bulk Upload.


Usage
-----

Uploads from an archive file, presently only a zip file, into
(potentially) multiple PostgreSQL tables.  The structure of the
zip file is as follows:

The zip file must contain one or more directories.  Each directory may
contain only files.  Each directory must contain a file, the map file,
which maps the directory's files to PostgreSQL tables (or views), one
file per table (or view).

The map file is in YAML syntax, which for purposes of this document
can be thought of as a superset of JSON.  It must contain a top-level
tag, `map_list`, which itself contains a list of maps, each of which
maps a file to a table or view.  The table (or view) names may,
optionally, be schema qualified.  An example map file might be::

  # This file is contents.yml
  map_list:
    # Load the foo.csv file into the foo_table table of the default schema.
    - file_map:
        file: foo.csv
        relation: foo_table
    # Load the bar.csv file into the bar_view uploadable-view of the default
    # schema.
    - file_map:
        file: bar.csv
        relation: bar_view
    # Load the baz.csv file into the baz_table table of the meta schema.
    - file_map:
        file: baz.csv
        relation: meta.baz_table

The files within each directory are uploaded in the order in which
they are listed in the map file.  The directories in the zip file are
processed in alphabetical order.

Top level tags, other than the `map_list` tag, are ignored.

It is recommended to enclose file names which contain spaces, or begin
with a digit, in single quotes.

The `yamllint` syntax and style checker can be helpful when
constructing YAML files.  See: https://github.com/adrienverge/yamllint

The default name of the map file is `contents.yml`, but this may be
changed with the `pgwui_bulk_upload:map_file` setting.


URL Configuration
-----------------

The default URL for PGWUI_Bulk_Upload looks like
*https://www.example.com/upload*.

See the PGWUI_Server documentation for how to configure a different
URL.


Development Status
------------------


Complete Documentation
----------------------

The complete documentation set can be found on the PGWUI_Upload home
page at http://pgwui_bulk_upload.readthedocs.io/.


License
-------

Except for files otherwise marked, distributed WITHOUT ANY WARRANTY
under the terms of the GNU Affero General Public License, version 3 or
a later version at your option.  See the copyright notices at the top
of each file and the LICENSE.txt file for details.

Acknowledgments
---------------

The PGWUI_Bulk_Upload code is based on the GMI_Pyramid sub-system created for
the `Gombe Mother Infant Database Project
<https://gombemi.ccas.gwu.edu>`_.  Support for extracting PGWUI_Core_
from GMI_Pyramid, its Python packaging, and further enhancement was
provided by `The Dian Fossey Gorilla Fund
<https://www.gorillafund.org>`_.


.. _PGWUI_Core: http://pgwui_core.readthedocs.io/
.. _PostgreSQL: https://www.postgresql.org/