Saturno - Impala SQL Tools via ODBC

Saturno is a Visual Studio Code extension designed to facilitate connectivity and querying of Impala databases using ODBC. It provides a suite of tools to execute SQL queries, visualize results, and manage database interactions directly within the VS Code environment.

Features

• Impala Connectivity: Seamlessly connect to Impala databases using an ODBC Data Source Name (DSN), with the ability to add or remove DSNs as needed.
• Connection Management: Monitor and manage connection status via a status bar indicator, with manual connect and disconnect options.
• SQL Execution: Execute entire .sql files or individual SQL queries with highlighted code execution.
• SQL Explain Queries: Execute EXPLAIN queries on SQL statements without manually typing the EXPLAIN keyword, providing query execution plan analysis.
• Result Visualization: View query results in an interactive, sortable table powered by DataTables with features including column sorting, search filtering, pagination, and copy-to-clipboard functionality for individual cells or entire datasets.
• CSV Export: Export query results from individual queries to CSV format.
• Query History: Access a reverse chronological list of executed queries with the ability to copy them to the clipboard.
• Database Explorer: Browse Impala databases, tables, and fields in a tree view, with options to copy table names and column lists to avoid using SELECT *.
• Quick Table Search: Search button on each database/zone that opens an interactive quick pick to instantly find and navigate to tables, with options to reveal them expanded in the tree view.
• Parameterized Queries: Define and manage parameters in a dedicated view, using them in queries with {param} syntax for dynamic SQL execution.
• SQL Bad Practices Validation: Automatically or manually validate SQL queries against a set of bad practices to ensure code quality and performance standards.
• File Logging System: Comprehensive logging system that writes all query executions, connections, and errors to timestamped log files with configurable directory and enable/disable options.
• Snippets: Includes a collection of SQL snippets for common Impala commands, such as CREATE, INSERT, SELECT, and more, to speed up development.
• AI Chat Assistant: Interactive conversational assistant with natural language understanding for help with queries, connections, snippets, and general Saturno functionality.
• Keyboard Shortcuts: Provides convenient keyboard shortcuts for quick access to commands, enhancing productivity.

Requirements

• An installed ODBC driver for Impala compatible with your system.
• A properly configured ODBC Data Source Name (DSN) for your Impala database connection.
• Visual Studio Code version 1.87.0 or higher.

Installation

1. Install the extension from the Visual Studio Code Marketplace.
2. Configure the ODBC DSN in the VS Code settings (see Configuration below).

Configuration

Saturno can be configured through VS Code settings:

• saturno.dsn: Specifies the ODBC DSN used to connect to Impala.

  • Type: String
  • Default: "impala-prod"
  • Description: The DSN configured in your ODBC driver for Impala connectivity.

• saturno.validateSqlBadPractices: Enables automatic validation of SQL queries against bad practices.

  • Type: Boolean
  • Default: true
  • Description: When enabled, automatically validates queries before execution.

• saturno.useTableView: Selects the table view type for query results.

  • Type: String (enum: "DataTable", "CustomTable")
  • Default: "DataTable"
  • Description: Choose between DataTable (feature-rich with sorting and filtering) or CustomTable (experimental).

• saturno.logDirectory: Directory path for storing query execution logs.

  • Type: String
  • Default: "C:/Temp/Saturno_logs"
  • Description: Location where log files will be saved. Each session creates a timestamped log file (e.g., saturno_2025-10-15_14-30-45-123.log).

• saturno.enableFileLogging: Enables saving logs to files in addition to OUTPUT panel.

  • Type: Boolean
  • Default: true
  • Description: When enabled, all query executions and events are logged to files in the configured directory.

To configure:

1. Open VS Code settings (Ctrl+, or Cmd+, on macOS).
2. Search for saturno settings and adjust the values as needed.

Usage

1. Connect to Impala:

   • Click the status bar icon ($(plug) Impala: Desconectado) to establish a connection.
   • Alternatively, use Alt + . to connect.

2. Disconnect from Impala:

   • Use Alt + , to close the active connection.

3. Execute Queries:

   • Open any file in the editor.
   • Saturno: Ejecutar archivo SQL: Runs all queries in the file, separated by ;, in sequence. Use Ctrl + Shift + Enter.
   • Saturno: Ejecutar query SQL: Executes the SQL query at the cursor position and displays results in a table. Use Ctrl + Enter.
   • Saturno: Exportar query SQL a CSV: Executes the SQL query at the cursor and exports results to a CSV file. Use Alt + Enter.
   • Saturno: Explain query SQL: Shows the query execution plan for the SQL query at the cursor position. Use Ctrl + Alt + Enter.

4. Manage Parameters:

   • Open the "Saturno" view in the Activity Bar and go to the "Parameters" section.
     • Add parameters using the "+" button, edit, or delete them as needed.
     • Use parameters in your queries with the {param} syntax. Parameter names support flexible naming conventions including underscores and array-like syntax.
     • Valid parameter examples: {anio}, {param_name}, {data_2023}, {param[0]}, {user_id}, {data[1]}, {data[year]},{data[year_2023]}
     • Invalid parameter examples: {123} (cannot start with numbers), {#} (special characters not allowed), {,#} (invalid syntax), {#,#} (invalid syntax)
     • Usage example: SELECT field1, field2 FROM table WHERE year = {anio} AND user_id = {user_param}

5. Manage DSN:

   • Use Saturno: Cambiar DSN to update the DSN manually.

6. Explore Database:

   • Open the "Saturno" view in the Activity Bar:
     • Tree: Navigate through databases, tables, and fields.
       • Quick Search: Click the search icon (🔍) next to any database/zone to open an interactive table finder
       • Fields: View fields of a selected table and copy the list of fields to the clipboard.
       • Copy Table Name: Right-click on a table to copy its name.

7. Quick Table Search:

   • Click the search icon (🔍) next to any database/zone in the tree view
   • An interactive quick pick will open showing all tables in that zone
   • Search: Type to filter tables in real-time
   • Navigate: Press Enter on any table to reveal and expand it in the tree view with all its fields visible
   • Quick Actions: Use the inline buttons on each table:
     • 📋 Copy Name: Copies fully qualified table name (zone.table)
     • 📝 Copy Columns: Copies all column names from the table
     • ⋯ Actions: Opens the table actions menu (Select Top 100, Compute Stats, etc.)

8. Review Query History: - Access the "Saturno" view in the Activity Bar and navigate to the "Query History" section. - Browse through previously executed queries in reverse chronological order. - Click on any query to copy it to the clipboard for reuse.

9. Access Logs:

   • OUTPUT Panel: View real-time logs in the VS Code OUTPUT panel (select "Saturno" from the dropdown).
   • Log Files: When file logging is enabled (default), all query executions are saved to timestamped log files in the configured directory.
   • Open Log Directory: Use the command Saturno: Abrir directorio de logs to quickly access your log files folder.
   • Log Content: Each log file includes:
     • Connection events (connect/disconnect)
     • Query execution details with timestamps
     • Query results summaries (rows returned, execution time)
     • Error messages and stack traces
     • Parameter replacement information

10. SQL Bad Practices Validation

    Saturno includes built-in SQL bad practices validation to help maintain code quality and performance standards:

    • Automatic Validation: Configure validation through the saturno.validateBadPractices setting to automatically check queries against bad practices.
    • Manual Validation: Use dedicated commands to validate individual queries or entire documents on demand.

Chat Assistant

Saturno includes an intelligent AI-powered chat assistant that provides conversational help and guidance for all extension features:

How to Access

• Open the Chat view in VS Code (you may need to enable it in the Activity Bar)
• Type @saturno followed by your question or request
• The assistant will provide contextual help and suggestions

What the Assistant Can Help With

🔌 Connection Support:

• "How do I connect to Impala?"
• "Help me change my DSN configuration"
• "I'm having connection issues"

📝 SQL and Query Help:

• "Show me how to write a SELECT query"
• "Help me with JOIN syntax"
• "Generate a query for my table"

🔧 Parameter Management:

• "How do I use parameters in queries?"
• "Show me parameter syntax examples"
• "Help me set up dynamic queries"

📊 Data Export and Results:

• "How do I export results to CSV?"
• "Explain the results table features"
• "Help with large query results"

✅ SQL Validation:

• "Check my query for bad practices"
• "What are SQL best practices for Impala?"
• "Validate this query"

📝 Code Snippets:

• "What snippets are available?"
• "Show me CREATE table snippets"
• "Help me with INSERT templates"

🌳 Database Navigation:

• "How do I explore database tables?"
• "Copy table column names"
• "Navigate the database tree"

Smart Features

• Natural Language Understanding: Ask questions in plain English or Spanish
• Context-Aware Responses: Gets relevant help based on your specific situation
• Interactive Actions: Provides clickable buttons to execute commands directly
• Code Generation: Generates SQL queries and code snippets on demand
• Fallback Support: Works even when AI models are unavailable

Example Conversations

You: "I need help connecting to my database"
@saturno: I'll help you connect to Impala! First, make sure you have...

You: "Show me snippets for creating tables"
@saturno: Here are the available CREATE table snippets...

You: "¿Cómo valido mi consulta SQL?"
@saturno: Te ayudo a validar tu consulta SQL. Puedes usar...

The chat assistant makes Saturno more accessible and helps both beginners and experienced users get the most out of the extension's features.

Keyboard Shortcuts

Saturno provides the following keyboard shortcuts for quick access to its commands:

Snippets

Below is a summary table of the available SQL snippets included with Saturno:

Logs

Logs for Saturno can be found in the Output panel of Visual Studio Code. To view logs:

1. Open the Command Palette (Ctrl + Shift + P or Cmd + Shift + P on macOS).
2. Type Output: Focus on Output View and select it.
3. In the Output panel, select Saturno logs from the dropdown to view logs related to Saturno operations.

Known Issues

• Performance may degrade with extremely large datasets.
• Some advanced Impala features might not be fully supported via ODBC.
• The extension may not handle all edge cases in SQL syntax, particularly with complex queries.

Contributing

Contributions are welcome! If you find a bug or have a feature request.

Additional Resources

• Impala Documentation
• ODBC Specification

Enhance your Impala workflow with Saturno in Visual Studio Code.