# dbtest: container test databases

Podman (preferred) or Docker. One tool for postgres, mssql, mysql.

## Commands

| Command | Action |
|---|---|
| `./tests/dbtest/dbtest.sh up <db\|all>` | Start, wait for ready, run init |
| `down <db\|all>` | Stop and remove |
| `restart <db>` | Fresh container |
| `status <db\|all>` | State and connection string |
| `env <db\|all>` | Print `export` line for the test env var |
| `test <db> [pkgs]` | up, `go test`, down |
| `shell <db>` | Interactive client |
| `exec <db> <file>` | Run SQL file |
| `logs <db>` | Container logs |

## Databases

| db | Port | Env var | Init | Default test pkgs |
|---|---|---|---|---|
| postgres | 5439 | `RELSPEC_TEST_PG_CONN` | `tests/postgres/init.sql` | readers/pgsql, writers/pgsql, writers/sqlexec |
| mssql | 1439 | `RELSPEC_TEST_MSSQL_CONN` | `test_data/mssql/test_schema.sql` (creates `RelSpecTest`) | readers/mssql, writers/mssql |
| mysql | 3309 | `RELSPEC_TEST_MYSQL_CONN` | `tests/dbtest/init/mysql.sql` | readers/mysql, writers/mysql |

## Env

| Var | Effect |
|---|---|
| `DBTEST_RUNTIME` | Force `podman` or `docker` |
| `DBTEST_TIMEOUT` | Ready wait, seconds (default 120) |
| `DBTEST_KEEP=1` | Keep container after `test` |
| `DBTEST_GOFLAGS` | Extra `go test` flags |

## Add a database

1. Add `dbs/<name>.sh` defining: `DB_NAME DB_IMAGE DB_CONTAINER DB_PORT DB_INTERNAL_PORT DB_ENV DB_INIT_MOUNT DB_CONN_VAR DB_CONN DB_DEFAULT_PKGS` and functions `db_ready db_post_init db_shell db_exec_file`.
2. Add the name to `ALL_DBS` in `dbtest.sh`.

## Notes

- Containers are named `relspec-test-<db>`; existing `tests/postgres/*.sh` and `make docker-*` use the same postgres name/port 5439 and remain independent.
- mssql needs ~2GB RAM and takes longer to become ready.
- Tests skip when the env var is unset.

## MySQL schema fidelity tests

Run `./tests/dbtest/dbtest.sh test mysql` for the MySQL 8.4 round-trip and
unsupported-object regressions. They use temporary tables in `relspec_test`,
including checks, functional indexes, composite foreign keys, binary/expression
defaults, and generated columns. The test account needs table, view, and trigger
privileges in that database. The disposable runner enables
`log_bin_trust_function_creators` so binary logging does not require SUPER for
trigger fixtures. For a separately managed test server, disable binary logging
or configure that setting first. No global database-creation privilege is required.
A failed or interrupted test can leave tables named `rt_*` or `unsupported_*`;
restarting the disposable container removes them.

See [the MySQL capability matrix](../../docs/MYSQL_FIDELITY.md) for the supported
contract and strict conversion options. PostgreSQL/SQL Server tests remain
separate; this suite does not certify MariaDB compatibility.