eelke/pgLab
1
0
Fork 0
Code Issues 29 Pull requests Projects Releases 1 Packages Wiki Activity Actions
pgLab/AGENTS.md

2.8 KiB
Raw Blame History

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.