editorial review of PostgreSQL transport docs (#6999)

Co-authored-by: Adam Ralph <[email protected]>
Co-authored-by: Tomasz Masternak <[email protected]>

Author: 3 people

persistence/sql/postgresql-combining-persistence-with-transport.md

@@ -7,28 +7,24 @@ related:
   - transports/postgresql
 ---
 
-## Connection behavior
+When using [SQL persistence using the PostgreSQL dialect](/persistence/sql/dialect-postgresql.md) in combination with the [PostgreSQL transport](/transports/postgresql), the location of saga data depends both on whether the [outbox](/nservicebus/outbox/) is enabled and on the transaction mode.
 
-When combining [PostgreSQL](/transports/postgresql) and [SQL persistence using the PostgreSQL dialect](/persistence/sql/dialect-postgresql.md), the connection behaves differently based on whether the [Outbox](/nservicebus/outbox/) is enabled or disabled. This influences where the saga data is stored.
+## Outbox disabled
 
-### Without Outbox
-
-PostgreSQL Transport<br/>TransactionMode | Connection sharing | Saga location
+PostgreSQL Transport<br/>TransactionMode | Connection sharing | Saga data location
 :-:|:-:|:-:
-SendsAtomicWithReceive | PostgreSQL Transport uses isolated transaction for send and receive | Transport DB
-ReceiveOnly | PostgreSQL Transport uses isolated transaction for receive | Transport DB
+SendsAtomicWithReceive | isolated transaction for send and receive | Transport DB
+ReceiveOnly | isolated transaction for receive | Transport DB
 None | No transactions | Persistence DB
 
-#### Explicitly opting out of connection sharing when not using the Outbox
-
-When an endpoint uses PostgreSQL Persistence combined with the PostgreSQL Transport with [Outbox](/nservicebus/outbox/) disabled, the persistence uses the connection and transaction context established by the transport when accessing saga data. This behavior ensures *exactly-once* message processing behavior as the state change of the saga is committed atomically while consuming the message that triggered it.
+With the outbox disabled, the persistence uses the connection and transaction context established by the transport to access saga data. This behavior ensures *exactly-once* message processing, since the state change of a saga is committed atomically with the consumption of the message that caused it.
 
 partial: Connection
 
-### With Outbox
+## Outbox enabled
 
-PostgreSQL Transport<br/>TransactionMode | Connection sharing | Saga location
+PostgreSQL Transport<br/>TransactionMode | Connection sharing | Saga data location
 :-:|:-:|:-:
 SendsAtomicWithReceive | Not supported | N/A
-ReceiveOnly | Connection sharing via PostgreSQL Transport storage context | Persistence DB
+ReceiveOnly | via Transport storage context | Persistence DB
 None | Not supported | N/A

persistence/sql/postgresql-combining-persistence-with-transport_connection_sqlpersistence_[8,).partial.md

@@ -1,6 +1,6 @@
-When using the [outbox](/nservicebus/outbox/), SQL Persistence always opens its own connection. In order to force using a separate connection even when the [outbox](/nservicebus/outbox/) is disabled, use the following API:
+This behaviour may be disabled, to force the persistance to create its own connection, as it does when the outbox is enabled:
 
 snippet: PostgreSqlDoNotShareConnection
 
 > [!WARNING]
-> In this mode NServiceBus does not guarantee *exactly-once* message processing behavior which means that saga message handling logic might be called multiple times for a single incoming message in case the previous processing attempts failed just before consuming the message.
+> In this mode NServiceBus does not guarantee *exactly-once* message processing behavior. A single incoming message could result in multiple calls of the saga message handling logic, if the previous processing attempt failed just before consuming the message.

samples/postgresqltransport/simple/sample.md

@@ -9,7 +9,7 @@ related:
 
 ## Prerequisites
 
-The uses a database `nservicebus`. Ensure it exists before running the sample.
+This sample uses a database named `nservicebus`. Ensure it exists before running the sample.
 
 ## Running the sample
 

transports/postgresql/addressing.md

@@ -7,23 +7,25 @@ component: PostgreSqlTransport
 
 ## Format
 
-The PostgreSQL Transport address canonical form is a schema-qualified quoted identifier:
+The canonical form of a PostgreSQL transport address is a schema-qualified quoted identifier:
 
-```
+```text
 ""table"".""schema""
 ```
 
+Only the table name is mandatory. An address containing only a table name is a valid address, e.g. `MyTable`.
+
 ## Resolution
 
-The address is resolved into a fully-qualified table name that includes the table name and its schema. In the address, the table name is the only mandatory part. An address containing only a table name is a valid address, e.g. `MyTable`.
+The address is resolved into a fully-qualified table name that includes the table name and its schema.
 
 ### Schema
 
-The PostgreSQL transport needs to know what schema to use for a queue table when sending messages. The following API can be used to specify the schema for an endpoint when [routing](/nservicebus/messaging/routing.md) is used to find a destination queue table for a message:
+The transport needs to determine which schema to use for a queue table when sending messages. The following API sets the schema for an endpoint when using [routing](/nservicebus/messaging/routing.md) to determine the destination queue for a message:
 
 snippet: postgresql-multischema-config-for-endpoint
 
-There are several cases when routing is not used and the transport needs specific configuration to find out the schema for a queue table:
+There are several cases when routing is not used and the transport requires specific configuration to determine the schema for a queue table:
 
 - [Error queue](/nservicebus/recoverability/configure-error-handling.md#configure-the-error-queue-address)
 - [Audit queue](/nservicebus/operations/auditing.md#configuring-auditing)
@@ -32,11 +34,11 @@ There are several cases when routing is not used and the transport needs specifi
   - [Custom Checks plugin](/monitoring/custom-checks/install-plugin.md)
 - [Overriding the default routing mechanism](/nservicebus/messaging/send-a-message.md#overriding-the-default-routing)
 
-Use the following API to configure the schema for a queue:
+Use the following API to set the schema for a queue:
 
 snippet: postgresql-multischema-config-for-queue
 
-The configuration above is applicable when sending to a queue or when a queue is passed in the configuration:
+The specified schema is used both when sending to a specific queue, and when a queue is set in endpoint configuration:
 
 snippet: postgresql-multischema-config-for-queue-send
 
@@ -47,10 +49,10 @@ snippet: postgresql-multischema-config-for-queue-error
 
 snippet: postgresql-multischema-config-for-queue-heartbeats
 
-The entire algorithm for calculating the schema is the following:
+The following values determine the schema, in priority order:
 
-* If the schema is configured for a given queue via `UseSchemaForQueue`, the configured value is used.
-* If [logical routing](/nservicebus/messaging/routing.md#command-routing) is used and schema is configured for a given endpoint via `UseSchemaForEndpoint`, the configured schema is used.
-* If destination address contains a schema, the schema from address is used.
-* If default schema is configured via `DefaultSchema`, the configured value is used.
+* A schema configured for a given queue via `UseSchemaForQueue`.
+* A schema configured for a given endpoint via `UseSchemaForEndpoint`.
+* A schema contained in the destination address.
+* A default schema configured via `DefaultSchema`.
 * Otherwise, `public` is used as a default schema.

transports/postgresql/connection-settings.md

@@ -5,11 +5,11 @@ reviewed: 2024-05-27
 component: PostgreSqlTransport
 ---
 
-## Using connection pooling
+## Connection pooling
 
-The PostgreSQL transport is built on top of [ADO.NET](https://docs.microsoft.com/en-us/dotnet/framework/data/adonet/index) and will use connection pooling. This may result in the connection pool being shared by the transport, as well as other parts of the endpoint process and the business logic.
+The PostgreSQL transport is built on top of [ADO.NET](https://docs.microsoft.com/en-us/dotnet/framework/data/adonet/index) and will use connection pooling. This may result in sharing of the connection pool by the transport, as well as other parts of the endpoint process and the business logic.
 
-In scenarios where the concurrent message processing limit is changed, or the database connection is used for other purposes mentioned above, change the connection pool size to ensure it will not be exhausted.
+If increasing the concurrent message processing limit, or if the database connection is used for other purposes mentioned above, increase the connection pool size to ensure it is not exhausted.
 
 > [!NOTE]
 > If the maximum pool size is not explicitly set on the connection string, a warning message will be logged. See also [Tuning endpoint message processing](/nservicebus/operations/tuning.md).
@@ -22,24 +22,29 @@ snippet: postgresql-config-connectionstring
 
 ### Token Authentication
 
-To connect using token credentials, a User ID must still be supplied in the connection string with the password supplied from the access token. Given that the token is short-lived, a [data source builder must be utilized to handle password refreshes](https://devblogs.microsoft.com/dotnet/using-postgre-sql-with-dotnet-and-entra-id/). The following example uses Microsoft Entra ID.
+To connect using token credentials, the following must be provided in the connection string:
+
+- A User ID.
+- The password taken from the access token. 
+
+Since tokens are short-lived, a [data source builder must be utilized to handle password refreshes](https://devblogs.microsoft.com/dotnet/using-postgre-sql-with-dotnet-and-entra-id/). The following example uses Microsoft Entra ID.
 
 snippet: postgresql-config-entra
 
 ## Custom database schemas
 
-The PostgreSQL transport uses `public` as a default schema. It is used for every queue if no other schema is explicitly provided in a transport address. This includes all local queues, error, audit, and remote queues of other endpoints.
+The transport uses `public` as a default schema. It is used for every queue if no other schema is explicitly provided in a transport address. This includes all local queues, error, audit, and remote queues of other endpoints.
 
 The default schema can be overridden using the `DefaultSchema` method:
 
 snippet: postgresql-non-standard-schema
 
 > [!NOTE]
-> When subscribing to events between endpoints in different database schemas or catalogs, a [shared subscription table must be configured](/transports/postgresql/native-publish-subscribe.md#configure-subscription-table).
+> Subscribing to events between endpoints in different database schemas or catalogs requires a [shared subscription table to be configured](/transports/postgresql/native-publish-subscribe.md#configure-subscription-table).
 
-## Custom PostgreSQL transport connection factory
+## Custom connection factory
 
-In some environments, it might be necessary to adapt to the database server settings or to perform additional operations. This can be done by passing a custom factory method to the transport which will provide connection strings at runtime and can perform custom actions:
+Some environments need additional connection operations, such as adapting to the database server settings. To achieve this, pass a custom factory method to the transport that will provide connection strings at runtime and can perform custom actions:
 
 snippet: postgresql-custom-connection-factory
 

transports/postgresql/design.md

@@ -5,15 +5,15 @@ reviewed: 2024-05-28
 component: PostgreSqlTransport
 ---
 
-In PostgreSQL Transport each queue is represented as table inside a database. Depending on the endpoint configuration, each endpoint might use multiple queues/tables e.g. for [callbacks](/transports/sql/callbacks.md).
+Each queue in PostgreSQL Transport is implemented as table inside a database. Depending on the endpoint configuration, each endpoint could use multiple queues, and therefore tables, e.g. for [callbacks](/transports/sql/callbacks.md).
 
 ## Structure
 
 The queue table consists of the following columns
 
 ### ID
 
-The `Id` is a `uuid` generated by the sending code. It is not used by PostgreSQL transport itself.
+The `Id` is a `uuid` generated by the sending code. It is not used by the transport itself.
 
 ### Expires
 
@@ -47,20 +47,20 @@ Messages are sent by executing an `insert` command against the queue table.
 
 ### Receiving
 
-Messages are received by executing a `delete` command against the queue table. The `delete` is limited to a row with the lowest `Seq` not locked by other concurrent `delete`. This ensures that multiple threads within an endpoint instance and multiple instances of the same scaled-out endpoint can operate at full speed without conflicts.
+Messages are received by executing a `delete` command against the queue table. The `delete` is limited to a row with the lowest `Seq` not locked by any other concurrent `delete`. This ensures that multiple threads within an endpoint instance, and multiple instances of the same scaled-out endpoint, can operate at full speed without conflicts.
 
 PostgreSQL transport operates in two modes: *peek* and *receive*. It starts in the *peek* mode and checks via `max(seq) - min(seq)` the number of pending messages. If the number is greater then zero, it switches to the *receive* mode and starts spawning receive tasks that use the `delete` command to receive messages.
 
 The maximum number of concurrent receive tasks never exceeds the value set by `LimitMessageProcessingConcurrencyTo` (the number of tasks does not translate to the number of running threads which is controlled by the TPL scheduling mechanisms).
 
 When all tasks are done the transport switches back to the *peek* mode.
 
-In certain conditions, the initial estimate of a number of pending messages might be wrong e.g. when there is more than one instance of a scaled-out endpoint consuming messages from the same queue. In this case, one of the received tasks is going to fail (`delete` returns no results). When this happens, the transport immediately switches back to the *peek* mode.
+Under certain conditions, the initial estimate of the number of pending messages might be wrong e.g. when there is more than one instance of a scaled-out endpoint consuming messages from the same queue. In this case, one of the received tasks will fail (i.e. `delete` will return no results). When this happens, the transport immediately switches back to the *peek* mode.
 
-The default peek interval, if there is has been no messages in the queue, is 1 second. The recommended range for this setting is between 100 milliseconds to 10 seconds. If a value higher than the maximum recommended settings is used, a warning message will be logged. While a value less than 100 milliseconds will put too much unnecessary stress on the database, a value larger than 10 seconds should also be used with caution as it may result in messages backing up in the queue.
+The [default peek interval](#behavior-queue-peek-settings-peek-delay-configuration), if no peek has yet been run or the previous peek returned no messages in the queue, is 1 second. The recommended range for this setting is between 100 milliseconds to 10 seconds. If a value higher than the maximum recommended settings is used, a warning message will be logged. While a value less than 100 milliseconds will put unnecessary stress on the database, a value larger than 10 seconds should also be used with caution as it may result in messages backing up in the queue.
 
-[!NOTE]
-In cases where the queue peek interval is configured, care should be taken to ensure that the peek interval is not bigger than the Time-To-Be-Received(TTBR) to ensure that such messages are not discarded.
+> [!WARNING]
+> If the queue peek interval is configured, it must not be set larger than the [Time-To-Be-Received](/nservicebus/messaging/discard-old-messages.md)(TTBR) to ensure that such messages are not discarded.
 
 ### Queue peek settings
 

transports/postgresql/index.md

@@ -24,13 +24,13 @@ The PostgreSQL transport implements a message queuing mechanism on top of [Postg
 
 ## Usage
 
-A basic use of the PostgreSQL transport is as follows:
+A basic use of the transport is as follows:
 
 snippet: usage
 
 ## How it works
 
-PostgreSQL transport uses tables to represent queues and store messages. The PostgreSQL transport is best considered as a brokered transport, like RabbitMQ, rather than a store-and-forward transport, such as MSMQ.
+Tables are used to represent queues and store messages. The transport is best considered as a brokered transport, like RabbitMQ, rather than a store-and-forward transport, such as MSMQ.
 
 ## Advantages
 
@@ -41,9 +41,9 @@ PostgreSQL transport uses tables to represent queues and store messages. The Pos
 
 ## Disadvantages
 
-* No local store-and-forward mechanism; when a PostgreSQL instance is down, the endpoint cannot send nor receive messages.
+* No local store-and-forward mechanism; when a PostgreSQL instance is down, the endpoint cannot send or receive messages.
 * In centralized deployment scenarios, maximum throughput applies for the whole system, not individual endpoints. For example, if PostgreSQL can handle 2000 msg/s on the given hardware, each one of the 10 endpoints deployed on this machine can only receive a maximum of 200 msg/s (on average).
-* When using PostgreSQL transport, a database table serves as a queue for the messages for the endpoints. These tables are polled periodically to see if messages need to be processed by the endpoints. Although the polling interval is one second, this may still lead to delays in processing a message. For environments where low latency is required, consider using other transports that use queuing technologies, such as RabbitMQ.
+* When using PostgreSQL transport, a database table serves as a queue for the messages for the endpoints. These tables are polled to see if there are messages to be processed by the endpoints. Although the polling interval is, by default, one second, this may still lead to delays in processing a message. For environments where low latency is required, consider using other transports that use dedicated queuing technologies, such as RabbitMQ.
 
 ## Deployment considerations
 
@@ -71,4 +71,10 @@ By default, PostgreSQL [limits the maximum number](https://www.postgresql.org/do
 
 ## Transactions
 
-PostgreSQL transport supports following [transaction handling modes](/transports/transactions.md): receive only, send atomic with receive, and no transactions. It does not support Transaction scope mode due to the limitations in the design of the PostgreSQL database and the System.Transactions library.
+PostgreSQL transport supports the following [transaction handling modes](/transports/transactions.md): 
+
+- receive only 
+- send atomic with receive 
+- no transactions. 
+
+It does not support Transaction scope mode due to the limitations in the design of the PostgreSQL database and the System.Transactions library.