rails-query-command 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 04c9d9094284ac4f93952cfcdd3ecd4649d430ef7c187a74b5056cd845c90997
+  data.tar.gz: 54c59107e0b483c4be257be924202c5971b0c361bf3caba7dd4b4f852d6dd16a
+SHA512:
+  metadata.gz: 2339fe0e1cdb277aa9b13c0c3a575a18b15c9eb6754fe44b373851161c88f80f1623f0f2110f8785ab948fa2ef41fc6fa59667b13bb19fe1ce9f30ed42f7e9ec
+  data.tar.gz: f97379b216efa767e874c5de05deb27bccdfd436ecbae7633a5ef497608aec4b1f65fdc2e20bef272218f17a9e2d59b54b5fdd3597d86a159685ed7b02ad49ca

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release. Backports `bin/rails query` from rails/rails `main` at
+  [`e9aab74b13`](https://github.com/rails/rails/commit/e9aab74b13) (originally
+  [#57156](https://github.com/rails/rails/pull/57156)) for Rails 7.2, 8.0 and 8.1.

data/LICENSE.txt

@@ -0,0 +1,25 @@
+Copyright (c) 2026 Lázaro Nixon Amaral de Almeida
+
+The query command and its tests are taken from Ruby on Rails
+(https://github.com/rails/rails), which is released under the MIT License:
+
+Copyright (c) David Heinemeier Hansson
+
+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,98 @@
+# rails-query-command
+
+A backport of `bin/rails query` for **Rails 7.2, 8.0 and 8.1**.
+
+`rails query` was added to Rails in [rails/rails#57156](https://github.com/rails/rails/pull/57156) and is planned for Rails 8.2. It runs read-only database queries and prints structured JSON, so agents and scripts can query a database (for example with `kamal app exec`) without risking writes or parsing free-form `rails runner` output.
+
+This gem ships the command exactly as it is on Rails `main` (commit [`e9aab74b13`](https://github.com/rails/rails/commit/e9aab74b13)), including the fixes merged after the original PR.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "rails-query-command"
+```
+
+You don't need any setup. `bin/rails` finds the command on the load path, and it shows up in `bin/rails --help`.
+
+**Upgrading to Rails 8.2:** the command is built into Rails 8.2, so remove this gem when you upgrade. The gemspec requires `railties < 8.2`, so Bundler will remind you.
+
+## Usage
+
+```bash
+# Active Record expressions
+bin/rails query "Account.where(plan: 'premium').limit(10)"
+bin/rails query "Account.count"
+
+# Raw SQL
+bin/rails query --sql "SELECT id, name FROM accounts"
+
+# Read from stdin
+echo "Account.first" | bin/rails query -
+
+# Pagination (default: --page 1 --per 100, max per page 10000)
+bin/rails query "Account.all" --page 2 --per 50
+
+# Introspection
+bin/rails query schema              # list tables
+bin/rails query schema accounts     # columns, indexes, enums, associations
+bin/rails query models              # models with table names and associations
+bin/rails query explain "Account.where(plan: 'premium')"
+
+# Pick a database config in a multi-database app
+bin/rails query "Account.count" --database primary_replica
+
+# Pretty-print / CSV with jq
+bin/rails query "Account.first" | jq
+bin/rails query "Account.limit(5)" | jq -r '.rows[] | @csv'
+```
+
+The output looks like this:
+
+```json
+{
+  "columns": ["id", "name", "plan"],
+  "rows": [[1, "Acme", "premium"], [2, "Widgets Co", "premium"]],
+  "meta": {
+    "row_count": 2,
+    "query_time_ms": 4.2,
+    "page": 1,
+    "per_page": 100,
+    "has_more": false,
+    "sql": "SELECT \"accounts\".* FROM \"accounts\" WHERE \"accounts\".\"plan\" = 'premium' LIMIT 101"
+  }
+}
+```
+
+Errors are also JSON, written to stderr, and the command exits with status 1:
+
+```json
+{"error": "Write query attempted while in readonly mode: INSERT INTO posts (title) VALUES ('x') LIMIT 101", "meta": {"query_time_ms": 0}}
+```
+
+## Safety
+
+- If a `reading` role is configured, queries run against it. Otherwise they run inside `while_preventing_writes`, so `INSERT`, `UPDATE`, `DELETE`, `Post.delete_all` and `record.update!` are rejected.
+- Active Record expressions are evaluated as Ruby, so they're as trusted as `rails runner` and `rails console`. Write protection covers the database, not arbitrary Ruby. Use `--sql` when you only want SQL to run.
+- Every query is wrapped in a `query.rails` `ActiveSupport::Notifications` event with an `expression` payload, which you can use for audit logging:
+
+  ```ruby
+  ActiveSupport::Notifications.subscribe("query.rails") do |event|
+    Rails.logger.info("rails query: #{event.payload[:expression]}")
+  end
+  ```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test                                              # Rails 8.1
+RAILS_VERSION=8.0 bundle update && RAILS_VERSION=8.0 bundle exec rake test
+RAILS_VERSION=7.2 bundle update && RAILS_VERSION=7.2 bundle exec rake test
+```
+
+The tests are ported from `railties/test/commands/query_test.rb`. Each test runs the real `bin/rails query` against a fresh copy of the app in `test/dummy`.
+
+## License
+
+MIT. The command and its tests come from [Ruby on Rails](https://github.com/rails/rails) and are © David Heinemeier Hansson. See `LICENSE.txt`.

data/lib/rails/commands/query/USAGE

@@ -0,0 +1,51 @@
+Description:
+    Run read-only queries against your database. Connects to the
+    reading replica role by default and prevents database writes.
+
+    The --sql flag restricts execution to SQL only. ActiveRecord
+    expressions are evaluated as Ruby, with the same trust model
+    as rails runner and rails console.
+
+    Output is JSON. Pipe through jq for human-readable formatting.
+
+Subcommands:
+    <%= executable %> schema [TABLE]      Show tables or table detail with associations
+    <%= executable %> models              List ActiveRecord models with associations
+    <%= executable %> explain EXPRESSION  Show EXPLAIN output
+
+Examples:
+    Run an ActiveRecord query:
+
+        <%= executable %> "Account.where(plan: 'premium').limit(10)"
+
+    Pretty-print with jq:
+
+        <%= executable %> "Account.first" | jq
+
+    Extract just the rows:
+
+        <%= executable %> "Account.limit(5)" | jq -r '.rows[] | @csv'
+
+    Run raw SQL:
+
+        <%= executable %> --sql "SELECT * FROM accounts LIMIT 10"
+
+    Paginate results:
+
+        <%= executable %> "Account.all" --page 2 --per 50
+
+    Use a specific database config:
+
+        <%= executable %> "Account.count" --database primary_replica
+
+    Schema introspection:
+
+        <%= executable %> schema accounts
+
+    List models:
+
+        <%= executable %> models
+
+    Explain a query:
+
+        <%= executable %> explain "Account.where(plan: 'premium')"

data/lib/rails/commands/query/query_command.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+# Backported from rails/rails main (railties/lib/rails/commands/query/query_command.rb
+# at e9aab74b13). Only change: `usage_path` points at this gem's USAGE file.
+
+require "json"
+require "rails/command/environment_argument"
+
+module Rails
+  module Command
+    class QueryCommand < Base # :nodoc:
+      include EnvironmentArgument
+
+      class_option :sql, type: :boolean,
+        desc: "Treat input as raw SQL instead of an Active Record expression"
+
+      class_option :database, aliases: "--db", type: :string,
+        desc: "Database configuration to use (e.g. primary_replica)"
+
+      class_option :page, type: :numeric, default: 1,
+        desc: "Page number for paginated results"
+
+      class_option :per, type: :numeric, default: 100,
+        desc: "Results per page (max 10000)"
+
+      def self.usage_path
+        File.expand_path("USAGE", __dir__)
+      end
+
+      desc "query [EXPRESSION]", "Run a read-only query against the database"
+      def perform(expression = nil, *args)
+        boot_application!
+        Rails.application.load_runner
+
+        ActiveSupport::Notifications.instrument("query.rails", expression: expression) do
+          case expression
+          when "schema"
+            run_schema(args.first)
+          when "models"
+            run_models
+          when "explain"
+            run_explain(args.first)
+          else
+            run_query(expression)
+          end
+        end
+      rescue StandardError, SyntaxError, NotImplementedError => e
+        output_error(e.message)
+        exit 1
+      end
+
+      private
+        def run_schema(table = nil)
+          with_readonly_connection do |connection|
+            if table
+              say format_table_detail(connection, table)
+            else
+              say format_table_list(connection)
+            end
+          end
+        end
+
+        def run_models
+          Rails.application.eager_load!
+
+          models = ActiveRecord::Base.descendants
+            .reject(&:abstract_class?)
+            .select { |model| model.table_name.present? }
+            .sort_by(&:name)
+
+          data = models.map do |model|
+            {
+              model: model.name,
+              table_name: model.table_name,
+              associations: format_associations(model)
+            }
+          end
+
+          say JSON.generate(data)
+        end
+
+        def run_explain(expression = nil)
+          expression = resolve_expression(expression)
+
+          if options[:sql]
+            with_readonly_connection do |connection|
+              result = connection.select_all("EXPLAIN #{expression}")
+              say format_result(columns: result.columns, rows: result.rows, sql: "EXPLAIN #{expression}")
+            end
+          else
+            relation = with_readonly_connection { eval(expression, TOPLEVEL_BINDING, "(query)", 1) }
+            sql = relation.to_sql
+            with_readonly_connection_for(relation.model.connection_class_for_self) do |connection|
+              result = connection.select_all("EXPLAIN #{sql}")
+              say format_result(columns: result.columns, rows: result.rows, sql: "EXPLAIN #{sql}")
+            end
+          end
+        end
+
+        def run_query(expression)
+          expression = resolve_expression(expression)
+          page = [ options[:page], 1 ].max
+          per = [ [ options[:per], 1 ].max, 10_000 ].min
+
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          result = if options[:sql]
+            with_readonly_connection do |connection|
+              execute_sql(connection: connection, sql: expression, page: page, per: per)
+            end
+          else
+            execute_expression(expression: expression, page: page, per: per)
+          end
+
+          elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(1)
+
+          say format_result(**result, elapsed_ms: elapsed_ms, page: page, per: per)
+        end
+
+        def with_readonly_connection(&block)
+          with_readonly_connection_for(ActiveRecord::Base, &block)
+        end
+
+        def with_readonly_connection_for(connection_class, &block)
+          if options[:database]
+            with_explicit_database(options[:database], &block)
+          elsif reading_role_available?(connection_class)
+            connection_class.connected_to(role: :reading) do
+              connection_class.with_connection(&block)
+            end
+          else
+            connection_class.while_preventing_writes do
+              connection_class.with_connection(&block)
+            end
+          end
+        end
+
+        def with_explicit_database(database)
+          original = ActiveRecord::Base.connection_db_config
+          begin
+            ActiveRecord::Base.establish_connection(database.to_sym)
+            ActiveRecord::Base.while_preventing_writes do
+              yield ActiveRecord::Base.lease_connection
+            end
+          ensure
+            ActiveRecord::Base.establish_connection(original)
+          end
+        end
+
+        def reading_role_available?(connection_class)
+          connection_class.connected_to(role: :reading) do
+            connection_class.lease_connection
+          end
+          true
+        rescue ActiveRecord::ConnectionNotEstablished
+          false
+        end
+
+        def execute_sql(connection:, sql:, page:, per:)
+          unless sql.gsub(/--[^\n]*|\/\*.*?\*\//m, "").match?(/\bLIMIT\b/i)
+            offset = (page - 1) * per
+            sql = "#{sql.rstrip.chomp(';')} LIMIT #{per + 1}"
+            sql += " OFFSET #{offset}" if offset > 0
+          end
+
+          active_record_result = connection.select_all(sql)
+          rows = active_record_result.rows
+
+          tabular_result(columns: active_record_result.columns, rows: rows.first(per), sql: sql, truncated: rows.length > per)
+        end
+
+        def execute_expression(expression:, page:, per:)
+          result = with_readonly_connection { eval(expression, TOPLEVEL_BINDING, "(query)", 1) }
+          columns, rows, sql, truncated = tabular_result_parts_for(result, expression: expression, page: page, per: per)
+
+          tabular_result(columns: columns, rows: rows, sql: sql, truncated: truncated)
+        end
+
+        def tabular_result_parts_for(result, expression:, page:, per:)
+          case result
+          when ActiveRecord::Relation
+            relation = if result.limit_value
+              result
+            else
+              result.offset((page - 1) * per).limit(per + 1)
+            end
+            relation_sql = relation.to_sql
+
+            with_readonly_connection_for(relation.model.connection_class_for_self) do |connection|
+              active_record_result = connection.select_all(relation_sql)
+              rows = active_record_result.rows
+
+              [ active_record_result.columns, rows.first(per), relation_sql, rows.length > per ]
+            end
+          when ActiveRecord::Result
+            [ result.columns, result.rows, expression, false ]
+          when ActiveRecord::Base
+            attributes = result.attributes
+
+            [ attributes.keys, [ attributes.values ], expression, false ]
+          when Hash
+            [ [ "key", "value" ], result.map { |key, val| [ key, val ] }, expression, false ]
+          when Array
+            peek_on_result = result.first
+
+            if peek_on_result.is_a?(ActiveRecord::Base)
+              columns = peek_on_result.attribute_names
+              rows = result.map { |record| record.attributes.values }
+            else
+              rows = result.map { |value| Array(value) }
+              columns = Array.new(rows.first&.length.to_i) { |index| "column_#{index}" }
+            end
+
+            [ columns, rows, expression, false ]
+          else
+            [ [ "result" ], [ [ result ] ], expression, false ]
+          end
+        end
+
+        def tabular_result(columns:, rows:, sql:, truncated: false)
+          { columns: columns, rows: rows, sql: sql, truncated: truncated }
+        end
+
+        def format_result(columns:, rows:, sql:, elapsed_ms: 0, page: 1, per: rows.length, truncated: false)
+          JSON.generate({
+            columns: columns,
+            rows: rows,
+            meta: {
+              row_count: rows.length,
+              query_time_ms: elapsed_ms,
+              page: page,
+              per_page: per,
+              has_more: truncated,
+              sql: sql
+            }
+          })
+        end
+
+        def format_table_list(connection)
+          tables = connection.tables.sort
+          rows = tables.map { |table| [ table ] }
+
+          format_result(columns: [ "table_name" ], rows: rows, sql: "")
+        end
+
+        def format_table_detail(connection, table)
+          raise ArgumentError, "Table '#{table}' does not exist" unless connection.table_exists?(table)
+
+          columns = connection.columns(table)
+          indexes = connection.indexes(table)
+          model = model_for_table(table)
+
+          JSON.generate({
+            table: table,
+            columns: columns.map do |col|
+              { name: col.name, type: col.sql_type, null: col.null, default: col.default }
+            end,
+            indexes: indexes.map do |idx|
+              { name: idx.name, columns: idx.columns, unique: idx.unique }
+            end,
+            enums: model&.defined_enums.presence,
+            associations: format_associations(model)
+          }.compact)
+        end
+
+        def model_for_table(table)
+          Rails.application.eager_load!
+
+          ActiveRecord::Base.descendants.find do |klass|
+            !klass.abstract_class? && klass.table_name == table
+          end
+        end
+
+        def format_associations(model)
+          return unless model
+
+          model.reflect_on_all_associations.map do |assoc|
+            hash = {
+              type: assoc.macro,
+              name: assoc.name,
+              class_name: assoc.class_name
+            }
+            hash[:foreign_key] = assoc.foreign_key if assoc.respond_to?(:foreign_key)
+            hash[:through] = assoc.through_reflection.name if assoc.through_reflection?
+            hash
+          end
+        end
+
+        def resolve_expression(expression)
+          if expression == "-" || (expression.nil? && !$stdin.tty?)
+            $stdin.read.strip
+          elsif expression
+            expression
+          else
+            raise ArgumentError, "No query expression provided. Run '#{self.class.executable} -h' for help."
+          end
+        end
+
+        def output_error(message)
+          error JSON.generate({
+            error: message,
+            meta: { query_time_ms: 0 }
+          })
+        end
+    end
+  end
+end

data/lib/rails_query_command/version.rb

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

data/lib/rails_query_command.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The command itself lives at lib/rails/commands/query/query_command.rb and is
+# discovered by `bin/rails` through the load path; nothing needs to be required here.
+require "rails_query_command/version"

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: rails-query-command
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lázaro Nixon Amaral de Almeida
+bindir: bin
+cert_chain: []
+date: 2026-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+description: |
+  Adds the `bin/rails query` command from Rails main (rails/rails#57156) to apps running
+  Rails 7.2, 8.0 and 8.1. Runs Active Record expressions or raw SQL against a read-only
+  connection and prints structured JSON, with pagination and schema/model introspection.
+email:
+- lazaronixon@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/rails/commands/query/USAGE
+- lib/rails/commands/query/query_command.rb
+- lib/rails_query_command.rb
+- lib/rails_query_command/version.rb
+homepage: https://github.com/lazaronixon/rails-query-command
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/lazaronixon/rails-query-command
+  changelog_uri: https://github.com/lazaronixon/rails-query-command/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Backport of `bin/rails query` (read-only JSON database queries) for Rails
+  7.2, 8.0 and 8.1.
+test_files: []