Skip to content

generate-scripts.md

Latest commit

 

History

History
201 lines (154 loc) · 7.22 KB

generate-scripts.md

File metadata and controls

201 lines (154 loc) · 7.22 KB
Raw

dbpm generate-scripts

Generate standalone Oracle install and upgrade scripts from committed Git state. The generated SQL can be executed by SQL*Plus or SQLcl without dbpm.

generate-scripts is intended for ordinary Core-dependent applications. Core itself is intentionally unsupported because Core uses a bootstrap lifecycle that differs from normal package deployments.

Syntax

dbpm generate-scripts [source] [--from REF] [--to REF]
                      [--version VERSION]
                      [--application-name NAME]
                      [--deployment-type major|minor|patch]
                      [--install-output PATH]
                      [--release-upgrade-output PATH]
                      [--upgrade-pointer-output PATH]
                      [--check]

EBNF diagram

flowchart LR
    command["command"] --> dbpm["dbpm"]
    dbpm --> generate["generate-scripts"]
    generate --> source["[ source ]"]
    source --> options["{ option }"]
    options --> end_node(("end"))

    options -. expands to .-> option["option"]
    option --> from_ref["--from REF"]
    option --> to_ref["--to REF"]
    option --> version["--version VERSION"]
    option --> app_name["--application-name NAME"]
    option --> deployment_type["--deployment-type TYPE"]
    option --> install_output["--install-output PATH"]
    option --> release_output["--release-upgrade-output PATH"]
    option --> pointer_output["--upgrade-pointer-output PATH"]
    option --> check["--check"]

    from_ref -. enables .-> upgrade_outputs["release upgrade and pointer outputs"]
    release_output -. requires .-> from_ref
    pointer_output -. requires .-> from_ref
    deployment_type -. requires .-> from_ref
    deployment_type -. choices .-> deployment_note["major, minor, patch"]
    check -. changes execution .-> check_note["verifies generated files are current"]
Loading

Arguments

Argument Default Description
source . Git repository root. dbpm resolves this to the repository top level.
--from none Baseline Git commit or ref used to build the upgrade diff. Must resolve to a commit when supplied. Omit for initial full-install-only generation.
--to HEAD Target Git commit or ref. Must resolve to a commit.
--version package.version in dbpm.yaml Target semantic version. Required when the repository has no dbpm manifest.
--application-name normalized package.name, or repository directory name Application registry name. The value is normalized the same way package names are normalized.
--deployment-type inferred Upgrade deployment type. Requires --from; normally inferred from the baseline and target versions.
--install-output scripts.install in manifest, then Deployment_Manifests/deploy.sql Full-install script path, relative to the repository root.
--release-upgrade-output generation.release_upgrade_output, then Deployment_Manifests/releases/{version}/update.sql Versioned upgrade script path, relative to the repository root. Requires --from; supports {version} and <version> placeholders.
--upgrade-pointer-output scripts.upgrade in manifest, then Deployment_Manifests/update.sql Current upgrade pointer script path, relative to the repository root. Requires --from.
--check false Do not write files. Fail if generated scripts are missing or stale.

Outputs

Without --from, the command is in initial deploy mode and renders only the full-install script. With --from, the command renders three files:

Output Description
Full install Deploys the current object tree at --to.
Versioned upgrade Applies object changes between --from and --to.
Upgrade pointer Includes the versioned upgrade script and passes through the deployment commit hash argument.

When generated content differs from the files on disk, dbpm writes the changed files and prints one WROTE=path line for each changed output. With --check, dbpm writes nothing and prints GENERATED_SCRIPTS_OK only when every generated file for the selected mode already matches.

Manifest configuration

generate-scripts reads package identity and default script locations from dbpm.yaml when present:

package:
  name: demo
  version: "1.5.0"

scripts:
  install: Deployment_Manifests/deploy.sql
  upgrade: Deployment_Manifests/update.sql

generation:
  release_upgrade_output: Deployment_Manifests/releases/{version}/update.sql

CLI values override manifest values. Repositories without a dbpm manifest are supported when --version is supplied; use --application-name when the normalized repository directory name is not the desired Core application name.

Table conventions

Canonical table DDL describes the current full-install shape:

Tables/ORDERS.sql

Upgrade-specific table lifecycle scripts use the target release version:

Tables/ORDERS.alter.1.5.0.sql
Tables/ORDERS.recreate.1.5.0.sql
Tables/OLD_ORDERS.drop.1.5.0.sql
  • alter evolves an existing table without running canonical DDL.
  • recreate runs immediately before the updated canonical DDL.
  • drop removes an object and should normally call Core cleanup APIs such as pkg_application.drop_and_forget_object_p.

A modified canonical table without a matching alter or recreate script is emitted as commented SQL in the upgrade script and reported as a warning.

Type conventions

Type files may use generic SQL or explicit type spec/body extensions:

Types/COUNTRY.sql
Types/ADDRESS.tps
Types/ADDRESS.tpb
  • *.sql is treated as generic standalone type DDL.
  • *.tps is treated as a type specification.
  • *.tpb is treated as a type body.

Use .tps and .tpb when type spec/body ordering matters. dbpm does not inspect SQL contents to infer whether a .sql file contains a type spec or type body.

Examples

Generate an initial full-install script from the current repository:

dbpm generate-scripts . --version 0.1.0

Generate install and upgrade scripts from a baseline:

dbpm generate-scripts . --from v0.1.0 --version 0.2.0

Generate from an explicit target ref:

dbpm generate-scripts . --from v1.4.0 --to release/1.5.0

Verify committed generated scripts in CI:

dbpm generate-scripts . --from v1.4.0 --to HEAD --check

Generate for a repository without dbpm.yaml:

dbpm generate-scripts . --from v1.4.0 --version 1.5.0 --application-name DEMO

Override output paths:

dbpm generate-scripts . \
  --from v1.4.0 \
  --version 1.5.0 \
  --install-output sql/install.sql \
  --release-upgrade-output sql/releases/{version}/update.sql \
  --upgrade-pointer-output sql/update.sql

Notes

  • --to, and --from when supplied, must name committed Git state. Working-tree and staged changes are not used for generation.
  • Full installs contain canonical object and metadata files only. Upgrade scripts register new and modified objects with Core before applying object changes.
  • Existing update files are not removed or checked when --from is omitted.
  • Use Convention-Driven SQL Generation for the convention overview and Convention-Driven SQL Generation Design for the behavioral contract and deferred scope.