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

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
plugins:
  - name: PostgreSQL
    sourceCommit: 5852a91f8ba9f4c73585a5984a96117a159c068f
    descriptorDigest: 52bdb147746c6fea6fe1f11aa839b05c7ee0eb9a9f97619380ae38a143f72afe
---

### 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 names the invocation’s retained evidence. 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 rather than deleting application data.

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.