@@ -3,28 +3,41 @@ src/test/isolation/README
33Isolation tests
44===============
55
6- This directory contains a set of tests for the serializable isolation level.
7- Testing isolation requires running multiple overlapping transactions,
8- which requires multiple concurrent connections, and therefore can't be
9- tested using the normal pg_regress program.
6+ This directory contains a set of tests for concurrent behaviors in
7+ PostgreSQL. These tests require running multiple interacting transactions,
8+ which requires management of multiple concurrent connections, and therefore
9+ can't be tested using the normal pg_regress program. The name "isolation"
10+ comes from the fact that the original motivation was to test the
11+ serializable isolation level; but tests for other sorts of concurrent
12+ behaviors have been added as well.
1013
1114To run the tests, you need to have a server running at the default port
1215expected by libpq. (You can set PGPORT and so forth in your environment
1316to control this.) Then run
1417 gmake installcheck
15- Note that the prepared-transactions test will not pass unless you have
16- the server's max_prepared_transactions parameter set to at least 3.
18+ To run just specific test(s), you can do something like
19+ ./pg_isolation_regress fk-contention fk-deadlock
20+ (look into the specs/ subdirectory to see the available tests).
1721
18- To represent a test with overlapping transactions, we use a test specification
19- file with a custom syntax, which is described in the next section.
22+ The prepared-transactions test requires the server's
23+ max_prepared_transactions parameter to be set to at least 3; therefore it
24+ is not run by default. To include it in the test run, use
25+ gmake installcheck-prepared-txns
26+
27+ To define tests with overlapping transactions, we use test specification
28+ files with a custom syntax, which is described in the next section. To add
29+ a new test, place a spec file in the specs/ subdirectory, add the expected
30+ output in the expected/ subdirectory, and add the test's name to the
31+ isolation_schedule file.
2032
2133isolationtester is a program that uses libpq to open multiple connections,
2234and executes a test specified by a spec file. A libpq connection string
2335specifies the server and database to connect to; defaults derived from
2436environment variables are used otherwise.
2537
2638pg_isolation_regress is a tool similar to pg_regress, but instead of using
27- psql to execute a test, it uses isolationtester.
39+ psql to execute a test, it uses isolationtester. It accepts all the same
40+ command-line arguments as pg_regress.
2841
2942
3043Test specification
@@ -36,48 +49,65 @@ subdirectory. A test specification consists of four parts, in this order:
3649setup { <SQL> }
3750
3851 The given SQL block is executed once, in one session only, before running
39- the test. Create any test tables orsuch objects here. This part is
40- optional.
52+ the test. Create any test tables orother required objects here. This
53+ part is optional.
4154
4255teardown { <SQL> }
4356
4457 The teardown SQL block is executed once after the test is finished. Use
45- this to clean up, e.g dropping any test tables. This part is optional.
58+ this to clean up in preparation for the next permutation, e.g dropping
59+ any test tables created by setup. This part is optional.
4660
4761session "<name>"
4862
49- Each session is executed in a separate connection. A session consists
50- of four parts: setup, teardown and one or more steps. The per-session
63+ There are normally several "session" parts in a spec file. Each
64+ session is executed in its own connection. A session part consists
65+ of three parts: setup, teardown and one or more "steps". The per-session
5166 setup and teardown parts have the same syntax as the per-test setup and
52- teardown described above, but they are executed in every session,
53- before and after each permutation. The setup part typically contains a
54- "BEGIN" command to begin a transaction.
67+ teardown described above, but they are executed in each session. The
68+ setup part typically contains a "BEGIN" command to begin a transaction.
5569
56- Each step hasa syntax of
70+ Each step hasthe syntax
5771
5872 step "<name>" { <SQL> }
5973
60- where <name> is aunique name identifying this step, and SQL is a SQL
61- statement (or statements, separated by semicolons) that is executed in the
62- step .
74+ where <name> is a name identifying this step, and SQL is a SQL statement
75+ (or statements, separated by semicolons) that is executed in the step.
76+ Step names must be unique across the whole spec file .
6377
6478permutation "<step name>" ...
6579
6680 A permutation line specifies a list of steps that are run in that order.
67- If no permutation lines are given, the test program automatically generates
68- all possible overlapping orderings of the given sessions.
81+ Any number of permutation lines can appear. If no permutation lines are
82+ given, the test program automatically generates all possible orderings
83+ of the steps from each session (running the steps of any one session in
84+ order). Note that the list of steps in a manually specified
85+ "permutation" line doesn't actually have to be a permutation of the
86+ available steps; it could for instance repeat some steps more than once,
87+ or leave others out.
6988
7089Lines beginning with a # are considered comments.
7190
91+ For each permutation of the session steps (whether these are manually
92+ specified in the spec file, or automatically generated), the isolation
93+ tester runs the main setup part, then per-session setup parts, then
94+ the selected session steps, then per-session teardown, then the main
95+ teardown script. Each selected step is sent to the connection associated
96+ with its session.
97+
7298
7399Support for blocking commands
74100=============================
75101
76- Eachspec may contain commands that block until further action has been taken
102+ Eachstep may contain commands that block until further action has been taken
77103(most likely, some other session runs a step that unblocks it or causes a
78- deadlock).Such a spec needs to be careful to manually specify valid
104+ deadlock).A test that uses this ability must manually specify valid
79105permutations, i.e. those that would not expect a blocked session to execute a
80- command. If the spec fails to follow that rule, the spec is aborted.
106+ command. If the test fails to follow that rule, the test is aborted.
107+
108+ Currently, at most one step can be waiting at a time. As long as one
109+ step is waiting, subsequent steps are run to completion synchronously.
81110
82- Only one command can be waiting at a time. As long as one command is waiting,
83- other commands are run to completion synchronously.
111+ Note that isolationtester recognizes that a command has blocked by looking
112+ to see if it is shown as waiting in the pg_locks view; therefore, only
113+ blocks on heavyweight locks will be detected.