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


   This file is part of PGWUI_Copy.
  
   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_Copy
============

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

PGWUI_Copy stands for `PostgreSQL`_ Web User Interface, Copy a Schema
Between Databases.

A generic WSGI web form for copying schemas between `PostgreSQL`_
databases.  The form presented requests database names, login
credentials, and the name of the schema to be copied.


Usage and Cautions
------------------

PGWUI_Copy is included when PGWUI is installed.

Superuser privileges are required in the target database.

There is an option to have the schema copy operation delete an already
existing schema, in the target database, having the same name as the
copied schema.  Care must be taken when this is done.  When the schema
in the target database is dropped all dependent objects, such as the
tables in the dropped schema, are dropped as well.  But dependent
objects need not be located in the target schema.  Anything outside of
the schema which is dependent upon anything in the schema is dropped
as well.  All of the objects deleted may not be within the target
schema.

At present, the schema copy operation may not be suitable for use when
copying into a production database.  The core assumption is that the
target database is read-mostly and will benefit from ``VACUUM FULL``
defragementation.  PGWUI_Copy's schema copy operation is intended to
maximize the performance of the target database and copied schema on a
system with locally attached spinning disks.  The intention is to put
the copied data onto contiguous disk sectors, under the assumption
that sectors newly allocated by the OS are likely to be contiguous.
The following steps are taken to accomplish this:

* The existing schema, if it exists in the target database, is dropped.

* If an existing schema is dropped, a ``VACUUM FULL`` operation is done
  on the target database.

* The schema is copied from the source database to the target database,.

* A ``VACUUM ANALYZE`` is done on the target database.

This series of steps has the following implications:

* The ``VACUUM FULL`` of the target database returns the space occupied
  by deleted rows to the operating system.

  * The ``VACUUM FULL`` operation not only utilizes system resources but
    also requires an exclusive lock on each table as it is examined.
    This can negatively impact performance.

  * ``INSERT`` and ``UPDATE`` operations in the target database must
    obtain space from the operating system.  This results in reduced
    performance in comparison with re-using space occupied by deleted
    or updated rows, which can negatively impact performance in high
    volume production environments.

  * The deletion of the old schema from the target database and
    the creation of the new do not happen within a single transaction.
    Should the restoration of the schema into the target database fail
    the result will be a database without the target schema.

* The ``VACUUM ANALYZE`` on the target database analyzes the entire
  database, not just the copied schema.

* The database credentials supplied to PGWUI_Copy must be sufficient
  to perform all operations.

It is recommended but not required to install PGWUI_Logout when
installing PGWUI_Copy.


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

The default URL for PGWUI_Copy looks like
*https://www.example.com/copy*.

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_copy.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_Copy 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>`_.


.. _PostgreSQL: https://www.postgresql.org/