render_sql 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 79e1fd7e1a9c5b7dff2b66880e5ee967c22a82014c7f6b8a8cc2672c6e99ecfd
+  data.tar.gz: 732d844fbf23393b21b9a77b263b467d38d3cb9524b7790b926f2dff2eb43400
+SHA512:
+  metadata.gz: 94e7ffc62d42432319817b8a3409a68ad38a3e4fcbd54fc3c6f3247fb86a968e3f76fc796c45461b4b7e3b697cc5ebd6582d8c9d6154740036b0337e92e6cae6
+  data.tar.gz: d28a482b7d9241894a817c4f86a046075df5bb87cc59cf809453385e522a50b20531410a083e2d59ed2b83f1a8967716d10327a7b6963db815b96f8ff9adbb04

data/README.md

@@ -0,0 +1,125 @@
+# RenderSQL
+
+Rails Engine to treat SQL files as user-facing views.
+
+Often times —usually in an "admin" context— one needs to display data to users.
+SQL is a quick way to retrieve the data but _your users_ need (semi)pretty HTML displays.
+This means you have to create a view file, maybe convert it to an ActiveRecord query or paste it
+into a `.find_by_sql` call etc... Sometimes in lieu of writing an HTML view you'll
+"compromise" and export to CSV.
+
+With RenderSQL just create an SQL file. The result will be automatically displayed in an HTML table.
+
+## Usage
+
+In your `Gemfile`:
+
+```rb
+gem "render_sql"
+```
+
+Define an action and route in a controller:
+
+```rb
+class UsersController
+  def must_upgrade
+  end
+end
+```
+
+Create an SQL file named `must_upgrade.sql` with a query:
+
+```sql
+select id, name, monthly_payment from users where monthly_payment < 5 order by created_at desc
+```
+
+Now when you visit the `#must_upgrade` action the query will be executed and its result placed in an HTML table
+using the current controller's layout.
+
+The selected column names will be used for the HTML table's headers. If you need something pretty create column aliases:
+
+```sql
+select id, name 'Full Name', monthly_payment 'Monthly Payment' from users where monthly_payment < 5 order by created_at desc
+```
+
+If you want to use a single action for multiple SQL files:
+
+```rb
+class UsersController
+  KNOWN_REPORTS = %w[monthly weekly yearly].freeze
+
+  # Don't forget to define the route
+  def reports
+    if KNOWN_REPORTS.include?(params[:report])
+      render params[:report]
+    else
+      render :plain => "Unknown report", :status => 400
+    end
+  end
+end
+```
+
+Then create 3 SQL files `monthly.sql`, `weekly.sql`, `yearly.sql` containing the respective queries.
+
+The page's heading will be the SQL file's basename, titleized.
+
+
+### Query Placeholders
+
+Supported only for where clauses. For example:
+
+```sql
+select id, name from users where created_at < :created_at limit 50
+```
+
+Now when the associated controller action is accessed one must provide a value for the `created_at` parameter.
+
+If a required placeholder is missing a `RenderSQL::MissingParameter` error will be raised.
+
+### View Customization
+
+You can override some things in your app's `application.rb` file:
+
+```rb
+module YourApp
+  class Application < Rails::Application
+    config.render_sql.css_classes[:table] = "table"
+    config.render_sql.css_classes[:container] = "container py-4"
+    config.render_sql.css_classes[:heading] = "mb-2"
+    config.render_sql.partial = "your-partial"
+  end
+end
+```
+
+The partial will be provided with a `result` variable:
+
+```erb
+<table>
+  <tr>
+    <% result.headers.each do |header| %>
+      <th><%= h(header) %></th>
+    <% end %>
+  </tr>
+  <% result.each do |row| %>
+    <tr>
+      <% row.each do |cell| %>
+        <td><%= h(cell) %></td>
+      <% end %>
+    </tr>
+  <% end %>
+</table>
+```
+
+## Limitations
+
+- No pagination
+- Placeholders only for where criteria
+- Rails >= 6.1
+
+## Author
+
+Skye Shaw [skye.shaw -AT- gmail.com]
+
+## License
+
+Released under the MIT License: http://www.opensource.org/licenses/MIT

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"

data/lib/render_sql/engine.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RenderSQL
+  class Engine < ::Rails::Engine
+    isolate_namespace RenderSQL
+
+    config.render_sql = ActiveSupport::OrderedOptions.new.tap do |c|
+      c.partial = nil
+      c.css_classes = {
+        :heading => "render-sql-heading",
+        :table => "render-sql-results",
+        :container => "render-sql-container"
+      }
+    end
+
+    initializer "render_sql.register_template_handler" do
+      ActionView::Template.register_template_handler(:sql, RenderSQL::TemplateHandler)
+    end
+  end
+end

data/lib/render_sql/query.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RenderSQL
+  class Query                   # :nodoc:
+    Result = Struct.new(:headers, :rows) do
+      include Enumerable
+
+      def each(&block)
+        return rows.to_enum(:each) unless block_given?
+
+        rows.each(&block)
+      end
+    end
+
+    class << self
+      def execute(sql, params)
+        result = ActiveRecord::Base.connection.select_all(sanitize(sql, params))
+        Result.new(result.columns, result.rows)
+      end
+
+      private
+
+      def sanitize(sql, params)
+        values = []
+
+        query = sql.gsub(/:(\w+)/) do
+          name = $1.to_sym
+          raise RenderSQL::MissingParameter, "Missing required query parameter: #{name}" unless params[name]
+
+          values << params[name]
+
+          "?"
+        end
+
+        ActiveRecord::Base.sanitize_sql_array([query, *values])
+      end
+    end
+  end
+end

data/lib/render_sql/template_handler.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "render_sql/query"
+
+module RenderSQL
+  class TemplateHandler
+    DEFAULT_CSS = <<-CSS
+      <style>
+        table.render-sql-results {
+          border-collapse: collapse;
+          width: 100%;
+        }
+
+        table.render-sql-results th, table.render-sql-results td {
+          border: 1px solid #ccc;
+          padding: 8px;
+        }
+
+        table.render-sql-results th {
+          text-align: left;
+          background-color: #f2f2f2;
+        }
+      </style>
+    CSS
+
+    DEFAULT_TEMPLATE = <<-ERB
+      <div class="<%= css[:container] %>">
+        <h1 class="<%= css[:heading] %>"><%= heading %></h1>
+        <table class="<%= css[:table] %>">
+          <thead>
+            <tr>
+              <% result.headers.each do |header| %>
+                <th><%= h(header) %></th>
+              <% end %>
+            </tr>
+          </thead>
+          <tbody>
+            <% result.each do |row| %>
+              <tr>
+                <% row.each do |cell| %>
+                  <td><%= h(cell) %></td>
+                <% end %>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+    ERB
+
+    class << self
+      def call(template, source = nil)
+        sql = source || template.source
+
+        <<-TEMPLATE
+          begin
+            config = Rails.application.config.render_sql
+            heading = File.basename(#{template.short_identifier.inspect}, ".sql").titleize
+            result = RenderSQL::Query.execute(#{sql.inspect}, params)
+
+            if config.partial
+              render :partial => config.partial, :locals => { :css => config.css_classes, :result => result }
+            else
+              css = config.css_classes
+              ERB.new(#{DEFAULT_CSS.inspect + DEFAULT_TEMPLATE.inspect}).result(binding)
+            end
+          rescue ActiveRecord::StatementInvalid => e
+            "<p style='color: red'>SQL Error: \#{h(e.message)}</p>"
+          end
+        TEMPLATE
+      end
+    end
+  end
+end

data/lib/render_sql/version.rb

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

data/lib/render_sql.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "render_sql/engine"
+require "render_sql/template_handler"
+
+module RenderSQL
+  Error = Class.new(StandardError)
+  MissingParameter = Class.new(Error)
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: render_sql
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Skye Shaw
+bindir: bin
+cert_chain: []
+date: 2026-01-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+email:
+- skye.shaw@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/render_sql.rb
+- lib/render_sql/engine.rb
+- lib/render_sql/query.rb
+- lib/render_sql/template_handler.rb
+- lib/render_sql/version.rb
+homepage: https://github.com/sshaw/render_sql
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sshaw/render_sql
+  source_code_uri: https://github.com/sshaw/render_sql
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Rails engine for rendering SQL files as user-facing views
+test_files: []