Crate mz_pgtest

source ·
Expand description

pgtest is a Postgres wire protocol tester using datadriven test files. It can be used to send specific messages to any Postgres-compatible server and record received messages.

The following datadriven directives are supported. They support a conn=name argument to specify a non-default connection.

  • send: Sends input messages to the server. Arguments, if needed, are specified using JSON. Refer to the associated types to see supported arguments. Arguments can be omitted to use defaults.
  • until: Waits until input messages have been received from the server. Additional messages are accumulated and returned as well.

The first time a conn=name argument is specified, cluster=name can also be specified to set the sessions cluster on initial connection.

During debugging, set the environment variable PGTEST_VERBOSE=1 to see messages sent and received.

Supported send types:

Supported until arguments:

  • no_error_fields causes ErrorResponse messages to have empty contents. Useful when none of our fields match Postgres. For example until no_error_fields.
  • err_field_typs specifies the set of error message fields (reference). The default is CMS (code, message, severity). For example: until err_field_typs=SC would return the severity and code fields in any ErrorResponse message.

For example, to execute a simple prepared statement:

Parse {"query": "SELECT $1::text, 1 + $2::int4"}
Bind {"values": ["blah", "4"]}

DataRow {"fields":["blah","5"]}
CommandComplete {"tag":"SELECT 1"}
ReadyForQuery {"status":"I"}

§Usage while writing tests

The expected way to use this while writing tests is to generate output from a postgres server. Use the pgtest-mz directory if our output differs incompatibly from postgres. Write your test, excluding any lines after the ---- of the until directive. For example:

Query {"query": "SELECT 1"}


Then run the pgtest binary, enabling rewrites and pointing it at postgres:

REWRITE=1 cargo run --bin mz-pgtest -- test/pgtest/ --addr localhost:5432 --user postgres

This will generate the expected output for the until directive. Now rerun against a running Materialize server:

cargo run --bin mz-pgtest -- test/pgtest/