Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gubAU-0007eP-1O for pgsql-docs@arkaria.postgresql.org; Fri, 15 Feb 2019 10:56:30 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1gubAS-0001rX-0P for pgsql-docs@arkaria.postgresql.org; Fri, 15 Feb 2019 10:56:28 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gubAR-0001rP-OF for pgsql-docs@lists.postgresql.org; Fri, 15 Feb 2019 10:56:27 +0000 Received: from mout.kundenserver.de ([217.72.192.74]) by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gubAN-0008DW-V1 for pgsql-docs@lists.postgresql.org; Fri, 15 Feb 2019 10:56:27 +0000 Received: from [192.168.178.23] ([77.12.130.5]) by mrelayeu.kundenserver.de (mreue109 [212.227.15.183]) with ESMTPSA (Nemesis) id 1MspyA-1hEJqO3wb2-00t8sC for ; Fri, 15 Feb 2019 11:56:21 +0100 From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= Subject: Re: First SVG graphic To: pgsql-docs@lists.postgresql.org References: <0e0b8e73-cc7c-0557-c76f-35d9592eb50e@purtz.de> <20190117174053.GC10895@momjian.us> <20190118.074307.1409947743977067766.t-ishii@sraoss.co.jp> <2e5ef806-c4f8-3fe7-e9a4-4fcfd124568e@purtz.de> <20190123235312.GB8334@momjian.us> <6a97acaf-06e8-519c-a4ff-04a13e0d2675@2ndquadrant.com> <5ad6b96d-47d0-eb08-edc4-803645d2fd31@purtz.de> <4393cdcd-4efd-3198-4ffc-c080a5af79c7@2ndquadrant.com> <55a6a8cb-bfaa-e5a6-4596-82f445f1ec7c@2ndquadrant.com> Message-ID: <86af349c-5bcb-a28c-d858-c5cb0a283cd2@purtz.de> Date: Fri, 15 Feb 2019 11:58:46 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.4.0 MIME-Version: 1.0 In-Reply-To: <55a6a8cb-bfaa-e5a6-4596-82f445f1ec7c@2ndquadrant.com> Content-Type: multipart/mixed; boundary="------------CC53665E847E50A0D0123DD9" Content-Language: en-GB X-Provags-ID: V03:K1:vL4AYsgVOULQxSItWeHdjfF5OMAPlJoiI02Cpxv+QFThFwhHnvJ ER0GVr4CKG3ZUhAi8Ij4AhPzxdNMn19I0pCi+kTXsD16wls+HXamoKht4rmtxhKu0y7p/6I CBKInlPUqGAALKOS9G29U7s0oo6GdiZvIMsXaPYbEZGoUYHpzmvdcxYaj6VVlIojayARbfs uhSpPdwpGjZHe4RY+sjig== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:DPzVPrsH9Ik=:7/WO3X4bGYNYeKN4h7+TdY EPOuC1IH6qod2kDKBRpEkHMilZrAxIhFhNkZKsTqyIKRCfmh358aAwQwKmZaiW7RgxmsB1Qaz ByEE6KS5jkBC66tTxowLzI1rywgeqj6cvfMXzKTaP0mwXapDWgIRH4l5svTwgXue8rbZTzCs8 496AJrpEQMeptOp3Xt224LY3+CX8UoXjaC9bOgF4H0QmG64d5fFguRkGd0OM2T7v+NCURWVqh lreIJfnJZz4MKJZsGdzjzMGZXwYi9uAzUrd/t7iY3i/a7KHrAjPNjSdAAF4qaUEx8hKo+n+T9 66BrWBobs57R/LJz0YxCgDWlm/4KhXSgkPvmZBshzfyJHdjXVL8qj9vbhoia8aPoyLRgBvO9n t1FC3xbWGxMMd4fWlRfq4nCjbtGkLHoA6/MODNuS2MEyW9AG02x1utAswsUEyYNUevoL/dne4 D7fHUJrUkxdHojBUTBE5XVWLBif6iTKBacSg5Ggr2kv4v8W0vi3+z44Bk7XUVAinPbPPpY9LG IKGvPyYWM6hnWnoKDjkyP2yw8O/DLHO1hsBvfD1yKgPgPUosTDiUt/Xb9zzKfveqrmpXcCDfy ccgEe2esqLgMzKKsK6Mu6UnEnBDLhBOghtmJis7+57hmYq/+3IsYjt/IF8ZwtvudjEv3uE56H lRmaCuMals/lhGxJNBuwmp/jGBBDwbaL887B/mnAglMxghQ8e5Hzkg9BBDEgk3VbaStlFR6ra 1AelpYt5crFj/99LigyyYGvHH5qhDPKjwW1cJQ== List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk This is a multi-part message in MIME format. --------------CC53665E847E50A0D0123DD9 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit The graphic for dump/restore is transferred from 'pg_dump utility' chapter to the 'backup and restore' chapter in sgml/backup.sgml. In this chapter I made a lot of textual changes to explain the relation between pg_dump, pg_restore and psql in more detail. Especially I tried to introduce a more stringent use of terms, eg: avoiding 'archive' because this term is used with a different meaning in the PITR chapter. (It would be a good idea to do the same for the description of the pg_dump utility.) Because I'm not a native English speaker, feel free to correct my wording. The list of figures as well as lists of other prominent elements are removed. 'lists in TOC' seems to be a topic of its own and will be resumed later. Kind regards, Jürgen --------------CC53665E847E50A0D0123DD9 Content-Type: text/x-patch; name="firstSvg_4.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="firstSvg_4.patch" diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 8326c7c673..12997e903c 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -57,6 +57,8 @@ GENERATED_SGML = version.sgml \ ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML) +ALLSVG := $(wildcard $(srcdir)/svg/*.svg) + ## ## Man pages @@ -125,10 +127,12 @@ endif html: html-stamp -html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) +html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) $(ALLSVG) $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^) cp $(srcdir)/stylesheet.css html/ + $(MKDIR_P) html/svg + cp $(ALLSVG) html/svg touch $@ htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML) @@ -136,7 +140,7 @@ htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML) $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^) # single-page HTML -postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) +postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) $(ALLSVG) $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^) @@ -160,7 +164,7 @@ postgres.pdf: $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^) -%.pdf: %.fo +%.pdf: %.fo $(ALLSVG) $(FOP) -fo $< -pdf $@ @@ -169,7 +173,7 @@ postgres.pdf: ## epub: postgres.epub -postgres.epub: postgres.sgml $(ALLSGML) +postgres.epub: postgres.sgml $(ALLSGML) $(ALLSVG) $(XMLLINT) --noout --valid $< $(DBTOEPUB) $< diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index a73fd4d044..f192ea3b52 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -16,7 +16,7 @@ There are three fundamentally different approaches to backing up PostgreSQL data: - SQL dump + Dump into SQL INSERT syntax or a binary format File system level backup Continuous archiving @@ -25,23 +25,28 @@ - <acronym>SQL</acronym> Dump + Dump - The idea behind this dump method is to generate a file with SQL - commands that, when fed back to the server, will recreate the - database in the same state as it was at the time of the dump. + The idea behind this dump technique is to generate a file + that, when fed back to the server, will recreate the + database in the same state as it was at the time of the dump generation. + + + + Creating the Dump + PostgreSQL provides the utility program for this purpose. The basic usage of this command is: pg_dump dbname > dumpfile - As you see, pg_dump writes its result to the + As you see, pg_dump in this basic form writes its result to the standard output. We will see below how this can be useful. - While the above command creates a text file, pg_dump - can create files in other formats that allow for parallelism and more - fine-grained control of object restoration. + While the above command creates a plain-text SQL script, pg_dump + can create files also in other, dense binary formats that allow for parallelism and more + fine-grained control of object restoration, see: @@ -100,12 +105,13 @@ pg_dump dbname > ALTER TABLE.) + Restoring the Dump - Text files created by pg_dump are intended to + Such plain-text SQL scripts created by pg_dump are intended to be read in by the psql program. The general command form to restore a dump is @@ -121,8 +127,6 @@ psql dbname < pg_dump for specifying the database server to connect to and the user name to use. See the reference page for more information. - Non-text file dumps are restored using the utility. @@ -239,12 +243,12 @@ psql -f dumpfile postgres Some operating systems have maximum file size limits that cause problems when creating large pg_dump output files. Fortunately, pg_dump can write to the standard - output, so you can use standard Unix tools to work around this + output, so you can use standard tools to work around this potential problem. There are several possible methods: - Use compressed dumps. + Compress dumps. You can use your favorite compression program, for example gzip: @@ -268,7 +272,7 @@ cat filename.gz | gunzip | psql - Use <command>split</command>. + Split dumps. The split command allows you to split the output into smaller files that are @@ -287,22 +291,57 @@ cat filename* | psql - - Use <application>pg_dump</application>'s custom dump format. + + Use binary formats. + + In addition to the above mentioned plain-text SQL script format pg_dump + can create its output files in denser, binary formats: custom, + directory, and tar. + Dumps in such binary formats are restored using the utility program + instead of psql. + + + + +
+ <command>pg_dump</command>, <command>psql</command>, and <command>pg_restore</command>: + Dump Formats and Restore Proceedings + pg_dump + Dump Formats and Restore Proceedings (Figure) + + pg_restore + Dump Formats and Restore Proceedings (Figure) + + backup + Dump Formats and Restore Proceedings (Figure) + + + + + + + + + +
+ + If PostgreSQL was built on a system with the - zlib compression library installed, the custom dump + zlib compression library installed, the + custom dump format will compress data as it writes it to the output file. This will produce dump file sizes similar to using gzip, but it has the added advantage that tables can be restored selectively. The - following command dumps a database using the custom dump format: + following command dumps a database using the custom dump format: pg_dump -Fc dbname > filename - A custom-format dump is not a script for psql, but - instead must be restored with pg_restore, for example: + As mentioned above dumps in custom format are binary + and not plain-text SQL scripts, they must be restored with pg_restore + instead of psql, for example: pg_restore -d dbname filename @@ -311,11 +350,10 @@ pg_restore -d dbname and reference pages for details. - For very large databases, you might need to combine split - with one of the other two approaches. + with one of the other approaches. @@ -325,15 +363,16 @@ pg_restore -d dbname pg_dump's parallel mode. This will dump multiple tables at the same time. You can control the degree of parallelism with the -j parameter. Parallel dumps - are only supported for the "directory" archive format. + are only supported for the directory format. pg_dump -j num -F d -f out.dir dbname You can use pg_restore -j to restore a dump in parallel. - This will work for any archive of either the "custom" or the "directory" - archive mode, whether or not it has been created with pg_dump -j. + This will work for any dump output of either the custom + or the directory + format, whether or not it has been created with pg_dump -j. diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 86ff4e5c9e..ef299dd7f3 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -11228,17 +11228,18 @@ table2-mapping As an example of using the output produced by these functions, - shows an XSLT stylesheet that - converts the output of + the following shows + an XSLT stylesheet that converts the output of table_to_xml_and_xmlschema to an HTML document containing a tabular rendition of the table data. In a similar manner, the results from these functions can be converted into other XML-based formats. -
+ XSLT Stylesheet for Converting SQL/XML Output to HTML - + ]]> -
+ + diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml index cc7cd1ed2c..7e49254afe 100644 --- a/doc/src/sgml/gin.sgml +++ b/doc/src/sgml/gin.sgml @@ -453,6 +453,23 @@ key values for different columns can be of different types. +
+ GIN Overview + + index + GIN + GIN (Figure) + + + + + + + + + +
+ GIN Fast Update Technique diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml index cbdad0c3fb..d630366a9a 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -776,6 +776,19 @@ data. Empty in ordinary tables. +
+ Overall Page Layout + Page Layout (Figure) + + + + + + + + +
+ The first 24 bytes of each page consists of a page header diff --git a/doc/src/sgml/stylesheet-html-nochunk.xsl b/doc/src/sgml/stylesheet-html-nochunk.xsl index ffd2012e91..9e756708f5 100644 --- a/doc/src/sgml/stylesheet-html-nochunk.xsl +++ b/doc/src/sgml/stylesheet-html-nochunk.xsl @@ -9,4 +9,27 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/doc/src/sgml/svg/gin.svg b/doc/src/sgml/svg/gin.svg new file mode 100644 index 0000000000..9ea11f8b1f --- /dev/null +++ b/doc/src/sgml/svg/gin.svg @@ -0,0 +1,123 @@ + + + + + + + + + + + + + + Meta page + + + + Entry tree + + + + + + + + + + + + + + + + + + + + + + + + + + + + Posting tree + + + + + + + + + + + Posting tree + + + + + + Posting tree + + + + + + + + + + + Pending list + + + + + + + + + + + + Pointers to Posting tree + + Heap pointers (in Posting list or Posting tree) + + diff --git a/doc/src/sgml/svg/inkscape/gin_inkscape.svg b/doc/src/sgml/svg/inkscape/gin_inkscape.svg new file mode 100644 index 0000000000..be9a9b4c73 --- /dev/null +++ b/doc/src/sgml/svg/inkscape/gin_inkscape.svg @@ -0,0 +1,124 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + Meta page + + + Entry tree + + + + + + + + + + + + + + + + + + + + + + + + + + + Posting tree + + + + + + + + + + Posting tree + + + + + Posting tree + + + + + + + + + + Pending list + + + + + + + + + + + Pointers to Posting tree + + Heap pointers (in Posting list or Posting tree) + diff --git a/doc/src/sgml/svg/inkscape/pagelayout_inkscape.svg b/doc/src/sgml/svg/inkscape/pagelayout_inkscape.svg new file mode 100644 index 0000000000..5803077781 --- /dev/null +++ b/doc/src/sgml/svg/inkscape/pagelayout_inkscape.svg @@ -0,0 +1,81 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + Page Layout + 8 k B + Free space + + + Header + + ItemId + + ItemId + + + + + + + + Item + + + Item + + Special + + Content grows from start to center and from end to center. + diff --git a/doc/src/sgml/svg/inkscape/pgdump_inkscape.svg b/doc/src/sgml/svg/inkscape/pgdump_inkscape.svg new file mode 100644 index 0000000000..967ca9966a --- /dev/null +++ b/doc/src/sgml/svg/inkscape/pgdump_inkscape.svg @@ -0,0 +1,102 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Original + Database + + pg_dump, plain-text format + + pg_dump, other formats + + + + + SQL INSERT + commands + + psql + + + + + Binary + File(s) + + pg_restore + + + + + Restored + Database + + diff --git a/doc/src/sgml/svg/pagelayout.svg b/doc/src/sgml/svg/pagelayout.svg new file mode 100644 index 0000000000..223fcaf749 --- /dev/null +++ b/doc/src/sgml/svg/pagelayout.svg @@ -0,0 +1,74 @@ + + + + + + + + + + + + + + Page Layout + 8 k B + Free space + + + + Header + + ItemId + + ItemId + + + + + + + + Item + + Item + + Special + + + Content grows from start to center and from end to center. + + diff --git a/doc/src/sgml/svg/pgdump.svg b/doc/src/sgml/svg/pgdump.svg new file mode 100644 index 0000000000..c327136de4 --- /dev/null +++ b/doc/src/sgml/svg/pgdump.svg @@ -0,0 +1,95 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Original + Database + + pg_dump, plain-text format + + pg_dump, other formats + + + + + + SQL INSERT + commands + + psql + + + + + + Binary + File(s) + + pg_restore + + + + + + Restored + Database + + + --------------CC53665E847E50A0D0123DD9--