# PostgreSQL integration tests

From a checkout on a Linux Docker host, run:

```sh
sh bin/test-postgres.sh
```

This builds `docker/php/Dockerfile.test` from the current checkout and lockfile,
starts a disposable PostgreSQL 17 container on a unique network, runs the full
suite with PostgreSQL enabled, then runs lint. It publishes no ports, mounts no
existing database volumes, and removes its database container, network and test
image on exit. Build layers remain cached. PHP 8.4 is used for the PHPUnit 12 test
runtime; the production image is unchanged. Docker and network access for the
initial image/dependency build are required.

For remote validation, copy the current source to a **separate** remote directory
(do not overwrite an existing dirty checkout), then execute the command there.
Do not copy `.env`, host `vendor`, collection directories or other secrets.
Capture the command exit status along with its output.

## Existing dedicated test database

Alternatively, export these variables before invoking `composer test`:

```sh
export MESHVAULT_TEST_PG_DSN='pgsql:host=127.0.0.1;port=5432;dbname=meshvault_test'
export MESHVAULT_TEST_PG_USER=meshvault_test
# Supply MESHVAULT_TEST_PG_PASSWORD securely through your environment.
composer test
```

Use a dedicated test database and a role permitted to create schemas. Each test
migrates production Phinx migrations into a randomly named schema, sets its
connections' search path to that schema only, and drops that schema on teardown.
Configured connection or migration errors fail the suite rather than skip it.
An abruptly killed process may leave `meshvault_test_*` schemas; only remove
schemas known to belong to a finished test run.

Without `MESHVAULT_TEST_PG_DSN`, repository and pipeline tests continue to use
SQLite and the five PostgreSQL-only tests skip. Those tests cover schema isolation,
overlapping claims using `SKIP LOCKED`, rollback/reclaim, and item-lock timeout and
retry using two independent PDO sessions. They are not a multiprocess load test.

The older `MigrationTest` suite uses the separate application `MESHVAULT_DB_*`
variables and remains skipped in this isolated runner. Production migrations are
nevertheless exercised by the repository/pipeline fixtures on PostgreSQL.