[postgis-tickets] [SCM] PostGIS branch master updated. 3.2.0-858-g940834bd0

[git at osgeo.org]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".

The branch, master has been updated
       via  940834bd094e75a504b537234c453a0d1f115d5c (commit)
      from  1324a010dabc2ef30a7cb5d472568bb5baeb9152 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 940834bd094e75a504b537234c453a0d1f115d5c
Author: Sandro Santilli <strk at kbt.io>
Date:   Mon May 16 18:00:14 2022 +0200

    Document pgtopo_export and pgtopo_import
    
    References #5116

diff --git a/doc/extras_topology.xml b/doc/extras_topology.xml
index 3520b1758..de100245a 100644
--- a/doc/extras_topology.xml
+++ b/doc/extras_topology.xml
@@ -4172,4 +4172,131 @@ two topogeometries intersect.
         </refsection>
       </refentry>
 </sect1>
+
+<sect1 id="Topology_Import_Export">
+    <title>Importing and exporting Topologies</title>
+
+    <para>
+Once you have created topologies, and maybe associated topological layers,
+you might want to export them into a file-based format for backup or transfer
+into another database.
+    </para>
+
+    <para>
+Using the standard dump/restore tools of PostgreSQL is
+problematic because topologies are composed by a set of tables (4 for
+primitives, an arbitrary number for layers) and records in metadata tables
+(topology.topology and topology.layer). Additionally, topology identifiers
+are not univoque across databases so that parameter of your topology
+will need to be changes upon restoring it.
+    </para>
+
+    <para>
+In order to simplify export/restore of topologies a pair of
+executables are provided: <filename>pgtopo_export</filename>
+and <filename>pgtopo_import</filename>. Example usage:
+    </para>
+<programlisting>
+pgtopo_export dev_db topo1 | pgtopo_import topo1 | psql staging_db
+</programlisting>
+
+    <sect2 id="pgtopo_export">
+        <title>Using the Topology exporter</title>
+
+        <para>
+The <filename>pgtopo_export</filename> script takes the name of a
+database and a topology and outputs a dump file which can be used
+to import the topology (and associated layers) into a new database.
+        </para>
+
+        <para>
+By default <filename>pgtopo_export</filename> writes the
+dump file to the standard output so that it can be piped to
+<filename>pgtopo_import</filename> or redirected to a file
+(refusing to write to terminal). You can optionally specify
+an output filename with the <code>-f</code> commandline switch.
+        </para>
+
+        <para>
+By default <filename>pgtopo_export</filename> includes a dump
+of all layers defined against the given topology. This may be more
+data than you need, or may be non-working (in case your layer tables
+have complex dependencies) in which case you can request skipping the
+layers with the <code>--skip-layers</code> switch and deal with those
+separately.
+        </para>
+
+        <para>
+Invoking <filename>pgtopo_export</filename> with the
+<code>--help</code> (or <code>-h</code> for short) switch
+will always print short usage string.
+        </para>
+
+
+        <para>
+The dump file format is a compressed tar archive of a
+<filename>pgtopo_export</filename> directory containing
+at least a <filename>pgtopo_dump_version</filename> file with
+format version info. As of version <code>1</code> the directory
+contains tab-delimited CSV files with data of the topology
+primitive tables (node, edge_data, face, relation), of the
+topology and layer records associated with it, and optionall
+(if <code>--skip-layers</code> is not given) a custom-format
+PostgreSQL dump of tables reported as being layers of the given
+topology.
+        </para>
+
+    </sect2> <!-- pgtopo_export -->
+
+    <sect2 id="pgtopo_import">
+        <title>Using the Topology importer</title>
+
+        <para>
+The <filename>pgtopo_import</filename> script takes a
+<code>pgtopo_export</code> format topology dump and a
+name to give to  the topology to be created and outputs
+an SQL script reconstructing the topology and associated
+layers.
+        </para>
+
+        <para>
+The generated SQL file will contain statements that create
+a topology with the given name, load primitive data in it,
+restores and registers all topology layers by properly
+linking all TopoGeometry values to their correct topology.
+        </para>
+
+
+        <para>
+By default <filename>pgtopo_import</filename> reads the dump
+from the standard input so that it can be used in conjuction
+with <filename>pgtopo_export</filename> in a pipeline.
+You can optionally specify an input filename with the
+<code>-f</code> commandline switch.
+        </para>
+
+        <para>
+By default <filename>pgtopo_import</filename> includes in the output
+SQL file the code to restore all layers found in the dump.
+        </para>
+
+        <para>
+This may be unwanted or non-working in case your target database already
+have tables with the same name as the ones in the dump. In that case
+you can request skipping the layers with the <code>--skip-layers</code>
+switch and deal with those separately (or later).
+        </para>
+
+        <para>
+SQL to only load and link layers to a named topology can be generated
+using the <code>--only-layers</code> switch. This can be useful to load
+layers AFTER resolving the naming conflicts or to link layers to a
+different topology (say a spatially-simplified version of the starting
+topology).
+        </para>
+
+    </sect2> <!-- pgtopo_import -->
+
+</sect1> <!-- Importing and exporting Topologies -->
+
 </chapter>

-----------------------------------------------------------------------

Summary of changes:
 doc/extras_topology.xml | 127 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)


hooks/post-receive
-- 
PostGIS