better_structure_sql 0.1.0

data/lib/better_structure_sql/file_writer.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  # Handles writing schema output to either a single file or multiple files
+  # with intelligent chunking based on line count limits.
+  class FileWriter
+    attr_reader :config
+
+    def initialize(config = BetterStructureSql.configuration)
+      @config = config
+    end
+
+    # Detect if the output path is for single-file or multi-file mode
+    # @param path [String] The output path
+    # @return [Symbol] :single_file or :multi_file
+    def detect_output_mode(path)
+      # If path has no extension or is a directory, it's multi-file
+      # Otherwise, if it ends with .sql or .rb, it's single-file
+      return :multi_file if File.extname(path).empty?
+      return :multi_file if path.end_with?('/')
+
+      :single_file
+    end
+
+    # Write complete schema to a single file
+    # @param path [String] The file path
+    # @param content [String] The complete SQL content
+    def write_single_file(path, content)
+      full_path = Rails.root.join(path)
+      FileUtils.mkdir_p(File.dirname(full_path))
+      File.write(full_path, content)
+    end
+
+    # Write schema sections to multiple files with chunking
+    # @param base_path [String] The base directory path
+    # @param sections [Hash] Hash of section_name => array of SQL strings
+    # @param header [String] The header content (SET statements, etc.)
+    def write_multi_file(base_path, sections, header)
+      full_base_path = Rails.root.join(base_path)
+      FileUtils.mkdir_p(full_base_path)
+
+      # Write header file
+      write_chunk(full_base_path, '_header.sql', header)
+
+      # Define section order with directory prefixes
+      # Order CRITICAL for schema loading - respects dependency chain:
+      # extensions -> types/domains -> functions -> sequences -> tables -> indexes/fks -> views -> triggers -> migrations
+      section_order = {
+        extensions: '01_extensions',     # Must be first (enable features)
+        types: '02_types',               # Before domains and tables
+        domains: '02_types',             # Bundled with types (domains are custom types)
+        functions: '03_functions',       # Before triggers that call them
+        sequences: '04_sequences',       # Before tables that use them
+        tables: '05_tables',             # Core schema
+        indexes: '06_indexes',           # After tables exist
+        foreign_keys: '07_foreign_keys', # After all tables exist
+        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)
+      }
+
+      file_map = {}
+      directory_file_counters = Hash.new(0) # Track file numbers per directory
+
+      # Group sections by directory to handle shared directories correctly
+      sections_by_directory = {}
+      section_order.each do |section_key, directory_name|
+        next unless sections.key?(section_key)
+
+        section_content = sections[section_key]
+        next if section_content.blank?
+
+        sections_by_directory[directory_name] ||= []
+        sections_by_directory[directory_name].concat(section_content)
+      end
+
+      # Process each directory (with merged content from multiple sections)
+      sections_by_directory.each do |directory_name, merged_content|
+        # Create directory
+        section_dir = full_base_path.join(directory_name)
+        FileUtils.mkdir_p(section_dir)
+
+        # Chunk the merged content and write files
+        chunks = chunk_section(merged_content, config.max_lines_per_file)
+        chunks.each do |chunk|
+          # Increment counter for this directory
+          directory_file_counters[directory_name] += 1
+          filename = format_filename(directory_file_counters[directory_name])
+          file_path = section_dir.join(filename)
+          content = chunk.join("\n\n")
+          File.write(file_path, "#{content}\n")
+
+          # Track in file map for manifest
+          relative_path = "#{directory_name}/#{filename}"
+          file_map[relative_path] = content
+        end
+      end
+
+      file_map
+    end
+
+    private
+
+    # Chunk an array of SQL strings into file-sized groups
+    # Each chunk respects max_lines_per_file with overflow_threshold
+    # Single objects larger than max_lines get their own file
+    #
+    # @param objects [Array<String>] Array of SQL strings
+    # @param max_lines [Integer] Maximum lines per file
+    # @return [Array<Array<String>>] Array of chunks, each chunk is array of SQL strings
+    def chunk_section(objects, max_lines)
+      return [] if objects.empty?
+
+      chunks = []
+      current_chunk = []
+      current_lines = 0
+      max_with_overflow = (max_lines * config.overflow_threshold).to_i
+
+      objects.each do |object|
+        object_lines = object.lines.count
+
+        # If this single object exceeds max_lines, give it a dedicated file
+        if object_lines > max_lines
+          # Flush current chunk if it has content
+          chunks << current_chunk unless current_chunk.empty?
+
+          # Single object in its own chunk
+          chunks << [object]
+
+          # Reset for next chunk
+          current_chunk = []
+          current_lines = 0
+          next
+        end
+
+        # Decide whether to start a new chunk
+        # If current chunk is already at max_lines, definitely start new chunk
+        # If current chunk is under max_lines but adding this would exceed overflow, start new chunk
+        # Otherwise, add to current chunk (even if it puts us slightly over max_lines, up to overflow threshold)
+        if current_lines >= max_lines
+          # Current chunk is full, start new one
+          chunks << current_chunk unless current_chunk.empty?
+          current_chunk = [object]
+          current_lines = object_lines
+        elsif current_lines.positive? && (current_lines + object_lines) > max_with_overflow
+          # Adding this would exceed overflow threshold, start new chunk
+          chunks << current_chunk
+          current_chunk = [object]
+          current_lines = object_lines
+        else
+          # Add to current chunk (may go slightly over max_lines, within overflow)
+          current_chunk << object
+          current_lines += object_lines
+        end
+      end
+
+      # Don't forget the last chunk
+      chunks << current_chunk unless current_chunk.empty?
+
+      chunks
+    end
+
+    # Write a single chunk file
+    # @param directory [Pathname] The directory path
+    # @param filename [String] The filename
+    # @param content [String] The file content
+    def write_chunk(directory, filename, content)
+      file_path = directory.join(filename)
+      File.write(file_path, content)
+    end
+
+    # Generate zero-padded filename
+    # @param index [Integer] The file number (1-based)
+    # @return [String] Formatted filename like "000001.sql"
+    def format_filename(index)
+      "#{index.to_s.rjust(6, '0')}.sql"
+    end
+  end
+end

data/lib/better_structure_sql/formatter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  # Formats SQL output for consistency and readability
+  #
+  # Handles whitespace normalization, section spacing, and
+  # blank line management to produce clean, deterministic output.
+  class Formatter
+    attr_reader :config
+
+    def initialize(config = BetterStructureSql.configuration)
+      @config = config
+    end
+
+    # Formats SQL content with consistent spacing
+    #
+    # @param content [String] Raw SQL content
+    # @return [String] Formatted SQL
+    def format(content)
+      sections = parse_sections(content)
+      formatted = sections.map { |section| format_section(section) }
+
+      if config.add_section_spacing
+        formatted.join("\n\n")
+      else
+        formatted.join("\n")
+      end
+    end
+
+    # Formats an individual SQL section
+    #
+    # @param section [String] SQL section content
+    # @return [String] Formatted section
+    def format_section(section)
+      # Normalize whitespace
+      lines = section.split("\n").map(&:rstrip)
+
+      # Remove excessive blank lines
+      lines = collapse_blank_lines(lines)
+
+      lines.join("\n")
+    end
+
+    private
+
+    def parse_sections(content)
+      # Split content into logical sections based on SQL comments and statement types
+      content.split(/(?=--\s+\w+\n)/).reject(&:empty?)
+    end
+
+    def collapse_blank_lines(lines)
+      result = []
+      previous_blank = false
+
+      lines.each do |line|
+        current_blank = line.strip.empty?
+
+        if current_blank
+          result << line unless previous_blank
+        else
+          result << line
+        end
+
+        previous_blank = current_blank
+      end
+
+      result
+    end
+  end
+end

data/lib/better_structure_sql/generators/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Base class for all SQL generators
+    #
+    # Provides common functionality for generating SQL statements
+    # from database object metadata.
+    class Base
+      attr_reader :config
+
+      def initialize(config = BetterStructureSql.configuration)
+        @config = config
+      end
+
+      # Generates SQL for a database object
+      #
+      # @param object [Hash] Object metadata from introspection
+      # @return [String] SQL statement
+      # @raise [NotImplementedError] Must be implemented by subclasses
+      def generate(object)
+        raise NotImplementedError, 'Subclasses must implement #generate'
+      end
+
+      private
+
+      def indent(text, level = 1)
+        spaces = ' ' * (config.indent_size * level)
+        text.split("\n").map { |line| "#{spaces}#{line}" }.join("\n")
+      end
+    end
+  end
+end

data/lib/better_structure_sql/generators/domain_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Generates CREATE DOMAIN statements for custom types with constraints
+    class DomainGenerator < Base
+      # Generates CREATE DOMAIN statement
+      #
+      # @param domain [Hash] Domain metadata
+      # @return [String] SQL statement
+      def generate(domain)
+        schema_prefix = domain[:schema] == 'public' ? '' : "#{domain[:schema]}."
+
+        parts = ["CREATE DOMAIN IF NOT EXISTS #{schema_prefix}#{domain[:name]} AS #{domain[:base_type]}"]
+
+        parts << domain[:constraint] if domain[:constraint].present?
+
+        "#{parts.join(' ')};"
+      end
+    end
+  end
+end

data/lib/better_structure_sql/generators/extension_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Generates CREATE EXTENSION statements for PostgreSQL
+    class ExtensionGenerator < Base
+      # Generates CREATE EXTENSION or PRAGMA statement
+      #
+      # @param extension [Hash] Extension metadata
+      # @return [String] SQL statement
+      def generate(extension)
+        # Handle SQLite PRAGMAs (which are stored as "extensions")
+        return extension[:sql] if extension[:sql]
+
+        # PostgreSQL extensions
+        # Quote extension name if it contains special characters
+        ext_name = extension[:name].include?('-') ? "\"#{extension[:name]}\"" : extension[:name]
+        schema_clause = extension[:schema] == 'public' ? '' : " WITH SCHEMA #{extension[:schema]}"
+        "CREATE EXTENSION IF NOT EXISTS #{ext_name}#{schema_clause};"
+      end
+    end
+  end
+end

data/lib/better_structure_sql/generators/foreign_key_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Generates ALTER TABLE ADD CONSTRAINT for foreign keys
+    #
+    # Handles CASCADE, RESTRICT, SET NULL actions.
+    class ForeignKeyGenerator < Base
+      # Generates ALTER TABLE ADD CONSTRAINT for foreign key
+      #
+      # @param foreign_key [Hash] Foreign key metadata
+      # @return [String] SQL statement
+      def generate(foreign_key)
+        parts = [
+          "ALTER TABLE #{foreign_key[:table]}",
+          "ADD CONSTRAINT #{foreign_key[:name]}",
+          "FOREIGN KEY (#{foreign_key[:column]})",
+          "REFERENCES #{foreign_key[:foreign_table]} (#{foreign_key[:foreign_column]})"
+        ]
+
+        on_delete = format_action(foreign_key[:on_delete])
+        parts << "ON DELETE #{on_delete}" if on_delete != 'NO ACTION'
+
+        on_update = format_action(foreign_key[:on_update])
+        parts << "ON UPDATE #{on_update}" if on_update != 'NO ACTION'
+
+        "#{parts.join(' ')};"
+      end
+
+      private
+
+      def format_action(action)
+        case action&.upcase
+        when 'CASCADE' then 'CASCADE'
+        when 'SET NULL' then 'SET NULL'
+        when 'SET DEFAULT' then 'SET DEFAULT'
+        when 'RESTRICT' then 'RESTRICT'
+        else 'NO ACTION'
+        end
+      end
+    end
+  end
+end

data/lib/better_structure_sql/generators/function_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Generates CREATE FUNCTION statements
+    #
+    # Supports PL/pgSQL, SQL, and other procedural languages.
+    class FunctionGenerator < Base
+      # Generates CREATE FUNCTION or CREATE PROCEDURE statement
+      #
+      # @param function [Hash] Function metadata with definition
+      # @return [String] SQL statement
+      def generate(function)
+        # PostgreSQL's pg_get_functiondef and MySQL's SHOW CREATE both return
+        # complete CREATE FUNCTION/PROCEDURE statements
+        definition = function[:definition].strip
+
+        # For MySQL, strip DEFINER clause which causes permission issues
+        if definition.include?('CREATE DEFINER')
+          # Remove DEFINER clause: "CREATE DEFINER=`user`@`host` PROCEDURE" -> "CREATE PROCEDURE"
+          definition = definition.gsub(/CREATE DEFINER=`[^`]+`@`[^`]+`/, 'CREATE')
+        end
+
+        # For dumping to structure.sql, we need to ensure the statement ends with semicolon
+        # MySQL SHOW CREATE PROCEDURE returns WITHOUT semicolon, so add it
+        # PostgreSQL pg_get_functiondef includes it, so don't add duplicate
+        definition += ';' unless definition.end_with?(';')
+
+        definition
+      end
+    end
+  end
+end

data/lib/better_structure_sql/generators/index_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Generates CREATE INDEX statements
+    #
+    # Supports unique indexes, partial indexes, and expression indexes.
+    class IndexGenerator < Base
+      # Generates CREATE INDEX statement
+      #
+      # @param index [Hash] Index metadata
+      # @return [String] SQL statement
+      def generate(index)
+        # PostgreSQL provides complete definition via pg_indexes
+        if index[:definition]
+          definition = index[:definition]
+          return definition.end_with?(';') ? definition : "#{definition};"
+        end
+
+        # For MySQL/SQLite, generate CREATE INDEX statement from components
+        unique_clause = index[:unique] ? 'UNIQUE ' : ''
+        columns_list = Array(index[:columns]).map { |col| quote_identifier(col) }.join(', ')
+        table = quote_identifier(index[:table])
+        name = quote_identifier(index[:name])
+
+        "CREATE #{unique_clause}INDEX IF NOT EXISTS #{name} ON #{table} (#{columns_list});"
+      end
+
+      private
+
+      def quote_identifier(identifier)
+        return identifier if identifier.nil?
+
+        # Detect adapter from ActiveRecord connection
+        adapter_name = begin
+          ActiveRecord::Base.connection.adapter_name.downcase
+        rescue StandardError
+          nil
+        end
+
+        # MySQL/MariaDB use backticks, PostgreSQL/SQLite use double quotes
+        if %w[mysql mysql2 trilogy].include?(adapter_name)
+          "`#{identifier}`"
+        else
+          "\"#{identifier}\""
+        end
+      end
+    end
+  end
+end

data/lib/better_structure_sql/generators/materialized_view_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Generates CREATE MATERIALIZED VIEW statements for PostgreSQL
+    class MaterializedViewGenerator < Base
+      # Generates CREATE MATERIALIZED VIEW statement
+      #
+      # @param matview [Hash] Materialized view metadata
+      # @return [String] SQL statement
+      def generate(matview)
+        schema_prefix = matview[:schema] == 'public' ? '' : "#{matview[:schema]}."
+        definition = matview[:definition].strip
+
+        # Ensure definition ends with semicolon
+        definition += ';' unless definition.end_with?(';')
+
+        output = ["CREATE MATERIALIZED VIEW IF NOT EXISTS #{schema_prefix}#{matview[:name]} AS"]
+        output << definition
+
+        # Add indexes if present
+        if matview[:indexes]&.any?
+          output << ''
+          output += matview[:indexes].map { |idx| "#{idx};" }
+        end
+
+        output.join("\n")
+      end
+    end
+  end
+end

data/lib/better_structure_sql/generators/pragma_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Generator for SQLite PRAGMA statements
+    # PRAGMAs returned by SqliteAdapter are in format:
+    # { name: 'foreign_keys', value: 1, sql: 'PRAGMA foreign_keys = 1;' }
+    # Generates PRAGMA statements for SQLite
+    class PragmaGenerator < Base
+      # Generates PRAGMA statement for SQLite
+      #
+      # @param pragma [Hash] PRAGMA metadata
+      # @return [String] SQL statement
+      def generate(pragma)
+        # If SQL is pre-generated, use it
+        return pragma[:sql] if pragma[:sql]
+
+        # Otherwise generate from name and value
+        "PRAGMA #{pragma[:name]} = #{pragma[:value]};"
+      end
+    end
+  end
+end

data/lib/better_structure_sql/generators/sequence_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Generates CREATE SEQUENCE statements
+    class SequenceGenerator < Base
+      # Generates CREATE SEQUENCE statement
+      #
+      # @param sequence [Hash] Sequence metadata
+      # @return [String] SQL statement
+      def generate(sequence)
+        parts = ["CREATE SEQUENCE IF NOT EXISTS #{sequence[:name]}"]
+
+        parts << "START WITH #{sequence[:start_value]}" if sequence[:start_value]
+        parts << "INCREMENT BY #{sequence[:increment]}" if sequence[:increment] && sequence[:increment] != 1
+        parts << "MINVALUE #{sequence[:min_value]}" if sequence[:min_value]
+        parts << "MAXVALUE #{sequence[:max_value]}" if sequence[:max_value]
+
+        parts << "CACHE #{sequence[:cache_size]}" if sequence[:cache_size] && sequence[:cache_size] > 1
+
+        parts << 'CYCLE' if sequence[:cycle]
+
+        "#{parts.join("\n  ")};"
+      end
+    end
+  end
+end

data/lib/better_structure_sql/generators/table_generator.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module BetterStructureSql
+  module Generators
+    # Generates CREATE TABLE statements with columns and constraints
+    #
+    # Handles column definitions, primary keys, constraints, and
+    # inline foreign keys for SQLite.
+    class TableGenerator < Base
+      attr_reader :adapter
+
+      def initialize(config, adapter = nil)
+        super(config)
+        @adapter = adapter
+      end
+
+      # Generates CREATE TABLE statement
+      #
+      # @param table [Hash] Table metadata with columns and constraints
+      # @return [String] SQL statement
+      def generate(table)
+        lines = ["CREATE TABLE IF NOT EXISTS #{table[:name]} ("]
+
+        column_defs = table[:columns].map { |col| column_definition(col) }
+
+        if table[:primary_key]&.any?
+          # Quote primary key column names
+          pk_cols = table[:primary_key].map { |col| quote_column_name(col) }.join(', ')
+          column_defs << "PRIMARY KEY (#{pk_cols})"
+        end
+
+        table[:constraints]&.each do |constraint|
+          column_defs << constraint_definition(constraint)
+        end
+
+        # For SQLite, add foreign keys inline
+        if sqlite_adapter? && table[:foreign_keys]&.any?
+          table[:foreign_keys].each do |fk|
+            column_defs << foreign_key_definition(fk)
+          end
+        end
+
+        lines << column_defs.map { |def_line| indent(def_line) }.join(",\n")
+        lines << ');'
+
+        lines.join("\n")
+      end
+
+      private
+
+      def column_definition(column)
+        # Quote column name for MySQL compatibility (reserved words like 'key')
+        column_name = quote_column_name(column[:name])
+        parts = [column_name, column[:type]]
+
+        parts << 'NOT NULL' unless column[:nullable]
+
+        if column[:default]
+          default_value = format_default(column[:default])
+          parts << "DEFAULT #{default_value}"
+        end
+
+        parts.join(' ')
+      end
+
+      def constraint_definition(constraint)
+        case constraint[:type]
+        when :check
+        when :unique
+        end
+        "CONSTRAINT #{constraint[:name]} #{constraint[:definition]}"
+      end
+
+      def format_default(default_value)
+        return default_value if default_value.nil?
+
+        # Handle nextval for sequences
+        return default_value if default_value.start_with?('nextval(')
+
+        # Handle NULL
+        return 'NULL' if default_value.upcase == 'NULL'
+
+        # Handle boolean values
+        return default_value if %w[true false].include?(default_value.downcase)
+
+        # Handle numeric values
+        return default_value if default_value.match?(/\A-?\d+(\.\d+)?\z/)
+
+        # Handle functions and expressions
+        return default_value if default_value.include?('(') || default_value.upcase.start_with?('CURRENT_')
+
+        # Otherwise, assume it's a string and quote it if not already quoted
+        default_value.start_with?("'") ? default_value : "'#{default_value}'"
+      end
+
+      def sqlite_adapter?
+        adapter&.class&.name == 'BetterStructureSql::Adapters::SqliteAdapter'
+      end
+
+      def foreign_key_definition(foreign_key)
+        parts = ["FOREIGN KEY (#{foreign_key[:column]})"]
+        parts << "REFERENCES #{foreign_key[:foreign_table]} (#{foreign_key[:foreign_column]})"
+        parts << "ON DELETE #{foreign_key[:on_delete]}" if foreign_key[:on_delete] && foreign_key[:on_delete] != 'NO ACTION'
+        parts << "ON UPDATE #{foreign_key[:on_update]}" if foreign_key[:on_update] && foreign_key[:on_update] != 'NO ACTION'
+
+        parts.join(' ')
+      end
+
+      def quote_column_name(column_name)
+        # Detect adapter from ActiveRecord connection
+        adapter_name = begin
+          ActiveRecord::Base.connection.adapter_name.downcase
+        rescue StandardError
+          nil
+        end
+
+        # MySQL/MariaDB use backticks, PostgreSQL/SQLite use double quotes
+        if %w[mysql mysql2 trilogy].include?(adapter_name)
+          "`#{column_name}`"
+        else
+          "\"#{column_name}\""
+        end
+      end
+    end
+  end
+end