Skip to content

Commit

Permalink
Small docs fixes (#757)
Browse files Browse the repository at this point in the history
* update router config docs

* update ALTER DISTRIBUTION syntax in docs

* fix internal link

* update get_started
  • Loading branch information
Denchick authored Sep 4, 2024
1 parent dbac4cc commit 0d5691d
Show file tree
Hide file tree
Showing 4 changed files with 82 additions and 15 deletions.
12 changes: 7 additions & 5 deletions docs/configuration/router.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -83,11 +83,13 @@ Map of string to Shard objects. Refer to the `Shard` struct in the [pkg/config/r

## Feature Flags

| Setting | Description | Possible Values |
|--------------------------|-----------------------------------------------|-----------------|
| `maintain_params` | Whether to maintain parameters flag. | `true`, `false` |
| `with_jaeger` | Whether to integrate with Jaeger for tracing. | `true`, `false` |
| `world_shard_fallback` | Whether to enable fallback to world shard. | `true`, `false` |
| Setting | Description | Possible Values |
|-----------------------------------------|-------------------------------------------------|-----------------|
| `maintain_params` | Whether to maintain parameters flag. | `true`, `false` |
| `query_routing.default_route_behaviour` | Whether to explicitly block multishard queries. | `BLOCK`, `` |
| `query_routing.multicast_unroutable_insert_statement` | Whether to send insert statements without a sharding key to all shards. | `true`, `false` |
| `with_jaeger` | Whether to integrate with Jaeger for tracing. | `true`, `false` |
| `world_shard_fallback` | Whether to enable fallback to world shard. | `true`, `false` |


## Mode Settings
Expand Down
23 changes: 15 additions & 8 deletions docs/sharding/console/sql_commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Description: 'Create distributions, key ranges and tables and see cluster info'
This command is used to create a new distribution with the specified name. Optionally, you can specify the column types for the distribution using the COLUMN TYPES clause.

```sql
CREATE DISTRIBUTION <distributionID> [COLUMN TYPES types]
CREATE DISTRIBUTION <distributionID> COLUMN TYPES <types>

where types is a comma-separated list of column types

Expand All @@ -23,16 +23,23 @@ This command is used to drop an existing distribution with the specified name. T
DROP DISTRIBUTION <distribution_name> [CASCADE]
```

### ALTER DISTRIBUTION
### ALTER DISTRIBUTION ATTACH RELATION

This command is used to alter an existing distribution. You can attach one or more relations to the distribution using the ATTACH RELATION clause, or detach a relation from the distribution using the DETACH RELATION clause.
This command is used to alter an existing distribution. You can attach one or more relations to the distribution using the ATTACH RELATION clause.

```sql
ALTER DISTRIBUTION <distribution_name>
[
ATTACH RELATION <relation_name> [, <relation_name> ...] |
DETACH RELATION <relation_name>
]
ALTER DISTRIBUTION <distribution_name> ATTACH RELATION <relation_name> [, <relation_name> ...]
DISTRIBUTION KEY <keys> [HASH FUNCTION <hash_function_name>]

where hash_function_name is one of: IDENTITY, MURMUR, CITY
```

### ALTER DISTRIBUTION DETACH RELATION

This command is used to alter an existing distribution. You can detach a relation from the distribution using the DETACH RELATION clause.

```sql
ALTER DISTRIBUTION <distribution_name> DETACH RELATION <relation_name>
```

### CREATE KEY RANGE
Expand Down
60 changes: 59 additions & 1 deletion docs/welcome/get_started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -93,4 +93,62 @@ CREATE KEY RANGE krid2 FROM 1000 ROUTE TO shard2 FOR DISTRIBUTION ds1;
(1 row)
```

Here we go! You can play with some SELECTs or INSERTs.
Here we go! You can play with some SELECTs or INSERTs.

### Connect to SPQR router

Now we can connect to proxy a.k.a. router and play with it:

```bash
➜ psql "host=localhost sslmode=disable user=demo dbname=demo port=6432"
psql (13.3, server 9.6.22)
Type "help" for help.

demo=> CREATE TABLE orders (
id SERIAL NOT NULL PRIMARY KEY,
customer_id INT,
order_date DATE
);
NOTICE: send query to shard(s) : shard01,shard02
CREATE TABLE

demo=> CREATE TABLE items (
id SERIAL NOT NULL PRIMARY KEY,
order_id SERIAL NOT NULL PRIMARY KEY,
name VARCHAR,
);
NOTICE: send query to shard(s) : shard01,shard02
CREATE TABLE

demo=> BEGIN;
BEGIN
demo=> INSERT INTO orders (id, customer_id, order_data) VALUES (777, 123456, '2024-01-08');
NOTICE: send query to shard(s) : shard01
INSERT 0 1
demo=> INSERT INTO items (id, order_id, name) VALUES (1, 777, 'elephant');
INSERT 0 1
demo=> COMMIT;
COMMIT
```

> NOTICE messages are disabled by default, specify `show_notice_messages` setting in the router config to enable them
You could check now that each shard has only one record:

```bash
demo=> SELECT * FROM orders WHERE id = 777;
NOTICE: send query to shard(s) : shard01
id | customer_id | order_data
------+-------------+--------------
777 | 123456 | '2024-01-08'
(1 row)

SPQR can handle such queries as `SELECT * FROM table` but we don't recommend using it. This feature is implemented in a non-transactional way.
```bash
demo=> SELECT * FROM orders WHERE id = 777;
NOTICE: send query to shard(s) : shard01
id | customer_id | order_data
------+-------------+--------------
777 | 123456 | '2024-01-08'
(1 row)
2 changes: 1 addition & 1 deletion docs/welcome/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ SPQR is a good fit for:
<Card
title="Internals"
icon="code"
href="/internals/balancing"
href="/sharding/cluster_components/overview"
>
Learn more how SPQR works under the hood
</Card>
Expand Down

0 comments on commit 0d5691d

Please sign in to comment.