summaryrefslogtreecommitdiff
path: root/doc/src/sgml/ref
AgeCommit message (Collapse)Author
2015-08-20doc: Whitespace and formatting fixesPeter Eisentraut
2015-08-15Improve documentation about MVCC-unsafe utility commands.Tom Lane
The table-rewriting forms of ALTER TABLE are MVCC-unsafe, in much the same way as TRUNCATE, because they replace all rows of the table with newly-made rows with a new xmin. (Ideally, concurrent transactions with old snapshots would continue to see the old table contents, but the data is not there anymore --- and if it were there, it would be inconsistent with the table's updated rowtype, so there would be serious implementation problems to fix.) This was nowhere documented though, and the problem was only documented for TRUNCATE in a note in the TRUNCATE reference page. Create a new "Caveats" section in the MVCC chapter that can be home to this and other limitations on serializable consistency. In passing, fix a mistaken statement that VACUUM and CLUSTER would reclaim space occupied by a dropped column. They don't reconstruct existing tuples so they couldn't do that. Back-patch to all supported branches.
2015-08-10Don't start to stream after pg_receivexlog --create-slot.Andres Freund
Immediately starting to stream after --create-slot is inconvenient in a number of situations (e.g. when configuring a slot for use in recovery.conf) and it's easy to just call pg_receivexlog twice in the rest of the cases. Author: Michael Paquier Discussion: CAB7nPqQ9qEtuDiKY3OpNzHcz5iUA+DUX9FcN9K8GUkCZvG7+Ew@mail.gmail.com Backpatch: 9.5, where the option was introduced
2015-07-30Improve CREATE FUNCTION doc WRT to LEAKPROOF RLS interaction.Joe Conway
Patch by Dean Rasheed. Back-patched to 9.5 where RLS was introduced.
2015-07-25Redesign tablesample method API, and do extensive code review.Tom Lane
The original implementation of TABLESAMPLE modeled the tablesample method API on index access methods, which wasn't a good choice because, without specialized DDL commands, there's no way to build an extension that can implement a TSM. (Raw inserts into system catalogs are not an acceptable thing to do, because we can't undo them during DROP EXTENSION, nor will pg_upgrade behave sanely.) Instead adopt an API more like procedural language handlers or foreign data wrappers, wherein the only SQL-level support object needed is a single handler function identified by having a special return type. This lets us get rid of the supporting catalog altogether, so that no custom DDL support is needed for the feature. Adjust the API so that it can support non-constant tablesample arguments (the original coding assumed we could evaluate the argument expressions at ExecInitSampleScan time, which is undesirable even if it weren't outright unsafe), and discourage sampling methods from looking at invisible tuples. Make sure that the BERNOULLI and SYSTEM methods are genuinely repeatable within and across queries, as required by the SQL standard, and deal more honestly with methods that can't support that requirement. Make a full code-review pass over the tablesample additions, and fix assorted bugs, omissions, infelicities, and cosmetic issues (such as failure to put the added code stanzas in a consistent ordering). Improve EXPLAIN's output of tablesample plans, too. Back-patch to 9.5 so that we don't have to support the original API in production.
2015-07-12Optionally don't error out due to preexisting slots in commandline utilities.Andres Freund
pg_receivexlog and pg_recvlogical error out when --create-slot is specified and a slot with the same name already exists. In some cases, especially with pg_receivexlog, that's rather annoying and requires additional scripting. Backpatch to 9.5 as slot control functions have newly been added to pg_receivexlog, and there doesn't seem much point leaving it in a less useful state. Discussion: 20150619144755.GG29350@alap3.anarazel.de
2015-07-11doc: fix typo in CREATE POLICY manual pageBruce Momjian
Backpatch through 9.5
2015-07-10Copy-edit the docs changes of OWNER TO CURRENT/SESSION_USER additions.Heikki Linnakangas
Commit 31eae602 added new syntax to many DDL commands to use CURRENT_USER or SESSION_USER instead of role name in ALTER ... OWNER TO, but because of a misplaced '{', the syntax in the docs implied that the syntax was "ALTER ... CURRENT_USER", instead of "ALTER ... OWNER TO CURRENT_USER". Fix that, and also the funny indentation in some of the modified syntax blurps.
2015-07-06Remove incorrect warning from pg_archivecleanup document.Fujii Masao
The .backup file name can be passed to pg_archivecleanup even if it includes the extension which is specified in -x option. However, previously the document incorrectly warned a user not to do that. Back-patch to 9.2 where pg_archivecleanup's -x option and the warning were added.
2015-07-03Make WAL-related utilities handle .partial WAL files properly.Fujii Masao
Commit de76884 changed an archive recovery so that the last WAL segment with old timeline was renamed with suffix .partial. It should have updated WAL-related utilities so that they can handle such .paritial WAL files, but we forgot that. This patch changes pg_archivecleanup so that it can clean up even archived WAL files with .partial suffix. Also it allows us to specify .partial WAL file name as the command-line argument "oldestkeptwalfile". This patch also changes pg_resetxlog so that it can remove .partial WAL files in pg_xlog directory. pg_xlogdump cannot handle .partial WAL files. Per discussion, we decided only to document that limitation instead of adding the fix. Because a user can easily work around the limitation (i.e., just remove .partial suffix from the file name) and the fix seems complicated for very narrow use case. Back-patch to 9.5 where the problem existed. Review by Michael Paquier. Discussion: http://www.postgresql.org/message-id/CAHGQGwGxMKnVHGgTfiig2Bt_2djec0in3-DLJmtg7+nEiidFdQ@mail.gmail.com
2015-06-29Code + docs review for escaping of option values (commit 11a020eb6).Tom Lane
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.
2015-06-13doc: Add note to pg_dump man page about pg_dumpallPeter Eisentraut
suggested by Joshua Drake
2015-06-10doc: Use "connections" instead of "slots" to avoid confusionPeter Eisentraut
The text was written before replication slots existed, but now "slot" is best not used for anything else in the space of replication.
2015-06-10doc: Fix typoPeter Eisentraut
2015-06-04Remove -i/--ignore-version option from pg_dump, pg_dumpall and pg_restore.Fujii Masao
The commit c22ed3d523782c43836c163c16fa5a7bb3912826 turned the -i/--ignore-version options into no-ops and marked as deprecated. Considering we shipped that in 8.4, it's time to remove all trace of those switches, per discussion. We'd still have to wait a couple releases before it'd be safe to use -i for something else, but it'd be a start.
2015-05-23Remove the new UPSERT command tag and use INSERT instead.Andres Freund
Previously, INSERT with ON CONFLICT DO UPDATE specified used a new command tag -- UPSERT. It was introduced out of concern that INSERT as a command tag would be a misrepresentation for ON CONFLICT DO UPDATE, as some affected rows may actually have been updated. Alvaro Herrera noticed that the implementation of that new command tag was incomplete; in subsequent discussion we concluded that having it doesn't provide benefits that are in line with the compatibility breaks it requires. Catversion bump due to the removal of PlannedStmt->isUpsert. Author: Peter Geoghegan Discussion: 20150520215816.GI5885@postgresql.org
2015-05-22Minor enhancement of readability of ALTER TABLE syntax in the doc.Fujii Masao
Fabrízio Mello
2015-05-21Correct two mistakes in the ALTER FOREIGN TABLE reference page.Robert Haas
Etsuro Fujita
2015-05-20Collection of typo fixes.Heikki Linnakangas
Use "a" and "an" correctly, mostly in comments. Two error messages were also fixed (they were just elogs, so no translation work required). Two function comments in pg_proc.h were also fixed. Etsuro Fujita reported one of these, but I found a lot more with grep. Also fix a few other typos spotted while grepping for the a/an typos. For example, "consists out of ..." -> "consists of ...". Plus a "though"/ "through" mixup reported by Euler Taveira. Many of these typos were in old code, which would be nice to backpatch to make future backpatching easier. But much of the code was new, and I didn't feel like crafting separate patches for each branch. So no backpatching.
2015-05-17Fix wording error caused by recent typo fixesMagnus Hagander
It wasn't just a typo, but bad wording. This should make it more clear. Pointed out by Tom Lane.
2015-05-17Fix typos in commentsMagnus Hagander
Dmitriy Olshevskiy
2015-05-16Support GROUPING SETS, CUBE and ROLLUP.Andres Freund
This SQL standard functionality allows to aggregate data by different GROUP BY clauses at once. Each grouping set returns rows with columns grouped by in other sets set to NULL. This could previously be achieved by doing each grouping as a separate query, conjoined by UNION ALLs. Besides being considerably more concise, grouping sets will in many cases be faster, requiring only one scan over the underlying data. The current implementation of grouping sets only supports using sorting for input. Individual sets that share a sort order are computed in one pass. If there are sets that don't share a sort order, additional sort & aggregation steps are performed. These additional passes are sourced by the previous sort step; thus avoiding repeated scans of the source data. The code is structured in a way that adding support for purely using hash aggregation or a mix of hashing and sorting is possible. Sorting was chosen to be supported first, as it is the most generic method of implementation. Instead of, as in an earlier versions of the patch, representing the chain of sort and aggregation steps as full blown planner and executor nodes, all but the first sort are performed inside the aggregation node itself. This avoids the need to do some unusual gymnastics to handle having to return aggregated and non-aggregated tuples from underlying nodes, as well as having to shut down underlying nodes early to limit memory usage. The optimizer still builds Sort/Agg node to describe each phase, but they're not part of the plan tree, but instead additional data for the aggregation node. They're a convenient and preexisting way to describe aggregation and sorting. The first (and possibly only) sort step is still performed as a separate execution step. That retains similarity with existing group by plans, makes rescans fairly simple, avoids very deep plans (leading to slow explains) and easily allows to avoid the sorting step if the underlying data is sorted by other means. A somewhat ugly side of this patch is having to deal with a grammar ambiguity between the new CUBE keyword and the cube extension/functions named cube (and rollup). To avoid breaking existing deployments of the cube extension it has not been renamed, neither has cube been made a reserved keyword. Instead precedence hacking is used to make GROUP BY cube(..) refer to the CUBE grouping sets feature, and not the function cube(). To actually group by a function cube(), unlikely as that might be, the function name has to be quoted. Needs a catversion bump because stored rules may change. Author: Andrew Gierth and Atri Sharma, with contributions from Andres Freund Reviewed-By: Andres Freund, Noah Misch, Tom Lane, Svenne Krap, Tomas Vondra, Erik Rijkers, Marti Raudsepp, Pavel Stehule Discussion: CAOeZVidmVRe2jU6aMk_5qkxnB7dfmPROzM7Ur8JPW5j8Y5X-Lw@mail.gmail.com
2015-05-15doc: CREATE FOREIGN TABLE now allows CHECK ( ... ) NO INHERITRobert Haas
Etsuro Fujita
2015-05-15TABLESAMPLE, SQL Standard and extensibleSimon Riggs
Add a TABLESAMPLE clause to SELECT statements that allows user to specify random BERNOULLI sampling or block level SYSTEM sampling. Implementation allows for extensible sampling functions to be written, using a standard API. Basic version follows SQLStandard exactly. Usable concrete use cases for the sampling API follow in later commits. Petr Jelinek Reviewed by Michael Paquier and Simon Riggs
2015-05-15docs: consistently uppercase index method and add spacingBruce Momjian
Consistently uppercase index method names, e.g. GIN, and add space after the index method name and the parentheses enclosing the column names.
2015-05-15Support --verbose option in reindexdb.Fujii Masao
Sawada Masahiko, reviewed by Fabrízio Mello
2015-05-15Support VERBOSE option in REINDEX command.Fujii Masao
When this option is specified, a progress report is printed as each index is reindexed. Per discussion, we agreed on the following syntax for the extensibility of the options. REINDEX (flexible options) { INDEX | ... } name Sawada Masahiko. Reviewed by Robert Haas, Fabrízio Mello, Alvaro Herrera, Kyotaro Horiguchi, Jim Nasby and me. Discussion: CAD21AoA0pK3YcOZAFzMae+2fcc3oGp5zoRggDyMNg5zoaWDhdQ@mail.gmail.com
2015-05-12Map basebackup tablespaces using a tablespace_map fileAndrew Dunstan
Windows can't reliably restore symbolic links from a tar format, so instead during backup start we create a tablespace_map file, which is used by the restoring postgres to create the correct links in pg_tblspc. The backup protocol also now has an option to request this file to be included in the backup stream, and this is used by pg_basebackup when operating in tar mode. This is done on all platforms, not just Windows. This means that pg_basebackup will not not work in tar mode against 9.4 and older servers, as this protocol option isn't implemented there. Amit Kapila, reviewed by Dilip Kumar, with a little editing from me.
2015-05-11Allow LOCK TABLE .. ROW EXCLUSIVE MODE with INSERTStephen Frost
INSERT acquires RowExclusiveLock during normal operation and therefore it makes sense to allow LOCK TABLE .. ROW EXCLUSIVE MODE to be executed by users who have INSERT rights on a table (even if they don't have UPDATE or DELETE). Not back-patching this as it's a behavior change which, strictly speaking, loosens security restrictions. Per discussion with Tom and Robert (circa 2013).
2015-05-09Correct reindexdb documentationStephen Frost
--schema takes a schema, not a table. Author: Sawada Masahiko
2015-05-08Minor ON CONFLICT related comments and doc fixes.Andres Freund
Geoff Winkless, Stephen Frost, Peter Geoghegan and me.
2015-05-08Add support for INSERT ... ON CONFLICT DO NOTHING/UPDATE.Andres Freund
The newly added ON CONFLICT clause allows to specify an alternative to raising a unique or exclusion constraint violation error when inserting. ON CONFLICT refers to constraints that can either be specified using a inference clause (by specifying the columns of a unique constraint) or by naming a unique or exclusion constraint. DO NOTHING avoids the constraint violation, without touching the pre-existing row. DO UPDATE SET ... [WHERE ...] updates the pre-existing tuple, and has access to both the tuple proposed for insertion and the existing tuple; the optional WHERE clause can be used to prevent an update from being executed. The UPDATE SET and WHERE clauses have access to the tuple proposed for insertion using the "magic" EXCLUDED alias, and to the pre-existing tuple using the table name or its alias. This feature is often referred to as upsert. This is implemented using a new infrastructure called "speculative insertion". It is an optimistic variant of regular insertion that first does a pre-check for existing tuples and then attempts an insert. If a violating tuple was inserted concurrently, the speculatively inserted tuple is deleted and a new attempt is made. If the pre-check finds a matching tuple the alternative DO NOTHING or DO UPDATE action is taken. If the insertion succeeds without detecting a conflict, the tuple is deemed inserted. To handle the possible ambiguity between the excluded alias and a table named excluded, and for convenience with long relation names, INSERT INTO now can alias its target table. Bumps catversion as stored rules change. Author: Peter Geoghegan, with significant contributions from Heikki Linnakangas and Andres Freund. Testing infrastructure by Jeff Janes. Reviewed-By: Heikki Linnakangas, Andres Freund, Robert Haas, Simon Riggs, Dean Rasheed, Stephen Frost and many others.
2015-04-30Fix up some loose ends for CURRENT_USER as RoleSpecAlvaro Herrera
In commit 31eae6028eca4, some documents were not updated to show the new capability; fix that. Also, the error message you get when CURRENT_USER and SESSION_USER are used in a context that doesn't accept them could be clearer about it being a problem only in those contexts; so add the word "here". Author: Kyotaro HORIGUCHI His patch submission also included changes to GRANT/REVOKE, but those seemed more controversial, so I left them out. We can reconsider these changes later.
2015-04-26Add transforms featurePeter Eisentraut
This provides a mechanism for specifying conversions between SQL data types and procedural languages. As examples, there are transforms for hstore and ltree for PL/Perl and PL/Python. reviews by Pavel Stěhule and Andres Freund
2015-04-24Perform RLS WITH CHECK before constraints, etcStephen Frost
The RLS capability is built on top of the WITH CHECK OPTION system which was added for auto-updatable views, however, unlike WCOs on views (which are mandated by the SQL spec to not fire until after all other constraints and checks are done), it makes much more sense for RLS checks to happen earlier than constraint and uniqueness checks. This patch reworks the structure which holds the WCOs a bit to be explicitly either VIEW or RLS checks and the RLS-related checks are done prior to the constraint and uniqueness checks. This also allows better error reporting as we are now reporting when a violation is due to a WITH CHECK OPTION and when it's due to an RLS policy violation, which was independently noted by Craig Ringer as being confusing. The documentation is also updated to include a paragraph about when RLS WITH CHECK handling is performed, as there have been a number of questions regarding that and the documentation was previously silent on the matter. Author: Dean Rasheed, with some kabitzing and comment changes by me.
2015-04-24doc: Move ALTER TABLE IF EXISTS description to better placePeter Eisentraut
It was previously mixed in with the description of ALTER TABLE subcommands. Move it to the Parameters section, which is where it is on other reference pages. pointed out by Amit Langote
2015-04-21Move pg_xlogdump from contrib/ to src/bin/Peter Eisentraut
Reviewed-by: Michael Paquier <michael.paquier@gmail.com>
2015-04-20Move pg_test_timing from contrib/ to src/bin/Peter Eisentraut
Reviewed-by: Michael Paquier <michael.paquier@gmail.com>
2015-04-19Move pg_test_fsync from contrib/ to src/bin/Peter Eisentraut
Reviewed-by: Michael Paquier <michael.paquier@gmail.com>
2015-04-16pg_upgrade: document need for text search files to be copiedBruce Momjian
Report by CJ Estel Backpatch through 9.4
2015-04-14Move pg_upgrade from contrib/ to src/bin/Peter Eisentraut
Reviewed-by: Michael Paquier <michael.paquier@gmail.com>
2015-04-13Move pgbench from contrib/ to src/bin/Peter Eisentraut
Reviewed-by: Michael Paquier <michael.paquier@gmail.com>
2015-04-11Move pg_archivecleanup from contrib/ to src/bin/Peter Eisentraut
Reviewed-by: Michael Paquier <michael.paquier@gmail.com>
2015-04-09Remove obsolete FORCE option from REINDEX.Fujii Masao
FORCE option has been marked "obsolete" since very old version 7.4 but existed for backwards compatibility. Per discussion on pgsql-hackers, we concluded that it's no longer worth keeping supporting the option.
2015-04-05Reduce lock levels of some trigger DDL and add FKsSimon Riggs
Reduce lock levels to ShareRowExclusive for the following SQL CREATE TRIGGER (but not DROP or ALTER) ALTER TABLE ENABLE TRIGGER ALTER TABLE DISABLE TRIGGER ALTER TABLE … ADD CONSTRAINT FOREIGN KEY Original work by Simon Riggs, extracted and refreshed by Andreas Karlsson New test cases added by Andreas Karlsson Reviewed by Noah Misch, Andres Freund, Michael Paquier and Simon Riggs
2015-04-03Add log_min_autovacuum_duration per-table optionAlvaro Herrera
This is useful to control autovacuum log volume, for situations where monitoring only a set of tables is necessary. Author: Michael Paquier Reviewed by: A team led by Naoya Anzai (also including Akira Kurosawa, Taiki Kondo, Huong Dangminh), Fujii Masao.
2015-04-03Add markup for replaceable parameters to pg_rewind doc.Fujii Masao
2015-04-02psql: fix \connect with URIs and conninfo stringsAlvaro Herrera
This is the second try at this, after fcef1617295 failed miserably and had to be reverted: as it turns out, libpq cannot depend on libpgcommon after all. Instead of shuffling code in the master branch, make that one just like 9.4 and accept the duplication. (This was all my own mistake, not the patch submitter's). psql was already accepting conninfo strings as the first parameter in \connect, but the way it worked wasn't sane; some of the other parameters would get the previous connection's values, causing it to connect to a completely unexpected server or, more likely, not finding any server at all because of completely wrong combinations of parameters. Fix by explicitely checking for a conninfo-looking parameter in the dbname position; if one is found, use its complete specification rather than mix with the other arguments. Also, change tab-completion to not try to complete conninfo/URI-looking "dbnames" and document that conninfos are accepted as first argument. There was a weak consensus to backpatch this, because while the behavior of using the dbname as a conninfo is nowhere documented for \connect, it is reasonable to expect that it works because it does work in many other contexts. Therefore this is backpatched all the way back to 9.0. Author: David Fetter, Andrew Dunstan. Some editorialization by me (probably earning a Gierth's "Sloppy" badge in the process.) Reviewers: Andrew Gierth, Erik Rijkers, Pavel Stěhule, Stephen Frost, Robert Haas, Andrew Dunstan.
2015-04-02Revert "psql: fix \connect with URIs and conninfo strings"Robert Haas
This reverts commit fcef1617295c074f2684c887627184d2fc26ac04, about which both the buildfarm and my local machine are very unhappy.
2015-04-01psql: fix \connect with URIs and conninfo stringsAlvaro Herrera
psql was already accepting conninfo strings as the first parameter in \connect, but the way it worked wasn't sane; some of the other parameters would get the previous connection's values, causing it to connect to a completely unexpected server or, more likely, not finding any server at all because of completely wrong combinations of parameters. Fix by explicitely checking for a conninfo-looking parameter in the dbname position; if one is found, use its complete specification rather than mix with the other arguments. Also, change tab-completion to not try to complete conninfo/URI-looking "dbnames" and document that conninfos are accepted as first argument. There was a weak consensus to backpatch this, because while the behavior of using the dbname as a conninfo is nowhere documented for \connect, it is reasonable to expect that it works because it does work in many other contexts. Therefore this is backpatched all the way back to 9.0. To implement this, routines previously private to libpq have been duplicated so that psql can decide what looks like a conninfo/URI string. In back branches, just duplicate the same code all the way back to 9.2, where URIs where introduced; 9.0 and 9.1 have a simpler version. In master, the routines are moved to src/common and renamed. Author: David Fetter, Andrew Dunstan. Some editorialization by me (probably earning a Gierth's "Sloppy" badge in the process.) Reviewers: Andrew Gierth, Erik Rijkers, Pavel Stěhule, Stephen Frost, Robert Haas, Andrew Dunstan.