QRun-IO/qbit-quick-search
3
0 Fork 0
Code Issues 2 Pull Requests 4 Actions Packages Projects Releases 14 Wiki Activity

docs: add 'Adopting in another app' README section and operational-table DDL #37

New Issue
Open
opened 2026-10-12 10:27:51 +00:00 by KofTwentyTwo · 0 comments
KofTwentyTwo commented 2026-10-12 10:27:51 +00:00 (Migrated from github.com)
Copy link
Copy source

From the 2026-10-12 repo audit. The README has no ## Adopting in another app section (the anchor other docs link to), and three open PRs (#25, #27, #31) all edit README.md, so the audit did not touch it. Add the section after those merge.

Related README drift: the version badge and the Getting started snippet say 1.0.0-RC.1; #27 moves them to 1.0.0-RC.2, but Maven Central's newest is 1.1.0-RC.1 (from release/1.1). Pick the line hosts should adopt and say it once.

Proposed section (insert before ## Building)

## Adopting in another app

| Item | What to do |
|---|---|
| Coordinates | `com.kingsrook.qbits:qbit-quick-search`. Release candidates on Maven Central: `1.0.0-RC.2` (1.0 line, `release/1.0`) and `1.1.0-RC.1` (adds the core `/qqq/v1/search` provider, `release/1.1`). |
| QQQ version | 1.0: QQQ 4.1. 1.1: QQQ `4.1.0-RC.2` or later (record-search provider SPI). Java 21. |
| Infrastructure | An OpenSearch 2.19.x / 3.x cluster or an Amazon OpenSearch Service domain (not Serverless, not Elasticsearch). A least-privilege role on `{opensearchIndexName}*` (see Supported platforms). |
| Registration | `new QuickSearchQBitProducer().withConfig(config).produce(qInstance)` after backends, tables and the scheduler are in the instance. Don't add `QBitMetaData` yourself. |
| Required config | `backendName`, `opensearchUrl`, `opensearchIndexName`, at least one of `searchableEntityClasses` / `searchableTables`, and `schedulerName` (without it nothing runs basepull or reconcile). A cron reconcile needs a Quartz scheduler and `reconcileCronTimeZoneId`. |
| Secrets / env | `opensearchUsername` / `opensearchPassword` as `${env.X}` references (names are the host's). `AWS_SIGV4` reads `AWS_REGION` when `awsRegion` is unset and needs the optional `software.amazon.awssdk:apache-client` (and `sts` for `awsAssumeRoleArn`). |
| Storage | Three operational tables on `backendName`: `quickSearchIndex`, `quickSearchIndexRun`, `quickSearchFailedEvent`. The repo ships no DDL; on an RDBMS backend the host writes it (see Operational tables for columns; `quickSearchFailedEvent.status` needs at least 16 characters). |
| Permissions | `quickSearchAdmin.hasAccess` for the admin app and the three processes; `READ_WRITE_PERMISSIONS` on the operational tables (`quickSearchIndex.read` / `.write`, etc.). Override with `adminPermissionRules` / `tablePermissionRules`. Search itself honours table read permissions and record security locks. |
| First run | Run a full reindex once after install (and after upgrading from 0.x or 1.0 to remove PASSWORD-field values). |
| Known limitations | No OpenSearch Serverless. `IndexEventPublisher` SPI is experimental. One record-search provider per instance (a host-registered one wins). Schedules run only under `QApplicationLauncher` or a host-started `QScheduleManager`. |
| Upgrading | 0.x -> 1.0: docs/MIGRATION-1.0.md. 1.0 -> 1.1: docs/MIGRATION-1.1.md (core search switches to OpenSearch by default; `serveCoreRecordSearch(false)` keeps 1.0 behaviour; indexed tables gain `searchFields`). |

Also missing

  • DDL for the three operational tables (qbit-sql-workbench ships docs/ddl/postgres.sql as a model). Hosts on RDBMS currently reverse-engineer the columns.

Nothing host-specific (kof22) was found in src/main.

Filed with AI assistance (Claude Code).

From the 2026-10-12 repo audit. The README has no `## Adopting in another app` section (the anchor other docs link to), and three open PRs (#25, #27, #31) all edit `README.md`, so the audit did not touch it. Add the section after those merge. Related README drift: the version badge and the Getting started snippet say `1.0.0-RC.1`; #27 moves them to `1.0.0-RC.2`, but Maven Central's newest is `1.1.0-RC.1` (from `release/1.1`). Pick the line hosts should adopt and say it once. ## Proposed section (insert before `## Building`) ```markdown ## Adopting in another app | Item | What to do | |---|---| | Coordinates | `com.kingsrook.qbits:qbit-quick-search`. Release candidates on Maven Central: `1.0.0-RC.2` (1.0 line, `release/1.0`) and `1.1.0-RC.1` (adds the core `/qqq/v1/search` provider, `release/1.1`). | | QQQ version | 1.0: QQQ 4.1. 1.1: QQQ `4.1.0-RC.2` or later (record-search provider SPI). Java 21. | | Infrastructure | An OpenSearch 2.19.x / 3.x cluster or an Amazon OpenSearch Service domain (not Serverless, not Elasticsearch). A least-privilege role on `{opensearchIndexName}*` (see Supported platforms). | | Registration | `new QuickSearchQBitProducer().withConfig(config).produce(qInstance)` after backends, tables and the scheduler are in the instance. Don't add `QBitMetaData` yourself. | | Required config | `backendName`, `opensearchUrl`, `opensearchIndexName`, at least one of `searchableEntityClasses` / `searchableTables`, and `schedulerName` (without it nothing runs basepull or reconcile). A cron reconcile needs a Quartz scheduler and `reconcileCronTimeZoneId`. | | Secrets / env | `opensearchUsername` / `opensearchPassword` as `${env.X}` references (names are the host's). `AWS_SIGV4` reads `AWS_REGION` when `awsRegion` is unset and needs the optional `software.amazon.awssdk:apache-client` (and `sts` for `awsAssumeRoleArn`). | | Storage | Three operational tables on `backendName`: `quickSearchIndex`, `quickSearchIndexRun`, `quickSearchFailedEvent`. The repo ships no DDL; on an RDBMS backend the host writes it (see Operational tables for columns; `quickSearchFailedEvent.status` needs at least 16 characters). | | Permissions | `quickSearchAdmin.hasAccess` for the admin app and the three processes; `READ_WRITE_PERMISSIONS` on the operational tables (`quickSearchIndex.read` / `.write`, etc.). Override with `adminPermissionRules` / `tablePermissionRules`. Search itself honours table read permissions and record security locks. | | First run | Run a full reindex once after install (and after upgrading from 0.x or 1.0 to remove PASSWORD-field values). | | Known limitations | No OpenSearch Serverless. `IndexEventPublisher` SPI is experimental. One record-search provider per instance (a host-registered one wins). Schedules run only under `QApplicationLauncher` or a host-started `QScheduleManager`. | | Upgrading | 0.x -> 1.0: docs/MIGRATION-1.0.md. 1.0 -> 1.1: docs/MIGRATION-1.1.md (core search switches to OpenSearch by default; `serveCoreRecordSearch(false)` keeps 1.0 behaviour; indexed tables gain `searchFields`). | ``` ## Also missing - DDL for the three operational tables (qbit-sql-workbench ships `docs/ddl/postgres.sql` as a model). Hosts on RDBMS currently reverse-engineer the columns. Nothing host-specific (kof22) was found in `src/main`. Filed with AI assistance (Claude Code).
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
architecture
Architecture review: coupling, cohesion, UI API
 bug
Something isn't working
 dependencies
documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 github_actions
Pull requests that update GitHub Actions code
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 invalid
This doesn't seem right
 java
Pull requests that update java code
 question
Further information is requested
 release:rc
Merging this develop PR cuts the next release candidate
 secuurity
wontfix
This will not be worked on
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
forge-recovery (Forge Recovery) james.maes (James Maes)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: QRun-IO/qbit-quick-search#37