A Rails gem that tracks and visualizes database operations in your application. Built for developers who need to understand complex data flows and debug database interactions.
When developing Rails applications, understanding what database operations occur during code execution can be challenging. dbwatcher provides a simple way to:
- Track database changes within specific code blocks
- Monitor SQL operations during HTTP requests
- Visualize database relationships and model associations
- Debug complex data flows with an intuitive web interface
- Database Operation Tracking - Capture SQL operations (INSERT, UPDATE, DELETE)
- Targeted Monitoring - Track specific code blocks or entire HTTP requests
- Interactive Dashboard - Clean web interface for exploring captured data
- Relationship Diagrams - Visualize database relationships and model associations
- Simple Setup - File-based storage with zero additional database requirements
- Development Ready - Designed specifically for development environments
View more screenshots in here →
Add to your Gemfile:
gem 'dbwatcher', group: :developmentInstall the gem:
bundle installThe dashboard automatically becomes available at /dbwatcher in your Rails application.
Monitor specific operations:
Dbwatcher.track(name: "User Registration") do
user = User.create!(name: "John", email: "john@example.com")
user.create_profile!(bio: "Developer")
user.posts.create!(title: "Hello World")
endAdd ?dbwatch=true to any URL:
GET /users/123?dbwatch=true
POST /api/users?dbwatch=true
Visit /dbwatcher in your browser to explore tracked operations.
dbwatcher works out of the box with zero configuration - simply install the gem and visit /dbwatcher in your Rails application.
View All Configuration Settings
| Setting | Type | Default | Description |
|---|---|---|---|
| Core Settings | |||
enabled |
Boolean | true |
Enable or disable DBWatcher |
storage_path |
String | "tmp/dbwatcher" |
Directory for session data storage |
| Session Management | |||
max_sessions |
Integer | 50 |
Maximum number of sessions to retain |
auto_clean_days |
Integer | 7 |
Automatically delete sessions older than N days |
| Query Tracking | |||
track_queries |
Boolean | false |
Enable full SQL query tracking (resource intensive) |
| System Information | |||
system_info |
Boolean | true |
Collect system information for debugging |
debug_mode |
Boolean | false |
Enable detailed debug logging |
| Database Diagram Options | |||
diagram_show_attributes |
Boolean | true |
Display model attributes in diagrams |
diagram_show_cardinality |
Boolean | true |
Show relationship cardinality indicators |
diagram_show_methods |
Boolean | false |
Include model methods in diagrams |
diagram_max_attributes |
Integer | 10 |
Maximum attributes displayed per model |
diagram_attribute_types |
Boolean | true |
Show data types for attributes |
diagram_relationship_labels |
Boolean | true |
Display labels on relationship lines |
# config/environments/development.rb
Rails.application.configure do
config.dbwatcher.enabled = true
config.dbwatcher.max_sessions = 100
config.dbwatcher.track_queries = true
endAdd context to your tracking:
Dbwatcher.track(
name: "Order Processing",
metadata: { user_id: current_user.id, order_type: "premium" }
) do
# Database operations here
endAccess the current tracking session:
session = Dbwatcher.current_session
puts "Session ID: #{session.id}"
puts "Total changes: #{session.changes.count}"Remove all stored sessions and queries:
Dbwatcher.clear_allbundle exec rake test # All tests
bundle exec rake unit # Unit tests only
bundle exec rake acceptance # Feature tests onlyThe project uses SimpleCov for code coverage and uploads results to Qlty. To run tests with coverage locally:
COVERAGE=true bundle exec rake testCoverage reports will be generated in the coverage/ directory.
cd spec/dummy
bundle exec rails server -p 3001
open http://localhost:3001/dbwatcherbundle exec rubocop # Linting
bundle exec brakeman # Security analysis- Fork the repository
- Create a feature branch:
git checkout -b my-feature - Make changes and add tests
- Run tests:
bundle exec rake test - Run linter:
bundle exec rubocop - Commit changes:
git commit -am 'Add feature' - Push branch:
git push origin my-feature - Open a Pull Request
Released under the MIT License.