occams-record 0.27.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 9c718e8ed411d6d2a139dcc27c2c0f7fa788fc6dafb8c534d3332682c85502f6
-  data.tar.gz: 464d6e322e1a478f861cb576b4e506589da318485c29fe5ec852726fcba2a692
+SHA1:
+  metadata.gz: 6122accb864f31c103a6036c8c3b9e08b457b52f
+  data.tar.gz: f8ed00235fc026d24a56a9f44065a45142472603
 SHA512:
-  metadata.gz: ed85408318c87e662a14cc863fe43cb2b2e1f1a5aae739ff1a1b22968957a455e771e3ac6fcb3b902b0febe9585bddad6b4c02640bfaa077a6e6a98f3a3c148d
-  data.tar.gz: 78f981128bd9fad0d6a670ed21426366cf3ac1b74169f3571a6335ae9cf1d5a5c2c790fa7f4bc1c09d4b5756a0a7850998467a779c7bef4db2dc50b1553fb330
+  metadata.gz: 1f6a942bc993990b22448507ed25723a12a3a2a7d06d5684008b3a78a51f676b973cb11297f2a6818a9becd3164db5079181ae0566251cd8b8a2eee1b99fc763
+  data.tar.gz: 40f46acd684737a8214f7b06ce1dce31de0fc76bcc1f8ab4ee152973d6223f8089e416cec4536c9e567ac3c2ea292429a87cef898bcb059f05210d84285ff55a

data/README.md

@@ -1,4 +1,4 @@
-# Occam's Record [![Build Status](https://travis-ci.org/jhollinger/occams-record.svg?branch=master)](https://travis-ci.org/jhollinger/occams-record)
+### Occams Record [![Build Status](https://travis-ci.org/jhollinger/occams-record.svg?branch=master)](https://travis-ci.org/jhollinger/occams-record)
 
 > Do not multiply entities beyond necessity. -- Occam's Razor
 
@@ -11,203 +11,212 @@ Occam's Record is a high-efficiency, advanced query library for ActiveRecord app
 * `find_each`/`find_in_batches` respects `order` and `limit`.
 * Allows eager loading of associations when querying with raw SQL.
 * Allows `find_each`/`find_in_batches` when querying with raw SQL.
-* Eager load data from arbitrary SQL (no association required).
+* Eager load an ad hoc assocation using arbitrary SQL.
 
 [Look over the speed and memory measurements yourself!](https://github.com/jhollinger/occams-record/wiki/Measurements) OccamsRecord achieves all of this by making some very specific trade-offs:
 
 * OccamsRecord results are **read-only**.
 * OccamsRecord results are **purely database rows** - they don't have any instance methods from your Rails models.
-* OccamsRecord queries must eager load each association that will be used. Otherwise they simply won't be availble.
+* You **must eager load** each assocation you intend to use. If you forget one, an exception will be raised.
 
-## Usage
+---
 
-Full documentation is available at [rubydoc.info/gems/occams-record](http://www.rubydoc.info/gems/occams-record).
+# Installation
 
-**Add to your Gemfile**
+Simply add it to your `Gemfile`:
 
 ```ruby
 gem 'occams-record'
 ```
 
-**Simple example**
+---
+
+# Overview
 
-Build your query the same as before, using `ActiveRecord`'s excellent query builder. Just hand it off to `OccamsRecord.query` before running it. Be sure to use `OccamsRecord`'s eager loading helpers instead of `ActiveRecord`'s.
+Full documentation is available at [rubydoc.info/gems/occams-record](http://www.rubydoc.info/gems/occams-record).
+
+Build your queries like normal, using ActiveRecord's excellent query builder. Then pass them off to Occams Record.
 
 ```ruby
-widgets = OccamsRecord.
-  query(Widget.order("name")).
-  eager_load(:category).
+q = Order.
+  completed.
+  where("order_date > ?", 30.days.ago).
+  order("order_date DESC")
+
+orders = OccamsRecord.
+  query(q).
   run
+````
 
-widgets[0].id
-=> 1000
+`each`, `map`, `reduce`, and all other Enumerable methods are supported. `find_each` and `find_in_batches` are also supported, and unlike their ActiveRecord counterparts they respect *ORDER BY*. Occams Record has great support for raw SQL queries too, but we'll get to those later.
 
-widgets[0].name
-=> "Widget 1000"
+## Basic eager loading
 
-widgets[0].category.name
-=> "Category 1"
+Eager loading is similiar to ActiveRecord's `preload` (each association is loaded in a separate query). Nested associations use blocks instead of Hashes.
+
+```ruby
+orders = OccamsRecord.
+  query(q).
+  eager_load(:customer).
+  eager_load(:line_items) {
+    eager_load(:product)
+  }.
+  run
+  
+order = orders[0]
+puts order.customer.name
+
+order.line_items.each { |line_item|
+  puts line_item.product.name
+  puts line_item.product.category.name
+  OccamsRecord::MissingEagerLoadError: Association 'category' is unavailable on Product because it was not eager loaded!
+}
 ```
 
-**More complicated example**
+## Advanced eager loading
 
-Notice that we're eager loading splines, but *only the fields that we need*. If that's a wide table, your DBA will thank you.
+Occams Record allows you to customize each eager load query using the full power of ActiveRecord's query builder.
 
 ```ruby
-widgets = OccamsRecord.
-  query(Widget.order("name")).
-  eager_load(:category).
-  eager_load(:splines, select: "widget_id, description").
+orders = OccamsRecord.
+  query(q).
+  # Only SELECT these two columns. Your DBA will thank you, esp. on "wide" tables.
+  eager_load(:customer, select: "id, name").
+  
+  # A Proc can customize the query using any of ActiveRecord's query builders and
+  # any scopes you've defined on the LineItem model.
+  eager_load(:line_items, ->(q) { q.active.order("created_at") }) {
+    eager_load(:product)
+  }.
   run
+```
+
+Occams Record also supports creating ad hoc associations using raw SQL. We'll get to that in the next section.
+
+## Raw SQL queries
+
+ActiveRecord has raw SQL "escape hatches" like `find_by_sql` or `exec_query`, but they both give up critical features like eager loading and `find_each`/`find_in_batches`. Not so with Occams Record!
+
+**Batched loading**
 
-widgets[0].splines.map { |s| s.description }
-=> ["Spline 1", "Spline 2", "Spline 3"]
+To use `find_each`/`find_in_batches` you must provide the limit and offset statements yourself. OccamsRecord will fill in the values for you. Also, notice that the binding syntax is a bit different (it uses Ruby's built-in named string substitution).
 
-widgets[1].splines.map { |s| s.description }
-=> ["Spline 4", "Spline 5"]
+```ruby
+OccamsRecord.
+  sql(%(
+    SELECT * FROM orders
+    WHERE order_date > %{date}
+    ORDER BY order_date DESC
+    LIMIT %{batch_limit}
+    OFFSET %{batch_offset}
+  ), {
+    date: 30.days.ago
+  }).
+  find_each(batch_size: 1000) do |order|
+    ...
+  end
 ```
 
-**Even more complicated example**
+**Eager loading**
 
-Here we're eager loading several levels down. Notice the `Proc` given to `eager_load(:orders)`. The `select:` option is just for convenience; you may instead pass a `Proc` and customize the query with any of ActiveRecord's query builder helpers (`select`, `where`, `order`, `limit`, etc).
+To use `eager_load` with a raw SQL query you must tell Occams what the base model is. (That doesn't apply if you're loading an ad hoc, raw SQL association. We'll get to those later).
 
 ```ruby
-widgets = OccamsRecord.
-  query(Widget.order("name")).
-  eager_load(:category).
+orders = OccamsRecord.
+  sql(%(
+    SELECT * FROM orders
+    WHERE order_date > %{date}
+    ORDER BY order_date DESC
+  ), {
+    date: 30.days.ago
+  }).
+  model(Order).
+  eager_load(:customer).
+  run
+```
 
-  # load order_items, but only the fields needed to identify which orders go with which widgets
-  eager_load(:order_items, select: "widget_id, order_id") {
+## Raw SQL eager loading
 
-    # load the orders ("q" has all the normal query methods and any scopes defined on Order)
-    eager_load(:orders, ->(q) { q.select("id, customer_id").order("order_date DESC") }) {
+Let's say we want to load each product with an array of all customers who've ordered it. We *could* do that by loading various nested associations:
 
-      # load the customers who made the orders, but only their names
-      eager_load(:customer, select: "id, name")
+```ruby
+products_with_orders = OccamsRecord.
+  query(Product.all).
+  eager_load(:line_items) {
+    eager_load(:order) {
+      eager_load(:customer)
     }
   }.
-  run
+  map { |product|
+    customers = product.line_items.map(&:order).map(&:customer).uniq
+    [product, customers]
+  }
 ```
 
-**Eager load using raw SQL without a predefined association**
-
-Let's say we want to load each widget and eager load all the customers who've ever ordered it. We could do that using the above example, but we end up loading a lot of useless intermediate records. What if we could define an ad hoc association, using raw SQL, to load exactly what we need? Enter `eager_load_one` and `eager_load_many`! See the full documentation for a full description of all options.
+But that's very wasteful. Occams gives us a better options: `eager_load_many` and `eager_load_one`.
 
 ```ruby
-widgets = OccamsRecord.
-  query(Widget.order("name")).
-
-  # load the results of the query into "customers", matching "widget_id"
-  # in the results to the "id" field of the widgets
-  eager_load_many(:customers, {:widget_id => :id}, %(
-    SELECT DISTINCT customers.id, customers.name, order_items.widget_id
-    FROM customers
-      INNER JOIN orders ON orders.customer_id = customers.id
-      INNER JOIN order_items ON order_items.order_id = orders.id
-    WHERE order_items.widget_id IN (%{ids})
+products = OccamsRecord.
+  query(Product.all).
+  eager_load_many(:customers, {:product_id => :id}, %w(
+    SELECT DISTINCT product_id, customers.*
+    FROM line_items
+      INNER JOIN orders ON line_items.order_id = orders.id
+      INNER JOIN customers on orders.customer_id = customers.id
+    WHERE line_items.product_id IN (%{ids})
   ), binds: {
     # additional bind values (ids will be passed in for you)
   }).
   run
 ```
 
-## Injecting instance methods
+`eager_load_many` allows us to declare an ad hoc *has_many* association called *customers*. The `{:product_id => :id}` Hash defines the mapping: *product_id* in these results maps to *id* in the parent Product. The SQL string and binds should be familiar by now. The `%{ids}` value will be provided for you - just stick it in the right place.
 
-By default your results will only have getters for selected columns and eager-loaded associations. If you must, you *can* inject extra methods into your results by putting those methods into a Module. NOTE this is discouraged, as you should try to maintain a clear separation between your persistence layer and your domain.
+`eager_load_one` defines an ad hoc `has_one`/`belongs_to` association.
 
-```ruby
-module MyWidgetMethods
-  def to_s
-    name
-  end
+These ad hoc eager loaders are available on both `OccamsRecord.query` and `OccamsRecord.sql`. While eager loading with `OccamsRecord.sql` normallly requires you to declare the model, that is not necessary with `eager_load_one`/`eager_load_many`.
 
-  def expensive?
-    price_per_unit > 100
-  end
-end
+## Injecting instance methods
+
+Occams Records results are just plain rows; there are no methods from your Rails models. (Separating your persistence layer from your domain is good thing!) But sometimes you need a few methods. Occams Record allows you to specify modules to be included in your results.
 
+```ruby
 module MyOrderMethods
   def description
     "#{order_number} - #{date}"
   end
 end
 
-widgets = OccamsRecord.
-  query(Widget.order("name"), use: MyWidgetMethods).
-  eager_load(:orders, use: [MyOrderMethods, SomeAdditionalMethods]).
-  run
-
-widgets[0].to_s
-=> "Widget A"
-
-widgets[0].price_per_unit
-=> 57.23
-
-widgets[0].expensive?
-=> false
-
-widgets[0].orders[0].description
-=> "O839SJZ98B - 1/8/2017"
-```
-
-## Raw SQL queries
-
-If you have a complicated query to run, you may drop down to hand-written SQL while still taking advantage of eager loading and variable escaping (not possible in ActiveRecord). Note the slightly different syntax for binding variables.
-
-NOTE this feature is quite new and might have some bugs. Since we are not yet at 1.0, breaking changes may occur. Issues and Pull Requests welcome.
-
-```ruby
-widgets = OccamsRecord.sql(%(
-  SELECT * FROM widgets
-  WHERE category_id = %{cat_id}
-), {
-  cat_id: 5
-}).run
-```
-
-**Performing eager loading with raw SQL**
-
-To perform eager loading with raw SQL you must specify the base model (unless you use the raw SQL eager loaders `eager_load_one` or `eager_load_many`). NOTE some database adapters, notably SQLite, require you to always specify the model.
+module MyProductMethods
+  def expensive?
+    price > 100
+  end
+end
 
-```ruby
-widgets = OccamsRecord.
-  sql(%(
-    SELECT * FROM widgets
-    WHERE category_id IN (%{cat_ids})
-  ), {
-    cat_ids: [5, 10]
-  }).
-  model(Widget).
-  eager_load(:category).
+orders = OccamsRecord.
+  query(Order.all, use: MyOrderMethods).
+  eager_load(:line_items) {
+    eager_load(:product, use: [MyProductMethods, OtherMethods])
+  }.
   run
 ```
 
-**Using find_each/find_in_batches with raw SQL**
+---
 
-To use `find_each` or `find_in_batches` with raw SQL you must provide the `LIMIT` and `OFFSET` clauses yourself. The bind values for these will be filled in by OccamsRecord. Remember to always specific a consitent `ORDER BY` clause.
+# Unsupported features
 
-```ruby
-widgets = OccamsRecord.sql(%(
-  SELECT * FROM widgets
-  WHERE category_id = %{cat_id}
-  ORDER BY name, id
-  LIMIT %{batch_limit}
-  OFFSET %{batch_offset}
-), {
-  cat_id: 5
-}).find_each { |widget|
-  puts widget.name
-}
-```
+The following ActiveRecord features are under consideration, but not high priority. Pull requests welcome!
 
-## Unsupported features
+* `:through` associations.
 
-The following `ActiveRecord` are not supported, and I have no plans to do so. However, I'd be glad to accept pull requests.
+The following ActiveRecord features are not supported, and likely never will be. Pull requests are still welcome, though.
 
 * ActiveRecord enum types
 * ActiveRecord serialized types
 
-## Testing
+---
+
+# Testing
 
 To run the tests, simply run:
 
@@ -219,7 +228,7 @@ bundle exec rake test
 By default, bundler will install the latest (supported) version of ActiveRecord. To specify a version to test against, run:
 
 ```bash
-AR=4.2 bundle update activerecord
+AR=5.2 bundle update activerecord
 bundle exec rake test
 ```
 

data/lib/occams-record/results.rb

@@ -25,6 +25,8 @@ module OccamsRecord
         self.columns = column_names.map(&:to_s)
         self.associations = association_names.map(&:to_s)
         self.model_name = model ? model.name : nil
+        self.table_name = model ? model.table_name : nil
+        self.primary_key = model&.primary_key&.to_s
 
         # Build getters & setters for associations. (We need setters b/c they're set AFTER the row is initialized
         attr_accessor(*association_names)
@@ -64,6 +66,10 @@ module OccamsRecord
         attr_accessor :associations
         # Name of Rails model
         attr_accessor :model_name
+        # Name of originating database table
+        attr_accessor :table_name
+        # Name of primary key column (nil if column wasn't in the SELECT)
+        attr_accessor :primary_key
       end
       self.columns = []
       self.associations = []
@@ -78,20 +84,35 @@ module OccamsRecord
         @cast_values = {}
       end
 
+      #
+      # Returns true if the two objects are from the same table and have the same primary key.
+      #
+      # @param obj [OccamsRecord::Results::Row]
+      # @return [Boolean]
+      #
+      def ==(obj)
+        super ||
+          obj.is_a?(OccamsRecord::Results::Row) &&
+          obj.class.table_name && obj.class.table_name == self.class.table_name &&
+          (pkey1 = obj.class.primary_key) && (pkey2 = self.class.primary_key) &&
+          obj.send(pkey1) == self.send(pkey2)
+      end
+
       #
       # Return row as a Hash (recursive).
       #
       # @param symbolize_names [Boolean] if true, make Hash keys Symbols instead of Strings
+      # @param recursive [Boolean] if true, convert all associated records to Hashes too
       # @return [Hash] a Hash with String or Symbol keys
       #
-      def to_h(symbolize_names: false)
+      def to_h(symbolize_names: false, recursive: true)
         hash = self.class.columns.reduce({}) { |a, col_name|
           key = symbolize_names ? col_name.to_sym : col_name
           a[key] = send col_name
           a
         }
 
-        self.class.associations.reduce(hash) { |a, assoc_name|
+        recursive ? self.class.associations.reduce(hash) { |a, assoc_name|
           key = symbolize_names ? assoc_name.to_sym : assoc_name
           assoc = send assoc_name
           a[key] = if assoc.is_a? Array
@@ -100,11 +121,33 @@ module OccamsRecord
                      assoc.to_h(symbolize_names: symbolize_names)
                    end
           a
-        }
+        } : hash
       end
 
       alias_method :to_hash, :to_h
 
+      #
+      # Returns the name of the model and the attributes.
+      #
+      # @return [String]
+      #
+      def to_s
+        "#{self.class.model_name || "Anonymous"}#{to_h(symbolize_names: true, recursive: false)}"
+      end
+
+      #
+      # Returns a string with the "real" model name and raw result values.
+      #
+      # Weird note - if this string is longer than 65 chars it won't be used in exception messages.
+      # https://bugs.ruby-lang.org/issues/8982
+      #
+      # @return [String]
+      #
+      def inspect
+        id = self.class.primary_key ? send(self.class.primary_key) : "none"
+        "#<#{self.class.model_name || "Anonymous"} #{self.class.primary_key}: #{id}>"
+      end
+
       def method_missing(name, *args, &block)
         return super if args.any? or !block.nil?
         model = self.class.model_name.constantize
@@ -117,15 +160,6 @@ module OccamsRecord
           super
         end
       end
-
-      #
-      # Returns a string with the "real" model name and raw result values.
-      #
-      # @return [String]
-      #
-      def inspect
-        "#<OccamsRecord::Results::Row @model_name=#{self.class.model_name} @raw_values=#{@raw_values}>"
-      end
     end
   end
 end

data/lib/occams-record/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # Library version
-  VERSION = '0.27.0'.freeze
+  VERSION = '0.28.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Jordan Hollinger
@@ -56,7 +56,7 @@ files:
 - lib/occams-record/raw_query.rb
 - lib/occams-record/results.rb
 - lib/occams-record/version.rb
-homepage: https://github.com/jhollinger/occams-record
+homepage: https://jhollinger.github.io/occams-record/
 licenses:
 - MIT
 metadata: {}
@@ -76,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 2.5.2.2
 signing_key: 
 specification_version: 4
 summary: The missing high-efficiency query API for ActiveRecord