sql_beautifier 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9b1fa5cd125f5c255888fe73fa0eb382a711452e0dde36e72d194eede7909d8
+  data.tar.gz: 613ec14ba2aaa8e276e284195924ad955bd82634ce76598c822c523048939a7d
+SHA512:
+  metadata.gz: 554c19234224a8b2f96fe62499944ebb3f4d50f24e2ead9d38c5b340b983a4b1231b0feb395e978bf489a75cb390811254acbaa7239e3560d7c66a4520f41556
+  data.tar.gz: 04fcd9d23787c9e8a2e82a480ee545839666fc5e0b2b509ada502356d46547166cbd32ec7531662bfaaaeb12be39eeb18318f76f268595e324f5b19ccf6ef862

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [X.X.X] - YYYY-MM-DD
+
+## [0.1.1] - 2026-03-26
+
+## [0.1.0] - 2026-03-26
+
+- Initial release
+- Formats SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT clauses
+- Lowercase keywords with 8-character column alignment
+- Multi-column SELECT with continuation indentation
+- Parenthesis and string-literal aware tokenization
+- Normalizes whitespace and handles quoted identifiers

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Kinnell Shah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,178 @@
+# SqlBeautifier
+
+Opinionated PostgreSQL SQL formatter.
+
+## Requirements
+
+- Ruby >= 3.2.0
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "sql_beautifier"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install sql_beautifier
+```
+
+## Usage
+
+### Basic Formatting
+
+```ruby
+SqlBeautifier.call("SELECT id, name, email FROM users WHERE active = true ORDER BY name")
+```
+
+Produces:
+
+```sql
+select  id,
+        name,
+        email
+
+from    users
+
+where   active = true
+
+order by name
+```
+
+Single-word keywords are lowercased and padded so their clause bodies start at an 8-character column. Multi-word clauses such as `order by` and `group by`, and short clauses like `limit`, use a single space between the keyword and the clause body instead of padding. Each clause is separated by a blank line. Multi-column SELECT lists place each column on its own line with continuation indentation.
+
+### GROUP BY and HAVING
+
+```ruby
+SqlBeautifier.call(<<~SQL)
+  SELECT status, count(*)
+  FROM users
+  GROUP BY status
+  HAVING count(*) > 5
+SQL
+```
+
+Produces:
+
+```sql
+select  status,
+        count(*)
+
+from    users
+
+group by status
+
+having  count(*) > 5
+```
+
+### LIMIT
+
+```ruby
+SqlBeautifier.call("SELECT id FROM users ORDER BY created_at DESC LIMIT 25")
+```
+
+Produces:
+
+```sql
+select  id
+
+from    users
+
+order by created_at desc
+
+limit 25
+```
+
+### String Literals
+
+Case is preserved inside single-quoted string literals, and escaped quotes (`''`) are handled correctly:
+
+```ruby
+SqlBeautifier.call("SELECT * FROM users WHERE name = 'O''Brien' AND status = 'Active'")
+```
+
+Produces:
+
+```sql
+select  *
+
+from    users
+
+where   name = 'O''Brien' and status = 'Active'
+```
+
+### Double-Quoted Identifiers
+
+Double-quoted PostgreSQL identifiers are normalized by lowercasing their contents. If the resulting identifier can be safely represented as an unquoted PostgreSQL identifier, the surrounding quotes are removed; otherwise, the quotes are preserved and only the contents are lowercased:
+
+```ruby
+SqlBeautifier.call('SELECT "User_Id", "Full_Name" FROM "Users"')
+```
+
+Produces:
+
+```sql
+select  user_id,
+        full_name
+
+from    users
+```
+
+### Callable Interface
+
+`SqlBeautifier.call` is the public API, making it a valid callable for Rails `normalizes` and anywhere a proc-like object is expected:
+
+```ruby
+class Query < ApplicationRecord
+  normalizes :sql, with: SqlBeautifier
+end
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bin/setup
+```
+
+Run the test suite:
+
+```bash
+rake test
+```
+
+Run the linter:
+
+```bash
+rake lint
+```
+
+Run the full CI suite (tests + linting):
+
+```bash
+rake
+```
+
+Start an interactive console with the gem loaded:
+
+```bash
+bin/console
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kinnell/sql_beautifier.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/sql_beautifier/clauses/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Clauses
+    class Base
+      def self.call(value)
+        new(value).call
+      end
+
+      def initialize(value)
+        @value = value
+      end
+    end
+  end
+end

data/lib/sql_beautifier/clauses/from.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Clauses
+    class From < Base
+      KEYWORD_PREFIX = "from    "
+
+      def call
+        "#{KEYWORD_PREFIX}#{@value.strip}"
+      end
+    end
+  end
+end

data/lib/sql_beautifier/clauses/group_by.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Clauses
+    class GroupBy < Base
+      KEYWORD_PREFIX = "group by "
+
+      def call
+        "#{KEYWORD_PREFIX}#{@value.strip}"
+      end
+    end
+  end
+end

data/lib/sql_beautifier/clauses/having.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Clauses
+    class Having < Base
+      KEYWORD_PREFIX = "having  "
+
+      def call
+        "#{KEYWORD_PREFIX}#{@value.strip}"
+      end
+    end
+  end
+end

data/lib/sql_beautifier/clauses/limit.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Clauses
+    class Limit < Base
+      KEYWORD_PREFIX = "limit "
+
+      def call
+        "#{KEYWORD_PREFIX}#{@value.strip}"
+      end
+    end
+  end
+end

data/lib/sql_beautifier/clauses/order_by.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Clauses
+    class OrderBy < Base
+      KEYWORD_PREFIX = "order by "
+
+      def call
+        "#{KEYWORD_PREFIX}#{@value.strip}"
+      end
+    end
+  end
+end

data/lib/sql_beautifier/clauses/select.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Clauses
+    class Select < Base
+      KEYWORD_PREFIX = "select  "
+      CONTINUATION_INDENT = "        "
+
+      def call
+        columns = Tokenizer.split_by_top_level_commas(@value)
+        return "#{KEYWORD_PREFIX}#{columns.first.strip}" if columns.length == 1
+
+        column_lines = columns.map { |column| "#{CONTINUATION_INDENT}#{column.strip}" }
+        column_lines[0] = "#{KEYWORD_PREFIX}#{columns.first.strip}"
+
+        column_lines.join(",\n")
+      end
+    end
+  end
+end

data/lib/sql_beautifier/clauses/where.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Clauses
+    class Where < Base
+      KEYWORD_PREFIX = "where   "
+
+      def call
+        "#{KEYWORD_PREFIX}#{@value.strip}"
+      end
+    end
+  end
+end

data/lib/sql_beautifier/constants.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Constants
+    CLAUSE_KEYWORDS = [
+      "select",
+      "from",
+      "where",
+      "group by",
+      "having",
+      "order by",
+      "limit",
+    ].freeze
+  end
+end

data/lib/sql_beautifier/formatter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  class Formatter
+    def self.call(value)
+      new(value).call
+    end
+
+    def initialize(value)
+      @value = value
+    end
+
+    def call
+      return unless @value.present?
+
+      @normalized_value = Normalizer.call(@value)
+      return unless @normalized_value.present?
+
+      first_clause_position = Tokenizer.first_clause_position(@normalized_value)
+      return "#{@normalized_value}\n" if first_clause_position.nil? || first_clause_position.positive?
+
+      @clauses = Tokenizer.split_into_clauses(@normalized_value)
+      @parts = []
+
+      append_clause!(:select, Clauses::Select)
+      append_clause!(:from, Clauses::From)
+      append_clause!(:where, Clauses::Where)
+      append_clause!(:group_by, Clauses::GroupBy)
+      append_clause!(:having, Clauses::Having)
+      append_clause!(:order_by, Clauses::OrderBy)
+      append_clause!(:limit, Clauses::Limit)
+
+      output = @parts.join("\n\n")
+      return "#{@normalized_value}\n" if output.empty?
+
+      "#{output}\n"
+    end
+
+    private
+
+    def append_clause!(clause_key, formatter_class)
+      value = @clauses[clause_key]
+      return unless value.present?
+
+      @parts << formatter_class.call(value)
+    end
+  end
+end

data/lib/sql_beautifier/normalizer.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  class Normalizer
+    SAFE_UNQUOTED_IDENTIFIER = %r{\A[[:lower:]_][[:lower:][:digit:]_]*\z}
+
+    def self.call(value)
+      new(value).call
+    end
+
+    def initialize(value)
+      @value = value
+    end
+
+    def call
+      return unless @value.present?
+
+      @source = @value.strip
+      return unless @source.present?
+
+      @output = +""
+      @position = 0
+
+      while @position < @source.length
+        case current_character
+        when "'"
+          consume_string_literal!
+
+        when '"'
+          consume_quoted_identifier!
+
+        when %r{\s}
+          collapse_whitespace!
+
+        else
+          @output << current_character.downcase
+          @position += 1
+        end
+      end
+
+      @output
+    end
+
+    private
+
+    def current_character
+      @source[@position]
+    end
+
+    def collapse_whitespace!
+      @output << " "
+      @position += 1
+      @position += 1 while @position < @source.length && @source[@position] =~ %r{\s}
+    end
+
+    def consume_string_literal!
+      @output << current_character
+      @position += 1
+
+      while @position < @source.length
+        character = current_character
+        @output << character
+
+        if character == "'" && @source[@position + 1] == "'"
+          @position += 1
+          @output << current_character
+        elsif character == "'"
+          @position += 1
+          return
+        end
+
+        @position += 1
+      end
+    end
+
+    def consume_quoted_identifier!
+      start_position = @position
+      identifier = +""
+      @position += 1
+
+      while @position < @source.length
+        character = current_character
+
+        if character == '"' && @source[@position + 1] == '"'
+          identifier << '"'
+          @position += 2
+        elsif character == '"'
+          @position += 1
+          @output << format_identifier(identifier)
+          return
+        else
+          identifier << character
+          @position += 1
+        end
+      end
+
+      @position = start_position
+      @output << current_character.downcase
+      @position += 1
+    end
+
+    def format_identifier(identifier)
+      lowercased = identifier.downcase
+
+      if requires_quoting?(lowercased)
+        "\"#{lowercased.gsub('"', '""')}\""
+      else
+        lowercased
+      end
+    end
+
+    def requires_quoting?(identifier)
+      identifier !~ SAFE_UNQUOTED_IDENTIFIER
+    end
+  end
+end

data/lib/sql_beautifier/tokenizer.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Tokenizer
+    IDENTIFIER_CHARACTER = %r{[[:alnum:]_$]}
+
+    module_function
+
+    def find_top_level_keyword(sql, keyword)
+      keyword_pattern = %r{#{Regexp.escape(keyword)}}i
+      search_position = 0
+
+      while search_position < sql.length
+        match = sql.match(keyword_pattern, search_position)
+        return nil unless match
+
+        match_position = match.begin(0)
+
+        previous_character = match_position.zero? ? nil : sql[match_position - 1]
+        next_character = match_position + keyword.length >= sql.length ? nil : sql[match_position + keyword.length]
+
+        return match_position if word_boundary?(previous_character) && word_boundary?(next_character) && top_level?(sql, match_position)
+
+        search_position = match_position + 1
+      end
+
+      nil
+    end
+
+    def first_clause_position(sql)
+      Constants::CLAUSE_KEYWORDS.filter_map { |keyword| find_top_level_keyword(sql, keyword) }.min
+    end
+
+    def split_into_clauses(sql)
+      boundaries = Constants::CLAUSE_KEYWORDS.filter_map do |keyword|
+        keyword_position = find_top_level_keyword(sql, keyword)
+        next unless keyword_position
+
+        {
+          keyword: keyword,
+          position: keyword_position,
+        }
+      end
+
+      boundaries.sort_by! { |boundary| boundary[:position] }
+
+      clauses = {}
+
+      boundaries.each_with_index do |boundary, boundary_index|
+        content_start = boundary[:position] + boundary[:keyword].length
+        content_end = boundary_index + 1 < boundaries.length ? boundaries[boundary_index + 1][:position] : sql.length
+        clause_symbol = boundary[:keyword].tr(" ", "_").to_sym
+
+        clauses[clause_symbol] = sql[content_start...content_end].strip
+      end
+
+      clauses
+    end
+
+    def split_by_top_level_commas(text)
+      segments = []
+      current_segment = +""
+      parenthesis_depth = 0
+      inside_string_literal = false
+      inside_quoted_identifier = false
+      position = 0
+
+      while position < text.length
+        character = text[position]
+
+        if inside_string_literal
+          current_segment << character
+
+          if character == "'" && text[position + 1] == "'"
+            position += 1
+            current_segment << text[position]
+          elsif character == "'"
+            inside_string_literal = false
+          end
+
+          position += 1
+          next
+        end
+
+        if inside_quoted_identifier
+          current_segment << character
+
+          if character == '"' && text[position + 1] == '"'
+            position += 1
+            current_segment << text[position]
+          elsif character == '"'
+            inside_quoted_identifier = false
+          end
+
+          position += 1
+          next
+        end
+
+        case character
+        when "'"
+          inside_string_literal = true
+          current_segment << character
+
+        when '"'
+          inside_quoted_identifier = true
+          current_segment << character
+
+        when "("
+          parenthesis_depth += 1
+          current_segment << character
+
+        when ")"
+          parenthesis_depth = [parenthesis_depth - 1, 0].max
+          current_segment << character
+
+        when ","
+          if parenthesis_depth.zero?
+            segments << current_segment.strip
+            current_segment = +""
+          else
+            current_segment << character
+          end
+
+        else
+          current_segment << character
+        end
+
+        position += 1
+      end
+
+      segments << current_segment.strip unless current_segment.strip.empty?
+      segments
+    end
+
+    def word_boundary?(character)
+      character.nil? || character !~ IDENTIFIER_CHARACTER
+    end
+
+    def top_level?(sql, target_position)
+      parenthesis_depth = 0
+      inside_string_literal = false
+      inside_quoted_identifier = false
+      position = 0
+
+      while position < target_position
+        character = sql[position]
+
+        if inside_string_literal
+          if character == "'" && sql[position + 1] == "'"
+            position += 2
+            next
+          elsif character == "'"
+            inside_string_literal = false
+          end
+
+          position += 1
+          next
+        end
+
+        if inside_quoted_identifier
+          if character == '"' && sql[position + 1] == '"'
+            position += 2
+            next
+          elsif character == '"'
+            inside_quoted_identifier = false
+          end
+
+          position += 1
+          next
+        end
+
+        case character
+        when "'"
+          inside_string_literal = true
+        when '"'
+          inside_quoted_identifier = true
+        when "("
+          parenthesis_depth += 1
+        when ")"
+          parenthesis_depth = [parenthesis_depth - 1, 0].max
+        end
+
+        position += 1
+      end
+
+      parenthesis_depth.zero? && !inside_string_literal && !inside_quoted_identifier
+    end
+  end
+end

data/lib/sql_beautifier/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  VERSION = "0.1.1"
+end

data/lib/sql_beautifier.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+require_relative "sql_beautifier/version"
+require_relative "sql_beautifier/constants"
+require_relative "sql_beautifier/normalizer"
+require_relative "sql_beautifier/tokenizer"
+require_relative "sql_beautifier/clauses/base"
+require_relative "sql_beautifier/clauses/select"
+require_relative "sql_beautifier/clauses/from"
+require_relative "sql_beautifier/clauses/where"
+require_relative "sql_beautifier/clauses/group_by"
+require_relative "sql_beautifier/clauses/order_by"
+require_relative "sql_beautifier/clauses/having"
+require_relative "sql_beautifier/clauses/limit"
+require_relative "sql_beautifier/formatter"
+
+module SqlBeautifier
+  class Error < StandardError; end
+
+  module_function
+
+  def call(value)
+    return unless value.present?
+
+    Formatter.call(value)
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: sql_beautifier
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Kinnell Shah
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: 'Formats raw SQL into a clean, consistent style with lowercase keywords,
+  padded keyword alignment, and vertically separated clauses.
+
+  '
+email:
+- kinnell@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/sql_beautifier.rb
+- lib/sql_beautifier/clauses/base.rb
+- lib/sql_beautifier/clauses/from.rb
+- lib/sql_beautifier/clauses/group_by.rb
+- lib/sql_beautifier/clauses/having.rb
+- lib/sql_beautifier/clauses/limit.rb
+- lib/sql_beautifier/clauses/order_by.rb
+- lib/sql_beautifier/clauses/select.rb
+- lib/sql_beautifier/clauses/where.rb
+- lib/sql_beautifier/constants.rb
+- lib/sql_beautifier/formatter.rb
+- lib/sql_beautifier/normalizer.rb
+- lib/sql_beautifier/tokenizer.rb
+- lib/sql_beautifier/version.rb
+homepage: https://github.com/kinnell/sql_beautifier
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kinnell/sql_beautifier
+  github_repo: https://github.com/kinnell/sql_beautifier
+  source_code_uri: https://github.com/kinnell/sql_beautifier
+  changelog_uri: https://github.com/kinnell/sql_beautifier/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kinnell/sql_beautifier/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+requirements: []
+rubygems_version: 4.0.9
+specification_version: 4
+summary: Opinionated PostgreSQL SQL formatter
+test_files: []