Notebooks, cells, versions, pinned results, shares and the execution audit are now ordinary QQQ tables in the SQL Workbench app (nav children, record views with child lists, edit, export, audits, developer mode) instead of hidden admin-only tables. - Record security locks (core-enforced, so every entry point): owner OR share audience for notebooks and their children (through joins), the audit by user; admins hold sqlWorkbenchAllAccess. Key types sqlWorkbenchUser / sqlWorkbenchAudience, applied to sessions by SqlWorkbenchSecurity.applyToSession (no keys without workbench access). - New sqlWorkbenchNotebookShare (USER / GROUP / ALL); publishing writes an ALL share and visibility follows the shares. - Per-table read/insert/edit/delete permissions, listed per role by the config (user / share / admin). - Table customizers hold the notebook invariants for the notebook UI and the tables alike: owner from the session, cell validation and order, one version per change, share keys, append-only versions and audit (admins included), pinned results only from pinning, cascades. - NotebookService and history run as the caller through the same actions; explicit owner/share checks stay as defense in depth. - Record actions: Share Notebook, Duplicate Notebook, Restore Version. - DDL: share table plus an idempotent backfill of library shares. - Tests: TableSecurityMatrixTest (role x table x action over the v1 table API, core actions, export, PVS, record actions, notebook endpoints) and a PostgreSQL lock test. Docs: README, DESIGN, CHANGELOG. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.6 KiB
5.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 the user permission list,writer-*adds write and share,admin-*gets the admin list, anything else gets nothing.loginAs(user, groups...)/as(user)also apply the security keys; notebook calls must run with the matching session.TableSecurityMatrixTestis the role x table x action matrix.
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, sharing, versions in one transaction, snapshots), run as the caller's session through the standard table actions;NotebookVersioning(one version per change, as the system user).api/:SqlWorkbenchApi(transport-agnostic, permission checks),SqlWorkbenchRouteProvider(Javalin 7 routes under/qqq/v1/sql-workbench),ResultExporter(CSV/JSON/XLSX via fastexcel), andSqlWorkbenchRoutes.metadata/: the 6 tables (record locks, joins, child-list widgets), the security key types, the PVSs, the record actions, theSQL_WORKBENCHwidget and its renderer, and thesqlWorkbenchapp.customizers/: table customizers holding the notebook invariants for every entry point;SqlWorkbenchSecurityputs the lock keys in sessions.processes/: the record-action steps (Share, Duplicate, Restore Version).
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. - Workbench rows are read and written as the caller (record locks apply). Only the audit writes, version bookkeeping, cascades and share-visibility sync run as the system user, after QQQ authorized the change. Never re-hide the tables or bypass the locks to fix a permission problem.
- Table customizers hold the notebook invariants; the notebook UI and the table UI must behave the same.
- 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.