appquery 0.7.0 → 0.8.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5eeb81f992ea777b44680277fcf8ef0d763aa1e8d4d6b1750eb81f9198d5262
-  data.tar.gz: d9939585c40818303e0da886c459ad65c030b2501f8399942cf5b0b2a6d308ab
+  metadata.gz: 220f74299300b813e054b9ef57172083795b14209322ee9d5fbcb9d3de608a04
+  data.tar.gz: '064268f658576f5bf82e05dc97bd51138ccf4c903800296f18eee1c1c4f1c91f'
 SHA512:
-  metadata.gz: 8f5a4abb4f4e38477dba038d927ac19bef2c0b252f41d820e78706ab60bd2d22dcd07ee739781266fa52bb86317f44347a98bae1e109159c5a805c778534602c
-  data.tar.gz: 73f165536629ca28cd7077156ed67ee5b78f6b750fe7c69d62d98c8c6005ba004b770972b600378f7a05be36bb7a5bc214f2bf55a8c7695f509d76971a37dd3d
+  metadata.gz: b79adb014601b0f5c414c2f22935010bcac7b98ca9b452bbdb474ff9208d93f4868866f4a4740c5a8cbcf4bf652559bfc6f53927974b747559ae5aa9379fed8c
+  data.tar.gz: b30ce78b6188bb08b9013655980e54b9e49243f9a69c2a9e5dddc5384ed73508374cea1cdd35e2fa6fd36c792ca0f594f26180b9ed9ac93e5d0d772c003e5344

data/.yard/templates/default/layout/html/footer.erb

@@ -0,0 +1,7 @@
+<div id="footer">
+  AppQuery <%= ENV["APPQUERY_VERSION"] || `git describe --tags --abbrev=0 2>/dev/null`.strip %>
+  &mdash;
+  Generated on <%= Time.now.strftime("%c") %> by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  <%= YARD::VERSION %> (ruby-<%= RUBY_VERSION %>).
+</div>

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## 0.7.0
+
+**Releasedate**: 8-1-2026  
+**Rubygems**: https://rubygems.org/gems/appquery/versions/0.7.0  
+
 ### 💥 Breaking Changes
 
 - ⛔ drop Ruby 3.2 support  

data/lib/app_query/base_query.rb

@@ -154,11 +154,7 @@ module AppQuery
       end
     end
 
-    delegate :select_all, :select_one, :count, :to_s, :column, :first, :ids, to: :query
-
-    def entries
-      select_all
-    end
+    delegate :cte, :entries, :with_select, :select_all, :select_one, :count, :to_s, :column, :first, :ids, :copy_to, to: :query
 
     def query
       @query ||= base_query

data/lib/app_query/paginatable.rb

@@ -46,11 +46,23 @@ module AppQuery
     extend ActiveSupport::Concern
 
     # Kaminari-compatible wrapper for paginated results.
+    #
+    # Wraps an array of records with pagination metadata, providing a consistent
+    # interface for both counted and uncounted pagination modes.
+    #
+    # Includes Enumerable, so all standard iteration methods work directly.
+    #
+    # @example
+    #   result = ArticlesQuery.new.paginate(page: 2).entries
+    #   result.each { |article| puts article["title"] }
+    #   result.current_page # => 2
+    #   result.total_pages  # => 5
     class PaginatedResult
       include Enumerable
 
       delegate :each, :size, :[], :empty?, :first, :last, to: :@records
 
+      # @api private
       def initialize(records, page:, per_page:, total_count: nil, has_next: nil)
         @records = records
         @page = page
@@ -59,23 +71,31 @@ module AppQuery
         @has_next = has_next
       end
 
+      # @return [Integer] the current page number
       def current_page = @page
 
+      # @return [Integer] the number of records per page
       def limit_value = @per_page
 
+      # @return [Integer, nil] the previous page number, or nil if on first page
       def prev_page = (@page > 1) ? @page - 1 : nil
 
+      # @return [Boolean] true if this is the first page
       def first_page? = @page == 1
 
+      # @return [Integer] the total number of records across all pages
+      # @raise [RuntimeError] if called in +without_count+ mode
       def total_count
         @total_count || raise("total_count not available in without_count mode")
       end
 
+      # @return [Integer, nil] the total number of pages, or nil in +without_count+ mode
       def total_pages
         return nil unless @total_count
         (@total_count.to_f / @per_page).ceil
       end
 
+      # @return [Integer, nil] the next page number, or nil if on last page
       def next_page
         if @total_count
           (@page < total_pages) ? @page + 1 : nil
@@ -84,6 +104,7 @@ module AppQuery
         end
       end
 
+      # @return [Boolean] true if this is the last page
       def last_page?
         if @total_count
           @page >= total_pages
@@ -92,10 +113,20 @@ module AppQuery
         end
       end
 
+      # @return [Boolean] true if the requested page is beyond available data
       def out_of_range?
         empty? && @page > 1
       end
 
+      # Transforms each record in place using the given block.
+      #
+      # @yield [record] Block to transform each record
+      # @yieldparam record [Hash] the record to transform
+      # @yieldreturn [Object] the transformed record
+      # @return [self] for chaining
+      #
+      # @example
+      #   result.transform! { |row| OpenStruct.new(row) }
       def transform!
         @records = @records.map { |r| yield(r) }
         self
@@ -108,6 +139,20 @@ module AppQuery
     end
 
     class_methods do
+      # Gets or sets the default number of records per page.
+      #
+      # When called without arguments, returns the current per_page value
+      # (inheriting from superclass if not set, defaulting to 25).
+      #
+      # @param value [Integer, nil] the number of records per page (setter)
+      # @return [Integer] the current per_page value (getter)
+      #
+      # @example
+      #   class ArticlesQuery < ApplicationQuery
+      #     per_page 10
+      #   end
+      #
+      #   ArticlesQuery.per_page # => 10
       def per_page(value = nil)
         if value.nil?
           return @per_page if defined?(@per_page)
@@ -118,6 +163,18 @@ module AppQuery
       end
     end
 
+    # Enables pagination for this query.
+    #
+    # @param page [Integer] page number, starting at 1
+    # @param per_page [Integer] records per page (defaults to class setting)
+    # @param without_count [Boolean] skip COUNT query for large datasets
+    # @return [self] for chaining
+    #
+    # @example Standard pagination with total count
+    #   ArticlesQuery.new.paginate(page: 2, per_page: 20).entries
+    #
+    # @example Fast pagination without count (for large tables)
+    #   ArticlesQuery.new.paginate(page: 1, without_count: true).entries
     def paginate(page: 1, per_page: self.class.per_page, without_count: false)
       @page = page
       @per_page = per_page
@@ -125,28 +182,48 @@ module AppQuery
       self
     end
 
+    # Disables pagination, returning all results.
+    #
+    # @return [self] for chaining
+    #
+    # @example
+    #   ArticlesQuery.new.unpaginated.entries # => all records
     def unpaginated
       @page = nil
       @per_page = nil
       self
     end
 
+    # Executes the query and returns paginated results.
+    #
+    # @return [PaginatedResult] when pagination is enabled
+    # @return [Array<Hash>] when unpaginated
     def entries
       @_entries ||= build_paginated_result(super)
     end
 
+    # Returns the total count of records (without pagination).
+    #
+    # Executes a separate COUNT query. Result is memoized.
+    #
+    # @return [Integer] total number of records
     def total_count
       @_total_count ||= unpaginated_query.count
     end
 
+    private
+
+    # Returns the underlying query without pagination applied.
+    #
+    # Useful for getting total counts or building derived queries.
+    #
+    # @return [AppQuery::Q] the unpaginated query object
     def unpaginated_query
       base_query
         .render(**render_vars, page: nil)
         .with_binds(**bind_vars)
     end
 
-    private
-
     def build_paginated_result(entries)
       return entries unless @page # No pagination requested
 

data/lib/app_query/railtie.rb

@@ -0,0 +1,12 @@
+module AppQuery
+  class Railtie < ::Rails::Railtie # :nodoc:
+    generators do
+      require_relative "../generators/app_query/query_generator"
+      require_relative "../generators/app_query/example_generator"
+      require_relative "../generators/query_generator"
+      require_relative "../generators/rspec/app_query_generator"
+      require_relative "../generators/rspec/app_query_example_generator"
+      require_relative "../generators/rspec/query_generator"
+    end
+  end
+end

data/lib/app_query/rspec/helpers.rb

@@ -1,56 +1,111 @@
+# frozen_string_literal: true
+
 module AppQuery
   module RSpec
+    # RSpec helpers for testing query classes.
+    #
+    # @example Basic usage
+    #   RSpec.describe ProductsQuery, type: :query do
+    #     it "returns products" do
+    #       expect(described_query.entries).to be_present
+    #     end
+    #   end
+    #
+    # @example Testing a specific CTE
+    #   RSpec.describe ProductsQuery, type: :query do
+    #     describe "cte active_products" do
+    #       it "only contains active products" do
+    #         expect(described_query.entries).to all(include("active" => true))
+    #       end
+    #     end
+    #   end
+    #
+    # @example With required binds
+    #   RSpec.describe UsersQuery, type: :query, binds: {company_id: 1} do
+    #     it "returns users for company" do
+    #       expect(described_query.entries).to be_present
+    #     end
+    #   end
+    #
+    # @example With vars
+    #   RSpec.describe ProductsQuery, type: :query do
+    #     describe "as admin", vars: {admin: true} do
+    #       it "returns all products" do
+    #         expect(described_query.entries.size).to eq(3)
+    #       end
+    #     end
+    #   end
     module Helpers
-      def default_binds
-        self.class.default_binds
-      end
-
-      def default_vars
-        self.class.default_vars
-      end
-
-      def expand_select(s)
-        s.gsub(":cte", cte_name)
-      end
-
-      def select_all(select: nil, binds: default_binds, **kws)
-        @query_result = described_query(select:).select_all(binds:, **kws)
+      # Returns the query instance, optionally focused on a CTE.
+      #
+      # When inside a `describe "cte xxx"` block, returns a query
+      # that selects from that CTE instead of the full query.
+      #
+      # @param kwargs [Hash] arguments passed to {#build_query}
+      # @return [AppQuery::BaseQuery, AppQuery::Q] the query instance
+      #
+      # @example Override binds per-test
+      #   expect(described_query(user_id: 123).entries).to include(...)
+      def described_query(**kwargs)
+        query = build_query(**kwargs)
+        cte_name ? query.query.cte(cte_name) : query
       end
 
-      def select_one(select: nil, binds: default_binds, **kws)
-        @query_result = described_query(select:).select_one(binds:, **kws)
+      # Builds the query instance. Override this to customize instantiation.
+      #
+      # @param kwargs [Hash] merged with {#query_binds} and {#query_vars}
+      # @return [AppQuery::BaseQuery] the query instance
+      #
+      # @example Custom build method
+      #   def build_query(**kwargs)
+      #     described_class.build(**query_binds.merge(query_vars).merge(kwargs))
+      #   end
+      def build_query(**kwargs)
+        described_class.new(**query_binds.merge(query_vars).merge(kwargs))
       end
 
-      def select_value(select: nil, binds: default_binds, **kws)
-        @query_result = described_query(select:).select_value(binds:, **kws)
+      # Returns binds from RSpec metadata.
+      #
+      # @return [Hash] the binds hash
+      def query_binds
+        metadata_value(:binds) || {}
       end
 
-      def described_query(select: nil)
-        select ||= "SELECT * FROM :cte" if cte_name
-        select &&= expand_select(select) if cte_name
-        self.class.described_query.render(default_vars).with_select(select)
+      # Returns vars from RSpec metadata.
+      #
+      # @return [Hash] the vars hash
+      def query_vars
+        metadata_value(:vars) || {}
       end
 
+      # Returns the CTE name if inside a "cte xxx" describe block.
+      #
+      # @return [String, nil] the CTE name
       def cte_name
         self.class.cte_name
       end
 
-      def query_name
-        self.class.query_name
+      def self.included(klass)
+        klass.extend(ClassMethods)
       end
 
-      def query_result
-        @query_result
+      private
+
+      def metadata_value(key)
+        self.class.metadata_value(key)
       end
 
       module ClassMethods
-        def described_query
-          AppQuery[query_name]
+        def cte_name
+          descriptions.find { _1[/\Acte\s/i] }&.split&.last
+        end
+
+        def metadata_value(key)
+          metadatas.find { _1[key] }&.[](key)
         end
 
         def metadatas
-          scope = is_a?(Class) ? self : self.class
-          metahash = scope.metadata
+          metahash = metadata
           result = []
           loop do
             result << metahash
@@ -63,36 +118,7 @@ module AppQuery
         def descriptions
           metadatas.map { _1[:description] }
         end
-
-        def query_name
-          descriptions.find { _1[/(app)?query\s/i] }&.then { _1.split.last }
-        end
-
-        def cte_name
-          descriptions.find { _1[/cte\s/i] }&.then { _1.split.last }
-        end
-
-        def default_binds
-          metadatas.find { _1[:default_binds] }&.[](:default_binds) || []
-        end
-
-        def default_vars
-          metadatas.find { _1[:default_vars] }&.[](:default_vars) || {}
-        end
-
-        def included(klass)
-          super
-          # Inject classmethods into the group.
-          klass.extend(ClassMethods)
-          # If the describe block is aimed at string or resource/provider class
-          # then set the default subject to be the Chef run.
-          # if klass.described_class.nil? || klass.described_class.is_a?(Class) && (klass.described_class < Chef::Resource || klass.described_class < Chef::Provider)
-          #  klass.subject { chef_run }
-          # end
-        end
       end
-
-      extend ClassMethods
     end
   end
 end

data/lib/app_query/rspec.rb

@@ -2,4 +2,16 @@ require_relative "rspec/helpers"
 
 RSpec.configure do |config|
   config.include AppQuery::RSpec::Helpers, type: :query
+
+  # Enable SQL logging with `log: true` metadata
+  config.around(:each, type: :query) do |example|
+    if example.metadata[:log]
+      old_logger = ActiveRecord::Base.logger
+      ActiveRecord::Base.logger = Logger.new($stdout)
+      example.run
+      ActiveRecord::Base.logger = old_logger
+    else
+      example.run
+    end
+  end
 end

data/lib/app_query/version.rb

@@ -3,5 +3,5 @@
 module AppQuery
   # This should just contain the .dev of the upcoming version.
   # When doing the actual release, CI will write the tag here before pushing the gem.
-  VERSION = "0.7.0"
+  VERSION = "0.8.0.rc1"
 end

data/lib/app_query.rb

@@ -116,6 +116,26 @@ module AppQuery
     Q.new(full_path.read, name: "AppQuery #{query_name}", filename: full_path.to_s, **opts)
   end
 
+  # Creates a query that selects all columns from a table.
+  #
+  # Convenience method for quickly querying a table without writing SQL.
+  #
+  # @param name [Symbol, String] the table name
+  # @param opts [Hash] additional options passed to {Q#initialize}
+  # @return [Q] a new query object selecting from the table
+  #
+  # @example Basic usage
+  #   AppQuery.table(:products).count
+  #   AppQuery.table(:products).take(5)
+  #
+  # @example With binds
+  #   AppQuery.table(:users, binds: {active: true})
+  #     .select_all("SELECT * FROM :_ WHERE active = :active")
+  def self.table(name, **opts)
+    quoted = ActiveRecord::Base.connection.quote_table_name(name)
+    Q.new("SELECT * FROM #{quoted}", name: "AppQuery.table(#{name})", **opts)
+  end
+
   class Result < ActiveRecord::Result
     attr_accessor :cast
     alias_method :cast?, :cast
@@ -127,13 +147,13 @@ module AppQuery
       @hash_rows = [] if columns.empty?
     end
 
-    def column(name = nil)
+    def column(name = nil, unique: false)
       return [] if empty?
       unless name.nil? || includes_column?(name)
         raise ArgumentError, "Unknown column #{name.inspect}. Should be one of #{columns.inspect}."
       end
       ix = name.nil? ? 0 : columns.index(name)
-      rows.map { _1[ix] }
+      rows.map { _1[ix] }.then { unique ? _1.uniq! : _1 }
     end
 
     def size
@@ -184,7 +204,7 @@ module AppQuery
 
     def self.from_ar_result(r, cast = nil)
       if r.empty?
-        EMPTY
+        r.columns.empty? ? EMPTY : new(r.columns, [], r.column_types)
       else
         cast &&= case cast
         when Array
@@ -433,6 +453,24 @@ module AppQuery
     end
     alias_method :first, :select_one
 
+    # Executes the query and returns the first n rows.
+    #
+    # @param n [Integer] the number of rows to return
+    # @param s [String, nil] optional SELECT to apply before taking
+    # @param binds [Hash, nil] bind parameters to add
+    # @param cast [Boolean, Hash, Array] type casting configuration
+    # @return [Array<Hash>] the first n rows as an array of hashes
+    #
+    # @example
+    #   AppQuery("SELECT * FROM users ORDER BY created_at").take(5)
+    #   # => [{"id" => 1, ...}, {"id" => 2, ...}, ...]
+    #
+    # @see #first
+    def take(n, s = nil, binds: {}, cast: self.cast)
+      with_select(s).select_all("SELECT * FROM :_ LIMIT #{n.to_i}", binds:, cast:).entries
+    end
+    alias_method :limit, :take
+
     # Executes the query and returns the first value of the first row.
     #
     # @param binds [Hash, nil] named bind parameters
@@ -515,6 +553,7 @@ module AppQuery
     # @param c [String, Symbol] the column name to extract
     # @param s [String, nil] optional SELECT to apply before extracting
     # @param binds [Hash, nil] bind parameters to add
+    # @param unique [Boolean] whether to have unique values
     # @return [Array] the column values
     #
     # @example Extract a single column
@@ -524,9 +563,32 @@ module AppQuery
     # @example With additional filtering
     #   AppQuery("SELECT * FROM users").column(:email, "SELECT * FROM :_ WHERE active")
     #   # => ["alice@example.com", "bob@example.com"]
-    def column(c, s = nil, binds: {})
+    #
+    # @example Extract unique values
+    #   AppQuery("SELECT * FROM products").column(:category, unique: true)
+    #   # => ["Electronics", "Clothing", "Home"]
+    def column(c, s = nil, binds: {}, unique: false)
       quoted_column = ActiveRecord::Base.connection.quote_column_name(c)
-      with_select(s).select_all("SELECT #{quoted_column} AS column FROM :_", binds:).column("column")
+      with_select(s).select_all("SELECT #{unique ? "DISTINCT" : ""} #{quoted_column} AS column FROM :_", binds:).column("column")
+    end
+
+    # Returns the column names from the query without fetching any rows.
+    #
+    # Uses `LIMIT 0` to get column metadata efficiently.
+    #
+    # @param s [String, nil] optional SELECT to apply before extracting
+    # @param binds [Hash, nil] bind parameters to add
+    # @return [Array<String>] the column names
+    #
+    # @example Get column names
+    #   AppQuery("SELECT id, name, email FROM users").columns
+    #   # => ["id", "name", "email"]
+    #
+    # @example From a CTE
+    #   AppQuery("WITH t(a, b) AS (VALUES (1, 2)) SELECT * FROM t").columns
+    #   # => ["a", "b"]
+    def columns(s = nil, binds: {})
+      with_select(s).select_all("SELECT * FROM :_ LIMIT 0", binds:).columns
     end
 
     # Returns an array of id values from the query.
@@ -571,11 +633,6 @@ module AppQuery
     # @param returning [String, nil] columns to return (Rails 7.1+ only)
     # @return [Integer, Object] the inserted ID or returning value
     #
-    # @example With positional binds
-    #   AppQuery(<<~SQL).insert(binds: ["Let's learn SQL!"])
-    #     INSERT INTO videos(title, created_at, updated_at) VALUES($1, now(), now())
-    #   SQL
-    #
     # @example With values helper
     #   articles = [{title: "First", created_at: Time.current}]
     #   AppQuery(<<~SQL).render(articles:).insert
@@ -666,6 +723,104 @@ module AppQuery
       raise UnrenderedQueryError, "Query is ERB. Use #render before deleting."
     end
 
+    # Executes COPY TO STDOUT for efficient data export.
+    #
+    # PostgreSQL-only. Uses raw connection for streaming. Raises an error
+    # when used with SQLite or other non-PostgreSQL adapters.
+    #
+    # @param s [String, nil] optional SELECT to apply before extracting
+    # @param format [:csv, :text, :binary] output format (default: :csv)
+    # @param header [Boolean] include column headers (default: true, CSV only)
+    # @param delimiter [Symbol, nil] field delimiter - :tab, :comma, :pipe, :semicolon (default: format's default)
+    # @param dest [String, IO, nil] destination - file path, IO object, or nil to return string
+    # @param binds [Hash] bind parameters
+    # @return [String, Integer, nil] CSV string if dest: nil, bytes written if dest: path, nil if dest: IO
+    #
+    # @example Return as string
+    #   csv = AppQuery[:users].copy_to
+    #
+    # @example Write to file path
+    #   AppQuery[:users].copy_to(dest: "export.csv")
+    #
+    # @example Write to IO object
+    #   File.open("export.csv", "w") { |f| query.copy_to(dest: f) }
+    #
+    # @example Export in Rails controller
+    #   respond_to do |format|
+    #      format.html do
+    #        @invoices = query.entries
+    #
+    #        render :index
+    #      end
+    #
+    #      format.csv do
+    #        response.headers['Content-Type'] = 'text/csv'
+    #        response.headers['Content-Disposition'] = 'attachment; filename="invoices.csv"'
+    #
+    #        query.unpaginated.copy_to(dest: response.stream)
+    #      end
+    #    end
+    #
+    # @raise [AppQuery::Error] if adapter is not PostgreSQL
+    def copy_to(s = nil, format: :csv, header: true, delimiter: nil, dest: nil, binds: {})
+      raw_conn = ActiveRecord::Base.connection.raw_connection
+      unless raw_conn.respond_to?(:copy_data)
+        raise Error, "copy_to requires PostgreSQL (current adapter does not support COPY)"
+      end
+
+      allowed_formats = %i[csv text binary]
+      unless allowed_formats.include?(format)
+        raise ArgumentError, "Invalid format: #{format.inspect}. Allowed: #{allowed_formats.join(", ")}"
+      end
+
+      delimiters = {tab: "\t", comma: ",", pipe: "|", semicolon: ";"}
+      if delimiter
+        if !delimiters.key?(delimiter)
+          raise ArgumentError, "Invalid delimiter: #{delimiter.inspect}. Allowed: #{delimiters.keys.join(", ")}"
+        elsif format == :binary
+          raise ArgumentError, "Delimiter not allowed for format :binary"
+        end
+      end
+
+      add_binds(**binds).with_select(s).render({}).then do |aq|
+        options = ["FORMAT #{format.to_s.upcase}"]
+        options << "HEADER" if header && format == :csv
+        options << "DELIMITER E'#{delimiters[delimiter]}'" if delimiter
+
+        inner_sql = ActiveRecord::Base.sanitize_sql_array([aq.to_s, aq.binds])
+        copy_sql = "COPY (#{inner_sql}) TO STDOUT WITH (#{options.join(", ")})"
+
+        case dest
+        when NilClass
+          output = +""
+          raw_conn.copy_data(copy_sql) do
+            while (row = raw_conn.get_copy_data)
+              output << row
+            end
+          end
+          # pg returns ASCII-8BIT, but CSV/text is UTF-8; binary stays as-is
+          (format == :binary) ? output : output.force_encoding(Encoding::UTF_8)
+        when String
+          bytes = 0
+          File.open(dest, "wb") do |f|
+            raw_conn.copy_data(copy_sql) do
+              while (row = raw_conn.get_copy_data)
+                bytes += f.write(row)
+              end
+            end
+          end
+          bytes
+        else
+          raw_conn.copy_data(copy_sql) do
+            while (row = raw_conn.get_copy_data)
+              dest.write(row)
+            end
+          end
+          nil
+        end
+      end
+    end
+
     # @!group Query Introspection
 
     # Returns the tokenized representation of the SQL.
@@ -690,8 +845,12 @@ module AppQuery
     # @example
     #   AppQuery("WITH a AS (SELECT 1), b AS (SELECT 2) SELECT * FROM a, b").cte_names
     #   # => ["a", "b"]
+    #
+    # @example Quoted identifiers are returned without quotes
+    #   AppQuery('WITH "special*name" AS (SELECT 1) SELECT * FROM "special*name"').cte_names
+    #   # => ["special*name"]
     def cte_names
-      tokens.filter { _1[:t] == "CTE_IDENTIFIER" }.map { _1[:v] }
+      tokens.filter { _1[:t] == "CTE_IDENTIFIER" }.map { _1[:v].delete_prefix('"').delete_suffix('"') }
     end
 
     # @!group Query Transformation
@@ -812,6 +971,30 @@ module AppQuery
 
     # @!group CTE Manipulation
 
+    # Returns a new query focused on the specified CTE.
+    #
+    # Wraps the query to select from the named CTE, allowing you to
+    # inspect or test individual CTEs in isolation.
+    #
+    # @param name [Symbol, String] the CTE name to select from
+    # @return [Q] a new query selecting from the CTE
+    # @raise [ArgumentError] if the CTE doesn't exist
+    #
+    # @example Focus on a specific CTE
+    #   query = AppQuery("WITH published AS (SELECT * FROM articles WHERE published) SELECT * FROM published")
+    #   query.cte(:published).entries
+    #
+    # @example Chain with other methods
+    #   ArticleQuery.new.cte(:active_articles).take(5)
+    def cte(name)
+      name = name.to_s
+      unless cte_names.include?(name)
+        raise ArgumentError, "Unknown CTE #{name.inspect}. Available: #{cte_names.inspect}"
+      end
+      quoted = ActiveRecord::Base.connection.quote_table_name(name)
+      with_select("SELECT * FROM #{quoted}")
+    end
+
     # Prepends a CTE to the beginning of the WITH clause.
     #
     # If the query has no CTEs, wraps it with WITH. If the query already has
@@ -964,3 +1147,4 @@ rescue LoadError
 end
 
 require_relative "app_query/rspec" if Object.const_defined? :RSpec
+require_relative "app_query/railtie" if defined?(Rails::Railtie)

data/lib/generators/app_query/USAGE

@@ -0,0 +1,28 @@
+Description:
+    Generates a query class with SQL file and spec.
+
+    Also generates ApplicationQuery if it doesn't exist.
+
+Example:
+    rails generate app_query:query products
+    rails generate query products  # shorthand alias
+
+    This creates:
+        Base:   app/queries/application_query.rb (if not exists)
+        Class:  app/queries/products_query.rb
+        SQL:    app/queries/products.sql
+        Spec:   spec/queries/products_query_spec.rb
+
+    With namespace:
+        rails generate query admin/reports
+
+    Creates:
+        Class:  app/queries/admin/reports_query.rb
+        SQL:    app/queries/admin/reports.sql
+        Spec:   spec/queries/admin/reports_query_spec.rb
+
+See also:
+    rails generate app_query:example
+
+    Generates a fully annotated example query demonstrating
+    binds, vars, CTEs, and RSpec testing patterns.

data/lib/generators/app_query/example_generator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AppQuery
+  module Generators
+    class ExampleGenerator < Rails::Generators::Base
+      desc <<~DESC
+        Generates annotated example query demonstrating binds, vars, CTEs, and testing patterns.
+
+        See also:
+          rails generate query --help
+      DESC
+      source_root File.expand_path("templates", __dir__)
+
+      def create_application_query
+        return if File.exist?(application_query_path)
+
+        template "application_query.rb", application_query_path
+      end
+
+      def create_example_files
+        template "example_query.rb", File.join(query_path, "example_query.rb")
+        template "example.sql.erb", File.join(query_path, "example.sql.erb")
+      end
+
+      hook_for :test_framework, as: :app_query_example
+
+      private
+
+      def query_path
+        ::AppQuery.configuration.query_path
+      end
+
+      def application_query_path
+        File.join(query_path, "application_query.rb")
+      end
+    end
+  end
+end

data/lib/generators/app_query/query_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AppQuery
+  module Generators
+    class QueryGenerator < Rails::Generators::NamedBase
+      desc <<~DESC
+        Generates a query class with SQL file and spec.
+
+        See also:
+          rails generate query --help
+      DESC
+      source_root File.expand_path("templates", __dir__)
+
+      def create_application_query
+        return if File.exist?(application_query_path)
+
+        template "application_query.rb", application_query_path
+      end
+
+      def create_query_class
+        template "query.rb",
+          File.join(query_path, class_path, "#{file_name}_query.rb")
+      end
+
+      def create_query_file
+        template "query.sql",
+          File.join(query_path, class_path, "#{file_name}.sql")
+      end
+
+      hook_for :test_framework
+
+      private
+
+      def query_path
+        ::AppQuery.configuration.query_path
+      end
+
+      def application_query_path
+        File.join(query_path, "application_query.rb")
+      end
+    end
+  end
+end

data/lib/generators/app_query/templates/application_query.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class ApplicationQuery < AppQuery::BaseQuery
+  # Include middleware for all queries:
+  # include AppQuery::Paginatable
+  # include AppQuery::Mappable
+end

data/lib/generators/app_query/templates/example.sql.erb.tt

@@ -0,0 +1,41 @@
+-- =============================================================================
+-- ExampleQuery SQL Template
+--
+-- This file demonstrates AppQuery SQL patterns. Delete once familiar.
+--
+-- Key concepts:
+-- - CTEs (WITH clauses) for organizing complex queries
+-- - ∶bind_name for safe parameter binding
+-- - ERB for conditional SQL generation
+-- =============================================================================
+
+-- == CTEs (Common Table Expressions)
+-- Break complex queries into readable, testable pieces.
+-- Each CTE can be tested independently in specs.
+WITH products(id, name, supplier_id, active) AS (
+  -- In real code, this would be: SELECT * FROM products
+  VALUES (1, 'Widget', 100, true),
+         (2, 'Gadget', 100, false),
+         (3, 'Gizmo', 200, true)
+),
+-- == Derived CTEs
+-- Build on previous CTEs to filter/transform data.
+active_products AS (
+  SELECT * FROM products WHERE active
+)
+-- == Final SELECT
+-- The main query that uses the CTEs above.
+SELECT * FROM active_products
+-- == Conditional SQL with ERB
+-- Use vars (like @admin) to conditionally include SQL.
+-- Remember: vars are for trusted values only, not user input!
+<%% unless @admin -%>
+  -- == Bind Parameters
+  -- Use :name syntax for safe parameter binding.
+  -- Binds are defined in the query class with `bind :supplier_id`.
+  -- non-admins: MUST bring supplier_id
+  WHERE (:supplier_id::INTEGER IS NOT NULL AND supplier_id = :supplier_id)
+<%% else -%>
+  -- admin: MAY bring supplier_id
+  WHERE (:supplier_id::INTEGER IS NULL OR supplier_id = :supplier_id)
+<%% end -%>

data/lib/generators/app_query/templates/example_query.rb.tt

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# ExampleQuery demonstrates all AppQuery::BaseQuery features.
+#
+# Usage:
+#   ExampleQuery.new(supplier_id: 1).entries
+#   ExampleQuery.new(supplier_id: 1, admin: true).entries
+#   ExampleQuery.new(supplier_id: 1).query.to_s  # inspect SQL
+#
+# Delete this file once you're familiar with the patterns.
+#
+class ExampleQuery < ApplicationQuery
+  # == Binds
+  #
+  # Bind parameters are safe from SQL injection. Use for WHERE clauses.
+  # In SQL: WHERE supplier_id = :supplier_id
+  #
+  bind :supplier_id, default: nil
+
+  # == Vars
+  #
+  # Template variables for dynamic SQL generation (ERB).
+  # In SQL: <%% if @admin %>...<%% end %>
+  #
+  # WARNING: vars are NOT safe from injection - only use for trusted values
+  # like sorting options, not user input.
+  #
+  var :admin, default: false
+
+  # == Casts
+  #
+  # Automatically cast result columns to Ruby types.
+  # Supported: :date, :datetime, :time, :integer, :float, :decimal,
+  #            :boolean, :json, :array (PostgreSQL)
+  #
+  # cast metadata: :json, published_at: :datetime
+end

data/lib/generators/app_query/templates/query.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+class <%= class_name %>Query < ApplicationQuery
+  # bind :user_id              # SQL: WHERE user_id = :user_id
+  # var :admin, default: false # ERB: <%% if @admin %>
+  # cast published_at: :date   # Cast column to Ruby type
+end
+<% end -%>

data/lib/generators/app_query/templates/query.sql.tt

@@ -0,0 +1 @@
+SELECT * FROM <%= file_name %>

data/lib/generators/query_generator.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "app_query/query_generator"
+
+class QueryGenerator < AppQuery::Generators::QueryGenerator
+  # Hidden alias for app_query:query
+  # Usage: rails g query products
+  source_root AppQuery::Generators::QueryGenerator.source_root
+  hide!
+end

data/lib/generators/rspec/app_query_example_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Rspec
+  module Generators
+    class AppQueryExampleGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_test_file
+        template "app_query_example_spec.rb", "spec/queries/example_query_spec.rb"
+      end
+    end
+  end
+end

data/lib/{rails/generators/rspec/query_generator.rb → generators/rspec/app_query_generator.rb}

@@ -1,20 +1,14 @@
+# frozen_string_literal: true
+
 module Rspec
   module Generators
-    class QueryGenerator < ::Rails::Generators::NamedBase
+    class AppQueryGenerator < Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_test_file
-        template "query_spec.rb",
+        template "app_query_spec.rb",
           File.join("spec/queries", class_path, "#{file_name}_query_spec.rb")
       end
-
-      hide!
-
-      private
-
-      def query_path
-        AppQuery.configuration.query_path
-      end
     end
   end
 end

data/lib/generators/rspec/query_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "app_query_generator"
+
+module Rspec
+  module Generators
+    class QueryGenerator < AppQueryGenerator
+      # Hidden hook for query generator alias
+      source_root AppQueryGenerator.source_root
+      hide!
+    end
+  end
+end

data/lib/generators/rspec/templates/app_query_example_spec.rb.tt

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+# ExampleQuery Spec
+#
+# This demonstrates all AppQuery RSpec helpers. Delete once familiar.
+#
+# Setup: Add to spec/rails_helper.rb:
+#   require "app_query/rspec"
+#
+RSpec.describe ExampleQuery, type: :query do
+  # ============================================================================
+  # Basic Usage
+  # ============================================================================
+  #
+  # `described_query` instantiates the query class and returns results.
+  # It automatically uses binds/vars from metadata.
+
+  describe "basic query" do
+    it "returns an array of hashes" do
+      expect(described_query(admin: true).entries).to be_an(Array)
+      expect(described_query(admin: true).first).to be_a(Hash)
+    end
+  end
+
+  # ============================================================================
+  # Testing CTEs
+  # ============================================================================
+  #
+  # Use `describe "cte <name>"` to test a specific CTE in isolation.
+  # `described_query` will SELECT from that CTE instead of the full query.
+
+  describe "cte products" do
+    it "contains all products (including inactive)" do
+      expect(described_query.count).to eq(3)
+    end
+
+    it "has the expected columns" do
+      expect(described_query.columns).to contain_exactly(
+        "id", "name", "supplier_id", "active"
+      )
+    end
+  end
+
+  describe "cte active_products" do
+    it "only contains active products" do
+      expect(described_query.entries).to all(include("active" => true))
+    end
+
+    it "excludes inactive products" do
+      expect(described_query.entries.size).to eq(2)
+    end
+  end
+
+  # ============================================================================
+  # Passing Binds via Metadata
+  # ============================================================================
+  #
+  # Use `binds: {key: value}` in describe/context metadata.
+  # These are passed to the query class constructor.
+
+  describe "filtered by supplier", binds: {supplier_id: 100} do
+    it "returns only products for that supplier" do
+      expect(described_query.entries).to all(include("supplier_id" => 100))
+    end
+  end
+
+  # ============================================================================
+  # Passing Vars via Metadata
+  # ============================================================================
+  #
+  # Use `vars: {key: value}` for template variables.
+  # These control conditional SQL generation.
+
+  describe "as admin", vars: {admin: true} do
+    it "returns all active products regardless of supplier" do
+      expect(described_query.entries.size).to eq(2)
+    end
+
+    it "includes products from multiple suppliers" do
+      expect(described_query.column(:supplier_id, unique: true).count).to be > 1
+    end
+  end
+
+  # ============================================================================
+  # Combining Binds and Vars
+  # ============================================================================
+
+  describe "non-admin with supplier", binds: {supplier_id: 100}, vars: {admin: false} do
+    it "filters by supplier" do
+      expect(described_query.entries).to all(include("supplier_id" => 100))
+    end
+  end
+
+  # ============================================================================
+  # Per-Test Overrides
+  # ============================================================================
+  #
+  # Pass arguments to `described_query()` to override for a single test.
+
+  describe "per-test customization" do
+    it "can override binds inline" do
+      result = described_query(supplier_id: 200, admin: false)
+      expect(result.entries).to all(include("supplier_id" => 200))
+    end
+  end
+
+  # ============================================================================
+  # Custom Query Building
+  # ============================================================================
+  #
+  # Override `build_query` for custom instantiation patterns.
+
+  describe "custom build" do
+    def build_query(**kwargs)
+      # Example: always set admin to true in this context
+      described_class.new(admin: true, **kwargs)
+    end
+
+    it "uses the custom build method" do
+      # This will use admin: true from build_query
+      expect(described_query.entries.size).to eq(2)
+    end
+  end
+
+  # ============================================================================
+  # SQL Logging
+  # ============================================================================
+  #
+  # Add `log: true` to see the actual SQL being executed.
+  # Useful for debugging.
+
+  describe "with logging", log: true do
+    it "logs SQL to stdout" do
+      # Check your terminal - you'll see the SQL query
+      described_query.entries
+    end
+  end
+end

data/lib/generators/rspec/templates/app_query_spec.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe <%= class_name %>Query, type: :query do
+  it "returns results" do
+    expect(described_query.entries).to be_an(Array)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appquery
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0.rc1
 platform: ruby
 authors:
 - Gert Goet
@@ -46,6 +46,7 @@ files:
 - ".yard/templates/default/fulldoc/html/css/dark.css"
 - ".yard/templates/default/fulldoc/html/js/app.js"
 - ".yard/templates/default/fulldoc/html/setup.rb"
+- ".yard/templates/default/layout/html/footer.erb"
 - ".yard/templates/default/layout/html/setup.rb"
 - ".yardopts"
 - Appraisals
@@ -59,17 +60,27 @@ files:
 - lib/app_query/base_query.rb
 - lib/app_query/mappable.rb
 - lib/app_query/paginatable.rb
+- lib/app_query/railtie.rb
 - lib/app_query/render_helpers.rb
 - lib/app_query/rspec.rb
 - lib/app_query/rspec/helpers.rb
 - lib/app_query/tokenizer.rb
 - lib/app_query/version.rb
 - lib/appquery.rb
-- lib/rails/generators/query/USAGE
-- lib/rails/generators/query/query_generator.rb
-- lib/rails/generators/query/templates/query.sql.tt
-- lib/rails/generators/rspec/query_generator.rb
-- lib/rails/generators/rspec/templates/query_spec.rb.tt
+- lib/generators/app_query/USAGE
+- lib/generators/app_query/example_generator.rb
+- lib/generators/app_query/query_generator.rb
+- lib/generators/app_query/templates/application_query.rb.tt
+- lib/generators/app_query/templates/example.sql.erb.tt
+- lib/generators/app_query/templates/example_query.rb.tt
+- lib/generators/app_query/templates/query.rb.tt
+- lib/generators/app_query/templates/query.sql.tt
+- lib/generators/query_generator.rb
+- lib/generators/rspec/app_query_example_generator.rb
+- lib/generators/rspec/app_query_generator.rb
+- lib/generators/rspec/query_generator.rb
+- lib/generators/rspec/templates/app_query_example_spec.rb.tt
+- lib/generators/rspec/templates/app_query_spec.rb.tt
 - mise.local.toml.example
 - mise.toml
 - rakelib/gem.rake
@@ -89,7 +100,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/rails/generators/query/USAGE

@@ -1,10 +0,0 @@
-Description:
-    Generates a new query-file and invokes your template
-    engine and test framework generators.
-
-Example:
-    `bin/rails generate query reports/weekly`
-
-    creates an SQL file and test:
-        Query:  app/queries/reports/weekly.sql
-        Spec:   spec/queries/reports/weekly_query_spec.rb

data/lib/rails/generators/query/query_generator.rb

@@ -1,20 +0,0 @@
-module Rails
-  module Generators
-    class QueryGenerator < NamedBase
-      source_root File.expand_path("templates", __dir__)
-
-      def create_query_file
-        template "query.sql",
-          File.join(AppQuery.configuration.query_path, class_path, "#{file_name}.sql")
-
-        # in_root do
-        #  if behavior == :invoke && !File.exist?(application_mailbox_file_name)
-        #    template "application_mailbox.rb", application_mailbox_file_name
-        #  end
-        # end
-      end
-
-      hook_for :test_framework
-    end
-  end
-end

data/lib/rails/generators/query/templates/query.sql.tt

@@ -1,14 +0,0 @@
--- Instantiate this query with AppQuery[<%= (class_path << file_name).join("/").inspect %>]
-
-WITH
-  articles(article_id, article_title) AS (
-    VALUES (1, 'Some title'),
-           (2, 'Another article')
-  ),
-  authors(author_id, author_name) AS (
-    VALUES (1, 'Some Author'),
-           (2, 'Another Author')
-  )
-
-SELECT *
-FROM artciles

data/lib/rails/generators/rspec/templates/query_spec.rb.tt

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "rails_helper"
-
-RSpec.describe "AppQuery <%= (class_path << file_name).join("/") %>", type: :query, default_binds: nil do
-  describe "CTE articles" do
-    specify do
-      expect(select_all(select: "select * from :cte").cast_entries).to \
-        include(a_hash_including("article_id" => 1))
-    end
-  end
-end