Skip to content

Commit 49f0451

Browse files
committed
Added documentation for sr_plan contrib module.
1 parent 3b10b4b commit 49f0451

File tree

1 file changed

+77
-1
lines changed

1 file changed

+77
-1
lines changed

contrib/sr_plan/README.md

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,77 @@
1-
# sr_plan
1+
# Save and restore query plans in PostgreSQL
2+
3+
## Rationale
4+
5+
sr_plan looks like Oracle Outline system. It can be used to lock the execution plan. It is necessary if you do not trust the planner or able to form a better plan.
6+
7+
## Build
8+
9+
Dependencies: >= Python 3.2, Mako, pycparser
10+
If you only have a Python you can use the virtual environment:
11+
```bash
12+
virtualenv env
13+
source ./env/bin/activate
14+
pip install -r ./requirements.txt
15+
```
16+
17+
Then you need to generate C code and compiled it:
18+
```bash
19+
make USE_PGXS=1 genparser
20+
make USE_PGXS=1
21+
make USE_PGXS=1 install
22+
```
23+
24+
and modify your postgres config:
25+
```
26+
shared_preload_libraries = 'sr_plan.so'
27+
```
28+
29+
## Usage
30+
In your db:
31+
```SQL
32+
CREATE EXTENSION sr_plan;
33+
```
34+
If you want to save the query plan is necessary to set the variable:
35+
```SQL
36+
set sr_plan.write_mode = true;
37+
```
38+
Now plans for all subsequent queries will be stored in the table sr_plans. Don't forget that all queries will be stored including duplicates.
39+
Making an example query:
40+
```SQL
41+
select query_hash from sr_plans where query_hash=10;
42+
```
43+
disable saving the query:
44+
```SQL
45+
set sr_plan.write_mode = false;
46+
```
47+
Now verify that your query is saved:
48+
```SQL
49+
select query_hash, enable, valid, query, explain_jsonb_plan(plan) from sr_plans;
50+
51+
query_hash | enable | valid | query | explain_jsonb_plan
52+
------------+--------+-------+------------------------------------------------------+----------------------------------------------------
53+
1783086253 | f | t | select query_hash from sr_plans where query_hash=10; | Bitmap Heap Scan on sr_plans +
54+
| | | | Recheck Cond: (query_hash = 10) +
55+
| | | | -> Bitmap Index Scan on sr_plans_query_hash_idx+
56+
| | | | Index Cond: (query_hash = 10) +
57+
| | | |
58+
59+
```
60+
61+
explain_jsonb_plan function allows you to display explain execute the plan of which lies in jsonb. By default, all the plans are off, you need enable it:
62+
```SQL
63+
update sr_plans set enable=true where query_hash=1783086253;
64+
```
65+
(1783086253 for example only)
66+
After that, the plan for the query will be taken from the sr_plans.
67+
68+
In addition sr plan allows you to save a parameterized query plan. In this case, we have some constants in the query are not essential.
69+
For the parameters we use a special function _p (anyelement) example:
70+
```SQL
71+
select query_hash from sr_plans where query_hash=1000+_p(10);
72+
```
73+
if we keep the plan for the query and enable it to be used also for the following queries:
74+
```SQL
75+
select query_hash from sr_plans where query_hash=1000+_p(11);
76+
select query_hash from sr_plans where query_hash=1000+_p(-5);
77+
```

0 commit comments

Comments
 (0)