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: README.md
+82-35
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.
Drop partitions of the `parent` table (both foreign and local relations). If `delete_data` is `false`, the data is copied to the parent table first. Default is `false`.
243
253
254
+
To remove partitioned table along with all partitions fully, use conventional
255
+
`DROP TABLE relation CASCADE`. However, care should be taken in somewhat rare
256
+
case when you are running logical replication and `DROP` was executed by
257
+
replication apply worker, e.g. via trigger on replicated table. `pg_pathman`
258
+
uses `pathman_ddl_trigger` event trigger to remove the record about dropped
259
+
table from `pathman_config`, and this trigger by default won't fire on replica,
260
+
leading to inconsistent state when `pg_pathman` thinks that the table still
261
+
exists, but in fact it doesn't. If this is the case, configure this trigger to
262
+
fire on replica too:
263
+
264
+
```plpgsql
265
+
ALTER EVENT TRIGGER pathman_ddl_trigger ENABLE ALWAYS;
266
+
```
267
+
268
+
Physical replication doesn't have this problem since DDL as well as
269
+
`pathman_config` table is replicated too; master and slave PostgreSQL instances
270
+
are basically identical, and it is only harmful to keep this trigger in `ALWAYS`
271
+
mode.
272
+
244
273
245
274
### Additional parameters
246
275
@@ -297,9 +326,10 @@ When INSERTing new data beyond the partitioning range, use SpawnPartitionsWorker
297
326
```plpgsql
298
327
CREATETABLEIF NOT EXISTS pathman_config (
299
328
partrel REGCLASS NOT NULLPRIMARY KEY,
300
-
attnameTEXTNOT NULL,
329
+
expr TEXTNOT NULL,
301
330
parttype INTEGERNOT NULL,
302
-
range_interval TEXT);
331
+
range_interval TEXT,
332
+
cooked_expr TEXT);
303
333
```
304
334
This table stores a list of partitioned tables.
305
335
@@ -341,7 +371,7 @@ RETURNS TABLE (
341
371
parent REGCLASS,
342
372
partition REGCLASS,
343
373
parttype INT4,
344
-
partattrTEXT,
374
+
expr TEXT,
345
375
range_min TEXT,
346
376
range_max TEXT)
347
377
AS'pg_pathman', 'show_partition_list_internal'
@@ -352,6 +382,23 @@ AS SELECT * FROM show_partition_list();
352
382
```
353
383
This view lists all existing partitions, as well as their parents and range boundaries (NULL for HASH partitions).
0 commit comments