occams-record 1.1.6 → 1.3.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 466aabbac2317ba6b65e5d02c4f244f317640bbbea08a2949c4b4ebe59be5bfb
-  data.tar.gz: cd50c8465764d9f811acccd1d833357ced98e2ba5812e3c5d12a3f2534495fb1
+  metadata.gz: dd827ce90c189d89558863ece800e233c3296f590f18e6b756d4f4983c673e7e
+  data.tar.gz: 0bfd98422a9e2a313aae5faef338e442979235377ba1ddad9f5b38e2ccee1b27
 SHA512:
-  metadata.gz: d5935484d5a729eb82fa12eb6402b48d7a54f54d9d8fe2986694eada3af26296c88536c78bbf2a05239483d66deb2c0a7bd6f70097b51547d95d5ded77bbec11
-  data.tar.gz: b0162c9054e18a8c1c265de9e47b5cd2bb00dcc53bd7406a166d67b3c4a390389a0e06f80e345fff8ed89fc2b7edb2b87a9e30a4fc165c6a4f9be2541bbebd71
+  metadata.gz: 00352ecd359c2cd617f29d225aa3a566eed578a81f875714896b0e380931c9e5611b87971f2e68197225a59ebab5e7cefb96f65f4855f08481ca38b02d9f9c8c
+  data.tar.gz: 6f82a98e4790c92d86d44f4ea2e4babd8dde300a08a60106d8e1f8b0e1e0210351ff89915d1f56e44160779b358df8e8d4355ab69f14f81ee23d91e13f033f71

data/README.md

@@ -12,22 +12,22 @@ OccamsRecord is a high-efficiency, advanced query library for use alongside Acti
 
 ### 2) Supercharged querying & eager loading
 
-Continue using ActiveRecord's query builder, but let Occams take over eager loading and raw SQL calls. None of the examples below are possible with ActiveRecord, but OccamsRecord won't limit you. (More complete examples are shown later, but these should whet your appetite.)
+Continue using ActiveRecord's query builder, but let Occams take over running them, eager loading, and raw SQL calls. None of the examples below are possible with ActiveRecord, but OccamsRecord makes them trivial. (More complete examples are shown later, but these should whet your appetite.)
 
 **Customize the SQL used to eager load associations**
 
 ```ruby
-OccamsRecord.
-  query(User.active).
-  eager_load(:orders, ->(q) { q.where("created_at >= ?", date })
+OccamsRecord
+  .query(User.active)
+  .eager_load(:orders, ->(q) { q.where("created_at >= ?", date).order("created_at DESC") })
 ```
 
 **Use `ORDER BY` with `find_each`/`find_in_batches`**
 
 ```ruby
-OccamsRecord.
-  query(Order.order("created_at DESC")).
-  find_each { |order|
+OccamsRecord
+  .query(Order.order("created_at DESC"))
+  .find_each { |order|
     ...
   }
 ```
@@ -35,15 +35,15 @@ OccamsRecord.
 **Use `find_each`/`find_in_batches` with raw SQL**
 
 ```ruby
-OccamsRecord.
-  sql("
+OccamsRecord
+  .sql("
     SELECT * FROM orders
     WHERE created_at >= %{date}
     LIMIT %{batch_limit}
     OFFSET %{batch_offset}",
     {date: 10.years.ago}
-  ).
-  find_each { |order|
+  )
+  .find_each { |order|
     ...
   }
 ```
@@ -51,13 +51,13 @@ OccamsRecord.
 **Eager load associations when you're writing raw SQL**
 
 ```ruby
-OccamsRecord.
-  sql("
+OccamsRecord
+  .sql("
     SELECT * FROM users
     LEFT OUTER JOIN ...
-  ").
-  model(User).
-  eager_load(:orders)
+  ")
+  .model(User)
+  .eager_load(:orders)
 ```
 
 **Eager load "ad hoc associations" using raw SQL**
@@ -66,9 +66,9 @@ Relationships are complicated, and sometimes they can't be expressed in ActiveRe
 (Don't worry, there's a full explanation later on.)
 
 ```ruby
-OccamsRecord.
-  query(User.all).
-  eager_load_many(:orders, {:id => :user_id}, "
+OccamsRecord
+  .query(User.all)
+  .eager_load_many(:orders, {:id => :user_id}, "
     SELECT user_id, orders.*
     FROM orders INNER JOIN ...
     WHERE user_id IN (%{ids})
@@ -97,17 +97,19 @@ gem 'occams-record'
 
 Full documentation is available at [rubydoc.info/gems/occams-record](http://www.rubydoc.info/gems/occams-record).
 
+Code lives at at [github.com/jhollinger/occams-record](https://github.com/jhollinger/occams-record). Contributions welcome!
+
 Build your queries like normal, using ActiveRecord's excellent query builder. Then pass them off to Occams Record.
 
 ```ruby
-q = Order.
-  completed.
-  where("order_date > ?", 30.days.ago).
-  order("order_date DESC")
-
-orders = OccamsRecord.
-  query(q).
-  run
+q = Order
+  .completed
+  .where("order_date > ?", 30.days.ago)
+  .order("order_date DESC")
+
+orders = OccamsRecord
+  .query(q)
+  .run
 ````
 
 `each`, `map`, `reduce`, and other Enumerable methods may be used instead of *run*. `find_each` and `find_in_batches` are also supported, and unlike in ActiveRecord, `ORDER BY` works as you'd expect.
@@ -119,14 +121,14 @@ Occams Record has great support for raw SQL queries too, but we'll get to those
 Eager loading is similiar to ActiveRecord's `preload`: each association is loaded in a separate query. Unlike ActiveRecord, nested associations use blocks instead of Hashes. More importantly, if you try to use an association you didn't eager load *an exception will be raised*. In other words, the N+1 query problem simply doesn't exist.
 
 ```ruby
-OccamsRecord.
-  query(q).
-  eager_load(:customer).
-  eager_load(:line_items) {
+OccamsRecord
+  .query(q)
+  .eager_load(:customer)
+  .eager_load(:line_items) {
     eager_load(:product)
     eager_load(:something_else)
-  }.
-  find_each { |order|
+  }
+  .find_each { |order|
     puts order.customer.name
     order.line_items.each { |line_item|
       puts line_item.product.name
@@ -141,17 +143,17 @@ OccamsRecord.
 Occams Record allows you to tweak the SQL of any eager load. Pull back only the columns you need, change the order, add a `WHERE` clause, etc.
 
 ```ruby
-orders = OccamsRecord.
-  query(q).
+orders = OccamsRecord
+  .query(q)
   # Only SELECT the columns you need. Your DBA will thank you.
-  eager_load(:customer, select: "id, name").
+  .eager_load(:customer, select: "id, name")
   
   # A Proc can use ActiveRecord's query builder
-  eager_load(:line_items, ->(q) { q.active.order("created_at") }) {
+  .eager_load(:line_items, ->(q) { q.active.order("created_at") }) {
     eager_load(:product)
     eager_load(:something_else)
-  }.
-  run
+  }
+  .run
 ```
 
 Occams Record also supports loading ad hoc associations using raw SQL. We'll get to that in the next section.
@@ -165,8 +167,8 @@ ActiveRecord has raw SQL escape hatches like `find_by_sql` and `exec_query`, but
 To use `find_each`/`find_in_batches` you must provide the limit and offset statements yourself; Occams will provide the values. Also, notice that the binding syntax is a bit different (it uses Ruby's built-in named string substitution).
 
 ```ruby
-OccamsRecord.
-  sql("
+OccamsRecord
+  .sql("
     SELECT * FROM orders
     WHERE order_date > %{date}
     ORDER BY order_date DESC, id
@@ -174,8 +176,8 @@ OccamsRecord.
     OFFSET %{batch_offset}
   ", {
     date: 10.years.ago
-  }).
-  find_each(batch_size: 1000) do |order|
+  })
+  .find_each(batch_size: 1000) do |order|
     ...
   end
 ```
@@ -185,17 +187,17 @@ OccamsRecord.
 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 next.)
 
 ```ruby
-orders = OccamsRecord.
-  sql("
+orders = OccamsRecord
+  .sql("
     SELECT * FROM orders
     WHERE order_date > %{date}
     ORDER BY order_date DESC, id
   ", {
     date: 30.days.ago
-  }).
-  model(Order).
-  eager_load(:customer).
-  run
+  })
+  .model(Order)
+  .eager_load(:customer)
+  .run
 ```
 
 ## Raw SQL eager loading
@@ -203,14 +205,14 @@ orders = OccamsRecord.
 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:
 
 ```ruby
-products_with_orders = OccamsRecord.
-  query(Product.all).
-  eager_load(:line_items) {
+products_with_orders = OccamsRecord
+  .query(Product.all)
+  .eager_load(:line_items) {
     eager_load(:order) {
       eager_load(:customer)
     }
-  }.
-  map { |product|
+  }
+  .map { |product|
     customers = product.line_items.map(&:order).map(&:customer).uniq
     [product, customers]
   }
@@ -219,9 +221,9 @@ products_with_orders = OccamsRecord.
 But that's very wasteful. Occams gives us better options: `eager_load_many` and `eager_load_one`.
 
 ```ruby
-products = OccamsRecord.
-  query(Product.all).
-  eager_load_many(:customers, {:id => :product_id}, "
+products = OccamsRecord
+  .query(Product.all)
+  .eager_load_many(:customers, {:id => :product_id}, "
     SELECT DISTINCT product_id, customers.*
     FROM line_items
       INNER JOIN orders ON line_items.order_id = orders.id
@@ -229,8 +231,8 @@ products = OccamsRecord.
     WHERE line_items.product_id IN (%{ids})
   ", binds: {
     # additional bind values (ids will be passed in for you)
-  }).
-  run
+  })
+  .run
 ```
 
 `eager_load_many` is declaring an ad hoc *has_many* association called *customers*. The `{:id => :product_id}` Hash defines the mapping: *id* in the parent record maps to *product_id* in the child records.
@@ -256,12 +258,12 @@ module MyProductMethods
   end
 end
 
-orders = OccamsRecord.
-  query(Order.all, use: MyOrderMethods).
-  eager_load(:line_items) {
+orders = OccamsRecord
+  .query(Order.all, use: MyOrderMethods)
+  .eager_load(:line_items) {
     eager_load(:product, use: [MyProductMethods, OtherMethods])
-  }.
-  run
+  }
+  .run
 ```
 
 ---
@@ -290,30 +292,29 @@ On the other hand, Active Record makes it *very* easy to forget to eager load as
 
 # Testing
 
-To run the tests, simply run:
-
 ```bash
 bundle install
+
+# test against SQLite
 bundle exec rake test
-```
 
-**Specify ActiveRecord version**
+# test against Postgres
+TEST_DATABASE_URL=postgres://postgres@localhost:5432/occams_record bundle exec rake test
+```
 
-By default, bundler will install the latest (supported) version of ActiveRecord. To specify a version to test against, run:
+**Test against all supported ActiveRecord versions**
 
 ```bash
-AR=5.2 bundle update activerecord
-AR=5.2 bundle exec rake test
-```
+bundle exec appraisal install
 
-Look inside `Gemfile` to see all testable versions.
+# test against all supported AR versions (defaults to SQLite)
+bundle exec appraisal rake test
 
-**Run against Postgres**
+# test against a specific AR version
+bundle exec appraisal ar-7.0 rake test
 
-By default the tests run against an in-memory Sqlite3 database. Use the following env var to force running against a Postgres database:
-
-```bash
-TEST_DATABASE_URL=postgres://postgres@localhost:5432/occams_record bundle exec rake test
+# test against Postgres
+TEST_DATABASE_URL=postgres://postgres@localhost:5432/occams_record bundle exec appraisal rake test
 ```
 
 # License

data/lib/occams-record/eager_loaders/belongs_to.rb

@@ -34,7 +34,7 @@ module OccamsRecord
       #
       def merge!(assoc_rows, rows)
         Merge.new(rows, name).
-          single!(assoc_rows, {@ref.foreign_key.to_s => @ref.active_record_primary_key.to_s})
+          single!(assoc_rows, {@ref.foreign_key.to_s => @ref.association_primary_key.to_s})
       end
     end
   end

data/lib/occams-record/eager_loaders/builder.rb

@@ -56,14 +56,14 @@ module OccamsRecord
       #
       # The %{category_ids} bind param will be provided for you, and in this case will be all the category_id values from the Widget query.
       #
-      #   res = OccamsRecord.
-      #     query(Widget.order("name")).
-      #     eager_load_one(:category, {:category_id => :id}, "
+      #   res = OccamsRecord
+      #     .query(Widget.order("name"))
+      #     .eager_load_one(:category, {:category_id => :id}, "
       #       SELECT * FROM categories WHERE id IN (%{category_ids}) AND name != %{bad_name}
       #     ", binds: {
       #       bad_name: "Bad Category"
-      #     }).
-      #     run
+      #     })
+      #     .run
       #
       # @param name [Symbol] name of attribute to load records into
       # @param mapping [Hash] a Hash that defines the key mapping of the parent (widgets.category_id) to the child (categories.id).
@@ -89,14 +89,14 @@ module OccamsRecord
       # The %{ids} bind param will be provided for you, and in this case will be all the id values from the Widget
       # query.
       #
-      #   res = OccamsRecord.
-      #     query(Widget.order("name")).
-      #     eager_load_many(:parts, {:id => :widget_id}, "
+      #   res = OccamsRecord
+      #     .query(Widget.order("name"))
+      #     .eager_load_many(:parts, {:id => :widget_id}, "
       #       SELECT * FROM parts WHERE widget_id IN (%{ids}) AND sku NOT IN (%{bad_skus})
       #     ", binds: {
       #       bad_skus: ["G90023ASDf0"]
-      #     }).
-      #     run
+      #     })
+      #     .run
       #
       # @param name [Symbol] name of attribute to load records into
       # @param mapping [Hash] a Hash that defines the key mapping of the parent (widgets.id) to the children (parts.widget_id).

data/lib/occams-record/eager_loaders/through.rb

@@ -9,7 +9,7 @@ module OccamsRecord
       #
       # See documentation for OccamsRecord::EagerLoaders::Base.
       #
-      def initialize(*args)
+      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: :select, &builder)
         super
 
         unless @ref.macro == :has_one or @ref.macro == :has_many

data/lib/occams-record/measureable.rb

@@ -5,18 +5,18 @@ module OccamsRecord
   #
   # Measure the time each query takes. Useful for figuring out which query is the slow one when you're doing a bunch of eager loads.
   #
-  # orders = OccamsRecord.
-  #   query(Order.all).
-  #   eager_load(:customer).
+  # orders = OccamsRecord
+  #   .query(Order.all)
+  #   .eager_load(:customer)
   #   ...
-  #   measure { |x|
+  #   .measure { |x|
   #     puts "Total time: #{x.total_time} sec"
   #     x.queries.each { |q|
   #       puts "Table: #{q.table_name} (#{q.time} sec)"
   #       puts q.sql
   #     }
-  #   }.
-  #   run
+  #   }
+  #   .run
   #
   module Measureable
     #

data/lib/occams-record/query.rb

@@ -7,15 +7,15 @@ module OccamsRecord
   # Instead use OccamsRecord::Query#eager_load. Finally, call `run` (or any Enumerable method) to run
   # the query and get back an array of objects.
   #
-  #  results = OccamsRecord.
-  #    query(Widget.order("name")).
-  #    eager_load(:category).
-  #    eager_load(:order_items, ->(q) { q.select("widget_id, order_id") }) {
+  #  results = OccamsRecord
+  #    .query(Widget.order("name"))
+  #    .eager_load(:category)
+  #    .eager_load(:order_items, ->(q) { q.select("widget_id, order_id") }) {
   #      eager_load(:orders) {
   #        eager_load(:customer, ->(q) { q.select("name") })
   #      }
-  #    }.
-  #    run
+  #    }
+  #    .run
   #
   # @param scope [ActiveRecord::Relation]
   # @param use [Module] optional Module to include in the result class

data/lib/occams-record/raw_query.rb

@@ -4,7 +4,7 @@ module OccamsRecord
   # a Hash of binds. While this doesn't offer an additional performance boost, it's a nice way to
   # write safe, complicated SQL by hand while also supporting eager loading.
   #
-  #   results = OccamsRecord.sql(
+  #   results = OccamsRecord.sql("
   #     SELECT * FROM widgets
   #     WHERE category_id = %{cat_id}
   #   ", {
@@ -13,22 +13,33 @@ module OccamsRecord
   #
   # If you want to do eager loading, you must first the define a model to pull the associations from (unless
   # you're using the raw SQL eager loaders `eager_load_one` or `eager_load_many`).
-  # NOTE If you're using SQLite, you must *always* specify the model.
   #
-  #   results = OccamsRecord.
-  #     sql("
+  #   results = OccamsRecord
+  #     .sql("
   #       SELECT * FROM widgets
   #       WHERE category_id IN (%{cat_ids})
   #     ", {
   #       cat_ids: [5, 10]
-  #     }).
-  #     model(Widget).
-  #     eager_load(:category).
-  #     run
+  #     })
+  #     .model(Widget)
+  #     .eager_load(:category)
+  #     .run
   #
   # NOTE To use find_each/find_in_batches, your SQL string must include 'LIMIT %{batch_limit} OFFSET %{batch_offset}',
-  # and an ORDER BY is strongly recomended.
-  # OccamsRecord will provide the bind values for you.
+  # and an ORDER BY is strongly recomended. OccamsRecord will provide the bind values for you.
+  #
+  # NOTE There is variation of the types of values returned (e.g. a Date object vs a date string) depending on the database
+  # and ActiveRecord version being used:
+  #
+  # Postgres always returns native Ruby types.
+  #
+  # SQLite will return native types for the following: integers, floats, string/text.
+  # For booleans it will return 0|1 for AR 6+, and "t|f" for AR 5-.
+  # Dates and times will be ISO8601 formatted strings.
+  # It is possible to coerce the SQLite adapter into returning native types for everything IF they're columns of a table
+  # that you have an AR model for. e.g. if you're selecting from the widgets, table: `OccamsRecord.sql("...").model(Widget)...`.
+  #
+  # MySQL ?
   #
   # @param sql [String] The SELECT statement to run. Binds should use Ruby's named string substitution.
   # @param binds [Hash] Bind values (Symbol keys)

data/lib/occams-record/results/results.rb

@@ -4,7 +4,7 @@ module OccamsRecord
     # ActiveRecord's internal type casting API changes from version to version.
     CASTER = case ActiveRecord::VERSION::MAJOR
              when 4 then :type_cast_from_database
-             when 5, 6 then :deserialize
+             when 5, 6, 7 then :deserialize
              else raise "OccamsRecord::Results::CASTER does yet support this version of ActiveRecord"
              end
 
@@ -36,14 +36,20 @@ module OccamsRecord
         attr_accessor(*association_names)
 
         # Build a getter for each attribute returned by the query. The values will be type converted on demand.
-        model_column_types = model ? model.attributes_builder.types : {}
+        model_column_types = model ? model.attributes_builder.types : nil
         self.columns.each_with_index do |col, idx|
-          type =
-            column_types[col] ||
-            model_column_types[col] ||
-            raise("OccamsRecord: Column `#{col}` does not exist on model `#{self.model_name}`")
-
-          case type.type
+          #
+          # NOTE there's lots of variation between DB adapters and AR versions here. Some notes:
+          # * Postgres AR < 6.1 `column_types` will contain entries for every column.
+          # * Postgres AR >= 6.1 `column_types` only contains entries for "exotic" types. Columns with "common" types have already been converted by the PG adapter.
+          # * SQLite `column_types` will always be empty. Some types will have already been convered by the SQLite adapter, but others will depend on
+          #   `model_column_types` for converstion. See test/raw_query_test.rb#test_common_types for examples.
+          # * MySQL ?
+          #
+          type = column_types[col] || model_column_types&.[](col)
+          case type&.type
+          when nil
+            define_method(col) { @raw_values[idx] }
           when :datetime
             define_method(col) { @cast_values[idx] ||= type.send(CASTER, @raw_values[idx])&.in_time_zone }
           when :boolean

data/lib/occams-record/results/row.rb

@@ -152,7 +152,7 @@ module OccamsRecord
       def define_ids_reader!(assoc)
         model = self.class._model
         ref = model.reflections[assoc]
-        pkey = ref.association_primary_key.to_sym
+        pkey = ref.klass.primary_key.to_sym
 
         self.class.class_eval do
           define_method "#{assoc.singularize}_ids" do

data/lib/occams-record/ugly.rb

@@ -8,10 +8,10 @@ module OccamsRecord
     # The ONLY reason to use this is if you absolutely need ActiveRecord objects but still want to use Occams's
     # more advanced eager loading or find_each/find_in_batches features.
     #
-    #   OccamsRecord.
-    #     query(Order.order("created_at DESC")).
-    #     eager_load(:line_items, ->(q) { q.order("price") }).
-    #     find_each do |o|
+    #   OccamsRecord
+    #     .query(Order.order("created_at DESC"))
+    #     .eager_load(:line_items, ->(q) { q.order("price") })
+    #     .find_each do |o|
     #       order = OccamsRecord::Ugly.active_record(o)
     #       ...
     #     end

data/lib/occams-record/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # Library version
-  VERSION = "1.1.6".freeze
+  VERSION = "1.3.0.rc1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 1.1.6
+  version: 1.3.0.rc1
 platform: ruby
 authors:
 - Jordan Hollinger
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-05-14 00:00:00.000000000 Z
+date: 2021-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -19,7 +19,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,21 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  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'
 description: A faster, lower-memory querying API for ActiveRecord that returns results
   as unadorned, read-only objects.
 email: jordan.hollinger@gmail.com
@@ -66,7 +80,7 @@ homepage: https://jhollinger.github.io/occams-record/
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -77,12 +91,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.1.6
+signing_key:
 specification_version: 4
 summary: The missing high-efficiency query API for ActiveRecord
 test_files: []