Test a database in a private network

Put a zriz runner inside the network. It makes outbound connections only, so you open no port. The work is done when a run on the runner has status pass.

Draft. Guide · zz 0.4.0 or later · Updated 2026-10-09 · Plain text for agents: /docs/test-private-database.md

The runner reaches the database, and the internet does not. Which connections does the runner make? gives the rule.

The connection string stays in the config of the runner. The example is for Postgres.

Before you start

• zz is logged in: zz runners
• The project has the sample pipeline: zz validate hello

1. Deploy a runner in the network

Do

Do the guide Deploy a zriz runner with Docker on a host that can reach the database. Then come back.

The guide ends with a run of the sample on the runner. Keep its token, its file config.json, and the name of its environment.

zz runners

Why

The host needs outbound HTTPS to https://zriz.io and a route to the database. It needs no inbound rule.

You should see

{"ok":true,"command":"runners",
"connected":true

If not

• "connected":false: The runner is down. Do docker logs zriz-runner on its host. The runner guide names each message.
• not logged in: Do zz login. Then do the command again.

2. Add the database to the runner

Do

On the host of the runner, add one resource to resources of config.json. Keep the other keys as they are.

• <base url> is the value that the file has now.
• <db> is the id that you give to the database. It must be unique in your org. Example: shop-db.
• <user>, <host>, and <database> are the parts of the connection string. Use an account that can only read: Create a read-only Postgres user.
• <password> is the password of that account.
• <token> is the token of the runner guide.

config.json:

{
  "cloud": { "url": "https://zriz.io", "token-env": "ZRIZ_RUNNER_TOKEN" },
  "resources": {
    "target": { "type": "http", "base-url": "<base url>" },
    "<db>": {
      "type": "sql",
      "connection": "postgres://<user>:${DB_PASSWORD}@<host>:5432/<database>",
      "read-only": true
    }
  }
}

The runner reads the config at its start. Start it again, with the password in its environment:

docker rm -f zriz-runner
docker run -d --name zriz-runner \
  -e ZRIZ_RUNNER_CONFIG=/config/config.json \
  -e ZRIZ_RUNNER_TOKEN=<token> \
  -e DB_PASSWORD=<password> \
  -v "$PWD/config.json:/config/config.json:ro" \
  zriz-runner
docker logs zriz-runner

Why

The runner calls only the resources that its config names. It fills ${DB_PASSWORD} from its own environment, so the password is in no file.

You should see

runner connected

If not

• started: The runner is not connected yet. Wait 10 seconds. Then do docker logs zriz-runner again.
• missing environment variable: Give DB_PASSWORD to docker run with -e.
• config:: The line names the fault in config.json. Correct the file.

3. Write the test

Do

Do this step in the folder of your service. Make a resource file with the same id, and one pipeline that reads the database.

• <db> is the id from step 2.

A resource file must have the key connection. zz removes it before a run, and the runner uses the connection of its own config. Thus DB_URL needs no value.

.zriz/resources/<db>.json:

{
  "type": "sql",
  "connection": "${env.DB_URL}",
  "read-only": true,
  "actions": {
    "ping": { "query": "select 1 as ok" }
  }
}

.zriz/pipelines/db-ping.json:

{
  "description": "The runner reaches the database",
  "steps": [
    { "call": "<db>/ping", "expect": [["row-count", "==", 1]] }
  ]
}

zz validate db-ping

Why

The files in the repository name the query and the check. They hold no host and no password.

You should see

{"ok":true,"command":"validate",

If not

• missing-action: The call and the resource file do not agree. error.valid lists the actions. Correct the name.
• "ok":false: error.file and error.message name the fault. Correct it, then do the command again.

4. Run the test on the runner

Do

• <env> is the environment of the runner, from the runner guide.

zz run db-ping --env <env>

Why

zz run needs a runner that serves the environment of the run. The runner is in your network, so the query comes from inside it.

You should see

"status":"pass"

If not

• runner-unavailable: No runner serves this environment. Do zz runners, and compare env of each runner.
• no environment file: Make the file that the message names. The runner guide gives the step.
• no runner connected: The runner is down. Do docker logs zriz-runner on its host.
• "status":"fail": Do the command in hints of the reply. It shows the failed step.

Next

• Change the query to a select on a table of your own. Pipelines gives the checks on rows.
• Test an API call and the database row: one test for the API and the database.
• What never leaves my network?