summaryrefslogtreecommitdiff
path: root/doc
AgeCommit message (Collapse)Author
2024-08-15Fix doc typo: unicode_assigned() return type.Jeff Davis
Reported-by: Hironobu SUZUKI Discussion: https://postgr.es/m/5dd88820-bb00-4b90-904b-738ea2e4ee2e@interdb.jp Backpatch-through: 17
2024-08-14Remove TRACE_SORT macroPeter Eisentraut
The TRACE_SORT macro guarded the availability of the trace_sort GUC setting. But it has been enabled by default ever since it was introduced in PostgreSQL 8.1, and there have been no reports that someone wanted to disable it. So just remove the macro to simplify things. (For the avoidance of doubt: The trace_sort GUC is still there. This only removes the rarely-used macro guarding it.) Reviewed-by: Heikki Linnakangas <hlinnaka@iki.fi> Discussion: https://www.postgresql.org/message-id/flat/be5f7162-7c1d-44e3-9a78-74dcaa6529f2%40eisentraut.org
2024-08-12Add user-callable CRC functions.Nathan Bossart
We've had code for CRC-32 and CRC-32C for some time (for WAL records, etc.), but there was no way for users to call it, despite apparent popular demand. The new crc32() and crc32c() functions accept bytea input and return bigint (to avoid returning negative values). Bumps catversion. Author: Aleksander Alekseev Reviewed-by: Peter Eisentraut, Tom Lane Discussion: https://postgr.es/m/CAJ7c6TNMTGnqnG%3DyXXUQh9E88JDckmR45H2Q%2B%3DucaCLMOW1QQw%40mail.gmail.com
2024-08-12Remove "parent" column from pg_backend_memory_contextsDavid Rowley
32d3ed816 added the "path" column to pg_backend_memory_contexts to allow a stable method of obtaining the parent MemoryContext of a given row in the view. Using the "path" column is now the preferred method of obtaining the parent row. Previously, any queries which were self-joining to this view using the "name" and "parent" columns could get incorrect results due to the fact that names are not unique. Here we aim to explicitly break such queries so that they can be corrected and use the "path" column instead. It is possible that there are more innocent users of the parent column that just need an indication of the parent and having to write out a self-joining CTE may be an unnecessary hassle for those cases. Let's remove the column for now and see if anyone comes back with any complaints. This does seem like a good time to attempt to get rid of the column as we still have around 1 year to revert this if someone comes back with a valid complaint. Plus this view is new to v14 and is quite niche, so perhaps not many people will be affected. Author: Melih Mutlu <m.melihmutlu@gmail.com> Discussion: https://postgr.es/m/CAGPVpCT7NOe4fZXRL8XaoxHpSXYTu6GTpULT_3E-HT9hzjoFRA@mail.gmail.com
2024-08-10Adjust pg_wal_replay_wait() procedure behavior on promoted standbyAlexander Korotkov
pg_wal_replay_wait() is intended to be called on standby. However, standby can be promoted to primary at any moment, even concurrently with the pg_wal_replay_wait() call. If recovery is not currently in progress that doesn't mean the wait was unsuccessful. Thus, we always need to recheck if the target LSN is replayed. Reported-by: Kevin Hale Boyes Discussion: https://postgr.es/m/CAPpHfdu5QN%2BZGACS%2B7foxmr8_nekgA2PA%2B-G3BuOUrdBLBFb6Q%40mail.gmail.com Author: Alexander Korotkov
2024-08-09doc: Standardize use of dashes in references to CRC and SHA.Nathan Bossart
Presently, we inconsistently use dashes in references to these algorithms (e.g., CRC32C versus CRC-32C). Some popular web sources appear to prefer dashes, and with this commit, we will, too. Reviewed-by: Robert Haas Discussion: https://postgr.es/m/ZrUFpLP-w2zTAHqq%40nathan
2024-08-09doc: Fix name of CRC algorithm in "Reliability" section.Nathan Bossart
This section claims we use CRC-32 for WAL records and two-phase state files, but we've actually used CRC-32C since v9.5 (commit 5028f22f6e). Fix that. Reviewed-by: Robert Haas Discussion: https://postgr.es/m/ZrUFpLP-w2zTAHqq%40nathan Backpatch-through: 12
2024-08-09Remove obsolete RECHECK keyword completelyPeter Eisentraut
This used to be part of CREATE OPERATOR CLASS and ALTER OPERATOR FAMILY, but it has done nothing (except issue a NOTICE) since PostgreSQL 8.4. Commit 30e7c175b81 removed support for dumping from pre-9.2 servers, so this no longer serves any need. This now removes it completely, and you'd get a normal parse error if you used it. Reviewed-by: Aleksander Alekseev <aleksander@timescale.com> Discussion: https://www.postgresql.org/message-id/flat/113ef2d2-3657-4353-be97-f28fceddbca1%40eisentraut.org
2024-08-07Fix names of "Visual Studio" and Meson in a documentation sentence.Noah Misch
Commit 3cffe7946c268be91a340ec9a27081cb93d67d35 missed this. Back-patch to v17, which introduced this. Discussion: https://postgr.es/m/CAJ7c6TM7ct0EjoCQaLSVYoxxnEw4xCUFebWj77GktWsqEdyCtQ@mail.gmail.com
2024-08-05Restrict accesses to non-system views and foreign tables during pg_dump.Masahiko Sawada
When pg_dump retrieves the list of database objects and performs the data dump, there was possibility that objects are replaced with others of the same name, such as views, and access them. This vulnerability could result in code execution with superuser privileges during the pg_dump process. This issue can arise when dumping data of sequences, foreign tables (only 13 or later), or tables registered with a WHERE clause in the extension configuration table. To address this, pg_dump now utilizes the newly introduced restrict_nonsystem_relation_kind GUC parameter to restrict the accesses to non-system views and foreign tables during the dump process. This new GUC parameter is added to back branches too, but these changes do not require cluster recreation. Back-patch to all supported branches. Reviewed-by: Noah Misch Security: CVE-2024-7348 Backpatch-through: 12
2024-08-05injection_points: Add some cumulative stats for injection pointsMichael Paquier
This acts as a template of what can be achieved with the pluggable cumulative stats APIs introduced in 7949d9594582 for the variable-numbered case where stats entries are stored in the pgstats dshash, while being potentially useful on its own for injection points, say to add starting and/or stopping conditions based on the statistics (want to trigger a callback after N calls, for example?). Currently, the only data gathered is the number of times an injection point is run. More fields can always be added as required. All the routines related to the stats are located in their own file, called injection_stats.c in the test module injection_points, for clarity. The stats can be used only if the test module is loaded through shared_preload_libraries. The key of the dshash uses InvalidOid for the database, and an int4 hash of the injection point name as object ID. A TAP test is added to provide coverage for the new custom cumulative stats APIs, showing the persistency of the data across restarts, for example. Author: Michael Paquier Reviewed-by: Dmitry Dolgov, Bertrand Drouvot Discussion: https://postgr.es/m/Zmqm9j5EO0I4W8dx@paquier.xyz
2024-08-04pg_wal_replay_wait(): Fix typo in the docAlexander Korotkov
Reported-by: Kevin Hale Boyes Discussion: https://postgr.es/m/CADAecHWKpaPuPGXAMOH%3DwmhTpydHWGPOk9KWX97UYhp5GdqCWw%40mail.gmail.com
2024-08-04Introduce pluggable APIs for Cumulative StatisticsMichael Paquier
This commit adds support in the backend for $subject, allowing out-of-core extensions to plug their own custom kinds of cumulative statistics. This feature has come up a few times into the lists, and the first, original, suggestion came from Andres Freund, about pg_stat_statements to use the cumulative statistics APIs in shared memory rather than its own less efficient internals. The advantage of this implementation is that this can be extended to any kind of statistics. The stats kinds are divided into two parts: - The in-core "builtin" stats kinds, with designated initializers, able to use IDs up to 128. - The "custom" stats kinds, able to use a range of IDs from 128 to 256 (128 slots available as of this patch), with information saved in TopMemoryContext. This can be made larger, if necessary. There are two types of cumulative statistics in the backend: - For fixed-numbered objects (like WAL, archiver, etc.). These are attached to the snapshot and pgstats shmem control structures for efficiency, and built-in stats kinds still do that to avoid any redirection penalty. The data of custom kinds is stored in a first array in snapshot structure and a second array in the shmem control structure, both indexed by their ID, acting as an equivalent of the builtin stats. - For variable-numbered objects (like tables, functions, etc.). These are stored in a dshash using the stats kind ID in the hash lookup key. Internally, the handling of the builtin stats is unchanged, and both fixed and variabled-numbered objects are supported. Structure definitions for builtin stats kinds are renamed to reflect better the differences with custom kinds. Like custom RMGRs, custom cumulative statistics can only be loaded with shared_preload_libraries at startup, and must allocate a unique ID shared across all the PostgreSQL extension ecosystem with the following wiki page to avoid conflicts: https://wiki.postgresql.org/wiki/CustomCumulativeStats This makes the detection of the stats kinds and their handling when reading and writing stats much easier than, say, allocating IDs for stats kinds from a shared memory counter, that may change the ID used by a stats kind across restarts. When under development, extensions can use PGSTAT_KIND_EXPERIMENTAL. Two examples that can be used as templates for fixed-numbered and variable-numbered stats kinds will be added in some follow-up commits, with tests to provide coverage. Some documentation is added to explain how to use this plugin facility. Author: Michael Paquier Reviewed-by: Dmitry Dolgov, Bertrand Drouvot Discussion: https://postgr.es/m/Zmqm9j5EO0I4W8dx@paquier.xyz
2024-08-02Fix name of "Visual Studio" in documentation.Noah Misch
Back-patch to v17, which introduced this. Aleksander Alekseev Discussion: https://postgr.es/m/CAJ7c6TM7ct0EjoCQaLSVYoxxnEw4xCUFebWj77GktWsqEdyCtQ@mail.gmail.com
2024-08-02Implement pg_wal_replay_wait() stored procedureAlexander Korotkov
pg_wal_replay_wait() is to be used on standby and specifies waiting for the specific WAL location to be replayed. This option is useful when the user makes some data changes on primary and needs a guarantee to see these changes are on standby. The queue of waiters is stored in the shared memory as an LSN-ordered pairing heap, where the waiter with the nearest LSN stays on the top. During the replay of WAL, waiters whose LSNs have already been replayed are deleted from the shared memory pairing heap and woken up by setting their latches. pg_wal_replay_wait() needs to wait without any snapshot held. Otherwise, the snapshot could prevent the replay of WAL records, implying a kind of self-deadlock. This is why it is only possible to implement pg_wal_replay_wait() as a procedure working without an active snapshot, not a function. Catversion is bumped. Discussion: https://postgr.es/m/eb12f9b03851bb2583adab5df9579b4b%40postgrespro.ru Author: Kartyshov Ivan, Alexander Korotkov Reviewed-by: Michael Paquier, Peter Eisentraut, Dilip Kumar, Amit Kapila Reviewed-by: Alexander Lakhin, Bharath Rupireddy, Euler Taveira Reviewed-by: Heikki Linnakangas, Kyotaro Horiguchi
2024-08-01pg_createsubscriber: Rename option --socket-directory to --socketdirPeter Eisentraut
For consistency with the equivalent option in pg_upgrade. Reviewed-by: Hayato Kuroda <kuroda.hayato@fujitsu.com> Reviewed-by: Euler Taveira <euler@eulerto.com> Discussion: https://www.postgresql.org/message-id/flat/1ed82b9b-8e20-497d-a2f8-aebdd793d595%40eisentraut.org
2024-08-01Convert node test compile-time settings into run-time parametersPeter Eisentraut
This converts COPY_PARSE_PLAN_TREES WRITE_READ_PARSE_PLAN_TREES RAW_EXPRESSION_COVERAGE_TEST into run-time parameters debug_copy_parse_plan_trees debug_write_read_parse_plan_trees debug_raw_expression_coverage_test They can be activated for tests using PG_TEST_INITDB_EXTRA_OPTS. The compile-time symbols are kept for build farm compatibility, but they now just determine the default value of the run-time settings. Furthermore, support for these settings is not compiled in at all unless assertions are enabled, or the new symbol DEBUG_NODE_TESTS_ENABLED is defined at compile time, or any of the legacy compile-time setting symbols are defined. So there is no run-time overhead in production builds. (This is similar to the handling of DISCARD_CACHES_ENABLED.) Discussion: https://www.postgresql.org/message-id/flat/30747bd8-f51e-4e0c-a310-a6e2c37ec8aa%40eisentraut.org
2024-07-31Doc: mention executor memory usage for enable_partitionwise* GUCsDavid Rowley
Prior to this commit, the docs for enable_partitionwise_aggregate and enable_partitionwise_join mentioned the additional overheads enabling these causes for the query planner, but they mentioned nothing about the possible surge in work_mem-consuming executor nodes that could end up in the final plan. Dimitrios reported the OOM killer intervened on his query as a result of using enable_partitionwise_aggregate=on. Here we adjust the docs to mention the possible increase in the number of work_mem-consuming executor nodes that can appear in the final plan as a result of enabling these GUCs. Reported-by: Dimitrios Apostolou Reviewed-by: Ashutosh Bapat Discussion: https://postgr.es/m/3603c380-d094-136e-e333-610914fb3e80%40gmx.net Discussion: https://postgr.es/m/CAApHDvoZ0_yqwPFEpb6h261L76BUpmh5GxBQq0LeRzQ5Jh3zzg@mail.gmail.com Backpatch-through: 12, oldest supported version
2024-07-31Add API and ABI stability guidance to the C language docsPeter Eisentraut
Includes guidance for major and minor version releases, and sets reasonable expectations for extension developers to follow. Author: David Wheeler, Peter Eisentraut Discussion: https://www.postgresql.org/message-id/flat/5DA9F9D2-B8B2-43DE-BD4D-53A4160F6E8D%40justatheory.com
2024-07-31doc: Avoid too prominent use of "backup" on pg_dump man pagePeter Eisentraut
Some users inadvertently rely on pg_dump as their primary backup tool, when better solutions exist. The pg_dump man page is arguably misleading in that it starts with "pg_dump is a utility for backing up a PostgreSQL database." This tones this down a little bit, by replacing most uses of "backup" with "export" and adding a short note that pg_dump is not a general-purpose backup tool. Discussion: https://www.postgresql.org/message-id/flat/70b48475-7706-4268-990d-fd522b038d96%40eisentraut.org
2024-07-30Remove --disable-atomics, require 32 bit atomics.Thomas Munro
Modern versions of all relevant architectures and tool chains have atomics support. Since edadeb07, there is no remaining reason to carry code that simulates atomic flags and uint32 imperfectly with spinlocks. 64 bit atomics are still emulated with spinlocks, if needed, for now. Any modern compiler capable of implementing C11 <stdatomic.h> must have the underlying operations we need, though we don't require C11 yet. We detect certain compilers and architectures, so hypothetical new systems might need adjustments here. Reviewed-by: Heikki Linnakangas <hlinnaka@iki.fi> Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us> (concept, not the patch) Reviewed-by: Andres Freund <andres@anarazel.de> (concept, not the patch) Discussion: https://postgr.es/m/3351991.1697728588%40sss.pgh.pa.us
2024-07-30Remove --disable-spinlocks.Thomas Munro
A later change will require atomic support, so it wouldn't make sense for a hypothetical new system not to be able to implement spinlocks. Reviewed-by: Heikki Linnakangas <hlinnaka@iki.fi> Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us> (concept, not the patch) Reviewed-by: Andres Freund <andres@anarazel.de> (concept, not the patch) Discussion: https://postgr.es/m/3351991.1697728588%40sss.pgh.pa.us
2024-07-27Doc: fix text's description of regexp_replace's arguments.Tom Lane
Section 9.7.3 had a syntax synopsis for regexp_replace() that was different from Table 9.10's, but still wrong. Update that one too. Oversight in 580f8727c. Jian He Discussion: https://postgr.es/m/CACJufxG3NFKKsh6x4fRLv8h3V-HvN4W5dA=zNKMxsNcDwOKang@mail.gmail.com
2024-07-26Introduce num_os_semaphores GUC.Nathan Bossart
The documentation for System V IPC parameters provides complicated formulas to determine the appropriate values for SEMMNI and SEMMNS. Furthermore, these formulas have often been wrong because folks forget to update them (e.g., when adding a new auxiliary process). This commit introduces a new runtime-computed GUC named num_os_semaphores that reports the number of semaphores needed for the configured number of allowed connections, worker processes, etc. This new GUC allows us to simplify the formulas in the documentation, and it should help prevent future inaccuracies. Like the other runtime-computed GUCs, users can view it with "postgres -C" before starting the server, which is useful for preconfiguring the necessary operating system resources. Reviewed-by: Tom Lane, Sami Imseih, Andres Freund, Robert Haas Discussion: https://postgr.es/m/20240517164452.GA1914161%40nathanxps13
2024-07-26Clarify error message and documentation related to typed tables.Tom Lane
We restrict typed tables (those declared as "OF composite_type") to be based on stand-alone composite types, not composite types that are the implicitly-created rowtypes of other tables. But if you tried to do that, you got the very confusing error message "type foo is not a composite type". Provide a more specific message for that case. Also clarify related documentation in the CREATE TABLE man page. Erik Wienhold and David G. Johnston, per complaint from Hannu Krosing. Discussion: https://postgr.es/m/CAMT0RQRysCb_Amy5CTENSc5GfsvXL1a4qX3mv_hx31_v74P==g@mail.gmail.com
2024-07-26postgres_fdw: Add connection status check to postgres_fdw_get_connections().Fujii Masao
This commit extends the postgres_fdw_get_connections() function to check if connections are closed. This is useful for detecting closed postgres_fdw connections that could prevent successful transaction commits. Users can roll back transactions immediately upon detecting closed connections, avoiding unnecessary processing of failed transactions. This feature is available only on systems supporting the non-standard POLLRDHUP extension to the poll system call, including Linux. Author: Hayato Kuroda Reviewed-by: Shinya Kato, Zhihong Yu, Kyotaro Horiguchi, Andres Freund Reviewed-by: Onder Kalaci, Takamichi Osumi, Vignesh C, Tom Lane, Ted Yu Reviewed-by: Katsuragi Yuta, Peter Smith, Shubham Khanna, Fujii Masao Discussion: https://postgr.es/m/TYAPR01MB58662809E678253B90E82CE5F5889@TYAPR01MB5866.jpnprd01.prod.outlook.com
2024-07-26postgres_fdw: Add "used_in_xact" column to postgres_fdw_get_connections().Fujii Masao
This commit extends the postgres_fdw_get_connections() function to include a new used_in_xact column, indicating whether each connection is used in the current transaction. This addition is particularly useful for the upcoming feature that will check if connections are closed. By using those information, users can verify if postgres_fdw connections used in a transaction remain open. If any connection is closed, the transaction cannot be committed successfully. In this case users can roll back it immediately without waiting for transaction end. The SQL API for postgres_fdw_get_connections() is updated by this commit and may change in the future. To handle compatibility with older SQL declarations, an API versioning system is introduced, allowing the function to behave differently based on the API version. Author: Hayato Kuroda Reviewed-by: Fujii Masao Discussion: https://postgr.es/m/be9382f7-5072-4760-8b3f-31d6dffa8d62@oss.nttdata.com
2024-07-26Add test for early backend startup errorsHeikki Linnakangas
The new test tests the libpq fallback behavior on an early error, which was fixed in the previous commit. This adds an IS_INJECTION_POINT_ATTACHED() macro, to allow writing injected test code alongside the normal source code. In principle, the new test could've been implemented by an extra test module with a callback that sets the FrontendProtocol global variable, but I think it's more clear to have the test code right where the injection point is, because it has pretty intimate knowledge of the surrounding context it runs in. Reviewed-by: Michael Paquier Discussion: https://www.postgresql.org/message-id/CAOYmi%2Bnwvu21mJ4DYKUa98HdfM_KZJi7B1MhyXtnsyOO-PB6Ww%40mail.gmail.com
2024-07-26doc: Enhance documentation for postgres_fdw_get_connections() output columns.Fujii Masao
The documentation previously described the output columns of postgres_fdw_get_connections() in text format, which was manageable for the original two columns. However, upcoming patches will add new columns, making text descriptions less readable. This commit updates the documentation to use a table format, making it easier for users to understand each output column. Author: Fujii Masao, Hayato Kuroda Reviewed-by: Hayato Kuroda Discussion: https://postgr.es/m/d04aae8d-05f5-42f4-a263-b962334d9f75@oss.nttdata.com
2024-07-25Doc: fix misleading syntax synopses for targetlists.Tom Lane
In the syntax synopses for SELECT, INSERT, UPDATE, etc, SELECT ... and RETURNING ... targetlists were missing { ... } braces around an OR (|) operator. That allows misinterpretation which could lead to confusion. David G. Johnston, per gripe from masondeanm@aol.com. Discussion: https://postgr.es/m/172193970148.915373.2403176471224676074@wrigleys.postgresql.org
2024-07-25Doc: update some HTTP links to point to canonical URLs.Tom Lane
These aren't actually broken at present, but we might as well avoid redirects. Joel Jacobson Discussion: https://postgr.es/m/8ccc96c7-0515-491b-be98-cfacdaeda815@app.fastmail.com
2024-07-25Document restrictions regarding incremental backups and standbys.Robert Haas
If you try to take an incremental backup on a standby and there hasn't been much system activity, it might fail. Document why this happens. Also add a hint to the error message you get, to make it more likely that users will understand what has gone wrong. Laurenz Albe and Robert Haas Discussion: https://postgr.es/m/5468641ad821dad7aa3b2d65bf843146443a1b68.camel@cybertec.at
2024-07-25Add argument names to the regexp_XXX functions.Tom Lane
This change allows these functions to be called using named-argument notation, which can be helpful for readability, particularly for the ones with many arguments. There was considerable debate about exactly which names to use, but in the end we settled on the names already shown in our documentation table 9.10. The citext extension provides citext-aware versions of some of these functions, so add argument names to those too. In passing, fix table 9.10's syntax synopses for regexp_match, which were slightly wrong about which combinations of arguments are allowed. Jian He, reviewed by Dian Fay and others Discussion: https://postgr.es/m/CACJufxG3NFKKsh6x4fRLv8h3V-HvN4W5dA=zNKMxsNcDwOKang@mail.gmail.com
2024-07-25Add path column to pg_backend_memory_contexts viewDavid Rowley
"path" provides a reliable method of determining the parent/child relationships between memory contexts. Previously this could be done in a non-reliable way by writing a recursive query and joining the "parent" and "name" columns. This wasn't reliable as the names were not unique, which could result in joining to the wrong parent. To make this reliable, "path" stores an array of numerical identifiers starting with the identifier for TopLevelMemoryContext. It contains an element for each intermediate parent between that and the current context. Incompatibility: Here we also adjust the "level" column to make it 1-based rather than 0-based. A 1-based level provides a convenient way to access elements in the "path" array. e.g. path[level] gives the identifier for the current context. Identifiers are not stable across multiple evaluations of the view. In an attempt to make these more stable for ad-hoc queries, the identifiers are assigned breadth-first. Contexts closer to TopLevelMemoryContext are less likely to change between queries and during queries. Author: Melih Mutlu <m.melihmutlu@gmail.com> Discussion: https://postgr.es/m/CAGPVpCThLyOsj3e_gYEvLoHkr5w=tadDiN_=z2OwsK3VJppeBA@mail.gmail.com Reviewed-by: Andres Freund, Stephen Frost, Atsushi Torikoshi, Reviewed-by: Michael Paquier, Robert Haas, David Rowley
2024-07-25doc: Decorate psql page with application markup tagsMichael Paquier
Noticed while looking at this area of the documentation for a separate patch.
2024-07-24Fix a missing article in the documentationAlvaro Herrera
Per complaint from Grant Gryczan. It's a very old typo; backpatch all the way back. Author: Laurenz Albe <laurenz.albe@cybertec.at> Discussion: https://postgr.es/m/172179789219.915368.16590585529628354757@wrigleys.postgresql.org
2024-07-24Doc: Fix the mistakes in the subscription's failover option.Amit Kapila
The documentation incorrectly stated that users could not alter the subscription's failover option when the two-phase commit is enabled. The steps to confirm that the standby server is ready for failover were incorrect. Author: Shveta Malik, Hou Zhijie Reviewed-by: Amit Kapila Discussion: https://postgr.es/m/OS0PR01MB571657B72F8D75BD858DCCE394AD2@OS0PR01MB5716.jpnprd01.prod.outlook.com Discussion: https://postgr.es/m/CAJpy0uBBk+OZXXqQ00Gai09XR+mDi2=9sMBYY0F+BedoFivaMA@mail.gmail.com
2024-07-24Allow altering of two_phase option of a SUBSCRIPTION.Amit Kapila
The two_phase option is controlled by both the publisher (as a slot option) and the subscriber (as a subscription option), so the slot option must also be modified. Changing the 'two_phase' option for a subscription from 'true' to 'false' is permitted only when there are no pending prepared transactions corresponding to that subscription. Otherwise, the changes of already prepared transactions can be replicated again along with their corresponding commit leading to duplicate data or errors. To avoid data loss, the 'two_phase' option for a subscription can only be changed from 'false' to 'true' once the initial data synchronization is completed. Therefore this is performed later by the logical replication worker. Author: Hayato Kuroda, Ajin Cherian, Amit Kapila Reviewed-by: Peter Smith, Hou Zhijie, Amit Kapila, Vitaly Davydov, Vignesh C Discussion: https://postgr.es/m/8fab8-65d74c80-1-2f28e880@39088166
2024-07-23ldapurl is supported with simple bindPeter Eisentraut
The docs currently imply that ldapurl is for search+bind only, but that's not true. Rearrange the docs to cover this better. Add a test ldapurl with simple bind. This was previously allowed but unexercised, and now that it's documented it'd be good to pin the behavior. Improve error when mixing LDAP bind modes. The option names had gone stale; replace them with a more general statement. Author: Jacob Champion <jacob.champion@enterprisedb.com> Discussion: https://www.postgresql.org/message-id/flat/CAOYmi+nyg9gE0LeP=xQ3AgyQGR=5ZZMkVVbWd0uR8XQmg_dd5Q@mail.gmail.com
2024-07-22Doc: improve description of plpgsql's FETCH and MOVE commands.Tom Lane
We were not being clear about which variants of the "direction" clause are permitted in MOVE. Also, the text seemed to be written with only the FETCH/MOVE NEXT case in mind, so it didn't apply very well to other variants. Also, document that "MOVE count IN cursor" only works if count is a constant. This is not the whole truth, because some other cases such as a parenthesized expression will also work, but we want to push people to use "MOVE FORWARD count" instead. The constant case is enough to cover what we allow in plain SQL, and that seems sufficient to claim support for. Update a comment in pl_gram.y claiming that we don't document that point. Per gripe from Philipp Salvisberg. Discussion: https://postgr.es/m/172155553388.702.7932496598218792085@wrigleys.postgresql.org
2024-07-18Doc: improve description of plpgsql's RAISE command.Tom Lane
RAISE accepts either = or := in the USING clause, so fix the syntax synopsis to show that. Rearrange and wordsmith the descriptions of the different syntax variants, in hopes of improving clarity. Igor Gnatyuk, reviewed by Jian He and Laurenz Albe; minor additional wordsmithing by me Discussion: https://postgr.es/m/CAEu6iLvhF5sdGeat2x4_L0FvWW_SiN--ma8ya7CZd-oJoV+yqQ@mail.gmail.com
2024-07-18Do not summarize WAL if generated with wal_level=minimal.Robert Haas
To do this, we must include the wal_level in the first WAL record covered by each summary file; so add wal_level to struct Checkpoint and the payload of XLOG_CHECKPOINT_REDO and XLOG_END_OF_RECOVERY. This, in turn, requires bumping XLOG_PAGE_MAGIC and, since the Checkpoint is also stored in the control file, also PG_CONTROL_VERSION. It's not great to do that so late in the release cycle, but the alternative seems to ship v17 without robust protections against this scenario, which could result in corrupted incremental backups. A side effect of this patch is that, when a server with wal_level=replica is started with summarize_wal=on for the first time, summarization will no longer begin with the oldest WAL that still exists in pg_wal, but rather from the first checkpoint after that. This change should be harmless, because a WAL summary for a partial checkpoint cycle can never make an incremental backup possible when it would otherwise not have been. Report by Fujii Masao. Patch by me. Review and/or testing by Jakub Wartak and Fujii Masao. Discussion: http://postgr.es/m/6e30082e-041b-4e31-9633-95a66de76f5d@oss.nttdata.com
2024-07-18Add INJECTION_POINT_CACHED() to run injection points directly from cacheMichael Paquier
This new macro is able to perform a direct lookup from the local cache of injection points (refreshed each time a point is loaded or run), without touching the shared memory state of injection points at all. This works in combination with INJECTION_POINT_LOAD(), and it is better than INJECTION_POINT() in a critical section due to the fact that it would avoid all memory allocations should a concurrent detach happen since a LOAD(), as it retrieves a callback from the backend-private memory. The documentation is updated to describe in more details how to use this new macro with a load. Some tests are added to the module injection_points based on a new SQL function that acts as a wrapper of INJECTION_POINT_CACHED(). Based on a suggestion from Heikki Linnakangas. Author: Heikki Linnakangas, Michael Paquier Discussion: https://postgr.es/m/58d588d0-e63f-432f-9181-bed29313dece@iki.fi
2024-07-17Doc: fix minor syntax error in example.Tom Lane
The CREATE TABLE option is GENERATED BY DEFAULT *AS* IDENTITY. Per bug #18543 from Ondřej Navrátil. Seems to have crept in in a37bb7c13, so back-patch to v17 where that was added. Discussion: https://postgr.es/m/18543-93c721689f9928e8@postgresql.org
2024-07-16SQL/JSON: Fix a paragraph in JSON_TABLE documentationAmit Langote
Using <replaceable>text</replaceable> inside parantheses is not a common or good style, so rephrase a sentence to avoid that style. Also rephrase the text in that paragraph a bit while at it. Reported-by: Marcos Pegoraro <marcos@f10.com.br> Author: Jian He <jian.universality@gmail.com> Reviewed-by: Daniel Gustafsson <daniel@yesql.se> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Discussion: https://postgr.es/m/CAB-JLwZqH3Yec6Kz-4-+pa0ZG9QJBsxjJZwYcMZYzEDR_fXnKw@mail.gmail.com
2024-07-15Doc: minor improvements for plpgsql "Transaction Management" section.Tom Lane
Point out that savepoint commands cannot be issued in PL/pgSQL, and suggest that exception blocks can usually be used instead. Add a caveat to the discussion of cursor loops vs. transactions, pointing out that any locks taken by the cursor query will be lost at COMMIT. This is implicit in what's already said, but the existing text leaves the distinct impression that the auto-hold behavior is transparent, which it's not really. Per a couple of recent complaints (one unsigned, and one in bug #18531 from Dzmitry Jachnik). Back-patch to v17, just so this makes it into current docs in less than a year-and-a-half. Discussion: https://postgr.es/m/172076354433.736586.14347210271966220018@wrigleys.postgresql.org Discussion: https://postgr.es/m/18531-c6dddd33b8555fd2@postgresql.org
2024-07-15Fix tablespace handling in MERGE/SPLIT partition commands.Fujii Masao
As commit ca4103025d stated, new partitions without a specified tablespace should inherit the parent relation's tablespace. However, previously, ALTER TABLE MERGE PARTITIONS and ALTER TABLE SPLIT PARTITION commands always created new partitions in the default tablespace, ignoring the parent's tablespace. This commit ensures new partitions inherit the parent's tablespace. Backpatch to v17 where these commands were introduced. Author: Fujii Masao Reviewed-by: Masahiko Sawada Discussion: https://postgr.es/m/abaf390b-3320-40a5-8815-ef476db5cfe7@oss.nttdata.com
2024-07-11Add min and max aggregates for composite types (records).Tom Lane
Like min/max for arrays, these are just thin wrappers around the existing btree comparison function for records. Aleksander Alekseev Discussion: https://postgr.es/m/CAO=iB8L4WYSNxCJ8GURRjQsrXEQ2-zn3FiCsh2LMqvWq2WcONg@mail.gmail.com
2024-07-10Revamp documentation for predefined roles.Nathan Bossart
Presently, the page for predefined roles contains a table with brief descriptions of what each role allows. Below the table, there is a separate section with more detailed information about some of the roles. As the set of predefined roles has grown over the years, this page has (IMHO) become less readable. This commit attempts to improve the predefined roles documentation by abandoning the table in favor of listing each role with its own complete description, similar to how we document GUCs. Besides merging the information that was split between the table and the section below it, this commit also alphabetizes the roles. The alphabetization is imperfect because some of the roles are grouped (e.g., pg_read_all_data and pg_write_all_data), and we order such groups by the first role mentioned, but that seemed like a better choice than breaking the groups apart. Finally, this commit makes some stylistic adjustments to the text. Reviewed-by: David G. Johnston, Robert Haas Discussion: https://postgr.es/m/ZmtM-4-eRtq8DRf6%40nathan
2024-07-10doc: Update track_io_timing documentation to mention pg_stat_io.Fujii Masao
The I/O timing information collected when track_io_timing is enabled is now documented to appear in the pg_stat_io view, which was previously not mentioned. This commit also enhances the description of track_io_timing to clarify that it monitors not only block read and write but also block extend and fsync operations. Additionally, the description of track_wal_io_timing has been improved to mention both WAL write and WAL fsync monitoring. Backpatch to v16 where pg_stat_io was added. Author: Hajime Matsunaga Reviewed-by: Melanie Plageman, Nazir Bilal Yavuz, Fujii Masao Discussion: https://postgr.es/m/TYWPR01MB10742EE4A6F34C33061429D38A4D52@TYWPR01MB10742.jpnprd01.prod.outlook.com