better_structure_sql 0.1.0 → 0.2.0

data/lib/better_structure_sql/dumper.rb

@@ -55,6 +55,7 @@ module BetterStructureSql
       output << views_section if config.include_views
       output << materialized_views_section if config.include_materialized_views
       output << triggers_section if config.include_triggers
+      output << comments_section if config.include_comments
       output << schema_migrations_section
       output << footer
 
@@ -99,133 +100,222 @@ module BetterStructureSql
     end
 
     # Generate sections as structured data (arrays) instead of joined strings
+    #
+    # Refactored to extract section generation into dedicated methods for better readability
     def generate_sections_for_multi_file
       sections = {}
 
-      # Extensions
-      if config.include_extensions
-        extensions = Introspection.fetch_extensions(connection)
-        unless extensions.empty?
-          generator = Generators::ExtensionGenerator.new(config)
-          sections[:extensions] = extensions.map { |ext| generator.generate(ext) }
-        end
-      end
+      sections[:extensions] = generate_extensions_section if config.include_extensions
+      sections[:types] = generate_types_section if config.include_custom_types
+      sections[:domains] = generate_domains_section if config.include_domains
+      sections[:functions] = generate_functions_section if config.include_functions
+      sections[:sequences] = generate_sequences_section if config.include_sequences
+      sections[:tables] = generate_tables_section
+      sections[:indexes] = generate_indexes_section
+      sections[:foreign_keys] = generate_foreign_keys_section unless sqlite_adapter?
+      sections[:views] = generate_views_section if config.include_views
+      sections[:materialized_views] = generate_materialized_views_section if config.include_materialized_views
+      sections[:triggers] = generate_triggers_section if config.include_triggers
+      sections[:comments] = generate_comments_section if config.include_comments
+      sections[:migrations] = generate_migrations_section unless sqlite_adapter?
+
+      sections.compact
+    end
 
-      # Custom types (enums, composite)
-      if config.include_custom_types
-        types = Introspection.fetch_custom_types(connection).reject { |t| t[:type] == 'domain' }
-        unless types.empty?
-          generator = Generators::TypeGenerator.new(config)
-          sections[:types] = types.filter_map { |type| generator.generate(type) }
-        end
-      end
+    # Generate extensions section
+    #
+    # @return [Array<String>, nil] Array of CREATE EXTENSION statements or nil if empty
+    def generate_extensions_section
+      extensions = Introspection.fetch_extensions(connection)
+      return nil if extensions.empty?
 
-      # Domains
-      if config.include_domains
-        domains = Introspection.fetch_custom_types(connection).select { |t| t[:type] == 'domain' }
-        unless domains.empty?
-          generator = Generators::DomainGenerator.new(config)
-          sections[:domains] = domains.map { |domain| generator.generate(domain) }
-        end
-      end
+      generator = Generators::ExtensionGenerator.new(config)
+      extensions.map { |ext| generator.generate(ext) }
+    end
 
-      # Functions
-      if config.include_functions
-        functions = Introspection.fetch_functions(connection)
-        unless functions.empty?
-          generator = Generators::FunctionGenerator.new(config)
-          sections[:functions] = functions.map { |func| generator.generate(func) }
-        end
-      end
+    # Generate custom types section (enums, composite types)
+    #
+    # @return [Array<String>, nil] Array of CREATE TYPE statements or nil if empty
+    def generate_types_section
+      types = Introspection.fetch_custom_types(connection).reject { |t| t[:type] == 'domain' }
+      return nil if types.empty?
 
-      # Sequences
-      if config.include_sequences
-        sequences = Introspection.fetch_sequences(connection)
-        unless sequences.empty?
-          generator = Generators::SequenceGenerator.new(config)
-          sections[:sequences] = sequences.map { |seq| generator.generate(seq) }
-        end
-      end
+      generator = Generators::TypeGenerator.new(config)
+      types.filter_map { |type| generator.generate(type) }
+    end
+
+    # Generate domains section
+    #
+    # @return [Array<String>, nil] Array of CREATE DOMAIN statements or nil if empty
+    def generate_domains_section
+      domains = Introspection.fetch_custom_types(connection).select { |t| t[:type] == 'domain' }
+      return nil if domains.empty?
+
+      generator = Generators::DomainGenerator.new(config)
+      domains.map { |domain| generator.generate(domain) }
+    end
+
+    # Generate functions section
+    #
+    # @return [Array<String>, nil] Array of CREATE FUNCTION statements or nil if empty
+    def generate_functions_section
+      functions = Introspection.fetch_functions(connection)
+      return nil if functions.empty?
+
+      generator = Generators::FunctionGenerator.new(config)
+      functions.map { |func| generator.generate(func) }
+    end
+
+    # Generate sequences section
+    #
+    # @return [Array<String>, nil] Array of CREATE SEQUENCE statements or nil if empty
+    def generate_sequences_section
+      sequences = Introspection.fetch_sequences(connection)
+      return nil if sequences.empty?
+
+      generator = Generators::SequenceGenerator.new(config)
+      sequences.map { |seq| generator.generate(seq) }
+    end
 
-      # Tables
+    # Generate tables section
+    #
+    # @return [Array<String>, nil] Array of CREATE TABLE statements or nil if empty
+    def generate_tables_section
       tables = Introspection.fetch_tables(connection)
       tables = tables.sort_by { |t| t[:name] } if config.sort_tables
-      unless tables.empty?
-        # For SQLite, attach foreign keys to each table for inline generation
-        if adapter.class.name == 'BetterStructureSql::Adapters::SqliteAdapter'
-          all_foreign_keys = Introspection.fetch_foreign_keys(connection)
-          tables.each do |table|
-            table[:foreign_keys] = all_foreign_keys.select { |fk| fk[:table] == table[:name] }
-          end
-        end
+      return nil if tables.empty?
 
-        generator = Generators::TableGenerator.new(config, adapter)
-        sections[:tables] = tables.map { |table| generator.generate(table) }
-      end
+      attach_foreign_keys_for_sqlite(tables) if sqlite_adapter?
 
-      # Indexes
+      generator = Generators::TableGenerator.new(config, adapter)
+      tables.map { |table| generator.generate(table) }
+    end
+
+    # Generate indexes section
+    #
+    # @return [Array<String>, nil] Array of CREATE INDEX statements or nil if empty
+    def generate_indexes_section
       indexes = Introspection.fetch_indexes(connection)
-      unless indexes.empty?
-        generator = Generators::IndexGenerator.new(config)
-        sections[:indexes] = indexes.map { |idx| generator.generate(idx) }
+      return nil if indexes.empty?
+
+      generator = Generators::IndexGenerator.new(config)
+      indexes.map { |idx| generator.generate(idx) }
+    end
+
+    # Generate foreign keys section
+    #
+    # @return [Array<String>, nil] Array of ALTER TABLE ADD CONSTRAINT statements or nil if empty
+    def generate_foreign_keys_section
+      foreign_keys = Introspection.fetch_foreign_keys(connection)
+      return nil if foreign_keys.empty?
+
+      generator = Generators::ForeignKeyGenerator.new(config)
+      foreign_keys.map { |fk| generator.generate(fk) }
+    end
+
+    # Generate views section
+    #
+    # @return [Array<String>, nil] Array of CREATE VIEW statements or nil if empty
+    def generate_views_section
+      views = Introspection.fetch_views(connection)
+      return nil if views.empty?
+
+      generator = Generators::ViewGenerator.new(config)
+      views.map { |view| generator.generate(view) }
+    end
+
+    # Generate materialized views section
+    #
+    # @return [Array<String>, nil] Array of CREATE MATERIALIZED VIEW statements or nil if empty
+    def generate_materialized_views_section
+      matviews = Introspection.fetch_materialized_views(connection)
+      return nil if matviews.empty?
+
+      generator = Generators::MaterializedViewGenerator.new(config)
+      matviews.map { |mv| generator.generate(mv) }
+    end
+
+    # Generate triggers section
+    #
+    # @return [Array<String>, nil] Array of CREATE TRIGGER statements or nil if empty
+    def generate_triggers_section
+      triggers = Introspection.fetch_triggers(connection)
+      return nil if triggers.empty?
+
+      generator = Generators::TriggerGenerator.new(config)
+      triggers.map { |trigger| generator.generate(trigger) }
+    end
+
+    # Generate comments section
+    #
+    # @return [Array<String>, nil] Array of COMMENT ON statements or nil if empty
+    def generate_comments_section
+      return nil unless adapter.supports_comments?
+
+      all_comments = adapter.fetch_comments(connection)
+      generator = Generators::CommentGenerator.new(config)
+
+      # Generate table comments
+      comments_array = all_comments[:tables].map do |table_name, comment|
+        generator.generate(object_type: :table, object_name: table_name, comment: comment)
       end
 
-      # Foreign keys
-      # SQLite foreign keys are inline with CREATE TABLE, not separate ALTER TABLE statements
-      unless adapter.class.name == 'BetterStructureSql::Adapters::SqliteAdapter'
-        foreign_keys = Introspection.fetch_foreign_keys(connection)
-        unless foreign_keys.empty?
-          generator = Generators::ForeignKeyGenerator.new(config)
-          sections[:foreign_keys] = foreign_keys.map { |fk| generator.generate(fk) }
-        end
+      # Generate column comments
+      all_comments[:columns].each do |column_identifier, comment|
+        comments_array << generator.generate(object_type: :column, object_name: column_identifier, comment: comment)
       end
 
-      # Views
-      if config.include_views
-        views = Introspection.fetch_views(connection)
-        unless views.empty?
-          generator = Generators::ViewGenerator.new(config)
-          sections[:views] = views.map { |view| generator.generate(view) }
-        end
+      # Generate index comments (PostgreSQL only)
+      all_comments[:indexes].each do |index_name, comment|
+        comments_array << generator.generate(object_type: :index, object_name: index_name, comment: comment)
       end
 
-      # Materialized views
-      if config.include_materialized_views
-        matviews = Introspection.fetch_materialized_views(connection)
-        unless matviews.empty?
-          generator = Generators::MaterializedViewGenerator.new(config)
-          sections[:materialized_views] = matviews.map { |mv| generator.generate(mv) }
-        end
+      # Generate view comments (PostgreSQL only)
+      all_comments[:views].each do |view_name, comment|
+        comments_array << generator.generate(object_type: :view, object_name: view_name, comment: comment)
       end
 
-      # Triggers
-      if config.include_triggers
-        triggers = Introspection.fetch_triggers(connection)
-        unless triggers.empty?
-          generator = Generators::TriggerGenerator.new(config)
-          sections[:triggers] = triggers.map { |trigger| generator.generate(trigger) }
-        end
+      # Generate function comments (PostgreSQL only)
+      all_comments[:functions].each do |function_name, comment|
+        comments_array << generator.generate(object_type: :function, object_name: function_name, comment: comment)
       end
 
-      # Schema migrations - create batch INSERT statements
-      # Each batch INSERT is a complete SQL statement, chunked into groups
-      # SQLite doesn't include schema_migrations in structure.sql (Rails manages it separately)
-      if adapter.class.name != 'BetterStructureSql::Adapters::SqliteAdapter' && table_exists?('schema_migrations')
-        versions = fetch_schema_migration_versions
-        unless versions.empty?
-          # Chunk versions into groups (each group will be one batch INSERT)
-          # Using max_lines - 3 to account for INSERT header + ON CONFLICT footer
-          chunk_size = config.max_lines_per_file - 3
-          version_chunks = versions.each_slice(chunk_size).to_a
-
-          # Generate batch INSERT for each chunk
-          sections[:migrations] = version_chunks.map do |chunk|
-            generate_migrations_batch(chunk)
-          end
-        end
+      return nil if comments_array.empty?
+
+      comments_array
+    end
+
+    # Generate migrations section
+    #
+    # @return [Array<String>, nil] Array of batch INSERT statements or nil if empty
+    def generate_migrations_section
+      return nil unless table_exists?('schema_migrations')
+
+      versions = fetch_schema_migration_versions
+      return nil if versions.empty?
+
+      chunk_size = config.max_lines_per_file - 3
+      version_chunks = versions.each_slice(chunk_size).to_a
+
+      version_chunks.map { |chunk| generate_migrations_batch(chunk) }
+    end
+
+    # Attach foreign keys to tables for SQLite inline generation
+    #
+    # @param tables [Array<Hash>] Array of table hashes
+    # @return [void]
+    def attach_foreign_keys_for_sqlite(tables)
+      all_foreign_keys = Introspection.fetch_foreign_keys(connection)
+      tables.each do |table|
+        table[:foreign_keys] = all_foreign_keys.select { |fk| fk[:table] == table[:name] }
       end
+    end
 
-      sections
+    # Check if current adapter is SQLite
+    #
+    # @return [Boolean] True if using SQLite adapter
+    def sqlite_adapter?
+      adapter.class.name == 'BetterStructureSql::Adapters::SqliteAdapter'
     end
 
     # Combine sections for database storage (when versioning is enabled)
@@ -429,6 +519,44 @@ module BetterStructureSql
       lines.join("\n\n")
     end
 
+    def comments_section
+      return nil unless adapter.supports_comments?
+
+      all_comments = adapter.fetch_comments(connection)
+      generator = Generators::CommentGenerator.new(config)
+
+      # Generate table comments
+      comments_array = all_comments[:tables].map do |table_name, comment|
+        generator.generate(object_type: :table, object_name: table_name, comment: comment)
+      end
+
+      # Generate column comments
+      all_comments[:columns].each do |column_identifier, comment|
+        comments_array << generator.generate(object_type: :column, object_name: column_identifier, comment: comment)
+      end
+
+      # Generate index comments (PostgreSQL only)
+      all_comments[:indexes].each do |index_name, comment|
+        comments_array << generator.generate(object_type: :index, object_name: index_name, comment: comment)
+      end
+
+      # Generate view comments (PostgreSQL only)
+      all_comments[:views].each do |view_name, comment|
+        comments_array << generator.generate(object_type: :view, object_name: view_name, comment: comment)
+      end
+
+      # Generate function comments (PostgreSQL only)
+      all_comments[:functions].each do |function_name, comment|
+        comments_array << generator.generate(object_type: :function, object_name: function_name, comment: comment)
+      end
+
+      return nil if comments_array.empty?
+
+      lines = ['-- Comments']
+      lines += comments_array
+      lines.join("\n")
+    end
+
     def schema_migrations_section
       # SQLite doesn't include schema_migrations in structure.sql
       # Rails manages this table separately

data/lib/better_structure_sql/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  # Base error class for all BetterStructureSql errors
+  class Error < StandardError; end
+
+  # Raised when adapter-specific operations fail
+  class AdapterError < Error; end
+
+  # Raised when database introspection fails
+  class IntrospectionError < Error; end
+
+  # Raised when SQL generation fails
+  class GenerationError < Error; end
+
+  # Raised when configuration is invalid
+  class ConfigurationError < Error; end
+
+  # Raised when schema versioning operations fail
+  class SchemaVersionError < Error; end
+
+  # Raised when file operations fail
+  class FileError < Error; end
+end

data/lib/better_structure_sql/file_writer.rb

@@ -57,7 +57,8 @@ module BetterStructureSql
         views: '08_views',               # After tables (may use functions)
         materialized_views: '08_views',  # Bundled with views
         triggers: '09_triggers',         # After tables and functions
-        migrations: '10_migrations'      # Last (schema_migrations INSERT)
+        comments: '10_comments',         # After all objects are created
+        migrations: '20_migrations'      # Last (schema_migrations INSERT)
       }
 
       file_map = {}

data/lib/better_structure_sql/generators/base.rb

@@ -24,10 +24,48 @@ module BetterStructureSql
 
       private
 
+      # Indent text by specified level
+      #
+      # @param text [String] Text to indent
+      # @param level [Integer] Indentation level (default: 1)
+      # @return [String] Indented text
       def indent(text, level = 1)
         spaces = ' ' * (config.indent_size * level)
         text.split("\n").map { |line| "#{spaces}#{line}" }.join("\n")
       end
+
+      # Quote identifier based on database adapter
+      #
+      # @param identifier [String] Database identifier (table, column, index name)
+      # @return [String] Quoted identifier
+      def quote_identifier(identifier)
+        return identifier if identifier.nil?
+
+        adapter_name = detect_adapter_name
+
+        if mysql_adapter?(adapter_name)
+          "`#{identifier}`"
+        else
+          "\"#{identifier}\""
+        end
+      end
+
+      # Detect current adapter name
+      #
+      # @return [String, nil] Adapter name or nil
+      def detect_adapter_name
+        ActiveRecord::Base.connection.adapter_name.downcase
+      rescue StandardError
+        nil
+      end
+
+      # Check if adapter is MySQL
+      #
+      # @param adapter_name [String, nil] Adapter name
+      # @return [Boolean] True if MySQL adapter
+      def mysql_adapter?(adapter_name)
+        %w[mysql mysql2 trilogy].include?(adapter_name)
+      end
     end
   end
 end

data/lib/better_structure_sql/generators/comment_generator.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Generates COMMENT ON statements for database objects
+    #
+    # Supports PostgreSQL and MySQL comment syntax.
+    # MySQL uses ALTER TABLE syntax for table/column comments.
+    class CommentGenerator < Base
+      # Generates COMMENT ON statement
+      #
+      # @param comment_data [Hash] Comment metadata with :object_type, :object_name, :comment
+      # @return [String] SQL statement
+      def generate(comment_data)
+        object_type = comment_data[:object_type]
+        object_name = comment_data[:object_name]
+        comment_text = comment_data[:comment]
+
+        # Escape single quotes in comment
+        escaped_comment = comment_text.gsub("'", "''")
+
+        case object_type
+        when :table
+          generate_table_comment(object_name, escaped_comment)
+        when :column
+          generate_column_comment(object_name, escaped_comment)
+        when :index
+          generate_index_comment(object_name, escaped_comment)
+        when :view
+          generate_view_comment(object_name, escaped_comment)
+        when :function
+          generate_function_comment(object_name, escaped_comment)
+        else
+          raise ArgumentError, "Unknown object type: #{object_type}"
+        end
+      end
+
+      private
+
+      # Generate comment for table
+      #
+      # @param table_name [String] Table name
+      # @param comment [String] Comment text (already escaped)
+      # @return [String] SQL statement
+      def generate_table_comment(table_name, comment)
+        if mysql_adapter?(detect_adapter_name)
+          # MySQL uses ALTER TABLE syntax
+          "ALTER TABLE #{quote_identifier(table_name)} COMMENT '#{comment}';"
+        else
+          # PostgreSQL uses COMMENT ON
+          "COMMENT ON TABLE #{quote_identifier(table_name)} IS '#{comment}';"
+        end
+      end
+
+      # Generate comment for column
+      #
+      # @param column_identifier [String] Format: "table_name.column_name"
+      # @param comment [String] Comment text (already escaped)
+      # @return [String] SQL statement
+      def generate_column_comment(column_identifier, comment)
+        table_name, column_name = column_identifier.split('.')
+
+        if mysql_adapter?(detect_adapter_name)
+          # MySQL requires full column definition in ALTER TABLE
+          # This is a limitation - we'd need to fetch column type, which is complex
+          # For now, return a comment indicating manual update needed
+          "-- MySQL column comment (requires full ALTER TABLE with column definition):\n" \
+            "-- ALTER TABLE #{quote_identifier(table_name)} MODIFY COLUMN #{quote_identifier(column_name)} <type> COMMENT '#{comment}';"
+        else
+          # PostgreSQL supports COMMENT ON COLUMN
+          "COMMENT ON COLUMN #{quote_identifier(table_name)}.#{quote_identifier(column_name)} IS '#{comment}';"
+        end
+      end
+
+      # Generate comment for index
+      #
+      # @param index_name [String] Index name
+      # @param comment [String] Comment text (already escaped)
+      # @return [String] SQL statement
+      def generate_index_comment(index_name, comment)
+        # Only PostgreSQL supports index comments
+        if mysql_adapter?(detect_adapter_name)
+          '-- MySQL does not support index comments'
+        else
+          "COMMENT ON INDEX #{quote_identifier(index_name)} IS '#{comment}';"
+        end
+      end
+
+      # Generate comment for view
+      #
+      # @param view_name [String] View name
+      # @param comment [String] Comment text (already escaped)
+      # @return [String] SQL statement
+      def generate_view_comment(view_name, comment)
+        # Only PostgreSQL supports view comments
+        if mysql_adapter?(detect_adapter_name)
+          '-- MySQL does not support view comments'
+        else
+          "COMMENT ON VIEW #{quote_identifier(view_name)} IS '#{comment}';"
+        end
+      end
+
+      # Generate comment for function
+      #
+      # @param function_name [String] Function name
+      # @param comment [String] Comment text (already escaped)
+      # @return [String] SQL statement
+      def generate_function_comment(function_name, comment)
+        # Only PostgreSQL supports function comments
+        if mysql_adapter?(detect_adapter_name)
+          '-- MySQL does not support function comments'
+        else
+          "COMMENT ON FUNCTION #{quote_identifier(function_name)} IS '#{comment}';"
+        end
+      end
+    end
+  end
+end

data/lib/better_structure_sql/generators/domain_generator.rb

@@ -11,7 +11,8 @@ module BetterStructureSql
       def generate(domain)
         schema_prefix = domain[:schema] == 'public' ? '' : "#{domain[:schema]}."
 
-        parts = ["CREATE DOMAIN IF NOT EXISTS #{schema_prefix}#{domain[:name]} AS #{domain[:base_type]}"]
+        # NOTE: PostgreSQL does not support IF NOT EXISTS for domains
+        parts = ["CREATE DOMAIN #{schema_prefix}#{domain[:name]} AS #{domain[:base_type]}"]
 
         parts << domain[:constraint] if domain[:constraint].present?
 

data/lib/better_structure_sql/generators/index_generator.rb

@@ -23,7 +23,9 @@ module BetterStructureSql
         table = quote_identifier(index[:table])
         name = quote_identifier(index[:name])
 
-        "CREATE #{unique_clause}INDEX IF NOT EXISTS #{name} ON #{table} (#{columns_list});"
+        # MySQL doesn't support IF NOT EXISTS for indexes, SQLite does
+        # For simplicity, omit IF NOT EXISTS for cross-database compatibility
+        "CREATE #{unique_clause}INDEX #{name} ON #{table} (#{columns_list});"
       end
 
       private