aboutsummaryrefslogtreecommitdiff
path: root/doc/src/sgml/ref/postgres-ref.sgml
Commit message (Collapse)AuthorAge
* Provide options for postmaster to kill child processes with SIGABRT.Tom Lane2022-11-21
| | | | | | | | | | | | | | | | | | | | | | | | | | | | The postmaster normally sends SIGQUIT to force-terminate its child processes after a child crash or immediate-stop request. If that doesn't result in child exit within a few seconds, we follow it up with SIGKILL. This patch provides GUC flags that allow either of these signals to be replaced with SIGABRT. On typically-configured Unix systems, that will result in a core dump being produced for each such child. This can be useful for debugging problems, although it's not something you'd want to have on in production due to the risk of disk space bloat from lots of core files. The old postmaster -T switch, which sent SIGSTOP in place of SIGQUIT, is changed to be the same as send_abort_for_crash. As far as I can tell from the code comments, the intent of that switch was just to block things for long enough to force core dumps manually, which seems like an unnecessary extra step. (Maybe at the time, there was no way to get most kernels to produce core files with per-PID names, requiring manual core file renaming after each one. But now it's surely the hard way.) I also took the opportunity to remove the old postmaster -n (skip shmem reinit) switch, which hasn't actually done anything in decades, though the documentation still claimed it did. Discussion: https://postgr.es/m/2251016.1668797294@sss.pgh.pa.us
* Introduce GUC shared_memory_size_in_huge_pagesMichael Paquier2021-09-21
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This runtime-computed GUC shows the number of huge pages required for the server's main shared memory area, taking advantage of the work done in 0c39c29 and 0bd305e. This is useful for users to estimate the amount of huge pages required for a server as it becomes possible to do an estimation without having to start the server and potentially allocate a large chunk of shared memory. The number of huge pages is calculated based on the existing GUC huge_page_size if set, or by using the system's default by looking at /proc/meminfo on Linux. There is nothing new here as this commit reuses the existing calculation methods, and just exposes this information directly to the user. The routine calculating the huge page size is refactored to limit the number of files with platform-specific flags. This new GUC's name was the most popular choice based on the discussion done. This is only supported on Linux. I have taken the time to test the change on Linux, Windows and MacOS, though for the last two ones large pages are not supported. The first one calculates correctly the number of pages depending on the existing GUC huge_page_size or the system's default. Thanks to Andres Freund, Robert Haas, Kyotaro Horiguchi, Tom Lane, Justin Pryzby (and anybody forgotten here) for the discussion. Author: Nathan Bossart Discussion: https://postgr.es/m/F2772387-CE0F-46BF-B5F1-CC55516EB885@amazon.com
* Support "postgres -C" with runtime-computed GUCsMichael Paquier2021-09-16
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Until now, the -C option of postgres was handled before a small subset of GUCs computed at runtime are initialized, leading to incorrect results as GUC machinery would fall back to default values for such parameters. For example, data_checksums could report "off" for a cluster as the control file is not loaded yet. Or wal_segment_size would show a segment size at 16MB even if initdb --wal-segsize used something else. Worse, the command would fail to properly report the recently-introduced shared_memory, that requires to load shared_preload_libraries as these could ask for a chunk of shared memory. Support for runtime GUCs comes with a limitation, as the operation is now allowed on a running server. One notable reason for this is that _PG_init() functions of loadable libraries are called before all runtime-computed GUCs are initialized, and this is not guaranteed to be safe to do on running servers. For the case of shared_memory_size, where we want to know how much memory would be used without allocating it, this limitation is fine. Another case where this will help is for huge pages, with the introduction of a different GUC to evaluate the amount of huge pages required for a server before starting it, without having to allocate large chunks of memory. This feature is controlled with a new GUC flag, and four parameters are classified as runtime-computed as of this change: - data_checksums - shared_memory_size - data_directory_mode - wal_segment_size Some TAP tests are added to provide some coverage here, using data_checksums in the tests of pg_checksums. Per discussion with Andres Freund, Justin Pryzby, Magnus Hagander and more. Author: Nathan Bossart Discussion: https://postgr.es/m/F2772387-CE0F-46BF-B5F1-CC55516EB885@amazon.com
* Revert "Add key management system" (978f869b99) & later commitsBruce Momjian2020-12-27
| | | | | | | | | | The patch needs test cases, reorganization, and cfbot testing. Technically reverts commits 5c31afc49d..e35b2bad1a (exclusive/inclusive) and 08db7c63f3..ccbe34139b. Reported-by: Tom Lane, Michael Paquier Discussion: https://postgr.es/m/E1ktAAG-0002V2-VB@gemulon.postgresql.org
* Add key management systemBruce Momjian2020-12-25
| | | | | | | | | | | | | | | This adds a key management system that stores (currently) two data encryption keys of length 128, 192, or 256 bits. The data keys are AES256 encrypted using a key encryption key, and validated via GCM cipher mode. A command to obtain the key encryption key must be specified at initdb time, and will be run at every database server start. New parameters allow a file descriptor open to the terminal to be passed. pg_upgrade support has also been added. Discussion: https://postgr.es/m/CA+fd4k7q5o6Nc_AaX6BcYM9yqTbC6_pnH-6nSD=54Zp6NBQTCQ@mail.gmail.com Discussion: https://postgr.es/m/20201202213814.GG20285@momjian.us Author: Masahiko Sawada, me, Stephen Frost
* Remove -o option to postmasterMagnus Hagander2020-11-10
| | | | | | | This option was declared obsolete many years ago. Reviewed-By: Tom Lane Discussion: https://postgr.es/m/CABUevEyOE=9CQwZm2j=vwP5+6OLCSoxn9pBjK8gyRdkTzMfqtQ@mail.gmail.com
* Improve <xref> vs. <command> formatting in the documentationPeter Eisentraut2020-10-03
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
* doc: add commas after 'i.e.' and 'e.g.'Bruce Momjian2020-08-31
| | | | | | | | | | | This follows the American format, https://jakubmarian.com/comma-after-i-e-and-e-g/. There is no intention of requiring this format for future text, but making existing text consistent every few years makes sense. Discussion: https://postgr.es/m/20200825183619.GA22369@momjian.us Backpatch-through: 9.5
* Add hash_mem_multiplier GUC.Peter Geoghegan2020-07-29
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add a GUC that acts as a multiplier on work_mem. It gets applied when sizing executor node hash tables that were previously size constrained using work_mem alone. The new GUC can be used to preferentially give hash-based nodes more memory than the generic work_mem limit. It is intended to enable admin tuning of the executor's memory usage. Overall system throughput and system responsiveness can be improved by giving hash-based executor nodes more memory (especially over sort-based alternatives, which are often much less sensitive to being memory constrained). The default value for hash_mem_multiplier is 1.0, which is also the minimum valid value. This means that hash-based nodes continue to apply work_mem in the traditional way by default. hash_mem_multiplier is generally useful. However, it is being added now due to concerns about hash aggregate performance stability for users that upgrade to Postgres 13 (which added disk-based hash aggregation in commit 1f39bce0). While the old hash aggregate behavior risked out-of-memory errors, it is nevertheless likely that many users actually benefited. Hash agg's previous indifference to work_mem during query execution was not just faster; it also accidentally made aggregation resilient to grouping estimate problems (at least in cases where this didn't create destabilizing memory pressure). hash_mem_multiplier can provide a certain kind of continuity with the behavior of Postgres 12 hash aggregates in cases where the planner incorrectly estimates that all groups (plus related allocations) will fit in work_mem/hash_mem. This seems necessary because hash-based aggregation is usually much slower when only a small fraction of all groups can fit. Even when it isn't possible to totally avoid hash aggregates that spill, giving hash aggregation more memory will reliably improve performance (the same cannot be said for external sort operations, which appear to be almost unaffected by memory availability provided it's at least possible to get a single merge pass). The PostgreSQL 13 release notes should advise users that increasing hash_mem_multiplier can help with performance regressions associated with hash aggregation. That can be taken care of by a later commit. Author: Peter Geoghegan Reviewed-By: Álvaro Herrera, Jeff Davis Discussion: https://postgr.es/m/20200625203629.7m6yvut7eqblgmfo@alap3.anarazel.de Discussion: https://postgr.es/m/CAH2-WzmD%2Bi1pG6rc1%2BCjc4V6EaFJ_qSuKCCHVnH%3DoruqD-zqow%40mail.gmail.com Backpatch: 13-, where disk-based hash aggregation was introduced.
* Doc: fix "Unresolved ID reference" warnings, clean up man page cross-refs.Tom Lane2020-05-11
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Use xreflabel attributes instead of endterm attributes to control the appearance of links to subsections of SQL command reference pages. This is simpler, it matches what we do elsewhere (e.g. for GUC variables), and it doesn't draw "Unresolved ID reference" warnings from the PDF toolchain. Fix some places where the text was absolutely dependent on an <xref> rendering exactly so, by using a <link> around the required text instead. At least one of those spots had already been turned into bad grammar by subsequent changes, and the whole idea is just too fragile for my taste. <xref> does NOT have fixed output, don't write as if it does. Consistently include a page-level link in cross-man-page references, because otherwise they are useless/nonsensical in man-page output. Likewise, be consistent about mentioning "below" or "above" in same-page references; we were doing that in about 90% of the cases, but now it's 100%. Also get rid of another nonfunctional-in-PDF idea, of making cross-references to functions by sticking ID tags on <row> constructs. We can put the IDs on <indexterm>s instead --- which is probably not any more sensible in abstract terms, but it works where the other doesn't. (There is talk of attaching cross-reference IDs to most or all of the docs' function descriptions, but for now I just fixed the two that exist.) Discussion: https://postgr.es/m/14480.1589154358@sss.pgh.pa.us
* doc: Clean up title case usePeter Eisentraut2019-09-08
| | | | | Note: Following existing practice, titles of formalpara and step are not titlecased.
* Convert documentation to DocBook XMLPeter Eisentraut2017-11-23
| | | | | | | | | | | | | | | | | | Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
* Don't use SGML empty tagsPeter Eisentraut2017-10-17
| | | | | | | | For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
* Remove TZ environment-variable entry from postgres reference page.Tom Lane2016-03-29
| | | | | | | | | | | | The server hasn't paid attention to the TZ environment variable since commit ca4af308c32d03db, but that commit missed removing this documentation reference, as did commit d883b916a947a3c6 which added the reference where it now belongs (initdb). Back-patch to 9.2 where the behavior changed. Also back-patch d883b916a947a3c6 as needed. Matthew Somerville
* Adjust behavior of single-user -j mode for better initdb error reporting.Tom Lane2015-12-17
| | | | | | | | | | | | | | | | | | | | | | | | | | Previously, -j caused the entire input file to be read in and executed as a single command string. That's undesirable, not least because any error causes the entire file to be regurgitated as the "failing query". Some experimentation suggests a better rule: end the command string when we see a semicolon immediately followed by two newlines, ie, an empty line after a query. This serves nicely to break up the existing examples such as information_schema.sql and system_views.sql. A limitation is that it's no longer possible to write such a sequence within a string literal or multiline comment in a file meant to be read with -j; but there are no instances of such a problem within the data currently used by initdb. (If someone does make such a mistake in future, it'll be obvious because they'll get an unterminated-literal or unterminated-comment syntax error.) Other than that, there shouldn't be any negative consequences; you're not forced to end statements that way, it's just a better idea in most cases. In passing, remove src/include/tcop/tcopdebug.h, which is dead code because it's not included anywhere, and hasn't been for more than ten years. One of the debug-support symbols it purported to describe has been unreferenced for at least the same amount of time, and the other is removed by this commit on the grounds that it was useless: forcing -j mode all the time would have broken initdb. The lack of complaints about that, or about the missing inclusion, shows that no one has tried to use TCOP_DONTUSENEWLINE in many years.
* Code + docs review for escaping of option values (commit 11a020eb6).Tom Lane2015-06-29
| | | | | | | | | Avoid memory leak from incorrect choice of how to free a StringInfo (resetStringInfo doesn't do it). Now that pg_split_opts doesn't scribble on the optstr, mark that as "const" for clarity. Attach the commentary in protocol.sgml to the right place, and add documentation about the user-visible effects of this change on postgres' -o option and libpq's PGOPTIONS option.
* Properly document that -r is only honored from the command-line.Bruce Momjian2014-09-06
| | | | | | | | This is for postgres/postmaster options. Report by Tom Lane Backpatch through 9.4
* pg_ctl, pg_upgrade: allow multiple -o/-O options, append themBruce Momjian2014-08-25
| | | | Report by Pavel Raiskup
* Don't allow to disable backend assertions via the debug_assertions GUC.Andres Freund2014-06-20
| | | | | | | | | | | | | | | | | | | | The existance of the assert_enabled variable (backing the debug_assertions GUC) reduced the amount of knowledge some static code checkers (like coverity and various compilers) could infer from the existance of the assertion. That could have been solved by optionally removing the assertion_enabled variable from the Assert() et al macros at compile time when some special macro is defined, but the resulting complication doesn't seem to be worth the gain from having debug_assertions. Recompiling is fast enough. The debug_assertions GUC is still available, but readonly, as it's useful when diagnosing problems. The commandline/client startup option -A, which previously also allowed to enable/disable assertions, has been removed as it doesn't serve a purpose anymore. While at it, reduce code duplication in bufmgr.c and localbuf.c assertions checking for spurious buffer pins. That code had to be reindented anyway to cope with the assert_enabled removal.
* doc: Improve DocBook XML validityPeter Eisentraut2014-02-23
| | | | | | | | | | | DocBook XML is superficially compatible with DocBook SGML but has a slightly stricter DTD that we have been violating in a few cases. Although XSLT doesn't care whether the document is valid, the style sheets don't necessarily process invalid documents correctly, so we need to work toward fixing this. This first commit moves the indexterms in refentry elements to an allowed position. It has no impact on the output.
* Clarify terminology standalone backend vs. single-user modePeter Eisentraut2013-06-20
| | | | | | | | Most of the documentation uses "single-user mode", so use that in the code as well. Adjust the documentation to match the new error message wording. Also add a documentation index entry for "single-user mode". Based-on-patch-by: Jeff Janes <jeff.janes@gmail.com>
* Properly document that SIGTERM is OK for users to use on a postgresBruce Momjian2012-08-30
| | | | | | session, now that pg_terminate_backend() uses it. Josh Kupershmidt
* Document that PGDATA has to point to the configuration files, ratherBruce Momjian2012-08-15
| | | | | | than the actual data storage directory. Per suggestion from Thom Brown
* Support having multiple Unix-domain sockets per postmaster.Tom Lane2012-08-10
| | | | | | | | | | | | | | Replace unix_socket_directory with unix_socket_directories, which is a list of socket directories, and adjust postmaster's code to allow zero or more Unix-domain sockets to be created. This is mostly a straightforward change, but since the Unix sockets ought to be created after the TCP/IP sockets for safety reasons (better chance of detecting a port number conflict), AddToDataDirLockFile needs to be fixed to support out-of-order updates of data directory lockfile lines. That's a change that had been foreseen to be necessary someday anyway. Honza Horak, reviewed and revised by Tom Lane
* Make documentation of --help and --version options more consistentPeter Eisentraut2012-06-18
| | | | | | Before, some places didn't document the short options (-? and -V), some documented both, some documented nothing, and they were listed in various orders. Now this is hopefully more consistent and complete.
* Improve documentation of postgres -C optionPeter Eisentraut2012-06-13
| | | | | | Clarify help (s/return/print/), and explain that this option is for use by other programs, not for user-facing use (it does not print units).
* Support index-only scans using the visibility map to avoid heap fetches.Tom Lane2011-10-07
| | | | | | | | | | | | | When a btree index contains all columns required by the query, and the visibility map shows that all tuples on a target heap page are visible-to-all, we don't need to fetch that heap page. This patch depends on the previous patches that made the visibility map reliable. There's a fair amount left to do here, notably trying to figure out a less chintzy way of estimating the cost of an index-only scan, but the core functionality seems ready to commit. Robert Haas and Ibrar Ahmed, with some previous work by Heikki Linnakangas.
* Add postmaster -C option to query configuration parameters, and haveBruce Momjian2011-10-06
| | | | | | pg_ctl use that to query the data directory for config-only installs. This fixes awkward or impossible pg_ctl operation for config-only installs.
* Remove whitespace from end of linesPeter Eisentraut2011-08-07
|
* Document that server single-user mode does not do checkpoints or otherBruce Momjian2011-03-09
| | | | background processing.
* Improve wording of initdb and pg_controldata manual pages.REL9_1_ALPHA4Bruce Momjian2011-03-09
| | | | gabrielle <gorthx@gmail.com>
* Properly capitalize documentation headings; some only had initial-wordBruce Momjian2011-01-29
| | | | capitalization.
* Remove useless whitespace at end of linesPeter Eisentraut2010-11-23
|
* Remove cvs keywords from all files.Magnus Hagander2010-09-20
|
* Document that pg_ctl cares about the PGHOST environment variable.Bruce Momjian2010-02-22
|
* Minor copy-editing.Tom Lane2007-07-09
|
* Remove useless database name from bootstrap argument processing (includingAlvaro Herrera2007-02-16
| | | | startup and bgwriter processes), and the -y flag. It's not used anywhere.
* Update reference documentation on may/can/might:Bruce Momjian2007-01-31
| | | | | | | | | | | | | | Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash".
* Fix erroneous implementation of -s in postmaster.c (the switch doesn't takeTom Lane2007-01-04
| | | | | | an optarg). Add some comments noting that code in three different files has to be kept in sync. Fix erroneous description of -S switch (it sets work_mem not silent_mode), and do some light copy-editing elsewhere in postgres-ref.
* Merge postmaster and postgres command into just postgres. postmasterPeter Eisentraut2006-06-18
| | | | | symlink is kept for now for compatibility. To call single-user mode, use postgres --single.
* Make all command-line options of postmaster and postgres the same. SeePeter Eisentraut2006-01-05
| | | | | http://archives.postgresql.org/pgsql-hackers/2006-01/msg00151.php for the complete plan.
* Replace "--" and "---" with "&mdash;" as appropriate, for better-lookingNeil Conway2004-11-15
| | | | output.
* Whack some sense into the configuration-file-location patch.Tom Lane2004-10-08
| | | | | | | Refactor code into something reasonably understandable, cause use of the feature to not fail in standalone backends or in EXEC_BACKEND case, fix sloppy guc.c table entries, make the documentation minimally usable.
* Rename SortMem and VacuumMem to work_mem and maintenance_work_mem.Tom Lane2004-02-03
| | | | | | | Make btree index creation and initial validation of foreign-key constraints use maintenance_work_mem rather than work_mem as their memory limit. Add some code to guc.c to allow these variables to be referenced by their old names in SHOW and SET commands, for backwards compatibility.
* $Header: -> $PostgreSQL Changes ...PostgreSQL Daemon2003-11-29
|
* Put --describe-config in the right place.Peter Eisentraut2003-11-02
|
* Add --describe-config to top of postgres manual page.Bruce Momjian2003-10-28
|
* Document --describe-config.Bruce Momjian2003-10-28
|
* Add mention of SIGHUP on the postmaster manual page.Bruce Momjian2003-10-16
|
* Repair some REINDEX problems per recent discussions. The relcache isTom Lane2003-09-24
| | | | | | | | | | | | | now able to cope with assigning new relfilenode values to nailed-in-cache indexes, so they can be reindexed using the fully crash-safe method. This leaves only shared system indexes as special cases. Remove the 'index deactivation' code, since it provides no useful protection in the shared- index case. Require reindexing of shared indexes to be done in standalone mode, but remove other restrictions on REINDEX. -P (IgnoreSystemIndexes) now prevents using indexes for lookups, but does not disable index updates. It is therefore safe to allow from PGOPTIONS. Upshot: reindexing system catalogs can be done without a standalone backend for all cases except shared catalogs.
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-22 05:57:47 +0000