70 lines
4.7 KiB
Markdown
70 lines
4.7 KiB
Markdown
# Preview SQL Delivery Rehearsal Design
|
|
|
|
## Context
|
|
|
|
P2-D8e2b provides a real, default-disabled `sql-jdbc:v1` Executor, but every installed PageBlock release still has an empty delivery payload. The execution framework therefore has no reviewed built-in release that proves a real classpath SQL artifact can move through publication, immutable Transition planning, trusted content re-resolution, target deduplication, and compensation.
|
|
|
|
P2-D8e2c adds one deliberately small delivery Plugin and a read-only target probe. It does not enable the SQL target, publish a release, enqueue a Transition, or connect to a production database automatically.
|
|
|
|
## Delivery Plugin
|
|
|
|
The installed release is `delivery.preview-baseline@1.0.0`, provided by `ruoyi-factory` with Plugin type `delivery`. It declares one `DATABASE_MIGRATION` contribution named `V1__preview_delivery_baseline`.
|
|
|
|
The apply resource:
|
|
|
|
- creates the dedicated `factory_delivery_baseline_marker` table with `IF NOT EXISTS`;
|
|
- uses `INSERT IGNORE` to add the immutable `delivery.preview-baseline` marker;
|
|
- is declared `idempotent=true`;
|
|
- contains no control-database table and no dynamic catalog name.
|
|
|
|
The rollback resource uses only `DROP TABLE IF EXISTS factory_delivery_baseline_marker`. The table is dedicated to this Plugin release, so compensation does not remove data owned by another feature.
|
|
|
|
The Plugin is a normal Spring `FeaturePlugin`. It appears in installed Registry manifests and can be bootstrapped through the existing publication workflow. Installation alone has no target-side effect. Operators must still publish the release and explicitly enqueue its Transition.
|
|
|
|
## Manual Target Probe
|
|
|
|
Registry status continues to report only local configuration readiness. A separate `POST /generator/plugin/sql-target/probe` operation performs an explicit, read-only probe under `generator:plugin:list` permission.
|
|
|
|
The probe:
|
|
|
|
1. returns `DISABLED` without opening a connection when the target is disabled;
|
|
2. returns `INVALID_CONFIGURATION` without opening a connection when local validation fails;
|
|
3. opens the guarded isolated connection, which rechecks target catalog and control-database identity;
|
|
4. runs a zero-row query against `factory_plugin_target_receipt`;
|
|
5. returns `READY`, `UNAVAILABLE`, or `LEDGER_UNAVAILABLE` with a generic message.
|
|
|
|
The response contains only state, enabled/config-ready/reachable/ledger-ready booleans, environment code, allowed catalog, and a generic message. It has no JDBC URL, username, password, driver exception, SQLState, or server error text. Probe results are not persisted and never run migration payloads.
|
|
|
|
## Admin UI
|
|
|
|
When SQL target configuration is enabled, the Registry status band shows a compact manual probe command and the last result held in the browser. The initial state is `NOT_CHECKED`. A successful result confirms isolation checks and receipt-table visibility, not permission to modify arbitrary application tables.
|
|
|
|
The existing execution dialog remains the only place where an operator starts a published Transition. The probe cannot publish, execute, retry, or compensate a Plugin.
|
|
|
|
## End-To-End Rehearsal Test
|
|
|
|
The integration test uses H2 1.4.200 in MySQL mode and the real classpath apply/rollback resources. It performs this path without replacing core steps with mocks:
|
|
|
|
1. construct the installed Plugin and validate its manifest/payload fingerprint;
|
|
2. plan a schema 1.2 PUBLISH Transition;
|
|
3. re-resolve the apply content from the installed release;
|
|
4. execute through `sql-jdbc:v1` and the target receipt ledger;
|
|
5. redeliver the same logical step and verify one marker row and one target execution;
|
|
6. resolve the planned compensation and execute it under a separate stable key;
|
|
7. verify the marker table is absent and both target receipts are SUCCEEDED.
|
|
|
|
Separate probe tests cover disabled, invalid, ready, unreachable, and missing-ledger outcomes with mocked JDBC boundaries. No test attempts a production target connection.
|
|
|
|
## Activation Order
|
|
|
|
1. Apply `sql/factory_plugin_sql_target.sql` to an isolated preview catalog.
|
|
2. Configure and enable the SQL target, then restart.
|
|
3. Use the manual target probe and require `READY`.
|
|
4. Bootstrap or create the `delivery.preview-baseline` definition and publish version `1.0.0`.
|
|
5. Inspect the immutable Transition Plan and enqueue execution.
|
|
6. Verify the marker and target receipt, then exercise compensation before considering a broader Plugin.
|
|
|
|
## Scope
|
|
|
|
This stage proves one small database delivery artifact and closes the target-readiness observability gap. It does not add permission/menu adapters, arbitrary SQL upload, automatic execution, scheduled probes, production credentials, or production rollout approval. Existing plaintext development credential and TLS settings remain deferred by explicit user decision.
|