Spellchecking lb docs

Author: levkk

docs/features/load-balancer/manual-routing.md

@@ -23,7 +23,7 @@ Query comments are supported in all types of queries, including prepared stateme
 
 Parameters are connection-specific settings that can be set on connection creation to configure database behavior. For example, this is how ORMs and web frameworks control settings like `application_name`, `statement_timeout` and many others.
 
-The Postgres protocol doesn't have any restrictions on parameter names or values, and PgDog has access to them at connection creation.
+The Postgres protocol doesn't have any restrictions on parameter names or values, and PgDog can intercept and handle them at any time.
 
 The following two parameters allow you to control which database is used for all queries on a client connection:
 
@@ -34,16 +34,20 @@ The following two parameters allow you to control which database is used for all
 
 The `pgdog.role` parameter accepts the following values:
 
-| Parameter value | Behavior |
-|-|-|
-| `primary` | All queries are sent to the primary database. |
-| `replica` | All queries are load balanced between replica databases, and possibly the primary if [`read_write_split`](../../configuration/pgdog.toml/general.md#read_write_split) is set to `include_primary` (default). |
+| Parameter value | Behavior | Example |
+|-|-|-|
+| `primary` | All queries are sent to the primary database. | `SET pgdog.role TO "primary"` |
+| `replica` | All queries are load balanced between replica databases, and possibly the primary if [`read_write_split`](../../configuration/pgdog.toml/general.md#read_write_split) is set to `include_primary` (default). | `SET pgdog.role TO "replica"` |
+
+The `pgdog.shard` parameter accepts a shard number for any database specified in [`pgdog.toml`](../../configuration/pgdog.toml/databases.md), for example:
 
-The `pgdog.shard` parameter accepts a shard number for any database specified in [`pgdog.toml`](../../configuration/pgdog.toml/databases.md).
+```postgresql
+SET pgdog.shard TO 1;
+```
 
 ### Setting the parameters
 
-Configuring parameters at connection creation is PostgreSQL driver-specific. Some of the common drivers and frameworks are shown below.
+Configuring parameters can be done at connection creation, or by using the `SET` command. Below are examples of some of the common PostgreSQL drivers and web frameworks.
 
 #### Database URL
 
@@ -114,19 +118,19 @@ Depending on the environment, the parameters may need to be URL-encoded, e.g., `
 
 ### Using `SET`
 
-The PostgreSQL protocol supports configuring connection parameters using the `SET` statement. This also works for configuring both `pgdog.role` and `pgdog.shard`.
+The PostgreSQL protocol supports changing connection parameters using the `SET` statement. By extension, this also works for changing `pgdog.role` and `pgdog.shard` settings.
 
-For example, to make sure all subsequent queries to be sent to the primary, you can execute the following statement:
+For example, to make sure all subsequent queries are sent to the primary, you can execute the following statement:
 
 ```postgresql
 SET pgdog.role TO "primary";
 ```
 
-The parameter is persisted on the connection until it's closed or the parameter is changed with another `SET` statement.
+The parameter is persisted on the connection until it's closed or the value is changed with another `SET` statement. Before routing a query, the load balancer will check the value of this parameter, so setting it early on during connection creation ensures all transactions are executed on the right database.
 
 #### Inside transactions
 
-If you want to provide a transaction routing hint without affecting the rest of the connection, you can use `SET LOCAL` instead:
+It's possible to set routing hints for the lifetime of a single transaction, by using the `SET LOCAL` command. This ensures the routing hint is used for one transaction only and doesn't affect the rest of the queries:
 
 ```postgresql
 BEGIN;
@@ -136,7 +140,7 @@ SET LOCAL pgdog.role TO "primary";
 In this example, all transaction statements (including the `BEGIN` statement) will be sent to the primary database. Whether the transaction is committed or reverted, the value of `pgdog.role` will be reset to its previous value.
 
 !!! note "Statement ordering"
-    To make sure PgDog intercepts the routing hint early enough in the transaction flow, make sure to send all hints _before_ executing actual queries.
+    To make sure PgDog intercepts the routing hint early enough in the transaction flow, you need to send all hints _before_ executing actual queries.
 
     The following flow, for example, _will not_ work:
 
@@ -153,7 +157,7 @@ In this example, all transaction statements (including the `BEGIN` statement) wi
 
 In certain situations, the overhead of parsing queries may be too high, e.g., when your application can't use prepared statements.
 
-If you've configured the desired database role (and/or shard) for each of your application connections, you can disable the query parser in [pgdog.toml](../../configuration/pgdog.toml/general.md#query_parser):
+If you've configured the desired database role (and/or shard) for each of your application connections, you can disable the query parser in [`pgdog.toml`](../../configuration/pgdog.toml/general.md#query_parser):
 
 ```toml
 [general]

docs/features/load-balancer/transactions.md

@@ -6,7 +6,7 @@ icon: material/swap-horizontal
 
 PgDog's load balancer is [transaction-aware](../transaction-mode.md) and will ensure that all statements inside a transaction are sent to the same PostgreSQL connection on just one database.
 
-To make sure all queries inside a transaction succeed, PgDog will route all manually started transactions to the **primary** database.
+To make sure all queries inside a transaction succeed, PgDog will route all manually started transactions to the primary database.
 
 ## How it works
 
@@ -18,57 +18,62 @@ INSERT INTO users (email, created_at) VALUES ($1, NOW()) RETURNING *;
 COMMIT;
 ```
 
-PgDog processes queries immediately upon receiving them, and since transactions can contain multiple statements, it isn't possible to determine whether one of the statements won't write to the database.
+PgDog executes queries immediately upon receiving them, and since transactions can contain multiple statements, it isn't possible to determine in advance what the statements will do.
 
-Therefore, it is more reliable to send the entire transaction to the primary database.
+Therefore, it is more reliable to send the entire transaction to the primary, which can handle all types of queries.
 
 ### Read-only transactions
 
-The PostgreSQL query language allows you to declare a transaction as read-only, which prevents it from writing data to the database. PgDog can take advantage of this property and will send such transactions to a replica database.
+The PostgreSQL query language allows you to declare a transaction as read-only. This property prevents it from writing data, even if a database can accept writes.
 
-Read-only transactions are started with the `BEGIN READ ONLY` command, for example:
+PgDog takes advantage of this property and will send such transactions to a replica. Read-only transactions are started with the `BEGIN READ ONLY` command, for example:
 
 ```postgresql
 BEGIN READ ONLY;
 SELECT * FROM users WHERE id = $1;
 COMMIT;
 ```
 
-Read-only transactions are useful when queries need a consistent view of the database. Some Postgres database drivers allow this option to be set in the code, for example:
+In addition to forcing all statements to a replica, read-only transactions are useful when queries need a consistent view of the database. Most Postgres client drivers allow this option to be set in the code, for example:
 
-=== "pgx (go)"
+=== "pgx (Go)"
     ```go
     tx, err := conn.BeginTx(ctx, pgx.TxOptions{
         AccessMode: pgx.ReadOnly,
     })
     ```
-=== "Sequelize (node)"
+=== "Sequelize (Node)"
     ```javascript
     const tx = await sequelize.transaction({
       readOnly: true,
     });
     ```
-=== "SQLAlchemy (python)"
-    Add `postgresql_readonly=True` to [execution options](https://docs.sqlalchemy.org/en/20/core/connections.html#sqlalchemy.engine.Engine.execution_options), like so:
+=== "SQLAlchemy (Python)"
     ```python
     engine = create_engine("postgresql://user:pw@pgdog:6432/prod")
               .execution_options(postgresql_readonly=True)
     ```
 
 ### Replication lag
 
-While transactions are used to atomically change multiple tables, they can also be used to manually route `SELECT` queries to the primary database. For example:
+Since PgDog sends all manual transactions to the primary, they can also be used to send `SELECT` queries to the primary as well.
+
+For example:
 
 ```postgresql
 BEGIN;
 SELECT * FROM users WHERE id = $1;
 COMMIT;
 ```
 
-This is useful when the data in the table(s) has been recently updated and you want to avoid errors caused by replication lag. This often manifests as "record not-found"-style errors, for example:
+ This avoids having to write additional code to handle replication lag, which is useful when the data in the table(s) has been recently updated and you want to avoid fetching stale or nonexistent rows.
 
-```
-ActiveRecord::RecordNotFound (Couldn't find User with 'id'=9999):
-```
 
-While sending read queries to the primary adds load, it is often necessary in real-time systems that are not equipped to handle replication delays.
+!!! note "Example"
+    If you're using Rails/ActiveRecord, these types of errors sometimes manifest like this:
+
+    ```
+    ActiveRecord::RecordNotFound (Couldn't find User with 'id'=9999):
+    ```
+
+While sending read queries to the primary adds additional load, it is often necessary in real-time systems that are not equipped to handle replication delays.