database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-10 09:21:54 +03:00
Code

Update isolation tests' README file.

Browse Source 
The directions explaining about running the prepared-transactions test
were not updated in commit ae55d9fbe3871a5e6309d9b91629f1b0ff2b8cba.
This commit is contained in:
Tom Lane 2012-08-08 12:02:15 -04:00
parent efed8c0031
commit 2bf6e8cbc0
1 changed files with 58 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
src/test/isolation/README
View File

@ -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.