Spelling

levkk · levkk · commit ec6ee36bd58f · 2025-08-27T19:02:42.000-07:00
diff --git a/docs/about.md b/docs/about.md
@@ -16,4 +16,4 @@ PgDog source code, so the whole community can benefit from your knowledge and ex
 
 ## Project name
 
-This project is dedicated to the bestest dog in the world who's been patiently sitting at my feet the entire time PgDog has been developed.
+This project is dedicated to the best dog in the world who's been patiently sitting at my feet the entire time PgDog has been developed.
diff --git a/docs/architecture/benchmarks.md b/docs/architecture/benchmarks.md
@@ -1,6 +1,6 @@
 # Benchmarks
 
-PgDog does its best to minimize its impact on database performance. Great care is taken to make sure as few operations are possible are performed
+PgDog does its best to minimize its impact on database performance. Great care is taken to make sure as few operations as possible are performed
 when passing data between clients and servers.
 
 All benchmarks listed below were done on my local system (AMD Ryzen 7 5800X). Real world performance is impacted by factors like network speed, query complexity and especially by hardware used for running PgDog and PostgreSQL servers.
diff --git a/docs/features/load-balancer/healthchecks.md b/docs/features/load-balancer/healthchecks.md
@@ -14,7 +14,7 @@ While all databases receive health checks, only replicas can be removed from the
 
 ### Individual connections
 
-In addition to checking entire databases, the load balancer checks that every connection in the pool is healthy on a regular basis. Before giving a connection to a client, it will, from time to time, send the a short query to the server, and if it fails, ban the entire database from serving any more requests.
+In addition to checking entire databases, the load balancer checks that every connection in the pool is healthy on a regular basis. Before giving a connection to a client, it will, from time to time, send a short query to the server, and if it fails, ban the entire database from serving any more requests.
 
 To reduce the overhead of health checks, these connection-specific checks are done infrequently. This is configurable via the `healthcheck_interval` setting:
 
diff --git a/docs/features/multi-tenancy.md b/docs/features/multi-tenancy.md
@@ -7,7 +7,7 @@ PgDog is a natural fit for multitenant databases. It allows to separate data usi
 There are two ways to enforce multitenancy rules with PgDog:
 
 1. Physical multitenancy
-2. Virtual multinancy
+2. Virtual multitenancy
 
 **Physical** multitenancy separates data into multiple Postgres databases. In that scenario, it becomes very difficult for data from one tenant to make its way to another, providing a good layer of security and workload isolation between your customers.
 
@@ -101,7 +101,7 @@ Much like Postgres partitions, the start of the range is included in the range w
     regularly with its status. The documentation is written in a way as to reflect
     the desired state of this feature, not how it currently works.
 
-Virtual multinancy is a great option if your customers are small and can share the same compute. To make this work you have several options:
+Virtual multitenancy is a great option if your customers are small and can share the same compute. To make this work you have several options:
 
 1. Place each of your tenants data into their own Postgres schema
 2. Add a column in every table identifying your tenants and make sure your app includes it in every query
diff --git a/docs/features/sharding/copy.md b/docs/features/sharding/copy.md
@@ -1,6 +1,6 @@
 # COPY
 
-`COPY` is a special PostgreSQL command that ingests a file directly into a database table. This allows to ingest data faster than by using individual `INSERT` queries.
+`COPY` is a special PostgreSQL command that ingests a file directly into a database table. This allows ingesting data faster than by using individual `INSERT` queries.
 PgDog supports parsing this command, sharding the file automatically, and splitting the data between shards, invisible to the application.
 
 <center style="margin-top: 2rem;">
@@ -18,7 +18,7 @@ PgDog supports data sent via `COPY` formatted using any one of the 3 possible fo
 
 ### Expected syntax
 
-`COPY` commands sent through PgDog should specify table columns explicitly. This allows itg to parse the data stream correctly, knowing which column is the sharding key.
+`COPY` commands sent through PgDog should specify table columns explicitly. This allows it to parse the data stream correctly, knowing which column is the sharding key.
 
 Take the following example:
 
diff --git a/docs/features/sharding/cross-shard.md b/docs/features/sharding/cross-shard.md
@@ -43,7 +43,7 @@ to values in `DataRow`[^1] messages based on their position in the `RowDescripti
 
 For example, if the query specifies `ORDER BY id ASC, email DESC`, both `id` and `email` columns will be present in the `RowDescription` message along with their data types and locations in `DataRow`[^1] messages.
 
-The rows are received asynchronously  as the query is executing on the shards. Once the messages are buffered, PgDog will sort them using the extracted column values and return the sorted result to the client.
+The rows are received asynchronously as the query is executing on the shards. Once the messages are buffered, PgDog will sort them using the extracted column values and return the sorted result to the client.
 
 #### Example
 
@@ -117,7 +117,7 @@ GROUP BY email;
 
 ## Supported data types
 
-Processing results in PgDog requires it to parse Postgres data types from the wire protocol. Postgres supports many data types and PgDog, currently, can only handle a some of them. Clients can request results to be encoded in either `text` or `binary` encoding and supporting both requires special handling as well.
+Processing results in PgDog requires it to parse Postgres data types from the wire protocol. Postgres supports many data types and PgDog, currently, can only handle some of them. Clients can request results to be encoded in either `text` or `binary` encoding and supporting both requires special handling as well.
 
 | Data type | Sorting | Aggregation | Text format | Binary format |
 |-|-|-|-|-|
diff --git a/docs/features/sharding/index.md b/docs/features/sharding/index.md
@@ -22,7 +22,7 @@ When sharding hints are not present in a query, either accidentally or on purpos
 
 ### Manual routing
 
-If direct-to-shard queries are desired but the query doesn't have enough information to extract this information automatically, clients can specify which to which shard PgDog should route the query.
+If direct-to-shard queries are desired but the query doesn't have enough information to extract this information automatically, clients can specify to which shard PgDog should route the query.
 
 [**→ Manual routing**](manual-routing.md)
 
diff --git a/docs/features/sharding/internals/logical-replication/index.md b/docs/features/sharding/internals/logical-replication/index.md
@@ -1,6 +1,6 @@
 # Logical replication overview
 
-One of PgDog's most interested features is its ability to interpret the logical replication protocol used by Postgres to synchronize replicas. This allows PgDog to reroute data depending on which shard it should go to in a sharded cluster. Since logical replication is streaming data in real time, PgDog can move data between shards invisibly to the client and without database downtime.
+One of PgDog's most interesting features is its ability to interpret the logical replication protocol used by Postgres to synchronize replicas. This allows PgDog to reroute data depending on which shard it should go to in a sharded cluster. Since logical replication is streaming data in real time, PgDog can move data between shards invisibly to the client and without database downtime.
 
 ## Logical replication internals
 
diff --git a/docs/features/sharding/migrations.md b/docs/features/sharding/migrations.md
@@ -3,7 +3,7 @@
 PgDog expects that all shards have, roughly, the same tables. A notable exception to this rule is partitioned tables,
 which can have different data tables on different shards. The parent tables should be present on all shards, however.
 
-If a shard has different tables than another, [automatic](query-routing.md) query routing may no work as expected.
+If a shard has different tables than another, [automatic](query-routing.md) query routing may not work as expected.
 
 ## How it works
 
diff --git a/docs/features/sharding/primary-keys.md b/docs/features/sharding/primary-keys.md
@@ -5,7 +5,7 @@ If you're coming from unsharded Postgres, you're probably used to doing somethin
 ```postgresql
 CREATE TABLE users (
   id BIGSERIAL PRIMARY KEY,
-  email VARCHAR,
+  email VARCHAR
 );
 ```
 
diff --git a/docs/features/sharding/resharding/hash.md b/docs/features/sharding/resharding/hash.md
@@ -17,7 +17,7 @@ You can visualize this phenomenon with a bit of Python:
     [1, 2, 0, 1, 2]
     ```
 
-Since most rows will have to moved, resharding a cluster in-place would put a lot of load on an already overextended system.
+Since most rows will have to be moved, resharding a cluster in-place would put a lot of load on an already overextended system.
 
 PgDog's strategy for resharding is to **move data** from an existing cluster to a completely new one, while rehashing the rows in-flight. This process is parallelizable and fast, and since most of the work is done by the new cluster, production databases are not affected.
 
@@ -43,7 +43,7 @@ pgdog data-sync --help
 | `--from-database` | Name of the **source** database cluster. | `prod` |
 | `--from-user` | Name of the user configured in `users.toml` for the **source** database cluster. | `postgres` |
 | `--to-database` | Name of the **destination** database cluster. | `prod-sharded` |
-| `--to-user` | Name of the user configured in `users.tom` for the **destination** database cluster. | `postgres` |
+| `--to-user` | Name of the user configured in `users.toml` for the **destination** database cluster. | `postgres` |
 | `--publication` | Name of the Postgres [publication](https://www.postgresql.org/docs/current/sql-createpublication.html) for tables to be copied and sharded. It should exist on the **source** database. | `all_tables` |
 
 All databases and users must be configured in `pgdog.toml` and `users.toml`.
diff --git a/docs/features/sharding/sharding-functions.md b/docs/features/sharding/sharding-functions.md
@@ -32,7 +32,7 @@ column = "user_id"
 data_type = "bigint"
 ```
 
-All queries referencing the `user_id` column will be automatically sent the matching shard(s) and data in those tables will be split between all shards evenly.
+All queries referencing the `user_id` column will be automatically sent to the matching shard(s) and data in those tables will be split between all shards evenly.
 
 <!-- For hash-based sharding, to achieve the same inside the database, you can use the `satisfies_hash_partition` function: -->
 
diff --git a/docs/features/transaction-mode.md b/docs/features/transaction-mode.md
@@ -1,30 +1,35 @@
 # Transaction mode
 
-Transaction mode allows PgDog to share just a few PostgreSQL server connections with thousands of clients. This is required for at-scale production deployments where the number of clients is much higher than the number of available Postgres connections.
+Transaction mode allows PgDog to share just a few of PostgreSQL server connections with thousands of clients. This is required for at-scale production deployments where the number of clients is much higher than the number of available connections to the database.
 
 ## How it works
 
-All queries served by PostgreSQL run inside transactions. Transactions can be started manually by executing a `BEGIN` statement. If a transaction is not started manually, each query sent to PostgreSQL is executed inside its own, automatic, transaction.
+All queries served by PostgreSQL run inside transactions. Transactions can be started manually by executing a `BEGIN` command, or automatically by running individual statements.
 
-PgDog takes advantage of this behavior and can separate client transactions inside client connections and send them, individually, to the first available PostgreSQL server in the connection pool.
+PgDog takes advantage of this behavior and can split up transactions inside client connections and send them, individually and in order, to the first available PostgreSQL server in the connection pool.
 
 <center>
   <img src="/images/transaction-mode.png" width="85%" alt="Load balancer" />
 </center>
 
-In practice, this allows thousands of client connections to use just one PostgreSQL server connection to execute queries. Most connection pools will have multiple server connections, so hundreds of thousands of clients can connect to PgDog and execute queries over just a handful of PostgreSQL server connections.
+In practice, this allows thousands of client connections to re-use just one PostgreSQL server connection. Most pools will have several server connections, so 100,000s of clients can use the pooler to execute queries without exceeding the database connection limit.
 
+## Enabling transaction mode
 
-### Enabling transaction mode
+Transaction mode is **enabled** by default. This is controllable via configuration, at the global, user and database levels:
 
-Transaction mode is **enabled** by default. This is controllable via configuration, at the global
-and user level:
-
-=== "pgdog.toml"
+=== "pgdog.toml (global)"
     ```toml
     [general]
     pooler_mode = "transaction"
     ```
+=== "pgdog.toml (database)"
+    ```toml
+    [[databases]]
+    name = "prod"
+    host = "127.0.0.1"
+    pooler_mode = "transaction"
+    ```
 === "users.toml"
     ```toml
     [[users]]
@@ -33,13 +38,15 @@ and user level:
     pooler_mode = "transaction"
     ```
 
-### Session-level state
+## Session-level state
 
-Clients can set session-level variables, e.g., by passing them in connection parameters or using the `SET` command. This works fine when connecting to Postgres directly, but PgDog shares server
-connections between multiple clients. To avoid session-level state leaking between clients, PgDog tracks connection parameters for each client and updates connection settings before
-giving a connection to a client.
+Clients can set session-level variables, e.g., by passing them in connection parameters or using the `SET` command. This works fine when connecting to Postgres directly, but transaction poolers share server connections between multiple clients.
 
-#### Specifying connection parameters
+To avoid session-level state leaking between clients, PgDog tracks connection parameters for each client and updates connection settings before giving a connection to each client.
+
+This is performed efficiently, and server parameters are updated only if they differ from the ones set on the client.
+
+### Specifying connection parameters
 
 Most Postgres connection drivers support passing parameters in the connection URL. Using the special `options` setting, each parameter is set using the `-c` flag, for example:
 
@@ -48,20 +55,19 @@ postgres://user@host:6432/db?options=-c%20statement_timeout%3D3s
 ```
 
 This sets the `statement_timeout` setting to `3s` (3 seconds). Each time this client
-executes a transaction, PgDog will check the value for `statement_timeout` on the server connection,
-and if it differs, issue a command to Postgres to update it, e.g.:
+executes a transaction, the pooler will check the value for `statement_timeout` on the server connection,
+and if it differs, issue a command to Postgres to update it:
 
 ```postgresql
 SET statement_timeout TO '3s';
 ```
 
-
-#### Tracking `SET` commands
+### Tracking `SET` commands
 
 If the client manually changes server settings, i.e., by issuing `SET` commands, the server will send the updated setting
-in a `ParameterStatus` message. PgDog will see this message and update client connection parameters accordingly, as to avoid
+in a `ParameterStatus` message. The pooler will see this message and update client connection parameters accordingly, so as to avoid
 issuing unnecessary `SET` statements on subsequent transactions.
 
-#### Impact on latency
+### Impact on latency
 
-PgDog keeps a real-time mapping for servers and their parameters, so checking the current value for any parameter doesn't require PgDog to talk to the database. Additionally, it's typically expected that applications have similar connection parameters, so PgDog won't have to synchronize parameters frequently.
+PgDog keeps a real-time mapping of servers and their parameters, so checking the current value for any parameter doesn't require the pooler to talk to the database. Additionally, it's typically expected that applications have similar connection parameters, so the pooler won't have to synchronize parameters frequently.
diff --git a/docs/index.md b/docs/index.md
@@ -32,7 +32,7 @@ This documentation provides a detailed overview of all PgDog features, along wit
     </div>
     <div>
         <h4><a href="/administration/">Administration</a></h4>
-        <p>Learn how to operate PgDog in production, like fetching real time statistics from the admin database or updating configuration.</p>
+        <p>Learn how to operate PgDog in production, like fetching real-time statistics from the admin database or updating configuration.</p>
     </div>
     <div>
         <h4><a href="/installation/">Installation</a></h4>
diff --git a/docs/installation.md b/docs/installation.md
@@ -93,7 +93,7 @@ PgDog is configured via 2 files:
 
 Users are configured separately to allow them to be encrypted at rest in environments that support it, like in Kubernetes or with the AWS Secrets Manager.
 
-Both config files should to be placed in the current working directory (`$PWD`) for PgDog to detect them. Alternatively,
+Both config files should be placed in the current working directory (`$PWD`) for PgDog to detect them. Alternatively,
 you can pass their paths at startup as arguments:
 
 ```bash
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -27,7 +27,7 @@ Features around query execution in a direct-to-shard or multi-shard context.
 | Cross-shard queries | Queries spanning multiple shards are supported, for most simple use cases. See below for details. |
 | Cross-shard sorting | `SELECT ... ORDER BY ...`-style queries work automatically. Data types supported in the `ORDER BY` clause are: `BIGINT`, `INTEGER`, `TEXT`/`VARCHAR`. Missing: dates/timestamps, other Postgres types. |
 | Cross-shard aggregates | Basic aggregates like `count`, `max`, `min`, `sum` are supported with/without `GROUP BY` clause. Missing aggregates include: `avg`, `percentile_cont` (and `disc`), `JSON`, and others. Some require query rewriting. |
-| Query rewriting | Rewriting queries is only supported for renaming prepared statements. Query rewriting to support aggregates or cross-shard joins is not yet. |
+| Query rewriting | Rewriting queries is only supported for renaming prepared statements. Query rewriting to support aggregates or cross-shard joins is not yet implemented. |
 | Cross-shard joins | Not supported yet. Requires query rewriting and implementing inner/outer hash joins inside PgDog. |
 
 

Original file line number	Diff line number	Diff line change
`@@ -16,4 +16,4 @@ PgDog source code, so the whole community can benefit from your knowledge and ex`
`16`	`16`
`17`	`17`	`## Project name`
`18`	`18`
`19`		`-This project is dedicated to the bestest dog in the world who's been patiently sitting at my feet the entire time PgDog has been developed.`
	`19`	`+This project is dedicated to the best dog in the world who's been patiently sitting at my feet the entire time PgDog has been developed.`