query_console 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5f57530c0dcf15456265758600392d0eeff17ba08cfff9f879d0afa31a1ab7e3
+  data.tar.gz: 12952c2bac1d22594a51e06d7c44e892b8e9955381091c22eb696ce08f7a8668
+SHA512:
+  metadata.gz: c2c2c54e0c044763180321438121c11b66a5cabd8ebc6a1afe53eea8f58b22675424647b3c5b2bde568aeac62e4de5bfa2dcc2f1f32606f5a1a50eeb3960519f
+  data.tar.gz: 28d136f7b2c95ae7aeb551c07bf38bc8a861ff434885a75cbf805773935d4b3df8df57f2a165f9aca7e5ee23169822e635cd23b884d998626a1a7d654c012b57

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johnson Gnanasekar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,382 @@
+# QueryConsole
+
+A Rails engine that provides a secure, mountable web interface for running read-only SQL queries against your application's database.
+
+## Features
+
+- 🔒 **Security First**: Read-only queries enforced at multiple levels
+- 🚦 **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
+
+## Security Features
+
+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
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'query_console'
+```
+
+And then execute:
+
+```bash
+bundle install
+rails generate query_console:install
+```
+
+**Requirements:**
+- Ruby 3.1+
+- Rails 7.0+
+- Works with Rails 8+
+- Hotwire (Turbo Rails + Stimulus) - automatically included
+
+## Configuration
+
+The generator creates `config/initializers/query_console.rb`. You **MUST** configure the authorization hook:
+
+```ruby
+QueryConsole.configure do |config|
+  # Required: Set up authorization
+  config.authorize = ->(controller) {
+    controller.current_user&.admin?
+  }
+
+  # Track who runs queries
+  config.current_actor = ->(controller) {
+    controller.current_user&.email || "anonymous"
+  }
+
+  # Optional: Enable in additional environments (use with caution!)
+  # config.enabled_environments = %w[development staging]
+
+  # Optional: Adjust limits
+  # config.max_rows = 1000
+  # config.timeout_ms = 5000
+end
+```
+
+### Authorization Examples
+
+#### With Devise
+
+```ruby
+config.authorize = ->(controller) {
+  controller.current_user&.admin?
+}
+```
+
+#### With HTTP Basic Auth
+
+```ruby
+config.authorize = ->(controller) {
+  controller.authenticate_or_request_with_http_basic do |username, password|
+    username == "admin" && password == Rails.application.credentials.query_console_password
+  end
+}
+```
+
+#### For Development (NOT for production!)
+
+```ruby
+config.authorize = ->(_controller) { true }
+```
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled_environments` | `["development"]` | Environments where console is accessible |
+| `authorize` | `nil` | Lambda/proc that receives controller and returns true/false |
+| `current_actor` | `->(_) { "unknown" }` | Lambda/proc to identify who's running queries |
+| `max_rows` | `500` | Maximum rows returned per query |
+| `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 |
+
+## Mounting
+
+Add to your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount QueryConsole::Engine, at: "/query_console"
+end
+```
+
+Then visit: `http://localhost:3000/query_console`
+
+## Usage
+
+### Running Queries
+
+1. Enter your SELECT query in the editor
+2. Click "Run Query" or press Ctrl/Cmd+Enter
+3. View results in the table below
+4. Query is automatically saved to history
+
+### Query History
+
+- Stored locally in your browser (not on server)
+- Click any history item to load it into the editor
+- Stores up to 20 recent queries
+- Clear history with the "Clear" button
+
+### Allowed Queries
+
+✅ **Allowed**:
+- `SELECT * FROM users`
+- `SELECT id, name FROM users WHERE active = true`
+- `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)
+- Any query containing forbidden keywords
+
+## Example Queries
+
+```sql
+-- List recent users
+SELECT id, email, created_at 
+FROM users 
+ORDER BY created_at DESC 
+LIMIT 10;
+
+-- Count by status
+SELECT status, COUNT(*) as count 
+FROM orders 
+GROUP BY status;
+
+-- Join with aggregation
+SELECT u.email, COUNT(o.id) as order_count
+FROM users u
+LEFT JOIN orders o ON u.id = o.user_id
+GROUP BY u.id, u.email
+ORDER BY order_count DESC
+LIMIT 20;
+
+-- Common Table Expression (CTE)
+WITH active_users AS (
+  SELECT * FROM users WHERE active = true
+)
+SELECT * FROM active_users WHERE created_at > DATE('now', '-30 days');
+```
+
+## Security Considerations
+
+### Environment Configuration
+
+⚠️ **Important**: QueryConsole is **disabled by default in production**. To enable in non-development environments:
+
+```ruby
+config.enabled_environments = %w[development staging]
+```
+
+**Never enable in production without**:
+1. Strong authentication
+2. Network restrictions (VPN, IP whitelist)
+3. Audit monitoring
+4. Database read-only user (recommended)
+
+### Authorization
+
+The authorization hook is called on **every request**. Ensure it:
+- Returns `false` or `nil` to deny access
+- Is performant (avoid N+1 queries)
+- Handles edge cases (logged out users, etc.)
+
+### Audit Logs
+
+All queries are logged to `Rails.logger.info` with:
+
+```ruby
+{
+  component: "query_console",
+  actor: "user@example.com",
+  sql: "SELECT * FROM users LIMIT 10",
+  duration_ms: 45.2,
+  rows: 10,
+  status: "ok",  # or "error"
+  truncated: false
+}
+```
+
+Monitor these logs for:
+- Unusual query patterns
+- Unauthorized access attempts
+- Performance issues
+- Data access patterns
+
+### Database Permissions
+
+For production environments, consider using a dedicated read-only database user:
+
+```ruby
+# config/database.yml
+production_readonly:
+  <<: *production
+  username: readonly_user
+  password: <%= ENV['READONLY_DB_PASSWORD'] %>
+
+# In your initializer
+QueryConsole.configure do |config|
+  config.database_config = :production_readonly
+end
+```
+
+## Development
+
+### Testing Without a Rails App
+
+You can test the gem in isolation without needing a full Rails application:
+
+**Option 1: Run automated tests**
+```bash
+cd query_console
+bundle install
+bundle exec rspec
+```
+
+**Option 2: Start the test server**
+```bash
+cd query_console
+bundle install
+./bin/test_server
+```
+
+Then visit: http://localhost:9292/query_console
+
+The test server includes sample data and is pre-configured for easy testing.
+
+**See [TESTING.md](TESTING.md) for detailed testing instructions.**
+
+### Test Coverage
+
+The test suite includes:
+- SQL validator specs (security rules)
+- SQL limiter specs (result limiting)
+- Runner specs (integration tests)
+- Controller specs (authorization & routing)
+
+## Frontend Technology Stack
+
+QueryConsole uses **Hotwire (Turbo + Stimulus)**, the modern Rails-native frontend framework:
+
+### What's Included
+
+- **Turbo Frames**: Query results update without page reloads (SPA-like experience)
+- **Stimulus Controllers**: Organized JavaScript for collapsible sections, history, and editor
+- **CDN Delivery**: Hotwire loaded from CDN (no asset compilation needed)
+- **Zero Build Step**: No webpack, esbuild, or other bundlers required
+
+### Architecture
+
+```
+Frontend Stack
+├── HTML: ERB Templates
+├── CSS: Vanilla CSS (inline)
+├── JavaScript: 
+│   ├── Turbo Frames (results updates)
+│   └── Stimulus Controllers
+│       ├── collapsible_controller (section toggling)
+│       ├── history_controller (localStorage management)
+│       └── editor_controller (query execution)
+└── Storage: localStorage API
+```
+
+### Benefits
+
+✅ **No Build Step**: Works out of the box, no compilation needed  
+✅ **Rails-Native**: Standard Rails 7+ approach  
+✅ **Lightweight**: ~50KB total (vs React's 200KB+)  
+✅ **Fast**: No page reloads, instant interactions  
+✅ **Progressive**: Degrades gracefully without JavaScript  
+
+### Why Hotwire?
+
+1. **Rails Standard**: Default frontend stack for Rails 7+
+2. **Simple**: Fewer moving parts than SPA frameworks
+3. **Productive**: Write less JavaScript, more HTML
+4. **Modern**: All the benefits of SPAs without the complexity
+5. **Maintainable**: Standard Rails patterns throughout
+
+## Troubleshooting
+
+### Console returns 404
+
+**Possible causes**:
+1. Environment not in `enabled_environments`
+2. Authorization hook returns `false`
+3. Authorization hook not configured (defaults to deny)
+
+**Solution**: Check your initializer configuration.
+
+### Query times out
+
+**Causes**:
+- Query is too complex
+- Database is slow
+- Timeout setting too aggressive
+
+**Solutions**:
+- Increase `timeout_ms`
+- Optimize query
+- Add indexes to database
+
+### "Multiple statements" error
+
+**Cause**: Query contains semicolon (`;`) in the middle
+
+**Solution**: Remove extra semicolons. Only one trailing semicolon is allowed.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Write tests for your changes
+4. Ensure tests pass (`bundle exec rspec`)
+5. Commit your changes (`git commit -am 'Add feature'`)
+6. Push to the branch (`git push origin feature/my-feature`)
+7. Create a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](MIT-LICENSE).
+
+## Credits
+
+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

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/controllers/query_console/application_controller.rb

@@ -0,0 +1,38 @@
+module QueryConsole
+  class ApplicationController < ActionController::Base
+    # Rails 8 CSRF protection - use null_session for Turbo Frame requests
+    protect_from_forgery with: :exception, prepend: true
+    
+    # Skip CSRF for Turbo Frame requests (Turbo handles it via meta tags)
+    skip_forgery_protection if: -> { request.headers['Turbo-Frame'].present? }
+
+    before_action :ensure_enabled!
+    before_action :authorize_access!
+
+    private
+
+    def ensure_enabled!
+      config = QueryConsole.configuration
+      
+      unless config.enabled_environments.map(&:to_s).include?(Rails.env.to_s)
+        raise ActionController::RoutingError, "Not Found"
+      end
+    end
+
+    def authorize_access!
+      config = QueryConsole.configuration
+      
+      # 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"
+      end
+
+      # Call the authorization hook
+      unless config.authorize.call(self)
+        Rails.logger.warn("[QueryConsole] Access denied by authorization hook")
+        raise ActionController::RoutingError, "Not Found"
+      end
+    end
+  end
+end

data/app/controllers/query_console/queries_controller.rb

@@ -0,0 +1,43 @@
+module QueryConsole
+  class QueriesController < ApplicationController
+    def new
+      # Render the main query editor page
+    end
+
+    def run
+      sql = params[:sql]
+
+      if sql.blank?
+        @result = Runner::QueryResult.new(error: "Query cannot be empty")
+        respond_to do |format|
+          format.turbo_stream { render turbo_stream: turbo_stream.replace("query-results", partial: "results", locals: { result: @result }) }
+          format.html { render :_results, layout: false }
+        end
+        return
+      end
+
+      # Execute the query
+      runner = Runner.new(sql)
+      @result = runner.execute
+
+      # Log the query execution
+      AuditLogger.log_query(
+        sql: 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(
+            "query-results",
+            partial: "results",
+            locals: { result: @result }
+          )
+        end
+        format.html { render :_results, layout: false }
+      end
+    end
+  end
+end

data/app/javascript/query_console/application.js

@@ -0,0 +1,20 @@
+// Entry point for the QueryConsole Stimulus application
+import { Application } from "@hotwired/stimulus"
+import { registerControllers } from "@hotwired/stimulus-loading"
+
+const application = Application.start()
+
+// Configure Stimulus development experience
+application.debug = false
+window.Stimulus = application
+
+// Register all controllers in the controllers/query_console directory
+import CollapsibleController from "./controllers/collapsible_controller"
+import HistoryController from "./controllers/history_controller"
+import EditorController from "./controllers/editor_controller"
+
+application.register("collapsible", CollapsibleController)
+application.register("history", HistoryController)
+application.register("editor", EditorController)
+
+export { application }

data/app/javascript/query_console/controllers/collapsible_controller.js

@@ -0,0 +1,42 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Handles collapsible sections (banner, editor, history)
+// Usage: <div data-controller="collapsible" data-collapsible-key-value="banner">
+export default class extends Controller {
+  static values = {
+    key: String  // Storage key suffix (e.g., "banner", "editor", "history")
+  }
+
+  connect() {
+    this.storageKey = `query_console.${this.keyValue}_collapsed`
+    this.loadState()
+  }
+
+  toggle(event) {
+    event.preventDefault()
+    this.element.classList.toggle('collapsed')
+    
+    const isCollapsed = this.element.classList.contains('collapsed')
+    this.saveState(isCollapsed)
+    this.updateToggleButton(event.target, isCollapsed)
+  }
+
+  loadState() {
+    const isCollapsed = localStorage.getItem(this.storageKey) === 'true'
+    if (isCollapsed) {
+      this.element.classList.add('collapsed')
+      const button = this.element.querySelector('.section-toggle, .banner-toggle')
+      if (button) {
+        this.updateToggleButton(button, true)
+      }
+    }
+  }
+
+  saveState(isCollapsed) {
+    localStorage.setItem(this.storageKey, isCollapsed ? 'true' : 'false')
+  }
+
+  updateToggleButton(button, isCollapsed) {
+    button.textContent = isCollapsed ? '▲' : '▼'
+  }
+}

data/app/javascript/query_console/controllers/editor_controller.js

@@ -0,0 +1,77 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Manages the SQL editor textarea and query execution
+// Usage: <div data-controller="editor">
+export default class extends Controller {
+  static targets = ["textarea", "runButton", "clearButton", "results"]
+
+  connect() {
+    // Listen for history load events
+    this.element.addEventListener('history:load', (event) => {
+      this.loadQuery(event.detail.sql)
+    })
+  }
+
+  // Load query into textarea (from history)
+  loadQuery(sql) {
+    this.textareaTarget.value = sql
+    this.textareaTarget.focus()
+    
+    // Scroll to editor
+    this.element.scrollIntoView({ behavior: 'smooth', block: 'start' })
+  }
+
+  // Clear textarea
+  clear(event) {
+    event.preventDefault()
+    this.textareaTarget.value = ''
+    this.textareaTarget.focus()
+  }
+
+  // Handle form submission
+  submit(event) {
+    const sql = this.textareaTarget.value.trim()
+    
+    if (!sql) {
+      event.preventDefault()
+      alert('Please enter a SQL query')
+      return
+    }
+
+    // Show loading state
+    this.runButtonTarget.disabled = true
+    this.runButtonTarget.textContent = 'Running...'
+    
+    // After Turbo completes the request, we'll handle success/error
+  }
+
+  // Called after successful query execution (via Turbo)
+  querySuccess(event) {
+    // Re-enable button
+    this.runButtonTarget.disabled = false
+    this.runButtonTarget.textContent = 'Run Query'
+    
+    // Dispatch event to add to history
+    const sql = this.textareaTarget.value.trim()
+    this.dispatch('executed', { 
+      detail: { 
+        sql: sql,
+        timestamp: new Date().toISOString()
+      },
+      target: document.querySelector('[data-controller="history"]')
+    })
+  }
+
+  // Called after failed query execution
+  queryError(event) {
+    this.runButtonTarget.disabled = false
+    this.runButtonTarget.textContent = 'Run Query'
+  }
+
+  // Handle Turbo Frame errors
+  turboFrameError(event) {
+    console.error('Turbo Frame error:', event.detail)
+    this.runButtonTarget.disabled = false
+    this.runButtonTarget.textContent = 'Run Query'
+  }
+}