diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 37d78b3512..04ddd73c98 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -238,9 +238,9 @@ include 'filename' The postgresql.conf file can also contain include_dir directives, which specify an entire directory of configuration files to include. It is used similarly: - - include_dir 'directory' - + +include_dir 'directory' + Non-absolute directory names follow the same rules as single file include directives: they are relative to the directory containing the referencing configuration file. Within that directory, only non-directory files whose @@ -263,11 +263,11 @@ include 'filename' situation is to break the custom configuration changes for your site into three files. You could add this to the end of your postgresql.conf file to include them: - - include 'shared.conf' - include 'memory.conf' - include 'server.conf' - + +include 'shared.conf' +include 'memory.conf' +include 'server.conf' + All systems would have the same shared.conf. Each server with a particular amount of memory could share the same memory.conf; you might have one for all servers with 8GB of RAM, @@ -279,15 +279,15 @@ include 'filename' Another possibility is to create a configuration file directory and put this information into files there. For example, a conf.d directory could be referenced at the end ofpostgresql.conf: - - include_dir 'conf.d' - + +include_dir 'conf.d' + Then you could name the files in the conf.d directory like this: - - 00shared.conf - 01memory.conf - 02server.conf - + +00shared.conf +01memory.conf +02server.conf + This shows a clear order in which these files will be loaded. This is important because only the last setting encountered when the server is reading its configuration will be used. Something set in @@ -298,11 +298,11 @@ include 'filename' You might instead use this configuration directory approach while naming these files more descriptively: - - 00shared.conf - 01memory-8GB.conf - 02server-foo.conf - + +00shared.conf +01memory-8GB.conf +02server-foo.conf + This sort of arrangement gives a unique name for each configuration file variation. This can help eliminate ambiguity when several servers have their configurations all stored in one place, such as in a version diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index 3ee6ba2f67..a2d4ca26d8 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -1167,12 +1167,12 @@ include $(PGXS) This procedure is also called a VPATHVPATH build. Here's how: - - mkdir build_dir - cd build_dir - make -f /path/to/extension/source/tree/Makefile - make -f /path/to/extension/source/tree/Makefile install - + +mkdir build_dir +cd build_dir +make -f /path/to/extension/source/tree/Makefile +make -f /path/to/extension/source/tree/Makefile install + @@ -1181,10 +1181,10 @@ include $(PGXS) core script config/prep_buildtree. Once this has been done you can build by setting the make variable USE_VPATH like this: - - make USE_VPATH=/path/to/extension/source/tree - make USE_VPATH=/path/to/extension/source/tree install - + +make USE_VPATH=/path/to/extension/source/tree +make USE_VPATH=/path/to/extension/source/tree install + This procedure can work with a greater variety of directory layouts. diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index cd2465e41c..3badb514ae 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -10495,7 +10495,7 @@ table2-mapping -----+------- a | "foo" b | "bar" - + @@ -10514,7 +10514,7 @@ table2-mapping -----+------- a | foo b | bar - + @@ -10598,7 +10598,7 @@ table2-mapping ---+--- 1 | 2 3 | 4 - + @@ -10671,7 +10671,7 @@ table2-mapping a | b | d ---+---------+--- 1 | [1,2,3] | - + @@ -10692,7 +10692,7 @@ table2-mapping ---+----- 1 | foo 2 | - + diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml index d55a08fb18..4fadf65558 100644 --- a/doc/src/sgml/json.sgml +++ b/doc/src/sgml/json.sgml @@ -163,7 +163,7 @@ The following are all valid json (or jsonb) expressions: - + -- Simple scalar/primitive value -- Primitive values can be numbers, quoted strings, true, false, or null SELECT '5'::json; @@ -177,7 +177,7 @@ SELECT '{"bar": "baz", "balance": 7.77, "active": false}'::json; -- Arrays and objects can be nested arbitrarily SELECT '{"foo": [true, "bar"], "tags": {"a": 1, "b": null}}'::json; - + @@ -262,7 +262,7 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; one jsonb document has contained within it another one. These examples return true except as noted: - + -- Simple scalar/primitive values contain only the identical value: SELECT '"foo"'::jsonb @> '"foo"'::jsonb; @@ -282,7 +282,7 @@ SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; -- Similarly, containment is not reported here: SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields false - + The general principle is that the contained object must match the @@ -296,13 +296,13 @@ SELECT '{"foo": {"bar": "baz"}}'::jsonb @> '{"bar": "baz"}'::jsonb; -- yields f As a special exception to the general principle that the structures must match, an array may contain a primitive value: - + -- This array contains the primitive string value: SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; -- This exception is not reciprocal -- non-containment is reported here: SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- yields false - + jsonb also has an existence operator, which is @@ -363,22 +363,22 @@ SELECT '"foo"'::jsonb ? 'foo'; (For details of the semantics that these operators implement, see .) An example of creating an index with this operator class is: - + CREATE INDEX idxgin ON api USING gin (jdoc); - + The non-default GIN operator class jsonb_path_ops supports indexing the @> operator only. An example of creating an index with this operator class is: - + CREATE INDEX idxginp ON api USING gin (jdoc jsonb_path_ops); - + Consider the example of a table that stores JSON documents retrieved from a third-party web service, with a documented schema definition. A typical document is: - + { "guid": "9c36adc1-7fb5-4d5b-83b4-90356a46061a", "name": "Angela Barton", @@ -394,32 +394,32 @@ CREATE INDEX idxginp ON api USING gin (jdoc jsonb_path_ops); "qui" ] } - + We store these documents in a table named api, in a jsonb column named jdoc. If a GIN index is created on this column, queries like the following can make use of the index: - + -- Find documents in which the key "company" has value "Magnafone" SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"company": "Magnafone"}'; - + However, the index could not be used for queries like the following, because though the operator ? is indexable, it is not applied directly to the indexed column jdoc: - + -- Find documents in which the key "tags" contains key or array element "qui" SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc -> 'tags' ? 'qui'; - + Still, with appropriate use of expression indexes, the above query can use an index. If querying for particular items within the "tags" key is common, defining an index like this may be worthwhile: - + -- Note that the "jsonb -> text" operator can only be called on a JSON -- object, so as a consequence of creating this index the root of each -- "jdoc" value must be an object. This is enforced during insertion. CREATE INDEX idxgintags ON api USING gin ((jdoc -> 'tags')); - + Now, the WHERE clause jdoc -> 'tags' ? 'qui' will be recognized as an application of the indexable operator ? to the indexed @@ -429,10 +429,10 @@ CREATE INDEX idxgintags ON api USING gin ((jdoc -> 'tags')); Another approach to querying is to exploit containment, for example: - + -- Find documents in which the key "tags" contains array element "qui" SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qui"]}'; - + A simple GIN index on the jdoc column can support this query. But note that such an index will store copies of every key and value in the jdoc column, whereas the expression index @@ -460,7 +460,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu and a jsonb_path_ops GIN index is that the former creates independent index items for each key and value in the data, while the latter creates index items only for each value in the - data. + data. For this purpose, the term value includes array elements, @@ -501,17 +501,17 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu equality of complete JSON documents. The btree ordering for jsonb datums is seldom of great interest, but for completeness it is: - - Object > Array > Boolean > Number > String > Null + +Object > Array > Boolean > Number > String > Null - Object with n pairs > object with n - 1 pairs +Object with n pairs > object with n - 1 pairs - Array with n elements > array with n - 1 elements - +Array with n elements > array with n - 1 elements + Objects with equal numbers of pairs are compared in the order: - - key-1, value-1, key-2 ... - + +key-1, value-1, key-2 ... + Note that object keys are compared in their storage order; in particular, since shorter keys are stored before longer keys, this can lead to results that might be unintuitive, such as: @@ -520,9 +520,9 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu Similarly, arrays with equal numbers of elements are compared in the order: - - element-1, element-2 ... - + +element-1, element-2 ... + Primitive JSON values are compared using the same comparison rules as for the underlying PostgreSQL data type. Strings are diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml index a2108d68e2..41b63b4a03 100644 --- a/doc/src/sgml/logicaldecoding.sgml +++ b/doc/src/sgml/logicaldecoding.sgml @@ -51,7 +51,7 @@ Then, you should connect to the target database (in the example below, postgres) as a superuser. - + postgres=# -- Create a slot named 'regression_slot' using the output plugin 'test_decoding' postgres=# SELECT * FROM pg_create_logical_replication_slot('regression_slot', 'test_decoding'); slot_name | xlog_position @@ -139,7 +139,7 @@ postgres=# SELECT pg_drop_replication_slot('regression_slot'); ----------------------- (1 row) - + The following example shows usage of the walsender interface using the pg_recvlogical @@ -148,7 +148,7 @@ postgres=# SELECT pg_drop_replication_slot('regression_slot'); and max_wal_senders to be set sufficiently high for another connection. - + # pg_recvlogical -d postgres --slot test --create # pg_recvlogical -d postgres --slot test --start -f - CTRL-Z @@ -159,7 +159,7 @@ table public.data: INSERT: id[integer]:4 data[text]:'4' COMMIT 693 CTRL-C # pg_recvlogical -d postgres --slot test --drop - + Logical Decoding Concepts @@ -317,7 +317,7 @@ CTRL-C _PG_output_plugin_init. This function is passed a struct that needs to be filled with the callback function pointers for individual actions. - + typedef struct OutputPluginCallbacks { LogicalDecodeStartupCB startup_cb; @@ -326,8 +326,9 @@ typedef struct OutputPluginCallbacks LogicalDecodeCommitCB commit_cb; LogicalDecodeShutdownCB shutdown_cb; } OutputPluginCallbacks; + typedef void (*LogicalOutputPluginInit)(struct OutputPluginCallbacks *cb); - + The begin_cb, change_cb and commit_cb callbacks are required, while startup_cb @@ -344,10 +345,10 @@ typedef void (*LogicalOutputPluginInit)(struct OutputPluginCallbacks *cb); accessed that either have been created by initdb in the pg_catalog schema, or have been marked as user provided catalog tables using - + ALTER TABLE user_catalog_table SET (user_catalog_table = true); CREATE TABLE another_catalog_table(data text) WITH (user_catalog_table = true); - + Any actions leading to xid assignment are prohibited. That, among others, includes writing to tables, performing DDL changes and calling txid_current(). @@ -385,23 +386,23 @@ CREATE TABLE another_catalog_table(data text) WITH (user_catalog_table = true); The optional startup_cb callback is called whenever a replication slot is created or asked to stream changes, independent of the number of changes that are ready to be put out. - + typedef void (*LogicalDecodeStartupCB) ( struct LogicalDecodingContext *ctx, OutputPluginOptions *options, bool is_init ); - + The is_init parameter will be true when the replication slot is being created and false otherwise. options points to a struct of options that output plugins can set: - + typedef struct OutputPluginOptions { OutputPluginOutputType output_type; } OutputPluginOptions; - + output_type has to either be set to OUTPUT_PLUGIN_TEXTUAL_OUTPUT or OUTPUT_PLUGIN_BINARY_OUTPUT. @@ -420,11 +421,11 @@ typedef struct OutputPluginOptions whenever a formerly active replication slot is not used anymore and can be used to deallocate resources private to the output plugin. The slot isn't necessarily being dropped, streaming is just being stopped. - + typedef void (*LogicalDecodeShutdownCB) ( struct LogicalDecodingContext *ctx ); - + @@ -433,12 +434,12 @@ typedef void (*LogicalDecodeShutdownCB) ( The required begin_cb callback is called whenever a start of a commited transaction has been decoded. Aborted transactions and their contents never get decoded. - + typedef void (*LogicalDecodeBeginCB) ( struct LogicalDecodingContext *, ReorderBufferTXN *txn ); - + The txn parameter contains meta information about the transaction, like the timestamp at which it has been committed and its XID. @@ -452,12 +453,12 @@ typedef void (*LogicalDecodeBeginCB) ( decoded. The change_cb callbacks for all modified rows will have been called before this, if there have been any modified rows. - + typedef void (*LogicalDecodeCommitCB) ( struct LogicalDecodingContext *, ReorderBufferTXN *txn ); - + @@ -470,14 +471,14 @@ typedef void (*LogicalDecodeCommitCB) ( or DELETE. Even if the original command modified several rows at once the callback will be called indvidually for each row. - + typedef void (*LogicalDecodeChangeCB) ( struct LogicalDecodingContext *ctx, ReorderBufferTXN *txn, Relation relation, ReorderBufferChange *change ); - + The ctx and txn parameters have the same contents as for the begin_cb and commit_cb callbacks, but additionally the @@ -513,11 +514,11 @@ typedef void (*LogicalDecodeChangeCB) ( The following example shows how to output data to the consumer of an output plugin: - + OutputPluginPrepareWrite(ctx, true); appendStringInfo(ctx->out, "BEGIN %u", txn->xid); OutputPluginWrite(ctx, true); - + diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index c6eb863d1f..11b4d9a0dd 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1315,9 +1315,9 @@ the connection to be used for logical replication from that database. connection via psql or any other libpq-using tool with a connection string including the replication option, e.g.: - - psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - + +psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" + However it is often more useful to use pg_receivexlog (for physical replication) or pg_recvlogical (for logical replication). diff --git a/doc/src/sgml/test-decoding.sgml b/doc/src/sgml/test-decoding.sgml index 250c0d82d1..23cdfe35f8 100644 --- a/doc/src/sgml/test-decoding.sgml +++ b/doc/src/sgml/test-decoding.sgml @@ -23,7 +23,7 @@ Typical output from this plugin, used over the SQL logical decoding interface, might be: - + postgres=# SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'include-xids', '0'); location | xid | data -----------+-----+-------------------------------------------------- @@ -36,7 +36,7 @@ postgres=# SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'i 0/16D3398 | 692 | table public.data: DELETE: id[int4]:3 0/16D3398 | 692 | COMMIT (8 rows) - +