Project Overview

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. Published releases are available on PyPI, and the CLI can be installed with your preferred Python tool:

## pipx
pipx install dbpm

## uv
uv tool install dbpm

## pip
python3 -m pip install --user dbpm

For a quick sanity check after installation:

dbpm --version

If you want to install directly from the GitHub repository instead of PyPI, use:

python3 -m pip install --user git+https://github.com/512itconsulting/[email protected]

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
Application-owned runtime composition for manifest-declared runtimes (runtime: in dbpm.yaml), including isolated dependency payloads, package-local scripts, command exports, staged activation, validation, resume, upgrade, reinstall, uninstall, and rollback. See spec/runtime-component.md for the behavioral contract.
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.
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

Command	Description
`dbpm init`	Scaffold a new package or workspace directory
`dbpm check-core`	Verify Core is installed and meets a minimum version
`dbpm plan`	Generate and print a deployment plan without executing
`dbpm lock`	Write or verify a dependency lockfile
`dbpm bootstrap-core`	Install Core into an empty schema
`dbpm install`	Install a package not yet registered in Core
`dbpm upgrade`	Upgrade an installed package to a higher version
`dbpm reinstall`	Destructively reinstall a package
`dbpm resume`	Resume a running or failed deployment
`dbpm validate`	Run a package’s validation script
`dbpm uninstall`	Remove an application and its managed runtime
`dbpm rollback`	Reactivate a database-compatible retained runtime generation
`dbpm generate-scripts`	Generate standalone Oracle install and upgrade scripts from Git changes
`dbpm publish`	Build and publish a package to a Maven repository with GPG signing
`dbpm registry index`	Index a published immutable artifact in a dbpm registry
`dbpm workspace list`	List packages declared by a workspace manifest

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

core

Source: README.md