DbdocEngine

A mountable Rails engine for database design documentation. Provides a full-featured web interface to document, visualize, and collaborate on your database schema — tables, columns, relationships, constraints, and change history.

• Table & Column Documentation — Document every table and column with logical/physical names, data types, constraints (PK, FK, NOT NULL, unique, indexed), default values, and descriptions.
• Table Groups — Organize tables into color-coded logical groups (e.g., "User Management", "Orders", "Master Data").
• Interactive Schema Diagram — Auto-generated ER diagram with group-based highlighting and FK relationship lines.
• Changelog & Audit Trail — Every create, update, and delete is automatically logged with timestamp, user, and before/after values.
• Excel Export — Export full documentation as .xlsx (all tables or single table) with proper formatting and i18n support.
• JSON Import/Export — Backup and restore all documentation data as JSON.
• Schema.rb Import — Auto-import table/column definitions from your project's schema.rb or an uploaded file.
• Role-Based Access Control — Three roles: user (read-only), admin (edit), superadmin (full control including import/export/delete).
• Soft Delete & Restore — Safely delete and restore tables and groups.
• i18n Support — Full English and Japanese localization.
• Modern Dashboard — Stats overview, recent activity, action chart, and quick-access import/export tools.

gem "dbdoc_engine"

bundle install
bin/rails generate dbdoc_engine:install

The installer will automatically:

1. Copy the appropriate migrations (Rails 7 or Rails 8)
2. Run db:migrate to create all DbdocEngine tables
3. Seed three default users
4. Mount the engine at /dbdoc in config/routes.rb
5. Configure importmap pins in config/importmap.rb
6. Add the JS import to app/javascript/application.js
7. For Rails 7: install importmap/turbo/stimulus if missing, update manifest.js

bin/rails server

Visit http://localhost:3000/dbdoc and log in.

After installation, three users are created in the dbdoc_engine_users table (isolated from your app's users table):

Important: Change the default passwords in production.

By default the engine is mounted at /dbdoc. To change it:

# config/routes.rb
Rails.application.routes.draw do
  mount DbdocEngine::Engine => "/dbdoc"
end

DbdocEngine supports English (en) and Japanese (ja). The locale can be switched from the UI or by appending ?locale=ja to any URL.

All tables are namespaced to avoid conflicts with your application:

dbdoc_engine/
├── app/
│   ├── controllers/dbdoc_engine/
│   │   ├── application_controller.rb      # Auth, i18n, layout
│   │   ├── home_controller.rb             # Public documentation pages
│   │   ├── schema_diagram_controller.rb   # ER diagram + JSON API
│   │   ├── db_doc_sessions_controller.rb  # Login/logout
│   │   └── admin/
│   │       ├── base_controller.rb         # Admin authorization
│   │       ├── dashboard_controller.rb    # Dashboard stats & chart
│   │       ├── db_design_dynamic_tables_controller.rb
│   │       ├── db_design_table_groups_controller.rb
│   │       └── data_transfer_controller.rb  # Import/export
│   ├── models/dbdoc_engine/
│   │   ├── user.rb
│   │   ├── db_design_table_group.rb
│   │   ├── db_design_dynamic_table.rb
│   │   ├── db_design_dynamic_column.rb
│   │   ├── db_design_changelog.rb
│   │   └── concerns/soft_deletable.rb
│   ├── services/dbdoc_engine/
│   │   ├── schema_rb_parser_service.rb    # Parse schema.rb DSL
│   │   └── schema_rb_import_service.rb    # Bulk-import tables/columns
│   ├── queries/dbdoc_engine/              # Query objects (no N+1)
│   ├── helpers/dbdoc_engine/
│   ├── views/dbdoc_engine/                # ERB templates
│   ├── javascript/dbdoc_engine/           # Stimulus controllers
│   └── assets/
│       ├── stylesheets/dbdoc_engine/      # CSS
│       └── images/dbdoc_engine/           # Icons, logos
├── config/
│   ├── routes.rb                          # Engine routes
│   ├── locales/
│   │   ├── en.yml                         # English translations
│   │   └── ja.yml                         # Japanese translations
│   └── importmap.rb
├── db/
│   ├── migrate/
│   │   ├── rails7/                        # Migrations for Rails 7.x
│   │   └── rails8/                        # Migrations for Rails 8.x
│   └── seeds.rb                           # Default user seeds
└── lib/
    ├── dbdoc_engine.rb
    ├── dbdoc_engine/
    │   ├── engine.rb
    │   └── version.rb
    ├── generators/dbdoc_engine/
    │   ├── install/install_generator.rb    # Install generator
    │   └── uninstall/uninstall_generator.rb # Uninstall generator
    └── tasks/dbdoc_engine_tasks.rake

# config/routes.rb
Rails.application.routes.draw do
  mount DbdocEngine::Engine => "/dbdoc"
end

# config/importmap.rb
if defined?(DbdocEngine)
  pin_all_from DbdocEngine::Engine.root.join("app/javascript/dbdoc_engine"),
    under: "dbdoc_engine",
    to: "dbdoc_engine"
end

// app/javascript/application.js
import "dbdoc_engine/application";

bin/rails dbdoc_engine:install:migrations
bin/rails db:migrate

bin/rails dbdoc_engine:install:seeds
bin/rails dbdoc_engine:db:seed

To completely remove DbdocEngine from your project:

bin/rails generate dbdoc_engine:uninstall

The uninstaller will ask for confirmation before:

1. Dropping all DbdocEngine tables (with a separate confirmation — you can choose to keep them)
2. Removing the engine route from config/routes.rb
3. Removing importmap pins from config/importmap.rb
4. Removing the JS import from app/javascript/application.js
5. Deleting the seed file db/dbdoc_engine_seeds.rb
6. Cleaning up migration files and schema_migrations entries

After running the uninstaller, remove gem "dbdoc_engine" from your Gemfile and run bundle install.

From the Admin Dashboard, superadmins can:

• Export all documentation data (groups, tables, columns) as a single .json file
• Import a previously exported .json file to restore or migrate documentation

Two options to quickly bootstrap documentation from an existing database:

• This Project — Reads the current project's db/schema.rb and imports all table/column definitions
• Upload File — Upload any schema.rb file (from another project) via drag-and-drop or file picker

The import uses bulk insert_all! for fast performance (1500+ columns in under 1 second).

Export documentation as a formatted .xlsx file:

• All Tables — Generates a workbook with a table index sheet and one detail sheet per table
• Single Table — Export a specific table's column definitions

All Excel content is fully internationalized (English/Japanese).

cd dbdoc_engine
bundle install
cd test/dummy
bin/rails db:create db:migrate
bin/rails dbdoc_engine:db:seed
bin/rails server

cd dbdoc_engine
bundle exec rspec

The gem is available as open source under the terms of the MIT License.