dbpm

See Convention-Driven SQL Generation for generating standalone install and versioned upgrade scripts from Git changes.

dbpm is a package manager for Oracle database applications and reusable PL/SQL components.

The goal is to bring modern dependency management, versioning, packaging, and deployment workflows to Oracle database development.

Visit the dbpm website for product documentation and the package registry for published package metadata.

Installation

dbpm requires Python 3.11 or newer. Install the command in an isolated environment with pipx:

pipx install dbpm
dbpm --version

uv users can install the same PyPI package with:

uv tool install dbpm

Installing into an existing Python environment with python -m pip install dbpm is also supported.

Database deployment commands require access to an Oracle database and an Oracle-compatible command-line runner. Set DBPM_SQL_RUNNER to SQLcl (the sql executable) or SQL*Plus. Core is dbpm's in-database deployment substrate; run dbpm check-core before managed deployments, or use dbpm bootstrap-core for an empty schema. See Getting Started for database connection setup.

Vision

dbpm aims to make Oracle database development feel more like modern software engineering ecosystems such as:

• Maven
• npm
• Cargo
• pip

while remaining Oracle-native and deployment-friendly.

Maven-compatible repositories may be useful for publishing immutable package artifacts, but dbpm should not require ordinary package consumers to understand Maven or install a JDK. Consumer installs should use dbpm's own CLI and plain HTTP(S) artifact retrieval where possible.

Goals

• Package reusable PL/SQL libraries
• Deploy end-user Oracle database applications through the same package workflow
• Resolve dependencies automatically
• Support semantic versioning
• Enable repeatable deployments
• Use Core as the in-database install registry and deployment substrate
• Support schema evolution
• Inject deployment provenance from package artifacts
• Lock deployments to immutable artifact identities
• Simplify CI/CD integration
• Reduce fragile hand-managed deployment scripts

Example

dbpm check-core --minimum-version 3.2.0
dbpm plan gh-maven:rsantmyer/simple_scheduler:com.512itconsulting.database:simple_scheduler:1.1.0 --mode install --dependency-source gh-maven:512itconsulting/utl_interval:com.512itconsulting.database:utl_interval:1.0.0
dbpm lock gh-maven:rsantmyer/simple_scheduler:com.512itconsulting.database:simple_scheduler:1.1.0 --dependency-source gh-maven:512itconsulting/utl_interval:com.512itconsulting.database:utl_interval:1.0.0
dbpm install --lockfile dbpm-lock.json

For a guided setup, see Getting Started. See the changelog for release contents and release checklist for the versioning process.

Features

• Package manifests through dbpm.yaml, dbpm.yml, dbpm.json, or package.dbpm.yaml
• Workspace manifests through dbpm-workspace.yaml for repositories with multiple package roots
• Local package directory sources
• Local ZIP package sources
• GitHub Maven ZIP package sources with gh-maven:owner/repo:group:artifact:version[:extension]
• Generic Maven ZIP package sources with maven:repository-url::group:artifact:version[:extension]
• dbpm registry sources with registry:package@constraint
• HTTPS ZIP artifact sources for lockfile installs
• Maven snapshot ZIP resolution through maven-metadata.xml
• SHA-256 checksum capture for ZIP artifacts and deterministic TREE-SHA-256 capture for local directories
• Content-addressed artifact cache keyed by SHA-256 for lockfile-verified downloads
• Exact and caret-compatible dependency constraints
• Ordered multi-package install, conservative upgrade, and validate for dependency sources
• Dependency lockfile generation and verification through dbpm lock
• Lockfile-driven install without restating package sources
• Core-backed installed-state lookup
• Core-backed reverse-dependency lookup
• Core provenance staging through pkg_application.stage_deployment_provenance_p
• Core DEPLOY_LOCKED-aware deployment policy
• Install, upgrade, reinstall, resume, and validate workflows
• Read-only planning for manifest-declared composable runtimes (runtime: in dbpm.yaml), including isolated dependency payload paths and command exports beneath a root-application prefix. Filesystem staging and activation remain in progress (see spec/runtime-component.md).
• ZIP artifact publishing to GitHub Packages and generic Maven repositories
• GPG artifact signing and lockfile-driven signature verification
• dbpm registry source resolution and artifact metadata indexing

Known Limitations

• Multi-package dependency execution does not support reinstall.
• Application-owned runtime composition, isolated dependency payloads, and declarative command exports support install execution with isolated staging, package-local scripts, export validation, payload promotion, command-link activation, and an application receipt. Runtime validate reconciles the receipt, payload identities, managed links, executable targets, and package health scripts. Runtime resume can retry a matching incomplete staged generation. Runtime upgrade retains prior versioned payloads, and reinstall reconstructs same-version payloads with recovery backups. The active and immediately prior generation are retained; unreachable older payloads and recovery metadata are garbage-collected after activation. Uninstall removes dbpm-owned runtime state while preserving operator data, and rollback reactivates only database-compatible retained generations. The removed package-owned fields runtime.name, runtime.home_env, runtime.into, and runtime.layout are rejected.
• Lockfile database provenance reconciliation requires Core 3.3.0 or newer.
• Non-lockfile installs use the coordinate-based cache without checksum verification; the lockfile path has full SHA-256 verification.

Roadmap

• APEX integration
• Registry search/info commands and compatibility-aware registry resolution

Status

Live-tested against GitHub Packages artifacts for:

• core
• utl_interval
• simple_scheduler

simple_scheduler depends on utl_interval; dbpm can install both from GitHub Packages in dependency order and record Core provenance with artifact URLs and SHA-256 checksums.

Environment

Database and GitHub Packages access is configured through a local, uncommitted shell environment file. Start from the committed dbpm-env.sh.example template:

cp dbpm-env.sh.example dbpm-env.sh
chmod 600 dbpm-env.sh

Common variables:

• DBPM_SQL_RUNNER: SQLcl or SQL*Plus executable, such as sql
• DBPM_CONNECT: raw Oracle connect string, such as user/password@service
• DBPM_CONNECT_NAME: SQLcl saved connection name local to the invoking OS user. Mutually exclusive with DBPM_CONNECT; requires SQLcl as the runner.
• DBPM_GITHUB_TOKEN: GitHub token with package read access
• DBPM_GITHUB_USER: optional GitHub username for package authentication
• DBPM_SIGNING_KEY: optional default GPG key ID, fingerprint, or email for dbpm publish
• DBPM_MAVEN_TOKEN: token for generic Maven publishing targets
• DBPM_MAVEN_USER: optional username for generic Maven publishing targets
• DBPM_REGISTRY_URL: optional default registry URL, default: https://registry.dbpm.io
• DBPM_REGISTRY_TOKEN: bearer token for registry indexing
• DBPM_REGISTRY_PUBLISHER: optional registry publisher override
• DBPM_REGISTRY_DESCRIPTION: optional registry description override
• DBPM_CACHE_DIR: optional local artifact cache directory, default: ~/.dbpm/cache
• DBPM_LOG_DIR: optional execution log directory, default: .dbpm-logs in the current working directory
• DBPM_RUN_DB_TESTS: optional 1 to enable live database pytest tests

For SQLcl saved connections, do not put the saved connection name in DBPM_CONNECT. Unset DBPM_CONNECT and set DBPM_CONNECT_NAME instead:

unset DBPM_CONNECT
export DBPM_CONNECT_NAME="Development Database (APP_USER)"
export DBPM_SQL_RUNNER=sql

Commands

Run dbpm <command> --help for a quick flag reference. See docs/commands/source-types.md for the full source and version constraint syntax.

Related Projects

• core