document schema cache

Author: levkk

docs/features/sharding/schema_management/cache.md

@@ -0,0 +1,54 @@
+---
+icon: material/cached
+---
+
+# Schema cache
+
+To be able to automatically detect sharded and omnisharded tables, PgDog fetches the Postgres schema from all shards on startup. The schema is placed into an in-memory cache and contains Postgres schema names, tables and their columns, including data types.
+
+## How it works
+
+The schema cache allows PgDog to detect the column order in certain queries and extract sharding keys automatically. For example, consider the following table and query:
+
+```postgresql
+CREATE TABLE users (
+    id BIGINT PRIMARY KEY,
+    email VARCHAR NOT NULL UNIQUE
+);
+```
+
+When an `INSERT` query without explicit column names is executed, PgDog will be able to extract the sharding key using the schema cache:
+
+```postgresql
+INSERT INTO users VALUES ($1, $2);
+-- $1 is id
+-- $2 is email
+```
+
+### Omnisharded check
+
+In addition to detecting sharding keys, PgDog uses the schema cache to determine if a table is sharded or omnisharded. If a sharded table is configured using a column name only in [`pgdog.toml`](../../../configuration/pgdog.toml/sharded_tables.md), inspecting its schema is the only way to find if it has the sharding key, for example:
+
+```toml
+[[sharded_tables]]
+database = "prod"
+column = "user_id"
+```
+
+When a query comes in that doesn't specify this column, PgDog needs to decide if the table is sharded or omnisharded:
+
+```postgresql
+SELECT * FROM users WHERE created_at > NOW() - INTERVAL '1 hour';
+```
+
+PgDog will inspect its in-memory schema cache for the `users` table (taking into consideration the `search_path` setting), and if the table contains the `user_id` column, treat it as a [cross-shard `SELECT`](../cross-shard-queries/select.md). Otherwise, it'll assume the table is [omnisharded](../omnishards.md) and send the query to one of the shards only.
+
+### Migrations
+
+If you change your database schema, e.g. add a new table or alter an existing one, make sure to reload the schema cache, so PgDog is able to route queries correctly. To reload the schema cache, just run the [`RELOAD`](../../../administration/index.md) command via the admin database:
+
+```
+RELOAD;
+```
+
+The cache is reloaded every time PgDog re-creates its connection pools, so executing the `RECONNECT` command or restarting PgDog will have the same effect.

docs/features/sharding/schema_management/index.md

@@ -5,6 +5,12 @@ icon: material/database
 
 Schemas in sharded databases require additional tooling and maintenance to work correctly. Most aspects of this are handled by PgDog automatically and documented below.
 
+## Schema cache
+
+If your database is sharded, PgDog will automatically load the schema from all shards on startup and use it to detect sharded and omnisharded tables.
+
+[**→ Schema cache**](cache.md)
+
 ### Schema manager
 
 Tooling and automation for managing tables, indexes, primary keys, and other schema entities.

docs/features/sharding/schema_management/manager.md

@@ -1,6 +1,7 @@
 ---
 icon: material/knob
 ---
+
 # Schema manager
 
 PgDog provides several tools for sharded schema management. Currently, most of the functionality is implemented in Postgres with pl/PgSQL functions. To take advantage of it, you need to install these functions into your sharded database.

docs/features/sharding/supported-queries.md

@@ -33,16 +33,16 @@ SELECT * FROM users WHERE id IN ($1, $2, $3);
 The sharding key can be present anywhere in the query, including a join, a subquery, or a CTE. For example:
 
 ```postgresql
---- Join.
+-- Join.
 SELECT * FROM users
 INNER JOIN orders ON users.id = $1 AND orders.user_id = users.id;
 
---- Subquery.
+-- Subquery.
 SELECT * FROM users WHERE id IN (
     SELECT user_id FROM orders WHERE user_id = $1
 );
 
---- CTE.
+-- CTE.
 WITH my_user AS (
     SELECT * FROM users WHERE id = $1
 ) SELECT * FROM my_user;
@@ -64,10 +64,11 @@ DELETE FROM users WHERE id IN ($1, $2, $3);
 
 ### `INSERT`
 
-`INSERT` queries need to specify the column names in order for PgDog to be able to extract the sharding key from the tuple:
+`INSERT` queries can take two forms: specifying column names explicitly or implicitly. PgDog is able to detect the sharding key in both cases (using its [schema cache](schema_management/cache.md)) and route the query correctly:
 
 ```postgresql
 INSERT INTO users (id, email) VALUES ($1, $2);
+INSERT INTO users VALUES ($1, $2);
 ```
 
 Statements with multiple tuples can be [rewritten automatically](cross-shard-queries/insert.md#multiple-tuples) to write each row to its corresponding shard.