dbtodoc 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f435503e31f05aaa1598c8d7fee82519cc38ecc36b5ce0e4d3f783948579543
-  data.tar.gz: 10177a6e91718a7c8e4da15bc5db59e0351f6e6ba35719e272e431a0e8e119fd
+  metadata.gz: 46b410adc65d93a3d5ddadb38c150e011210b6fa647ad997da4ba02a16278061
+  data.tar.gz: 5ee19920e8f462e061d3966f75c82a26147fb51375553bc51da1b6dce789d6e1
 SHA512:
-  metadata.gz: c7408cbe931b98cc51d0850fce98a8150094f141a04838afb5f2f877c59e033d11ad2a39cc65d8c61f157bd38a8837b06ae4e976d71acedd47b99db9c749eea1
-  data.tar.gz: 804cf971c9051fcdb8602f87001140659ea04524af9aea2e039315cc8cc48a1ebdd92f3fa5ea444b07543b025c42fe60d13d215bf3b1ed53098791a2f610bced
+  metadata.gz: 53e6983ec0ddc34630e115817dfd067a527cf573c9493daf1145d7ba9070defea4113a21253a588664eca1b34ebb6844082fc62b45e216e3ce4ec7fb1f6071e6
+  data.tar.gz: 10b006ba3cd8634ad5370a06f208566fbbcb73cea56ccd41a9bcc594faa012e8bf7573e80824e3bf9142ccc89eaab2af31b17031dbcc1077cc964c3cf0ae6a8a

data/README.md

@@ -1,31 +1,199 @@
-# Dbtodoc
+# DBToDoc
 
-TODO: Delete this and the text below, and describe your gem
+DBToDoc 是一个专门用于将 Rails 项目的数据库 schema 导出为文档的Ruby gem。它支持多种输出格式，包括 schema.rb、CSV 和 Excel，帮助开发者快速生成数据库文档。
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/dbtodoc`. To experiment with that code, run `bin/console` for an interactive prompt.
+## ✨ 功能特性
 
-## Installation
+- 🚀 **多格式支持**：导出为 schema.rb、CSV 或 Excel 格式，默认 Excel
+- 🗄️ **多数据库兼容**：支持 MySQL、PostgreSQL、SQLite
+- 🌐 **国际化支持**：自动读取 Rails 的 locales 文件进行字段翻译
+- 🎨 **美观输出**：Excel 格式支持样式设置和颜色主题
+- 🔍 **智能分析**：自动解析数据库配置和表结构
+- 📊 **详细文档**：包含字段名、类型、约束、默认值等完整信息
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## 📋 系统要求
 
-Install the gem and add to the application's Gemfile by executing:
+- Ruby >= 2.6.0
+- Rails 项目（包含 config/database.yml）
+- 支持的数据库：MySQL、PostgreSQL、SQLite
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## 🚀 安装
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### 从 Rubygems 安装
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```bash
+gem install dbtodoc
+```
 
-## Usage
+### 从源码安装
 
-TODO: Write usage instructions here
+```bash
+git clone https://github.com/shuhjx/dbtodoc.git
+cd dbtodoc
+gem build dbtodoc.gemspec
+gem install dbtodoc-*.gem
+```
 
-## Development
+## 📖 使用方法
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### 基本用法
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+DBToDoc 提供了一个简单的命令行接口：
 
-## Contributing
+```bash
+# 导出为 schema.rb 格式
+dbtodoc --format=ruby
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/dbtodoc.
+# 导出为 schema.sql 格式
+dbtodoc --format=sql
+
+# 导出为 CSV 格式
+dbtodoc --format=csv
+
+# 导出为 Excel 格式
+dbtodoc --format=excel
+
+# 指定项目路径
+dbtodoc --path=/path/to/rails/project --format=excel
+```
+
+### 在 Ruby 代码中使用
+
+```ruby
+require 'dbtodoc'
+
+# 导出为 schema.rb 格式
+Dbtodoc.start(format: 'ruby')
+
+# 导出为 schema.sql 格式
+Dbtodoc.start(format: 'sql')
+
+# 导出为 CSV 格式
+Dbtodoc.start(format: 'csv')
+
+# 导出为 Excel 格式
+Dbtodoc.start(format: 'excel')
+
+# 指定项目路径
+Dbtodoc.start(path: '/path/to/rails/project', format: 'excel')
+```
+
+## 📊 输出格式说明
+
+### CSV 格式
+CSV 文件包含以下列：
+- 表名
+- 字段名
+- 类型
+- NULL许可
+- 默认值
+- 日本語名（通过 i18n 获取）
+- 说明
+- 样本数据
+- 索引名
+
+### Excel 格式
+Excel 文件具有以下特性：
+- 📋 每张表单独分组显示
+- 🎨 专业的颜色主题：
+  - 蓝色：表名行
+  - 绿色：表头
+  - 白色：数据行
+  - 浅绿色：主键字段
+- 📏 自动调整列宽
+- 🔤 支持日文字体（MS Pゴシック）
+- 📐 完整的边框样式
+
+Excel 输出包含以下列：
+- フィールド名（字段名）
+- 型（类型）
+- NULL許可（NULL许可）
+- デフォルト値（默认值）
+- 日本語名（日文字段名）
+- 説明（说明）
+- サンプルデータ（样本数据）
+- 索引名（索引名）
+
+## 🌍 国际化支持
+
+DBToDoc 自动读取 Rails 项目的 `config/locales/*.yml` 文件，支持以下国际化特性：
+
+- 📝 **表名翻译**：自动将英文表名转换为本地语言
+- 🏷️ **字段名翻译**：为字段名提供多语言支持
+- 🔄 **智能复数处理**：自动处理单复数形式转换
+
+示例 locales 配置：
+
+```yaml
+# config/locales/ja.yml
+ja:
+  activerecord:
+    models:
+      user: ユーザー
+      post: 投稿
+    attributes:
+      user:
+        name: 名前
+        email: メール
+```
+
+## 🔧 技术架构
+
+### 核心组件
+
+1. **Dbtodoc::Schema** - 重写 ActiveRecord::Schema 方法，拦截表定义过程
+2. **Dbtodoc::Definition** - 处理表和字段定义的收集
+3. **Dbtodoc::I18n** - 提供国际化支持
+4. **Dbtodoc::Doc::Csv** - CSV 格式导出
+5. **Dbtodoc::Doc::Excel** - Excel 格式导出
+
+### 工作流程
+
+```
+读取 database.yml → 连接数据库 → 生成 schema.rb → 转换为目标格式
+```
+
+## 📁 文件输出位置
+
+所有输出文件都保存在 Rails 项目的 `tmp/` 目录下：
+
+```
+tmp/
+├── {database_name}_schema.rb    # schema 格式
+├── {database_name}.csv          # CSV 格式
+└── {database_name}.xlsx         # Excel 格式
+```
+
+## 🛠️ 开发环境设置
+
+### 克隆项目
+
+```bash
+git clone https://github.com/shuhjx/dbtodoc.git
+cd dbtodoc
+```
+
+### 安装依赖
+
+```bash
+bundle install
+```
+
+### 运行测试(待完成)
+
+```bash
+rake spec
+```
+
+### 构建 gem
+
+```bash
+rake build
+```
+
+## 🙏 致谢
+
+感谢以下开源项目：
+- [RubyXL](https://rubyxl.github.io/) - Excel 文件处理
+- [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html) - 数据库抽象层
+- [CLI::UI](https://github.com/shopify/cli-ui) - 用户界面组件

data/bin/dbtodoc

@@ -6,16 +6,16 @@ require 'optparse'
 class ArgsParser
   def self.parse!(args)
     options = {
-      type: 'excel'
+      format: 'excel'
     }
     opt_parser = OptionParser.new do |opts|
       opts.banner = "Usage: dbtodoc [options]"
 
-      opts.on('-t', '--type TYPE', "指定输出类型，默认值：excel，可选值：schema, csv, excel") do |o|
-        options[:type] = o
+      opts.on('-f', '--format FORMAT', "指定输出格式，默认值：excel，可选值：ruby, sql, csv, excel") do |o|
+        options[:format] = o
       end
 
-      opts.on('-h', '--help', "显示帮助\n例：dbtodoc -t csv /rails/root/path") do
+      opts.on('-h', '--help', "显示帮助\n例：dbtodoc -f csv /rails/root/path") do
         puts opts
         exit
       end
@@ -35,8 +35,8 @@ unless File.exist?(path)
   puts "#{path}: 文件或目录不存在"
   exit 1
 end
-options[:path] = path
+options[:path] = File.expand_path(path, Dir.pwd)
+Dir.chdir(options[:path]) if path != '.' # 切换到目标目录
 
 require 'dbtodoc'
-
-Dbtodoc.start(options)
+Dbtodoc.start(options)

data/dbtodoc.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email = ["shuh_jx@163.com"]
 
   spec.summary = "将 Rails 项目的数据库 schema 导出为文档"
-  spec.description = "将 Rails 项目的数据库 schema 导出为文档，支持 schema, csv, excel 格式"
+  spec.description = "将 Rails 项目的数据库 schema 导出为文档，支持 ruby, sql, csv, excel 格式"
   spec.homepage = "https://github.com/shuhjx/dbtodoc"
   spec.required_ruby_version = ">= 2.6.0"
 

data/lib/dbtodoc/definition.rb

@@ -17,7 +17,7 @@ module Dbtodoc
       before_define()
       instance_eval(&block)
     ensure
-      after_define()
+      after_define() rescue nil
     end
 
     def index(column_names, **options)
@@ -33,7 +33,13 @@ module Dbtodoc
     end
 
     def database
-      @_database ||= ActiveRecord::Base.connection.current_database
+      return @_database if @_database
+      if ActiveRecord::Base.connection.respond_to?(:current_database)
+        @_database = ActiveRecord::Base.connection.current_database
+      else
+        # sqlite3 数据库文件路径
+        @_database = File.basename(ActiveRecord::Base.connection_db_config.database)
+      end
     end
     private
     # 写入文档
@@ -91,25 +97,48 @@ module Dbtodoc
     def add_foreign_key(from_table, to_table, **options)
       #TODO 外键
     end
+    def enable_extension(extension_name)
+      # TODO
+    end
+
+    # def test(name)
+    #   if !@definition
+    #     version = ActiveRecord::Migration.current_version
+    #     klass = Class.new(ActiveRecord::Migration::Compatibility.find(version)) do
+    #       include ActiveRecord::Schema::Definition
+    #     end
+    #     @definition = klass.new
+    #   end
+    #   @definition.instance_eval do
+    #     create_table("test_bak") do |t|
+    #       puts "#{name}: #{t.method(name).source_location}"
+    #     end
+    #     drop_table("test_bak")
+    #   end
+    # end
 
     def method_missing(name, *args, &block)
       type = case name
-        when :bigint
+        when :bigint, :bigserial
           ActiveRecord::Type.registry.lookup(:big_integer)
+        when :serial
+          ActiveRecord::Type.registry.lookup(:integer)
         else 
           ActiveRecord::Type.registry.lookup(name.to_sym) rescue nil
         end
+      column = args[0]
+      options = args[1] || {}
       if type
-        column = args[0]
-        options = args[1] || {}
         # 调用type_to_sql方法
         sql_type = ActiveRecord::Base.connection.schema_creation.send(:type_to_sql, type.type, **options)
         add_row(column, sql_type, **options)
+      elsif native_type = ActiveRecord::Base.adapter_class.native_database_types[name]
+        add_row(column, native_type[:name], **options)
       else
         puts '------------'
         puts "name: #{name}, args: #{args}"
         puts '------------'
-        super
+        raise "Unknown method: #{name}"
       end
     end
   end

data/lib/dbtodoc/doc/csv.rb

@@ -2,7 +2,7 @@ require 'csv'
 module Dbtodoc
   module Doc
     module Csv
-      DOC_HEADER = %w(表名 字段名 类型 NULL許可 默认値 日本語名 説明 样本数据 索引名)
+      DOC_HEADER = %w(テーブル名 フィールド名 型 NULL許可 デフォルト値 日本語名 説明 サンプルデータ 索引名)
 
       private
       def before_define

data/lib/dbtodoc/doc/excel.rb

@@ -45,7 +45,6 @@ module Dbtodoc
 
       def add_table_name_row(table_name)
         [table_name, i18n.table_name(table_name), *Array.new(DOC_HEADER.size - 2, nil)].each_with_index do |value, col|
-          @col_max_widths[col+1] = [@col_max_widths[col+1], value.to_s.length].max if value
           cell = @worksheet.add_cell(@max_row, col + 1, value)
           # 设置背景颜色（蓝色）
           set_cell_style(cell, :table_name)

data/lib/dbtodoc/doc/ruby.rb

@@ -0,0 +1,15 @@
+module Dbtodoc
+  module Doc
+    module Ruby
+      def self.dump(filename)
+        File.open(filename, 'w:utf-8') do |file|
+          if ActiveRecord.version >= '7.1'
+            ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection_pool, file)
+          else
+            ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection, file)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dbtodoc/doc/sql.rb

@@ -0,0 +1,29 @@
+module Dbtodoc
+  module Doc
+    module Sql
+      def self.dump(filename)
+        pool =  ActiveRecord::Base.connection_pool
+        db_config = pool.db_config
+        klass = case db_config.adapter
+          when /mysql|trilogy/
+            'ActiveRecord::Tasks::MySQLDatabaseTasks'
+          when /postgresql/
+            'ActiveRecord::Tasks::PostgreSQLDatabaseTasks'
+          when /sqlite/
+            'ActiveRecord::Tasks::SQLiteDatabaseTasks'
+          else
+            raise "Unknown adapter: #{db_config.adapter}"
+          end
+        klass = klass.constantize 
+        converted = klass.respond_to?(:using_database_configurations?) && klass.using_database_configurations?
+        # db_config = ActiveRecord::Base.configurations.resolve(db_config)
+        config = converted ? db_config : db_config.configuration_hash
+        task = db_config.adapter =~ /sqlite/ ? klass.new(config, '.') : klass.new(config)
+
+        flags = nil
+        # flags = ["--exclude-table-data '*'", '--no-comments', '--no-publications', '--no-subscriptions', '--no-security-labels', '--no-tablespaces', '--no-unlogged-table-data'] if db_config.adapter =~ /postgresql/
+        task.structure_dump(filename, flags)
+      end
+    end
+  end
+end

data/lib/dbtodoc/schema.rb

@@ -36,14 +36,14 @@ module ActiveRecord
         @class_for_version ||= {}
         @class_for_version[version] ||= Class.new do
           include ::Dbtodoc::Definition
-          if @@doc_type_module
-            include @@doc_type_module
+          if @@doc_format_module
+            include @@doc_format_module
           end
         end
       end
 
-      def set_doc_type(type)
-        @@doc_type_module = case type
+      def set_doc_format(format)
+        @@doc_format_module = case format
           when 'csv'
             require_relative('./doc/csv.rb')
             ::Dbtodoc::Doc::Csv
@@ -51,7 +51,7 @@ module ActiveRecord
             require_relative './doc/excel.rb'
             ::Dbtodoc::Doc::Excel
           else
-            raise ArgumentError, "Invalid doc type: #{type}"
+            raise ArgumentError, "Invalid doc format: #{format}"
           end
       end
     end

data/lib/dbtodoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dbtodoc
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

data/lib/dbtodoc.rb

@@ -24,7 +24,6 @@ module Dbtodoc
   
   def self.start(options)
     path = options[:path] || '.'
-    Dir.chdir(path) if path != '.' # 切换到目标目录
 
     db_config_file = File.join(path, 'config/database.yml')
     unless File.exist?(db_config_file)
@@ -55,10 +54,13 @@ module Dbtodoc
     case adapter
     when 'mysql2'
       require 'mysql2'
-    when 'pg'
+    when 'postgresql'
       require 'pg'
     when 'sqlite3'
       require 'sqlite3'
+      _tmp = all_db_configs[db_name].update('database' => File.join(path, db_name))
+      db_name = File.basename(db_name)
+      all_db_configs[db_name] = _tmp
     else
       puts "Unknown adapter: #{adapter}"
       exit 1
@@ -69,29 +71,31 @@ module Dbtodoc
 
     # 确保tmp目录存在
     FileUtils.mkdir_p File.join(path, 'tmp')
-
-    # 生成数据库 schema 文件
-    schema_file = File.join(path, "tmp/#{db_name}_schema.rb")
-    File.open(schema_file, 'w:utf-8') do |file|
-      if ActiveRecord.version >= '7.1'
-        ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection_pool, file)
-      else
-        ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection, file)
+    
+    format = options[:format].downcase
+    case format
+    when 'sql'
+      filename = File.join(path, "tmp/#{db_name}.sql")
+      require_relative File.join(__dir__, 'dbtodoc/doc/sql.rb')
+      Dbtodoc::Doc::Sql.dump(filename)
+      puts "SQL file: #{filename}"
+    when 'ruby', 'csv', 'excel'
+      schema_file = File.join(path, "tmp/#{db_name}.rb")
+      require_relative File.join(__dir__, 'dbtodoc/doc/ruby.rb')
+      # 生成数据库 schema 文件
+      Dbtodoc::Doc::Ruby.dump(schema_file)
+      if format == 'ruby'
+        puts "Ruby file: #{schema_file}"
+        exit
       end
-    end
-
-    case options[:type].downcase
-    when 'schema'
-      puts "Schema file: #{schema_file}"
-    when 'csv', 'excel'
       require_relative File.join(__dir__, 'dbtodoc/schema.rb')
-      ActiveRecord::Schema.set_doc_type(options[:type])
+      ActiveRecord::Schema.set_doc_format(options[:format])
       #执行schema.rb文件，生成csv|excel文件
-      eval File.read(schema_file), binding
-      puts "CSV file: #{File.join(path, "tmp/#{db_name}.csv")}" if options[:type] == 'csv'
-      puts "Excel file: #{File.join(path, "tmp/#{db_name}.xlsx")}" if options[:type] == 'excel'
+      eval File.read(schema_file)
+      puts "CSV file: #{File.join(path, "tmp/#{db_name}.csv")}" if options[:format] == 'csv'
+      puts "Excel file: #{File.join(path, "tmp/#{db_name}.xlsx")}" if options[:format] == 'excel'
     else
-      puts "Unknown type: #{options[:type]}"
+      puts "Unknown format: #{options[:format]}"
     end
   end
 end

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: dbtodoc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - shuhjx
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-05 00:00:00.000000000 Z
+date: 2026-01-06 00:00:00.000000000 Z
 dependencies: []
-description: 将 Rails 项目的数据库 schema 导出为文档，支持 schema, csv, excel 格式
+description: 将 Rails 项目的数据库 schema 导出为文档，支持 ruby, sql, csv, excel 格式
 email:
 - shuh_jx@163.com
 executables:
@@ -18,17 +18,17 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".DS_Store"
 - ".rspec"
 - README.md
 - Rakefile
-- bin/.DS_Store
 - bin/dbtodoc
 - dbtodoc.gemspec
 - lib/dbtodoc.rb
 - lib/dbtodoc/definition.rb
 - lib/dbtodoc/doc/csv.rb
 - lib/dbtodoc/doc/excel.rb
+- lib/dbtodoc/doc/ruby.rb
+- lib/dbtodoc/doc/sql.rb
 - lib/dbtodoc/i18n.rb
 - lib/dbtodoc/schema.rb
 - lib/dbtodoc/version.rb