postgres_upsert 2.0.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 363018cec57166d2976cbeedc60fad9dc17e5ac7
-  data.tar.gz: 280a43ba9f6dea9a72111031c5c7e82089185f72
+SHA256:
+  metadata.gz: 89478e281fa4cd37be98385dab13c96de8f4128702e4a9cfd1c7f8049d912fb8
+  data.tar.gz: b20dc2e32478209af409f86299ea5c702be7c7ec8cf87d7e2dd2035afe27130a
 SHA512:
-  metadata.gz: 195008d31407158e4cecf27fbd1aec45b6b3c17a078efe5dcd567e4ec8d023f187d597cf0b1a5a1e46e53c901e957a7c70b6ceccdd1aa27231f1cd2f727b194d
-  data.tar.gz: fbf6e4e15fc23ab1c344a1a8bdd9ba80733cc77c776b6eed98c05936a0dd6cd4889f387e43f028c8c380a2e7d4beb9f3ecc58ef5374183ff3891821077e0fb37
+  metadata.gz: 4349cbfbeeeeb5bdd4b95086f693e19968319f9a3b4a2bf0dbb290789b9e9893496463a08335dd2e6f9f2d7c0717036cdabfdbca00e1d2ab394beb143bbd2d45
+  data.tar.gz: 8abcd0a2167f3ed42ed6fa1c70c145203a565a8a1418ea3f265a1b81a8267e22aa321b544d350d8c711d420d53c0263c9487bfc8678e5499dad1363475ee2cd0

data/.gitignore

@@ -8,6 +8,9 @@
 /test/tmp/
 /test/version_tmp/
 /tmp/
+/log
+.DS_Store
+*/.Ds_Store
 
 ## Specific to RubyMotion:
 .dat*

data/.rubocop.yml

@@ -0,0 +1,57 @@
+AllCops:
+  Exclude:
+    - '.*'
+    - 'app/*'
+    - 'bin/*'
+    - 'config*'
+    - 'db/*'
+    - '*.md'
+    - 'Gemfile'
+    - 'Gemfile.lock'
+
+Layout/Tab:
+  Enabled: false
+
+Layout/IndentationWidth:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 99
+
+Metrics/MethodLength:
+  CountAsOne: ['array', 'hash', 'heredoc']
+
+Style/RescueModifier:
+  Enabled: false
+
+Layout/TrailingEmptyLines:
+  Enabled: false
+
+Layout/AccessModifierIndentation:
+  Enabled: false
+
+Style/BlockComments:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+Metrics/BlockLength:
+  Exclude: 
+    - 'spec/*'
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: false

data/.ruby-gemset

@@ -0,0 +1 @@
+postgres_upsert

data/.ruby-version

@@ -0,0 +1 @@
+2.6.5

data/.travis.yml

@@ -0,0 +1,20 @@
+language: ruby
+dist: trusty
+before_install:
+  - gpg2 --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
+  - gem install bundler
+  - cp config/database.yml.travis config/database.yml
+  - psql -c 'create database ar_pg_copy_test;' -U postgres
+
+rvm:
+  - 2.5.0
+
+script:
+  - gpg2 --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
+  - bundle exec rake db:setup
+  - bundle exec rspec spec
+services:
+  postgresql
+addons:
+  postgresql: "9.4"
+

data/Gemfile

@@ -1,5 +1,4 @@
 source 'https://rubygems.org'
 
-# specify gem dependencies in activerecord-postgres-hstore.gemspec
-# except the platform-specific dependencies below
+# specify gem dependencies in postgres_upsert.gemspec
 gemspec

data/Gemfile.lock

@@ -1,112 +1,202 @@
 PATH
   remote: .
   specs:
-    postgres_upsert (1.1.0)
+    postgres_upsert (5.1.0)
       activerecord (>= 3.0.0)
-      pg (~> 0.17.0)
+      pg (>= 0.17.0)
       rails (>= 3.0.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionmailer (4.0.3)
-      actionpack (= 4.0.3)
-      mail (~> 2.5.4)
-    actionpack (4.0.3)
-      activesupport (= 4.0.3)
-      builder (~> 3.1.0)
-      erubis (~> 2.7.0)
-      rack (~> 1.5.2)
-      rack-test (~> 0.6.2)
-    activemodel (4.0.3)
-      activesupport (= 4.0.3)
-      builder (~> 3.1.0)
-    activerecord (4.0.3)
-      activemodel (= 4.0.3)
-      activerecord-deprecated_finders (~> 1.0.2)
-      activesupport (= 4.0.3)
-      arel (~> 4.0.0)
-    activerecord-deprecated_finders (1.0.3)
-    activesupport (4.0.3)
-      i18n (~> 0.6, >= 0.6.4)
-      minitest (~> 4.2)
-      multi_json (~> 1.3)
-      thread_safe (~> 0.1)
-      tzinfo (~> 0.3.37)
-    arel (4.0.2)
-    builder (3.1.4)
+    actioncable (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activejob (= 6.1.3.2)
+      activerecord (= 6.1.3.2)
+      activestorage (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      mail (>= 2.7.1)
+    actionmailer (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      actionview (= 6.1.3.2)
+      activejob (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (6.1.3.2)
+      actionview (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      rack (~> 2.0, >= 2.0.9)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activerecord (= 6.1.3.2)
+      activestorage (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      nokogiri (>= 1.8.5)
+    actionview (6.1.3.2)
+      activesupport (= 6.1.3.2)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.1.3.2)
+      activesupport (= 6.1.3.2)
+      globalid (>= 0.3.6)
+    activemodel (6.1.3.2)
+      activesupport (= 6.1.3.2)
+    activerecord (6.1.3.2)
+      activemodel (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+    activestorage (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activejob (= 6.1.3.2)
+      activerecord (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      marcel (~> 1.0.0)
+      mini_mime (~> 1.0.2)
+    activesupport (6.1.3.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.1)
+    builder (3.2.4)
     coderay (1.1.0)
-    diff-lcs (1.1.3)
-    erubis (2.7.0)
-    hike (1.2.3)
-    i18n (0.6.11)
-    json (1.7.6)
-    mail (2.5.4)
-      mime-types (~> 1.16)
-      treetop (~> 1.4.8)
+    concurrent-ruby (1.1.8)
+    crass (1.0.6)
+    database_cleaner-active_record (2.0.1)
+      activerecord (>= 5.a)
+      database_cleaner-core (~> 2.0.0)
+    database_cleaner-core (2.0.1)
+    diff-lcs (1.4.4)
+    erubi (1.10.0)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.4)
+    loofah (2.9.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (1.0.1)
     method_source (0.8.2)
-    mime-types (1.25.1)
-    minitest (4.7.5)
-    multi_json (1.10.1)
-    pg (0.17.1)
-    polyglot (0.3.5)
+    mini_mime (1.0.3)
+    mini_portile2 (2.5.1)
+    minitest (5.14.4)
+    nio4r (2.5.7)
+    nokogiri (1.11.3)
+      mini_portile2 (~> 2.5.0)
+      racc (~> 1.4)
+    parallel (1.19.2)
+    parser (2.7.1.3)
+      ast (~> 2.4.0)
+    pg (1.2.3)
     pry (0.10.1)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
       slop (~> 3.4)
+    pry-nav (0.3.0)
+      pry (>= 0.9.10, < 0.13.0)
     pry-rails (0.3.2)
       pry (>= 0.9.10)
-    rack (1.5.2)
-    rack-test (0.6.2)
-      rack (>= 1.0)
-    rails (4.0.3)
-      actionmailer (= 4.0.3)
-      actionpack (= 4.0.3)
-      activerecord (= 4.0.3)
-      activesupport (= 4.0.3)
-      bundler (>= 1.3.0, < 2.0)
-      railties (= 4.0.3)
-      sprockets-rails (~> 2.0.0)
-    railties (4.0.3)
-      actionpack (= 4.0.3)
-      activesupport (= 4.0.3)
+    racc (1.5.2)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (6.1.3.2)
+      actioncable (= 6.1.3.2)
+      actionmailbox (= 6.1.3.2)
+      actionmailer (= 6.1.3.2)
+      actionpack (= 6.1.3.2)
+      actiontext (= 6.1.3.2)
+      actionview (= 6.1.3.2)
+      activejob (= 6.1.3.2)
+      activemodel (= 6.1.3.2)
+      activerecord (= 6.1.3.2)
+      activestorage (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      bundler (>= 1.15.0)
+      railties (= 6.1.3.2)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    railties (6.1.3.2)
+      actionpack (= 6.1.3.2)
+      activesupport (= 6.1.3.2)
+      method_source
       rake (>= 0.8.7)
-      thor (>= 0.18.1, < 2.0)
-    rake (10.3.2)
-    rdoc (3.12)
-      json (~> 1.4)
-    rspec (2.12.0)
-      rspec-core (~> 2.12.0)
-      rspec-expectations (~> 2.12.0)
-      rspec-mocks (~> 2.12.0)
-    rspec-core (2.12.2)
-    rspec-expectations (2.12.1)
-      diff-lcs (~> 1.1.3)
-    rspec-mocks (2.12.2)
+      thor (~> 1.0)
+    rainbow (3.0.0)
+    rake (13.0.3)
+    rexml (3.2.4)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-rails (5.0.1)
+      actionpack (>= 5.2)
+      activesupport (>= 5.2)
+      railties (>= 5.2)
+      rspec-core (~> 3.10)
+      rspec-expectations (~> 3.10)
+      rspec-mocks (~> 3.10)
+      rspec-support (~> 3.10)
+    rspec-support (3.10.2)
+    rubocop (0.80.1)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.7.0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rexml
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    ruby-progressbar (1.10.1)
     slop (3.6.0)
-    sprockets (2.11.0)
-      hike (~> 1.2)
-      multi_json (~> 1.0)
-      rack (~> 1.0)
-      tilt (~> 1.1, != 1.3.0)
-    sprockets-rails (2.0.1)
-      actionpack (>= 3.0)
-      activesupport (>= 3.0)
-      sprockets (~> 2.8)
-    thor (0.19.1)
-    thread_safe (0.3.4)
-    tilt (1.4.1)
-    treetop (1.4.15)
-      polyglot
-      polyglot (>= 0.3.1)
-    tzinfo (0.3.40)
+    sprockets (4.0.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.2)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    thor (1.1.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (1.6.1)
+    websocket-driver (0.7.3)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.4.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler
+  database_cleaner-active_record
   postgres_upsert!
+  pry-nav
   pry-rails
-  rdoc
-  rspec (~> 2.12)
+  rspec-rails (>= 3.9)
+  rubocop
+
+BUNDLED WITH
+   2.2.3

data/README.md

@@ -1,9 +1,11 @@
-# postgres_upsert
+# postgres_upsert [![Build Status](https://travis-ci.org/theSteveMitchell/postgres_upsert.svg?branch=master)](https://travis-ci.org/theSteveMitchell/postgres_upsert)
 
 Allows your  rails app to load data in a very fast way, avoiding calls to ActiveRecord.
 
 Using the PG gem and postgres's powerful COPY command, you can create thousands of rails objects in your db in a single query.
 
+## Compatibility Note
+The master branch requires the 'pg' gem which only supports MRI ruby.  the jruby branch requires 'activerecord-jdbcpostgresql-adapter' which, of course only supports JRuby.  Installation is the same whatever your platform.
 
 ## Install
 
@@ -17,76 +19,150 @@ Run the bundle command
 
 ## Usage
 
-The gem will add the aditiontal class method to ActiveRecord::Base
-
-* pg_upsert io_object_or_file_path, [options]
-
-io_object_or_file_path => is a file path or an io object (StringIO, FileIO, etc.)
+```ruby
+PostgresUpsert.write <class_or_table_name>, <io_object_or_file_path>[, options]
+```
+<class_or_table_name> is either an ActiveRecord::Base subclass, or a string representing the name of a database table.
+<io_object_or_file_path> can be either a string representing a file path, or an io object (StringIO, FileIO, etc.)
 
 options:
-:delimiter - the string to use to delimit fields.  Default is ","
-:format - the format of the file (valid formats are :csv or :binary).  Default is :csv
-:header => specifies if the file/io source contains a header row.  Either :header option must be true, or :columns list must be passed.  Default true
-:key_column => the primary key or unique key column on your ActiveRecord table, used to distinguish new records from existing records.  Default is the primary_key of your ActiveRecord model class.
-:update_only => when true, postgres_upsert will ONLY update existing records, and not insert new.  Default is false.
-
-pg_upsert will allow you to copy data from an arbritary IO object or from a file in the database server (when you pass the path as string).
-Let's first copy from a file in the database server, assuming again that we have a users table and
-that we are in the Rails console:
+- :delimiter - the string to use to delimit fields from the source data.  Default is ","
+- :header => specifies if the file/io source contains a header row.  Either :header option must be true, or :columns list must be passed.  Default true
+- :unique_key => the primary key or unique key column (or composite key columns) on your destination table, used to distinguish new records from existing records.  Default is the primary_key of your destination table/model.
+- :update_only => when true, postgres_upsert will ONLY update existing records, and not insert new.  Default is false.
 
+## Examples
+for these examples let's assume we have a users table and model:
 ```ruby
-User.pg_upsert "/tmp/users.csv"
+class User < ActiveRecord::Base
+```
+In the rails console we can run:
+```ruby
+PostgresUpsert.write User, "/tmp/users.csv"
 ```
 
-This command will use the headers in the CSV file as fields of the target table, so beware to always have a header in the files you want to import.
-If the column names in the CSV header do not match the field names of the target table, you can pass a map in the options parameter.
-
+This command will use the headers in the CSV file as fields of the target table (by default)
+If the CSV file's header does not match the field names of the User class, you can pass a map in the options parameter.
 ```ruby
-User.pg_upsert "/tmp/users.csv", :map => {'name' => 'first_name'}
+PostgresUpsert.write "users", "/tmp/users.csv", :map => {'name' => 'first_name'}
 ```
+The `name` column in the CSV file will be mapped to the `first_name` field in the users table.
+
+postgres_upsert  supports 'merge' operations, which is not yet natively supported in Postgres.  The data can include both new and existing records, and postgres_upsert will handle either update or insert of records appropriately.  Since the Postgres COPY command does not handle this, postgres_upsert accomplishes it using an intermediary temp table.
+
+The merge/upsert happens in 5 steps (assume your data table is called "users")
+* create a temp table named users_temp_123 where "123" is a random int.  In postgres temp tables are only visible to the current database session, so naming conflicts should not be a problem.  We add this random suffix just for additional safety.
+* COPY the data to user_temp
+* issue a query to insert all new records from users_temp_123 into users ("new" records are those records whos primary key does not already exist in the users)
+* issue a query to update all existing records in users with the data in users_temp_123 ("existing" records are those whose primary key already exists in the users table)
+* drop the temp table.
+
+## timestamp columns
+
+currently postgres_upsert detects and manages the default rails timestamp columns `created_at` and `updated_at`.  If these fields exist in your destination table, postgres_upsert will keep these current as expected.  I recommend you do NOT include these fields in your source CSV/IO, as postgres_upsert will not honor them.
+
+* newly inserted records get a current timestamp for created_at
+* records existing in the source file/IO will get an update to their updated_at timestamp (even if all fields maintain the same value)
+* records that are in the destination table but not the source will not have their timestamps changed.
+
 
-In the above example the header name in the CSV file will be mapped to the field called first_name in the users table.
+### Overriding the unique_key
 
-To copy a binary formatted data file or IO object you can specify the format as binary
+By default postgres_upsert uses the primary key on your ActiveRecord table to determine if each record should be inserted or updated.  You can override the column using the :unique_key option:
 
 ```ruby
-User.pg_upsert "/tmp/users.dat", :format => :binary, :columns => ["id, "name"]
+PostgresUpsert.write User "/tmp/users.csv", :unique_key => ["external_twitter_id"]
 ```
 
-Which will generate the following SQL command:
+obviously, the field you pass must be a unique key in your database (this is not enforced at the moment, but will be)
+
+If your source data does not contain the primary key, or an individual unique key, you can pass multiple columns in the unique_key option:
 
-```sql
-COPY users (id, name) FROM '/tmp/users.dat' WITH BINARY
+```ruby
+  PostgresUpsert.write User "/tmp/users.csv", :unique_key => ["state_id_numer", "state_name"]
 ```
+As long as combined columns represent a unique value, row, we can successfully upsert.
 
-NOTE: binary files do not include header columns, so passing a :columns array is required for binary files.
+passing :update_only => true will ensure that no new records are created, but records will be updated.
 
+### Insert/Update Counts
+PostgresUpsert with also return a PostgresUpsert::Result object that will tell you how many records were inserted or updated:
 
-pg_upsert  supports 'upsert' or 'merge' operations.  In other words, the data source can contain both new and existing objects, and pg_upsert will handle either case.  Since the Postgres native COPY command does not handle updating existing records, pg_upsert accomplishes update and insert using an intermediary temp table:
+```ruby
+User.delete_all
+result = PostgresUpsert.write User "/tmp/users.csv"
+result.inserted 
+# => 10000
+result.updated
+# => 0
+```
 
-This merge/upsert happend in 5 steps (assume your data table is called "users")
-* create a temp table named users_temp_### where "###" is a random number.  In postgres temp tables are only visible to the current database session, so naming conflicts should not be a problem.
-* COPY the data to user_temp
-* issue a query to insert all new records from users_temp_### into users (newness is determined by the presence of the primary key in the users table)
-* issue a query to update all records in users with the data in users_temp_### (matching on primary key)
-* drop the temp table.
+### Huge Caveat!
+Since postgres_upsert does not use validations or even instantiate rails objects, you can get invalid data if you're not careful.  Postgres upsert assumes that your source data is minimally cleaned up, and will not tell you if any data is invalid based on rails model rules.  It will, of course raise an error if data does not conform to your database constraints.
 
-### overriding the key_column
+### Benchmarks!
 
-By default pg_upsert uses the primary key on your ActiveRecord table to determine if each record should be inserted or updated.  You can override the column using the :key_field option:
+Given a User model, (validates presence of email and paassword)
+```console
+2.1.3 :008 > User
+ => User(id: integer, email: string, password: string, created_at: datetime, updated_at: datetime) 
+```
 
+And the following railsy code to create 10,000 users:
 ```ruby
-User.pg_upsert "/tmp/users.dat", :format => :binary, :key_column => ["external_twitter_id"]
+def insert_dumb
+    time = Benchmark.measure do
+      (1..10000).each do |n|
+        User.create!(:email => "number#{n}@email.com", :password => "password#{n)}")
+      end
+    end
+  puts time
+end
 ```
 
-obviously, the field you pass must be a unique key in your database (this is not enforced at the moment, but will be)
+Compared to the following code using Postgres_upsert:
+```ruby
+def insert_smart
+    time = Benchmark.measure do
+      csv_string = CSV.generate do |csv|
+        csv << %w(email password)    # CSV header row
+        (1..10000).each do |n|
+          csv << ["number#{n}@email.com", "password#{n)}"]
+        end
+      end
+      io = StringIO.new(csv_string)
+      PostgresUpsert.write User io, unique_key: "email"
+    end
+    puts time
+end
+```
 
-passing :update_only = true will ensure that no new records are created, but records will be updated.
+let's compare!
+
+```console
+2.1.3 :002 > insert_dumb
+   #...snip  ~30k lines of output :( (10k queries, each wrapped in a transaction)
+   (0.3ms)  COMMIT
+26.639246
+2.1.3 :004 > User.delete_all
+  SQL (15.4ms)  DELETE FROM "users"
+2.1.3 :006 > insert_smart
+   #...snip ~30 lines of output, composing 5 sql queries...
+0.275503
+```
+
+...That's 26.6 seconds for classic create loop... vs. 0.276 seconds for postgres_upsert.  
+This is over 96X faster.  And it only cost me ~6 extra lines of code.
+
+Note that for the benchmark, my database is local.  The performance improvement should only increase when we have network latency to worry about.
 
 ## Note on Patches/Pull Requests
 
-* Fork the project
-* add your feature/fix to your fork(rpsec tests pleaze)
+I greatly appreciate contribution to this gem. 
+
+* Fork the project and clone the repo locally
+* run 'bin/setup' to setup dependencies and create test DB
+* add your feature/fix to your fork(add and run rpsec tests please)
 * submit a PR
 * If you find an issue but can't fix in in a PR, please log an issue.  I'll do my best.