diff --git a/.gitignore b/.gitignore index 6848a4e..d863ea2 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ .claude/settings.local.json +apex/PRIVATE_NOTES_APEX_SKILLS.md diff --git a/README.md b/README.md index 098873c..a093f7d 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ The goal is to give developers and agents a single place to find source-backed O Install a domain by appending the root-level domain directory to the repository name: ```bash +npx skills add oracle/skills/apex npx skills add oracle/skills/db npx skills add oracle/skills/graal ... @@ -26,7 +27,7 @@ npx skills add oracle/skills/graal - `db/` is the active Oracle Database domain and includes database, ORDS, SQLcl, framework, container, and agent workflow skills. - `oci/` is the root for future Oracle Cloud Infrastructure skills. - `fusion/` is the root for future Oracle Fusion skills. -- `apex/` is the root for future Oracle APEX skills. +- `apex/` contains Oracle APEX skills, starting with workspace provisioning and administration. The APEX root skill is token-optimized: it keeps `apex/SKILL.md` concise, routes to topic files on demand, and includes token-use rules to avoid loading whole categories unnecessarily. - `graal/` contains GraalVM skills, starting with Native Image. ## Start Here @@ -61,7 +62,12 @@ npx skills add oracle/skills/graal ├── fusion/ │ └── SKILL.md ├── apex/ -│ └── SKILL.md +│ ├── SKILL.md +│ └── deployment/ +│ └── monitoring/ +│ └── security/ +│ └── workspace/ +│ └── test-apex-skills.sh ├── graal/ │ ├── SKILL.md │ └── native-image/ diff --git a/apex/SKILL.md b/apex/SKILL.md index efe204d..688ab36 100644 --- a/apex/SKILL.md +++ b/apex/SKILL.md @@ -1,5 +1,77 @@ +--- +name: apex +description: Oracle APEX skills for workspace administration, application development, deployment, monitoring, and source-backed operational workflows. +--- + # Oracle APEX Skills -This file is a sample domain skeleton. +Only the root `apex/SKILL.md` is a skill entry point. Category folders contain topic `.md` files; read only the specific topic needed for the request. + +## Token Use + +- Load one routed topic first; add a second topic only when the workflow crosses that boundary. +- Use `rg`/section search for exact checks instead of reading whole categories. +- Load `apex/security/safety-messages.md` only when an exact user-facing message is needed. +- For SQL examples, prefer the smallest relevant snippet from the topic file. + +## Routing + +- Workspace lifecycle/provisioning/listing/removal: `apex/workspace/lifecycle.md`, `apex/workspace/resource-governance.md`, `apex/workspace/users-and-auth.md`, `apex/workspace/schema-mapping.md`, `apex/workspace/removal.md`, `apex/workspace/version-notes.md`, `apex/workspace/security-review.md` +- Security/auth/session/export safety: `apex/security/guardrails.md`, `apex/security/safety-messages.md`, `apex/security/audit-columns.md`, `apex/security/security-review.md` +- Monitoring/runtime diagnosis/MCP availability: `apex/monitoring/activity-log.md`, `apex/monitoring/error-handling.md`, `apex/monitoring/user-journey-replay.md`, `apex/monitoring/background-jobs.md`, `apex/monitoring/rest-data-sources.md`, `apex/monitoring/page-performance.md`, `apex/monitoring/ir-ig-tuning.md`, `apex/monitoring/awr-wait-correlation.md`, `apex/monitoring/mcp-availability.md`, `apex/monitoring/security-review.md` +- Deployment/export/import/patching: `apex/deployment/pre-check.md`, `apex/deployment/export-review.md`, `apex/deployment/import-promotion.md`, `apex/deployment/post-deploy-validation.md`, `apex/deployment/patching.md`, `apex/deployment/security-review.md` + +## Scope + +Keep APEX skills APEX-specific. Before adding or expanding an APEX skill, check whether the generic database topic is already covered under `db/`. + +Use APEX skills for APEX workspaces, applications, App Builder, runtime behavior, session state, APEX activity/debug logs, APEX users, Team Development, supported `APEX_*` views, and APEX APIs such as `APEX_UTIL`, `APEX_INSTANCE_ADMIN`, and `APEX_APPLICATION_INSTALL`. + +Do not duplicate generic database guidance in APEX skills. Privilege management, auditing, encryption, network security, data masking, VPD/RLS, AWR, ASH, wait events, SQL tuning, SQLcl basics, and ORDS fundamentals belong in `db/`. + +When using a generic DB skill, announce it with `DB skill in use: db/...`, for example: + +```text +DB skill in use: db/performance/wait-events.md for the generic wait-event analysis. The APEX skill is being used for APEX activity-log correlation. +``` + +## Safety + +- Use least privilege for parsing schemas, workspace users, database-login users, and automation accounts. Do not recommend broad grants such as `DBA`, `SYSDBA`, `SELECT ANY TABLE`, `EXECUTE ANY PROCEDURE`, `CREATE ANY TABLE`, `GRANT ANY ROLE`, `GRANT ANY PRIVILEGE`, or `WITH ADMIN OPTION` unless the user explicitly asks for privileged administration and the risk is called out. +- Keep APEX security contexts separate: workspace administrator, developer, end user, parsing schema, database-login user, ORDS/APEX runtime account, and DBA/admin account are different roles. +- Do not treat APEX parsing schemas as personal interactive logins in production. +- Prefer supported APEX APIs and views. Do not write directly to internal APEX repository tables. +- Treat versions and managed environments as variable. Inspect availability with `ALL_TAB_COLUMNS`, `ALL_ARGUMENTS`, `DESC`, `APEX_RELEASE`, or `APEX_DICTIONARY` before relying on version-specific columns or package signatures. +- Protect destructive actions with object listings, fresh exact English confirmation prompts, protected-account checks, and no remembered-context assumptions. Workspace-related database users may be dropped only when the user explicitly asks to remove the workspace and its listed related database users/components and confirms that this is their own will. Load `apex/workspace/removal.md`. +- After interrupted APEX provisioning, reconnect, inventory each planned artifact individually, and ask whether to roll back only the listed artifacts before retrying or continuing. Load `apex/monitoring/mcp-availability.md` and `apex/workspace/lifecycle.md`. +- Before APEX workflows that use MCP database access, run the APEX MCP availability guard. If MCP reports `Transport closed` or an unavailable tool channel, stop and do not continue from stale database state. +- Never include real secrets in skills, examples, logs, exports, or chat output. +- Treat APEX activity logs, debug logs, error messages, request values, Team Development files, exports, and session context as potentially sensitive. +- Do not treat APEX session state, hidden items, read-only items, or client-side checks as a security boundary. +- For tenant isolation or sensitive row access, APEX authorization can help the UI, but critical data isolation belongs in the database. Hand off implementation details to `db/security/row-level-security.md`. +- APEX exports may contain application logic, URLs, authorization schemes, build options, static files, credential references, defaults, and other sensitive metadata. +- For APEX-owned application tables, include safe audit columns when appropriate: `created_at`, `created_by`, `updated_at`, `updated_by`. Audit-column triggers should use APEX user context with a database-user fallback, not only `USER`; for database auditing, announce and use `db/security/auditing.md`. +- Mark licensed features and production constraints, especially AWR/ASH/Diagnostics Pack and database security options whose licensing depends on deployment. +- End substantial APEX skill additions with a security review covering privileges, secrets, auditability, data exposure, version/cloud restrictions, and destructive actions. + +## Documentation + +Use official Oracle APEX documentation and prefer the newest available documentation unless the user names a specific installed APEX version. Start from: + +```text +https://apex.oracle.com/en/learn/documentation/ +``` + +Do not hard-code older APEX documentation URLs unless the guidance is explicitly about that older version. + +## Safety Messages + +For exact user-facing safety messages, load `apex/security/safety-messages.md`. Use it for broad grants, direct internal repository writes, destructive changes, interrupted provisioning recovery, sensitive logs/exports, session-state assumptions, audit triggers, version-sensitive APEX views, or unavailable MCP-backed database access. + +## Validation + +Run after changing APEX skills: -For the repo-wide structure and authoring pattern, read the root `README.md` and `SKILL_AUTHORING_GUIDE.md`. +```bash +bash apex/test-apex-skills.sh +``` diff --git a/apex/deployment/export-review.md b/apex/deployment/export-review.md new file mode 100644 index 0000000..8a5b002 --- /dev/null +++ b/apex/deployment/export-review.md @@ -0,0 +1,21 @@ +# APEX Export Review + +APEX exports can contain sensitive metadata: URLs, authorization schemes, build options, substitution strings, static files, credential references, REST endpoints, defaults, install scripts, and business logic. Review before commit, sharing, or import. + +Use App Builder export or SQLcl APEX export workflows, but keep generic SQLcl syntax and CI/CD mechanics in the SQLcl DB skills. + +## Review Checklist + +- Application ID and alias are intentional for the target environment. +- Workspace and parsing schema mapping are explicit. +- Build options match the target environment. +- Substitution strings do not include real secrets or production-only endpoints unless intentionally deployed. +- Static files and supporting objects do not embed tokens, passwords, private URLs, or customer data. +- Authentication and authorization schemes are correct for the target environment. +- Web Credentials are referenced safely; secret values are not printed, committed, or copied into examples. +- REST Data Sources and remote server URLs are environment-aware. +- No real passwords, tokens, OAuth secrets, SMTP credentials, wallet passwords, web credential values, or secret-bearing URLs appear in exports, scripts, examples, logs, or chat output. + +## DB Skill Usage + +DB skill in use: `db/security/encryption.md`, `db/security/network-security.md`, or `db/security/privilege-management.md` for generic secret storage, TLS/network, and privilege implementation. The APEX deployment skill is being used for APEX export and credential-reference review. diff --git a/apex/deployment/import-promotion.md b/apex/deployment/import-promotion.md new file mode 100644 index 0000000..6fe7c41 --- /dev/null +++ b/apex/deployment/import-promotion.md @@ -0,0 +1,51 @@ +# APEX Import And Promotion + +Use `APEX_APPLICATION_INSTALL` when the import needs deterministic workspace, application ID, offset, alias, proxy, image prefix, or schema settings. Keep these calls in the import wrapper, not scattered through application code. + +Version check: inspect `ALL_ARGUMENTS` for `APEX_APPLICATION_INSTALL` in the target APEX release before using version-specific procedures or parameters. + +```sql +BEGIN + APEX_APPLICATION_INSTALL.SET_WORKSPACE(:target_workspace); + APEX_APPLICATION_INSTALL.SET_APPLICATION_ID(:target_application_id); + APEX_APPLICATION_INSTALL.SET_SCHEMA(:target_parsing_schema); + APEX_APPLICATION_INSTALL.SET_APPLICATION_ALIAS(:target_application_alias); +END; +/ +``` + +Check package arguments in the target APEX version before using less common procedures or parameters. Do not assume every APEX release supports the same install API shape. + +## Replace Safety + +For replace imports, list the existing target application and workspace before import and require explicit confirmation for production: + +```sql +SELECT workspace, + application_id, + application_name, + alias, + owner, + last_updated_on +FROM apex_applications +WHERE application_id = :target_application_id + OR UPPER(alias) = UPPER(:target_application_alias) +ORDER BY workspace, + application_id; +``` + +Treat these as destructive or high-risk: + +- Replace an existing application in production. +- Run supporting objects that drop or truncate tables. +- Delete or rotate APEX Web Credentials. +- Change authentication or authorization schemes. +- Change parsing schema mapping. +- Remove static files used by deployed pages. +- Import into a different workspace than expected. + +Safety stop: list affected workspace, application, parsing schema, authentication scheme, authorization schemes, credentials, and supporting objects. Require explicit confirmation before generating or running replace, delete, or destructive supporting-object steps. + +## DB Skill Usage + +DB skill in use: `db/devops/schema-migrations.md` and `db/devops/version-control-sql.md` for generic schema migration and release governance. The APEX deployment skill is being used for APEX application artifact promotion and environment mapping. diff --git a/apex/deployment/patching.md b/apex/deployment/patching.md new file mode 100644 index 0000000..79a8dce --- /dev/null +++ b/apex/deployment/patching.md @@ -0,0 +1,140 @@ +# APEX Patch Set Bundle Workflow + +Use this topic for Oracle APEX Patch Set Bundle status checks and patch planning. Patch availability is time-sensitive, so verify the latest patch number, patch version, README, and known issues from Oracle before giving exact patch instructions. + +Use this for self-managed or co-managed environments. For fully managed Autonomous Database or APEX Application Development Service, Oracle normally applies APEX patch bundles; do not advise manual patching unless the service documentation says patching is customer-managed. + +## Version And View Availability + +Check APEX version first: + +```sql +SELECT version_no +FROM apex_release; +``` + +Check whether `APEX_PATCHES` is available and which columns exist before querying patch rows: + +```sql +SELECT table_name, + column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name = 'APEX_PATCHES' +ORDER BY column_id; +``` + +Then query installed patch rows: + +```sql +SELECT patch_number, + patch_version, + installed_on +FROM apex_patches +ORDER BY installed_on; +``` + +If `APEX_PATCHES` returns no rows, that only means no patch rows are recorded in that view for the current APEX installation. It does not prove that the system is unsupported or broken. Compare `APEX_RELEASE.VERSION_NO` with the latest official APEX release and patch bundle information. + +## Find The Latest Patch Bundle + +Before recommending a patch number: + +- Check the Oracle APEX Downloads and Known Issues page. +- Check My Oracle Support for the target APEX release. +- Read the patch README included in the downloaded patch bundle. +- Confirm whether the patch applies to the exact installed APEX base release. + +As of May 11, 2026, Oracle's APEX downloads page lists Patch Set Bundle for Oracle APEX 24.2 as patch `37366599`, last updated April 30, 2026, with `PATCH_VERSION` 16. Oracle states that applying it updates the APEX product version to `24.2.16`. Treat this as a dated reference point, not a permanent rule. + +## High-Level Patch Flow + +Follow the patch README for exact commands. Use this as the operational checklist: + +1. Confirm target PDB and installed APEX version. +2. Query `APEX_PATCHES`. +3. Download the matching APEX Patch Set Bundle from My Oracle Support. +4. Read the patch README completely. +5. Back up the database/PDB and export critical APEX applications. +6. Stop ORDS or put APEX behind maintenance if the README or local policy requires it. +7. Unzip the patch on the database host or approved deployment host. +8. Connect to the PDB where APEX is installed with the required administrative privileges, typically `SYS AS SYSDBA` when the README requires it. +9. Run the patch script from the extracted patch directory exactly as documented. +10. Recompile invalid objects. +11. Update APEX static files, or set the image prefix to the matching Oracle CDN path when CDN images are used. +12. Restart or reload ORDS. +13. Verify APEX version, patch rows, invalid objects, App Builder, application runtime, and static resources. + +## Post-Patch Verification + +```sql +SELECT version_no +FROM apex_release; +``` + +```sql +SELECT patch_number, + patch_version, + installed_on +FROM apex_patches +ORDER BY installed_on; +``` + +```sql +SELECT owner, + object_type, + COUNT(*) AS invalid_objects +FROM dba_objects +WHERE status = 'INVALID' + AND owner LIKE 'APEX\_%' ESCAPE '' +GROUP BY owner, object_type +ORDER BY owner, object_type; +``` + +Also verify: + +- APEX Administration Services opens. +- At least one workspace can sign in. +- App Builder opens without JavaScript/CSS errors. +- A representative runtime application works. +- Browser developer tools show no missing `/i/` static resources. +- ORDS logs have no new APEX static-resource or pool errors. + +## Static Files And CDN + +APEX patches can require static file updates. The database APEX version and the served image files must match. + +If using local images: + +- Copy the patched `images` directory according to the README. +- Confirm ORDS or the web server serves the updated `/i/` path. + +If using Oracle CDN: + +- Confirm the known-issues/downloads page lists a CDN URL for the exact patched APEX version. +- Set the image prefix only to the matching version path. +- Test App Builder and runtime pages for missing assets. + +## Autonomous And Managed Services + +For Autonomous Database and APEX Application Development Service: + +- Check `APEX_RELEASE` and `APEX_PATCHES`. +- Report the observed version and patch rows. +- Do not instruct the user to manually download and apply a patch bundle unless Oracle service documentation explicitly says that patching is customer-managed. +- If the environment is behind the latest published patch, advise checking the service maintenance schedule or opening an Oracle Support service request. + +## DB Skill Usage + +DB skill in use: `db/admin/backup-recovery.md` for generic database backup and restore planning. The APEX deployment skill is being used for APEX patch-bundle workflow context. + +DB skill in use: `db/ords/ords-monitoring.md` for generic ORDS runtime checks. The APEX deployment skill is being used for APEX static-file and App Builder verification context. + +## Guardrails + +- Do not treat `APEX_PATCHES` with no rows as proof that the newest patch is missing. +- Do not apply a patch bundle to the wrong APEX base version. +- Do not run patch scripts in `CDB$ROOT` unless the patch README explicitly instructs it. +- Do not forget to update static files or CDN image prefix. +- Do not give a hard-coded latest patch number without checking Oracle first. diff --git a/apex/deployment/post-deploy-validation.md b/apex/deployment/post-deploy-validation.md new file mode 100644 index 0000000..135a43f --- /dev/null +++ b/apex/deployment/post-deploy-validation.md @@ -0,0 +1,22 @@ +# APEX Post-Deploy Validation + +Validate APEX-specific behavior after import. + +## Validation Checklist + +- Application exists in the expected workspace with the expected ID, alias, owner, and parsing schema. +- Build options and substitution strings match target environment policy. +- Authentication and authorization schemes work for Workspace Admin, Developer, End User, parsing schema, database-login user, ORDS/APEX runtime account, and DBA/admin account boundaries. +- REST Data Sources and Web Credentials resolve without exposing secret values. +- Critical pages compile and run with expected authorization and session-state protection. +- Supporting objects ran only when intended and did not perform surprise destructive work. +- APEX activity/debug/error logs are free of deployment-time secret leakage. + +## Security Review + +- Privileges remain least-privilege. +- No broad grants such as `DBA`, `SELECT ANY TABLE`, `EXECUTE ANY PROCEDURE`, `CREATE ANY TABLE`, `GRANT ANY ROLE`, or `GRANT ANY PRIVILEGE` were introduced for ordinary APEX deployment. +- APEX session state, hidden items, read-only items, and client-side checks are not treated as security boundaries. +- Any database auditing requirement is handled by the DB auditing skill. + +DB skill in use: `db/security/auditing.md` for generic database audit policy and evidence handling. The APEX deployment skill is being used for APEX release traceability and post-import validation context. diff --git a/apex/deployment/pre-check.md b/apex/deployment/pre-check.md new file mode 100644 index 0000000..e243d23 --- /dev/null +++ b/apex/deployment/pre-check.md @@ -0,0 +1,91 @@ +# APEX Deployment Pre-Check + +Before generating import SQL or deployment steps, identify: + +- Source and target workspace names and workspace IDs. +- Source and target application IDs and whether the target ID must be preserved or remapped. +- Parsing schema mapping and whether schemas already exist. +- Target APEX version and managed-service restrictions. +- Authentication scheme, authorization schemes, build options, substitution strings, application settings, static files, supporting objects, web credentials, and REST Data Sources. +- Whether the import will replace an existing application, install supporting objects, overwrite shared components, or run post-install code. + +## Version And Package Checks + + +For APEX 24.2 installation or upgrade pre-checks, also identify: + +- Database version and whether the target is CDB/PDB. +- Exact PDB where APEX is or will be installed. +- Existing APEX version, if any. +- ORDS version and deployment mode. +- Whether APEX static files are served by ORDS local images, web server images, or Oracle CDN. +- Backup and rollback plan. +- Maintenance window and affected applications/workspaces. + +As of May 11, 2026, Oracle's APEX downloads page states that APEX 24.2 is supported through Oracle Support Services on Oracle Database 19.3 or higher with a valid Oracle Database Technical Support agreement. Still verify the current installation guide before acting, because managed services, patch levels, and support policies can change. + +For fully managed Autonomous Database or APEX Application Development Service, do not plan a manual APEX installation unless Oracle documentation for that service explicitly allows it. For self-managed environments, follow the APEX installation guide for the exact target version. + +Before installation or upgrade, confirm: + +- A tested database/PDB backup or restore point exists. +- Static files and image prefix handling are planned before the maintenance window. +- ORDS can be stopped, reloaded, or placed behind maintenance according to local policy. + +Before relying on an APEX API signature, check the current official Oracle APEX documentation landing page and then use the docs for the target installed version: + +```text +https://apex.oracle.com/en/learn/documentation/ +``` + +If the target version is unknown, use the newest official Oracle APEX documentation as the default reference and keep SQL version-tolerant. + +Check APEX version and package signatures before version-specific calls: + +```sql +SELECT version_no +FROM apex_release; + +SELECT object_name, + argument_name, + position, + data_type +FROM all_arguments +WHERE package_name = 'APEX_APPLICATION_INSTALL' +ORDER BY object_name, + sequence; +``` + +Discover available APEX metadata views before querying deployment metadata: + +```sql +SELECT view_name, + comments +FROM apex_dictionary +WHERE view_name LIKE 'APEX_APPLICATION%' + OR view_name LIKE 'APEX_APPL%' +ORDER BY view_name; +``` + +```sql +SELECT table_name, + column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name IN ( + 'APEX_APPLICATIONS', + 'APEX_APPLICATION_BUILD_OPTIONS', + 'APEX_APPLICATION_SUBSTITUTIONS', + 'APEX_APPLICATION_AUTH', + 'APEX_APPL_WEB_CREDENTIALS', + 'APEX_APPLICATION_STATIC_FILES') +ORDER BY table_name, + column_id; +``` + +## DB Skill Usage + +DB skill in use: `db/sqlcl/sqlcl-basics.md`, `db/sqlcl/sqlcl-scripting.md`, or `db/sqlcl/sqlcl-cicd.md` for generic SQLcl commands and CI/CD mechanics. The APEX deployment skill is being used for APEX metadata and import semantics. + +DB skill in use: `db/security/privilege-management.md` for generic deployment-account, parsing-schema, and runtime-account privilege analysis. The APEX deployment skill is being used for APEX export/import context and environment mapping. diff --git a/apex/deployment/security-review.md b/apex/deployment/security-review.md new file mode 100644 index 0000000..f1ba4f1 --- /dev/null +++ b/apex/deployment/security-review.md @@ -0,0 +1,12 @@ +# APEX Deployment Security Review + +Use this checklist after substantial APEX deployment or promotion work. + +- Scope: APEX export/import, `APEX_APPLICATION_INSTALL`, App Builder settings, workspace/application mapping, and APEX metadata stayed in this skill; generic SQLcl, schema migration, privilege, encryption, auditing, network, ORDS, or CI/CD work was routed to `db/...`. +- DB usage messages: every generic DB step has a visible `DB skill in use:` message naming the relevant DB skill path. +- Privileges: deployment accounts, parsing schemas, workspace administrators, developers, database-login users, ORDS/APEX runtime accounts, and DBA/admin accounts remain separate and least-privilege. +- Secrets: no real passwords, tokens, OAuth secrets, SMTP credentials, wallet passwords, web credential values, or secret-bearing URLs appear in exports, scripts, examples, logs, or chat output. +- Data exposure: static files, supporting objects, substitution strings, REST Data Sources, debug logs, and exports do not expose unnecessary payloads, BLOBs, CLOBs, credentials, or sensitive metadata. +- Version/cloud restrictions: APEX version, install package signatures, managed-service restrictions, and available metadata views were checked before version-specific SQL or import steps. +- Destructive actions: replace imports, supporting objects, credential changes, app deletion, schema mapping changes, and production imports list affected objects and require explicit confirmation. +- Auditability: export source, import target, application ID, workspace, parsing schema, build options, release artifact, and operator are traceable. diff --git a/apex/monitoring/activity-log.md b/apex/monitoring/activity-log.md new file mode 100644 index 0000000..8e31609 --- /dev/null +++ b/apex/monitoring/activity-log.md @@ -0,0 +1,92 @@ +# APEX Activity Log Triage + +Use this reference for `APEX_WORKSPACE_ACTIVITY_LOG`, `APEX_ACTIVITY_LOG`, usage/load trends, session drilldown, and Team Development file context. + +## View Pre-Check + +APEX view columns vary by release and privilege. Inspect availability before version-specific SQL. + +```sql +SELECT table_name, + column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name IN ( + 'APEX_WORKSPACE_ACTIVITY_LOG', + 'APEX_ACTIVITY_LOG', + 'APEX_TEAM_DEV_FILES') +ORDER BY table_name, + column_id; +``` + +```sql +SELECT owner, + object_name, + object_type +FROM all_objects +WHERE object_name IN ( + 'APEX_WORKSPACE_ACTIVITY_LOG', + 'APEX_ACTIVITY_LOG', + 'APEX_TEAM_DEV_FILES') +ORDER BY object_name, + owner; +``` + +## Usage And Load Trends + +Group by workspace and application first, then drill into pages after identifying the noisy application. + +```sql +SELECT TRUNC(view_date, 'HH24') AS hour_start, + workspace, + application_id, + application_name, + COUNT(*) AS page_events, + COUNT(DISTINCT apex_session_id) AS apex_sessions, + ROUND(AVG(elapsed_time), 3) AS avg_elapsed_seconds, + ROUND(PERCENTILE_CONT(0.95) + WITHIN GROUP (ORDER BY elapsed_time), 3) AS p95_elapsed_seconds, + MAX(elapsed_time) AS max_elapsed_seconds +FROM apex_workspace_activity_log +WHERE view_date >= SYSDATE - 1 +GROUP BY TRUNC(view_date, 'HH24'), + workspace, + application_id, + application_name +ORDER BY hour_start, + page_events DESC; +``` + +## Session Drilldown + +Use this when a user reports one bad session. Avoid selecting request payloads or sensitive item values by default. + +```sql +SELECT view_date, + workspace, + apex_user, + apex_session_id, + application_id, + page_id, + page_name, + page_view_type, + request_value, + elapsed_time, + rows_queried, + error_message +FROM apex_workspace_activity_log +WHERE apex_session_id = :apex_session_id +ORDER BY view_date, + id; +``` + +Look for latency jumps, AJAX storms, repeated authentication callbacks, missing expected page steps, and component errors. + +## Team Development File Context + +Use `APEX_TEAM_DEV_FILES` only as optional developer-artifact context. Inspect columns before selecting from it. Do not select file BLOB/CLOB payloads during triage. + +## DB Skill Usage + +DB skill in use: `db/performance/wait-events.md`, `db/performance/ash-analysis.md`, or `db/performance/awr-reports.md` only after the APEX workspace, application, page, session, and time window are identified. The APEX monitoring skill is being used for activity-log context. diff --git a/apex/monitoring/awr-wait-correlation.md b/apex/monitoring/awr-wait-correlation.md new file mode 100644 index 0000000..f0fcba8 --- /dev/null +++ b/apex/monitoring/awr-wait-correlation.md @@ -0,0 +1,58 @@ +# APEX Cross-Check With AWR Wait Events + +Use this reference only after APEX activity has identified the workspace, application, page, and time window. + +## Scope + +APEX activity chooses the incident window. Generic AWR, ASH, and wait-event interpretation belongs to DB performance skills. + +DB skill in use: `db/performance/wait-events.md`, `db/performance/ash-analysis.md`, or `db/performance/awr-reports.md` for generic database wait-event, ASH, and AWR interpretation. The APEX monitoring skill is being used for choosing the APEX time window and correlating it with database symptoms. + +## Historical Wait Cross-Check + +```sql +WITH snaps AS ( + SELECT snap_id, + dbid, + instance_number, + begin_interval_time, + end_interval_time + FROM dba_hist_snapshot + WHERE begin_interval_time >= SYSTIMESTAMP - INTERVAL '1' DAY +), +waits AS ( + SELECT s.begin_interval_time, + s.end_interval_time, + e.instance_number, + e.wait_class, + e.event_name, + e.total_waits, + e.time_waited_micro + - LAG(e.time_waited_micro) OVER ( + PARTITION BY e.dbid, e.instance_number, e.event_id + ORDER BY e.snap_id) AS waited_micro_delta + FROM dba_hist_system_event e + JOIN snaps s + ON s.snap_id = e.snap_id + AND s.dbid = e.dbid + AND s.instance_number = e.instance_number + WHERE e.wait_class <> 'Idle' +) +SELECT begin_interval_time, + end_interval_time, + instance_number, + wait_class, + event_name, + ROUND(waited_micro_delta / 1000000, 2) AS waited_seconds +FROM waits +WHERE waited_micro_delta > 0 +ORDER BY begin_interval_time DESC, + waited_seconds DESC +FETCH FIRST 50 ROWS ONLY; +``` + +## Guardrails + +- AWR and ASH require Diagnostics Pack in production. +- Database waits during an APEX window are correlation evidence, not proof of a page or region root cause. +- Confirm with SQL ID, ECID, module/action, client identifier, APEX debug, Page Performance reports, or application instrumentation. diff --git a/apex/monitoring/background-jobs.md b/apex/monitoring/background-jobs.md new file mode 100644 index 0000000..fdfcfb3 --- /dev/null +++ b/apex/monitoring/background-jobs.md @@ -0,0 +1,68 @@ +# APEX Background Job Monitoring + +Use this reference for APEX background processing, automations, scheduled work, and `APEX_APPL_JOB_LOG`. + +Version check: use `ALL_OBJECTS` and `ALL_TAB_COLUMNS` before assuming APEX job-log or automation view availability. + +## Job Log Pre-Check + +```sql +SELECT owner, + object_name, + object_type +FROM all_objects +WHERE object_name IN ( + 'APEX_APPL_JOB_LOG', + 'APEX_APPL_AUTOMATIONS', + 'APEX_APPLICATIONS') +ORDER BY object_name, + owner; +``` + +```sql +SELECT table_name, + column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name IN ( + 'APEX_APPL_JOB_LOG', + 'APEX_APPL_AUTOMATIONS', + 'APEX_APPLICATIONS') +ORDER BY table_name, + column_id; +``` + +If `APEX_APPL_JOB_LOG` is missing, use APEX Builder automation/task reports, application debug logs, application-specific job tables, and database scheduler views. Do not query internal APEX repository tables as a workaround. + +## Recent APEX Job Failures + +Adapt column names to the installed view. + +```sql +SELECT workspace, + application_id, + application_name, + job_name, + status, + started_on, + finished_on, + run_duration, + error_code, + SUBSTR(error_message, 1, 300) AS sample_error +FROM apex_appl_job_log +WHERE started_on >= SYSTIMESTAMP - INTERVAL '1' DAY + AND status <> 'SUCCESS' +ORDER BY started_on DESC +FETCH FIRST 50 ROWS ONLY; +``` + +## Scheduler Mapping + +Use APEX job name, application ID, parsing schema, and run timestamp to map APEX symptoms to `DBA_SCHEDULER_JOB_RUN_DETAILS`. Treat this as correlation until confirmed with job action, comments, module/action, or application code. + +Do not blindly call `DBMS_SCHEDULER.RUN_JOB`, `STOP_JOB`, `DISABLE`, `ENABLE`, or `DROP_JOB`. Show affected job, state, recent runs, and likely impact first; ask for confirmation before changing job state. + +## DB Skill Usage + +DB skill in use: `db/features/dbms-scheduler.md` for generic `DBMS_SCHEDULER` job design, attributes, logging levels, `max_failures`, `max_run_duration`, job classes, and operational management. The APEX monitoring skill is being used for APEX application, workspace, automation, and job-log context. diff --git a/apex/monitoring/error-handling.md b/apex/monitoring/error-handling.md new file mode 100644 index 0000000..9370a9f --- /dev/null +++ b/apex/monitoring/error-handling.md @@ -0,0 +1,109 @@ +# APEX Error Handling And Logging + +Use this reference for collecting, categorizing, and prioritizing APEX errors from `APEX_DEBUG_MESSAGES`, `APEX_ERROR_LOG`, and APEX activity logs. + +Version check: use `ALL_OBJECTS` and `ALL_TAB_COLUMNS` before assuming APEX debug, activity, or error-log view availability. + +## Error Log Pre-Check + +```sql +SELECT owner, + object_name, + object_type +FROM all_objects +WHERE object_name IN ( + 'APEX_WORKSPACE_ACTIVITY_LOG', + 'APEX_ACTIVITY_LOG', + 'APEX_DEBUG_MESSAGES', + 'APEX_ERROR_LOG') +ORDER BY object_name, + owner; +``` + +```sql +SELECT table_name, + column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name IN ( + 'APEX_WORKSPACE_ACTIVITY_LOG', + 'APEX_ACTIVITY_LOG', + 'APEX_DEBUG_MESSAGES', + 'APEX_ERROR_LOG') +ORDER BY table_name, + column_id; +``` + +If `APEX_ERROR_LOG` is missing, use `APEX_WORKSPACE_ACTIVITY_LOG`, `APEX_DEBUG_MESSAGES`, App Builder error reports, ORDS/web-server logs, and application-specific error tables. Do not query internal APEX repository tables as a workaround. + +## Collection And Priority + +```sql +SELECT workspace, + application_id, + application_name, + page_id, + page_name, + error_on_component_type, + error_on_component_name, + COUNT(*) AS error_events, + COUNT(DISTINCT apex_session_id) AS affected_sessions, + COUNT(DISTINCT apex_user) AS affected_users, + MIN(view_date) AS first_seen, + MAX(view_date) AS last_seen, + SUBSTR(MIN(error_message), 1, 300) AS sample_error +FROM apex_workspace_activity_log +WHERE view_date >= SYSDATE - 1 + AND error_message IS NOT NULL +GROUP BY workspace, + application_id, + application_name, + page_id, + page_name, + error_on_component_type, + error_on_component_name +ORDER BY error_events DESC, + affected_sessions DESC, + last_seen DESC; +``` + +Classify errors as authentication/authorization, validation/business rule, SQL/PLSQL, ORDS/REST/integration, timeout/performance, or internal/unhandled. Prioritize by production impact, affected users/sessions, recency, security risk, data-loss risk, and critical workflow impact. + +## Debug Correlation + +```sql +SELECT message_timestamp, + application_id, + page_id, + session_id, + debug_page_view_id, + message_level, + message_type, + component_type, + component_name, + SUBSTR(message, 1, 300) AS message_sample +FROM apex_debug_messages +WHERE message_timestamp >= :apex_start_time + AND message_timestamp < :apex_end_time + AND (:application_id IS NULL OR application_id = :application_id) + AND (:debug_page_view_id IS NULL OR debug_page_view_id = :debug_page_view_id) +ORDER BY message_timestamp; +``` + +Prefer `DEBUG_PAGE_VIEW_ID`, `APEX_SESSION_ID`, ECID, application/page/component, and timestamp window. Avoid verbose production debug unless scoped and temporary. + +## Quick Fix Patterns + +- Missing grant, synonym, or invalid object: confirm parsing schema and least-privilege object grants. +- Bad bind or item conversion: align APEX item type, format mask, NLS assumptions, and database column type. +- Unhandled process exception: log correlation metadata and return a safe user-facing message. +- Auth/authz misconfiguration: review authorization scheme placement, public pages, and session state protection. +- REST credential/token expiry: rotate via APEX Web Credentials; never print credential values or bearer tokens. +- Timeout from slow SQL or remote call: narrow APEX page/component/time window first. + +## DB Skill Usage + +DB skill in use: `db/security/auditing.md` for generic database audit trails. DB skill in use: `db/performance/awr-reports.md` and `db/performance/ash-analysis.md` for AWR/ASH correlation. DB skill in use: `db/monitoring/alert-log-analysis.md` for database alert log, trace, and ADR investigation. The APEX monitoring skill is being used for APEX debug/error context and incident time-window selection. + +AWR and ASH require Diagnostics Pack in production. diff --git a/apex/monitoring/ir-ig-tuning.md b/apex/monitoring/ir-ig-tuning.md new file mode 100644 index 0000000..76dd762 --- /dev/null +++ b/apex/monitoring/ir-ig-tuning.md @@ -0,0 +1,65 @@ +# Interactive Report And Grid Tuning + +Use this reference for APEX Interactive Report and Interactive Grid performance: filtering, sorting, pagination, downloads, report settings, SQL IDs, and AWR correlation. + +Version check: use `APEX_DICTIONARY` and `ALL_TAB_COLUMNS` before assuming Interactive Report or Interactive Grid metadata view availability. + +## Region Metadata Pre-Check + +```sql +SELECT owner, + object_name, + object_type +FROM all_objects +WHERE object_name IN ( + 'APEX_APPLICATION_PAGE_REGIONS', + 'APEX_APPLICATION_PAGE_IR', + 'APEX_APPLICATION_PAGE_IR_COL', + 'APEX_APPL_PAGE_IGS', + 'APEX_APPL_PAGE_IG_COLUMNS', + 'APEX_WORKSPACE_ACTIVITY_LOG', + 'APEX_DEBUG_MESSAGES') +ORDER BY object_name, + owner; +``` + +```sql +SELECT table_name, + column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name IN ( + 'APEX_APPLICATION_PAGE_REGIONS', + 'APEX_APPLICATION_PAGE_IR', + 'APEX_APPLICATION_PAGE_IR_COL', + 'APEX_APPL_PAGE_IGS', + 'APEX_APPL_PAGE_IG_COLUMNS') +ORDER BY table_name, + column_id; +``` + +## Runtime Symptoms + +Use activity logs to identify whether the pain is initial render, filtering, sorting, pagination, aggregation, save, or download. + +Red flags: + +- Filtering is slow only for wildcard, case-insensitive, or contains searches. +- Pagination is slow because the region query must sort or count a large rowset before returning the next page. +- Download is slow because it bypasses small-page pagination and exports a much larger result set. +- User-saved reports add expensive filters, control breaks, aggregates, highlights, or computations. + +## APEX-Specific Checks + +- Avoid unnecessary columns in IR/IG source SQL. Wide projections increase sort, download, network, and browser cost. +- Keep bind variable types aligned with table column types. APEX item values are strings; avoid implicit conversions. +- Prefer server-side filters with bind variables over concatenating item values into dynamic SQL. +- Limit download scope and require deliberate user action for large exports. +- For IG pages with DML, validate that any new index does not make saves unacceptably slow. + +## DB Skill Usage + +DB skill in use: `db/sql-dev/sql-tuning.md` for generic SQL tuning. DB skill in use: `db/performance/index-strategy.md` for index design. DB skill in use: `db/monitoring/top-sql-queries.md` for SQL IDs and `DBA_HIST_SQLSTAT`. DB skill in use: `db/performance/awr-reports.md` for AWR interpretation. The APEX monitoring skill is being used for IR/IG behavior, report settings, request patterns, and APEX page context. + +AWR, ASH, and `DBA_HIST_SQLSTAT` require Diagnostics Pack in production. diff --git a/apex/monitoring/mcp-availability.md b/apex/monitoring/mcp-availability.md new file mode 100644 index 0000000..59516ac --- /dev/null +++ b/apex/monitoring/mcp-availability.md @@ -0,0 +1,95 @@ +# APEX MCP Availability Guard + +Use this topic when an APEX workflow depends on database access through an MCP tool, for example listing workspaces, creating a workspace, checking `APEX_RELEASE`, checking `APEX_PATCHES`, or querying APEX runtime views. + +This is an APEX workflow guard, not database-client troubleshooting. Do not provide setup commands, client configuration advice, or connection-store instructions from this topic. + +## When To Check + +Before any APEX workflow that will run SQL or PL/SQL through MCP: + +- Confirm the MCP tool transport is available. +- Confirm a database connection can be established or is already active. +- If the APEX workflow needs a specific connection name, confirm that connection before generating change SQL. + +Use the smallest available client-side MCP check. Do not run APEX DDL, APEX administration APIs, or destructive SQL as a connectivity test. + +## Stop Condition + +If the MCP tool reports a closed transport, unavailable server, disconnected tool channel, or similar client-side transport failure, stop the APEX workflow. Do not infer database state from stale context, screenshots, previous outputs, or another UI session. + +Use this message: + +```text +APEX MCP availability check failed: the MCP transport is closed, so I cannot safely verify or change APEX state from here. I will pause the APEX workflow until the MCP tool channel is available again. +``` + +If the user has APEX open in a browser, make clear that this does not prove the MCP tool channel is available: + +```text +Your APEX browser session may still be connected, but this APEX workflow needs the MCP tool channel. Those are separate sessions, and I cannot use browser state as confirmation for database changes. +``` + +## Recovery Behavior + +After the user says MCP is available again: + +1. Repeat the MCP availability check. +2. Reconnect or confirm the active database connection. +3. Re-read APEX state from the database. +4. If an APEX provisioning workflow may have been interrupted after create steps, inventory each planned artifact individually with `apex/workspace/lifecycle.md#provisioning-recovery-after-interruption`. +5. Ask whether the user wants to roll back the listed artifacts before continuing or retrying. +6. Continue only from freshly verified state. + +Never continue a workspace create, user create, patch check, or removal workflow from pre-failure assumptions. + +## APEX State To Re-Read + +Pick the smallest relevant verification query after MCP recovers: + +```sql +SELECT version_no +FROM apex_release; +``` + +```sql +SELECT workspace_id, + workspace, + schemas, + applications, + apex_developers, + apex_workspace_administrators +FROM apex_workspaces +ORDER BY workspace; +``` + +For user provisioning recovery: + +```sql +SELECT workspace_name, + user_name, + email, + is_admin, + is_application_developer, + account_locked +FROM apex_workspace_apex_users +WHERE workspace_name = :workspace_name + AND user_name = :user_name; +``` + +For interrupted workspace/app provisioning, use the lifecycle recovery checklist to re-read the planned workspace, schema mappings, APEX users, database users, application tables, and APEX applications one by one before asking: + +```text +I found the following artifacts from the interrupted APEX provisioning workflow: . Do you want me to roll back the listed artifacts by removing only these objects? +``` + +## DB Skill Usage + +No DB skill is used for this topic. This topic only decides whether an APEX workflow may continue when MCP-backed database access is unavailable. + +## Guardrails + +- Do not continue an APEX workflow after `Transport closed` because a previous query succeeded. +- Do not treat a browser APEX session as proof that MCP database access is available. +- Do not re-run a create step without first checking whether the object was committed before the transport failed. +- Do not explain database-client internals when the user only needs an APEX workflow stop/retry decision. diff --git a/apex/monitoring/page-performance.md b/apex/monitoring/page-performance.md new file mode 100644 index 0000000..b67d99b --- /dev/null +++ b/apex/monitoring/page-performance.md @@ -0,0 +1,76 @@ +# APEX Page Performance Profiler + +Use this reference for the slowest APEX pages, regions, Page Performance reports, `APEX_WORKSPACE_PAGE_VIEW_DETAIL`, and `DBA_HIST_SQLSTAT` correlation. + +Version check: use `APEX_DICTIONARY` and `ALL_TAB_COLUMNS` before assuming page-view detail or activity-log view availability. + +## Logging Pre-Check + +Page-view detail logging can increase log volume and may capture sensitive context. Enable or increase it only for the affected application, workspace, or test window when possible. + +```sql +SELECT owner, + object_name, + object_type +FROM all_objects +WHERE object_name IN ( + 'APEX_WORKSPACE_ACTIVITY_LOG', + 'APEX_ACTIVITY_LOG', + 'APEX_WORKSPACE_PAGE_VIEWS', + 'APEX_WORKSPACE_PAGE_VIEW_DETAIL', + 'APEX_DEBUG_MESSAGES') +ORDER BY object_name, + owner; +``` + +```sql +SELECT table_name, + column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name IN ( + 'APEX_WORKSPACE_ACTIVITY_LOG', + 'APEX_ACTIVITY_LOG', + 'APEX_WORKSPACE_PAGE_VIEWS', + 'APEX_WORKSPACE_PAGE_VIEW_DETAIL', + 'APEX_DEBUG_MESSAGES') +ORDER BY table_name, + column_id; +``` + +## Slowest Pages + +```sql +SELECT workspace, + application_id, + application_name, + page_id, + page_name, + COUNT(*) AS page_events, + COUNT(DISTINCT apex_session_id) AS apex_sessions, + ROUND(AVG(elapsed_time), 3) AS avg_elapsed_seconds, + ROUND(PERCENTILE_CONT(0.95) + WITHIN GROUP (ORDER BY elapsed_time), 3) AS p95_elapsed_seconds, + MAX(elapsed_time) AS max_elapsed_seconds, + MIN(view_date) AS first_seen, + MAX(view_date) AS last_seen +FROM apex_workspace_activity_log +WHERE view_date >= SYSDATE - 1 +GROUP BY workspace, + application_id, + application_name, + page_id, + page_name +HAVING COUNT(*) >= 10 +ORDER BY p95_elapsed_seconds DESC +FETCH FIRST 20 ROWS ONLY; +``` + +Use APEX Builder Page Performance reports or narrow SQL/CSV extracts of page, region, elapsed time, session, `DEBUG_PAGE_VIEW_ID`, and timestamp metadata. Do not export debug CLOBs, request values, item payloads, or file payloads unless explicitly confirmed. + +## DB Skill Usage + +DB skill in use: `db/monitoring/top-sql-queries.md` for `DBA_HIST_SQLSTAT`, top-SQL resource dimensions, and historical SQL-stat interpretation. DB skill in use: `db/performance/awr-reports.md` for AWR report interpretation. The APEX monitoring skill is being used for page, region, session, and report context. + +AWR, ASH, and `DBA_HIST_SQLSTAT` require Diagnostics Pack in production. diff --git a/apex/monitoring/rest-data-sources.md b/apex/monitoring/rest-data-sources.md new file mode 100644 index 0000000..df590f7 --- /dev/null +++ b/apex/monitoring/rest-data-sources.md @@ -0,0 +1,68 @@ +# APEX REST Data Source Health Check + +Use this reference for APEX REST Data Sources, Web Source Modules, REST Source Synchronization, `APEX_WEBSERVICE_LOG`, latency, HTTP status codes, and component impact. + +Version check: use `APEX_DICTIONARY` and `ALL_TAB_COLUMNS` before assuming REST Data Source, Web Source, or webservice-log view availability. + +## REST Source Inventory + +```sql +SELECT view_name, + comments +FROM apex_dictionary +WHERE view_name LIKE 'APEX%WEB%SRC%' + OR view_name LIKE 'APEX%REST%SOURCE%' + OR view_name LIKE 'APEX%WEBSERVICE%LOG%' +ORDER BY view_name; +``` + +```sql +SELECT table_name, + column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name IN ( + 'APEX_APPL_WEB_SRC_MODULES', + 'APEX_APPL_WEB_SRC_OPERATIONS', + 'APEX_APPL_WEB_SRC_PARAMETERS', + 'APEX_WEBSERVICE_LOG', + 'APEX_REST_SOURCE_SYNC_LOG') +ORDER BY table_name, + column_id; +``` + +Do not print credentials, authorization headers, API keys, OAuth tokens, or full URLs with secrets. + +## Latency And Error Codes + +Use `APEX_WEBSERVICE_LOG` when available. Inspect installed columns before selecting status-code or elapsed-time fields. + +```sql +SELECT application_id, + module_id, + module_name, + operation_id, + status_code, + COUNT(*) AS calls, + ROUND(AVG(elapsed_time), 3) AS avg_elapsed_seconds, + MAX(elapsed_time) AS max_elapsed_seconds, + MIN(request_date) AS first_seen, + MAX(request_date) AS last_seen +FROM apex_webservice_log +WHERE request_date >= SYSTIMESTAMP - INTERVAL '1' DAY +GROUP BY application_id, + module_id, + module_name, + operation_id, + status_code +ORDER BY max_elapsed_seconds DESC; +``` + +Map symptoms back to APEX pages and components with `APEX_WORKSPACE_ACTIVITY_LOG`. Decide whether the issue is global to a remote service or isolated to a component, operation, parameter set, or page request. + +## DB Skill Usage + +DB skill in use: `db/ords/ords-monitoring.md` for generic ORDS monitoring and request/pool troubleshooting. DB skill in use: `db/performance/ash-analysis.md` and `db/performance/wait-events.md` for `DBA_HIST_ACTIVE_SESS_HISTORY`, `V$ACTIVE_SESSION_HISTORY`, wait-class, and network-wait interpretation. The APEX monitoring skill is being used for REST Data Source metadata, APEX webservice logs, and component impact. + +ASH and `DBA_HIST_ACTIVE_SESS_HISTORY` require Diagnostics Pack in production. diff --git a/apex/monitoring/security-review.md b/apex/monitoring/security-review.md new file mode 100644 index 0000000..116a223 --- /dev/null +++ b/apex/monitoring/security-review.md @@ -0,0 +1,12 @@ +# APEX Monitoring Security Review + +Use this checklist after substantial APEX monitoring, replay, debug, error-log, performance, REST, or background-job work. + +- Scope: APEX logs, debug context, Session Replay output, page/runtime context, workspace/application/page IDs, and time windows stayed in this skill; generic AWR, ASH, wait-event, SQL tuning, ORDS, scheduler, auditing, or alert-log analysis was routed to `db/...`. +- DB usage messages: every generic DB step has a visible `DB skill in use:` message naming the relevant DB skill path. +- Sensitive data: activity logs, debug messages, error logs, request values, Team Development files, Session Replay output, and exports avoid unnecessary payload columns, BLOBs, CLOBs, headers, tokens, item values, and secret-bearing URLs. +- Version checks: APEX views and columns were discovered with `APEX_DICTIONARY`, `ALL_OBJECTS`, or `ALL_TAB_COLUMNS` before version-specific SQL was generated. +- Licensed features: AWR, ASH, and Diagnostics Pack usage was called out; non-licensed fallbacks such as live `V$SESSION`, `V$SQL`, ORDS logs, APEX debug, and application instrumentation were considered. +- Security boundaries: APEX session state, hidden items, read-only items, client-side checks, and replay observations were not treated as access control. +- Reproduction safety: journey replay and background-job reruns avoid production side effects such as emails, payments, notifications, approvals, destructive DML, or external calls unless explicitly confirmed. +- Evidence quality: AWR/ASH candidates are treated as correlation evidence, not proof, unless confirmed by SQL ID, ECID, module/action, client identifier, debug page-view ID, or application instrumentation. diff --git a/apex/monitoring/user-journey-replay.md b/apex/monitoring/user-journey-replay.md new file mode 100644 index 0000000..7b26676 --- /dev/null +++ b/apex/monitoring/user-journey-replay.md @@ -0,0 +1,72 @@ +# End-To-End User Journey Replay + +Use this reference for reproducing critical APEX paths with Session Replay and `APEX_ACTIVITY_LOG`. + +Version check: use `APEX_DICTIONARY` and `ALL_TAB_COLUMNS` before assuming Session Replay, activity-log, debug, or page-view detail availability. + +## Replay Pre-Check + +Session Replay availability, retention, and exposed metadata vary by APEX release and instance configuration. Use App Builder reports when replay is not exposed through supported SQL views. + +```sql +SELECT view_name, + comments +FROM apex_dictionary +WHERE view_name LIKE '%ACTIVITY%LOG%' + OR view_name LIKE '%DEBUG%MESSAGE%' + OR view_name LIKE '%PAGE%VIEW%' + OR view_name LIKE '%REPLAY%' +ORDER BY view_name; +``` + +```sql +SELECT table_name, + column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name IN ( + 'APEX_ACTIVITY_LOG', + 'APEX_WORKSPACE_ACTIVITY_LOG', + 'APEX_DEBUG_MESSAGES', + 'APEX_WORKSPACE_PAGE_VIEW_DETAIL') +ORDER BY table_name, + column_id; +``` + +## Journey Path Reconstruction + +```sql +SELECT view_date, + apex_user, + apex_session_id, + application_id, + application_name, + page_id, + page_name, + page_view_type, + request_value, + elapsed_time, + rows_queried, + debug_page_view_id, + ecid, + CASE WHEN error_message IS NOT NULL THEN 'Y' ELSE 'N' END AS has_error +FROM apex_activity_log +WHERE apex_session_id = :apex_session_id +ORDER BY view_date, + id; +``` + +Compare one failed session with one successful baseline from the same application version and similar data shape. Capture correlation metadata only: APEX session, user, page, request, `DEBUG_PAGE_VIEW_ID`, ECID, timestamp window, and timing/error summary. + +## Replay Safety + +- Do not export Session Replay output unless privacy handling and incident need are confirmed. +- Reproduce destructive, externally visible, payment, email, notification, approval, or workflow actions in non-production first. +- Treat missing steps as evidence: branches, authorization failures, validations, AJAX callbacks, redirects, or expired sessions can remove expected page views. + +## DB Skill Usage + +DB skill in use: `db/performance/ash-analysis.md`, `db/performance/awr-reports.md`, and `db/performance/wait-events.md` for generic ASH/AWR and wait-event interpretation. The APEX monitoring skill is being used for Session Replay, activity-log path, and journey reproduction context. + +AWR and ASH require Diagnostics Pack in production. diff --git a/apex/security/audit-columns.md b/apex/security/audit-columns.md new file mode 100644 index 0000000..64f86d8 --- /dev/null +++ b/apex/security/audit-columns.md @@ -0,0 +1,51 @@ +# APEX Application Table Audit Columns + +Use this pattern for APEX-owned application tables when the application needs simple change metadata. This is application-level audit metadata, not a replacement for tamper-resistant database auditing. + +DB skill in use: `db/security/auditing.md` for generic database auditing, Unified Auditing, FGA, compliance audit policies, or tamper-resistant audit design. The APEX security skill is being used for APEX-owned application-table audit-column context. + +## Columns + +For new APEX application tables, prefer consistent audit columns: + +```sql +created_at TIMESTAMP WITH LOCAL TIME ZONE, +created_by VARCHAR2(255), +updated_at TIMESTAMP WITH LOCAL TIME ZONE, +updated_by VARCHAR2(255) +``` + +## Trigger Pattern + +Use the APEX session user when available, with a database-user fallback. In APEX runtime, `USER` and `SESSION_USER` commonly identify the parsing schema, not the end user. + +```sql +CREATE OR REPLACE TRIGGER sales_orders_biu_audit + BEFORE INSERT OR UPDATE ON sales_orders + FOR EACH ROW +DECLARE + l_actor VARCHAR2(255); +BEGIN + l_actor := COALESCE( + NULLIF(SYS_CONTEXT('APEX$SESSION', 'APP_USER'), ''), + SYS_CONTEXT('USERENV', 'SESSION_USER')); + + IF INSERTING THEN + :NEW.created_at := COALESCE(:NEW.created_at, SYSTIMESTAMP); + :NEW.created_by := COALESCE(:NEW.created_by, l_actor); + END IF; + + :NEW.updated_at := SYSTIMESTAMP; + :NEW.updated_by := l_actor; +END; +/ +``` + +For tables where callers must not override creation metadata, assign `created_at` and `created_by` unconditionally on insert instead of using `COALESCE`. + +## Guardrails + +- Do not use audit-column triggers to copy passwords, tokens, large payloads, BLOBs, CLOBs, or sensitive free text into audit tables by default. +- On hot tables, bulk-load paths, or ETL-heavy workloads, call out row-level trigger cost. +- Consider database-generic alternatives such as compound triggers, history tables, Unified Auditing, or Flashback Data Archive through the relevant DB skill. +- The trigger records application change metadata only; it is not a replacement for tamper-resistant database auditing. diff --git a/apex/security/guardrails.md b/apex/security/guardrails.md new file mode 100644 index 0000000..49ee45b --- /dev/null +++ b/apex/security/guardrails.md @@ -0,0 +1,47 @@ +# APEX Security Guardrails + +Apply these APEX-specific rules before generating SQL, scripts, or operational steps. + +## Role Boundaries + +Keep APEX role boundaries clear: workspace administrator, developer, end user, parsing schema, database-login user, ORDS/APEX runtime account, and DBA/admin account are different security contexts. + +Do not treat parsing schemas as personal interactive logins in production. If a parsing schema is only technical, keep it narrow and document whether it should be locked outside deployment windows. + +## Least Privilege + +Do not grant broad privileges such as `DBA`, `SYSDBA`, `SELECT ANY TABLE`, `EXECUTE ANY PROCEDURE`, `CREATE ANY TABLE`, `GRANT ANY ROLE`, `GRANT ANY PRIVILEGE`, or `WITH ADMIN OPTION` for ordinary APEX provisioning. + +DB skill in use: `db/security/privilege-management.md` for generic database privilege design. The APEX security skill is being used for APEX workspace, parsing-schema, and runtime-account context. + +## Supported Interfaces + +Do not write directly to internal APEX repository tables. Use supported APEX APIs and views. + +Before querying APEX views or package signatures, inspect version-specific availability through `ALL_TAB_COLUMNS`, `ALL_ARGUMENTS`, `APEX_DICTIONARY`, or `APEX_RELEASE`. + +## Session State And Tenant Isolation + +APEX session state, hidden items, read-only items, and client-side checks are not a security boundary. Use server-side authorization, validations, and database privileges. + +For tenant isolation or sensitive row access, describe the APEX authorization context, then use database-enforced isolation. + +DB skill in use: `db/security/row-level-security.md` for VPD/RLS implementation details. The APEX security skill is being used for APEX authorization and UI context. + +## Secrets, Logs, And Exports + +Do not hard-code secrets in APEX examples, exports, logs, scripts, or chat output. This includes database passwords, web credentials, OAuth secrets, SMTP credentials, wallet passwords, and API tokens. + +Treat APEX activity logs, debug logs, error messages, request values, Team Development files, static files, and exports as potentially sensitive. Avoid selecting unnecessary CLOB/BLOB payloads or secret-bearing values during triage. + +Review APEX exports before committing or sharing. They may contain application logic, URLs, authorization schemes, build options, static files, credential references, defaults, and sensitive metadata. + +DB skill in use: `db/security/encryption.md`, `db/security/network-security.md`, or `db/security/data-masking.md` for generic encryption, TLS, network ACL, redaction, and masking implementation. The APEX security skill is being used for APEX-specific exposure and export/log context. + +## Common Mistakes + +- Treating APEX session state, hidden items, read-only items, or client-side checks as a security boundary. +- Querying or updating internal APEX repository tables when supported APEX APIs or views should be used. +- Duplicating generic database security guidance in an APEX skill instead of using `db/security/*`. +- Selecting unnecessary debug, request, Team Development, BLOB, CLOB, or export payloads during operational triage. +- Creating schemas or workspace users with broad privileges because the script runs as an administrator. diff --git a/apex/security/safety-messages.md b/apex/security/safety-messages.md new file mode 100644 index 0000000..6000a59 --- /dev/null +++ b/apex/security/safety-messages.md @@ -0,0 +1,49 @@ +# APEX Security Safety Messages + +Use these message patterns when a user request crosses an APEX safety boundary. + +```text +DB skill in use: db/security/privilege-management.md for generic privilege analysis. The APEX skill is being used only for APEX workspace and parsing-schema context. +``` + +```text +Safety note: this is generic database security guidance, not APEX-specific behavior. I will route the generic part to db/security/auditing.md and keep the APEX skill focused on the APEX action that needs auditability. +``` + +```text +Safety stop: direct writes to internal APEX repository tables are not supported by this skill. I will use supported APEX APIs or views instead. +``` + +```text +Safety stop: this would grant a broad administrative privilege. Please confirm the exact purpose, target account, and why a narrower privilege is not sufficient before I generate SQL. +``` + +```text +Safety stop: this operation is destructive. I will first list affected workspaces, schemas, APEX users, database users, and related components, then require a fresh exact English confirmation before generating or running delete steps. If database users are included, you must confirm that deleting the listed users/components is your own will. +``` + +```text +Recovery check: this APEX provisioning workflow was interrupted. I will inventory the planned workspace, schema mappings, APEX users, database users, application tables, and APEX applications one by one, then ask whether you want to roll back only the listed artifacts. +``` + +```text +Sensitive data warning: APEX logs, debug output, request values, Team Development files, and exports may contain secrets or personal data. I will avoid selecting payload columns unless you explicitly need them. +``` + +```text +Security warning: APEX session state, hidden items, read-only items, and client-side checks are not security boundaries. I will use server-side authorization, validations, and database privileges for enforcement. +``` + +```text +Audit note: the trigger pattern records application change metadata only. It is not a replacement for tamper-resistant database auditing; use db/security/auditing.md for that. +``` + +```text +Version check: this APEX view or package signature can vary by release. I will inspect available columns or arguments before generating version-specific SQL. +``` + +```text +APEX MCP availability check failed: the MCP transport is closed, so I cannot safely verify or change APEX state from here. I will pause the APEX workflow until the MCP tool channel is available again. +``` + +Emit these messages before continuing when the request involves broad grants, direct internal repository writes, destructive changes, interrupted provisioning recovery, sensitive logs/exports, session-state security assumptions, audit triggers, version-sensitive APEX views, or unavailable MCP-backed database access. diff --git a/apex/security/security-review.md b/apex/security/security-review.md new file mode 100644 index 0000000..7ef0952 --- /dev/null +++ b/apex/security/security-review.md @@ -0,0 +1,12 @@ +# APEX Security Review + +Use this checklist after substantial APEX workspace or application-support changes. + +- Privileges: parsing schemas, workspace users, database-login users, and automation accounts have only the required rights. +- Role boundaries: workspace administrator, developer, end user, parsing schema, runtime account, and DBA/admin roles are not mixed. +- Secrets: no real passwords, web credentials, OAuth secrets, SMTP credentials, wallet passwords, or API tokens appear in scripts, exports, logs, examples, or chat output. +- Data exposure: activity logs, debug logs, request values, Team Development files, static files, exports, and audit columns do not expose unnecessary sensitive data. +- Auditability: workspace creation/removal, user creation, schema mapping changes, imports/exports, grants, role changes, and credential changes are traceable. +- Version and cloud limits: APEX package signatures, APEX view columns, Autonomous Database limits, and managed-service restrictions are checked before use. +- Destructive actions: affected objects are listed, protected accounts are blocked, and explicit confirmations are required. +- DB skill usage: generic security, performance, ORDS, SQLcl, masking, encryption, VPD/RLS, or auditing work is routed to the relevant `db/...` skill and announced with a visible `DB skill in use:` message. diff --git a/apex/test-apex-skills.sh b/apex/test-apex-skills.sh new file mode 100644 index 0000000..f2bbd79 --- /dev/null +++ b/apex/test-apex-skills.sh @@ -0,0 +1,435 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +APEX_DIR="$SCRIPT_DIR" +ROOT_SKILL="$APEX_DIR/SKILL.md" +DB_SKILLS_ROOT="${DB_SKILLS_ROOT:-"$(cd "$APEX_DIR/../.." && pwd)/oracle-db-skills"}" + +failures=0 + +begin_check() { + printf ' - %s\n' "$1" +} + +pass() { + printf ' ok: %s\n' "$1" +} + +fail() { + printf ' not ok: %s\n' "$1" + failures=$((failures + 1)) +} + +print_section() { + printf '\n%s\n' "$1" +} + +require_file() { + local file="$1" + local label="$2" + + begin_check "$label exists" + if [[ -f "$file" ]]; then + pass "$label exists" + else + fail "$label missing: $file" + fi +} + +require_contains() { + local file="$1" + local pattern="$2" + local label="$3" + + begin_check "$label" + if grep -Eq "$pattern" "$file"; then + pass "$label" + else + fail "$label" + fi +} + +reject_contains() { + local file="$1" + local pattern="$2" + local label="$3" + + begin_check "$label" + if grep -Eq "$pattern" "$file"; then + fail "$label" + else + pass "$label" + fi +} + +require_tree_contains() { + local dir="$1" + local pattern="$2" + local label="$3" + + begin_check "$label" + if grep -REq --include='*.md' "$pattern" "$dir"; then + pass "$label" + else + fail "$label" + fi +} + +reject_tree_contains() { + local dir="$1" + local pattern="$2" + local label="$3" + + begin_check "$label" + if grep -REq --include='*.md' "$pattern" "$dir"; then + fail "$label" + else + pass "$label" + fi +} + +print_section "APEX root skill" +require_file "$ROOT_SKILL" "apex/SKILL.md" +require_contains "$ROOT_SKILL" '^---$' "apex/SKILL.md has YAML frontmatter" +require_contains "$ROOT_SKILL" '^name: apex$' "apex/SKILL.md has domain name" +require_contains "$ROOT_SKILL" '^description: ' "apex/SKILL.md has description" +require_contains "$ROOT_SKILL" 'Only the root `apex/SKILL.md` is a skill entry point' "apex/SKILL.md documents root-only skill entry" +require_contains "$ROOT_SKILL" '^## Routing$' "apex/SKILL.md documents category routing" +require_contains "$ROOT_SKILL" '^## Scope$' "apex/SKILL.md documents APEX scope" +require_contains "$ROOT_SKILL" '^## Safety$' "apex/SKILL.md documents safety rules" +require_contains "$ROOT_SKILL" '^## Safety Messages$' "apex/SKILL.md points to user-facing safety messages" +require_contains "$ROOT_SKILL" '^## Documentation$' "apex/SKILL.md documents documentation version policy" +require_contains "$ROOT_SKILL" 'read only the specific topic needed for the request' "apex/SKILL.md uses progressive topic loading" +require_contains "$ROOT_SKILL" '^## Token Use$' "apex/SKILL.md documents token-use rules" +require_contains "$ROOT_SKILL" 'Load one routed topic first' "apex/SKILL.md avoids loading multiple topics by default" +require_contains "$ROOT_SKILL" 'https://apex.oracle.com/en/learn/documentation/' "apex/SKILL.md points to official APEX documentation landing page" +require_contains "$ROOT_SKILL" 'newest available documentation unless the user names a specific installed APEX version' "apex/SKILL.md requires newest docs by default" +require_contains "$ROOT_SKILL" 'DB skill in use: db/' "apex/SKILL.md includes exact DB skill usage message pattern" +require_contains "$ROOT_SKILL" 'Keep APEX skills APEX-specific' "apex/SKILL.md requires APEX-specific scope" +require_contains "$ROOT_SKILL" 'Before adding or expanding an APEX skill, check whether the generic database topic is already covered under `db/`' "apex/SKILL.md requires pre-extension DB overlap check" +require_contains "$ROOT_SKILL" 'Privilege management, auditing, encryption, network security, data masking, VPD/RLS, AWR, ASH, wait events, SQL tuning, SQLcl basics' "apex/SKILL.md lists generic DB topics not to duplicate" +require_contains "$ROOT_SKILL" 'APEX_UTIL' "apex/SKILL.md lists APEX-specific APIs" +require_contains "$ROOT_SKILL" 'APEX_INSTANCE_ADMIN' "apex/SKILL.md lists APEX instance admin API" +require_contains "$ROOT_SKILL" 'APEX_APPLICATION_INSTALL' "apex/SKILL.md lists APEX application install API" +require_contains "$ROOT_SKILL" 'SELECT ANY TABLE' "apex/SKILL.md blocks broad SELECT ANY TABLE grants" +require_contains "$ROOT_SKILL" 'EXECUTE ANY PROCEDURE' "apex/SKILL.md blocks broad EXECUTE ANY PROCEDURE grants" +require_contains "$ROOT_SKILL" 'GRANT ANY PRIVILEGE' "apex/SKILL.md blocks broad GRANT ANY PRIVILEGE grants" +require_contains "$ROOT_SKILL" 'workspace administrator, developer, end user, parsing schema, database-login user, ORDS/APEX runtime account, and DBA/admin account' "apex/SKILL.md separates APEX security roles" +require_contains "$ROOT_SKILL" 'Do not treat APEX parsing schemas as personal interactive logins' "apex/SKILL.md protects parsing schemas" +require_contains "$ROOT_SKILL" 'Do not write directly to internal APEX repository tables' "apex/SKILL.md blocks direct APEX repository writes" +require_contains "$ROOT_SKILL" 'ALL_TAB_COLUMNS' "apex/SKILL.md requires view/column checks" +require_contains "$ROOT_SKILL" 'APEX session state, hidden items, read-only items, or client-side checks' "apex/SKILL.md rejects session-state security boundary" +require_contains "$ROOT_SKILL" 'db/security/row-level-security.md' "apex/SKILL.md hands off VPD/RLS" +require_contains "$ROOT_SKILL" 'APEX exports may contain' "apex/SKILL.md warns about sensitive exports" +require_contains "$ROOT_SKILL" 'created_at' "apex/SKILL.md includes audit-column pattern" +require_contains "$ROOT_SKILL" 'db/security/auditing.md' "apex/SKILL.md hands off DB auditing" +require_contains "$ROOT_SKILL" 'AWR/ASH/Diagnostics Pack' "apex/SKILL.md marks licensed diagnostics features" +require_contains "$ROOT_SKILL" 'security review covering privileges, secrets, auditability, data exposure, version/cloud restrictions, and destructive actions' "apex/SKILL.md requires security review for substantial additions" + +print_section "APEX tree layout" +begin_check "APEX subdirectories do not contain SKILL.md files" +nested_skill_count="$(find "$APEX_DIR" -mindepth 2 -maxdepth 2 -type f -name 'SKILL.md' | wc -l | tr -d '[:space:]')" +if [[ "$nested_skill_count" -eq 0 ]]; then + pass "APEX subdirectories do not contain SKILL.md files" +else + fail "APEX subdirectories contain SKILL.md files" +fi + +begin_check "APEX tree follows db-style two-level file layout" +deep_files_count="$(find "$APEX_DIR" -mindepth 4 -type f | wc -l | tr -d '[:space:]')" +if [[ "$deep_files_count" -eq 0 ]]; then + pass "APEX tree follows db-style two-level file layout" +else + fail "APEX tree has files below category subdirectories" +fi + +print_section "Topic files" +workspace_topics=( + "$APEX_DIR/workspace/lifecycle.md" + "$APEX_DIR/workspace/resource-governance.md" + "$APEX_DIR/workspace/users-and-auth.md" + "$APEX_DIR/workspace/schema-mapping.md" + "$APEX_DIR/workspace/removal.md" + "$APEX_DIR/workspace/version-notes.md" + "$APEX_DIR/workspace/security-review.md" +) + +security_topics=( + "$APEX_DIR/security/safety-messages.md" + "$APEX_DIR/security/guardrails.md" + "$APEX_DIR/security/audit-columns.md" + "$APEX_DIR/security/security-review.md" +) + +monitoring_topics=( + "$APEX_DIR/monitoring/activity-log.md" + "$APEX_DIR/monitoring/error-handling.md" + "$APEX_DIR/monitoring/user-journey-replay.md" + "$APEX_DIR/monitoring/background-jobs.md" + "$APEX_DIR/monitoring/rest-data-sources.md" + "$APEX_DIR/monitoring/page-performance.md" + "$APEX_DIR/monitoring/ir-ig-tuning.md" + "$APEX_DIR/monitoring/awr-wait-correlation.md" + "$APEX_DIR/monitoring/mcp-availability.md" + "$APEX_DIR/monitoring/security-review.md" +) + +deployment_topics=( + "$APEX_DIR/deployment/pre-check.md" + "$APEX_DIR/deployment/export-review.md" + "$APEX_DIR/deployment/import-promotion.md" + "$APEX_DIR/deployment/post-deploy-validation.md" + "$APEX_DIR/deployment/security-review.md" + "$APEX_DIR/deployment/patching.md" +) + +for topic_file in "${workspace_topics[@]}" "${security_topics[@]}" "${monitoring_topics[@]}" "${deployment_topics[@]}"; do + rel="${topic_file#$APEX_DIR/}" + require_file "$topic_file" "$rel topic" + require_contains "$ROOT_SKILL" "$rel" "apex/SKILL.md routes $rel" +done + +print_section "Workspace checks" +workspace_scope="$APEX_DIR/workspace" +require_tree_contains "$workspace_scope" 'APEX_WORKSPACES' "workspace scope covers workspace inventory" +require_tree_contains "$workspace_scope" 'APEX_WORKSPACE_SCHEMAS' "workspace scope covers schema mappings" +require_tree_contains "$workspace_scope" 'APEX_WORKSPACE_APEX_USERS' "workspace scope covers APEX users" +require_tree_contains "$workspace_scope" 'APEX_WORKSPACE_QUOTAS' "workspace scope checks workspace quota view" +require_tree_contains "$workspace_scope" 'FILE_STORAGE_MAX|file-storage|file storage' "workspace scope covers file storage quota" +require_tree_contains "$workspace_scope" 'RM_CONSUMER_GROUP|Resource Manager' "workspace scope covers resource manager mapping" +require_tree_contains "$workspace_scope" 'db/security/privilege-management.md' "workspace scope marks privilege DB skill usage" +require_tree_contains "$workspace_scope" 'db/monitoring/space-management.md' "workspace scope marks space analysis DB skill usage" +require_tree_contains "$workspace_scope" 'db/performance/ash-analysis.md' "workspace scope marks ASH analysis DB skill usage" +require_tree_contains "$workspace_scope" 'DB skill in use:' "workspace scope has visible DB skill usage message pattern" +require_tree_contains "$workspace_scope" 'SELECT ANY TABLE' "workspace scope blocks broad grants" +require_tree_contains "$workspace_scope" 'direct writes to internal APEX repository tables|Do not query or update internal APEX repository tables|not direct writes to internal APEX repository tables' "workspace scope blocks direct repository writes" +require_tree_contains "$workspace_scope" 'Parsing Schema Guardrails' "workspace scope has parsing schema guardrails" +require_contains "$APEX_DIR/workspace/lifecycle.md" 'Always ask whether the workspace should use a new database user/schema or an existing database user/schema' "workspace lifecycle asks for new or existing database user" +require_contains "$APEX_DIR/workspace/lifecycle.md" 'Do not infer this from the requested workspace name' "workspace lifecycle does not infer schema choice from workspace name" +require_tree_contains "$workspace_scope" 'PDB_ADMIN' "workspace scope excludes PDB_ADMIN from parsing schemas" +require_tree_contains "$workspace_scope" 'ORDS_METADATA' "workspace scope excludes ORDS_METADATA from parsing schemas" +require_tree_contains "$workspace_scope" 'ORDS_PUBLIC_USER' "workspace scope excludes ORDS_PUBLIC_USER from parsing schemas" +require_tree_contains "$workspace_scope" 'ORDS\_%' "workspace scope excludes ORDS service schemas from parsing schemas" +require_tree_contains "$workspace_scope" 'Welcome!123' "workspace scope documents temporary fallback password" +require_tree_contains "$workspace_scope" 'must change it on first login' "workspace scope requires first-login password change message" +require_contains "$APEX_DIR/workspace/removal.md" 'fresh exact English confirmation' "workspace removal requires fresh English confirmation" +require_contains "$APEX_DIR/workspace/removal.md" 'this is my own will' "workspace removal asks user to confirm own will" +require_contains "$APEX_DIR/workspace/removal.md" "p_drop_users[[:space:]]*=>[[:space:]]*'N'" "workspace removal keeps drop users disabled by default" +require_contains "$APEX_DIR/workspace/removal.md" "p_drop_users[[:space:]]*=>[[:space:]]*'Y'" "workspace removal allows dropping related users only in explicit component cleanup" +require_contains "$APEX_DIR/workspace/removal.md" "p_drop_tablespaces[[:space:]]*=>[[:space:]]*'N'" "workspace removal keeps drop tablespaces disabled by default" +reject_tree_contains "$workspace_scope" "APEX_UTIL.REMOVE_USER|DROP[[:space:]]+USER|p_drop_tablespaces[[:space:]]*=>[[:space:]]*'Y'" "workspace scope does not teach direct APEX user/database user/tablespace deletion" +require_tree_contains "$workspace_scope" 'db/security/privilege-management.md.*generic grants|generic grants.*db/security/privilege-management.md' "workspace scope hands generic grants to DB skill" +require_tree_contains "$workspace_scope" 'Existing Schema Privilege Check' "workspace scope checks privileges for reused parsing schemas" +require_tree_contains "$workspace_scope" 'dba_sys_privs' "workspace scope queries existing schema system privileges" +require_tree_contains "$workspace_scope" 'dba_ts_quotas' "workspace scope checks existing schema tablespace quotas" +require_contains "$APEX_DIR/workspace/schema-mapping.md" 'Oracle AI Database 26ai' "workspace schema mapping handles 26ai-specific privileges" +require_contains "$APEX_DIR/workspace/schema-mapping.md" 'CREATE MLE' "workspace schema mapping includes CREATE MLE for 26ai MLE use" +require_contains "$APEX_DIR/workspace/schema-mapping.md" 'EXECUTE DYNAMIC MLE' "workspace schema mapping includes EXECUTE DYNAMIC MLE for 26ai MLE use" +require_tree_contains "$workspace_scope" 'If privileges are correct, continue' "workspace scope continues when existing schema privileges are correct" +require_tree_contains "$workspace_scope" 'Do you want me to route the privilege adjustment through db/security/privilege-management.md before continuing' "workspace scope asks before privilege adjustment" +require_contains "$APEX_DIR/workspace/lifecycle.md" 'Provisioning Recovery After Interruption' "workspace lifecycle has interrupted provisioning recovery" +require_contains "$APEX_DIR/workspace/lifecycle.md" 'inventory each planned artifact individually' "workspace recovery inventories artifacts individually" +require_contains "$APEX_DIR/workspace/lifecycle.md" 'apex_applications' "workspace recovery checks APEX applications" +require_contains "$APEX_DIR/workspace/lifecycle.md" 'all_objects' "workspace recovery checks application table artifacts" +require_contains "$APEX_DIR/workspace/lifecycle.md" 'created, missing, or unknown' "workspace recovery reports per-artifact status" +require_contains "$APEX_DIR/workspace/lifecycle.md" 'Do you want me to roll back the listed artifacts by removing only these objects' "workspace recovery asks before rollback cleanup" +require_contains "$APEX_DIR/workspace/version-notes.md" 'https://apex.oracle.com/en/learn/documentation/' "workspace version notes use official APEX documentation landing page" +require_contains "$APEX_DIR/workspace/version-notes.md" 'newest official Oracle APEX documentation' "workspace version notes prefer newest docs when target version is unknown" +require_contains "$APEX_DIR/workspace/security-review.md" '^# APEX Workspace Security Review$' "workspace has security review checklist" +reject_tree_contains "$workspace_scope" '^## APEX Session Analytics$' "workspace scope does not own monitoring content" +reject_tree_contains "$workspace_scope" '^## Application Table Audit Columns$' "workspace scope does not own security audit-column content" + +print_section "Security checks" +security_scope="$APEX_DIR/security" +require_tree_contains "$security_scope" 'Safety Messages|Safety stop|Sensitive data warning' "security scope has user-facing safety messages" +require_tree_contains "$security_scope" 'Security Guardrails|Least Privilege|Role Boundaries' "security scope has guardrails" +require_tree_contains "$security_scope" 'Application Table Audit Columns|APEX Application Table Audit Columns' "security scope has APEX audit-column trigger pattern" +require_tree_contains "$security_scope" 'SYS_CONTEXT\('\''APEX\$SESSION'\'', '\''APP_USER'\''\)' "security scope audit trigger uses APEX user context" +require_tree_contains "$security_scope" 'SYS_CONTEXT\('\''USERENV'\'', '\''SESSION_USER'\''\)' "security scope audit trigger has database-user fallback" +require_tree_contains "$security_scope" 'not a replacement for tamper-resistant database auditing' "security scope distinguishes app audit metadata from DB auditing" +require_tree_contains "$security_scope" 'passwords, tokens, large payloads, BLOBs, CLOBs, or sensitive free text' "security scope blocks unsafe audit payloads" +require_tree_contains "$security_scope" 'hot tables, bulk-load paths, or ETL-heavy workloads' "security scope calls out trigger cost" +require_tree_contains "$security_scope" 'db/security/auditing.md' "security scope marks DB auditing skill usage" +require_contains "$APEX_DIR/security/security-review.md" '^# APEX Security Review$' "security has security review checklist" + +print_section "Monitoring checks" +monitoring_scope="$APEX_DIR/monitoring" +require_tree_contains "$monitoring_scope" 'APEX_WORKSPACE_ACTIVITY_LOG' "monitoring scope covers APEX workspace activity log" +require_tree_contains "$monitoring_scope" '^## Usage And Load Trends$' "monitoring scope has usage and load trends" +require_tree_contains "$monitoring_scope" 'Error Handling And Logging' "monitoring scope has error handling and logging" +require_tree_contains "$monitoring_scope" 'APEX_DEBUG_MESSAGES' "monitoring scope covers APEX debug messages" +require_tree_contains "$monitoring_scope" 'APEX_ERROR_LOG' "monitoring scope covers APEX error log" +require_tree_contains "$monitoring_scope" 'DEBUG_PAGE_VIEW_ID' "monitoring scope covers debug page-view correlation" +require_tree_contains "$monitoring_scope" 'Session Replay output' "monitoring scope treats session replay as sensitive" +require_tree_contains "$monitoring_scope" 'Diagnostics Pack' "monitoring scope marks Diagnostics Pack constraints" +require_tree_contains "$monitoring_scope" 'Session Drilldown' "monitoring scope has session drilldown" +require_tree_contains "$monitoring_scope" 'End-To-End User Journey Replay' "monitoring scope has end-to-end user journey replay" +require_tree_contains "$monitoring_scope" 'Session Replay' "monitoring scope covers APEX Session Replay" +require_tree_contains "$monitoring_scope" 'APEX_ACTIVITY_LOG' "monitoring scope covers APEX activity log" +require_tree_contains "$monitoring_scope" 'Background Job Monitoring' "monitoring scope has background job monitoring" +require_tree_contains "$monitoring_scope" 'APEX_APPL_JOB_LOG' "monitoring scope covers APEX application job log" +require_tree_contains "$monitoring_scope" 'DBA_SCHEDULER_JOB_RUN_DETAILS|dba_scheduler_job_run_details' "monitoring scope maps to scheduler run details" +require_tree_contains "$monitoring_scope" 'Page Performance Profiler' "monitoring scope has page performance profiler" +require_tree_contains "$monitoring_scope" 'DBA_HIST_SQLSTAT' "monitoring scope covers DBA_HIST_SQLSTAT correlation" +require_tree_contains "$monitoring_scope" 'APEX_WORKSPACE_PAGE_VIEW_DETAIL' "monitoring scope checks page-view detail availability" +require_tree_contains "$monitoring_scope" 'Interactive Report And Grid Tuning' "monitoring scope has IR/IG tuning" +require_tree_contains "$monitoring_scope" 'APEX_APPLICATION_PAGE_IR' "monitoring scope checks IR metadata availability" +require_tree_contains "$monitoring_scope" 'APEX_APPL_PAGE_IGS' "monitoring scope checks IG metadata availability" +require_tree_contains "$monitoring_scope" 'REST Data Source Health Check' "monitoring scope has REST Data Source health check" +require_tree_contains "$monitoring_scope" 'APEX_APPL_WEB_SRC_MODULES' "monitoring scope checks REST/Web Source metadata" +require_tree_contains "$monitoring_scope" 'APEX_WEBSERVICE_LOG' "monitoring scope checks APEX webservice log" +require_tree_contains "$monitoring_scope" 'DBA_HIST_ACTIVE_SESS_HISTORY|dba_hist_active_sess_history' "monitoring scope covers historical ASH correlation" +require_tree_contains "$monitoring_scope" 'V\$SESSION|V\$SQL|V\$ACTIVE_SESSION_HISTORY|V\$SESSTAT|v\$session|v\$sql|v\$active_session_history|v\$sesstat' "monitoring scope covers live DB fallback views" +require_tree_contains "$monitoring_scope" 'AWR Wait Events' "monitoring scope has AWR wait-event cross-check" +require_tree_contains "$monitoring_scope" 'db/security/auditing.md' "monitoring scope marks DB auditing skill usage" +require_tree_contains "$monitoring_scope" 'db/monitoring/alert-log-analysis.md' "monitoring scope marks alert log and trace DB skill usage" +require_tree_contains "$monitoring_scope" 'db/features/dbms-scheduler.md' "monitoring scope marks DBMS_SCHEDULER DB skill usage" +require_tree_contains "$monitoring_scope" 'db/monitoring/top-sql-queries.md' "monitoring scope marks top SQL DB skill usage" +require_tree_contains "$monitoring_scope" 'db/sql-dev/sql-tuning.md' "monitoring scope marks SQL tuning DB skill usage" +require_tree_contains "$monitoring_scope" 'db/performance/index-strategy.md' "monitoring scope marks index strategy DB skill usage" +require_tree_contains "$monitoring_scope" 'db/ords/ords-monitoring.md' "monitoring scope marks ORDS monitoring DB skill usage" +require_tree_contains "$monitoring_scope" 'db/performance/wait-events.md' "monitoring scope marks wait-event DB skill usage" +require_contains "$APEX_DIR/monitoring/security-review.md" '^# APEX Monitoring Security Review$' "monitoring has security review checklist" + +require_contains "$APEX_DIR/monitoring/mcp-availability.md" '^# APEX MCP Availability Guard$' "monitoring has MCP availability guard" +require_contains "$APEX_DIR/monitoring/mcp-availability.md" 'APEX MCP availability check failed' "monitoring has MCP failure message" +require_contains "$APEX_DIR/monitoring/mcp-availability.md" 'Do not infer database state from stale context' "monitoring blocks stale-state continuation after MCP failure" +require_contains "$APEX_DIR/monitoring/mcp-availability.md" 'inventory each planned artifact individually' "MCP recovery inventories provisioning artifacts" +require_contains "$APEX_DIR/monitoring/mcp-availability.md" 'Do you want me to roll back the listed artifacts' "MCP recovery asks before rollback cleanup" + +print_section "Deployment checks" +deployment_scope="$APEX_DIR/deployment" +require_tree_contains "$deployment_scope" 'Deployment Pre-Check' "deployment scope has deployment pre-check" +require_tree_contains "$deployment_scope" 'APEX_APPLICATION_INSTALL' "deployment scope covers APEX_APPLICATION_INSTALL" +require_tree_contains "$deployment_scope" 'APEX_APPLICATIONS' "deployment scope checks APEX applications metadata" +require_tree_contains "$deployment_scope" 'APEX_APPLICATION_BUILD_OPTIONS' "deployment scope checks build options metadata" +require_tree_contains "$deployment_scope" 'APEX_APPLICATION_SUBSTITUTIONS' "deployment scope checks substitution metadata" +require_tree_contains "$deployment_scope" 'APEX_APPL_WEB_CREDENTIALS' "deployment scope checks web credential references" +require_tree_contains "$deployment_scope" 'APEX exports can contain sensitive metadata' "deployment scope warns about sensitive exports" +require_tree_contains "$deployment_scope" 'DB skill in use: `db/sqlcl/sqlcl-basics.md`' "deployment scope marks SQLcl DB skill usage" +require_tree_contains "$deployment_scope" 'DB skill in use: `db/devops/schema-migrations.md`' "deployment scope marks schema migration DB skill usage" +require_tree_contains "$deployment_scope" 'DB skill in use: `db/security/privilege-management.md`' "deployment scope marks privilege DB skill usage" +require_tree_contains "$deployment_scope" 'destructive or high-risk|Destructive Action Rules|Safety stop' "deployment scope has destructive action rules" +require_tree_contains "$deployment_scope" 'no real passwords, tokens, OAuth secrets, SMTP credentials, wallet passwords' "deployment scope blocks real secrets" +require_contains "$APEX_DIR/deployment/pre-check.md" 'https://apex.oracle.com/en/learn/documentation/' "deployment pre-check uses official APEX documentation landing page" +require_contains "$APEX_DIR/deployment/pre-check.md" 'newest official Oracle APEX documentation' "deployment pre-check prefers newest docs when target version is unknown" +require_contains "$APEX_DIR/deployment/security-review.md" '^# APEX Deployment Security Review$' "deployment has security review checklist" + +require_contains "$APEX_DIR/deployment/pre-check.md" 'Oracle Database 19.3 or higher' "deployment pre-check includes APEX 24.2 database support note" +require_contains "$APEX_DIR/deployment/patching.md" '^# APEX Patch Set Bundle Workflow$' "deployment has patch set bundle workflow" +require_contains "$APEX_DIR/deployment/patching.md" 'APEX_PATCHES' "deployment patching checks APEX_PATCHES" +require_contains "$APEX_DIR/deployment/patching.md" '37366599' "deployment patching includes dated APEX 24.2 patch reference" +require_contains "$APEX_DIR/deployment/patching.md" 'PATCH_VERSION' "deployment patching includes patch version" +require_contains "$APEX_DIR/deployment/patching.md" '24.2.16' "deployment patching includes target patched APEX version" + +print_section "Global safety checks" +reject_tree_contains "$APEX_DIR" 'DB skill handoff:' "APEX tree does not use ambiguous DB handoff label" +reject_tree_contains "$APEX_DIR" 'UPDATE[[:space:]]+APEX_|INSERT[[:space:]]+INTO[[:space:]]+APEX_|DELETE[[:space:]]+FROM[[:space:]]+APEX_' "APEX tree does not recommend direct APEX repository DML" +reject_tree_contains "$APEX_DIR" 'GRANT[[:space:]]+(DBA|SYSDBA|SELECT ANY TABLE|EXECUTE ANY PROCEDURE|CREATE ANY TABLE|GRANT ANY ROLE|GRANT ANY PRIVILEGE)' "APEX tree does not contain broad-grant SQL examples" +reject_tree_contains "$APEX_DIR" 'docs\.oracle\.com/en/database/oracle/apex/[0-9]' "APEX tree does not hard-code versioned Oracle APEX docs URLs" +reject_tree_contains "$APEX_DIR" 'password123|Password123|Welcome1|changeme|ChangeMe|secret123|Bearer[[:space:]]+[A-Za-z0-9._-]+|client_secret[[:space:]]*[:=][[:space:]]*['\''"]?[A-Za-z0-9]' "APEX tree does not contain hard-coded secret-like example values" + +reject_contains "$APEX_DIR/monitoring/mcp-availability.md" 'sql -mcp|conn -save' "APEX MCP availability guard does not include database-client setup commands" + +print_section "Cross-file quality gates" +all_markdown_files=() +while IFS= read -r markdown_file; do + all_markdown_files+=("$markdown_file") +done < <(find "$APEX_DIR" -type f -name '*.md' | sort) + +for markdown_file in "${all_markdown_files[@]}"; do + rel="${markdown_file#$APEX_DIR/}" + + if grep -Eq 'db/[[:alnum:]_-]+/' "$markdown_file"; then + require_contains "$markdown_file" 'DB skill in use:' "$rel marks DB skill usage when referencing db/" + fi + + if grep -Eq 'AWR|ASH|DBA_HIST' "$markdown_file"; then + require_contains "$markdown_file" 'Diagnostics Pack' "$rel marks Diagnostics Pack for AWR/ASH/historical views" + fi + + if grep -Eq 'APEX_[A-Z0-9_]+' "$markdown_file"; then + require_contains "$markdown_file" 'ALL_TAB_COLUMNS|ALL_ARGUMENTS|APEX_DICTIONARY|APEX_RELEASE|column availability|view availability|available columns|package signature|version-specific|Version check' "$rel has version/availability guard for APEX objects" + fi +done + +print_section "DB skill reference checks" +begin_check "DB skills root exists or DB_SKILLS_ROOT is configured" +if [[ -d "$DB_SKILLS_ROOT/db" ]]; then + pass "DB skills root available: $DB_SKILLS_ROOT" +else + fail "DB skills root missing: $DB_SKILLS_ROOT" +fi + +db_skill_refs=() +while IFS= read -r db_skill_ref; do + db_skill_refs+=("$db_skill_ref") +done < <(grep -RhoE 'db/[A-Za-z0-9_*/.-]+\.md' "$APEX_DIR" --include='*.md' | sort -u) + +for db_skill_ref in "${db_skill_refs[@]}"; do + if [[ "$db_skill_ref" == *'*'* ]]; then + begin_check "$db_skill_ref is an intentional wildcard DB skill reference" + pass "$db_skill_ref is an intentional wildcard DB skill reference" + else + begin_check "$db_skill_ref exists in DB skills" + if [[ -f "$DB_SKILLS_ROOT/$db_skill_ref" ]]; then + pass "$db_skill_ref exists in DB skills" + else + fail "$db_skill_ref missing in DB skills" + fi + fi +done + +print_section "Routing prompt examples" +prompt_count=0 + +add_prompt_example() { + local topic="$1" + local expected_skill="$2" + local expected_message="$3" + local prompt="$4" + + prompt_count=$((prompt_count + 1)) + printf ' scenario %02d: %s\n' "$prompt_count" "$topic" + printf ' given: %s\n' "$prompt" + printf ' expect: route to %s\n' "$expected_skill" + printf ' expect: %s\n' "$expected_message" + printf ' ok: routing example is documented\n' +} + +add_prompt_example "workspace-list" "apex/workspace/lifecycle.md" "No DB skill in use message unless generic database diagnosis is requested." "List APEX workspaces and show basic workspace metadata." +add_prompt_example "workspace-provisioning" "apex/workspace/lifecycle.md" "Use least privilege and supported APEX APIs." "Create an APEX workspace with a parsing schema and an initial workspace admin." +add_prompt_example "workspace-resource-governance" "apex/workspace/resource-governance.md plus db/performance/ash-analysis.md and db/monitoring/space-management.md" "DB skill in use messages for CPU/IO/storage analysis; keep APEX focused on workspace quotas and mappings." "Analyze APEX workspace limits, APEX_WORKSPACE_QUOTAS, sessions, storage, CPU/IO pressure, and recommend quota adjustments." +add_prompt_example "destructive-cleanup" "apex/workspace/removal.md" "Safety stop: list affected objects and require a fresh exact English own-will confirmation before delete steps." "Drop this APEX workspace and all users created for it." +add_prompt_example "broad-privileges" "apex/security/guardrails.md plus db/security/privilege-management.md" "DB skill in use message plus broad-privilege safety stop." "Grant DBA to the APEX parsing schema so the app can access everything." +add_prompt_example "internal-apex-repository" "apex/security/safety-messages.md" "Safety stop: direct writes to internal APEX repository tables are not supported." "Update the internal APEX repository table directly to rename a workspace." +add_prompt_example "activity-log-triage" "apex/monitoring/activity-log.md" "Sensitive data warning for logs; DB skill in use message if AWR/ASH/wait events are used." "Find slow APEX pages and correlate the spike with database wait events." +add_prompt_example "page-performance-profiler" "apex/monitoring/page-performance.md plus db/monitoring/top-sql-queries.md" "DB skill in use message for DBA_HIST_SQLSTAT; keep APEX focused on page and region context." "Profile the slowest APEX pages and regions, export page performance details, and correlate with DBA_HIST_SQLSTAT." +add_prompt_example "background-job-monitoring" "apex/monitoring/background-jobs.md plus db/features/dbms-scheduler.md" "DB skill in use message for DBMS_SCHEDULER; review APEX job log before changing scheduler state." "Diagnose failed APEX background jobs and map them to DBA_SCHEDULER_JOB_RUN_DETAILS." +add_prompt_example "interactive-report-grid-tuning" "apex/monitoring/ir-ig-tuning.md plus db/sql-dev/sql-tuning.md and db/performance/index-strategy.md" "DB skill in use messages for generic SQL tuning/index/AWR analysis; keep APEX focused on IR/IG behavior." "Tune slow Interactive Reports and Interactive Grids, including filtering, pagination, downloads, indexes, and SQL IDs in AWR." +add_prompt_example "rest-data-source-health-check" "apex/monitoring/rest-data-sources.md plus db/ords/ords-monitoring.md and db/performance/ash-analysis.md" "DB skill in use messages for ORDS/ASH/network waits; keep APEX focused on REST Data Source metadata and logs." 'Health check APEX REST Data Sources, latency, HTTP error codes, and database-side network waits via ASH and V$SESSTAT.' +add_prompt_example "error-handling-logging" "apex/monitoring/error-handling.md plus db/security/auditing.md, db/performance/awr-reports.md, db/performance/ash-analysis.md, and db/monitoring/alert-log-analysis.md" "DB skill in use messages for audit, AWR/ASH, alert log, and trace analysis; keep APEX focused on APEX debug/error context." "Collect, categorize, and prioritize APEX errors from APEX_DEBUG_MESSAGES and APEX_ERROR_LOG, correlate with AWR trace/audit evidence, and suggest quick fixes." +add_prompt_example "end-to-end-user-journey-replay" "apex/monitoring/user-journey-replay.md plus db/performance/ash-analysis.md, db/performance/awr-reports.md, and db/performance/wait-events.md" "DB skill in use messages for ASH/AWR/wait-event analysis; keep APEX focused on Session Replay, activity log path, and journey reproduction." "Replay an end-to-end APEX user journey with Session Replay and APEX_ACTIVITY_LOG, then correlate the critical path with ASH/AWR for systemic bottlenecks." +add_prompt_example "apex-deployment-promotion" "apex/deployment/import-promotion.md plus db/sqlcl/sqlcl-cicd.md, db/devops/schema-migrations.md, and db/security/privilege-management.md as needed" "DB skill in use messages for generic SQLcl, schema migration, and privilege work; keep APEX focused on export/import, APEX_APPLICATION_INSTALL, and APEX metadata safety." "Review and promote an APEX application export to production using APEX_APPLICATION_INSTALL, build options, substitutions, credential references, and safe import validation." +add_prompt_example "audit-columns" "apex/security/audit-columns.md" "Audit note: trigger records application metadata only; use db/security/auditing.md for database auditing." "Add created_by and updated_by audit columns for an APEX application table." +add_prompt_example "apex-mcp-transport-closed" "apex/monitoring/mcp-availability.md" "APEX MCP availability check failed; pause the APEX workflow and re-read state after recovery." "The MCP transport is closed while creating an APEX workspace user. What should happen next?" +add_prompt_example "interrupted-provisioning-rollback" "apex/monitoring/mcp-availability.md plus apex/workspace/lifecycle.md and apex/workspace/removal.md if cleanup is requested" "Inventory each planned artifact individually, then ask whether to roll back only the listed artifacts before retrying." "I aborted while creating an APEX workspace, parsing schema, EMP table, and demo app. What should happen before we continue?" +add_prompt_example "apex-patch-status" "apex/deployment/patching.md" "Check APEX_RELEASE and APEX_PATCHES, then verify latest patch details from Oracle before recommending a patch." "Check whether my APEX 24.2 environment has the latest Patch Set Bundle installed." + +begin_check "routing prompt examples available" +if [[ "$prompt_count" -ge 15 ]]; then + pass "routing prompt examples available ($prompt_count)" +else + fail "routing prompt examples should cover core APEX workflows" +fi + +print_section "Result" +if [[ "$failures" -eq 0 ]]; then + printf ' 0 failing\n' + printf ' all APEX skill checks passed\n' +else + printf ' %d failing\n' "$failures" + printf ' APEX skill checks failed\n' + exit 1 +fi diff --git a/apex/workspace/lifecycle.md b/apex/workspace/lifecycle.md new file mode 100644 index 0000000..6c9f074 --- /dev/null +++ b/apex/workspace/lifecycle.md @@ -0,0 +1,151 @@ +# APEX Workspace Lifecycle + +Use this topic for workspace inventory, pre-flight checks, create workspace, and verification. + +## Pre-Flight Questions + +- APEX version, because package signatures differ across APEX releases. +- Target workspace name and whether a deterministic workspace ID is required. +- Primary parsing schema and any additional schemas. +- Always ask whether the workspace should use a new database user/schema or an existing database user/schema before creating the workspace. Do not infer this from the requested workspace name. +- If a new database user/schema is requested, route generic user creation and grants through the relevant DB skills before calling `APEX_INSTANCE_ADMIN.ADD_WORKSPACE`. +- If an existing database user/schema is requested, verify it with `apex/workspace/schema-mapping.md` before workspace creation. +- Whether the first user should be an APEX workspace administrator, developer, or end user. +- Authentication model for the development environment. +- Confirm parsing-schema candidates with `apex/workspace/schema-mapping.md`; do not suggest ORDS schemas, `PDB_ADMIN`, Oracle-maintained accounts, APEX platform schemas, or DBA/runtime service accounts as parsing schemas. +- If the user wants to reuse an existing parsing schema, verify required privileges first. If privileges are missing or excessive, ask whether the user wants the DB privilege changes handled through `db/security/privilege-management.md`; continue only when the privileges are correct or the user approves adjustment. +- Whether this is Oracle Cloud or Autonomous Database, where some instance administration options may be restricted. + +## List Workspaces + +Use `APEX_WORKSPACES` for workspace inventory. + +```sql +SELECT workspace_id, + workspace, + workspace_display_name, + path_prefix, + schemas, + applications, + apex_developers, + apex_workspace_administrators, + allow_app_building_yn, + allow_sql_workshop_yn, + allow_restful_services_yn, + created_on +FROM apex_workspaces +ORDER BY workspace; +``` + +If you need a version-safe query, inspect installed columns first: + +```sql +SELECT column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name = 'APEX_WORKSPACES' +ORDER BY column_id; +``` + +## Create A Workspace + +Run instance-level workspace APIs as `SYS`, `SYSTEM`, or a user granted `APEX_ADMINISTRATOR_ROLE`. Do not grant broad DBA privileges just to automate workspace creation. + +```sql +BEGIN + APEX_INSTANCE_ADMIN.ADD_WORKSPACE( + p_workspace_id => :workspace_id, + p_workspace => :workspace_name, + p_primary_schema => :primary_schema); +END; +/ +``` + +Check `APEX_INSTANCE_ADMIN.ADD_WORKSPACE` arguments with `ALL_ARGUMENTS` before using version-specific parameters. + +## Verify + +After creation, verify workspace, schema mappings, APEX users, and expected privileges through supported APEX views. Do not query or update internal APEX repository tables directly. + +## Provisioning Recovery After Interruption + +If a workspace provisioning workflow is interrupted, aborted, or loses MCP/database connectivity after any create step may have run, do not continue or retry blindly. Reconnect first, then inventory each planned artifact individually before deciding what to do next. + +Check only the objects that were part of the current provisioning plan: + +```sql +SELECT workspace_id, + workspace, + schemas, + applications, + apex_developers, + apex_workspace_administrators +FROM apex_workspaces +WHERE workspace = UPPER(TRIM(:workspace_name)); +``` + +```sql +SELECT workspace_name, + schema +FROM apex_workspace_schemas +WHERE workspace_name = UPPER(TRIM(:workspace_name)) +ORDER BY schema; +``` + +```sql +SELECT workspace_name, + user_name, + email, + is_admin, + is_application_developer, + account_locked +FROM apex_workspace_apex_users +WHERE workspace_name = UPPER(TRIM(:workspace_name)) +ORDER BY user_name; +``` + +```sql +SELECT username, + account_status, + oracle_maintained +FROM dba_users +WHERE username IN ( + UPPER(TRIM(:primary_schema)), + UPPER(TRIM(:database_login_user)) +) +ORDER BY username; +``` + +```sql +SELECT owner, + object_name, + object_type, + status +FROM all_objects +WHERE owner = UPPER(TRIM(:primary_schema)) + AND object_name IN ('EMP') +ORDER BY object_type, object_name; +``` + +```sql +SELECT workspace, + application_id, + application_name, + alias +FROM apex_applications +WHERE workspace = UPPER(TRIM(:workspace_name)) +ORDER BY application_id; +``` + +Report the recovered inventory in concrete terms: created, missing, or unknown for each planned workspace, schema mapping, APEX user, database user, application table, and APEX application. + +Then ask before cleanup: + +```text +I found the following artifacts from the interrupted APEX provisioning workflow: . Do you want me to roll back the listed artifacts by removing only these objects? +``` + +If the user wants cleanup, route the destructive part through `apex/workspace/removal.md` and require its exact English confirmation for the current cleanup scope. If the user wants to continue instead, proceed only from the freshly verified inventory and skip create steps for objects that already exist. + +DB skill in use: `db/security/privilege-management.md` for generic schema/user privilege design. The APEX workspace skill is being used for workspace and parsing-schema context. diff --git a/apex/workspace/removal.md b/apex/workspace/removal.md new file mode 100644 index 0000000..34c8c56 --- /dev/null +++ b/apex/workspace/removal.md @@ -0,0 +1,93 @@ +# APEX Workspace Removal + +Use this topic for guarded test-workspace removal and cleanup. Treat removal as destructive. + +Version check: use `ALL_TAB_COLUMNS` and `ALL_ARGUMENTS` before assuming workspace inventory columns or `APEX_INSTANCE_ADMIN.REMOVE_WORKSPACE` parameters. + +## Safety Rules + +Safety stop: list affected workspaces, schemas, APEX users, database users, and tablespaces, then require explicit English confirmation before generating or running delete steps. + +Do not use stale context to infer the target. Require the workspace name and a fresh exact English confirmation for the current request. + +Protected accounts must never be deleted: Oracle-maintained users, APEX platform users, ORDS users, runtime accounts, DBA/admin accounts, and shared service accounts. + +## Confirmation Contract + +Before removing a workspace or any workspace-related database user, show the affected-object inventory and require the user to reply with the exact English confirmation phrase in the current conversation. Do not accept `yes`, `y`, screenshots, previous confirmations, branch names, or implied approval. + +For workspace metadata removal only, use this prompt: + +```text +To remove workspace , reply with exactly: YES, I confirm that I want to delete this workspace and that this is my own will. This will remove the listed APEX workspace metadata. Database users and tablespaces will not be dropped by this APEX workflow. +``` + +For workspace removal with related database users/components, use this prompt: + +```text +To remove workspace and the listed related database users/components, reply with exactly: YES, I confirm that I want to delete this workspace and its listed related database users/components and that this is my own will. +``` + +## Affected Object Inventory + +```sql +SELECT workspace_id, + workspace, + workspace_display_name, + schemas, + applications, + apex_developers, + apex_workspace_administrators +FROM apex_workspaces +WHERE workspace = UPPER(TRIM(:workspace_name)); +``` + +```sql +SELECT workspace_name, + schema +FROM apex_workspace_schemas +WHERE workspace_name = UPPER(TRIM(:workspace_name)) +ORDER BY schema; +``` + +```sql +SELECT workspace_name, + user_name, + is_admin, + is_application_developer +FROM apex_workspace_apex_users +WHERE workspace_name = UPPER(TRIM(:workspace_name)) +ORDER BY user_name; +``` + +## Removal Guardrail + +Use `APEX_INSTANCE_ADMIN.REMOVE_WORKSPACE` only after the exact English confirmation for the current removal scope. + +Default to workspace metadata removal only. Keep `p_drop_users => 'N'` and `p_drop_tablespaces => 'N'` unless the user explicitly asks to delete the workspace and the listed related database users/components. + +```sql +BEGIN + APEX_INSTANCE_ADMIN.REMOVE_WORKSPACE( + p_workspace => :workspace_name, + p_drop_users => 'N', + p_drop_tablespaces => 'N'); +END; +/ +``` + +If the user explicitly asks to delete the workspace and the listed related database users/components, and only after the exact English confirmation phrase for that broader scope, `p_drop_users => 'Y'` is allowed. + +```sql +BEGIN + APEX_INSTANCE_ADMIN.REMOVE_WORKSPACE( + p_workspace => :workspace_name, + p_drop_users => 'Y', + p_drop_tablespaces => 'N'); +END; +/ +``` + +Keep `p_drop_tablespaces => 'N'` unless the user explicitly lists tablespace deletion in the requested scope and confirms that scope with the same English own-will confirmation pattern. + +DB skill in use: `db/agent/destructive-op-guards.md` for generic destructive-operation safety patterns. The APEX workspace skill is being used for APEX workspace object inventory and supported removal API context. diff --git a/apex/workspace/resource-governance.md b/apex/workspace/resource-governance.md new file mode 100644 index 0000000..eeaae01 --- /dev/null +++ b/apex/workspace/resource-governance.md @@ -0,0 +1,50 @@ +# APEX Workspace Resource Governance + +Use this workflow when reviewing workspace limits, storage pressure, request ceilings, active session counts, or whether a workspace quota should be adjusted. Keep this topic focused on APEX workspace limits and governance context. + +DB skill in use: `db/performance/ash-analysis.md`, `db/performance/awr-reports.md`, `db/performance/wait-events.md`, and `db/monitoring/space-management.md` for generic CPU, I/O, wait-event, AWR/ASH, and tablespace analysis. The APEX workspace skill is being used for workspace quota, schema mapping, file-storage, and Resource Manager context. + +## Quota Source Pre-Check + +`APEX_WORKSPACE_QUOTAS` may not exist in every APEX release or managed environment. Check available views and columns first. + +Version check: use `APEX_DICTIONARY` and `ALL_TAB_COLUMNS` before assuming workspace quota, schema, or Resource Manager metadata columns. + +```sql +SELECT owner, + object_name, + object_type +FROM all_objects +WHERE object_name IN ( + 'APEX_WORKSPACE_QUOTAS', + 'APEX_WORKSPACES', + 'APEX_WORKSPACE_SCHEMAS') +ORDER BY object_name, + owner; +``` + +```sql +SELECT table_name, + column_id, + column_name, + data_type +FROM all_tab_columns +WHERE table_name IN ( + 'APEX_WORKSPACE_QUOTAS', + 'APEX_WORKSPACES', + 'APEX_WORKSPACE_SCHEMAS') +ORDER BY table_name, + column_id; +``` + +## APEX Governance Checks + +Use `APEX_WORKSPACES` and supported quota views to review file storage, session/request ceilings, application counts, and Resource Manager mapping. Columns such as `FILE_STORAGE_MAX` and `RM_CONSUMER_GROUP` are version-dependent; inspect columns first. + +Do not treat database CPU/I/O pressure as a quota problem without mapped-schema and time-window evidence. Use APEX workspace/application/page context to choose a time window, then use the DB skills for generic resource analysis. + +## Recommendations + +- Adjust APEX workspace quotas only after identifying whether pressure comes from APEX file storage, parsing-schema segment growth, sessions, requests, or database CPU/I/O. +- Do not increase quotas to hide application design issues such as large file uploads, excessive debug logging, or inefficient report downloads. +- Mark AWR/ASH/Diagnostics Pack constraints before using historical DB performance views. diff --git a/apex/workspace/schema-mapping.md b/apex/workspace/schema-mapping.md new file mode 100644 index 0000000..40b6524 --- /dev/null +++ b/apex/workspace/schema-mapping.md @@ -0,0 +1,131 @@ +# APEX Workspace Schema Mapping + +Use this topic for parsing schema mappings, additional schemas, workspace export/import preparation, and deployment handoff. + +## Parsing Schema Guardrails + +Only suggest application-owned schemas as APEX parsing schemas. Do not suggest platform, runtime, DBA, or service accounts, even if they technically exist and have `CREATE SESSION`. + +Never suggest these accounts or account families as primary or additional parsing schemas: + +- `PDB_ADMIN` +- `ADMIN` +- `SYS`, `SYSTEM`, `DBSNMP`, `OUTLN`, `GSMADMIN_INTERNAL` +- Oracle-maintained accounts where `ORACLE_MAINTAINED = 'Y'` +- APEX platform schemas such as `APEX_%`, `FLOWS_%`, `APEX_PUBLIC_USER`, `APEX_LISTENER`, `APEX_REST_PUBLIC_USER` +- ORDS schemas such as `ORDS_METADATA`, `ORDS_PUBLIC_USER`, and any `ORDS_%` service/runtime schema +- Runtime or shared service accounts used by ORDS, connection pools, monitoring, CI/CD, or automation +- Personal developer accounts in production + +Prefer schemas created specifically for the application or workspace, for example `SALES_APP`, `SALES_REF`, or `HR_PORTAL_APP`. + +## Find Candidate Schemas + +Use this as a conservative starting point when the user asks which schemas can be mapped. Review the result with the user before creating or changing mappings. + +```sql +SELECT username, + account_status, + authentication_type, + default_tablespace, + created +FROM dba_users +WHERE oracle_maintained = 'N' + AND account_status NOT LIKE 'LOCKED%' + AND username NOT IN ( + 'ADMIN', + 'PDB_ADMIN', + 'APEX_PUBLIC_USER', + 'APEX_LISTENER', + 'APEX_REST_PUBLIC_USER', + 'ORDS_METADATA', + 'ORDS_PUBLIC_USER' + ) + AND username NOT LIKE 'APEX\_%' ESCAPE '\\' + AND username NOT LIKE 'FLOWS\_%' ESCAPE '\\' + AND username NOT LIKE 'ORDS\_%' ESCAPE '\\' +ORDER BY username; +``` + +On environments where `DBA_USERS.ORACLE_MAINTAINED` is not visible, use `ALL_USERS` only as a fallback and apply the same name-based exclusions. When in doubt, ask whether the schema is application-owned before mapping it. + +## Existing Schema Privilege Check + +When the user wants to reuse an existing schema as a primary or additional parsing schema, check its account status, quotas, and current system privileges before mapping it. Do not assume an existing user is suitable just because it exists. + +```sql +SELECT username, + account_status, + authentication_type, + default_tablespace, + temporary_tablespace, + oracle_maintained +FROM dba_users +WHERE username = UPPER(:schema_name); +``` + +```sql +SELECT privilege +FROM dba_sys_privs +WHERE grantee = UPPER(:schema_name) +ORDER BY privilege; +``` + +```sql +SELECT tablespace_name, + bytes, + max_bytes +FROM dba_ts_quotas +WHERE username = UPPER(:schema_name) +ORDER BY tablespace_name; +``` + +Evaluate the result against the application need. Typical APEX application parsing schemas may need narrowly scoped object-creation privileges such as `CREATE TABLE`, `CREATE VIEW`, `CREATE SEQUENCE`, `CREATE PROCEDURE`, `CREATE TRIGGER`, `CREATE TYPE`, and quota on the application tablespace. If Oracle AI Database 26ai is detected and the APEX application needs MLE, add `CREATE MLE` and `EXECUTE DYNAMIC MLE` to the expected privilege profile. They should not receive broad administrative grants such as `DBA`, `SELECT ANY TABLE`, `EXECUTE ANY PROCEDURE`, `CREATE ANY TABLE`, `GRANT ANY ROLE`, or `GRANT ANY PRIVILEGE` for ordinary workspace creation. + +If required privileges are missing or existing privileges are too broad, stop before mapping the schema and ask: + +```text +The existing schema does not match the expected privilege profile for this APEX workspace. Do you want me to route the privilege adjustment through db/security/privilege-management.md before continuing? +``` + +If privileges are correct, continue with the workspace creation or schema mapping. Do not generate GRANT or REVOKE statements from this APEX skill; route generic database privilege changes to `db/security/privilege-management.md`. + +## Add Schema Mapping + +Add an existing schema to a workspace with supported APEX APIs. + +```sql +BEGIN + APEX_INSTANCE_ADMIN.ADD_SCHEMA( + p_workspace => :workspace_name, + p_schema => :schema_name); +END; +/ +``` + +Check package signatures first: + +```sql +SELECT argument_name +FROM all_arguments +WHERE package_name = 'APEX_INSTANCE_ADMIN' + AND object_name = 'ADD_SCHEMA' +ORDER BY sequence; +``` + +## Export And Import + +For application imports into a target workspace, use the deployment skill for `APEX_APPLICATION_INSTALL`, build options, substitution strings, credential references, and safe import validation. + +DB skill in use: `db/devops/schema-migrations.md` for generic schema migration governance. The APEX workspace skill is being used for workspace-to-schema mapping. + +DB skill in use: `db/security/privilege-management.md` for generic grants and database object privileges. The APEX workspace skill is being used only to decide which application-owned schemas may be mapped to a workspace. + +Use `apex/deployment/` for APEX application export/import and environment promotion details. + +## Guardrails + +- Parsing schemas are not personal interactive logins in production. +- Do not write directly to internal APEX repository tables. +- Keep workspace schema mapping separate from generic object privileges. +- Review APEX exports before sharing; they may contain URLs, authorization schemes, build options, static files, credential references, defaults, and business logic. diff --git a/apex/workspace/security-review.md b/apex/workspace/security-review.md new file mode 100644 index 0000000..dca559f --- /dev/null +++ b/apex/workspace/security-review.md @@ -0,0 +1,13 @@ +# APEX Workspace Security Review + +Use this checklist after substantial workspace provisioning, import/export, schema mapping, resource governance, or removal work. + +- Scope: the workflow stayed APEX-specific; generic privilege, auditing, security, SQL tuning, ASH/AWR, SQLcl, ORDS, or resource diagnosis was routed to the relevant `db/...` skill with a visible `DB skill in use:` message. +- Licensed diagnostics: AWR and ASH usage called out Diagnostics Pack requirements before historical database-performance views were used. +- Privileges: parsing schemas, workspace administrators, developers, database-login users, ORDS/APEX runtime accounts, and DBA/admin accounts are separate and least-privilege. +- Broad grants: no ordinary APEX provisioning grants `DBA`, `SELECT ANY TABLE`, `EXECUTE ANY PROCEDURE`, `CREATE ANY TABLE`, `GRANT ANY ROLE`, or `GRANT ANY PRIVILEGE`. +- Supported interfaces: workspace changes use supported APEX APIs and views, not direct writes to internal APEX repository tables. +- Version and cloud limits: APEX package signatures, view columns, Autonomous Database limits, and managed-service restrictions were checked before version-specific SQL or PL/SQL. +- Secrets and exports: workspace exports, scripts, logs, and examples do not expose real passwords, tokens, SMTP credentials, wallet passwords, web credentials, or secret-bearing URLs. +- Destructive actions: affected workspaces, schemas, APEX users, database users, and tablespaces are listed; protected accounts are blocked; explicit confirmation is required. +- Data exposure: logs, Team Development files, exports, and session context avoid unnecessary payload columns, BLOBs, CLOBs, request values, and sensitive metadata. diff --git a/apex/workspace/users-and-auth.md b/apex/workspace/users-and-auth.md new file mode 100644 index 0000000..01e5399 --- /dev/null +++ b/apex/workspace/users-and-auth.md @@ -0,0 +1,60 @@ +# APEX Workspace Users And Authentication + +Use this topic for initial workspace administrators, developers, end users, and `Database Username` builder-login environments. + +Use `APEX_WORKSPACE_APEX_USERS` when you need supported workspace-user metadata for administrators, developers, and end users. Check column availability first on older or managed APEX environments. + +## Temporary Password Policy + +If the user provides an explicit temporary password or approved secret-handling method, use that. + +If the user does not provide a password for a newly created APEX workspace user in a demo or test workflow, use the temporary fallback password `Welcome!123` and always set `p_change_password_on_first_use => 'Y'`. + +After creating a user with the fallback password, tell the user: + +```text +APEX user was created with the temporary password Welcome!123 and must change it on first login. +``` + +Do not use the fallback password silently. Do not use it for production or shared non-test environments unless the user explicitly approves it for that environment. + +## Create Initial Workspace Admin + +Set the workspace security group ID before creating workspace-scoped users outside an APEX session. + +```sql +DECLARE + l_workspace_id NUMBER; +BEGIN + l_workspace_id := APEX_UTIL.FIND_SECURITY_GROUP_ID(:workspace_name); + APEX_UTIL.SET_SECURITY_GROUP_ID(l_workspace_id); + + APEX_UTIL.CREATE_USER( + p_user_name => :apex_user_name, + p_email_address => :email_address, + p_web_password => COALESCE(:temporary_password, 'Welcome!123'), + p_developer_privs => 'ADMIN:CREATE:DATA_LOADER:EDIT:HELP:MONITOR:SQL', + p_change_password_on_first_use => 'Y'); + + COMMIT; +END; +/ +``` + +Do not include real production passwords in skills, examples, logs, scripts, or chat output. + +## Database-Username Builder Login + +If the APEX sign-in page says `Database Username`, a matching database user may be required in addition to the APEX workspace user. Keep the security contexts separate: + +- Workspace Admin +- Developer +- End User +- Parsing Schema +- Database Login User +- ORDS/APEX Runtime Accounts +- DBA/Admin Accounts + +DB skill in use: `db/admin/user-management.md` and `db/security/privilege-management.md` for generic database user creation and privilege management. The APEX workspace skill is being used for APEX login-model and workspace-user context. + +Do not grant `DBA`, `SELECT ANY TABLE`, `EXECUTE ANY PROCEDURE`, `CREATE ANY TABLE`, `GRANT ANY ROLE`, or `GRANT ANY PRIVILEGE` for ordinary APEX workspace users. diff --git a/apex/workspace/version-notes.md b/apex/workspace/version-notes.md new file mode 100644 index 0000000..0a27718 --- /dev/null +++ b/apex/workspace/version-notes.md @@ -0,0 +1,30 @@ +# APEX Workspace Version Notes + +APEX version is usually more important than Oracle Database version for these APIs. The same database release can host different supported APEX versions, and APEX package signatures can change independently of database release cadence. + +Before citing API signatures or version-specific behavior, check the current official Oracle APEX documentation landing page and then use the docs for the target installed version: + +```text +https://apex.oracle.com/en/learn/documentation/ +``` + +If the target version is unknown, use the newest official Oracle APEX documentation as the default reference and keep SQL version-tolerant. + +Use these checks before generating version-sensitive SQL: + +```sql +SELECT version_no +FROM apex_release; + +SELECT argument_name +FROM all_arguments +WHERE package_name = 'APEX_INSTANCE_ADMIN' + AND object_name = 'ADD_WORKSPACE' +ORDER BY sequence; +``` + +Use `ALL_TAB_COLUMNS`, `ALL_ARGUMENTS`, `APEX_DICTIONARY`, and supported APEX version views before relying on a column or package parameter. + +For Oracle Database 19c through 26ai, keep workspace provisioning scripts portable by detecting APEX package signatures and by avoiding database-version assumptions unless the task depends on database-specific features such as MLE, Resource Manager setup, or schema privilege syntax. + +DB skill in use: `db/architecture/oracle-cloud-oci.md` or the relevant `db/admin/*` skill only when the question moves into generic database or cloud administration. The APEX workspace skill is being used for APEX version and package signature context.