Extension System¶

Purpose: Guide to OraDBA extension system for adding custom scripts and tools.

Audience: DBAs and developers extending OraDBA functionality.

The OraDBA extension system allows you to add custom scripts and tools without modifying the core OraDBA installation. Extensions are automatically discovered and integrated into your environment, working seamlessly with the Registry API and Plugin System.

What Are Extensions¶

Extensions are directories parallel to your OraDBA installation that contain custom:

Scripts (bin/) - Added to PATH automatically
SQL Scripts (sql/) - Added to SQLPATH for SQL*Plus
RMAN Scripts (rcv/) - Available for RMAN operations
Configuration (etc/) - Example configurations
Libraries (lib/) - Shared bash libraries

OraDBA automatically discovers extensions in ${ORADBA_LOCAL_BASE} (typically /opt/oracle/local). Extensions are identified by:

Metadata file: Directories with .extension file
Content directories: Directories with bin/, sql/, or rcv/ subdirectories

The core OraDBA installation (/opt/oradba) is excluded from discovery.

OraDBA creates navigation aliases for each extension:

# If extension name is "customer"
cdecustomer              # cd to extension directory

# If extension name is "monitoring"
cdemonitoring           # cd to monitoring extension

Each loaded extension also exports a <NAME>_BASE variable pointing to its directory:

echo $CUSTOMER_BASE    # /opt/oracle/local/customer
echo $USZ_BASE         # /opt/oracle/local/usz

Quick Start¶

Creating an Extension¶

Method 1: Using the create command (Recommended)¶

# Create new extension from default template
oradba_extension.sh create mycompany

# Follow the displayed next steps:
# 1. Review and customize files
# 2. Edit .extension metadata
# 3. Add your scripts to bin/, sql/, rcv/
# 4. Reload environment
source oraenv.sh FREE

# Verify extension is loaded
oradba_extension.sh list

Method 2: Manual creation¶

Create extension directory:

mkdir -p /opt/oracle/local/customer/bin
mkdir -p /opt/oracle/local/customer/sql

Add your scripts:

# Add a custom database script
cat > /opt/oracle/local/customer/bin/check_db.sh << 'EOF'
#!/usr/bin/env bash
echo "Custom database check for ${ORACLE_SID}"
sqlplus -s / as sysdba << SQL
SELECT name, open_mode FROM v\$database;
SQL
EOF

chmod +x /opt/oracle/local/customer/bin/check_db.sh

Source OraDBA environment:

source oraenv.sh FREE
# Extension is auto-discovered and loaded

check_db.sh  # Your script is now in PATH

Optional: Add Metadata¶

Create a .extension file for better tracking:

cat > /opt/oracle/local/customer/.extension << 'EOF'
name: customer
version: 1.0.0
priority: 10
author: DBA Team
description: Customer-specific Oracle tools and scripts
EOF

Database Monitoring Extension Example¶

mkdir -p /opt/oracle/local/monitoring/{bin,sql}

# Add monitoring script
cat > /opt/oracle/local/monitoring/bin/check_tablespaces.sh << 'EOF'
#!/usr/bin/env bash
sqlplus -s / as sysdba @${ORADBA_LOCAL_BASE}/monitoring/sql/tablespaces.sql
EOF

# Add SQL query
cat > /opt/oracle/local/monitoring/sql/tablespaces.sql << 'EOF'
SET PAGESIZE 100 LINESIZE 200
SELECT tablespace_name,
       ROUND(used_space*8192/1024/1024,2) used_mb,
       ROUND(tablespace_size*8192/1024/1024,2) size_mb,
       ROUND(used_percent,2) pct_used
FROM dba_tablespace_usage_metrics
ORDER BY pct_used DESC;
EOF

chmod +x /opt/oracle/local/monitoring/bin/check_tablespaces.sh

Backup Extension Example¶

mkdir -p /opt/oracle/local/backup/{bin,rcv}

# Add backup script
cat > /opt/oracle/local/backup/bin/backup_db.sh << 'EOF'
#!/usr/bin/env bash
rman target / @${ORADBA_LOCAL_BASE}/backup/rcv/level0.rman
EOF

# Add RMAN script
cat > /opt/oracle/local/backup/rcv/level0.rman << 'EOF'
RUN {
  BACKUP DATABASE PLUS ARCHIVELOG;
  DELETE NOPROMPT OBSOLETE;
}
EOF

chmod +x /opt/oracle/local/backup/bin/backup_db.sh

Managing Extensions¶

Use the oradba_extension.sh command-line tool to create, install, inspect, and validate extensions.

Create¶

# Create from default template
oradba_extension.sh create mycompany

# Create from GitHub release
oradba_extension.sh create mycompany --from-github

# Create with custom template
oradba_extension.sh create mycompany --template /path/to/template.tar.gz

# Create in custom location
oradba_extension.sh create mycompany --path /opt/oracle/custom

The create command validates the extension name, extracts the template to the target location, updates metadata with the new name, and displays next steps for customization.

Add / Install¶

Install existing extensions from GitHub or local tarballs:

# Install from GitHub (latest release)
oradba_extension.sh add oehrlis/odb_autoupgrade

# Install specific version
oradba_extension.sh add oehrlis/odb_autoupgrade@v1.2.0

# Install from local tarball
oradba_extension.sh add /path/to/extension.tar.gz

# Update existing extension (preserves modified configs)
oradba_extension.sh add oehrlis/odb_autoupgrade --update

# Install with custom name
oradba_extension.sh add oehrlis/odb_xyz --name custom_name

The add command downloads and extracts the extension, validates its structure, and enables it by default. When updating with --update, it:

Creates a timestamped backup (e.g., extension_backup_20260211_193500/)
Preserves modified files detected via .extension.checksum
Preserves user-added files: *.conf, *.sh, *.sql, *.rcv, *.rman, *.env, *.properties
Installs new extension content
Restores all preserved files to their original locations

This means customized configuration files (e.g., etc/datasafe.conf) and custom scripts you have added to bin/, sql/, or rcv/ are automatically preserved and restored during the update.

List¶

# Show all extensions
oradba_extension.sh list

# NAME                 VERSION      PRIORITY   STATUS
# ----                 -------      --------   ------
# customer             1.0.0        10         Enabled
# monitoring           2.1.0        20         Enabled

# Show detailed information
oradba_extension.sh list --verbose

# List only enabled or disabled extensions
oradba_extension.sh enabled
oradba_extension.sh disabled

Info¶

oradba_extension.sh info customer

# Extension Information
# =====================
# Name:        customer
# Version:     1.0.0
# Enabled:     yes
# Priority:    10
# Path:        /opt/oracle/local/customer
# ...

Validate¶

# Validate specific extension
oradba_extension.sh validate customer

# Validate all extensions
oradba_extension.sh validate-all

Discover¶

# Show auto-discovered extensions
oradba_extension.sh discover

# Display search paths
oradba_extension.sh paths

Configuration¶

Priority and Load Order¶

Extensions support priority-based loading (lower number = higher priority):

# In .extension file
priority: 10

Extensions are loaded in PATH as:

Core OraDBA (${ORADBA_BIN})
Extensions (by priority: 10, 20, 30, ...)
Oracle Home (${ORACLE_HOME}/bin)
System PATH

This ensures OraDBA core commands are always available, high-priority extensions can override Oracle tools, and low-priority extensions do not interfere with core functionality.

Enable/Disable Extensions¶

In oradba_customer.conf:

# Disable specific extension
export ORADBA_EXT_CUSTOMER_ENABLED="false"

# Enable extension (default)
export ORADBA_EXT_CUSTOMER_ENABLED="true"

Override Priority¶

# Change priority (lower = higher priority)
export ORADBA_EXT_CUSTOMER_PRIORITY="5"

Manual Extension Paths¶

# Add extensions not in ORADBA_LOCAL_BASE
export ORADBA_EXTENSION_PATHS="/data/ext1:/opt/custom/ext2"

Disable Auto-Discovery¶

# Disable auto-discovery (use only manual paths)
export ORADBA_AUTO_DISCOVER_EXTENSIONS="false"

Extension Structure¶

Minimal extension — a single content directory is sufficient:

/opt/oracle/local/customer/
└── bin/
    └── my_script.sh

Complete extension with all optional components:

/opt/oracle/local/customer/
├── .extension              # Metadata (optional)
├── .extension.checksum     # SHA256 checksums for integrity (optional)
├── README.md              # Documentation (recommended)
├── bin/                   # Executable scripts (added to PATH)
│   ├── tool1.sh
│   └── tool2.sh
├── sql/                   # SQL scripts (added to SQLPATH)
│   ├── query1.sql
│   └── query2.sql
├── rcv/                   # RMAN scripts (ORADBA_RCV_PATHS)
│   └── backup.rman
├── etc/                   # Configuration examples
│   └── config.example
└── lib/                   # Shared libraries
    └── functions.sh

Best practices:

Always create .extension for version tracking
Include README.md with usage instructions
Keep extensions in version control (git)
Run oradba_extension.sh validate before deployment
Avoid overriding core OraDBA commands
Choose distinctive script names to avoid conflicts
Use ${ORADBA_LOG} for logging (shared by default)
Use etc/ for configuration templates

Available Extensions¶

Extensions are separate packages that integrate with OraDBA to provide additional functionality. Each extension has its own repository and version numbers, follows the standard OraDBA directory structure (bin/, sql/, rcv/, lib/, etc.), is automatically discovered when placed parallel to the OraDBA installation, and can be installed using the OraDBA extension management tools.

OraDBA Extension Template¶

Repository: oehrlis/oradba_extension
Category: Development
Status: Active

Template and example for creating OraDBA extensions

View Documentation

OraDBA Data Safe Extension¶

Repository: oehrlis/odb_datasafe
Category: Operations
Status: Active

Tools for managing Oracle Data Safe targets in OCI with simplified CLI and comprehensive logging

View Documentation

OraDBA AutoUpgrade Extension¶

Repository: oehrlis/odb_autoupgrade
Category: Operations
Status: Active

Oracle AutoUpgrade wrapper scripts with ready-to-use configs for database upgrades

View Documentation

OraDBA Extras Extension¶

Repository: oehrlis/odb_extras
Category: Operations
Status: Active

Additional Oracle DBA utilities and helper scripts

View Documentation

Contributing Extensions¶

To have your extension listed here:

Follow the structure - Use the standard OraDBA extension layout
Add documentation - Include markdown docs in your repository's README
Submit a request - Open an issue or PR to add your extension to this catalog
Review process - Extensions are reviewed for quality and compatibility

Each extension maintains its own documentation in its GitHub repository. At minimum, the README should include an overview and features, installation instructions, configuration options, usage examples and command reference, and a changelog with version history. See the Extension Template for a complete example with comprehensive documentation structure.

Troubleshooting¶

Extension Not Found¶

Problem: Extension doesn't appear in oradba_extension.sh list

Solutions:

Check directory location:

ls -la ${ORADBA_LOCAL_BASE}

Verify content directories exist:

ls -la /opt/oracle/local/customer/bin

Check discovery setting:

echo ${ORADBA_AUTO_DISCOVER_EXTENSIONS}

Scripts Not in PATH¶

Problem: Extension scripts not available after sourcing oraenv

Solutions:

Verify files are executable:

chmod +x /opt/oracle/local/customer/bin/*.sh

Check PATH includes extension:

echo ${PATH} | tr ':' '\n' | grep customer

Source oraenv again:

source oraenv.sh ${ORACLE_SID}

Integrity Check Failures¶

Problem: Extension shows failed checksum verification

Symptoms:

Extension Integrity Checks:
  Managed directories: bin, sql, rcv, etc, lib
  (Other directories like doc/ and templates/ are not verified)
  ✗ Extension 'customer': FAILED

Note: Only files in managed directories (bin, sql, rcv, etc, lib) are verified. Files in other directories like doc/, templates/, or log/ are intentionally excluded from integrity checks.

Solutions:

Verify extension is enabled:

oradba_extension.sh list
# Disabled extensions are not checked

Check what files changed:

# Use verbose mode to see details
oradba_version.sh --info --verbose

# Or check manually
cd /opt/oracle/local/customer
sha256sum -c .extension.checksum

Update checksums after intentional changes:

cd /opt/oracle/local/customer
# Regenerate checksums for all files
find bin sql rcv etc lib -type f 2>/dev/null | sort | \
  xargs sha256sum > .extension.checksum

Exclude files from integrity checks by creating or editing .checksumignore:

# Add patterns to .checksumignore
cat >> .checksumignore << 'EOF'
# Temporary files
tmp/
*.tmp

# Credentials (if stored in extension)
keystore/
secrets/
EOF

Checksum Exclusions (.checksumignore):

The .checksumignore file lets you exclude specific files or patterns from integrity checks.

Default exclusions (always applied): .extension (metadata file), .checksumignore (this file itself), and log/ (log directory).

Pattern syntax:

One pattern per line, # for comments
* matches any characters: *.log, data/*.cache
? matches one character: file?.txt
Patterns ending with / match directories: tmp/, keystore/

Common patterns:

# Runtime files
cache/
tmp/
*.tmp
*.cache

# Credentials
keystore/
secrets/
*.key
*.pem

# User configs
etc/*.local

Use oradba_version.sh --verify --verbose to see detailed output showing exactly which files are modified, missing, or untracked.

Priority Issues¶

Problem: Wrong extension loads first

Solution: Set priority explicitly in oradba_customer.conf:

export ORADBA_EXT_IMPORTANT_PRIORITY="5"   # Loads last (appears first in PATH)
export ORADBA_EXT_OTHER_PRIORITY="50"      # Loads first (appears later in PATH)

Extension System¶

What Are Extensions¶

Navigation Aliases¶

Quick Start¶

Creating an Extension¶

Method 1: Using the create command (Recommended)¶

Method 2: Manual creation¶

Optional: Add Metadata¶

Database Monitoring Extension Example¶

Backup Extension Example¶

Managing Extensions¶

Create¶

Add / Install¶

List¶

Info¶

Validate¶

Discover¶

Configuration¶

Priority and Load Order¶

Enable/Disable Extensions¶

Override Priority¶

Manual Extension Paths¶

Disable Auto-Discovery¶

Extension Structure¶

Available Extensions¶

OraDBA Extension Template¶

OraDBA Data Safe Extension¶

OraDBA AutoUpgrade Extension¶

OraDBA Extras Extension¶

Contributing Extensions¶

Troubleshooting¶

Extension Not Found¶

Scripts Not in PATH¶

Integrity Check Failures¶

Priority Issues¶

See Also¶