pgLab/AGENTS.md

# AGENTS.md

pgLab: Qt 6 / C++20 desktop GUI for PostgreSQL.

## Layout (link order: core, pgsql -> pglablib -> pglab)
- `core/` – generic utilities (SQL lexer, CSV writer, `Expected`, JSON); no DB access.
- `pgsql/` – thin C++ wrapper around libpq (connection, result, params, oids).
- `pglablib/` – catalog models, code builders, query generation, connection config.
- `pglab/` – the Qt Widgets application (executable).
- `tests/` – gtest executables `PgsqlTests` and `pglabtests`, plus `mygtestutils` (Qt `PrintTo` helpers).
- `docs/` – Sphinx user docs; `releasenotes/notes` – `reno` notes.

## Build and test
CMake + vcpkg is the active build system (`VCPKG_ROOT` must be set). Qt 6 is not provided by vcpkg; it must be installed on the system.
```
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build
ctest --test-dir build --output-on-failure
```
- Run one suite: `./build/tests/pglabtests/pglabtests --gtest_filter='SqlLexer*'` (same for `PgsqlTests`).
- Integration tests against real PostgreSQL 14–17 (`IntegrationTests`, label `integration`): configure with `-DPGLAB_INTEGRATION_TESTS=ON` (needs Docker), then `ctest --test-dir build -L integration -j4`. This starts `tests/integration/docker-compose.yml` (ports 54314–54317), runs the binary once per version and tears it down. Manual run against any server: `TEST_DATABASE_URL=postgresql://postgres:test@localhost:54316/postgres ./build/tests/integration/IntegrationTests --gtest_filter='Smoke*'`. Without the variable the tests skip. Developer-facing only, no reno note. See the `pg-integration-tests` skill.
- `-DBUILD_TESTS=OFF` skips tests. `build/` is git-ignored; the first configure builds dependencies and is slow.
- Run the app headless with `QT_QPA_PLATFORM=offscreen ./build/pglab/pglab`. It needs a PostgreSQL server for anything useful.

## Gotchas
- Tests are registered per executable, so each `ctest` entry covers a whole suite.
- A new test file must be added to the `add_executable` list in `tests/<suite>/CMakeLists.txt`. Sources are listed explicitly, with no globbing. The same goes for new sources in each library's `CMakeLists.txt`.
- `core/test/` is not referenced by any CMake file (its tests are built from `tests/pglabtests`). Don't expect changes there to be compiled.
- `AUTOMOC`/`AUTOUIC`/`AUTORCC` are on globally, so `.ui` and `.qrc` files only need to be listed as sources.
- `BOOST_ENABLE_ASSERT_HANDLER` is defined; the handler lives in `core/my_boost_assert_handler.cpp`.
- Commit messages are plain imperative sentences. User-visible changes need a reno note (`releasenotes/notes`).
- Docs build: `pip install -r docs/requirements.txt && sphinx-build -b html docs userdocs`.
- Windows (VS 2022) is also a supported platform. Avoid Linux-only code, and don't break `WIN32_LEAN_AND_MEAN`/`NOMINMAX` assumptions.