|
| 1 | +--- |
| 2 | +icon: material/function-variant |
| 3 | +--- |
| 4 | + |
| 5 | +# Schema manager functions |
| 6 | + |
| 7 | +The [schema manager](index.md) uses PL/pgSQL functions to generate shard-aware identifiers and perform other actions inside the database to make sharding work. These functions are documented below. |
| 8 | + |
| 9 | +## Functions |
| 10 | + |
| 11 | +### `pgdog.next_id_seq` |
| 12 | + |
| 13 | +The `pgdog.next_id_seq` function generates a unique, shard-aware `BIGINT` number that can be used as a primary key. It accepts the following arguments: |
| 14 | + |
| 15 | +| Argument | Data type | Description | |
| 16 | +|-|-|-| |
| 17 | +| `sequence_name` | `regclass` | The sequence used as basis for generating integers. | |
| 18 | +| `table_name` | `regclass` | The partitioned by hash table which is required for `satisfies_hash_partition` to extract the hash data type. | |
| 19 | + |
| 20 | +If not specified, `table_name` will default to `'pgdog.validator_bigint'::regclass`, so this function can be used with any Postgres sequence. For [sharded sequences](../sequences.md), a special table is created in the `pgdog_internal` schema for each sharded sequence, to avoid lock contention on a single Postgres catalog entity. |
| 21 | + |
| 22 | +#### Sequence cache |
| 23 | + |
| 24 | +When looking for the next valid number, `next_id_seq` will consume several values from the sequence in a row. By default, each call to `nextval` requires a write to the WAL, which could be a bit slower than optimal. To mitigate this, we automatically increase the sequence's cache size to 100, which is usually enough to generate the next value entirely in memory. |
| 25 | + |
| 26 | +### `pgdog.next_uuid_auto` |
| 27 | + |
| 28 | +The `pgdog.next_uuid_auto` function generates a unique, shard-aware `UUID` value which can be used as a primary key. It accepts no arguments and uses `pgdog.validator_uuid` as basis for calling `satisfies_hash_partition`. |
| 29 | + |
| 30 | +##### Example |
| 31 | + |
| 32 | +=== "Function" |
| 33 | + ```postgresql |
| 34 | + SELECT pgdog.next_uuid_auto(); |
| 35 | + ``` |
| 36 | +=== "Output" |
| 37 | + ``` |
| 38 | + next_uuid_auto |
| 39 | + -------------------------------------- |
| 40 | + f54c49c1-47f6-4ca1-a108-782286e447c3 |
| 41 | + ``` |
| 42 | + |
| 43 | +UUID generation is not a big problem for sharded databases, since clients can generate and provide UUIDs as part of a query. PgDog still supports generating shard-aware UUIDs in the database, so this function can be configured as a default instead of `gen_random_uuid()`, for example: |
| 44 | + |
| 45 | +```postgresql |
| 46 | +CREATE TABLE measurements ( |
| 47 | + id UUID PRIMARY KEY DEFAULT pgdog.next_uuid_auto(), |
| 48 | + value REAL NOT NULL, |
| 49 | + created_at TIMESTAMPTZ NOT NULL DEFAULT now() |
| 50 | +); |
| 51 | +``` |
| 52 | + |
| 53 | +### `pgdog.install_sharded_sequence` |
| 54 | + |
| 55 | +The `pgdog.install_sharded_sequence` function replaces the `DEFAULT` value for a table column with a call to [`pgdog.next_id_seq`](#pgdognext_id_seq). It accepts the following arguments: |
| 56 | + |
| 57 | +| Argument | Data type | Description | |
| 58 | +|-|-|-| |
| 59 | +| `schema_name` | `text` | The name of the schema where the table resides. This is commonly `public` but can be any other schema. | |
| 60 | +| `table_name` | `text` | The name of the table that contains the primary key column. | |
| 61 | +| `column_name` | `text` | The name of the primary key column. | |
| 62 | +| `lock_timeout` | `text` | Maximum amount of time this function call will be allowed to block other queries from accessing this table while it mutates the schema definition. This is set to `1s` by default. | |
| 63 | + |
| 64 | +Under the hood, this function will create two entities: |
| 65 | + |
| 66 | +1. A regular Postgres sequence (using `CREATE SEQUENCE`) |
| 67 | +2. A copy of the table specified in `table_name` in the `pgdog_internal` schema and set that as the `table_name` argument for `pgdog.next_id_seq` |
| 68 | + |
| 69 | +One table and sequence is created per column, so it's possible to install multiple sharded sequences into the same table. Creating separate tables for each sharded sequence prevents lock contention on Postgres catalog entities while generating values. |
0 commit comments