CLI Integration Examples
Relevant source files
The following files were used as context for generating this wiki page:
The CLI integration for FLEXT DB Oracle provides a robust command-line interface for performing enterprise Oracle database operations. It serves as the application layer gateway, allowing developers and administrators to execute queries, manage plugins, check database health, and inspect schemas without writing custom Python code.
The CLI is built upon Clean Architecture principles, separating the interface logic in flext_db_oracle/cli.py from the core domain and infrastructure layers. It integrates deeply with the flext-cli ecosystem to provide standardized command patterns and output formatting.
Sources: src/README.md:16-17, src/README.md:43-58, pyproject.toml:23-28
Core CLI Commands
The flext-oracle entry point exposes several functional commands for database interaction. These commands leverage environment variables for configuration and provide both simple and debug output modes.
| Command | Description | Example Usage |
|---|---|---|
connect-env | Validates connection using environment variables | flext-oracle connect-env --debug |
schemas | Lists all available database schemas | flext-oracle schemas |
tables | Lists all tables within a schema | flext-oracle tables --schema NAME |
query | Executes a raw SQL query | flext-oracle query --sql "SELECT ..." |
health | Performs a database connectivity health check | flext-oracle health |
plugins | Manages and lists Oracle-specific plugins | flext-oracle plugins |
optimize | Analyzes and optimizes a provided SQL string | flext-oracle optimize --sql "..." |
Sources: examples/06_cli.py:27-77, tests/e2e/README.md:73-90
CLI Execution Flow
The following diagram illustrates the typical workflow of a CLI command from user input to database response.
The CLI verifies required environment variables (Host, Username, Password) before initializing the API and executing the requested operation.
Sources: examples/06_cli.py:80-112, tests/unit/test_cli.py:59-70
Environment Configuration
The CLI relies on specific environment variables for connection parameters and operational behavior. This allows for seamless integration into CI/CD pipelines and automated environments.
Required Connection Variables
FLEXT_TARGET_ORACLE_HOST: The database server hostname.FLEXT_TARGET_ORACLE_PORT: The listener port (defaults to 1521).FLEXT_TARGET_ORACLE_SERVICE_NAME: The Oracle service name (e.g., XEPDB1).FLEXT_TARGET_ORACLE_USERNAME: Database user credentials.FLEXT_TARGET_ORACLE_PASSWORD: Database user password.
Optional Operational Variables
FLEXT_CLI_DEV_MODE: Enables verbose error reporting and debug logs.FLEXT_CLI_LOG_LEVEL: Sets the logging verbosity (e.g.,debug,info).FLEXT_TARGET_ORACLE_POOL_MAX: Configures maximum connection pool size.
Sources: examples/06_cli.py:127-138, tests/e2e/README.md:52-62
Programmatic CLI Execution
The library provides utilities to run CLI commands programmatically for testing or automation purposes. The u.Cli.run_raw utility is used to execute commands and capture stdout, stderr, and exit codes.
def run_cli_command(cmd: t.StrSequence) -> tuple[int, str, str]:
"""Run CLI command and return exit code, stdout, stderr."""
result = u.Cli.run_raw(cmd, timeout=30)
if result.success:
process = result.value
return (process.exit_code, process.stdout, process.stderr)
return (1, "", result.error or "Command failed")
Sources: examples/06_cli.py:101-119
User Preferences and Client State
The FlextDbOracleClient manages user preferences and connection state. Preferences include output formats (table, json, csv) and query limits.
The client maintains internal state for user_preferences, including a default query_limit of 1000 and default_output_format set to "table".
Sources: tests/unit/test_cli.py:32-57, tests/unit/test_cli.py:173-183
Summary
CLI Integration in FLEXT DB Oracle provides a standardized interface for interacting with Oracle databases. By utilizing the FlextDbOracleClient and the flext-oracle command-point, users can perform complex schema inspections and query optimizations through a consistent environment-driven configuration model. This integration ensures that Oracle operations remain accessible and automatable within the broader FLEXT ecosystem.
Sources: src/README.md:88-95, tests/e2e/README.md:13-22