From 980a855c5c2e21e964a739694e24004f72e03fdf Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Sat, 8 Nov 2025 09:49:43 -0500 Subject: [PATCH] doc: consistently use "structname" and "structfield" markup Previously "literal" and "classname" were used, inconsistently, for SQL table and column names. Reported-by: Peter Smith Author: Peter Smith Discussion: https://postgr.es/m/CAHut+Pvtf24r+bdPgBind84dBLPvgNL7aB+=HxAUupdPuo2gRg@mail.gmail.com Backpatch-through: master --- doc/src/sgml/advanced.sgml | 26 ++++++++-------- doc/src/sgml/ddl.sgml | 6 ++-- doc/src/sgml/ecpg.sgml | 2 +- doc/src/sgml/func/func-json.sgml | 4 +-- doc/src/sgml/indices.sgml | 32 +++++++++---------- doc/src/sgml/information_schema.sgml | 36 +++++++++++----------- doc/src/sgml/libpq.sgml | 4 +-- doc/src/sgml/logical-replication.sgml | 26 ++++++++-------- doc/src/sgml/plperl.sgml | 8 ++--- doc/src/sgml/queries.sgml | 6 ++-- doc/src/sgml/ref/cluster.sgml | 4 +-- doc/src/sgml/ref/comment.sgml | 2 +- doc/src/sgml/ref/create_foreign_table.sgml | 2 +- doc/src/sgml/ref/create_function.sgml | 4 +-- doc/src/sgml/ref/create_index.sgml | 14 ++++----- doc/src/sgml/ref/create_table.sgml | 2 +- doc/src/sgml/ref/create_table_as.sgml | 8 ++--- doc/src/sgml/ref/create_trigger.sgml | 10 +++--- doc/src/sgml/ref/create_view.sgml | 16 +++++----- doc/src/sgml/ref/delete.sgml | 2 +- doc/src/sgml/ref/grant.sgml | 6 ++-- doc/src/sgml/ref/insert.sgml | 26 ++++++++-------- doc/src/sgml/ref/pg_dump.sgml | 2 +- doc/src/sgml/ref/psql-ref.sgml | 2 +- doc/src/sgml/ref/reindex.sgml | 2 +- doc/src/sgml/ref/reindexdb.sgml | 2 +- doc/src/sgml/ref/select.sgml | 18 +++++------ doc/src/sgml/ref/select_into.sgml | 4 +-- doc/src/sgml/ref/truncate.sgml | 8 ++--- doc/src/sgml/ref/vacuum.sgml | 2 +- doc/src/sgml/rules.sgml | 36 +++++++++++----------- doc/src/sgml/syntax.sgml | 4 +-- doc/src/sgml/xfunc.sgml | 6 ++-- 33 files changed, 166 insertions(+), 166 deletions(-) diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index 82e82c13457..451bcb202ec 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -80,18 +80,18 @@ SELECT * FROM myview; - Recall the weather and - cities tables from weather and + cities tables from . Consider the following problem: You want to make sure that no one can insert rows in the - weather table that do not have a matching - entry in the cities table. This is called + weather table that do not have a matching + entry in the cities table. This is called maintaining the referential integrity of your data. In simplistic database systems this would be implemented (if at all) by first looking at the - cities table to check if a matching record + cities table to check if a matching record exists, and then inserting or rejecting the new - weather records. This approach has a + weather records. This approach has a number of problems and is very inconvenient, so PostgreSQL can do this for you. @@ -578,8 +578,8 @@ SELECT sum(salary) OVER w, avg(salary) OVER w - Let's create two tables: A table cities - and a table capitals. Naturally, capitals + Let's create two tables: A table cities + and a table capitals. Naturally, capitals are also cities, so you want some way to show the capitals implicitly when you list all cities. If you're really clever you might invent some scheme like this: @@ -625,14 +625,14 @@ CREATE TABLE capitals ( - In this case, a row of capitals + In this case, a row of capitals inherits all columns (name, population, and elevation) from its - parent, cities. The + parent, cities. The type of the column name is text, a native PostgreSQL type for variable length character strings. The - capitals table has + capitals table has an additional column, state, which shows its state abbreviation. In PostgreSQL, a table can inherit from @@ -685,8 +685,8 @@ SELECT name, elevation Here the ONLY before cities indicates that the query should be run over only the - cities table, and not tables below - cities in the inheritance hierarchy. Many + cities table, and not tables below + cities in the inheritance hierarchy. Many of the commands that we have already discussed — SELECT, UPDATE, and DELETE — support this ONLY diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index 3e5fb590593..948b9327f24 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -1353,7 +1353,7 @@ CREATE TABLE posts ( ); Without the specification of the column, the foreign key would also set - the column tenant_id to null, but that column is still + the column tenant_id to null, but that column is still required as part of the primary key. @@ -2831,7 +2831,7 @@ REVOKE ALL ON accounts FROM PUBLIC; As an example, suppose that user miriam creates - table mytable and does: + table mytable and does: GRANT SELECT ON mytable TO PUBLIC; GRANT SELECT, UPDATE, INSERT ON mytable TO admin; @@ -3059,7 +3059,7 @@ CREATE POLICY user_mod_policy ON users Below is a larger example of how this feature can be used in production - environments. The table passwd emulates a Unix password + environments. The table passwd emulates a Unix password file: diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index df3965ec93f..807dadcb4a3 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -1827,7 +1827,7 @@ while (1) in . The following example inserts the complex type values (1,1) and (3,3) into the - columns a and b, and select + columns a and b, and select them from the table after that. diff --git a/doc/src/sgml/func/func-json.sgml b/doc/src/sgml/func/func-json.sgml index c529ddf1808..1ec73cff464 100644 --- a/doc/src/sgml/func/func-json.sgml +++ b/doc/src/sgml/func/func-json.sgml @@ -3899,8 +3899,8 @@ SELECT jt.* FROM NESTED paths $.movies[*] and $.books[*] and also the usage of FOR ORDINALITY column at NESTED - levels (columns movie_id, book_id, - and author_id): + levels (columns movie_id, book_id, + and author_id): SELECT * FROM JSON_TABLE ( diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index 6469f032f23..55f39b0df2f 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -593,7 +593,7 @@ CREATE INDEX test2_mm_idx ON test2 (major, minor); By default, B-tree indexes store their entries in ascending order with nulls last (table TID is treated as a tiebreaker column among otherwise equal entries). This means that a forward scan of an - index on column x produces output satisfying ORDER BY x + index on column x produces output satisfying ORDER BY x (or more verbosely, ORDER BY x ASC NULLS LAST). The index can also be scanned backward, producing output satisfying ORDER BY x DESC @@ -698,23 +698,23 @@ CREATE INDEX test3_desc_index ON test3 (id DESC NULLS LAST); indexes are best, but sometimes it's better to create separate indexes and rely on the index-combination feature. For example, if your workload includes a mix of queries that sometimes involve only column - x, sometimes only column y, and sometimes both + x, sometimes only column y, and sometimes both columns, you might choose to create two separate indexes on - x and y, relying on index combination to + x and y, relying on index combination to process the queries that use both columns. You could also create a multicolumn index on (x, y). This index would typically be more efficient than index combination for queries involving both columns, but as discussed in , it would be less useful for queries involving only y. Just how useful will depend on how effective the B-tree index skip scan - optimization is; if x has no more than several hundred + optimization is; if x has no more than several hundred distinct values, skip scan will make searches for specific - y values execute reasonably efficiently. A combination + y values execute reasonably efficiently. A combination of a multicolumn index on (x, y) and a separate index on - y might also serve reasonably well. For - queries involving only x, the multicolumn index could be + y might also serve reasonably well. For + queries involving only x, the multicolumn index could be used, though it would be larger and hence slower than an index on - x alone. The last alternative is to create all three + x alone. The last alternative is to create all three indexes, but this is probably only reasonable if the table is searched much more often than it is updated and all three types of query are common. If one of the types of query is much less common than the @@ -1179,9 +1179,9 @@ CREATE INDEX mytable_cat_data ON mytable (category, data); The query must reference only columns stored in the index. For - example, given an index on columns x - and y of a table that also has a - column z, these queries could use index-only scans: + example, given an index on columns x + and y of a table that also has a + column z, these queries could use index-only scans: SELECT x, y FROM tab WHERE x = 'key'; SELECT x FROM tab WHERE x = 'key' AND y < 42; @@ -1262,15 +1262,15 @@ CREATE INDEX tab_x_y ON tab(x) INCLUDE (y); - Because column y is not part of the index's search + Because column y is not part of the index's search key, it does not have to be of a data type that the index can handle; it's merely stored in the index and is not interpreted by the index machinery. Also, if the index is a unique index, that is CREATE UNIQUE INDEX tab_x_y ON tab(x) INCLUDE (y); - the uniqueness condition applies to just column x, - not to the combination of x and y. + the uniqueness condition applies to just column x, + not to the combination of x and y. (An INCLUDE clause can also be written in UNIQUE and PRIMARY KEY constraints, providing alternative syntax for setting up an index like @@ -1300,7 +1300,7 @@ CREATE UNIQUE INDEX tab_x_y ON tab(x) INCLUDE (y); CREATE INDEX tab_x_y ON tab(x, y); - even though they had no intention of ever using y as + even though they had no intention of ever using y as part of a WHERE clause. This works fine as long as the extra columns are trailing columns; making them be leading columns is unwise for the reasons explained in . @@ -1340,7 +1340,7 @@ SELECT f(x) FROM tab WHERE f(x) < 1; context f(x), but the planner does not notice that and concludes that an index-only scan is not possible. If an index-only scan seems sufficiently worthwhile, this can be worked around by - adding x as an included column, for example + adding x as an included column, for example CREATE INDEX tab_f_x ON tab (f(x)) INCLUDE (x); diff --git a/doc/src/sgml/information_schema.sgml b/doc/src/sgml/information_schema.sgml index 19dffe7be6a..60b4c4ae8c0 100644 --- a/doc/src/sgml/information_schema.sgml +++ b/doc/src/sgml/information_schema.sgml @@ -2089,15 +2089,15 @@ Since data types can be defined in a variety of ways in SQL, and PostgreSQL contains additional ways to define data types, their representation in the information schema - can be somewhat difficult. The column data_type + can be somewhat difficult. The column data_type is supposed to identify the underlying built-in type of the column. In PostgreSQL, this means that the type is defined in the system catalog schema pg_catalog. This column might be useful if the application can handle the well-known built-in types specially (for example, format the numeric types differently or use the data in - the precision columns). The columns udt_name, - udt_schema, and udt_catalog + the precision columns). The columns udt_name, + udt_schema, and udt_catalog always identify the underlying data type of the column, even if the column is based on a domain. (Since PostgreSQL treats built-in types like @@ -2107,8 +2107,8 @@ type, because in that case it wouldn't matter if the column is really based on a domain. If the column is based on a domain, the identity of the domain is stored in the columns - domain_name, domain_schema, - and domain_catalog. If you want to pair up + domain_name, domain_schema, + and domain_catalog. If you want to pair up columns with their associated data types and treat domains as separate types, you could write coalesce(domain_name, udt_name), etc. @@ -6376,7 +6376,7 @@ ORDER BY c.ordinal_position; the sequence data type (see above). The precision indicates the number of significant digits. It can be expressed in decimal (base 10) or binary (base 2) terms, as specified in the - column numeric_precision_radix. + column numeric_precision_radix. @@ -6386,8 +6386,8 @@ ORDER BY c.ordinal_position; This column indicates in which base the values in the columns - numeric_precision and - numeric_scale are expressed. The value is + numeric_precision and + numeric_scale are expressed. The value is either 2 or 10. @@ -6402,7 +6402,7 @@ ORDER BY c.ordinal_position; of significant digits to the right of the decimal point. It can be expressed in decimal (base 10) or binary (base 2) terms, as specified in the column - numeric_precision_radix. + numeric_precision_radix. @@ -6461,10 +6461,10 @@ ORDER BY c.ordinal_position; - <literal>sql_features</literal> + <structname>sql_features</structname> - The table sql_features contains information + The table sql_features contains information about which formal features defined in the SQL standard are supported by PostgreSQL. This is the same information that is presented in . @@ -6556,10 +6556,10 @@ ORDER BY c.ordinal_position; - <literal>sql_implementation_info</literal> + <structname>sql_implementation_info</structname> - The table sql_implementation_info contains + The table sql_implementation_info contains information about various aspects that are left implementation-defined by the SQL standard. This information is primarily intended for use in the context of the ODBC interface; @@ -6638,10 +6638,10 @@ ORDER BY c.ordinal_position; - <literal>sql_parts</literal> + <structname>sql_parts</structname> - The table sql_parts contains information about + The table sql_parts contains information about which of the several parts of the SQL standard are supported by PostgreSQL. @@ -6714,10 +6714,10 @@ ORDER BY c.ordinal_position; - <literal>sql_sizing</literal> + <structname>sql_sizing</structname> - The table sql_sizing contains information about + The table sql_sizing contains information about various size limits and maximum values in PostgreSQL. This information is primarily intended for use in the context of the ODBC interface; @@ -7843,7 +7843,7 @@ ORDER BY c.ordinal_position; in PostgreSQL) and distinct types (not implemented in PostgreSQL). To be future-proof, use the - column user_defined_type_category to + column user_defined_type_category to differentiate between these. Other user-defined types such as base types and enums, which are PostgreSQL extensions, are not shown here. For domains, diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 1c5ae9ad08f..7ab679a765d 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -4508,7 +4508,7 @@ Oid PQftable(const PGresult *res, InvalidOid is returned if the column number is out of range, or if the specified column is not a simple reference to a table column. - You can query the system table pg_class to determine + You can query the system table pg_class to determine exactly which table is referenced. @@ -4578,7 +4578,7 @@ Oid PQftype(const PGresult *res, - You can query the system table pg_type to + You can query the system table pg_type to obtain the names and properties of the various data types. The OIDs of the built-in data types are defined in the file catalog/pg_type_d.h diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml index daab2cae989..d64ed9dc36b 100644 --- a/doc/src/sgml/logical-replication.sgml +++ b/doc/src/sgml/logical-replication.sgml @@ -439,7 +439,7 @@ Furthermore, because the initial data copy ignores the publish operation, and because publication pub3a has no row filter, - it means the copied table t3 contains all rows even when + it means the copied table t3 contains all rows even when they do not match the row filter of publication pub3b. /* sub # */ SELECT * FROM t3; @@ -1036,8 +1036,8 @@ HINT: To initiate replication, you must manually create the replication slot, e Create some publications. Publication p1 has one table (t1) and that table has a row filter. Publication - p2 has two tables. Table t1 has no row - filter, and table t2 has a row filter. Publication + p2 has two tables. Table t1 has no row + filter, and table t2 has a row filter. Publication p3 has two tables, and both of them have a row filter. 5 AND c = 'NSW'); @@ -1076,9 +1076,9 @@ Tables: psql can be used to show the row filter expressions (if - defined) for each table. See that table t1 is a member + defined) for each table. See that table t1 is a member of two publications, but has a row filter only in p1. - See that table t2 is a member of two publications, and + See that table t2 is a member of two publications, and has a different row filter in each of them. - On the subscriber node, create a table t1 with the same + On the subscriber node, create a table t1 with the same definition as the one on the publisher, and also create the subscription s1 that subscribes to the publication p1. @@ -1474,14 +1474,14 @@ Publications: Examples - Create a table t1 to be used in the following example. + Create a table t1 to be used in the following example. /* pub # */ CREATE TABLE t1(id int, a text, b text, c text, d text, e text, PRIMARY KEY(id)); Create a publication p1. A column list is defined for - table t1 to reduce the number of columns that will be + table t1 to reduce the number of columns that will be replicated. Notice that the order of column names in the column list does not matter. @@ -1522,9 +1522,9 @@ Publications: - On the subscriber node, create a table t1 which now + On the subscriber node, create a table t1 which now only needs a subset of the columns that were on the publisher table - t1, and also create the subscription + t1, and also create the subscription s1 that subscribes to the publication p1. @@ -1535,7 +1535,7 @@ Publications: - On the publisher node, insert some rows to table t1. + On the publisher node, insert some rows to table t1. /* pub # */ INSERT INTO t1 VALUES(1, 'a-1', 'b-1', 'c-1', 'd-1', 'e-1'); /* pub # */ INSERT INTO t1 VALUES(2, 'a-2', 'b-2', 'c-2', 'd-2', 'e-2'); @@ -3285,8 +3285,8 @@ CREATE SUBSCRIPTION mysub CONNECTION 'dbname=foo host=bar user=repuser' PUBLICAT The above will start the replication process, which synchronizes the - initial table contents of the tables users and - departments and then starts replicating + initial table contents of the tables users and + departments and then starts replicating incremental changes to those tables. diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml index 011b9792325..6f018645f11 100644 --- a/doc/src/sgml/plperl.sgml +++ b/doc/src/sgml/plperl.sgml @@ -468,8 +468,8 @@ optional maximum number of rows: $rv = spi_exec_query('SELECT * FROM my_table', 5); This returns up to 5 rows from the table - my_table. If my_table - has a column my_column, you can get that + my_table. If my_table + has a column my_column, you can get that value from row $i of the result like this: $foo = $rv->{rows}[$i]->{my_column}; @@ -1199,7 +1199,7 @@ $$ LANGUAGE plperl; $_TD->{new}{foo} - NEW value of column foo + NEW value of column foo @@ -1208,7 +1208,7 @@ $$ LANGUAGE plperl; $_TD->{old}{foo} - OLD value of column foo + OLD value of column foo diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index 8d5ba72a198..4b522213171 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -410,7 +410,7 @@ FROM table_reference , table_r - To put this together, assume we have tables t1: + To put this together, assume we have tables t1: num | name -----+------ @@ -418,7 +418,7 @@ FROM table_reference , table_r 2 | b 3 | c - and t2: + and t2: num | value -----+------- @@ -1079,7 +1079,7 @@ SELECT select_list In the second query, we could not have written SELECT * FROM test1 GROUP BY x, because there is no single value - for the column y that could be associated with each + for the column y that could be associated with each group. The grouped-by columns can be referenced in the select list since they have a single value in each group. diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml index 8811f169ea0..0b47460080b 100644 --- a/doc/src/sgml/ref/cluster.sgml +++ b/doc/src/sgml/ref/cluster.sgml @@ -220,7 +220,7 @@ CLUSTER [ ( option [, ...] ) ] [ Examples - Cluster the table employees on the basis of + Cluster the table employees on the basis of its index employees_ind: CLUSTER employees USING employees_ind; @@ -228,7 +228,7 @@ CLUSTER employees USING employees_ind; - Cluster the employees table using the same + Cluster the employees table using the same index that was used before: CLUSTER employees; diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml index 5b43c56b133..8d81244910b 100644 --- a/doc/src/sgml/ref/comment.sgml +++ b/doc/src/sgml/ref/comment.sgml @@ -301,7 +301,7 @@ COMMENT ON Examples - Attach a comment to the table mytable: + Attach a comment to the table mytable: COMMENT ON TABLE mytable IS 'This is my table.'; diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml index 009fa46532b..08a8ceeae75 100644 --- a/doc/src/sgml/ref/create_foreign_table.sgml +++ b/doc/src/sgml/ref/create_foreign_table.sgml @@ -360,7 +360,7 @@ WITH ( MODULUS numeric_literal, REM Currently, CHECK expressions cannot contain subqueries nor refer to variables other than columns of the - current row. The system column tableoid + current row. The system column tableoid may be referenced, but not any other system column. diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index e748e842353..30bd4602f8d 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -817,10 +817,10 @@ $$ LANGUAGE plpgsql SET search_path = admin, pg_temp; - This function's intention is to access a table admin.pwds. + This function's intention is to access a table admin.pwds. But without the SET clause, or with a SET clause mentioning only admin, the function could be subverted by - creating a temporary table named pwds. + creating a temporary table named pwds. diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index b9c679c41e8..bb7505d171b 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -898,17 +898,17 @@ Indexes: Examples - To create a unique B-tree index on the column title in - the table films: + To create a unique B-tree index on the column title in + the table films: CREATE UNIQUE INDEX title_idx ON films (title); - To create a unique B-tree index on the column title - with included columns director - and rating in the table films: + To create a unique B-tree index on the column title + with included columns director + and rating in the table films: CREATE UNIQUE INDEX title_idx ON films (title) INCLUDE (director, rating); @@ -960,8 +960,8 @@ CREATE INDEX gin_idx ON documents_table USING GIN (locations) WITH (fastupdate = - To create an index on the column code in the table - films and have the index reside in the tablespace + To create an index on the column code in the table + films and have the index reside in the tablespace indexspace: CREATE INDEX code_idx ON films (code) TABLESPACE indexspace; diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 94093599ca2..6557c5cffd8 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -862,7 +862,7 @@ WITH ( MODULUS numeric_literal, REM Currently, CHECK expressions cannot contain subqueries nor refer to variables other than columns of the current row (see ). - The system column tableoid + The system column tableoid may be referenced, but not any other system column. diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml index 8429333e3af..6b41226cbd6 100644 --- a/doc/src/sgml/ref/create_table_as.sgml +++ b/doc/src/sgml/ref/create_table_as.sgml @@ -266,8 +266,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI Examples - Create a new table films_recent consisting of only - recent entries from the table films: + Create a new table films_recent consisting of only + recent entries from the table films: CREATE TABLE films_recent AS @@ -286,8 +286,8 @@ CREATE TABLE films2 AS - Create a new temporary table films_recent, consisting of - only recent entries from the table films, using a + Create a new temporary table films_recent, consisting of + only recent entries from the table films, using a prepared statement. The new table will be dropped at commit: diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml index 0d8d463479b..bb1426f4970 100644 --- a/doc/src/sgml/ref/create_trigger.sgml +++ b/doc/src/sgml/ref/create_trigger.sgml @@ -485,7 +485,7 @@ UPDATE OF column_name1 [, column_name2BEFORE UPDATE triggers are not considered. Conversely, a command such as UPDATE ... SET x = x ... - will fire a trigger on column x, even though the column's + will fire a trigger on column x, even though the column's value did not change. @@ -598,7 +598,7 @@ UPDATE OF column_name1 [, column_name2 Execute the function check_account_update whenever - a row of the table accounts is about to be updated: + a row of the table accounts is about to be updated: CREATE TRIGGER check_update @@ -608,7 +608,7 @@ CREATE TRIGGER check_update Modify that trigger definition to only execute the function if - column balance is specified as a target in + column balance is specified as a target in the UPDATE command: @@ -618,7 +618,7 @@ CREATE OR REPLACE TRIGGER check_update EXECUTE FUNCTION check_account_update(); - This form only executes the function if column balance + This form only executes the function if column balance has in fact changed value: @@ -629,7 +629,7 @@ CREATE TRIGGER check_update EXECUTE FUNCTION check_account_update(); - Call a function to log updates of accounts, but only if + Call a function to log updates of accounts, but only if something changed: diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml index e8d9d3c8d0f..7b6b750c6de 100644 --- a/doc/src/sgml/ref/create_view.sgml +++ b/doc/src/sgml/ref/create_view.sgml @@ -492,7 +492,7 @@ CREATE VIEW comedies AS WHERE kind = 'Comedy'; This will create a view containing the columns that are in the - film table at the time of view creation. Though + film table at the time of view creation. Though * was used to create the view, columns added later to the table will not be part of the view. @@ -507,12 +507,12 @@ CREATE VIEW universal_comedies AS WHERE classification = 'U' WITH LOCAL CHECK OPTION; - This will create a view based on the comedies view, showing + This will create a view based on the comedies view, showing only films with kind = 'Comedy' and classification = 'U'. Any attempt to INSERT or UPDATE a row in the view will be rejected if the new row doesn't have classification = 'U', but the film - kind will not be checked. + kind will not be checked. @@ -525,8 +525,8 @@ CREATE VIEW pg_comedies AS WHERE classification = 'PG' WITH CASCADED CHECK OPTION; - This will create a view that checks both the kind and - classification of new rows. + This will create a view that checks both the kind and + classification of new rows. @@ -543,9 +543,9 @@ CREATE VIEW comedies AS WHERE f.kind = 'Comedy'; This view will support INSERT, UPDATE and - DELETE. All the columns from the films table will - be updatable, whereas the computed columns country and - avg_rating will be read-only. + DELETE. All the columns from the films table will + be updatable, whereas the computed columns country and + avg_rating will be read-only. diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index 29649f6afd6..5b52f77e28f 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -285,7 +285,7 @@ DELETE FROM films WHERE kind <> 'Musical'; - Clear the table films: + Clear the table films: DELETE FROM films; diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index 999f657d5c0..043f5d5a40a 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -434,7 +434,7 @@ GRANT role_name [, ...] TO Examples - Grant insert privilege to all users on table films: + Grant insert privilege to all users on table films: GRANT INSERT ON films TO PUBLIC; @@ -443,14 +443,14 @@ GRANT INSERT ON films TO PUBLIC; Grant all available privileges to user manuel on view - kinds: + kinds: GRANT ALL PRIVILEGES ON kinds TO manuel; Note that while the above will indeed grant all privileges if executed by a - superuser or the owner of kinds, when executed by someone + superuser or the owner of kinds, when executed by someone else it will only grant those permissions for which the someone else has grant options. diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml index b337f2ee555..0598b8dea34 100644 --- a/doc/src/sgml/ref/insert.sgml +++ b/doc/src/sgml/ref/insert.sgml @@ -654,7 +654,7 @@ INSERT oid countExamples - Insert a single row into table films: + Insert a single row into table films: INSERT INTO films VALUES @@ -663,7 +663,7 @@ INSERT INTO films VALUES - In this example, the len column is + In this example, the len column is omitted and therefore it will have the default value: @@ -704,8 +704,8 @@ INSERT INTO films (code, title, did, date_prod, kind) VALUES This example inserts some rows into table - films from a table tmp_films - with the same column layout as films: + films from a table tmp_films + with the same column layout as films: INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07'; @@ -726,7 +726,7 @@ INSERT INTO tictactoe (game, board) - Insert a single row into table distributors, returning + Insert a single row into table distributors, returning the sequence number generated by the DEFAULT clause: @@ -751,8 +751,8 @@ INSERT INTO employees_log SELECT *, current_timestamp FROM upd; Insert or update new distributors as appropriate. Assumes a unique index has been defined that constrains values appearing in the - did column. Note that the special - excluded table is used to reference values originally + did column. Note that the special + excluded table is used to reference values originally proposed for insertion: INSERT INTO distributors (did, dname) @@ -763,8 +763,8 @@ INSERT INTO distributors (did, dname) Insert or update new distributors as above, returning information about any existing values that were updated, together with the new data - inserted. Note that the returned values for old_did - and old_dname will be NULL for + inserted. Note that the returned values for old_did + and old_dname will be NULL for non-conflicting rows: INSERT INTO distributors (did, dname) @@ -779,7 +779,7 @@ INSERT INTO distributors (did, dname) when an existing, excluded row (a row with a matching constrained column or columns after before row insert triggers fire) exists. Example assumes a unique index has been defined that constrains - values appearing in the did column: + values appearing in the did column: INSERT INTO distributors (did, dname) VALUES (7, 'Redline GmbH') ON CONFLICT (did) DO NOTHING; @@ -788,7 +788,7 @@ INSERT INTO distributors (did, dname) VALUES (7, 'Redline GmbH') Insert or update new distributors as appropriate. Example assumes a unique index has been defined that constrains values appearing in - the did column. WHERE clause is + the did column. WHERE clause is used to limit the rows actually updated (any existing row not updated will still be locked, though): @@ -808,8 +808,8 @@ INSERT INTO distributors (did, dname) VALUES (9, 'Antwerp Design') Insert new distributor if possible; otherwise DO NOTHING. Example assumes a unique index has been defined that constrains values appearing in the - did column on a subset of rows where the - is_active Boolean column evaluates to + did column on a subset of rows where the + is_active Boolean column evaluates to true: -- This statement could infer a partial unique index on "did" diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index 5ac3f3e8510..ae7718e1a93 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1878,7 +1878,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; To dump all tables whose names start with mytable, except - for table mytable2, specify a filter file + for table mytable2, specify a filter file filter.txt like: include table mytable* diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 1ab427d18af..f56c70263e0 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -4859,7 +4859,7 @@ bar testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; - would query the table my_table. Note that this + would query the table my_table. Note that this may be unsafe: the value of the variable is copied literally, so it can contain unbalanced quotes, or even backslash commands. You must make sure that it makes sense where you put it. diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index c4055397146..185cd75ca30 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -528,7 +528,7 @@ REINDEX INDEX my_index; - Rebuild all the indexes on the table my_table: + Rebuild all the indexes on the table my_table: REINDEX TABLE my_table; diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml index abcb041179b..a90e48ea86b 100644 --- a/doc/src/sgml/ref/reindexdb.sgml +++ b/doc/src/sgml/ref/reindexdb.sgml @@ -433,7 +433,7 @@ PostgreSQL documentation - To reindex the table foo and the index + To reindex the table foo and the index bar in a database named abcd: $ reindexdb --table=foo --index=bar abcd diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index fd441ef4487..ca5dd14d627 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -1768,8 +1768,8 @@ SELECT * FROM name Examples - To join the table films with the table - distributors: + To join the table films with the table + distributors: SELECT f.title, f.did, d.name, f.date_prod, f.kind @@ -1784,8 +1784,8 @@ SELECT f.title, f.did, d.name, f.date_prod, f.kind - To sum the column len of all films and group - the results by kind: + To sum the column len of all films and group + the results by kind: SELECT kind, sum(len) AS total FROM films GROUP BY kind; @@ -1801,8 +1801,8 @@ SELECT kind, sum(len) AS total FROM films GROUP BY kind; - To sum the column len of all films, group - the results by kind and show those group totals + To sum the column len of all films, group + the results by kind and show those group totals that are less than 5 hours: @@ -1821,7 +1821,7 @@ SELECT kind, sum(len) AS total The following two examples are identical ways of sorting the individual results according to the contents of the second column - (name): + (name): SELECT * FROM distributors ORDER BY name; @@ -1847,8 +1847,8 @@ SELECT * FROM distributors ORDER BY 2; The next example shows how to obtain the union of the tables - distributors and - actors, restricting the results to those that begin + distributors and + actors, restricting the results to those that begin with the letter W in each table. Only distinct rows are wanted, so the key word ALL is omitted. diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml index 233f9bfa284..cbf865ff838 100644 --- a/doc/src/sgml/ref/select_into.sgml +++ b/doc/src/sgml/ref/select_into.sgml @@ -120,8 +120,8 @@ SELECT [ ALL | DISTINCT [ ON ( expressionExamples - Create a new table films_recent consisting of only - recent entries from the table films: + Create a new table films_recent consisting of only + recent entries from the table films: SELECT * INTO films_recent FROM films WHERE date_prod >= '2002-01-01'; diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml index 9d846f88c9f..d6efa286e99 100644 --- a/doc/src/sgml/ref/truncate.sgml +++ b/doc/src/sgml/ref/truncate.sgml @@ -182,8 +182,8 @@ TRUNCATE [ TABLE ] [ ONLY ] name [ Examples - Truncate the tables bigtable and - fattable: + Truncate the tables bigtable and + fattable: TRUNCATE bigtable, fattable; @@ -199,8 +199,8 @@ TRUNCATE bigtable, fattable RESTART IDENTITY; - Truncate the table othertable, and cascade to any tables - that reference othertable via foreign-key + Truncate the table othertable, and cascade to any tables + that reference othertable via foreign-key constraints: diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index bd5dcaf86a5..6d0fdd43cfb 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -512,7 +512,7 @@ VACUUM [ ( option [, ...] ) ] [ Examples - To clean a single table onek, analyze it for + To clean a single table onek, analyze it for the optimizer and print a detailed vacuum activity report: diff --git a/doc/src/sgml/rules.sgml b/doc/src/sgml/rules.sgml index 50ac9bd4bdb..7f23962f524 100644 --- a/doc/src/sgml/rules.sgml +++ b/doc/src/sgml/rules.sgml @@ -662,8 +662,8 @@ SELECT shoe_ready.shoename, shoe_ready.sh_avail, command other than a SELECT, the result relation points to the range-table entry where the result should go. Everything else is absolutely the same. So having two tables - t1 and t2 with columns a and - b, the query trees for the two statements: + t1 and t2 with columns a and + b, the query trees for the two statements: SELECT t2.b FROM t1, t2 WHERE t1.a = t2.a; @@ -676,27 +676,27 @@ UPDATE t1 SET b = t2.b FROM t2 WHERE t1.a = t2.a; - The range tables contain entries for the tables t1 and t2. + The range tables contain entries for the tables t1 and t2. The target lists contain one variable that points to column - b of the range table entry for table t2. + b of the range table entry for table t2. - The qualification expressions compare the columns a of both + The qualification expressions compare the columns a of both range-table entries for equality. - The join trees show a simple join between t1 and t2. + The join trees show a simple join between t1 and t2. @@ -705,7 +705,7 @@ UPDATE t1 SET b = t2.b FROM t2 WHERE t1.a = t2.a; The consequence is, that both query trees result in similar execution plans: They are both joins over the two tables. For the - UPDATE the missing columns from t1 are added to + UPDATE the missing columns from t1 are added to the target list by the planner and the final query tree will read as: @@ -727,7 +727,7 @@ SELECT t1.a, t2.b FROM t1, t2 WHERE t1.a = t2.a; one is a SELECT command and the other is an UPDATE is handled higher up in the executor, where it knows that this is an UPDATE, and it knows that - this result should go into table t1. But which of the rows + this result should go into table t1. But which of the rows that are there has to be replaced by the new row? @@ -739,7 +739,7 @@ SELECT t1.a, t2.b FROM t1, t2 WHERE t1.a = t2.a; This is a system column containing the file block number and position in the block for the row. Knowing the table, the CTID can be used to retrieve the - original row of t1 to be updated. After adding the + original row of t1 to be updated. After adding the CTID to the target list, the query actually looks like: @@ -1691,7 +1691,7 @@ CREATE RULE shoelace_ok_ins AS ON INSERT TO shoelace_ok WHERE sl_name = NEW.ok_name; - Now you can fill the table shoelace_arrive with + Now you can fill the table shoelace_arrive with the data from the parts list: @@ -2355,7 +2355,7 @@ CREATE RULE computer_del AS ON DELETE TO computer DELETE FROM computer WHERE hostname = 'mypc.local.net'; - the table computer is scanned by index (fast), and the + the table computer is scanned by index (fast), and the command issued by the trigger would also use an index scan (also fast). The extra command from the rule would be: @@ -2421,16 +2421,16 @@ Nestloop This shows, that the planner does not realize that the qualification for hostname in - computer could also be used for an index scan on - software when there are multiple qualification + computer could also be used for an index scan on + software when there are multiple qualification expressions combined with AND, which is what it does in the regular-expression version of the command. The trigger will get invoked once for each of the 2000 old computers that have to be deleted, and that will result in one index scan over - computer and 2000 index scans over - software. The rule implementation will do it with two + computer and 2000 index scans over + software. The rule implementation will do it with two commands that use indexes. And it depends on the overall size of - the table software whether the rule will still be faster in the + the table software whether the rule will still be faster in the sequential scan situation. 2000 command executions from the trigger over the SPI manager take some time, even if all the index blocks will soon be in the cache. @@ -2443,7 +2443,7 @@ DELETE FROM computer WHERE manufacturer = 'bim'; Again this could result in many rows to be deleted from - computer. So the trigger will again run many commands + computer. So the trigger will again run many commands through the executor. The command generated by the rule will be: @@ -2452,7 +2452,7 @@ DELETE FROM software WHERE computer.manufacturer = 'bim' The plan for that command will again be the nested loop over two - index scans, only using a different index on computer: + index scans, only using a different index on computer: Nestloop diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 237d7306fe8..34c83880a66 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -2430,8 +2430,8 @@ SELECT ROW(1,2.5,'this is a test'); which will be expanded to a list of the elements of the row value, just as occurs when the .* syntax is used at the top level of a SELECT list (see ). - For example, if table t has - columns f1 and f2, these are the same: + For example, if table t has + columns f1 and f2, these are the same: SELECT ROW(t.*, 42) FROM t; SELECT ROW(t.f1, t.f2, 42) FROM t; diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index cdc387805b1..7dcd7d32329 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -397,8 +397,8 @@ SELECT tf1(17, 100.0); In this example, we chose the name accountno for the first argument, but this is the same as the name of a column in the - bank table. Within the UPDATE command, - accountno refers to the column bank.accountno, + bank table. Within the UPDATE command, + accountno refers to the column bank.accountno, so tf1.accountno must be used to refer to the argument. We could of course avoid this by using a different name for the argument. @@ -1016,7 +1016,7 @@ SELECT *, upper(fooname) FROM getfoo(1) AS t1; This feature is normally used when calling the function in the FROM clause. In this case each row returned by the function becomes a row of the table seen by the query. For example, assume that - table foo has the same contents as above, and we say: + table foo has the same contents as above, and we say: CREATE FUNCTION getfoo(int) RETURNS SETOF foo AS $$ -- 2.47.3