taql 0.3.7 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66db91199e02a0312a18f93208174c5ef48002e60415d0b36680c6eaa3a02d61
-  data.tar.gz: 31358e92a67034c323975e931ab54102d6ee3cb40f5bb191fa06f5e7687f8414
+  metadata.gz: a347baf32a9b92dccb94907b40b42d35d00a5f8929f5938842e774d0dfe810a6
+  data.tar.gz: 261b1878bc277f27c9d803a675f7ccc085c71eea9639bcdcdd8e6d44b28d5c82
 SHA512:
-  metadata.gz: 7c68d0a8f118fac312d48864fa64e56dc5d56b0ffc26dfb7b56196a8bc18387517c5d1f9fb69c8835bf84514962b49a7756b01a3e7f55f777e673a61b342953c
-  data.tar.gz: 43f2896a0c7d00455ff599425e5b22d08e0f837950fa8af44e239dfdf37a05db7e83776726ff21417642252617aabfeb852fdaf4e752af8b98c135155991565c
+  metadata.gz: f0aa1e50f2e9adfcc0013fe53d2a16d44f1b67cb3204c14f86cdff0c30a6e5b213eb5710c1573aa8be0cc1080f057b77e050882b762d23fb1f86b6f5f8e14cdb
+  data.tar.gz: 817431a4c417af5c022fc893e0e40b5c8501f0e1470f64e5049b0a916cf20c448d574b48e62562c5e4f2b15bf150724c8ad5aa0f72cc404c6cfd928bcc64c87b

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.5.0] - 2026-03-11
+
+- Auto-switch to vertical list layout when table exceeds terminal width
+- Add List class for vertical output formatting
+- Right-align headers in vertical list output
+
+## [0.4.0] - 2026-03-11
+
+- Fix CLI to use passed argv instead of global ARGV
+- Fix CLI to use ActiveRecord connection directly after booting Rails
+- Memoize Table headers, columns, and column_widths
+- Fix headers deduplication for heterogeneous entries
+- Raise error when CLI is invoked without a query
+- Add --version flag to CLI
+- Support Rails 7.2+ lease_connection
+
 ## [0.3.7] - 2025-09-01
 
 - Add Railtie

data/CLAUDE.md

@@ -0,0 +1,34 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## About
+
+Taql is a Ruby gem that formats SQL query results into pretty-printed tables (ASCII or Markdown). Provides both a CLI (`taql "SELECT ..."`) and programmatic API (`Taql.execute(query)`) for use with Rails/ActiveRecord.
+
+## Commands
+
+```bash
+bundle exec rake          # Run tests + lint (default)
+rake test                 # Run all tests (minitest)
+rake test TEST=test/test_table.rb                        # Single test file
+rake test TEST=test/test_table.rb TESTOPTS="--name=test_something"  # Single test method
+rake standard             # Lint (Standard Ruby)
+rake standard:fix         # Auto-fix lint issues
+bin/setup                 # Install dependencies
+```
+
+## Architecture
+
+- `lib/taql.rb` — Main module; `.execute(query, options, connection:)` entry point
+- `lib/taql/table.rb` — Table formatting (ASCII borders + Markdown mode); handles column width calculation
+- `lib/taql/list.rb` — Vertical list formatting; used when table exceeds terminal width
+- `lib/taql/cli.rb` — CLI parser (`--markdown/-m` flag); loads Rails env, calls `Taql.execute`
+- `lib/taql/railtie.rb` — Rails integration; sets `@default_connection` from ActiveRecord pool
+- `exe/taql` — CLI executable entry point
+
+**Flow:** CLI loads Rails environment → parses args → `Taql.execute` uses ActiveRecord connection (from Railtie or explicit) → auto-selects `Table` or `List` based on terminal width → prints formatted output.
+
+## Testing
+
+Tests use Minitest with mocked database connections. Test files mirror lib structure: `test_taql.rb`, `test_table.rb`, `test_list.rb`, `test_cli.rb`. CI runs on Ruby 3.4 via GitHub Actions.

data/README.md

@@ -27,6 +27,13 @@ $ gem install taql
 +----+----------------------+-----------+----------------------+
 ```
 
+Use `--version` (or `-v`) to check the installed version:
+
+```sh
+$ taql --version
+taql 0.4.0
+```
+
 Use the `--markdown` (or `-m`) flag to generate Markdown output:
 
 ```sh
@@ -52,7 +59,7 @@ Any valid SQL SELECT statement can be executed:
 Within a console:
 
 ```ruby
->> Taql.execute("select id, email from users order by created at limit 3").pluck("email")
+>> Taql.execute("select id, email from users order by created_at limit 3").pluck("email")
    (1.2ms)  select id, email from users limit 3
 +----+---------------------+
 | ID | EMAIL               |
@@ -79,6 +86,21 @@ The return value is a native PG::Result object, which supports mapping or extrac
 => #<PG::Result:0x000000012ebf6a38 status=PGRES_TUPLES_OK ntuples=3 nfields=1 cmd_tuples=3>
 ```
 
+When results exceed terminal width, output automatically switches to a vertical list format:
+
+```
+----------------------------------------
+              ID | 1
+           ADMIN | false
+           EMAIL | alice@example.com
+      CREATED_AT | 2021-10-01 00:00:00 UTC
+----------------------------------------
+```
+
+## TODO
+
+- [ ] `--list` / `--table` CLI flags to override auto-detection
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -91,7 +113,7 @@ To release a new version, update the version number in `version.rb`, and then ru
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/taql. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/taql/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/arzezak/taql. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/arzezak/taql/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -99,4 +121,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Taql project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/taql/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Taql project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/arzezak/taql/blob/main/CODE_OF_CONDUCT.md).

data/RELEASING.md

@@ -0,0 +1,7 @@
+# Releasing
+
+1. Update version in `lib/taql/version.rb`
+2. Run `bundle install` to update lockfile
+3. Update `CHANGELOG.md` with new version and changes
+4. Commit: `git commit -am "Release vX.Y.Z"`
+5. Run `bundle exec rake release` (builds gem, creates git tag, pushes to RubyGems)

data/lib/taql/cli.rb

@@ -5,14 +5,17 @@ module Taql
     attr_reader :options, :query
 
     def initialize(argv)
+      @argv = argv
       @options = {markdown: false}
       @query = parse!
+
+      raise ArgumentError, "Usage: taql [--markdown] QUERY" if @query.empty?
     end
 
     def run
       silence { require environment_path }
 
-      Taql.execute(*query, options)
+      Taql.execute(*query, options, connection: ActiveRecord::Base.connection)
     end
 
     private
@@ -24,7 +27,9 @@ module Taql
     def parse!
       OptionParser.new do |parser|
         parser.on("-m", "--markdown", TrueClass, "Output table in Markdown")
-      end.parse!(into: options)
+        parser.program_name = "taql"
+        parser.version = Taql::VERSION
+      end.parse!(@argv, into: options)
     end
 
     def silence

data/lib/taql/list.rb

@@ -0,0 +1,49 @@
+module Taql
+  class List
+    DASH = "-".freeze
+    PIPE = " | ".freeze
+
+    def initialize(entries, terminal_width: nil)
+      @entries = entries.map { |entry| entry.transform_values(&:to_s) }
+      @terminal_width = terminal_width
+    end
+
+    def print
+      output if entries.any?
+    end
+
+    private
+
+    attr_reader :entries
+
+    def headers
+      @headers ||= entries.flat_map(&:keys).uniq
+    end
+
+    def max_header_width
+      @max_header_width ||= headers.map(&:length).max
+    end
+
+    def divider_width
+      @terminal_width&.finite? ? @terminal_width : 32
+    end
+
+    def output
+      records = entries.map { |entry| [separator, *rows(entry)].join("\n") }
+
+      [*records, separator].join("\n")
+    end
+
+    def separator
+      DASH * divider_width
+    end
+
+    def rows(entry)
+      headers.map do |header|
+        "#{header.upcase.rjust(max_header_width)}#{PIPE}#{entry[header]}"
+      end
+    end
+
+    alias_method :to_s, :print
+  end
+end

data/lib/taql/railtie.rb

@@ -6,8 +6,16 @@ module Taql
 
     initializer "taql.initialize" do
       ActiveSupport.on_load(:active_record) do
-        Taql.instance_variable_set(:@default_connection, -> { ActiveRecord::Base.connection_pool.connection })
+        Taql.default_connection = method(:connection)
       end
     end
+
+    def self.connection
+      pool.respond_to?(:lease_connection) ? pool.lease_connection : pool.connection
+    end
+
+    def self.pool
+      ActiveRecord::Base.connection_pool
+    end
   end
 end

data/lib/taql/table.rb

@@ -12,18 +12,22 @@ module Taql
       @markdown = markdown
     end
 
+    def table_width
+      column_widths.sum + (3 * columns.count) + 1
+    end
+
     def body
       entries.map(&:values)
     end
 
     def columns
-      headers.map do |header|
+      @columns ||= headers.map do |header|
         [header, *entries.map { |entry| entry[header] }]
       end
     end
 
     def headers
-      entries.map(&:keys).uniq.flatten
+      @headers ||= entries.flat_map(&:keys).uniq
     end
 
     def print
@@ -43,7 +47,7 @@ module Taql
     end
 
     def column_widths
-      columns.map { |column| column.map(&:length).max }
+      @column_widths ||= columns.map { |column| column.map(&:length).max }
     end
 
     def edge

data/lib/taql/version.rb

@@ -1,3 +1,3 @@
 module Taql
-  VERSION = "0.3.7"
+  VERSION = "0.5.0"
 end

data/lib/taql.rb

@@ -1,20 +1,37 @@
+require "io/console"
 require_relative "taql/cli"
+require_relative "taql/list"
 require_relative "taql/table"
 require_relative "taql/version"
 require_relative "taql/railtie" if defined?(Rails)
 
 module Taql
   class << self
+    attr_writer :default_connection
+
     def execute(query, options = {}, connection: nil)
       (connection || default_connection).execute(query).tap do |result|
         if (results = result.entries).any?
-          $stdout.puts Table.new(results, markdown: options[:markdown])
+          $stdout.puts formatter(results, markdown: options[:markdown])
         end
       end
     end
 
     private
 
+    def formatter(results, markdown: false)
+      table = Table.new(results, markdown: markdown)
+      if !markdown && table.table_width > terminal_width
+        List.new(results, terminal_width: terminal_width)
+      else
+        table
+      end
+    end
+
+    def terminal_width
+      IO.console&.winsize&.last || Float::INFINITY
+    end
+
     def default_connection
       @default_connection&.call || raise("Taql not properly initialized with Rails")
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taql
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 0.5.0
 platform: ruby
 authors:
 - Ariel Rzezak
@@ -18,15 +18,18 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
+- RELEASING.md
 - Rakefile
 - bin/console
 - bin/setup
 - exe/taql
 - lib/taql.rb
 - lib/taql/cli.rb
+- lib/taql/list.rb
 - lib/taql/railtie.rb
 - lib/taql/table.rb
 - lib/taql/version.rb
@@ -52,7 +55,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Tableize Rails SQL queries
 test_files: []