OraDBA Data Safe Extension - Quick Reference¶

Current version: see ../VERSION | Release Notes

📁 Project Structure¶

odb_datasafe/                          # OraDBA Extension for Data Safe
├── .extension                         # Extension metadata
├── VERSION                            # Current extension version
├── README.md                          # Complete documentation
├── CHANGELOG.md                       # Release history
├── QUICKREF.md                        # This file
├── LICENSE                            # Apache 2.0
│
├── bin/                               # Executable scripts (added to PATH)
│   ├── template.sh                    # Copy this to create new scripts
│   ├── ds_target_list.sh              # List Data Safe targets
│   ├── ds_target_list_connector.sh    # List Data Safe connectors
│   ├── ds_target_connector_summary.sh # Group targets by connector
│   ├── ds_target_refresh.sh           # Refresh Data Safe targets
│   ├── ds_target_update_*.sh          # Update target properties
│   ├── ds_connector_update.sh         # Update Data Safe connector
│   ├── ds_connector_register_oradba.sh # Register connector in OraDBA config
│   ├── datasafe_env.sh                # Sourceable standalone shell environment
│   ├── ds_version.sh                  # Show extension version and integrity
│   └── install_datasafe_service.sh    # Install connector as service
│
├── lib/                               # Shared library framework
│   ├── ds_lib.sh                      # Main loader (2 lines, sources both)
│   ├── common.sh                      # Generic helpers (~350 lines)
│   ├── oci_helpers.sh                 # OCI Data Safe ops (~400 lines)
│   └── README.md                      # Library API documentation
│
├── etc/                               # Configuration examples
│   ├── datasafe.conf.example          # Main config template
│   └── odb_datasafe.conf.example      # OCI IAM config template
│
├── sql/                               # SQL scripts (added to SQLPATH)
├── tests/                             # Test suite (BATS)
└── scripts/                           # Dev/build tools
    ├── build.sh                       # Build extension tarball
    └── rename-extension.sh            # Rename extension helper

🚀 Quick Start¶

1. Setup Configuration¶

# Navigate to extension base directory
cd /path/to/odb_datasafe  # This is $ODB_DATASAFE_BASE

# Create environment file in base directory (NOT in etc/)
cp etc/.env.example .env
vim .env
  # Set: DS_ROOT_COMP, OCI_CLI_PROFILE, etc.

# IMPORTANT: .env must be in extension base directory:
#   odb_datasafe/.env  <-- HERE (correct)
#   odb_datasafe/etc/.env  <-- WRONG (will not be loaded)

# (Optional) Create config file
cp etc/datasafe.conf.example etc/datasafe.conf
vim etc/datasafe.conf

2. Test Installation¶

# Source environment
source .env

# Test library load
bash -c 'source lib/ds_lib.sh && log "INFO" "Library loaded successfully"'

# Test script
bin/ds_target_refresh.sh --help

3. Basic Usage¶

# Show help overview of all available tools
bin/odb_datasafe_help.sh

# Show extension version, metadata, and integrity status
bin/ds_version.sh

# List Data Safe targets (default: table view)
bin/ds_target_list.sh

# Overview grouped by cluster/SID from target name
bin/ds_target_list.sh --overview

# Overview with status counts disabled
bin/ds_target_list.sh --overview --no-status

# List Data Safe on-premises connectors
bin/ds_target_list_connector.sh

# Show summary of targets grouped by connector
bin/ds_target_connector_summary.sh

# Show detailed targets per connector
bin/ds_target_connector_summary.sh -D

# Generate target-group report (all sections)
bin/ds_tg_report.sh

# Run target-group report from saved target JSON
bin/ds_tg_report.sh --input-json ./target_selection.json -r env

# Persist selected targets while running report
bin/ds_tg_report.sh -c prod-compartment --save-json ./target_selection.json

# Show count summary by lifecycle state
bin/ds_target_list.sh --count

# Quiet mode (default; warnings/errors only)
bin/ds_target_list.sh -q

# Debug mode (TRACE+DEBUG plus higher levels)
bin/ds_target_list.sh -d

# Filter by lifecycle state
bin/ds_target_list.sh -L NEEDS_ATTENTION
bin/ds_target_list_connector.sh -L ACTIVE

# Filter target names by regex (display name substring match)
bin/ds_target_list.sh -r "db02"
bin/ds_target_refresh.sh -r "db02"

# Overview for filtered scope only
bin/ds_target_list.sh --overview -r "db02"

# Explicitly select all targets from DS_ROOT_COMP
bin/ds_target_list.sh --all
bin/ds_target_refresh.sh --all

# Output as JSON or CSV
bin/ds_target_list.sh -f json
bin/ds_target_list_connector.sh -f csv -F display-name,id,time-created

# Refresh specific target (dry-run first)
bin/ds_target_refresh.sh -T mydb01 --dry-run --debug

# Refresh for real
bin/ds_target_refresh.sh -T mydb01

# Refresh multiple targets
bin/ds_target_refresh.sh -T db1,db2,db3

# Refresh all NEEDS_ATTENTION in compartment
bin/ds_target_refresh.sh -c "MyCompartment" -L NEEDS_ATTENTION

# Refresh intersection of explicit targets and regex filter
bin/ds_target_refresh.sh -T db01,db02,db03 -r "db02"

# Dry-run refresh from saved selection JSON
bin/ds_target_refresh.sh --input-json ./target_selection.json --dry-run

# Apply refresh from saved selection JSON (requires explicit safeguard override)
bin/ds_target_refresh.sh --input-json ./target_selection.json --allow-stale-selection

# Activate INACTIVE targets in a compartment (dry-run by default)
bin/ds_target_activate.sh -c "MyCompartment" -L INACTIVE

# Apply activation changes and wait for completion
bin/ds_target_activate.sh -c "MyCompartment" -L INACTIVE --apply --wait-state ACCEPTED

# Activate specific targets by name (uses --compartment or DS_ROOT_COMP for resolution)
bin/ds_target_activate.sh -c "MyCompartment" -T db1,db2 --apply

# Activate only targets matching regex
bin/ds_target_activate.sh -c "MyCompartment" -r "db02" --apply

# Consolidated issue summary (all issue categories)
bin/ds_target_list.sh --mode health

# Problems-only summary (NEEDS_ATTENTION + INACTIVE + UNEXPECTED_STATE)
bin/ds_target_list.sh --mode problems

# Backward-compatible short aliases for mode switching
# -C=count, -H=health, -P=problems, -R=report
bin/ds_target_list.sh -C
bin/ds_target_list.sh -H
bin/ds_target_list.sh -P
bin/ds_target_list.sh -R

# Drill down into one issue topic (code or label)
bin/ds_target_list.sh --mode health --issue-view details --issue "SID missing CDB root"

# Overview mode
bin/ds_target_list.sh --mode overview

# One-page consolidated high-level report
bin/ds_target_list.sh --report

# Equivalent explicit mode selector for consolidated report
bin/ds_target_list.sh --mode report

# Save selected target JSON payload for reuse
bin/ds_target_list.sh --all --save-json ./target_selection.json

# Run reporting from saved JSON payload (no OCI fetch)
bin/ds_target_list.sh --input-json ./target_selection.json --report

# Report output includes scope banner, coverage metrics, SID impact %,
# NEEDS_ATTENTION breakdown, top affected SIDs, and run-to-run deltas
# Issue summary uses health-overview-style aligned single-line rows
# with severity/count/SIDs plus SID %
# Top affected SIDs shows top 10 with "showing X of Y"; empty issue sections
# collapse to "none" for cleaner healthy-scope output

# Reuse saved payload with additional local filtering
bin/ds_target_list.sh --input-json ./target_selection.json -r "db02" --mode health

# Show all fields for a target (JSON only)
bin/ds_target_list.sh -T mydb01 -F all -f json

# Issue summary in JSON for automation
bin/ds_target_list.sh --mode health -f json

# Update credentials for targets matching regex (dry-run default)
bin/ds_target_update_credentials.sh -r "db02"

# Apply credential update for regex-matched targets
bin/ds_target_update_credentials.sh -r "db02" --apply

# Dry-run credential update from saved selection JSON
bin/ds_target_update_credentials.sh --input-json ./target_selection.json -U dbuser --dry-run

# Apply credential update from saved selection JSON (requires explicit safeguard override)
bin/ds_target_update_credentials.sh --input-json ./target_selection.json -U dbuser --apply --allow-stale-selection

# Apply with interactive OCI confirmation (disable default force mode)
bin/ds_target_update_credentials.sh -r "db02" --apply --no-force

# Update tags for targets matching regex
bin/ds_target_update_tags.sh -r "db02" --apply

# Dry-run tag update from saved selection JSON
bin/ds_target_update_tags.sh --input-json ./target_selection.json

# Apply tag update from saved selection JSON (requires explicit safeguard override)
bin/ds_target_update_tags.sh --input-json ./target_selection.json --apply --allow-stale-selection

# Update service names for targets matching regex
bin/ds_target_update_service.sh -c "MyCompartment" -r "db02" --apply

# Dry-run service update from saved selection JSON
bin/ds_target_update_service.sh --input-json ./target_selection.json

# Apply service update from saved selection JSON (requires explicit safeguard override)
bin/ds_target_update_service.sh --input-json ./target_selection.json --apply --allow-stale-selection

4. Default Behavior Without Parameters¶

Scripts with useful no-argument defaults (execute immediately):

bin/ds_target_list.sh → list targets in default scope (DS_ROOT_COMP fallback)
bin/ds_target_list_connector.sh → list connectors in default scope
bin/ds_target_connector_summary.sh → connector summary output
bin/ds_target_refresh.sh → refresh NEEDS_ATTENTION targets in default scope
bin/ds_tg_report.sh → report type all

Scripts requiring explicit intent show usage/help when started without parameters:

bin/ds_target_update_connector.sh
bin/ds_target_update_credentials.sh
bin/ds_target_update_service.sh
bin/ds_target_update_tags.sh
bin/ds_target_move.sh
bin/ds_target_register.sh
bin/ds_target_delete.sh
bin/ds_target_audit_trail.sh
bin/ds_connector_register_oradba.sh

5. On-Prem Database Prereqs¶

ds_database_prereqs.sh runs locally on the DB host and creates/updates the Data Safe profile, user, and grants. You can use the embedded payload in the script or provide the SQL files on the server. The Oracle environment must be sourced first.

# Base directory on the DB host.
# In OraDBA mode, ODB_DATASAFE_BASE is set automatically.
export DATASAFE_BASE="${ODB_DATASAFE_BASE:-${ORACLE_BASE}/local/datasafe}"

# Copy to DB host (embedded payload)
scp bin/ds_database_prereqs.sh oracle@dbhost:${DATASAFE_BASE}/
ssh oracle@dbhost chmod 755 ${DATASAFE_BASE}/ds_database_prereqs.sh

# Copy to DB host (external SQL files)
scp bin/ds_database_prereqs.sh sql/*.sql oracle@dbhost:${DATASAFE_BASE}/
ssh oracle@dbhost chmod 755 ${DATASAFE_BASE}/ds_database_prereqs.sh

# Source environment on DB host
export ORACLE_SID=cdb01
. oraenv <<< "${ORACLE_SID}" >/dev/null

# Run for root or all open PDBs
${DATASAFE_BASE}/ds_database_prereqs.sh --root -P "<password>"
${DATASAFE_BASE}/ds_database_prereqs.sh --all -P "<password>"

# Update secret for existing user (no drop)
${DATASAFE_BASE}/ds_database_prereqs.sh --root -P "<password>" --update-secret

# Base64 password input (auto-decoded)
DS_PW_B64=$(printf '%s' 'mySecret' | base64)
${DATASAFE_BASE}/ds_database_prereqs.sh --root -P "${DS_PW_B64}"

# Use embedded payload
${DATASAFE_BASE}/ds_database_prereqs.sh --root --embedded -P "<password>"

5. Getting Help¶

The odb_datasafe_help.sh script provides an overview of all available tools:

# Show all available tools in table format
bin/odb_datasafe_help.sh

# Export as markdown for documentation
bin/odb_datasafe_help.sh -f markdown

# Export as CSV for processing
bin/odb_datasafe_help.sh -f csv

# Quiet mode (no header/footer)
bin/odb_datasafe_help.sh -q

6. Target-Connector Summary¶

The ds_target_connector_summary.sh script provides enhanced visibility of the relationship between targets and on-premises connectors:

# Show summary of targets grouped by connector (default)
bin/ds_target_connector_summary.sh

# Output shows:
# - Connector name
# - Lifecycle state breakdown per connector
# - Count per lifecycle state
# - Subtotals per connector
# - Grand total of all targets

# Example output:
# Connector                                          Lifecycle State      Count
# -------------------------------------------------- -------------------- ----------
# prod-connector                                     ACTIVE                      5
#                                                    NEEDS_ATTENTION             2
#                                                    Subtotal                    7
#
# test-connector                                     ACTIVE                      3
#                                                    CREATING                    1
#                                                    Subtotal                    4
#
# No Connector (Cloud)                               ACTIVE                     10
#                                                    Subtotal                   10
# -------------------------------------------------- -------------------- ----------
# GRAND TOTAL                                                                   21

# Show detailed list of targets under each connector
bin/ds_target_connector_summary.sh -D

# Filter by lifecycle state (applies to all connectors)
bin/ds_target_connector_summary.sh -L ACTIVE

# Output as JSON (useful for automation)
bin/ds_target_connector_summary.sh -f json

# Output as CSV (useful for reporting)
bin/ds_target_connector_summary.sh -f csv

# Detailed view with custom fields
bin/ds_target_connector_summary.sh -D -F display-name,lifecycle-state,id

# Run connector summary from saved target selection JSON (no OCI target list)
bin/ds_target_connector_summary.sh --input-json ./target_selection.json

# Persist selected targets while generating summary
bin/ds_target_connector_summary.sh -c prod-compartment --save-json ./target_selection.json

5. Connector Management¶

# List all connectors
bin/ds_target_list_connector.sh

# Update a connector using OraDBA environment (simplest)
bin/ds_connector_update.sh --datasafe-home dscon4

# Update a connector (traditional method with compartment)
bin/ds_connector_update.sh --connector my-connector -c MyCompartment

# Dry-run to see what would be done
bin/ds_connector_update.sh --datasafe-home dscon4 --dry-run

# Check a single connector version/status only (no update)
bin/ds_connector_update.sh --datasafe-home dscon4 --check-only

# Check all datasafe connectors from oradba_homes.conf (batch check)
bin/ds_connector_update.sh --check-all

# Update with specific home directory
bin/ds_connector_update.sh --connector my-connector --connector-home /u01/app/oracle/product/datasafe

# Force new password generation
bin/ds_connector_update.sh --datasafe-home dscon4 --force-new-password

# Use existing bundle file (skip download)
bin/ds_connector_update.sh --connector my-connector --skip-download --bundle-file /tmp/bundle.zip

# Register connector in OraDBA configuration (for --datasafe-home usage)
bin/ds_connector_register_oradba.sh --datasafe-home dscon4 --connector my-connector

# Register connector OCID
bin/ds_connector_register_oradba.sh --datasafe-home dscon4 --connector ocid1.datasafe...

# Preview registration changes (dry-run)
bin/ds_connector_register_oradba.sh --datasafe-home dscon4 --connector my-connector --dry-run

📚 Library Functions (Quick Reference)¶

common.sh - Generic Helpers¶

# Logging
log "INFO" "message"                    # Log with level
die "error message" [exit_code]         # Log error and exit

# Validation
require_cmd "oci" "jq" "curl"           # Check commands exist
require_env "VAR1" "VAR2"               # Check env vars set

# Configuration
load_env_file "/path/to/.env"           # Load .env file
load_config_file "/path/to/conf"        # Load config file

# Arguments
parse_common_flags "$@"                 # Parse standard flags
get_flag_value "flag_name"              # Get parsed flag value

# Utilities
normalize_bool "yes"                    # Returns: true
timestamp                               # Returns: 2026-01-09T10:30:45Z
cleanup_temp_files                      # Remove temp files on exit

oci_helpers.sh - OCI Data Safe Operations¶

# Execute OCI commands
oci_exec "data-safe" "target-database" "list" \
  "--compartment-id" "$comp_id"

# Target operations
ds_list_targets "$compartment_id" "$lifecycle"
ds_get_target "$target_ocid"
ds_refresh_target "$target_ocid"
ds_update_target_tags "$target_ocid" '{"key":"value"}'

# Connector operations
ds_list_connectors "$compartment_id"
ds_resolve_connector_ocid "$name" "$compartment_id"
ds_resolve_connector_name "$connector_ocid"
ds_get_connector_details "$connector_ocid"
ds_generate_connector_bundle "$connector_ocid" "$password"
ds_download_connector_bundle "$connector_ocid" "$output_file"

# Resolution helpers
resolve_target_ocid "target_name"       # Name → OCID
resolve_compartment "comp_name"         # Name → OCID

# Wait/retry
oci_wait_for_state "$resource_ocid" "ACTIVE" [max_wait]

🛠️ Creating New Scripts¶

Step-by-step¶

# 1. Copy template
cp bin/template.sh bin/ds_new_feature.sh

# 2. Edit metadata (top of file)
vim bin/ds_new_feature.sh
  # Update: SCRIPT_NAME, SCRIPT_PURPOSE, VERSION

# 3. Implement parse_args() for script-specific flags
#    (See template.sh for examples)

# 4. Add your business logic in main section

# 5. Test
chmod +x bin/ds_new_feature.sh
bin/ds_new_feature.sh --help
bin/ds_new_feature.sh --dry-run --debug

Standard Script Pattern¶

#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"

# Load library
source "${PROJECT_ROOT}/lib/ds_lib.sh" || exit 1

# Initialize
init_script
load_configuration

# Parse arguments
parse_args "$@"

# Main logic
main() {
    log "INFO" "Starting operation..."
    # Your code here
    log "INFO" "Operation complete"
}

# Run
main

🎯 Common Flags (Standardized)¶

All scripts should support these where applicable:

# Help & Version
-h, --help                    Show usage information
-V, --version                 Show script version

# Logging
-v, --verbose                 Set log level to INFO
-d, --debug                   Set log level to DEBUG
-q, --quiet                   Set log level to ERROR
-l, --log-file <file>         Write logs to file

# Configuration
--config <file>               Load configuration from file
--env <file>                  Load environment from file

# OCI Configuration
--profile <name>              OCI CLI profile (default: $OCI_CLI_PROFILE)
--region <name>               OCI region (default: $OCI_CLI_REGION)

# Execution Control
-n, --dry-run                 Show what would be done (no changes)
-y, --yes                     Skip confirmation prompts

Wait State (`--wait-state STATE`)¶

Supported in all mutating scripts:

ds_target_refresh.sh
ds_target_activate.sh
ds_target_update_credentials.sh
ds_target_update_connector.sh
ds_target_update_service.sh
ds_target_update_tags.sh
ds_target_register.sh
ds_target_delete.sh
ds_target_move.sh

Behavior:

Default (empty): submit the OCI API call and return immediately (async, fast).
--wait-state STATE: block until the work request reaches the given lifecycle state.
Common values: ACCEPTED, IN_PROGRESS, SUCCEEDED, FAILED.

Examples:

# Refresh and return immediately (default)
ds_target_refresh.sh -T mydb01

# Refresh and wait until the work request is SUCCEEDED
ds_target_refresh.sh -T mydb01 --wait-state SUCCEEDED

# Activate and wait for ACCEPTED (earliest confirmation)
ds_target_activate.sh -T mydb01 --apply --wait-state ACCEPTED

# Delete and wait for SUCCEEDED
ds_target_delete.sh -T mydb01 --force --wait-state SUCCEEDED

# Move and wait for SUCCEEDED
ds_target_move.sh -T mydb01 -D prod-compartment --wait-state SUCCEEDED

Target Name Regex Filter (`-r`, `--filter`)¶

Supported in:

ds_target_list.sh
ds_target_refresh.sh
ds_target_activate.sh
ds_target_update_credentials.sh
ds_target_update_connector.sh
ds_target_update_service.sh
ds_target_update_tags.sh

Behavior:

Matches regex against target display name.
Combines with -T/--target(s) using intersection.
Mutating scripts exit with status 1 if no targets match.
ds_target_list.sh reports no matches as an informational empty result.

Examples:

# List only targets containing db02
ds_target_list.sh -r "db02"

# Refresh only targets containing db02
ds_target_refresh.sh -r "db02"

# Activate only targets containing db02
ds_target_activate.sh -c MyCompartment -r "db02" --apply

# Set connector for targets containing db02
ds_target_update_connector.sh set --target-connector conn-prod-01 -r "db02" --apply

# Update service names for targets containing db02
ds_target_update_service.sh -c MyCompartment -r "db02" --apply

# Update credentials for targets containing db02
ds_target_update_credentials.sh -r "db02" --apply

# Update credentials with interactive OCI confirmation
ds_target_update_credentials.sh -r "db02" --apply --no-force

# Update tags for targets containing db02
ds_target_update_tags.sh -r "db02" --apply

All Targets from DS_ROOT_COMP (`-A`, `--all`)¶

Supported in:

ds_target_list.sh
ds_target_refresh.sh
ds_target_activate.sh
ds_target_update_credentials.sh
ds_target_update_connector.sh
ds_target_update_service.sh
ds_target_update_tags.sh

Behavior:

--all requires DS_ROOT_COMP to be configured.
--all cannot be combined with -c/--compartment or -T/--target(s).

Examples:

# List all targets from DS_ROOT_COMP
ds_target_list.sh --all

# Refresh all targets from DS_ROOT_COMP
ds_target_refresh.sh --all

# Activate all INACTIVE targets from DS_ROOT_COMP
ds_target_activate.sh --all --apply

# Update credentials for all ACTIVE targets from DS_ROOT_COMP
ds_target_update_credentials.sh --all --apply

# Update credentials for all ACTIVE targets from DS_ROOT_COMP with confirmation prompts
ds_target_update_credentials.sh --all --apply --no-force

# Set connector for all ACTIVE targets from DS_ROOT_COMP
ds_target_update_connector.sh set --all --target-connector conn-prod-01 --apply

# Update service names for all ACTIVE targets from DS_ROOT_COMP
ds_target_update_service.sh --all --apply

# Update tags for all ACTIVE targets from DS_ROOT_COMP
ds_target_update_tags.sh --all --apply

🧪 Testing¶

# Basic smoke test
bin/ds_target_refresh.sh --help
bin/ds_target_refresh.sh -T dummy --dry-run --debug

# Library test
bash -c 'source lib/ds_lib.sh && \
  log "DEBUG" "Debug test" && \
  log "INFO" "Info test" && \
  log "WARN" "Warning test" && \
  echo "All tests passed"'

# Full BATS test (when available)
bats tests/

📋 Configuration Priority¶

Configuration is loaded in this order (later overrides earlier):

Code defaults - Hardcoded in scripts
Environment file - .env in project root or specified location
Config file - etc/datasafe.conf or specified file
CLI arguments - Command-line flags (highest priority)

Example Flow¶

# 1. Script has default: LOG_LEVEL="INFO"
# 2. .env sets: LOG_LEVEL="WARN"
# 3. datasafe.conf sets: LOG_LEVEL="DEBUG"  
# 4. CLI provides: --debug (sets LOG_LEVEL="DEBUG")
# Result: LOG_LEVEL="DEBUG" (CLI wins)

🐛 Debugging Tips¶

# Maximum verbosity
bin/ds_target_refresh.sh -T target --debug --log-file /tmp/debug.log

# Check library loading
bash -x bin/ds_target_refresh.sh --help 2>&1 | grep -E "source|lib"

# Trace OCI calls
export OCI_CLI_LOG_LEVEL=DEBUG
bin/ds_target_refresh.sh ...

# Dry-run everything
export DRY_RUN=true
bin/ds_target_refresh.sh ...

# Test with minimal config
unset OCI_CLI_PROFILE OCI_CLI_REGION
bin/ds_target_refresh.sh --profile test --region eu-frankfurt-1 ...

🔗 Useful Links¶

Extension README: README.md
Library Docs: lib/README.md
Template: bin/template.sh
Config Examples: etc/
Legacy Project: ../datasafe/

📊 Version Comparison¶

Aspect	Legacy (v3.0.0)	New (v1.0.0)
Library Files	9 modules	2 modules
Total Lines	~3000	~800
Complexity	High (nested deps)	Low (flat)
Learning Curve	Steep	Gentle
Maintainability	Difficult	Easy
Functionality	Full	Full
Performance	Good	Better

💡 Tips & Best Practices¶

Always test with --dry-run first
Use --debug for troubleshooting
Keep scripts under 300 lines - Extract complex logic to lib/
Document functions - Inline comments are your friend
Test error paths - Not just happy paths
Log liberally - But use appropriate levels
Check return codes - Don't assume success
Clean up resources - Use cleanup_temp_files
Validate inputs early - Fail fast, fail clear
Copy template.sh - Don't start from scratch

Maintainer: Stefan Oehrli (oes) stefan.oehrli@oradba.ch

🆕 New in v0.3.0¶

Target Deletion¶

# Delete targets with dependencies (audit trails, assessments, policies)
ds_target_delete.sh -T target1,target2 --delete-dependencies --force

# Delete from compartment with confirmation
ds_target_delete.sh -c prod-compartment

# Continue processing even if errors occur
ds_target_delete.sh -T target1,target2,target3 --continue-on-error

Find Untagged Targets¶

# Find targets without tags in default DBSec namespace
ds_find_untagged_targets.sh

# Find untagged in specific namespace, CSV output
ds_find_untagged_targets.sh -n Security -o csv

# Find in specific compartment
ds_find_untagged_targets.sh -c prod-compartment

# Find untagged from saved target selection JSON
ds_find_untagged_targets.sh --input-json ./target_selection.json

# Persist selected targets from OCI for offline reuse
ds_find_untagged_targets.sh -c prod-compartment --save-json ./target_selection.json

Audit Trail Status and Start¶

# List audit trail states for all targets in DS_ROOT_COMP (read-only)
ds_target_audit_trail.sh --list --all

# List trail states from saved target JSON (avoids re-fetching targets)
ds_target_list.sh --all --save-json /tmp/targets.json
ds_target_audit_trail.sh --list --input-json /tmp/targets.json

# List trail states filtered by name, CSV output
ds_target_audit_trail.sh --list --all --filter prod -f csv

# List trail states as JSON for automation
ds_target_audit_trail.sh --list --all -f json

# Start audit trails for specific targets
ds_target_audit_trail.sh -T target1,target2

# Start trails for all ACTIVE targets in a compartment
ds_target_audit_trail.sh -c prod-compartment -L ACTIVE

# Start trails with custom collection start time and auto-purge
ds_target_audit_trail.sh --all \
  --start-time 2025-01-01T00:00:00Z \
  --auto-purge false

# Start from saved target selection (no re-fetch from OCI)
ds_target_audit_trail.sh --input-json /tmp/targets.json

Move Targets Between Compartments¶

# Move targets with dependencies
ds_target_move.sh -T target1,target2 -D prod-compartment --move-dependencies

# Move entire compartment of targets
ds_target_move.sh -c test-compartment -D prod-compartment --force

# Dry-run first to see what would happen
ds_target_move.sh -c test-compartment -D prod-compartment --dry-run

Update Target Connectors¶

# Set specific connector for target (dry-run by default)
ds_target_update_connector.sh set -T my-target --target-connector conn-prod-01

# Apply connector to specific targets
ds_target_update_connector.sh set -T target1,target2 --target-connector conn-prod-02 --apply

# Include targets needing attention (shortcut for ACTIVE,NEEDS_ATTENTION)
ds_target_update_connector.sh set --target-connector conn-prod-01 --include-needs-attention --apply

# Work with specific lifecycle states
ds_target_update_connector.sh set --target-connector conn-prod-01 -L NEEDS_ATTENTION --apply

# Multiple lifecycle states (comma-separated)
ds_target_update_connector.sh set --target-connector conn-prod-01 -L ACTIVE,NEEDS_ATTENTION --apply

# Migrate all targets from old to new connector
ds_target_update_connector.sh migrate -c my-compartment \
  --source-connector conn-old --target-connector conn-new --apply

# Distribute targets evenly across all available connectors
ds_target_update_connector.sh distribute --apply

# Distribute excluding specific connectors
ds_target_update_connector.sh distribute \
  --exclude-connectors "conn-old,conn-test" --apply

Get Detailed Target Info¶

# Show details for specific targets
ds_target_details.sh -T target1,target2

# Show details for all targets in compartment (JSON output)
ds_target_details.sh -c prod-compartment -O json

# Get cluster/CDB/PDB info for specific target
ds_target_details.sh -T my-target-id -O table

# Load details from saved target selection payload
ds_target_details.sh --input-json ./target_selection.json -f json

# Persist selected targets while collecting details
ds_target_details.sh -c prod-compartment --save-json ./target_selection.json -f json

🆕 New in v0.3.1¶

Export Targets¶

# Export all targets in compartment to CSV
ds_target_export.sh -c prod-compartment

# Export ACTIVE targets to JSON
ds_target_export.sh -c prod-compartment -L ACTIVE -F json -o targets.json

# Export targets created since specific date
ds_target_export.sh -c prod-compartment -D 2025-01-01

# Export from saved target selection payload
ds_target_export.sh --input-json ./target_selection.json -F json -o targets.json

# Persist selected targets for offline reuse
ds_target_export.sh -c prod-compartment --save-json ./target_selection.json

Register New Targets¶

# Register a PDB
ds_target_register.sh -H db01 --sid cdb01 --pdb APP1PDB \
  -c prod-compartment --connector my-connector --ds-secret <secret>

# Register CDB$ROOT  
ds_target_register.sh -H db01 --sid cdb01 --root \
  -c prod-compartment --connector my-connector --ds-secret <secret>

# Register using secret file (<user>_pwd.b64)
ds_target_register.sh -H db01 --sid cdb01 --pdb APP1PDB \
  -c prod-compartment --connector my-connector --secret-file /path/to/DS_ADMIN_pwd.b64

# Check if target already exists
ds_target_register.sh -H db01 --sid cdb01 --pdb APP1PDB \
  -c prod-compartment --connector my-connector --check

# Dry-run to preview registration plan
ds_target_register.sh -H db01 --sid cdb01 --pdb APP1PDB \
  -c prod-compartment --connector my-connector --ds-secret <secret> --dry-run

New in v0.3.2¶

ds_target_connect_details.sh - Display connection details for Data Safe targets

# Show connection details for a target (table format)
ds_target_connect_details.sh -T exa118r05c15_cdb09a15_MYPDB

# Get connection details as JSON
ds_target_connect_details.sh -T ocid1.datasafetargetdatabase... -O json

# Specify compartment for name resolution
ds_target_connect_details.sh -T MYPDB -c my-compartment-name

# Get connection details with debug output
ds_target_connect_details.sh -T exa118r05c15_cdb09a15_MYPDB -d

OraDBA Data Safe Extension - Quick Reference¶

📁 Project Structure¶

🚀 Quick Start¶

1. Setup Configuration¶

2. Test Installation¶

3. Basic Usage¶

4. Default Behavior Without Parameters¶

5. On-Prem Database Prereqs¶

5. Getting Help¶

6. Target-Connector Summary¶

5. Connector Management¶

📚 Library Functions (Quick Reference)¶

common.sh - Generic Helpers¶

oci_helpers.sh - OCI Data Safe Operations¶

🛠️ Creating New Scripts¶

Step-by-step¶

Standard Script Pattern¶

🎯 Common Flags (Standardized)¶

Wait State (--wait-state STATE)¶

Target Name Regex Filter (-r, --filter)¶

All Targets from DS_ROOT_COMP (-A, --all)¶

🧪 Testing¶

📋 Configuration Priority¶

Example Flow¶

🐛 Debugging Tips¶

🔗 Useful Links¶

📊 Version Comparison¶

💡 Tips & Best Practices¶

🆕 New in v0.3.0¶

Target Deletion¶

Find Untagged Targets¶

Audit Trail Status and Start¶

Move Targets Between Compartments¶

Update Target Connectors¶

Get Detailed Target Info¶

🆕 New in v0.3.1¶

Export Targets¶

Register New Targets¶

New in v0.3.2¶

Wait State (`--wait-state STATE`)¶

Target Name Regex Filter (`-r`, `--filter`)¶

All Targets from DS_ROOT_COMP (`-A`, `--all`)¶