From 76547289b5b351799198c8ea6fae3f0e52d576e7 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sun, 14 Dec 2014 14:58:06 -0500 Subject: [PATCH] Update 9.4 release notes. Set release date, do a final pass of wordsmithing, improve some other new-in-9.4 documentation. --- doc/src/sgml/datatype.sgml | 15 ++- doc/src/sgml/plpgsql.sgml | 65 ++++++---- doc/src/sgml/release-9.4.sgml | 233 ++++++++++++++-------------------- 3 files changed, 143 insertions(+), 170 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 223ba6ade8..3a565e8d78 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -3180,9 +3180,10 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - Lines (line) are represented by the linear equation Ax + By - + C = 0, where A and B are not both zero. Values of - type line is input and output in the following form: + Lines are represented by the linear + equation Ax + By + C = 0, + where A and B are not both zero. Values + of type line are input and output in the following form: { A, B, C } @@ -3200,7 +3201,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays (x1,y1) and (x2,y2) - are two (different) points on the line. + are two different points on the line. @@ -3216,9 +3217,9 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - Line segments (lseg) are represented by pairs of points. - Values of type lseg are specified using any of the following - syntaxes: + Line segments are represented by pairs of points that are the endpoints + of the segment. Values of type lseg are specified using any + of the following syntaxes: [ ( x1 , y1 ) , ( x2 , y2 ) ] diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index e0a2668079..5db6610aa2 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1078,15 +1078,26 @@ END; always sets FOUND to true. + + For INSERT/UPDATE/DELETE with + RETURNING, PL/pgSQL reports + an error for more than one returned row, even when + STRICT is not specified. This is because there + is no option such as ORDER BY with which to determine + which affected row should be returned. + + If print_strict_params is enabled for the function, - you will get information about the parameters passed to the - query in the DETAIL part of the error message produced - when the requirements of STRICT are not met. You can change this - setting on a system-wide basis by setting + then when an error is thrown because the requirements + of STRICT are not met, the DETAIL part of + the error message will include information about the parameters + passed to the query. + You can change the print_strict_params + setting for all functions by setting plpgsql.print_strict_params, though only subsequent function compilations will be affected. You can also enable it - on a per-function basis by using a compiler option: + on a per-function basis by using a compiler option, for example: CREATE FUNCTION get_userid(username text) RETURNS int AS $$ @@ -1100,15 +1111,12 @@ BEGIN END $$ LANGUAGE plpgsql; - - - - For INSERT/UPDATE/DELETE with - RETURNING, PL/pgSQL reports - an error for more than one returned row, even when - STRICT is not specified. This is because there - is no option such as ORDER BY with which to determine - which affected row should be returned. + On failure, this function might produce an error message such as + +ERROR: query returned no rows +DETAIL: parameters: $1 = 'nosuchuser' +CONTEXT: PL/pgSQL function get_userid(text) line 6 at SQL statement + @@ -2767,28 +2775,36 @@ END; - Obtaining the Call Stack Context Information + Obtaining Current Execution Information + + + The GET CURRENT DIAGNOSTICS + command retrieves information about current execution state (whereas + the GET STACKED DIAGNOSTICS command discussed above + reports information about the execution state as of a previous error). + This command has the form: + -GET CURRENT DIAGNOSTICS variable { = | := } PG_CONTEXT , ... ; +GET CURRENT DIAGNOSTICS variable { = | := } item , ... ; - Calling GET DIAGNOSTICS with status - item PG_CONTEXT will return a text string with line(s) of - text describing the call stack. The first row refers to the + Currently only one information item is supported. Status + item PG_CONTEXT will return a text string with line(s) of + text describing the call stack. The first line refers to the current function and currently executing GET DIAGNOSTICS - command. The second and any subsequent rows refer to the calling functions - up the call stack. + command. The second and any subsequent lines refer to calling functions + further up the call stack. For example: -CREATE OR REPLACE FUNCTION public.outer_func() RETURNS integer AS $$ +CREATE OR REPLACE FUNCTION outer_func() RETURNS integer AS $$ BEGIN RETURN inner_func(); END; $$ LANGUAGE plpgsql; -CREATE OR REPLACE FUNCTION public.inner_func() RETURNS integer AS $$ +CREATE OR REPLACE FUNCTION inner_func() RETURNS integer AS $$ DECLARE stack text; BEGIN @@ -2801,8 +2817,9 @@ $$ LANGUAGE plpgsql; SELECT outer_func(); NOTICE: --- Call Stack --- -PL/pgSQL function inner_func() line 4 at GET DIAGNOSTICS +PL/pgSQL function inner_func() line 5 at GET DIAGNOSTICS PL/pgSQL function outer_func() line 3 at RETURN +CONTEXT: PL/pgSQL function outer_func() line 3 at RETURN outer_func ------------ 1 diff --git a/doc/src/sgml/release-9.4.sgml b/doc/src/sgml/release-9.4.sgml index 9bbf953043..961e461797 100644 --- a/doc/src/sgml/release-9.4.sgml +++ b/doc/src/sgml/release-9.4.sgml @@ -6,9 +6,7 @@ Release Date - 2014-??-?? - Current as of 2014-11-17 - + 2014-12-18 @@ -24,44 +22,44 @@ - Allow materialized views - to be refreshed without blocking reads + Add jsonb, a more + capable and efficient data type for storing JSON data - Add support for logical decoding - of WAL data, to allow database changes to be streamed out in a - customizable format + Add new SQL command + for changing postgresql.conf configuration file entries - Allow background worker processes - to be dynamically registered, started and terminated + Reduce lock strength for some + commands - Add jsonb, a more - capable and efficient data type for storing JSON data + Allow materialized views + to be refreshed without blocking concurrent reads - Add new SQL command - for updating postgresql.conf configuration file entries + Add support for logical decoding + of WAL data, to allow database changes to be streamed out in a + customizable format - Reduce lock strength for some - commands + Allow background worker processes + to be dynamically registered, started and terminated @@ -90,39 +88,6 @@ - - - - Change on-disk format of jsonb data - (Heikki Linnakangas and Tom Lane) - - - - The on-disk representation was changed after 9.4beta2 to improve - efficiency. pg_upgrade will refuse to upgrade any - 9.4beta1 or 9.4beta2 database containing jsonb columns; you - will need to use pg_dumpall instead to migrate such - databases. - - - - - - - Fix representation of numeric values in jsonb GIN indexes - (Tom Lane) - - - - Numeric items within jsonb values are converted to strings - for storage in GIN jsonb_ops indexes. In 9.4beta3, - trailing zeroes in such items were mishandled. Beta testers - should REINDEX any such indexes after upgrading, to ensure - that searches for numeric values will find the expected rows. Note - that jsonb_path_ops indexes were not affected by this bug. - - - Tighten checks for multidimensional Previously, an input array string that started with a single-element - array dimension could later contain multidimensional segments, - e.g. '{{1}, {2,3}}'::int[]. + sub-array could later contain multi-element sub-arrays, + e.g. '{{1}, {2,3}}'::int[] would be accepted. @@ -173,7 +138,7 @@ The json - #> text[] path extraction operator now + #> text[] path extraction operator now returns its lefthand input, not NULL, if the array is empty (Tom Lane) @@ -335,8 +300,14 @@ - Use the last specified if multiple - values are specified (Heikki Linnakangas) + Use the last specified recovery + target parameter if multiple target parameters are specified + (Heikki Linnakangas) + + + + Previously, there was an undocumented precedence order among + the recovery_target_xxx parameters. @@ -443,29 +414,6 @@ - - - - Update time zone data files to tzdata release 2014j for DST law - changes in Russia and elsewhere - - - - This change is more significant than most time zone updates because - many Russian zone abbreviations are changing meaning, including IRKT, - KRAT, MAGT, MSK, NOVT, OMST, SAKT, VLAT, YAKT, and YEKT. - PostgreSQL will now associate the correct UTC offset - with these abbreviations depending on the given date. Also, IANA - has formally recognized abbreviations of the form - AxST/AxDT for Australian timezones, - so adopt those names as part of the Default abbreviation - set in PostgreSQL. The Australia - abbreviation set now need be selected only if it's desired to use - historical abbreviations that conflict with abbreviations commonly - used elsewhere, such as EST or SAST. - - - @@ -491,7 +439,7 @@ - The contrib/worker_spi module shows an example of use + The new worker_spi module shows an example of use of this feature. @@ -503,7 +451,8 @@ - This feature is illustrated in . + This feature is illustrated in the test_shm_mq + module. @@ -555,7 +504,7 @@ Indexes upgraded via will work fine but will still be in the old, larger GIN format. - Use to recreate such an index in the + Use to recreate old GIN indexes in the new format. @@ -656,8 +605,7 @@ - Improve speed of - with DEFAULT with default nextval() columns (Simon Riggs) @@ -687,7 +635,7 @@ - Make the planner more aggressive in extracting restriction clauses + Make the planner more aggressive about extracting restriction clauses from mixed AND/OR clauses (Tom Lane) @@ -830,7 +778,7 @@ Add new SQL command - for updating postgresql.conf configuration file entries + for changing postgresql.conf configuration file entries (Amit Kapila) @@ -948,7 +896,7 @@ The previous level was LOG, which was too verbose - for per-session libraries. + for libraries loaded per-session. @@ -993,8 +941,7 @@ - Add recovery.conf - parameter + Add recovery parameter to delay replication (Robert Haas, Fabrízio de Royes Mello, Simon Riggs) @@ -1145,8 +1092,8 @@ Add WITH - ORDINALITY syntax to number rows returned from - set-returning functions in the FROM clause + ORDINALITY syntax to number the rows returned from a + set-returning function in the FROM clause (Andrew Gierth, David Fetter) @@ -1272,9 +1219,9 @@ - Allow materialized views - to be refreshed without blocking reads - (Kevin Grittner) + Allow a materialized view + to be refreshed without blocking other sessions from reading the view + meanwhile (Kevin Grittner) @@ -1435,8 +1382,9 @@ The line segment data type (lseg) has always been - fully supported. The previous line data type (enabled - only via a compile-time option) is not binary or dump-compatible. + fully supported. The previous line data type (which was + enabled only via a compile-time option) is not binary or + dump-compatible with the new implementation. @@ -1459,8 +1407,8 @@ - Support time zone abbreviations that change from time to time - (Tom Lane) + Support time zone abbreviations that change UTC offset from time to + time (Tom Lane) @@ -1472,6 +1420,8 @@ Update the zone abbreviation definition files to make use of this feature in timezone locales that have changed the UTC offset of their abbreviations since 1970 (according to the IANA timezone database). + In such timezones, PostgreSQL will now associate the + correct UTC offset with the abbreviation depending on the given date. @@ -1507,8 +1457,8 @@ - This new type allows faster access to values in a JSON - document and faster and more useful indexing of JSON columns. + This new type allows faster access to values within a JSON + document, and faster and more useful indexing of JSON columns. Scalar values in jsonb documents are stored as appropriate scalar SQL types, and the JSON document structure is pre-parsed rather than being stored as text as in the original json @@ -1716,7 +1666,7 @@ Add control over which rows are passed - into aggregate functions using the FILTER clause (David Fetter) @@ -1732,7 +1682,7 @@ - Add aggregates percentile_cont(), percentile_disc(), mode(), rank(), @@ -1756,8 +1706,8 @@ types (Tom Lane) - This allows proper declaration of aggregates like the built-in - aggregate array_agg() in SQL. + This allows proper declaration in SQL of aggregates like the built-in + aggregate array_agg(). @@ -1801,9 +1751,9 @@ - Add ability to store the PL/PgSQL - call stack into a variable using PG_CONTEXT + Add ability to retrieve the current PL/PgSQL call stack + using GET + DIAGNOSTICS (Pavel Stehule, Stephen Frost) @@ -1811,10 +1761,9 @@ Add option @@ -1827,7 +1776,7 @@ - Currently only shadowed variable errors/warnings are available. + Currently only warnings/errors about shadowed variables are available. @@ -1962,8 +1911,8 @@ - Allow Control-C to abort psql when hung at connection - startup (Peter Eisentraut) + Allow Control-C to abort psql when it's hung at + connection startup (Peter Eisentraut) @@ -1976,23 +1925,23 @@ - Make psql \db+ show tablespace options + Make psql's \db+ show tablespace options (Magnus Hagander) - Make psql \do+ display the functions - which implement the operators (Marko Tiikkaja) + Make \do+ display the functions + that implement the operators (Marko Tiikkaja) - Make psql \d+ output an + Make \d+ output an OID line only if an oid column - exists in a table (Bruce Momjian) + exists in the table (Bruce Momjian) @@ -2015,23 +1964,22 @@ - Fix psql \copy to no longer require + Fix \copy to no longer require a space between stdin and a semicolon (Etsuro Fujita) - Output the row count at the end - of psql \copy just - like (Kumar Rajeev Rastogi) + Output the row count at the end of \copy, just + like COPY already did (Kumar Rajeev Rastogi) - Fix psql \conninfo to display the - server's IP address for clients that connect using + Fix \conninfo to display the + server's IP address for connections using hostaddr (Fujii Masao) @@ -2043,29 +1991,29 @@ - Mention the SSL protocol version in - psql's \conninfo (Marko Kreen) + Show the SSL protocol version in + \conninfo (Marko Kreen) - Add psql tab completion for \pset + Add tab completion for \pset (Pavel Stehule) - Allow psql's \pset with no arguments + Allow \pset with no arguments to show all settings (Gilles Darold) - In psql, display the history file name written by - \s without converting it to an absolute path (Tom Lane) + Make \s display the name of the history file it wrote + without converting it to an absolute path (Tom Lane) @@ -2291,7 +2239,7 @@ Currently, these tests are run by make check-world only if the @@ -2316,7 +2264,7 @@ Improve support for VPATH builds of PGXS - modules (Cédric Villemain, Andrew Dunstan) + modules (Cédric Villemain, Andrew Dunstan, Peter Eisentraut) @@ -2345,14 +2293,15 @@ - Various minor security and sanity fixes reported by the + Fix various minor security and sanity issues reported by the Coverity scanner (Stephen Frost) - Improve Valgrind detection of invalid memory usage + Improve detection of invalid memory usage when testing + PostgreSQL with Valgrind (Noah Misch) @@ -2373,10 +2322,12 @@ Allow pgindent to accept a command-line list of typedefs (Bruce Momjian) + + - pgindent is also now smarter about blank lines - around preprocessor conditionals. + Make pgindent smarter about blank lines + around preprocessor conditionals (Bruce Momjian) @@ -2479,8 +2430,12 @@ Improve 's choice of trigrams for indexed - regular expression searches by discouraging the selection of - trigrams containing whitespace (Alexander Korotkov) + regular expression searches (Alexander Korotkov) + + + + This change discourages use of trigrams containing whitespace, which + are usually less selective. @@ -2518,8 +2473,8 @@ - Pass user name ( -- 2.40.0