Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Oracle-CLI

Python Version License: MIT GitHub Release MCP Server

πŸš€ Interactive Oracle Database Explorer with AI-powered MCP Integration

Oracle-CLI Demo

Install with pipx Add to Cursor View on GitHub

Features

✨ Interactive TUI - Modern terminal interface with full keyboard navigation
πŸ” Schema Explorer - Browse tables, packages, procedures, and functions
πŸ”„ Multi-Schema Support - Easy switching between schemas with dropdown selector
πŸ“Š Data Preview - View table structures and sample data
πŸ’Ύ SQL Editor - Execute custom SQL queries with Ctrl+E and instant results
πŸ”Ž Smart Search - Real-time filtering with Ctrl+S across all objects
⚑ Lightning Fast - Intelligent caching & prefetching for instant navigation
πŸš€ Smart Performance - Background loading & 5-minute cache for large databases
πŸ“‹ Copy to Clipboard - Export table structure & data in markdown format with Ctrl+Y
πŸ€– AI-Ready - Perfect for pasting into ChatGPT, Claude, Cursor, or any AI assistant
🎨 Syntax Highlighting - Color-coded PL/SQL source code viewer
🎨 Theme Toggle - Switch between light and dark themes via Command Palette (Ctrl+P)
⌨️ Keyboard First - Navigate everything with arrow keys, no mouse needed
πŸ”Œ No Client Required - Uses python-oracledb thin mode by default
πŸ”— MCP Server - Integrates with AI tools (Cursor, VS Code, Claude) via Model Context Protocol
πŸ”Ž Relationship Discovery - Automatically find foreign key relationships between tables
πŸ“ˆ Performance Analysis - Index analysis and optimization recommendations
πŸ”’ Constraint Mapping - Complete view of primary keys, foreign keys, unique constraints


πŸ€– Quick Start: Add to Cursor (MCP Integration)

Oracle-CLI now works as an MCP server! Let AI assistants directly access your Oracle database.

πŸ“¦ Step 1: Install Oracle-CLI

pipx install git+https://github.com/oguzhankalelioglu/oracle-cli.git

βš™οΈ Step 2: Configure Database Connection

oracle-cli configure

πŸ”Œ Step 3: Add to Cursor

Option 1: One-Click Install (Easiest!)

Add to Cursor

Click the button above β†’ Cursor will automatically add the configuration!

Option 2: Manual Configuration

Open Cursor Settings β†’ Features β†’ Model Context Protocol β†’ Add this JSON:

For macOS/Linux:

{
  "mcpServers": {
    "oracle-cli": {
      "command": "oracle-cli",
      "args": ["mcp"]
    }
  }
}

For Windows:

First, find your Python path:

where python

Then use one of these configurations:

Option A: Using Python directly (Recommended for Windows)

{
  "mcpServers": {
    "oracle-cli": {
      "command": "python",
      "args": ["-m", "oracle_cli", "mcp"]
    }
  }
}

Option B: Using full path to oracle-cli

{
  "mcpServers": {
    "oracle-cli": {
      "command": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\oracle-cli.exe",
      "args": ["mcp"]
    }
  }
}

πŸ’‘ Tip: Replace YourUsername and Python312 with your actual paths

βœ… Step 4: Restart Cursor & Test

Ask your AI assistant:

  • "List all tables in my database"
  • "Show me the structure of EMPLOYEES table"
  • "Find all customers from California"
  • "What tables are related to EMPLOYEES?" πŸ†•
  • "Show me the indexes on EMPLOYEES table" πŸ†•
  • "Search for all tables containing 'customer'" πŸ†•

That's it! πŸŽ‰ AI can now:

  • βœ… Query your Oracle database automatically
  • βœ… Discover table relationships and foreign keys
  • βœ… Analyze indexes and constraints
  • βœ… Search across your entire schema
  • βœ… Provide performance optimization tips

πŸ’‘ Works with: Cursor, VS Code, Claude Desktop, and any MCP-compatible AI tool


Installation

Prerequisites

  • Python 3.10 or higher
  • Oracle Database (tested with 11g, 12c, 18c, 19c, 21c, 23c)

Install with pipx (Recommended)

pipx install git+https://github.com/oguzhankalelioglu/oracle-cli.git

ℹ️ If the oracle-cli command is not found in a new terminal session, run pipx ensurepath, restart your terminal, and make sure ~/.local/bin is on your PATH.

Install with pip

pip install git+https://github.com/oguzhankalelioglu/oracle-cli.git

Install from source

git clone https://github.com/oguzhankalelioglu/oracle-cli.git
cd oracle-cli
pip install -e .

Updating

Update with pipx (Recommended)

pipx upgrade oracle-cli

Or reinstall from GitHub for the latest version:

pipx uninstall oracle-cli
pipx install git+https://github.com/oguzhankalelioglu/oracle-cli.git

Update with pip

pip install --upgrade git+https://github.com/oguzhankalelioglu/oracle-cli.git

Update from source

cd oracle-cli
git pull
pip install -e . --upgrade

After updating:

  • Configuration file (~/.oracle_cli/config.json) is preserved
  • Cache is automatically cleared on first run
  • Press R in TUI to clear cache and see new features

Quick Start

1. Configure Connection

Save your Oracle connection details:

oracle-cli configure

You'll be prompted for:

  • Username: Your Oracle database username
  • Password: Your database password
  • DSN: Connection string (e.g., localhost:1521/XEPDB1 or hostname:1521/ORCL)
  • Schema: Default schema to explore (defaults to username)

2. Launch TUI

oracle-cli

That's it! The interactive TUI will open.

Usage

Interactive TUI (Default)

Launch the full-featured terminal interface:

oracle-cli
# or explicitly
oracle-cli tui

Keyboard Shortcuts

Key Action
↑/↓ Arrows Navigate through objects
Tab Switch focus between panels
Ctrl+Y πŸ“‹ Copy selected object to clipboard (markdown format)
Ctrl+S Toggle search (real-time filtering)
Ctrl+P Open command palette (schema, theme, etc.)
Ctrl+Shift+P Show procedures only
Ctrl+K Show packages only
Ctrl+E Open SQL editor (execute queries)
F1 Show About/Help screen
R Refresh & clear cache
ESC Close panels/Cancel
Q Quit application

πŸ€– AI Assistant Integration

Press Ctrl+Y on any selected object to copy:

  • Tables: Complete structure + sample data in markdown tables
  • PL/SQL Objects: Full source code in code blocks

Perfect for:

  • Asking AI to explain table structures
  • Getting AI help with PL/SQL code
  • Generating queries based on table schema
  • Database documentation

Example workflow:

  1. Open oracle-cli in your terminal
  2. Navigate to a table using ↑/↓ arrows
  3. Press Ctrl+Y to copy
  4. Paste into ChatGPT/Claude/Cursor and ask: "Explain this table structure"

⚑ Command Palette

Press Ctrl+P to open the command palette for quick actions:

  • Change Schema: Switch between database schemas
  • Change Theme: Toggle between light and dark themes
  • SQL Editor: Open SQL query editor
  • Refresh: Clear cache and reload objects
  • About: Show help and keyboard shortcuts

Command Line Interface

You can also use oracle-cli as a traditional CLI tool:

# List all tables
oracle-cli list-tables

# Describe table structure
oracle-cli describe-table EMPLOYEES

# Preview table data
oracle-cli preview-table EMPLOYEES --limit 10

# List packages
oracle-cli list-packages --with-body

# List procedures
oracle-cli list-programs --type procedure

# Show PL/SQL source code
oracle-cli show-source MY_PACKAGE --type package

# Show package body
oracle-cli show-source MY_PACKAGE --type package --body

# Switch schema
oracle-cli use-schema HR

Connection Options

Using Environment Variables

export ORACLE_USER=hr
export ORACLE_PASSWORD='your_password'
export ORACLE_DSN='localhost:1521/XEPDB1'
export ORACLE_SCHEMA='HR'  # Optional

oracle-cli

Using Command Line Options

oracle-cli --user hr --password secret --dsn localhost:1521/XEPDB1 --schema HR

Configuration

Connection details are stored in ~/.oracle_cli/config.json. You can:

  • Update configuration: oracle-cli configure
  • Use custom path: oracle-cli configure --path /custom/path/config.json

Note: Configuration file may contain sensitive information. Never commit it to version control.

Performance

Oracle-CLI is optimized for large databases with thousands of tables:

πŸš€ Smart Caching System

  • Intelligent Cache: Table structures and data are cached for 5 minutes
  • Instant Navigation: Second visit to a table is instant (from cache)
  • Auto-Refresh: Press R to clear cache and reload
  • Schema-Aware: Changing schemas automatically clears cache

⚑ Background Prefetching

  • Predictive Loading: Next 2-3 tables are loaded in background
  • Seamless Experience: By the time you navigate, data is ready
  • Smart Queue: Only prefetches items you're likely to visit

πŸ“Š Performance Tips

# For very large databases (10,000+ tables)
oracle-cli tui --limit 20  # Reduce data preview rows

# Enable debug mode to see cache hits
oracle-cli tui --debug

# Check cache statistics
# Open TUI, press F1 (About) - shows cache count

Performance Improvements:

  • βœ… First table load: ~200-500ms
  • βœ… Cached table load: <50ms (4-10x faster!)
  • βœ… Prefetched table: Instant (already loaded)

Oracle Client

By default, python-oracledb runs in thin mode (no Oracle Client required).

If your organization requires Oracle Instant Client:

  1. Install Oracle Instant Client
  2. Set the ORACLE_CLIENT_LIB_DIR environment variable
  3. The tool will automatically use thick mode

Development

Setup Development Environment

# Clone repository
git clone https://github.com/oguzhankalelioglu/oracle-cli.git
cd oracle-cli

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

Project Structure

oracle-cli/
β”œβ”€β”€ oracle_cli/
β”‚   β”œβ”€β”€ __init__.py
β”‚   β”œβ”€β”€ __main__.py
β”‚   β”œβ”€β”€ cli.py          # CLI commands
β”‚   β”œβ”€β”€ config.py       # Configuration management
β”‚   β”œβ”€β”€ db.py           # Database operations
β”‚   └── tui.py          # Text User Interface
β”œβ”€β”€ pyproject.toml      # Project metadata
β”œβ”€β”€ README.md
β”œβ”€β”€ LICENSE
└── INSTALL.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Oğuzhan Kalelioğlu

Acknowledgments

πŸ”§ Advanced MCP Configuration

Available MCP Tools

  • βœ… 13 Powerful Tools: List tables, describe structures, query data, analyze relationships
  • πŸ”’ Secure: SELECT-only queries, local stdio access
  • ⚑ Fast: Uses existing caching system
  • 🎯 Smart: AI automatically selects the right tools
  • πŸ”— Relational: Discover table relationships and dependencies
  • πŸ“Š Analytical: Index analysis, constraint mapping, performance insights

MCP Tools Reference

πŸ“Š Basic Information (4 tools)

Tool Description
list_tables List all tables in the schema
describe_table View detailed table structure (columns, types, constraints)
query_table Get sample data from a table
get_table_stats Get table statistics (row count, size, segments)

πŸ”— Relationship Analysis (4 tools)

Tool Description
get_table_relationships View foreign key relationships (parent & child tables)
get_table_constraints Show all constraints (PRIMARY KEY, FOREIGN KEY, UNIQUE, CHECK)
get_related_tables Find all related tables through foreign key relationships
get_table_indexes List all indexes with performance insights

πŸ” Search & Discovery (1 tool)

Tool Description
search_tables Search tables and columns by keyword across schema

πŸ› οΈ Advanced Tools (4 tools)

Tool Description
execute_sql Run custom SELECT queries (read-only)
get_table_triggers List table triggers with event details
list_objects List PL/SQL packages, procedures, functions
get_source View PL/SQL source code

For detailed setup and troubleshooting: MCP_SETUP.md

Roadmap

  • Copy to clipboard (markdown format) βœ…
  • Full keyboard navigation βœ…
  • MCP Server Integration βœ…
  • Table relationships viewer βœ…
  • Index and constraint viewer βœ…
  • Advanced schema analysis βœ…
  • SQL Editor with real-time execution βœ…
  • Multi-schema switching βœ…
  • Search and filtering βœ…
  • Theme toggle (light/dark) βœ…
  • Command Palette βœ…
  • Export data to CSV/JSON
  • Save and load SQL queries
  • Query history
  • Support for database diagrams
  • Multi-connection management
  • Plugin system
  • ER diagram visualization
  • Performance monitoring dashboard

Support

If you encounter any issues or have questions:


Note: This tool is designed for development and database exploration. Always follow your organization's security policies when connecting to production databases.

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages