dbwatcher 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee5502341a37e588b1dcf38edd5f33fa9e0b3746f43efea7e419ec241e873150
+  data.tar.gz: 874907249da682606c7f02df3e423ba3f0b6ef8c553ff6165561ab5cb7ad0981
+SHA512:
+  metadata.gz: 8b8d78baaa87bad96ac04968238b945d162c8acc0451c678803d7defdfa46ab66fbb9d7e96ab8bc11a4f09166713f995e641bea32090c2346ab335939faa7770
+  data.tar.gz: 13dd481403397e95a74c04857718f878ebd35dc223ffa164dfaf871f6da4a9c0d02559555b25f5b575e5bab2cf265ce953902e400026647d3441c9bdd38a3e92

data/README.md

@@ -0,0 +1,282 @@
+# DBWatcher 🔍
+
+Track and visualize database changes in your Rails application for easier debugging and development.
+
+DBWatcher is a powerful Rails gem that captures, stores, and visualizes all database operations in your application. Perfect for debugging complex data flows, understanding application behavior, and optimizing database performance.
+
+## ✨ Features
+
+- **📊 Real-time Database Tracking**: Monitor all SQL operations (INSERT, UPDATE, DELETE, SELECT)
+- **🎯 Selective Tracking**: Track specific code blocks or entire requests
+- **📱 Web Dashboard**: Beautiful, responsive interface built with Alpine.js and Tailwind CSS
+- **💾 File-based Storage**: No additional database setup required
+- **🔗 URL-based Activation**: Simple `?dbwatch=true` parameter enables tracking
+- **🧹 Automatic Cleanup**: Configurable session cleanup and storage management
+- **⚡ Zero Dependencies**: Works with any Rails application without complex setup
+- **🔒 Development-focused**: Designed for development and testing environments
+
+## 🚀 Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'dbwatcher', group: :development
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+The engine will automatically mount at `/dbwatcher` in your Rails application.
+
+### Manual Route Mounting (Optional)
+
+If you need custom mounting, add to your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount Dbwatcher::Engine => "/dbwatcher" if Rails.env.development?
+  # ... your other routes
+end
+```
+
+## 📖 Usage
+
+### 🎯 Targeted Tracking
+
+Track specific code blocks with detailed context:
+
+```ruby
+Dbwatcher.track(name: "User Registration Flow") do
+  user = User.create!(
+    name: "John Doe", 
+    email: "john@example.com"
+  )
+  
+  user.create_profile!(
+    bio: "Software Developer",
+    location: "San Francisco"
+  )
+  
+  user.posts.create!(
+    title: "Welcome Post",
+    content: "Hello World!"
+  )
+end
+```
+
+### 🌐 URL-based Tracking
+
+Enable tracking for any request by adding `?dbwatch=true`:
+
+```
+# Track a user show page
+GET /users/123?dbwatch=true
+
+# Track a form submission
+POST /users?dbwatch=true
+
+# Track API endpoints
+GET /api/posts?dbwatch=true
+```
+
+### 📊 View Tracking Results
+
+Visit `/dbwatcher` in your Rails application to access the dashboard where you can:
+- Browse all tracking sessions
+- View detailed SQL queries and timing
+- Analyze database operation patterns
+- Monitor application performance
+
+## ⚙️ Configuration
+
+Create an initializer for custom configuration:
+
+```ruby
+# config/initializers/dbwatcher.rb
+Dbwatcher.configure do |config|
+  # Storage location for tracking data
+  config.storage_path = Rails.root.join('tmp', 'dbwatcher')
+  
+  # Enable/disable tracking (default: development only)
+  config.enabled = Rails.env.development?
+  
+  # Maximum number of sessions to keep
+  config.max_sessions = 100
+  
+  # Automatic cleanup after N days
+  config.auto_clean_after_days = 7
+  
+  # Include query parameters in tracking
+  config.include_params = true
+  
+  # Exclude certain SQL patterns
+  config.excluded_patterns = [
+    /SHOW TABLES/,
+    /DESCRIBE/
+  ]
+end
+```
+
+## 🏗️ Development & Testing
+
+This project includes a comprehensive dummy Rails application for testing and development.
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run specific test suites
+bundle exec rake unit          # Unit tests
+bundle exec rake acceptance    # Feature tests
+bundle exec cucumber -p chrome # Browser tests
+```
+
+### Development Server
+
+```bash
+# Start the dummy application
+cd spec/dummy
+bundle exec rails server -p 3001
+
+# Visit the test interface
+open http://localhost:3001
+
+# Visit DBWatcher dashboard
+open http://localhost:3001/dbwatcher
+```
+
+### Code Quality
+
+```bash
+# Run linter
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop --autocorrect
+
+# Security analysis
+bundle exec brakeman
+```
+
+## 🛠️ Troubleshooting
+
+### Route Helper Errors
+
+If you encounter `undefined method 'dbwatcher_sessions_path'`:
+
+1. **Restart your Rails server** after installing the gem
+2. **Check Rails version** - requires Rails 6.0+
+3. **Manual mounting** - add the mount line to your routes file
+
+### Performance Considerations
+
+- DBWatcher is designed for development environments
+- Disable in production using `config.enabled = false`
+- Use targeted tracking for performance-sensitive operations
+- Regular cleanup prevents storage bloat
+
+### Storage Location
+
+- Default: `Rails.root/tmp/dbwatcher/`
+- Files are JSON formatted for easy inspection
+- Sessions auto-expire based on configuration
+
+## 🔧 Advanced Usage
+
+### Custom Metadata
+
+Add context to your tracking sessions:
+
+```ruby
+Dbwatcher.track(
+  name: "Complex Business Logic",
+  metadata: {
+    user_id: current_user.id,
+    feature_flag: "new_checkout",
+    version: "2.1.0"
+  }
+) do
+  # Your database operations
+end
+```
+
+### Conditional Tracking
+
+```ruby
+Dbwatcher.track(name: "Admin Operations") do
+  # This will only track if DBWatcher is enabled
+  User.where(admin: true).update_all(last_seen: Time.current)
+end if Dbwatcher.enabled?
+```
+
+### Integration with Testing
+
+```ruby
+# In your test suite
+RSpec.describe "User Registration" do
+  it "creates user with proper associations" do
+    session_data = nil
+    
+    Dbwatcher.track(name: "Test User Creation") do
+      user = create(:user)
+      expect(user.profile).to be_present
+    end
+    
+    # Analyze the tracked operations
+    expect(Dbwatcher::Storage.last_session).to include_sql(/INSERT INTO users/)
+  end
+end
+```
+
+## 📁 Project Structure
+
+```
+dbwatcher/
+├── app/
+│   ├── controllers/dbwatcher/    # Web interface controllers
+│   └── views/dbwatcher/          # Dashboard templates
+├── config/
+│   └── routes.rb                 # Engine routes
+├── lib/dbwatcher/
+│   ├── configuration.rb         # Configuration management
+│   ├── engine.rb                # Rails engine
+│   ├── middleware.rb            # Rack middleware
+│   ├── storage.rb               # File-based storage
+│   └── tracker.rb               # Core tracking logic
+└── spec/
+    ├── dummy/                    # Test Rails application
+    ├── acceptance/               # Feature tests
+    └── unit/                     # Unit tests
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes and add tests
+4. Ensure all tests pass: `bundle exec rake test`
+5. Run the linter: `bundle exec rubocop`
+6. Commit your changes: `git commit -am 'Add amazing feature'`
+7. Push to the branch: `git push origin feature/amazing-feature`
+8. Open a Pull Request
+
+## 📝 License
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 🙏 Acknowledgments
+
+- Built with Rails Engine architecture
+- UI powered by Alpine.js and Tailwind CSS
+- Inspired by debugging needs in complex Rails applications
+
+---
+
+**Happy Debugging!** 🐛✨

data/Rakefile

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+# Unit tests
+RSpec::Core::RakeTask.new(:unit) do |task|
+  task.pattern = "spec/unit/**/*_spec.rb"
+end
+
+# Acceptance tests (Cucumber)
+begin
+  require "cucumber/rake/task"
+
+  Cucumber::Rake::Task.new(:acceptance) do |task|
+    task.cucumber_opts = ["spec/acceptance/features", "--require", "spec/acceptance"]
+  end
+rescue LoadError
+  desc "Cucumber not available"
+  task :acceptance do
+    puts "Cucumber not available. Install cucumber-rails gem to run acceptance tests."
+  end
+end
+
+# All tests
+task spec: [:unit]
+task test: %i[spec acceptance]
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+# Security tasks
+desc "Run bundle audit to check for security vulnerabilities"
+task :bundle_audit do
+  require "bundler/audit/task"
+  Bundler::Audit::Task.new
+end
+
+desc "Run Brakeman security scanner"
+task :brakeman do
+  require "brakeman"
+  result = Brakeman.run app_path: "spec/dummy", config_file: ".brakeman.yml"
+  if result.warnings.any? || result.errors.any?
+    puts "❌ Brakeman found security issues"
+    exit 1
+  else
+    puts "✅ Brakeman security check passed"
+  end
+end
+
+desc "Run all security checks"
+task security: %i[bundle_audit brakeman]
+
+# Default task
+task default: %i[test rubocop security]
+
+# Setup tasks
+desc "Set up test database and environment"
+task :test_setup do
+  Dir.chdir("spec/dummy") do
+    system("bundle install")
+    system("bundle exec rails db:drop db:create db:migrate RAILS_ENV=test")
+  end
+end
+
+desc "Start test server for manual testing"
+task :test_server do
+  Dir.chdir("spec/dummy") do
+    ENV["BUNDLE_GEMFILE"] = File.expand_path("Gemfile", Dir.pwd)
+    system("bundle exec rails server -e test -p 3001")
+  end
+end

data/app/controllers/dbwatcher/sessions_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Dbwatcher
+  class SessionsController < ActionController::Base
+    protect_from_forgery with: :exception
+    layout "dbwatcher/application"
+
+    def index
+      @sessions = Storage.all_sessions
+    end
+
+    def show
+      @session = Storage.load_session(params[:id])
+
+      respond_to do |format|
+        format.html
+        format.json { render json: @session.to_h }
+      end
+    end
+
+    def destroy_all
+      Dbwatcher.reset!
+      redirect_to root_path, notice: "All sessions cleared"
+    end
+
+    private
+
+    # Helper method to safely get the sessions path
+    def sessions_index_path
+      if respond_to?(:sessions_path)
+        sessions_path
+      else
+        "/dbwatcher"
+      end
+    end
+    helper_method :sessions_index_path
+  end
+end

data/app/views/dbwatcher/sessions/index.html.erb

@@ -0,0 +1,37 @@
+<div class="px-4 sm:px-0">
+  <h2 class="text-2xl font-bold mb-6">Tracking Sessions</h2>
+
+  <% if @sessions.empty? %>
+    <div class="bg-white overflow-hidden shadow rounded-lg p-6 text-center text-gray-500">
+      No tracking sessions yet. Start tracking with <code class="bg-gray-100 px-2 py-1 rounded">Dbwatcher.track { ... }</code>
+    </div>
+  <% else %>
+    <div class="bg-white shadow overflow-hidden sm:rounded-md">
+      <ul class="divide-y divide-gray-200">
+        <% @sessions.each do |session| %>
+          <li>
+            <%= link_to session_path(session[:id]), class: "block hover:bg-gray-50 px-4 py-4 sm:px-6" do %>
+              <div class="flex items-center justify-between">
+                <div class="flex-1">
+                  <p class="text-sm font-medium text-indigo-600 truncate">
+                    <%= session[:name] %>
+                  </p>
+                  <p class="mt-1 text-sm text-gray-600">
+                    <%= Time.parse(session[:started_at]).strftime("%Y-%m-%d %H:%M:%S") %>
+                    <span class="text-gray-400">•</span>
+                    <%= session[:change_count] %> changes
+                  </p>
+                </div>
+                <div class="ml-2 flex-shrink-0">
+                  <svg class="h-5 w-5 text-gray-400" fill="currentColor" viewBox="0 0 20 20">
+                    <path fill-rule="evenodd" d="M7.293 14.707a1 1 0 010-1.414L10.586 10 7.293 6.707a1 1 0 011.414-1.414l4 4a1 1 0 010 1.414l-4 4a1 1 0 01-1.414 0z" clip-rule="evenodd" />
+                  </svg>
+                </div>
+              </div>
+            <% end %>
+          </li>
+        <% end %>
+      </ul>
+    </div>
+  <% end %>
+</div>

data/app/views/dbwatcher/sessions/show.html.erb

@@ -0,0 +1,150 @@
+<div x-data="sessionViewer(<%= @session.to_h.to_json %>)" class="space-y-6">
+  <div class="flex justify-between items-center">
+    <h2 class="text-2xl font-bold" x-text="session.name"></h2>
+    <button @click="showFullRecords = !showFullRecords"
+            class="bg-gray-100 hover:bg-gray-200 px-4 py-2 rounded flex items-center gap-2">
+      <span x-text="showFullRecords ? 'Show Changes Only' : 'Show Full Records'"></span>
+    </button>
+  </div>
+
+  <!-- Summary -->
+  <div class="bg-white shadow rounded-lg p-6">
+    <h3 class="text-lg font-semibold mb-4">Summary</h3>
+    <div class="grid grid-cols-3 gap-4">
+      <template x-for="[key, count] in Object.entries(session.summary)" :key="key">
+        <div class="text-sm">
+          <span x-text="key.split(',')[0]" class="font-medium"></span>
+          <span x-text="key.split(',')[1]" :class="getOperationColor(key.split(',')[1])"></span>:
+          <span x-text="count"></span>
+        </div>
+      </template>
+    </div>
+  </div>
+
+  <!-- Changes by Table -->
+  <div class="bg-white shadow rounded-lg p-6">
+    <h3 class="text-lg font-semibold mb-4">Database Changes</h3>
+
+    <div class="space-y-2">
+      <template x-for="table in groupedChanges" :key="table.name">
+        <div class="border rounded">
+          <button @click="table.expanded = !table.expanded"
+                  class="w-full px-4 py-3 flex items-center justify-between hover:bg-gray-50">
+            <div class="flex items-center gap-2">
+              <svg class="w-4 h-4 transition-transform" :class="{'rotate-90': table.expanded}" fill="currentColor" viewBox="0 0 20 20">
+                <path fill-rule="evenodd" d="M7.293 14.707a1 1 0 010-1.414L10.586 10 7.293 6.707a1 1 0 011.414-1.414l4 4a1 1 0 010 1.414l-4 4a1 1 0 01-1.414 0z" clip-rule="evenodd" />
+              </svg>
+              <span class="font-medium" x-text="table.name"></span>
+              <span class="text-sm text-gray-500" x-text="`(${table.changes.length} changes)`"></span>
+            </div>
+          </button>
+
+          <div x-show="table.expanded" x-collapse class="border-t">
+            <template x-for="record in table.records" :key="record.id">
+              <div class="border-b last:border-0">
+                <button @click="record.expanded = !record.expanded"
+                        class="w-full px-6 py-2 flex items-center gap-2 hover:bg-gray-50 text-left">
+                  <svg class="w-4 h-4 transition-transform" :class="{'rotate-90': record.expanded}" fill="currentColor" viewBox="0 0 20 20">
+                    <path fill-rule="evenodd" d="M7.293 14.707a1 1 0 010-1.414L10.586 10 7.293 6.707a1 1 0 011.414-1.414l4 4a1 1 0 010 1.414l-4 4a1 1 0 01-1.414 0z" clip-rule="evenodd" />
+                  </svg>
+                  <span x-text="`Record #${record.id}`"></span>
+                </button>
+
+                <div x-show="record.expanded" x-collapse class="px-8 pb-4">
+                  <template x-for="change in record.changes" :key="change.timestamp">
+                    <div class="mt-3">
+                      <div class="font-medium mb-2" :class="getOperationColor(change.operation)">
+                        <span x-text="change.operation"></span> at
+                        <span x-text="new Date(change.timestamp).toLocaleTimeString()"></span>
+                      </div>
+
+                      <div x-show="!showFullRecords" class="space-y-1">
+                        <template x-for="col in change.changes" :key="col.column">
+                          <div class="text-sm">
+                            <span class="font-medium" x-text="col.column + ':'"></span>
+                            <template x-if="col.old_value">
+                              <span>
+                                <span class="text-red-600 line-through" x-text="col.old_value"></span>
+                                <span class="mx-1">→</span>
+                              </span>
+                            </template>
+                            <span class="text-green-600" x-text="col.new_value || 'null'"></span>
+                          </div>
+                        </template>
+                      </div>
+
+                      <div x-show="showFullRecords" class="bg-gray-50 p-3 rounded text-sm font-mono">
+                        <pre x-text="JSON.stringify(change.record_snapshot, null, 2)"></pre>
+                      </div>
+                    </div>
+                  </template>
+                </div>
+              </div>
+            </template>
+          </div>
+        </div>
+      </template>
+    </div>
+  </div>
+</div>
+
+<script>
+function sessionViewer(sessionData) {
+  return {
+    session: sessionData,
+    showFullRecords: false,
+    groupedChanges: [],
+
+    init() {
+      // Calculate summary from changes
+      const summary = {};
+      this.session.changes.forEach(change => {
+        const key = `${change.table_name},${change.operation}`;
+        summary[key] = (summary[key] || 0) + 1;
+      });
+      this.session.summary = summary;
+
+      // Group changes by table and record
+      const tables = {};
+
+      this.session.changes.forEach(change => {
+        if (!tables[change.table_name]) {
+          tables[change.table_name] = {
+            name: change.table_name,
+            expanded: false,
+            changes: [],
+            records: {}
+          };
+        }
+
+        tables[change.table_name].changes.push(change);
+
+        if (!tables[change.table_name].records[change.record_id]) {
+          tables[change.table_name].records[change.record_id] = {
+            id: change.record_id,
+            expanded: false,
+            changes: []
+          };
+        }
+
+        tables[change.table_name].records[change.record_id].changes.push(change);
+      });
+
+      // Convert to array format
+      this.groupedChanges = Object.values(tables).map(table => ({
+        ...table,
+        records: Object.values(table.records)
+      }));
+    },
+
+    getOperationColor(operation) {
+      const colors = {
+        'INSERT': 'text-green-600',
+        'UPDATE': 'text-blue-600',
+        'DELETE': 'text-red-600'
+      };
+      return colors[operation] || 'text-gray-600';
+    }
+  };
+}
+</script>

data/app/views/layouts/dbwatcher/application.html.erb

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>DB Watcher</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <%= csrf_meta_tags %>
+  <script src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js" defer></script>
+  <script src="https://cdn.tailwindcss.com"></script>
+</head>
+<body class="bg-gray-50">
+  <div class="min-h-screen">
+    <nav class="bg-white shadow">
+      <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+        <div class="flex justify-between h-16">
+          <div class="flex items-center">
+            <h1 class="text-xl font-semibold">🔍 DB Watcher</h1>
+          </div>
+          <div class="flex items-center space-x-4">
+            <%= link_to "Sessions", sessions_index_path, class: "text-gray-700 hover:text-gray-900" %>
+            <%= button_to "Reset All Sessions", destroy_all_sessions_path,
+                method: :delete,
+                data: { confirm: "Are you sure? This will delete all tracking data." },
+                class: "bg-red-500 text-white px-4 py-2 rounded hover:bg-red-600" %>
+          </div>
+        </div>
+      </div>
+    </nav>
+
+    <main class="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">
+      <%= yield %>
+    </main>
+  </div>
+</body>
+</html>

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "dbwatcher"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)