You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: contrib/pg_pathman/README.md
+82-48Lines changed: 82 additions & 48 deletions
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,12 @@
7
7
8
8
The `pg_pathman` module provides optimized partitioning mechanism and functions to manage partitions.
9
9
10
-
The extension is compatible with PostgreSQL 9.5+.
10
+
The extension is compatible with:
11
+
* PostgreSQL 9.5, 9.6, 10;
12
+
* Postgres Pro Standard 9.5, 9.6;
13
+
* Postgres Pro Enterprise;
14
+
15
+
By the way, we have a growing Wiki [out there](https://github.com/postgrespro/pg_pathman/wiki).
11
16
12
17
## Overview
13
18
**Partitioning** means splitting one large table into smaller pieces. Each row in such table is moved to a single partition according to the partitioning key. PostgreSQL supports partitioning via table inheritance: each partition must be created as a child table with CHECK CONSTRAINT. For example:
@@ -41,6 +46,7 @@ More interesting features are yet to come. Stay tuned!
41
46
## Feature highlights
42
47
43
48
* HASH and RANGE partitioning schemes;
49
+
* Partitioning by expression and composite key;
44
50
* Both automatic and manual partition management;
45
51
* Support for integer, floating point, date and other types, including domains;
46
52
* Effective query planning for partitioned tables (JOINs, subselects etc);
@@ -55,9 +61,11 @@ More interesting features are yet to come. Stay tuned!
* Optimize hash join (both tables are partitioned by join key).
68
+
Take a look at [this page](https://github.com/postgrespro/pg_pathman/wiki/Roadmap);
61
69
62
70
## Installation guide
63
71
To install `pg_pathman`, execute this in the module's directory:
@@ -97,47 +105,49 @@ SET pg_pathman.enable = t;
97
105
### Partition creation
98
106
```plpgsql
99
107
create_hash_partitions(relation REGCLASS,
100
-
attributeTEXT,
108
+
expr TEXT,
101
109
partitions_count INTEGER,
102
110
partition_data BOOLEAN DEFAULT TRUE,
103
111
partition_names TEXT[] DEFAULT NULL,
104
112
tablespaces TEXT[] DEFAULT NULL)
105
113
```
106
-
Performs HASH partitioning for `relation` by integer key `attribute`. The `partitions_count` parameter specifies the number of partitions to create; it cannot be changed afterwards. If `partition_data` is `true` then all the data will be automatically copied from the parent table to partitions. Note that data migration may took a while to finish and the table will be locked until transaction commits. See `partition_table_concurrently()` for a lock-free way to migrate data. Partition creation callback is invoked for each partition if set beforehand (see `set_init_callback()`).
114
+
Performs HASH partitioning for `relation` by partitioning expression `expr`. The `partitions_count` parameter specifies the number of partitions to create; it cannot be changed afterwards. If `partition_data` is `true` then all the data will be automatically copied from the parent table to partitions. Note that data migration may took a while to finish and the table will be locked until transaction commits. See `partition_table_concurrently()` for a lock-free way to migrate data. Partition creation callback is invoked for each partition if set beforehand (see `set_init_callback()`).
107
115
108
116
```plpgsql
109
-
create_range_partitions(relation REGCLASS,
110
-
attribute TEXT,
111
-
start_value ANYELEMENT,
112
-
p_interval ANYELEMENT,
113
-
p_count INTEGER DEFAULT NULL
114
-
partition_data BOOLEAN DEFAULT TRUE)
117
+
create_range_partitions(relation REGCLASS,
118
+
expression TEXT,
119
+
start_value ANYELEMENT,
120
+
p_interval ANYELEMENT,
121
+
p_count INTEGER DEFAULT NULL
122
+
partition_data BOOLEAN DEFAULT TRUE)
123
+
124
+
create_range_partitions(relation REGCLASS,
125
+
expression TEXT,
126
+
start_value ANYELEMENT,
127
+
p_interval INTERVAL,
128
+
p_count INTEGER DEFAULT NULL,
129
+
partition_data BOOLEAN DEFAULT TRUE)
115
130
116
-
create_range_partitions(relation REGCLASS,
117
-
attributeTEXT,
118
-
start_valueANYELEMENT,
119
-
p_interval INTERVAL,
120
-
p_countINTEGER DEFAULT NULL,
121
-
partition_data BOOLEAN DEFAULT TRUE)
131
+
create_range_partitions(relation REGCLASS,
132
+
expressionTEXT,
133
+
bounds ANYARRAY,
134
+
partition_names TEXT[] DEFAULT NULL,
135
+
tablespacesTEXT[] DEFAULT NULL,
136
+
partition_data BOOLEAN DEFAULT TRUE)
122
137
```
123
-
Performs RANGE partitioning for `relation` by partitioning key `attribute`, `start_value` argument specifies initial value, `p_interval` sets the default range for auto created partitions or partitions created with `append_range_partition()` or `prepend_range_partition()` (if `NULL` then auto partition creation feature won't work), `p_count` is the number of premade partitions (if not set then `pg_pathman` tries to determine it based on attribute values). Partition creation callback is invoked for each partition if set beforehand.
138
+
Performs RANGE partitioning for `relation` by partitioning expression `expr`, `start_value` argument specifies initial value, `p_interval` sets the default range for auto created partitions or partitions created with `append_range_partition()` or `prepend_range_partition()` (if `NULL` then auto partition creation feature won't work), `p_count` is the number of premade partitions (if not set then `pg_pathman` tries to determine it based on expression's values). The `bounds` array can be built using `generate_range_bounds()`. Partition creation callback is invoked for each partition if set beforehand.
124
139
125
140
```plpgsql
126
-
create_partitions_from_range(relation REGCLASS,
127
-
attribute TEXT,
128
-
start_value ANYELEMENT,
129
-
end_value ANYELEMENT,
130
-
p_interval ANYELEMENT,
131
-
partition_data BOOLEAN DEFAULT TRUE)
141
+
generate_range_bounds(p_start ANYELEMENT,
142
+
p_interval INTERVAL,
143
+
p_count INTEGER)
132
144
133
-
create_partitions_from_range(relation REGCLASS,
134
-
attribute TEXT,
135
-
start_value ANYELEMENT,
136
-
end_value ANYELEMENT,
137
-
p_interval INTERVAL,
138
-
partition_data BOOLEAN DEFAULT TRUE)
145
+
generate_range_bounds(p_start ANYELEMENT,
146
+
p_interval ANYELEMENT,
147
+
p_count INTEGER)
139
148
```
140
-
Performs RANGE-partitioning from specified range for `relation` by partitioning key `attribute`. Partition creation callback is invoked for each partition if set beforehand.
149
+
Builds `bounds` array for `create_range_partitions()`.
150
+
141
151
142
152
### Data migration
143
153
@@ -157,7 +167,7 @@ Stops a background worker performing a concurrent partitioning task. Note: worke
157
167
```plpgsql
158
168
create_hash_update_trigger(parent REGCLASS)
159
169
```
160
-
Creates the trigger on UPDATE for HASH partitions. The UPDATE trigger isn't created by default because of the overhead. It's useful in cases when the key attribute might change.
170
+
Creates the trigger on UPDATE for HASH partitions. The UPDATE trigger isn't created by default because of the overhead. It's useful in cases when the partitioning expression's value might change.
161
171
```plpgsql
162
172
create_range_update_trigger(parent REGCLASS)
163
173
```
@@ -267,18 +277,22 @@ Set partition creation callback to be invoked for each attached or created parti
267
277
```json
268
278
/* RANGE-partitioned table abc (child abc_4) */
269
279
{
270
-
"parent": "abc",
271
-
"parttype": "2",
272
-
"partition": "abc_4",
273
-
"range_max": "401",
274
-
"range_min": "301"
280
+
"parent": "abc",
281
+
"parent_schema": "public",
282
+
"parttype": "2",
283
+
"partition": "abc_4",
284
+
"partition_schema": "public",
285
+
"range_max": "401",
286
+
"range_min": "301"
275
287
}
276
288
277
289
/* HASH-partitioned table abc (child abc_0) */
278
290
{
279
-
"parent": "abc",
280
-
"parttype": "1",
281
-
"partition": "abc_0"
291
+
"parent": "abc",
292
+
"parent_schema": "public",
293
+
"parttype": "1",
294
+
"partition": "abc_0",
295
+
"partition_schema": "public"
282
296
}
283
297
```
284
298
@@ -293,9 +307,10 @@ When INSERTing new data beyond the partitioning range, use SpawnPartitionsWorker
293
307
```plpgsql
294
308
CREATETABLEIF NOT EXISTS pathman_config (
295
309
partrel REGCLASS NOT NULLPRIMARY KEY,
296
-
attnameTEXTNOT NULL,
310
+
expr TEXTNOT NULL,
297
311
parttype INTEGERNOT NULL,
298
-
range_interval TEXT);
312
+
range_interval TEXT,
313
+
cooked_expr TEXT);
299
314
```
300
315
This table stores a list of partitioned tables.
301
316
@@ -306,7 +321,7 @@ CREATE TABLE IF NOT EXISTS pathman_config_params (
306
321
enable_parent BOOLEANNOT NULL DEFAULT TRUE,
307
322
auto BOOLEANNOT NULL DEFAULT TRUE,
308
323
init_callback REGPROCEDURE NOT NULL DEFAULT 0,
309
-
spawn_using_bgw BOOLEANNOT NULL DEFAULT FALSE);
324
+
spawn_using_bgw BOOLEANNOT NULL DEFAULT FALSE);
310
325
```
311
326
This table stores optional parameters which override standard behavior.
312
327
@@ -337,7 +352,7 @@ RETURNS TABLE (
337
352
parent REGCLASS,
338
353
partition REGCLASS,
339
354
parttype INT4,
340
-
partattrTEXT,
355
+
expr TEXT,
341
356
range_min TEXT,
342
357
range_max TEXT)
343
358
AS'pg_pathman', 'show_partition_list_internal'
@@ -348,6 +363,23 @@ AS SELECT * FROM show_partition_list();
348
363
```
349
364
This view lists all existing partitions, as well as their parents and range boundaries (NULL for HASH partitions).
0 commit comments