sqlite_dashboard 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 869bae55994f425455d02e3798d598d4d346a4d6bfa90f11898e0b4a1c36320f
+  data.tar.gz: 030f4f2c91332a9ef73e65eb5a06be94f38c7063c65cf17b538680b1c72b155f
+SHA512:
+  metadata.gz: a067bb74a549a6a34c9779ec167a7670c47505b76af208dfd7e2be02564d68bb9e0edda43ddab7c1b16e9ac43d13080d1f62045fee71d1cf1667fa79f00fd382
+  data.tar.gz: 2bfb94bd33407f7f22503934b532fa93f263f40f40ca5ae2dbb1acfcd25e2e1e6b0dc6bc2aa84448e64fa38498b4bdf5bef03b6e8938f72fc3b12ca11849383e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SQLite Dashboard Contributors
+
+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,361 @@
+# SQLite Dashboard
+
+[![Gem Version](https://badge.fury.io/rb/sqlite_dashboard.svg)](https://badge.fury.io/rb/sqlite_dashboard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A beautiful, feature-rich SQLite database browser and query interface for Rails applications. Mount it as an engine in your Rails app to inspect and query your SQLite databases through a clean, modern interface.
+
+![SQLite Dashboard Screenshot](https://via.placeholder.com/800x400)
+
+## Features
+
+- 🎨 **Modern UI** with Bootstrap 5 and responsive design
+- 🔍 **Multiple Database Support** - Configure and switch between multiple SQLite databases
+- ✨ **SQL Syntax Highlighting** - CodeMirror editor with SQL syntax highlighting and autocomplete
+- 📊 **Interactive Query Results** - Paginated, sortable results with horizontal scrolling
+- 🎯 **Quick Table Browse** - Click any table name to instantly query it
+- ⚡ **Fast & Lightweight** - No build tools required, works with Rails importmap
+- 🔐 **Safe for Development** - Read-only access to prevent accidental data modification
+- ⌨️ **Keyboard Shortcuts** - `Ctrl/Cmd + Enter` to execute queries
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sqlite_dashboard'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Configuration
+
+### Step 1: Mount the Engine
+
+In your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount SqliteDashboard::Engine => "/sqlite_dashboard"
+
+  # Your other routes...
+end
+```
+
+### Step 2: Configure Databases
+
+Create an initializer `config/initializers/sqlite_dashboard.rb`:
+
+```ruby
+SqliteDashboard.configure do |config|
+  config.db_files = [
+    {
+      name: "Development",
+      path: Rails.root.join("storage", "development.sqlite3").to_s
+    },
+    {
+      name: "Test",
+      path: Rails.root.join("storage", "test.sqlite3").to_s
+    }
+  ]
+
+  # Or add databases dynamically:
+  # config.add_database("Custom DB", "/path/to/database.sqlite3")
+end
+```
+
+### Step 3: Access the Dashboard
+
+Start your Rails server and navigate to:
+
+```
+http://localhost:3000/sqlite_dashboard
+```
+
+## Usage
+
+### Basic Query Execution
+
+1. Select a database from the main page
+2. Write your SQL query in the syntax-highlighted editor
+3. Press `Execute Query` or use `Ctrl/Cmd + Enter`
+4. View paginated results below
+
+### Quick Table Browse
+
+- Click any table name in the left sidebar to instantly query it
+- Tables are automatically limited to 100 rows for performance
+
+### Pagination Controls
+
+- Adjust rows per page (10, 25, 50, 100, 500)
+- Navigate through pages with First, Previous, Next, Last buttons
+- See current position (e.g., "Showing 1 to 25 of 150 rows")
+
+### Keyboard Shortcuts
+
+- `Ctrl/Cmd + Enter` - Execute current query
+- `Ctrl + Space` - Trigger SQL autocomplete
+- `Escape` - Close autocomplete suggestions
+
+## Security Considerations
+
+⚠️ **Warning**: This gem provides direct SQL access to your databases.
+
+### Recommended Security Measures:
+
+1. **Development Only** - Only mount in development environment:
+
+```ruby
+# config/routes.rb
+if Rails.env.development?
+  mount SqliteDashboard::Engine => "/sqlite_dashboard"
+end
+```
+
+2. **Authentication** - Add authentication with Devise or similar:
+
+```ruby
+# config/routes.rb
+authenticate :user, ->(user) { user.admin? } do
+  mount SqliteDashboard::Engine => "/sqlite_dashboard"
+end
+```
+
+3. **Basic Auth** - Quick protection with HTTP Basic Auth:
+
+```ruby
+# config/initializers/sqlite_dashboard.rb
+SqliteDashboard::Engine.middleware.use Rack::Auth::Basic do |username, password|
+  username == ENV['DASHBOARD_USER'] && password == ENV['DASHBOARD_PASS']
+end
+```
+
+4. **Read-Only Mode** - Configure read-only database connections:
+
+```ruby
+config.db_files = [
+  {
+    name: "Production (Read-Only)",
+    path: Rails.root.join("db/production.sqlite3").to_s,
+    readonly: true  # Coming in v2.0
+  }
+]
+```
+
+## Customization
+
+### Custom Styling
+
+Override styles by creating `app/assets/stylesheets/sqlite_dashboard_overrides.css`:
+
+```css
+.sqlite-dashboard-container {
+  /* Your custom styles */
+}
+
+.CodeMirror {
+  /* Customize editor appearance */
+  font-family: 'Fira Code', monospace;
+  font-size: 14px;
+}
+```
+
+### Configuration Options
+
+The `SqliteDashboard.configure` block accepts the following configuration options:
+
+#### `db_files`
+
+**Type:** `Array<Hash>`
+**Default:** `[]` (automatically loads from `config/database.yml` if empty)
+**Required:** No
+
+Specifies the SQLite database files to make available in the dashboard. Each database should be defined as a hash with `:name` and `:path` keys.
+
+```ruby
+SqliteDashboard.configure do |config|
+  config.db_files = [
+    {
+      name: "Development Database",
+      path: Rails.root.join("storage", "development.sqlite3").to_s
+    },
+    {
+      name: "Cache Database",
+      path: Rails.root.join("storage", "cache.sqlite3").to_s
+    },
+    {
+      name: "Custom Database",
+      path: "/absolute/path/to/database.sqlite3"
+    }
+  ]
+end
+```
+
+**Automatic Database Discovery:**
+If `db_files` is empty (default), the gem will automatically discover SQLite databases from your `config/database.yml` file for the current Rails environment. This works for both single and multiple database configurations (Rails 6+).
+
+#### `add_database` Helper Method
+
+**Type:** `Method`
+**Parameters:** `name` (String), `path` (String)
+
+A convenience method to add databases one at a time instead of assigning the entire array:
+
+```ruby
+SqliteDashboard.configure do |config|
+  config.add_database("Development", Rails.root.join("db/development.sqlite3").to_s)
+  config.add_database("Test", Rails.root.join("db/test.sqlite3").to_s)
+  config.add_database("Analytics", "/var/data/analytics.sqlite3")
+end
+```
+
+#### `allow_dml`
+
+**Type:** `Boolean`
+**Default:** `false`
+**Recommended:** `false` (read-only)
+
+Controls whether Data Manipulation Language (DML) statements are allowed. When `false`, only SELECT queries are permitted, preventing accidental data modification.
+
+```ruby
+SqliteDashboard.configure do |config|
+  # Read-only mode (recommended for production-like environments)
+  config.allow_dml = false
+
+  # Or allow write operations (USE WITH CAUTION)
+  # config.allow_dml = true
+
+  config.db_files = [
+    { name: "My Database", path: "db/production.sqlite3" }
+  ]
+end
+```
+
+**⚠️ Security Warning:** Enabling `allow_dml = true` permits INSERT, UPDATE, DELETE, and other write operations. Only enable this in trusted, development-only environments.
+
+### Complete Configuration Example
+
+```ruby
+# config/initializers/sqlite_dashboard.rb
+SqliteDashboard.configure do |config|
+  # Option 1: Explicitly define databases
+  config.db_files = [
+    {
+      name: "Primary Database",
+      path: Rails.root.join("storage", "development.sqlite3").to_s
+    },
+    {
+      name: "Background Jobs",
+      path: Rails.root.join("storage", "jobs.sqlite3").to_s
+    }
+  ]
+
+  # Option 2: Or use the helper method
+  # config.add_database("Development", Rails.root.join("db/development.sqlite3").to_s)
+  # config.add_database("Test", Rails.root.join("db/test.sqlite3").to_s)
+
+  # Option 3: Or leave empty to auto-discover from database.yml
+  # config.db_files = [] # (default)
+
+  # Security: Disable write operations (recommended)
+  config.allow_dml = false
+end
+```
+
+### Environment-Specific Configuration
+
+You can conditionally configure databases based on the Rails environment:
+
+```ruby
+SqliteDashboard.configure do |config|
+  case Rails.env
+  when 'development'
+    config.db_files = [
+      { name: "Dev DB", path: Rails.root.join("storage/development.sqlite3").to_s },
+      { name: "Test DB", path: Rails.root.join("storage/test.sqlite3").to_s }
+    ]
+    config.allow_dml = true  # Allow writes in development
+
+  when 'staging'
+    config.db_files = [
+      { name: "Staging DB (Read-Only)", path: Rails.root.join("db/staging.sqlite3").to_s }
+    ]
+    config.allow_dml = false  # Read-only in staging
+
+  when 'production'
+    # Generally not recommended to use in production
+    # But if you must, make it read-only
+    config.db_files = [
+      { name: "Production DB", path: Rails.root.join("db/production.sqlite3").to_s }
+    ]
+    config.allow_dml = false
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+To install this gem onto your local machine, run:
+
+```bash
+bundle exec rake install
+```
+
+To release a new version:
+
+1. Update the version number in `version.rb`
+2. Update the CHANGELOG.md
+3. Run `bundle exec rake release`
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/sqlite_dashboard. This project is intended to be a safe, welcoming space for collaboration.
+
+### Development Setup
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+
+## Roadmap
+
+- [x] **v1.1** - Export results to CSV/JSON
+- [ ] **v1.2** - Query history and saved queries
+- [ ] **v1.3** - Database schema visualization
+- [ ] **v2.0** - Read-only mode enforcement
+- [ ] **v2.1** - Dark mode theme
+- [ ] **v2.2** - Multi-query execution
+- [ ] **v2.3** - Query performance analytics
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Created by [Your Name](https://github.com/yourusername)
+
+Special thanks to:
+- [CodeMirror](https://codemirror.net/) for the SQL editor
+- [Bootstrap](https://getbootstrap.com/) for the UI framework
+- [Font Awesome](https://fontawesome.com/) for icons
+
+## Support
+
+- 🐛 [Report bugs](https://github.com/yourusername/sqlite_dashboard/issues)
+- 💡 [Request features](https://github.com/yourusername/sqlite_dashboard/issues)
+- 📧 [Email support](mailto:your.email@example.com)
+
+---
+
+Made with ❤️ for the Rails community

data/Rakefile

@@ -0,0 +1,60 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test
+
+desc "Run RuboCop"
+task :rubocop do
+  sh "rubocop"
+end
+
+desc "Run tests and RuboCop"
+task ci: [:test, :rubocop]
+
+desc "Generate documentation"
+task :doc do
+  sh "yard doc"
+end
+
+desc "Open documentation in browser"
+task :doc_open => :doc do
+  sh "open doc/index.html"
+end
+
+desc "Console with gem loaded"
+task :console do
+  require "irb"
+  require "sqlite_dashboard"
+  ARGV.clear
+  IRB.start
+end
+
+desc "Show gem stats"
+task :stats do
+  puts "SQLite Dashboard Gem Statistics"
+  puts "=" * 40
+
+  # Count lines of code
+  ruby_files = Dir["lib/**/*.rb", "app/**/*.rb"]
+  total_lines = ruby_files.sum { |file| File.readlines(file).count }
+  puts "Ruby files: #{ruby_files.count}"
+  puts "Lines of Ruby code: #{total_lines}"
+
+  # Count view files
+  view_files = Dir["app/**/*.erb"]
+  view_lines = view_files.sum { |file| File.readlines(file).count }
+  puts "View files: #{view_files.count}"
+  puts "Lines of template code: #{view_lines}"
+
+  # Count CSS/JS
+  asset_files = Dir["app/assets/**/*", "app/javascript/**/*"].select { |f| File.file?(f) }
+  puts "Asset files: #{asset_files.count}"
+
+  puts "Total files: #{ruby_files.count + view_files.count + asset_files.count}"
+end

data/app/controllers/sqlite_dashboard/application_controller.rb

@@ -0,0 +1,6 @@
+module SqliteDashboard
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+    layout "sqlite_dashboard/application"
+  end
+end

data/app/controllers/sqlite_dashboard/databases_controller.rb

@@ -0,0 +1,247 @@
+require 'sqlite3'
+require 'csv'
+require 'json'
+
+module SqliteDashboard
+  class DatabasesController < ApplicationController
+    before_action :set_database, only: [:show, :execute_query, :export_csv, :export_json, :tables, :table_schema]
+
+    def index
+      @databases = SqliteDashboard.configuration.databases
+    end
+
+    def show
+      @tables = fetch_tables
+    end
+
+    def execute_query
+      @query = params[:query]
+
+      Rails.logger.debug "=" * 80
+      Rails.logger.debug "Execute Query Called"
+      Rails.logger.debug "Request format: #{request.format}"
+      Rails.logger.debug "Accept header: #{request.headers['Accept']}"
+      Rails.logger.debug "Query: #{@query}"
+      Rails.logger.debug "=" * 80
+
+      begin
+        @results = execute_sql(@query)
+        Rails.logger.debug "Query executed successfully. Results: #{@results.inspect}"
+
+        respond_to do |format|
+          format.json do
+            Rails.logger.debug "Rendering JSON response"
+            render json: @results
+          end
+          format.turbo_stream do
+            Rails.logger.debug "Rendering turbo_stream response"
+            render :execute_query
+          end
+          format.html do
+            Rails.logger.debug "Falling back to HTML redirect"
+            redirect_to database_path(@database[:id])
+          end
+        end
+      rescue => e
+        @error = e.message
+        Rails.logger.error "Query execution error: #{@error}"
+
+        respond_to do |format|
+          format.json do
+            Rails.logger.debug "Rendering JSON error response"
+            render json: { error: @error }, status: :unprocessable_entity
+          end
+          format.turbo_stream { render turbo_stream: turbo_stream.replace("query-results", partial: "sqlite_dashboard/databases/error", locals: { error: @error }) }
+          format.html { redirect_to database_path(@database[:id]), alert: @error }
+        end
+      end
+    end
+
+    def tables
+      tables = fetch_tables
+      render json: tables
+    end
+
+    def table_schema
+      table_name = params[:table_name]
+      schema = fetch_table_schema(table_name)
+      render json: schema
+    end
+
+    def export_csv
+      query = params[:query]
+      separator = params[:separator] || ','
+      include_headers = params[:include_headers] == 'true'
+
+      begin
+        # Always forbid DROP and ALTER operations
+        if contains_destructive_ddl?(query)
+          render json: { error: "DROP and ALTER operations are forbidden for safety reasons." }, status: :unprocessable_entity
+          return
+        end
+
+        # Check for DML operations if allow_dml is false
+        unless SqliteDashboard.configuration.allow_dml
+          if contains_dml?(query)
+            render json: { error: "DML operations (INSERT, UPDATE, DELETE, CREATE, TRUNCATE) are not allowed." }, status: :unprocessable_entity
+            return
+          end
+        end
+
+        database_connection.results_as_hash = true
+        results = database_connection.execute(query)
+
+        if results.empty?
+          render json: { error: "No data to export" }, status: :unprocessable_entity
+          return
+        end
+
+        # Generate CSV
+        csv_data = CSV.generate(col_sep: separator) do |csv|
+          columns = results.first.keys
+          csv << columns if include_headers
+
+          results.each do |row|
+            csv << row.values
+          end
+        end
+
+        # Send as download
+        send_data csv_data,
+                  filename: "export_#{Time.now.strftime('%Y%m%d_%H%M%S')}.csv",
+                  type: 'text/csv',
+                  disposition: 'attachment'
+      rescue => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      end
+    end
+
+    def export_json
+      query = params[:query]
+      format_type = params[:format] || 'array' # 'array' or 'object'
+      pretty_print = params[:pretty_print] == 'true'
+
+      begin
+        # Always forbid DROP and ALTER operations
+        if contains_destructive_ddl?(query)
+          render json: { error: "DROP and ALTER operations are forbidden for safety reasons." }, status: :unprocessable_entity
+          return
+        end
+
+        # Check for DML operations if allow_dml is false
+        unless SqliteDashboard.configuration.allow_dml
+          if contains_dml?(query)
+            render json: { error: "DML operations (INSERT, UPDATE, DELETE, CREATE, TRUNCATE) are not allowed." }, status: :unprocessable_entity
+            return
+          end
+        end
+
+        database_connection.results_as_hash = true
+        results = database_connection.execute(query)
+
+        if results.empty?
+          render json: { error: "No data to export" }, status: :unprocessable_entity
+          return
+        end
+
+        # Generate JSON
+        json_data = if format_type == 'object'
+          # Format: { "columns": [...], "rows": [...] }
+          columns = results.first.keys
+          rows = results.map(&:values)
+          data = { columns: columns, rows: rows }
+          pretty_print ? JSON.pretty_generate(data) : data.to_json
+        else
+          # Format: array of objects
+          pretty_print ? JSON.pretty_generate(results) : results.to_json
+        end
+
+        # Send as download
+        send_data json_data,
+                  filename: "export_#{Time.now.strftime('%Y%m%d_%H%M%S')}.json",
+                  type: 'application/json',
+                  disposition: 'attachment'
+      rescue => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def set_database
+      @database = SqliteDashboard.configuration.databases.find { |db| db[:id] == params[:id].to_i }
+      redirect_to databases_path, alert: "Database not found" unless @database
+    end
+
+    def database_connection
+      @connection ||= SQLite3::Database.new(@database[:path])
+    end
+
+    def fetch_tables
+      database_connection.execute("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name").map { |row| row[0] }
+    end
+
+    def fetch_table_schema(table_name)
+      database_connection.execute("PRAGMA table_info(#{table_name})").map do |row|
+        {
+          cid: row[0],
+          name: row[1],
+          type: row[2],
+          notnull: row[3],
+          dflt_value: row[4],
+          pk: row[5]
+        }
+      end
+    end
+
+    def execute_sql(query)
+      return { error: "Query cannot be empty" } if query.blank?
+
+      # Always forbid DROP and ALTER operations
+      if contains_destructive_ddl?(query)
+        return { error: "DROP and ALTER operations are forbidden for safety reasons." }
+      end
+
+      # Check for DML operations if allow_dml is false
+      unless SqliteDashboard.configuration.allow_dml
+        if contains_dml?(query)
+          return { error: "DML operations (INSERT, UPDATE, DELETE, CREATE, TRUNCATE) are not allowed. Set allow_dml to true in configuration to enable." }
+        end
+      end
+
+      database_connection.results_as_hash = true
+      results = database_connection.execute(query)
+
+      if results.empty?
+        { columns: [], rows: [], message: "Query executed successfully with no results" }
+      else
+        columns = results.first.keys
+        rows = results.map(&:values)
+        { columns: columns, rows: rows }
+      end
+    end
+
+    def contains_destructive_ddl?(query)
+      # Remove comments and normalize whitespace
+      normalized_query = query.gsub(/--[^\n]*/, '').gsub(/\/\*.*?\*\//m, '').gsub(/\s+/, ' ').strip.upcase
+      normalized_query =~ /\b(DROP|ALTER)\s+/
+    end
+
+    def contains_dml?(query)
+      # Remove comments and normalize whitespace
+      normalized_query = query.gsub(/--[^\n]*/, '').gsub(/\/\*.*?\*\//m, '').gsub(/\s+/, ' ').strip.upcase
+
+      # Check for DML/DDL keywords (excluding DROP and ALTER which are always forbidden)
+      dml_patterns = [
+        /\bINSERT\s+INTO\b/,
+        /\bUPDATE\s+/,
+        /\bDELETE\s+FROM\b/,
+        /\bCREATE\s+/,
+        /\bTRUNCATE\s+/,
+        /\bREPLACE\s+INTO\b/
+      ]
+
+      dml_patterns.any? { |pattern| normalized_query =~ pattern }
+    end
+  end
+end