Re-pin the default-active qqq-snapshot profile from qqq-bom-pom 4.1.0-RC.1 to 4.1.0-RC.2 (now on Maven Central) and update the docs. No SNAPSHOT dependencies. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.6 KiB
4.6 KiB
AGENTS.md
This file provides guidance to Codex when working with code in this repository.
Project Overview
QBit SQL Workbench: a QQQ QBit that provides a super-user SQL notebook. Sessions are read-only by default, write mode is gated, and everything is audited. It works over any RDBMS backend of the instance. The UI is the Next UI SQL_WORKBENCH widget. Design: docs/DESIGN.md.
Build Commands
./mvnw compile # Compile (always use the wrapper: Maven 3.10 cannot read the parent POM)
./mvnw test # Unit tests (H2 MODE=MySQL, SQLite, Javalin over HTTP)
./mvnw test -Dtest=ClassName
CI=true ./mvnw verify # Unit + Postgres integration tests (Docker) + JaCoCo gate (70% instructions, 90% classes)
./mvnw verify -Dpostgres.test.image=postgres:17-alpine
How tests are split:
- Integration tests (
*IntegrationTest) run under failsafe and use@ExtendWith(RequiresDockerCondition.class). Without Docker they are skipped locally; withCI=truethe build fails instead. - Unit tests extend
BaseSqlWorkbenchTest. It sets up an H2 backendh2with the snake_case DDL fromsrc/test/resources/sql-workbench-h2.sql, MOCK auth, and a session customizer. The session id prefix picks the permissions:reader-*gets access,writer-*gets access plus write plus share, anything else gets nothing.
Architecture
Entry point: SqlWorkbenchQBitProducer implements QBitMetaDataProducer<SqlWorkbenchQBitConfig>.
- Component producers are found in the
metadatapackage only (getPackageNameForFindingMetaDataProducers), becauseapineeds the optional Javalin dependency. postProduceActionsbuildsSqlWorkbenchRuntimeand callsapi.SqlWorkbenchRoutes.registerwhen Javalin is on the classpath.
Packages:
sql/:SqlScanner(dialect-aware lexer),SqlClassifier(split, then classify as READ, EXPLAIN_ANALYZE, WRITE, DDL, or FORBIDDEN),NamedParameterSql(:name→?). Pure Java.engine/:SqlExecutionEnginehandles read-only runs, the write preview/commit protocol, and EXPLAIN.SessionGuardsets up the per-vendor read-only transaction and timeouts, and always restores the connection (or aborts it).WorkbenchBackendsresolves targets and derives backends for dedicated credentials.ResultCollectorconverts types and applies the row/byte caps.ResultCache,RunningStatements, andWritePreviewTokensare the runtime state.ExecutionAuditorwrites audits through QQQ actions asQSystemUserSession.
explain/:PlanParser(Postgres JSON, MySQL JSON/text, SQLite rows, text) andPlanNode.schema/:SchemaIntrospector(JDBCDatabaseMetaDataplus the QQQ table and field to SQL name mapping), cached in the runtime.notebook/:NotebookService(CRUD, visibility, versions in one transaction, snapshots).api/:SqlWorkbenchApi(transport-agnostic, permission checks),SqlWorkbenchRouteProvider(Javalin 7 routes under/qqq/v1/sql-workbench),ResultExporter(CSV/JSON/XLSX via fastexcel), andSqlWorkbenchRoutes.metadata/: the 5 tables, the notebook PVS, theSQL_WORKBENCHwidget and its renderer, and thesqlWorkbenchapp.
Invariants (do not break):
- Never log SQL text, parameters, or results. Only the audit table holds them.
- Audit
start()runs before any SQL. If it fails, the SQL does not run. - Audit updates are deferred until the session's connection is released (
Deferredin the engine), so the engine never needs two pooled connections at once. - Engine-side session settings must be transaction-scoped (
SET LOCAL) or reverted inSessionGuard.close. - SQL errors are results (
statusFAILED, TIMED_OUT, or CANCELLED). Exceptions are only for 400, 401, 403, and 404.
Code Style
- 3-space indentation, opening braces on the next line,
return (x);. - Javadoc flower-box comments (
/*****with**lines) on every class and method. - Fluent setters (
withX()). - Wrapper types (
Integer,Boolean) in config and entities.
Dependencies
- Java 21.
- Parent
com.kingsrook:qbit-build-parent:2.0.0(qqq 4.0.0). The default-activeqqq-snapshotprofile importsqqq-bom-pom:4.1.0-RC.2ahead of it, as in qbit-quick-search (ADR-0007). Remove that activation when the parent moves to 4.1. qqq-backend-core,qqq-backend-module-rdbms, andqqq-middleware-javalin(optional).- Tests: JUnit 5, AssertJ, Mockito, H2,
qqq-backend-module-sqlite/-postgres(drivers), Testcontainers 1.21.4.
Release
- CircleCI qqq-orb 0.6.8.
developpublishes SNAPSHOTs.- A
release/*branch publishes RCs (the orb bumps the version). - A
v*tag publishes the release.