occams-record 1.1.7 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f20725f84205589f6d7f9f11b54870e7cdc4697020863133e8669f80ef9c601d
-  data.tar.gz: 3abfc4b311d439d866ff40c512f8a7ce478c0f938483fb6805dad1a1ac4c1ebc
+  metadata.gz: 95a5656a0aa870ae2458e549442d68f8f685388d2f561321daae428509bdac6e
+  data.tar.gz: 9b5c0edddab969fd9ba3140e028dd4d36d4408fe079c5e8987be8b35a3263d4e
 SHA512:
-  metadata.gz: 03272f59314447452b174e24c0e8b334fbd9ce0a03ef29b54d353710b29f08b679a8d3b8e5e6108593a10019a84a7069519810e37c7598e79d3002f7314f7ede
-  data.tar.gz: e9b99f0ef4e60c0ac1e70d431dc40ac9e2f0d265e4687eba9dbf8163ce89894baca4b50c2e34b3e8cecbc99727800039b404eedb0e156a2b887b5e9736d20780
+  metadata.gz: 1fb09da919637085f3673dffa20416dbbcfcd5f03d0b9d4efbcc074f26a076b44a286a10da6f311822dda843b4480f631dc93d8f6e7cfe9818998e933bd0c099
+  data.tar.gz: 9f3dc78c47a39f396ee393e8c9a472dedd3e436db00cafd6e7773f8137e143fb5c5b86bffa7db204b63d170567285c5baf04928b4a4405aead081115c5b77bf1

data/README.md

@@ -17,17 +17,17 @@ Continue using ActiveRecord's query builder, but let Occams take over running th
 **Customize the SQL used to eager load associations**
 
 ```ruby
-OccamsRecord.
-  query(User.active).
-  eager_load(:orders, ->(q) { q.where("created_at >= ?", date).order("created_at DESC") })
+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=postgresql://postgres@localhost:5432/occams_record bundle exec appraisal rake test
 ```
 
 # License

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/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.7".freeze
+  VERSION = "1.3.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 1.1.7
+  version: 1.3.0
 platform: ruby
 authors:
 - Jordan Hollinger
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-11-30 00:00:00.000000000 Z
+date: 2022-01-30 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
@@ -81,8 +95,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 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: []