APEX 26.2 partial APEXlang imports

Import a changed page and its shared list of values without re-importing the rest of the application. APEXREST selects eligible .apx files automatically or accepts an explicit list, validates dependencies using retained application context and fresh selected server sources, and preserves unrelated remote changes.

Source version: this guide describes the 2.5.0 source bundle. Use its bundled runtime or plugin; a separately published package must be checked for feature compatibility. APEX 26.1 projects use full imports.

Choose an import mode

The CLI and the apexrest_ship MCP tool expose the same modes. The requirement to use direct SQLcl CLI describes how APEXREST connects to Oracle; it does not prevent using the feature through Codex or Claude Code's APEXREST MCP tools. SQLcl's own mcp execution mode and the ORDS transport are separate options and do not support partial import in this implementation.

Requirements

APEX 26.2 requires SQLcl and ORDS 26.3 or later. APEXREST's partial-import gate deliberately accepts the exact reviewed compiler/MMD tuple and 26.2 target stream. Target releases are checked; a future version is not automatically qualified.

Select the matching compiler through APEXREST_SQLCL. The managed installer still defaults to 26.1. Set toolchain.profile to 26.2 for authoring references and use the reviewed toolchains/toolchain-26.2.lock.json when establishing that toolchain; changing the reference profile alone does not install a compiler or upgrade source metadata. Existing project/toolchain changes require explicit refresh or re-establishment of the sync baseline. A new app generated by the selected 26.2 compiler records its profile and matching lock.

Quick start from an updated checkout

The following examples assume a configured application project with an environment named dev. Replace the absolute paths and example page/LOV filenames with your project's values. These commands use the checkout runtime described in this guide.

APEXREST_CLI="/absolute/path/to/apexrest/plugins/apexrest-apex/runtime/apexrest.mjs"
APEXREST_PROJECT="/absolute/path/to/application-project"

node "$APEXREST_CLI" sqlcl configure --mode cli --database-transport direct --json
node "$APEXREST_CLI" apex sync --project "$APEXREST_PROJECT" --env dev --action init --json

Initialize the baseline before editing. Initial sync refuses conflicting local sources; retain and reconcile them rather than overwriting them. An already initialized ready working copy can be reused.

After editing, ordinary authorized work needs one apply call: it compiles and plans before import. Use a separate plan preview only when review is useful:

node "$APEXREST_CLI" ship --project "$APEXREST_PROJECT" --env dev --mode plan --import-mode auto --user-request "Update the Home page and status LOV in the configured dev application" --json
node "$APEXREST_CLI" ship --project "$APEXREST_PROJECT" --env dev --mode apply --import-mode auto --user-request "Update the Home page and status LOV in the configured dev application" --json

For an explicit selection, list exact files. Shared components use a full APEXlang observation because native component export is not qualified on the tested server; the import still touches only these files:

node "$APEXREST_CLI" ship --project "$APEXREST_PROJECT" --env dev --mode plan --import-mode files --files pages/p00001-home.apx shared-components/lovs/status.apx --user-request "Import only the Home page and status LOV into the configured dev application" --json
node "$APEXREST_CLI" ship --project "$APEXREST_PROJECT" --env dev --mode apply --import-mode files --files pages/p00001-home.apx shared-components/lovs/status.apx --user-request "Import only the Home page and status LOV into the configured dev application" --json

Paths are relative to the configured application source directory. files requires a nonempty list; globs, path escapes, symlinks and duplicates are rejected. The MCP equivalents are importMode: "files" and files: ["pages/p00001-home.apx", "shared-components/lovs/status.apx"] on apexrest_ship.

ship --mode apply prepares a fresh plan and then binds its grant to that plan; it does not consume the earlier preview file. To execute a particular saved plan, use the granular deploy plan / deploy apply flow with its exact-plan authorization. Once a plan is bound for apply, its selection cannot widen.

What the planner checks

The planner compares the saved baseline, local edits and fresh export of the selected server components. Local changes identify the intended update. Unselected remote changes are preserved on the server and are not fetched into local context; unequal local/server edits to the same component block planning. Retained dependency context and the selected server sources form an effective application validated as a whole, so a selected page cannot depend on an unselected new local LOV missing from the server. Include required changed dependencies in the reviewed list.

Review importSelection.requestedMode, resolvedMode, files, supporting-component selections and reasons. The compact preview shows at most 50 selected paths; use the full saved plan for a longer list.

Fast native export mappings cover page files. Supported shared-component files also use selected imports, but Oracle 26.2 rejects native APEXlang LOV/list export selectors. Their plans therefore expose exportScope:full and shared-components-require-full-apexlang-observation: a full APEXlang read is filtered to the selected sources for conflicts, backups and readback. This is a performance limit, not a full import. Themes, templates, plug-ins, workspace components, static assets and authentication/authorization changes require a full import; explicit files mode refuses them. Deletions, initial application creation, production, database operations and unsupported transports can require a full plan or block the operation under existing safeguards. Known remote changes must be reconciled before an automatic full fallback. Explicit files mode never becomes full. Database scripts require a full application import and the local/remote safety policy; production deployment is forbidden.

Backup, verification and recovery

Version 4 plans bind the exact file list, source/configuration/toolchain hashes, target, fresh server export and validated effective tree. Existing saved plans keep their previous full-import semantics. The temporary deploy grant binds the whole plan digest.

Page-only plan/apply uses native apex export -expComponents in the selected scope and never exports the complete application. Shared-component selections use the explicitly recorded full APEXlang observation; their retained snapshots and import scope remain selected. Existing pages need a selected export; new pages have a live ID collision check and no export when absent. The pre-apply selected export is also the backup source, avoiding a separate backup round trip. Backups record scope, exact files, checksums and absent components. Full changes use full APEXlang snapshots. Ordinary operation creates no SQL application dumps; explicitly requested restore of an existing legacy SQL backup remains compatible.

Apply acquires managed-home schema ownership before the fresh drift comparison, freezes the effective tree and runs one SQLcl apex import -files command. Same-component changes after planning block; different-page edits do not. Independent homes/machines still require external serialization. There is no claim of a distributed atomic compare-and-import protocol.

After page imports, only selected APEXlang sources are exported and compared. Shared-component imports use a full APEXlang observation and compare only selected files; the observation scope is recorded separately. Qualified Oracle 26.2 default elision covers native select-list/region start-new-row, checksum page protection and bar-chart type; uniquely identified regions with explicit unique layout sequences and native chart axes/series may be reordered. Scalar strings, fenced code, nondefault security values and ambiguous identities stay strict. Unknown forms fail closed. Both hashes and rules are retained in readback-verification.json, alongside selected scope and an explicit indication that unselected server content was not checked.

The checkpoint retains local dependency context plus verified selected sources; unselected local work remains dirty. Concurrent local edits are retained and require reconciliation. A confirmed import with failed readback is a verification failure; an unconfirmed write is outcome_unknown. Recovery reads only the original scope before deciding whether the result is already applied or needs a fresh plan. It does not blindly retry or roll back Oracle.

Selected APEXlang backup restore creates a separate exact plan and uses the same scoped compiler/import/readback flow. A creation backup records absence, so it cannot pretend to undo creation by importing an empty file set; component deletion needs a separately reviewed operation. Before/effective/readback snapshots, backups and journals remain durable and private.

Use one ship --mode apply call for a routine authorized edit. It includes compiler validation and planning; a separate validate and plan preview add duplicate work. Preview remains available when review is useful or a remote dangerous operation requires exact-plan confirmation. A local no-op stops before Oracle calls and explicitly reports that server freshness was not checked. Identity and release discovery share a read-only session, identical read/deploy connections reuse the fresh identity observation, and import help is cached by compiler installation.

Other 26.2 support

• Validation reports advisory CodeScan findings and source-upgrade hints separately from compiler diagnostics. Scanner unavailability is explicit and does not convert compilation success into a scanner pass.
• The new corpus covers provider APIs, unspecified versus explicit reasoning effort, secure agent navigation, Interactive Reports, workflow/task changes, charts and Universal Theme, DDS, managed credentials and deployment metadata.
• Six original recipe fragments have real offline compiler evidence. They do not establish provider availability, database policies, running-workflow migration, application imports or browser behavior.
• Effective deployment JSON preserves source defaults, subscription mappings and checksum salts while the configured target controls application/workspace/schema identity. Native Oracle Working Copies and application locking remain distinct from APEXREST's local sync state; API examples do not automatically create copies or acquire locks.
• Security readiness requires actual database capabilities, verified identity propagation, OCI IAM and network permissions. Credential/policy provisioning remains operator-managed. Database-backed Web Credentials do not enforce the Valid for URLs restriction; use the parsing schema's network controls.

For bounded read-only diagnostics, call apexrest_metadata_read with kind: "apex-capabilities", the configured parsing schema and env. Results include actual releases, visible public APIs, application lock/Working Copy observations, and explicit operator-verification requirements. Metadata visibility does not prove API execution or security enforcement.

Major-version source upgrades require a reviewed import/re-export into a separate directory, followed by explicit checkpoint refresh. Never edit .apex/apexlang.json to pretend that old sources use the new compiler. Keep old source and backup snapshots; an export with -force can remove its destination alias directory.

Sources: APEX 26.2 release notes, file import rules, requirements, deployment metadata, source upgrade, managed credentials.

Complete Oracle authoring inventory

The official inventory coverage includes all 389 definition documents and the upstream layout/syntax catalog. Select version:26.2, search corpus:components and read the returned oracle:26.2:inventory/... ID through all pages. Every contextual property, enum and applicability condition is retained. Local 26.1 UX recipes remain separately version-bound. Full source coverage does not qualify database, provider, import or browser behavior.

View this page source