PostgreSQL plugin

Use PostgreSQL to check the business data behind a user journey. Queries retain column names and row values, so a reviewer can inspect the database state alongside screenshots and command output.

Connect

Select your application collection during onboarding. Use its ID in the target command below.

Install the bundled plugin with reflow init --collection <collection-id>. Your test database must be running and reachable from the machine that runs Reflow.

Save a private bindings.json with your test database connection string:

{
  "db": {
    "provider": "PostgreSQL",
    "configuration": {
      "connectionString": "postgresql://test_user:replace-me@127.0.0.1:5432/test_db"
    }
  }
}

connectionString is required. Keep this file out of Git; credentials belong in the private connection, not the flow’s plugin requirements. allowWrites is an optional boolean and defaults to false.

The plugin uses pgx v5 to parse URL or keyword/value connection strings. PostgreSQL session parameters such as search_path are supported in the DSN, for example postgresql://test_user:replace-me@127.0.0.1:5432/test_db?search_path=public. Percent-encode parameter values when needed and keep the complete DSN private. The server must recognize each runtime parameter; application-specific URL options are not automatically PostgreSQL settings: use search_path=public, not an application-only option such as schema=public. Reflow sets application_name to reflow-plugin-postgresql and uses a five-second connection timeout.

chmod 600 /absolute/path/to/bindings.json
reflow target --group database-tests --collection <collection-id> --bindings /absolute/path/to/bindings.json

Write a flow

Copy this into /tmp/database-check.md, outside your checkout. The example returns one row without requiring an application table:

---
name: Capture database rows
providers:
  db: PostgreSQL
---

### Capture database rows

```rfl
db.query sql="SELECT 1 AS id, 'ready' AS status" key="id" checkpoint="database-ready"
```

Create the test in the team’s chosen location, then run it:

reflow flows create --name database-check --file /tmp/database-check.md
reflow plan database-check
reflow apply database-check
reflow dashboard

The alias db selects the private connection with the same name. For an application with an orders table, select the business columns you want to compare:

db.query sql="SELECT id, status, refunded FROM orders ORDER BY id" key="id" checkpoint="orders"

Query arguments and stable rows

Argument	Type	Meaning
sql	string, required	One SQL statement, executed in a read-only transaction.
key	string, optional	A unique, non-null returned column used to identify and sort rows.

checkpoint is a host RFL modifier, not a PostgreSQL command argument. RFL removes it before validating and dispatching the provider arguments, so it does not appear in the query descriptor returned by list_plugins. Use a literal label of 1-128 letters, digits, underscores or hyphens. Other unknown arguments are still rejected. A query already captures its result; there is no additional snapshot command.

Use a key or an explicit ORDER BY to make ordering repeatable. A missing, null or duplicate key fails the capture. Returned column names must also be unique. A capture is limited to 10,000 rows and 8 MiB of serialized row data; narrow the query instead of relying on a partial result.

Typed inputs can supply numeric limits and booleans; see the database flow example. Do not concatenate untrusted text into SQL. Plugin arguments do not provide SQL bind parameters.

Setup writes

db.execute accepts a required sql string. It runs only when the private connection explicitly sets "allowWrites": true; it retains the command tag and number of affected rows. Enabling writes does not make query writable.

Use a separate, deliberate setup step against your test database. Make repeated setup safe for your application: rerunning a flow does not reset database contents, and reflow reset rotates named test values and leaves application data in place.

Review the result

The snapshot keeps the returned columns and exact represented row values. Compare those retained results across runs and relate differences to the application’s rules; see database evidence. A query completing successfully does not itself assert that every business value is correct.

Flows using this plugin can be saved in Reflow or in your repository. Read test storage for the team preference, private bindings and the shared plan/apply workflow.