mirror of
https://github.com/postgres/postgres.git
synced 2025-06-08 22:02:03 +03:00
Update isolation tests' README file.
The directions explaining about running the prepared-transactions test were not updated in commit ae55d9fbe3871a5e6309d9b91629f1b0ff2b8cba.
This commit is contained in:
parent
efed8c0031
commit
2bf6e8cbc0
@ -3,20 +3,32 @@ src/test/isolation/README
|
|||||||
Isolation tests
|
Isolation tests
|
||||||
===============
|
===============
|
||||||
|
|
||||||
This directory contains a set of tests for the serializable isolation level.
|
This directory contains a set of tests for concurrent behaviors in
|
||||||
Testing isolation requires running multiple overlapping transactions,
|
PostgreSQL. These tests require running multiple interacting transactions,
|
||||||
which requires multiple concurrent connections, and therefore can't be
|
which requires management of multiple concurrent connections, and therefore
|
||||||
tested using the normal pg_regress program.
|
can't be tested using the normal pg_regress program. The name "isolation"
|
||||||
|
comes from the fact that the original motivation was to test the
|
||||||
|
serializable isolation level; but tests for other sorts of concurrent
|
||||||
|
behaviors have been added as well.
|
||||||
|
|
||||||
To run the tests, you need to have a server running at the default port
|
To run the tests, you need to have a server running at the default port
|
||||||
expected by libpq. (You can set PGPORT and so forth in your environment
|
expected by libpq. (You can set PGPORT and so forth in your environment
|
||||||
to control this.) Then run
|
to control this.) Then run
|
||||||
gmake installcheck
|
gmake installcheck
|
||||||
Note that the prepared-transactions test will not pass unless you have
|
To run just specific test(s), you can do something like
|
||||||
the server's max_prepared_transactions parameter set to at least 3.
|
./pg_isolation_regress fk-contention fk-deadlock
|
||||||
|
(look into the specs/ subdirectory to see the available tests).
|
||||||
|
|
||||||
To represent a test with overlapping transactions, we use a test specification
|
The prepared-transactions test requires the server's
|
||||||
file with a custom syntax, which is described in the next section.
|
max_prepared_transactions parameter to be set to at least 3; therefore it
|
||||||
|
is not run by default. To include it in the test run, use
|
||||||
|
gmake installcheck-prepared-txns
|
||||||
|
|
||||||
|
To define tests with overlapping transactions, we use test specification
|
||||||
|
files with a custom syntax, which is described in the next section. To add
|
||||||
|
a new test, place a spec file in the specs/ subdirectory, add the expected
|
||||||
|
output in the expected/ subdirectory, and add the test's name to the
|
||||||
|
isolation_schedule file.
|
||||||
|
|
||||||
isolationtester is a program that uses libpq to open multiple connections,
|
isolationtester is a program that uses libpq to open multiple connections,
|
||||||
and executes a test specified by a spec file. A libpq connection string
|
and executes a test specified by a spec file. A libpq connection string
|
||||||
@ -24,7 +36,8 @@ specifies the server and database to connect to; defaults derived from
|
|||||||
environment variables are used otherwise.
|
environment variables are used otherwise.
|
||||||
|
|
||||||
pg_isolation_regress is a tool similar to pg_regress, but instead of using
|
pg_isolation_regress is a tool similar to pg_regress, but instead of using
|
||||||
psql to execute a test, it uses isolationtester.
|
psql to execute a test, it uses isolationtester. It accepts all the same
|
||||||
|
command-line arguments as pg_regress.
|
||||||
|
|
||||||
|
|
||||||
Test specification
|
Test specification
|
||||||
@ -36,48 +49,65 @@ subdirectory. A test specification consists of four parts, in this order:
|
|||||||
setup { <SQL> }
|
setup { <SQL> }
|
||||||
|
|
||||||
The given SQL block is executed once, in one session only, before running
|
The given SQL block is executed once, in one session only, before running
|
||||||
the test. Create any test tables or such objects here. This part is
|
the test. Create any test tables or other required objects here. This
|
||||||
optional.
|
part is optional.
|
||||||
|
|
||||||
teardown { <SQL> }
|
teardown { <SQL> }
|
||||||
|
|
||||||
The teardown SQL block is executed once after the test is finished. Use
|
The teardown SQL block is executed once after the test is finished. Use
|
||||||
this to clean up, e.g dropping any test tables. This part is optional.
|
this to clean up in preparation for the next permutation, e.g dropping
|
||||||
|
any test tables created by setup. This part is optional.
|
||||||
|
|
||||||
session "<name>"
|
session "<name>"
|
||||||
|
|
||||||
Each session is executed in a separate connection. A session consists
|
There are normally several "session" parts in a spec file. Each
|
||||||
of four parts: setup, teardown and one or more steps. The per-session
|
session is executed in its own connection. A session part consists
|
||||||
|
of three parts: setup, teardown and one or more "steps". The per-session
|
||||||
setup and teardown parts have the same syntax as the per-test setup and
|
setup and teardown parts have the same syntax as the per-test setup and
|
||||||
teardown described above, but they are executed in every session,
|
teardown described above, but they are executed in each session. The
|
||||||
before and after each permutation. The setup part typically contains a
|
setup part typically contains a "BEGIN" command to begin a transaction.
|
||||||
"BEGIN" command to begin a transaction.
|
|
||||||
|
|
||||||
Each step has a syntax of
|
Each step has the syntax
|
||||||
|
|
||||||
step "<name>" { <SQL> }
|
step "<name>" { <SQL> }
|
||||||
|
|
||||||
where <name> is a unique name identifying this step, and SQL is a SQL
|
where <name> is a name identifying this step, and SQL is a SQL statement
|
||||||
statement (or statements, separated by semicolons) that is executed in the
|
(or statements, separated by semicolons) that is executed in the step.
|
||||||
step.
|
Step names must be unique across the whole spec file.
|
||||||
|
|
||||||
permutation "<step name>" ...
|
permutation "<step name>" ...
|
||||||
|
|
||||||
A permutation line specifies a list of steps that are run in that order.
|
A permutation line specifies a list of steps that are run in that order.
|
||||||
If no permutation lines are given, the test program automatically generates
|
Any number of permutation lines can appear. If no permutation lines are
|
||||||
all possible overlapping orderings of the given sessions.
|
given, the test program automatically generates all possible orderings
|
||||||
|
of the steps from each session (running the steps of any one session in
|
||||||
|
order). Note that the list of steps in a manually specified
|
||||||
|
"permutation" line doesn't actually have to be a permutation of the
|
||||||
|
available steps; it could for instance repeat some steps more than once,
|
||||||
|
or leave others out.
|
||||||
|
|
||||||
Lines beginning with a # are considered comments.
|
Lines beginning with a # are considered comments.
|
||||||
|
|
||||||
|
For each permutation of the session steps (whether these are manually
|
||||||
|
specified in the spec file, or automatically generated), the isolation
|
||||||
|
tester runs the main setup part, then per-session setup parts, then
|
||||||
|
the selected session steps, then per-session teardown, then the main
|
||||||
|
teardown script. Each selected step is sent to the connection associated
|
||||||
|
with its session.
|
||||||
|
|
||||||
|
|
||||||
Support for blocking commands
|
Support for blocking commands
|
||||||
=============================
|
=============================
|
||||||
|
|
||||||
Each spec may contain commands that block until further action has been taken
|
Each step may contain commands that block until further action has been taken
|
||||||
(most likely, some other session runs a step that unblocks it or causes a
|
(most likely, some other session runs a step that unblocks it or causes a
|
||||||
deadlock). Such a spec needs to be careful to manually specify valid
|
deadlock). A test that uses this ability must manually specify valid
|
||||||
permutations, i.e. those that would not expect a blocked session to execute a
|
permutations, i.e. those that would not expect a blocked session to execute a
|
||||||
command. If the spec fails to follow that rule, the spec is aborted.
|
command. If the test fails to follow that rule, the test is aborted.
|
||||||
|
|
||||||
Only one command can be waiting at a time. As long as one command is waiting,
|
Currently, at most one step can be waiting at a time. As long as one
|
||||||
other commands are run to completion synchronously.
|
step is waiting, subsequent steps are run to completion synchronously.
|
||||||
|
|
||||||
|
Note that isolationtester recognizes that a command has blocked by looking
|
||||||
|
to see if it is shown as waiting in the pg_locks view; therefore, only
|
||||||
|
blocks on heavyweight locks will be detected.
|
||||||
|
Loading…
x
Reference in New Issue
Block a user