src/test/isolation/README

Isolation tests
===============

This directory contains a set of tests for the serializable isolation level.
Testing isolation requires running multiple overlapping transactions,
which requires multiple concurrent connections, and therefore can't be
tested using the normal pg_regress program.

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
to control this.)  Then run
    gmake installcheck
Note that the prepared-transactions test will not pass unless you have
the server's max_prepared_transactions parameter set to at least 3.

To represent a test with overlapping transactions, we use a test specification
file with a custom syntax, which is described in the next section.

isolationtester is a program that uses libpq to open multiple connections,
and executes a test specified by a spec file. A libpq connection string
specifies the server and database to connect to; defaults derived from
environment variables are used otherwise.

pg_isolation_regress is a tool similar to pg_regress, but instead of using
psql to execute a test, it uses isolationtester.


Test specification
==================

Each isolation test is defined by a specification file, stored in the specs
subdirectory. A test specification consists of four parts, in this order:

setup { <SQL> }

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

teardown { <SQL> }

  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.

session "<name>"

  Each session is executed in a separate connection. A session consists
  of four 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
  teardown described above, but they are executed in every session,
  before and after each permutation. The setup part typically contains a
  "BEGIN" command to begin a transaction.

  Each step has a syntax of

  step "<name>" { <SQL> }

  where <name> is a unique name identifying this step, and SQL is a SQL
  statement (or statements, separated by semicolons) that is executed in the
  step.

permutation "<step name>" ...

  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
  all possible overlapping orderings of the given sessions.

Lines beginning with a # are considered comments.


Support for blocking commands
=============================

Each spec 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
deadlock).  Such a spec needs to be careful to manually specify valid
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.

Only one command can be waiting at a time.  As long as one command is waiting,
other commands are run to completion synchronously.