query_console 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f57530c0dcf15456265758600392d0eeff17ba08cfff9f879d0afa31a1ab7e3
-  data.tar.gz: 12952c2bac1d22594a51e06d7c44e892b8e9955381091c22eb696ce08f7a8668
+  metadata.gz: 9ea5d214eb67f13c153578fce1f001109518b6935409774d9ae343de3ee87258
+  data.tar.gz: e7f2c6c7a528ababbef441b2d548cc635222701f5903cbdd1f06b9ecbefd3bc8
 SHA512:
-  metadata.gz: c2c2c54e0c044763180321438121c11b66a5cabd8ebc6a1afe53eea8f58b22675424647b3c5b2bde568aeac62e4de5bfa2dcc2f1f32606f5a1a50eeb3960519f
-  data.tar.gz: 28d136f7b2c95ae7aeb551c07bf38bc8a861ff434885a75cbf805773935d4b3df8df57f2a165f9aca7e5ee23169822e635cd23b884d998626a1a7d654c012b57
+  metadata.gz: 5780f01ddfc86f3f998ea7f67b449ff312c3e4e305a6a5c454593a9aec6d691879837171d0567d2db8def6b70503d77203eecf708e4878947463b9f0443ba5eb
+  data.tar.gz: 99f44e0e10f2c06cb428936bfeaf8757bef817353d535ef1088761c6df7ea6a546905ce12c076207a5252103ce7df37a487ff56846a7e89d92c9e37e376de813

data/README.md

@@ -1,18 +1,76 @@
 # QueryConsole
 
-A Rails engine that provides a secure, mountable web interface for running read-only SQL queries against your application's database.
+[![Gem Version](https://badge.fury.io/rb/query_console.svg)](https://badge.fury.io/rb/query_console)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](MIT-LICENSE)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg)](https://www.ruby-lang.org)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%207.0-red.svg)](https://rubyonrails.org)
+
+A Rails engine that provides a secure, mountable web interface for running SQL queries against your application's database. Read-only by default with optional DML support.
+
+![Query Console Interface](docs/images/query-execution.png)
+*Modern, responsive SQL query interface with schema explorer, query management, and real-time execution*
+
+## Table of Contents
+
+- [Features](#features)
+- [Screenshots](#screenshots)
+- [Security Features](#security-features)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Security Considerations](#security-considerations)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
 
 ## Features
 
-- 🔒 **Security First**: Read-only queries enforced at multiple levels
+### Security & Control
+- 🔒 **Security First**: Read-only by default with multi-layer enforcement
 - 🚦 **Environment Gating**: Disabled by default in production
 - 🔑 **Flexible Authorization**: Integrate with your existing auth system
-- 📊 **Modern UI**: Clean, responsive interface with query history
-- 📝 **Audit Logging**: All queries logged with actor information
 - ⚡ **Resource Protection**: Configurable row limits and query timeouts
-- 💾 **Client-Side History**: Query history stored in browser localStorage
-- ⚡ **Hotwire-Powered**: Uses Turbo Frames and Stimulus for smooth, SPA-like experience
-- 🎨 **Zero Build Step**: CDN-hosted Hotwire, no asset compilation needed
+- 📝 **Comprehensive Audit Logging**: All queries logged with actor information and metadata
+- 🔐 **Optional DML Support**: Enable INSERT/UPDATE/DELETE with confirmation dialogs
+
+### Query Execution
+- 📊 **EXPLAIN Query Plans**: Analyze query execution plans for performance debugging
+- ✅ **Smart Validation**: SQL validation with keyword blocking and statement isolation
+- 🎯 **Accurate Results**: Proper row counts for both SELECT and DML operations
+- ⏱️ **Query Timeout**: Configurable timeout to prevent long-running queries
+
+### User Interface
+- 📊 **Modern UI**: Clean, responsive interface with real-time updates
+- 🗂️ **Schema Explorer**: Browse tables, columns, types with quick actions
+- 💾 **Query Management**: Save, organize, import/export queries (client-side)
+- 📜 **Query History**: Client-side history stored in browser localStorage
+- 🎨 **Tabbed Navigation**: Switch between History, Schema, and Saved Queries seamlessly
+- 🔍 **Quick Actions**: Generate queries from schema, copy names, insert WHERE clauses
+- ⚡ **Hotwire-Powered**: Turbo Frames and Stimulus for smooth, SPA-like experience
+- 🎨 **Zero Build Step**: CDN-hosted dependencies, no asset compilation needed
+
+## Screenshots
+
+### Query Execution with Results
+![Query Execution](docs/images/query-execution.png)
+*Execute SQL queries with real-time results, execution time, and row counts displayed in a clean, scrollable table*
+
+### Schema Explorer
+![Schema Browser](docs/images/schema-explorer.png)
+*Browse database tables, columns with data types, nullable status, and quick-action buttons (Insert, WHERE, Copy Table Name)*
+
+### DML Operations with Safety Features
+![DML Results Banner](docs/images/dml-results.png)
+*DML operations show "Data Modified" banner, accurate "Rows Affected" count, and permanent change confirmation. A browser confirmation dialog appears before execution (not shown - browser native UI).*
+
+### Query History
+![Query History](docs/images/query-history.png)
+*Access recent queries with timestamps - click any query to load it into the editor instantly*
+
+### Saved Queries Management
+![Saved Queries](docs/images/saved-queries.png)
+*Save important queries with names and tags, then load, export, or import them with one click*
 
 ## Security Features
 
@@ -20,12 +78,13 @@ QueryConsole implements multiple layers of security:
 
 1. **Environment Gating**: Only enabled in configured environments (development by default)
 2. **Authorization Hook**: Requires explicit authorization configuration
-3. **SQL Validation**: Only SELECT and WITH (CTE) queries allowed
-4. **Keyword Blocking**: Blocks all write operations (UPDATE, DELETE, INSERT, DROP, etc.)
-5. **Statement Isolation**: Prevents multiple statement execution
-6. **Row Limiting**: Automatic result limiting to prevent resource exhaustion
-7. **Query Timeout**: Configurable timeout to prevent long-running queries
-8. **Audit Trail**: All queries logged with structured data
+3. **Read-Only by Default**: Only SELECT and WITH (CTE) queries allowed by default
+4. **Optional DML with Safeguards**: INSERT/UPDATE/DELETE available when explicitly enabled, with mandatory user confirmation dialogs
+5. **Keyword Blocking**: Always blocks DDL operations (DROP, ALTER, CREATE, TRUNCATE, etc.)
+6. **Statement Isolation**: Prevents multiple statement execution
+7. **Row Limiting**: Automatic result limiting to prevent resource exhaustion
+8. **Query Timeout**: Configurable timeout to prevent long-running queries
+9. **Comprehensive Audit Trail**: All queries logged with actor, query type, and execution metadata
 
 ## Installation
 
@@ -70,6 +129,17 @@ QueryConsole.configure do |config|
   # Optional: Adjust limits
   # config.max_rows = 1000
   # config.timeout_ms = 5000
+  
+  # Advanced Features
+  # EXPLAIN feature (default: enabled)
+  # config.enable_explain = true
+  # config.enable_explain_analyze = false  # Disabled by default for safety
+  
+  # Schema Explorer (default: enabled)
+  # config.schema_explorer = true
+  # config.schema_cache_seconds = 60
+  # config.schema_table_denylist = ["schema_migrations", "ar_internal_metadata"]
+  # config.schema_allowlist = []  # Optional: whitelist specific tables
 end
 ```
 
@@ -110,6 +180,93 @@ config.authorize = ->(_controller) { true }
 | `timeout_ms` | `3000` | Query timeout in milliseconds |
 | `forbidden_keywords` | See code | SQL keywords that are blocked |
 | `allowed_starts_with` | `["select", "with"]` | Allowed query starting keywords |
+| `enable_dml` | `false` | Enable DML queries (INSERT, UPDATE, DELETE) |
+| `enable_explain` | `true` | Enable EXPLAIN query plans |
+| `enable_explain_analyze` | `false` | Enable EXPLAIN ANALYZE (use with caution) |
+| `schema_explorer` | `true` | Enable schema browser |
+| `schema_cache_seconds` | `60` | Schema cache duration in seconds |
+
+### DML (Data Manipulation Language) Support
+
+By default, Query Console is **read-only**. To enable DML operations (INSERT, UPDATE, DELETE):
+
+```ruby
+QueryConsole.configure do |config|
+  config.enable_dml = true
+  
+  # Recommended: Restrict to specific environments
+  config.enabled_environments = ["development", "staging"]
+end
+```
+
+#### Important Security Notes
+
+- **DML is disabled by default** for safety
+- When enabled, INSERT, UPDATE, DELETE, and MERGE queries are permitted
+- All DML operations are logged with actor information and query type
+- No transaction support - queries auto-commit immediately
+- Consider additional application-level authorization for production use
+
+#### What's Still Blocked
+
+Even with DML enabled, these operations remain **forbidden**:
+- `DROP`, `ALTER`, `CREATE` (schema changes)
+- `TRUNCATE` (bulk deletion)
+- `GRANT`, `REVOKE` (permission changes)
+- `EXECUTE`, `EXEC` (stored procedures)
+- `TRANSACTION`, `COMMIT`, `ROLLBACK` (manual transaction control)
+- System procedures (`sp_`, `xp_`)
+
+#### UI Behavior with DML
+
+When DML is enabled and a DML query is detected:
+- **Before execution**: A confirmation dialog appears with a clear warning about permanent data modifications
+- User must explicitly confirm to proceed (can click "Cancel" to abort)
+- **After execution**: An informational banner shows: "ℹ️ Data Modified: This query has modified the database"
+- **Rows Affected** count is displayed (e.g., "3 row(s) affected") showing how many rows were inserted/updated/deleted
+- The security banner reflects DML status
+- All changes are permanent and logged
+
+#### Database Support
+
+DML operations work on all supported databases:
+- **SQLite**: INSERT, UPDATE, DELETE
+- **PostgreSQL**: INSERT, UPDATE, DELETE, MERGE (via INSERT ... ON CONFLICT)
+- **MySQL**: INSERT, UPDATE, DELETE, REPLACE
+
+#### Enhanced Audit Logging
+
+DML queries are logged with additional metadata:
+
+```ruby
+{
+  component: "query_console",
+  actor: "user@example.com",
+  sql: "UPDATE users SET active = true WHERE id = 123",
+  duration_ms: 12.5,
+  rows: 1,
+  status: "ok",
+  query_type: "UPDATE",     # NEW: Query type classification
+  is_dml: true              # NEW: DML flag
+}
+```
+
+#### Example DML Queries
+
+```sql
+-- Insert a new record
+INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com');
+
+-- Update existing records
+UPDATE users SET active = true WHERE id = 123;
+
+-- Delete specific records
+DELETE FROM sessions WHERE expires_at < NOW();
+
+-- PostgreSQL upsert
+INSERT INTO settings (key, value) VALUES ('theme', 'dark')
+ON CONFLICT (key) DO UPDATE SET value = 'dark';
+```
 
 ## Mounting
 
@@ -147,14 +304,17 @@ Then visit: `http://localhost:3000/query_console`
 - `WITH active_users AS (SELECT * FROM users WHERE active = true) SELECT * FROM active_users`
 - Queries with JOINs, ORDER BY, GROUP BY, etc.
 
-❌ **Blocked**:
-- `UPDATE users SET name = 'test'`
-- `DELETE FROM users`
-- `INSERT INTO users VALUES (...)`
-- `DROP TABLE users`
-- `SELECT * FROM users; DELETE FROM users` (multiple statements)
+❌ **Blocked** (by default):
+- `UPDATE users SET name = 'test'` (unless `enable_dml = true`)
+- `DELETE FROM users` (unless `enable_dml = true`)
+- `INSERT INTO users VALUES (...)` (unless `enable_dml = true`)
+- `DROP TABLE users` (always blocked)
+- `TRUNCATE TABLE users` (always blocked)
+- `SELECT * FROM users; DELETE FROM users` (multiple statements always blocked)
 - Any query containing forbidden keywords
 
+**Note**: With `config.enable_dml = true`, INSERT, UPDATE, DELETE, and MERGE queries become allowed.
+
 ## Example Queries
 
 ```sql
@@ -371,12 +531,28 @@ Created by [Johnson Gnanasekar](https://github.com/JohnsonGnanasekar)
 
 ## Changelog
 
-### 0.1.0 (Initial Release)
-
-- Basic query console with read-only enforcement
-- Environment gating and authorization hooks
-- SQL validation and row limiting
-- Query timeout protection
-- Client-side history with localStorage
-- Comprehensive test suite
-- Audit logging
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
+
+### Recent Updates
+
+#### Latest (DML Support)
+- ✨ **Optional DML Support**: INSERT/UPDATE/DELETE with mandatory confirmation dialogs
+- 🎯 **Accurate Row Counts**: Proper affected rows tracking for DML operations
+- 🔒 **Enhanced Security**: Pre-execution confirmation with detailed warnings
+- 📝 **Enhanced Audit Logging**: Query type classification and DML flags
+- 🗃️ **Multi-Database Support**: SQLite, PostgreSQL, MySQL compatibility
+
+#### v0.2.0 (January 2026)
+- 📊 **EXPLAIN Plans**: Query execution plan analysis
+- 🗂️ **Schema Explorer**: Interactive table/column browser with quick actions
+- 💾 **Saved Queries**: Client-side query management with import/export
+- 🎨 **Modern UI**: Tabbed navigation and collapsible sections
+- 🔍 **Quick Actions**: Generate queries from schema explorer
+
+#### v0.1.0 (Initial Release)
+- 🔒 Read-only query console with security enforcement
+- 🚦 Environment gating and authorization hooks
+- ✅ SQL validation and row limiting
+- ⏱️ Query timeout protection
+- 📜 Client-side history with localStorage
+- ✅ Comprehensive test suite and audit logging

data/app/controllers/query_console/application_controller.rb

@@ -15,7 +15,8 @@ module QueryConsole
       config = QueryConsole.configuration
       
       unless config.enabled_environments.map(&:to_s).include?(Rails.env.to_s)
-        raise ActionController::RoutingError, "Not Found"
+        render plain: "Not Found", status: :not_found
+        return false
       end
     end
 
@@ -25,13 +26,15 @@ module QueryConsole
       # Default deny if no authorize hook is configured
       if config.authorize.nil?
         Rails.logger.warn("[QueryConsole] Access denied: No authorization hook configured")
-        raise ActionController::RoutingError, "Not Found"
+        render plain: "Not Found", status: :not_found
+        return false
       end
 
       # Call the authorization hook
       unless config.authorize.call(self)
         Rails.logger.warn("[QueryConsole] Access denied by authorization hook")
-        raise ActionController::RoutingError, "Not Found"
+        render plain: "Not Found", status: :not_found
+        return false
       end
     end
   end

data/app/controllers/query_console/explain_controller.rb

@@ -0,0 +1,47 @@
+module QueryConsole
+  class ExplainController < ApplicationController
+    skip_forgery_protection only: [:create] # Allow Turbo Frame POST requests
+
+    def create
+      sql = params[:sql]
+
+      if sql.blank?
+        @result = ExplainRunner::ExplainResult.new(error: "Query cannot be empty")
+        respond_to do |format|
+          format.turbo_stream do
+        render turbo_stream: turbo_stream.replace(
+          "explain-results",
+          partial: "query_console/explain/results",
+          locals: { result: @result }
+        )
+          end
+          format.html { render "explain/_results", layout: false, locals: { result: @result } }
+        end
+        return
+      end
+
+      # Execute the EXPLAIN
+      runner = ExplainRunner.new(sql)
+      @result = runner.execute
+
+      # Log the EXPLAIN execution
+      AuditLogger.log_query(
+        sql: "EXPLAIN: #{sql}",
+        result: @result,
+        controller: self
+      )
+
+      # Respond with Turbo Stream or HTML
+      respond_to do |format|
+        format.turbo_stream do
+          render turbo_stream: turbo_stream.replace(
+            "explain-results",
+            partial: "query_console/explain/results",
+            locals: { result: @result }
+          )
+        end
+        format.html { render "query_console/explain/_results", layout: false, locals: { result: @result } }
+      end
+    end
+  end
+end

data/app/controllers/query_console/queries_controller.rb

@@ -1,5 +1,7 @@
 module QueryConsole
   class QueriesController < ApplicationController
+    skip_forgery_protection only: [:run] # Allow Turbo Frame POST requests
+    
     def new
       # Render the main query editor page
     end
@@ -19,6 +21,7 @@ module QueryConsole
       # Execute the query
       runner = Runner.new(sql)
       @result = runner.execute
+      @is_dml = @result.dml?
 
       # Log the query execution
       AuditLogger.log_query(
@@ -33,7 +36,7 @@ module QueryConsole
           render turbo_stream: turbo_stream.replace(
             "query-results",
             partial: "results",
-            locals: { result: @result }
+            locals: { result: @result, is_dml: @is_dml }
           )
         end
         format.html { render :_results, layout: false }

data/app/controllers/query_console/schema_controller.rb

@@ -0,0 +1,32 @@
+module QueryConsole
+  class SchemaController < ApplicationController
+    def tables
+      unless QueryConsole.configuration.schema_explorer
+        render json: { error: "Schema explorer is disabled" }, status: :forbidden
+        return
+      end
+
+      introspector = SchemaIntrospector.new
+      @tables = introspector.tables
+
+      render json: @tables
+    end
+
+    def show
+      unless QueryConsole.configuration.schema_explorer
+        render json: { error: "Schema explorer is disabled" }, status: :forbidden
+        return
+      end
+
+      introspector = SchemaIntrospector.new
+      @table = introspector.table_details(params[:name])
+
+      if @table.nil?
+        render json: { error: "Table not found or access denied" }, status: :not_found
+        return
+      end
+
+      render json: @table
+    end
+  end
+end