Skip to content

Commit cceaae1

Browse files
zilderzilder
committed
documentation update
1 parent 0084ae6 commit cceaae1

File tree

2 files changed

+72
-35
lines changed

2 files changed

+72
-35
lines changed

‎README.md

Lines changed: 71 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -62,77 +62,93 @@ Done! Now it's time to setup your partitioning schemes.
6262

6363
### Partition creation
6464
```plpgsql
65-
create_hash_partitions(relation TEXT,
65+
create_hash_partitions(relation REGCLASS,
6666
attribute TEXT,
6767
partitions_count INTEGER)
6868
```
6969
Performs HASH partitioning for `relation` by integer key `attribute`. Creates `partitions_count` partitions and trigger on INSERT. All the data will be automatically copied from the parent to partitions.
7070

7171
```plpgsql
72-
create_range_partitions(relation TEXT,
73-
attribute TEXT,
74-
start_value ANYELEMENT,
75-
interval ANYELEMENT,
76-
premake INTEGER DEFAULT NULL)
72+
create_range_partitions(relation REGCLASS,
73+
attribute TEXT,
74+
start_value ANYELEMENT,
75+
interval ANYELEMENT,
76+
count INTEGER DEFAULT NULL
77+
partition_data BOOLEAN DEFAULT true)
78+
79+
create_range_partitions(relation TEXT,
80+
attribute TEXT,
81+
start_value ANYELEMENT,
82+
interval INTERVAL,
83+
count INTEGER DEFAULT NULL,
84+
partition_data BOOLEAN DEFAULT true)
85+
```
86+
Performs RANGE partitioning for `relation` by partitioning key `attribute`. `start_value` argument specifies initial value, `interval` sets the range of values in a single partition, `count` is the number of premade partitions (if not set then pathman tries to determine it based on attribute values). 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_data_concurrent()` for a lock-free way to migrate data.
7787

78-
create_range_partitions(relation TEXT,
79-
attribute TEXT,
80-
start_value ANYELEMENT,
81-
interval INTERVAL,
82-
premake INTEGER DEFAULT NULL)
88+
```plpgsql
89+
create_partitions_from_range(relation REGCLASS,
90+
attribute TEXT,
91+
start_value ANYELEMENT,
92+
end_value ANYELEMENT,
93+
interval ANYELEMENT,
94+
partition_data BOOLEAN DEFAULT true)
95+
96+
create_partitions_from_range(relation REGCLASS,
97+
attribute TEXT,
98+
start_value ANYELEMENT,
99+
end_value ANYELEMENT,
100+
interval INTERVAL,
101+
partition_data BOOLEAN DEFAULT true)
83102
```
84-
Performs RANGE partitioning for `relation` by partitioning key `attribute`. `start_value` argument specifies initial value, `interval` sets the range of values in a single partition, `premake` is the number of premade partitions (if not set then pathman tries to determine it based on attribute values). All the data will be automatically copied from the parent to partitions.
103+
Performs RANGE-partitioning from specified range for `relation` by partitioning key `attribute`.
85104

86-
```plpgsql
87-
create_partitions_from_range(relation TEXT,
88-
attribute TEXT,
89-
start_value ANYELEMENT,
90-
end_value ANYELEMENT,
91-
interval ANYELEMENT)
105+
### Data migration
92106

93-
create_partitions_from_range(relation TEXT,
94-
attribute TEXT,
95-
start_value ANYELEMENT,
96-
end_value ANYELEMENT,
97-
interval INTERVAL)
107+
```plpgsql
108+
partition_data_concurrent(relation REGCLASS)
98109
```
99-
Performs RANGE-partitioning from specified range for `relation` by partitioning key `attribute`. Data will be copied to partitions as well.
110+
Starts a background worker to copy data from parent table to partitions. The worker utilize short transactions to copy small bunches of data (up to 10K rows per transaction) and thus doesn't significantly interfere with users activity.
100111

101112
### Triggers
102113
```plpgsql
103-
create_hash_update_trigger(parent TEXT)
114+
create_hash_update_trigger(parent REGCLASS)
104115
```
105116
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.
106117
```plpgsql
107-
create_range_update_trigger(parent TEXT)
118+
create_range_update_trigger(parent REGCLASS)
108119
```
109120
Same as above, but for a RANGE-partitioned table.
110121

111122
### Post-creation partition management
112123
```plpgsql
113-
split_range_partition(partition TEXT, value ANYELEMENT)
124+
split_range_partition(partition REGCLASS,
125+
value ANYELEMENT,
126+
partition_name TEXT DEFAULT NULL)
114127
```
115128
Split RANGE `partition` in two by `value`.
116129

117130
```plpgsql
118-
merge_range_partitions(partition1 TEXT, partition2 TEXT)
131+
merge_range_partitions(partition1 REGCLASS, partition2 REGCLASS)
119132
```
120133
Merge two adjacent RANGE partitions. First, data from `partition2` is copied to `partition1`, then `partition2` is removed.
121134

122135
```plpgsql
123-
append_range_partition(p_relation TEXT)
136+
append_range_partition(p_relation REGCLASS,
137+
partition_name TEXT DEFAULT NULL)
124138
```
125139
Append new RANGE partition.
126140

127141
```plpgsql
128-
prepend_range_partition(p_relation TEXT)
142+
prepend_range_partition(p_relation REGCLASS,
143+
partition_name TEXT DEFAULT NULL)
129144
```
130145
Prepend new RANGE partition.
131146

132147
```plpgsql
133-
add_range_partition(relation TEXT,
134-
start_value ANYELEMENT,
135-
end_value ANYELEMENT)
148+
add_range_partition(relation REGCLASS,
149+
start_value ANYELEMENT,
150+
end_value ANYELEMENT,
151+
partition_name TEXT DEFAULT NULL)
136152
```
137153
Create new RANGE partition for `relation` with specified range bounds.
138154

@@ -155,10 +171,31 @@ detach_range_partition(partition TEXT)
155171
Detach partition from the existing RANGE-partitioned relation.
156172

157173
```plpgsql
158-
disable_partitioning(relation TEXT)
174+
disable_pathman_for(relation TEXT)
159175
```
160176
Permanently disable `pg_pathman` partitioning mechanism for the specified parent table and remove the insert trigger if it exists. All partitions and data remain unchanged.
161177

178+
```plpgsql
179+
drop_partitions(parent REGCLASS,
180+
delete_data BOOLEAN DEFAULT FALSE)
181+
```
182+
Drop partitions of the `parent` table. If `delete_data` is `false` then the data is copied to the parent table first. Default is `false`.
183+
184+
185+
### Additional parameters
186+
187+
```plpgsql
188+
enable_parent(relation REGCLASS)
189+
disable_parent(relation REGCLASS)
190+
```
191+
Include/exclude parent table into/from query plan. In original PostgreSQL planner parent table is always included into query plan even if it's empty which can lead to additional overhead. You can use `disable_parent()` if you are never going to use parent table as a storage. Default value depends on the `partition_data` parameter that was specified during initial partitioning in `create_range_partitions()` or `create_partitions_from_range()` functions. If the `partition_data` parameter was `true` then all data have already been migrated to partitions and parent table disabled. Otherwise it is enabled.
192+
193+
```plpgsql
194+
enable_auto(relation REGCLASS)
195+
disable_auto(relation REGCLASS)
196+
```
197+
Enable/disable auto partition propagation (only for RANGE partitioning). It is enabled by default.
198+
162199
## Custom plan nodes
163200
`pg_pathman` provides a couple of [custom plan nodes](https://wiki.postgresql.org/wiki/CustomScanAPI) which aim to reduce execution time, namely:
164201

‎init.sql

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -281,7 +281,7 @@ LANGUAGE plpgsql;
281281
/*
282282
* Disable pathman partitioning for specified relation
283283
*/
284-
CREATE OR REPLACE FUNCTION @extschema@.disable_partitioning(
284+
CREATE OR REPLACE FUNCTION @extschema@.disable_pathman_for(
285285
parent_relid REGCLASS)
286286
RETURNS VOID AS
287287
$$

0 commit comments

Comments
 (0)