save

Author: levkk

docs/features/sharding/2pc.md

@@ -31,7 +31,7 @@ ALTER SYSTEM SET max_prepared_transactions TO 1000;
 Alternatively, if you're running on managed Postgres (e.g., AWS RDS), this parameter can usually be set through your cloud admin panel.
 
 !!! note
-     This parameter can only be enabled on server start. Once you change it, make sure to restart your Postgres servers.
+     Changes to this parameter require a server restart to take effect.
 
 Once prepared transactions are enabled in Postgres, two-phase commit can be enabled in [`pgdog.toml`](../../configuration/pgdog.toml/general.md):
 

docs/features/sharding/cross-shard-queries/copy.md

@@ -38,7 +38,7 @@ The cost of parsing and sharding the CSV stream in PgDog is negligibly small.
 
 ## COPY out
 
-All `COPY [...] TO STDOUT` statements are treated as cross-shard and are executed on all shards concurrently. The rows are streamed directly, without buffering or sorting, which allows to read large amounts of data from all shards quickly.
+All `COPY [...] TO STDOUT` statements are treated as cross-shard and are executed on all shards concurrently. The rows are streamed directly, without buffering or sorting, which allows reading large amounts of data from all shards quickly.
 
 PgDog doesn't currently support routing `COPY` statements based on its query. For example, the following statement will be sent to all shards even if it contains a sharding key:
 

docs/features/sharding/cross-shard-queries/ddl.md

@@ -4,11 +4,11 @@ icon: material/table-cog
 
 # CREATE, ALTER, DROP
 
-`CREATE`, `ALTER` and `DROP`, also known as **D**ata **D**efinition **L**anguage (DDL), are by design, cross-shard statements. When a client sends over a DDL command, PgDog will send it to all shards in parallel, ensuring the table, index, view and sequence definitions are identical across the database cluster.
+`CREATE`, `ALTER` and `DROP`, also known as **D**ata **D**efinition **L**anguage (DDL), are, by design, cross-shard statements. When a client sends over a DDL command, PgDog will send it to all shards in parallel, ensuring the table, index, view and sequence definitions are identical across the database cluster.
 
 ## Atomicity
 
-DDL statements should be atomic across all shards. This is to protect against a single shard failure to create a table or index, which could result in an inconsistent schema. PgDog can use [two-phase commit](../2pc.md) to ensure this is the case, however that means that all DDL statements must be executed inside a transaction, for example:
+DDL statements should be atomic across all shards. This is to protect against a single shard failing to create a table or index, which could result in an inconsistent schema. PgDog can use [two-phase commit](../2pc.md) to ensure this is the case, however that means that all DDL statements must be executed inside a transaction, for example:
 
 ```postgresql
 BEGIN;

docs/features/sharding/cross-shard-queries/index.md

@@ -21,7 +21,7 @@ Just like with [direct-to-shard](../query-routing.md) queries, each SQL command
 - [`SELECT`](select.md)
 - [`INSERT`](insert.md)
 - [`UPDATE`, `DELETE`](update.md)
-- [`CREATE`, `ALTER`, `DROP`](ddl.md)(and other DDL statements)
+- [`CREATE`, `ALTER`, `DROP`](ddl.md) (and other DDL statements)
 - [`COPY`](copy.md)
 
 
@@ -62,7 +62,7 @@ If you don't want PgDog to route cross-shard queries, e.g., because you have a [
 cross_shard_disabled = true
 ```
 
-If this feature is enabled, and a query doesn't have a sharding key, instead of executing the query, PgDog will return an error and abort the transaction.
+When this setting is enabled and a query doesn't have a sharding key, instead of executing the query, PgDog will return an error and abort the transaction.
 
 ## Read more
 

docs/features/sharding/cross-shard-queries/insert.md

@@ -10,15 +10,15 @@ If an `INSERT` statement specifies only one sharding key, it's sent [directly](.
 
 Cross-shard `INSERT` statements fall into one of three categories, each one handled differently:
 
-1. `INSERT` targetting [omnisharded tables](#omnisharded-tables)
-2. `INSERT` targetting a [sharded table](#sharded-insert), with no sharding key specified
+1. `INSERT` targeting [omnisharded tables](#omnisharded-tables)
+2. `INSERT` targeting a [sharded table](#sharded-tables), with no sharding key specified
 3. `INSERT` with [multiple tuples](#multiple-tuples), each destined for a different shard
 
 By design, applications using PgDog don't need to concern themselves with this and can use the database normally. However, there are some trade-offs when using cross-shard queries, documented below.
 
 ## Omnisharded tables
 
-Queries that target [omnisharded](../omnishards.md) tables, the statement is sent to all shards concurrently. This ensures that the data is identical on all shards, for example:
+For queries that target [omnisharded](../omnishards.md) tables, the statement is sent to all shards concurrently. This ensures that the data is identical on all shards, for example:
 
 ```postgresql
 INSERT INTO request_logs
@@ -43,7 +43,7 @@ VALUES
 COMMIT;
 ```
 
-This gives you a much higher chance of recording rows on all shards, since you will know if your statement violated some contstraint (e.g., unique index or `NOT NULL` check) before committing the transaction.
+This gives you a much higher chance of recording rows on all shards, since you will know if your statement violated some constraint (e.g., unique index or `NOT NULL` check) before committing the transaction.
 
 ### Primary keys
 
@@ -57,7 +57,7 @@ To use unique IDs as primary keys (or in any other column) in omnisharded tables
 INSERT INTO ip_logs
     (id, client_ip, created_at)
 VALUES
-    (pgdog.unqiue_id(), $1, now());
+    (pgdog.unique_id(), $1, now());
 ```
 
 The function is evaluated inside PgDog which places the value it returns directly into the query. This works for all queries, including prepared statements.
@@ -82,21 +82,21 @@ This function can be used with any tables, not just omnisharded ones, or indepen
 
 ## Sharded tables
 
-`INSERT` statements targetting sharded tables will commonly provide the sharding key. A notable exception to this rule is tables that shard on the primary key, which is often database-generated, e.g., using a sequence.
+`INSERT` statements targeting sharded tables will commonly provide the sharding key. A notable exception to this rule is tables that shard on the primary key, which is often database-generated, e.g., using a sequence.
 
 The simplest way to work around this is to use the `pgdog.unique_id()` function to create a unique identifier on the fly, for example:
 
 ```postgresql
 INSERT INTO users
     (id, email, created_at)
 VALUES
-    (pgdog.unqiue_id(), $1, $2)
+    (pgdog.unique_id(), $1, $2)
 RETURNING *;
 ```
 
-If however, you prefer to use sequences instead, you can rely on [database-generated](../schema_management/primary_keys.md) primary keys.
+However, if you prefer to use sequences instead, you can rely on [database-generated](../schema_management/primary_keys.md) primary keys.
 
-Statements that don't include the primary key in the `INSERT` tuple will be sent to one of the shards, using same round robin algorithm used for [omnisharded](#omnisharded-tables) tables. The shard will then generate the primary key value using PgDog's [sharded sequences](../schema_management/primary_keys.md#pgdognext_id_seq).
+Statements that don't include the primary key in the `INSERT` tuple will be sent to one of the shards, using the same round robin algorithm used for [omnisharded](#omnisharded-tables) tables. The shard will then generate the primary key value using PgDog's [sharded sequences](../schema_management/primary_keys.md#pgdognext_id_seq).
 
 For example, assuming the table `users` is sharded on the primary key `id`, omitting it from the `INSERT` statement will send it to only one of the shards:
 
@@ -153,7 +153,7 @@ INSERT INTO users (email, created_at) VALUES ($1, $2), ($3, $4);
 COMMIT; -- or ROLLBACK;
 ```
 
-If a transaction isn't started and a multi-tuple statement are sent by the application, PgDog will return an error and abort the request.
+If a transaction isn't started and a multi-tuple statement is sent by the application, PgDog will return an error and abort the request.
 
 Requiring transactions ensures that if one of the `INSERT` statements fails, e.g., because of a unique constraint violation, the transaction can be rolled back, leaving the database in a consistent state.
 

docs/features/sharding/cross-shard-queries/select.md

@@ -13,7 +13,7 @@ When PgDog receives a `SELECT` query with no (or multiple) sharding keys, it con
 If the result needs post-processing, e.g., to support [sorting](#sorting) or [aggregation](#aggregates), it will buffer the rows in memory and perform the necessary operations. Otherwise, PgDog will stream the rows directly to the client.
 
 !!! note "Predicate push-down"
-    PgDog pushes all filtering, sorting and aggregation statements to the database. If the query is correctly constructed, the shards will return very few rows, allowing to search vast quantities of data without causing out-of-memory errors or latency issues in the proxy.
+    PgDog pushes all filtering, sorting and aggregation statements to the database. If the query is correctly constructed, the shards will return very few rows, allowing searches of vast quantities of data without causing out-of-memory errors or latency issues in the proxy.
 
 ## Supported features
 
@@ -25,9 +25,9 @@ The SQL language allows for powerful data filtration and manipulation. While we
 | `ORDER BY` | :material-check: | Columns must be part of the returned tuples. See [sorting](#sorting). |
 | `DISTINCT` / `DISTINCT BY`| :material-check: | Columns must be part of the returned tuples. |
 | `GROUP BY` | :material-wrench: | Columns must be part of the returned tuples. See [aggregates](#aggregates). |
-| CTEs | :material-wrench: | CTE must refer to data located on the same shard. See [CTEs](#ctes) |
+| CTEs | :material-wrench: | CTE must refer to data located on the same shard. |
 | Window functions | :material-close: | Not currently supported. |
-| Subqueries | :material-wrench: | Subqueries must refer to data located on the same shard. See [subqueries](#subqueries). |
+| Subqueries | :material-wrench: | Subqueries must refer to data located on the same shard. |
 
 ## Sorting
 
@@ -38,7 +38,7 @@ Currently, two forms of the `ORDER BY` SQL syntax are supported:
 | Syntax |  Example | Notes |
 |-|-|-|
 | Order by column name |  `ORDER BY id, email` | The column must be present in the returned tuples. |
-| Order by column position  | `ORDER BY 1, 2` |  The column is refernced by its position in the returned tuples. |
+| Order by column position  | `ORDER BY 1, 2` |  The column is referenced by its position in the returned tuples. |
 
 Sorting by multiple columns is supported, including opposing sorting directions, for example:
 
@@ -85,7 +85,7 @@ FROM users ORDER BY
 
 ORMs like SQLAlchemy or ActiveRecord, more often than not, will write queries that work with PgDog out of the box. This is because they tend to fetch entire rows and use fully-qualified names in all parts of the statement, including the `ORDER BY` clause.
 
-For example, this is how a [`first`](https://apidock.com/rails/ActiveRecord/FinderMethods/first) Rails/ActiveRecord query looks like:
+For example, this is what a [`first`](https://apidock.com/rails/ActiveRecord/FinderMethods/first) Rails/ActiveRecord query looks like:
 
 ```postgresql
 SELECT * FROM users ORDER BY users.id LIMIT 1
@@ -104,7 +104,7 @@ If an aggregate function is supported (see list of supported functions below), t
 | `count`, `count(*)` | :material-check: | Works for most [data types](#supported-data-types). |
 | `max`, `min`, `avg`, `sum` | :material-check: | Works for most [data types](#supported-data-types). |
 | `stddev`, `variance` | :material-check: | Works for most [data types](#supported-data-types).|
-| `percentile_disc`, `percentile_cont` | :material-close: | Doesn't work currently and very expensive to calculate on large datasets. |
+| `percentile_disc`, `percentile_cont` | :material-close: | Not currently supported and very expensive to calculate on large datasets. |
 | `*_agg` | :material-close: | Not currently supported. |
 | `json_*` | :material-close: | Not currently supported.  |
 
@@ -126,7 +126,7 @@ The `HAVING` clause requires additional filtering of the results and is not curr
 
 For some aggregate functions to work as expected, each shard may need to return columns and intermediate calculations not present in the original query.
 
-For example, to get an average of a column, we need to fetch the row `count`, multiply it by the `avg` the column on each shard, and divide it by the total `count` of rows on all shards.
+For example, to get an average of a column, we need to fetch the row `count`, multiply it by the `avg` of the column on each shard, and divide it by the total `count` of rows on all shards.
 
 If the `count` function isn't present in the query, PgDog will automatically rewrite the query to add it. This allows queries, like the following example, to just work without modifications:
 

docs/features/sharding/cross-shard-queries/update.md

@@ -41,19 +41,19 @@ When a client sends such a statement, PgDog will rewrite it into three statement
 
 1. `SELECT` statement to fetch the row from the database
 2. `INSERT` statement to create that row on the new shard, with updated values
-2. `DELETE` statement to remove the now stale row from the old shard
+3. `DELETE` statement to remove the now stale row from the old shard
 
 The entire exchange looks like this:
 
 ```postgresql
 -- Old `id` value.
 SELECT * FROM users WHERE id = $1;
 
- -- New `id` value, with columns retrieved by the previous query.
+-- New `id` value, with columns retrieved by the previous query.
 INSERT INTO users (id, email, created_at)
 VALUES ($1, $2, $3);
 
- -- Old `id` value.
+-- Old `id` value.
 DELETE FROM users WHERE id = $1;
 ```
 
@@ -81,13 +81,13 @@ shard_key = "rewrite"
 
 ### Updating multiple rows
 
-While multi-row updates are supported, changing multiple rows' sharding keys is not. If the `UPDATE` statement `WHERE` clause returns more than one row, PgDog will abort the transaction and return an error.
+While multi-row updates are supported, changing multiple rows' sharding keys is not. If the `UPDATE` statement's `WHERE` clause matches more than one row, PgDog will abort the transaction and return an error.
 
 This check happens early in the transaction and will not create partial updates to the database.
 
 ### Efficiency
 
-It's common practice for ORMs, like ActiveRecord or SQLAlchemy to mutate entire rows when saving records. Take the following example:
+It's common practice for ORMs, like ActiveRecord or SQLAlchemy, to mutate entire rows when saving records. Take the following example:
 
 === "ActiveRecord"
     ```ruby
@@ -106,6 +106,7 @@ It's common practice for ORMs, like ActiveRecord or SQLAlchemy to mutate entire
 While the sharding key (`id`) is technically updated in the query, its value doesn't change. To avoid unnecessary overhead, PgDog performs multiple checks on the new row before performing the [three statement](#how-it-works) sharding key update flow:
 
 1. If the value of the sharding key parameter (`SET id = $1`) is the same as it is in the `WHERE` clause (`WHERE id = $1`), the query is routed directly to the shard without modifications.
-2. If the values are different, or the `WHERE` clause doesn't specify the sharding key, PgDog will check the value of the key returned by the first `SELECT` statement in the flow. If both keys map to the _same_ shard, will send the query directly to that shard, without modifications.
+2. If the values are different, or the `WHERE` clause doesn't specify the sharding key, PgDog will check the value of the key returned by the first `SELECT` statement in the flow. If both keys map to the _same_ shard, PgDog will send the query directly to that shard, without modifications.
+
 
- Updating the sharding key isn't a frequent operation and both of these mechanisms ensure that the more expensive algorithm isn't triggered unnecessarily.
+Updating the sharding key isn't a frequent operation and both of these mechanisms ensure that the more expensive algorithm isn't triggered unnecessarily.

docs/features/sharding/index.md

@@ -8,7 +8,7 @@ Sharding splits a PostgreSQL database and all its tables and indices between mul
 
 ## Intro to sharding
 
-If you're not familiar with database sharding fundamentals, take a look at the [sharding basics](basics.md). Even if you're a seasoned database expert, it's good to have a refresher to confirm your understanding matches with our implementation.
+If you're not familiar with database sharding fundamentals, take a look at the [sharding basics](basics.md). Even if you're a seasoned database expert, it's good to have a refresher to confirm your understanding matches our implementation.
 
 [**→ Sharding basics**](basics.md)
 
@@ -41,6 +41,6 @@ Resharding takes a database cluster with _N_ shards (where _N_ can be 1, for uns
 
 ### Schema management
 
-PgDog makes sure that database schema is identical on all shards. It also has support for in-database primary key generation.
+PgDog makes sure that the database schema is identical on all shards. It also has support for in-database primary key generation.
 
 [**→ Schema management**](schema_management/index.md)

docs/features/sharding/supported-queries.md

@@ -3,7 +3,7 @@ icon: material/check-bold
 ---
 # Supported queries
 
-[Automatic routing](query-routing.md) in PgDog works by parsing queries and extracting the sharding key. SQL is a complex language and we are aiming to support as many queries as possible. As the development moves forward, this page will be updated with latest features.
+[Automatic routing](query-routing.md) in PgDog works by parsing queries and extracting the sharding key. SQL is a complex language and we are aiming to support as many queries as possible. As the development moves forward, this page will be updated with the latest features.
 
 Postgres has 3 kinds of queries, each handled a little bit differently in a sharded context:
 
@@ -52,7 +52,7 @@ Queries that don't specify a sharding key or specify more than one will be route
 
 ### `UPDATE` and `DELETE`
 
-Both `UPDATE` and `DELETE` queries work the same way as `SELECT` queries. The `WHERE` clause and any CTEs are checked for a sharding key, using any of the supported patterns and if a key is found, the query is routed to directly to one shard. Statements without a key are sent to all shards, in parallel.
+Both `UPDATE` and `DELETE` queries work the same way as `SELECT` queries. The `WHERE` clause and any CTEs are checked for a sharding key, using any of the supported patterns, and if a key is found, the query is routed directly to one shard. Statements without a key are sent to all shards, in parallel.
 
 #### Examples