atomic_arrays 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7f109dc67250882c4425341e1c12ae2abd8d9b80
-  data.tar.gz: fce753b3c188ca2a2ae971e68af482e2bce202b3
+  metadata.gz: 6dde301579229402102122bbeeb2860a6841d575
+  data.tar.gz: 61f5d0549fb1afcd43ec1106d3ec34592b3f3e7b
 SHA512:
-  metadata.gz: 8e3d5194b39f156b5035e671846f1714a1a4ad85b4b3ee921ebddb2c030aae715381dd24b0bb61aff0858dc09ab38fe04feaf669dc7f23d67a26fc25cd841c97
-  data.tar.gz: 57fdedc6dbf69f9145c522b9c237ea328c84b845fc83efe87592c6f4e28264497986fd3450c5d4c7507acdddda83f26ac5993471128e65c5ca696a5b8a691283
+  metadata.gz: 8f5905101324c9b1d0d22a8af4039fda7746b6b105c34be0a16c3362b995fe474320ca7bada3d7082f276816da2958a7e4148b3a5d71305e3c15502f13882378
+  data.tar.gz: 6be556c640a7b4b5cedd1ffccb7a93f8dd5e94368476edd0a1a6def30951acb939369fe2caf3c5889593e1d61814022dd396abaafe0fc4eb6f74c529bab5a4b2

data/README.md

@@ -1,6 +1,6 @@
 # AtomicArrays
 
-TODO: Write a gem description
+AtomicArrays is a lightweight gem that aims to assist ActiveRecord with PostgreSQL array operations by offering a couple simple methods to update arrays in the database and the instance that it is called on. These methods are atomic in nature because they update the arrays in the database without relying on the current object's instantiated arrays.
 
 ## Installation
 
@@ -17,12 +17,120 @@ Or install it yourself as:
     $ gem install atomic_arrays
 
 ## Usage
+This gem is very simple to use. After bundling the gem, include it in your ActiveRecord-descended class. Example:
+```ruby
+class User < ActiveRecord::Base
+  include AtomicArrays
+end
+```
+Make sure that you have specified the array field in your migrations. Example:
+```ruby
+class CreateUsers < ActiveRecord::Migration
+  def change
+    create_table :users, force: true do |t|
+      t.string   :name
+      t.text     :hobbies,      array: true,  default: []  # This is an array of strings
+      t.integer  :comment_ids,  array: true,  default: []  # This is an array of ints
+    end
+  end
+end
+```
+
+This will give you a couple of instance methods used in updating and relating arrays. The first argument of each method is the targeted array column and the second is the value/values.
+
+### Appending
+Method `atomic_append(array_column, value)` will take a single value to append it on to the end of the specified PG array. Example:
+```ruby
+user = User.find(1)
+# => <#User id: 1, hobbies: ["Basketball", "Racing"]>
+user.atomic_append(:hobbies, "Eating")
+# => <#User id: 1, hobbies: ["Basketball", "Racing", "Eating"]>  # "Eating" was appended to the array in the db.
+```
+
+### Removing
+Method `atomic_remove(array_column, value)` will remove a single value from the specified PG array. It should be noted that the PG array "remove" function removes ALL occurences of that value, therefore this method does as well. Example:
+```ruby
+user = User.find(2)
+# => <#User id: 2, friend_ids: [12, 34, 89]>
+user.atomic_remove(:friend_ids, 12)
+# => <#User id: 2, friend_ids: [34, 89]>  # 12 was removed from the array in the db.
+```
+
+### Concatenation
+Method `atomic_cat(array_column, value_array)` will concatenate an array of values with the specified PG array. Example:
+```ruby
+user = User.find(2)
+# => <#User id: 2, friend_ids: [34, 89]>
+user.atomic_cat(:friend_ids, [34, 30, 56, 90])
+# => <#User id: 2, friend_ids: [34, 89, 34, 30, 56, 90]>  # All four values were concatenated with the array in the db.
+```
+
+### Relating
+Method `atomic_relate(array_column, related_class, limit=100)` is a little odd and unorthodox with a relational db. It assists with querying a denormalized database that uses arrays. Let's say your `users` table has an array column called `blog_ids` and you also have a `blogs` table with each row having an id, like normal. Every time a `User` creates a blog, you could append that blog's id to your user's `blog_ids` column. When relating your user to his/her blogs (`one->many`), rather than scanning the `blogs`.`user_id` column for your user's id, you could potentially just use this method to grab all of his/her blogs in a single query, without scanning a table. First, make sure `AtomicArrays` is included in both classes, then it'll be ready to go! Example:
+```ruby
+user = User.find(2)
+# => <#User id: 2, blog_ids: [4, 16, 74]>
+user.atomic_relate(:blog_ids, Blog)
+# => [
+#     <#Blog id: 4, body: "This is my blog!">,
+#     <#Blog id: 16, body: "This is my other blog!">,
+#     <#Blog id: 74, body: "This is my third blog!">
+#    ]
+```
+This method is extremely performant, especially with large tables because it uses a subquery to grab all of the user's `blog_ids` then immediately `unnests` the ids `IN` the primary id key of the `blogs` table. The subquery that this method employs has nearly zero overhead on performance. The power of this method really reveals itself with (`many->many`) relationships. For instance, let's say each `Blog` has many authors and each `User` authors many blogs. Instead of having a `blog_users` join table, you can potentially just store all of the blogs' `user_ids` in one of its columns and the users' `blog_ids` on one of their columns. Then you could relate them by using `atomic_relate`.
+
+While denormalizing using arrays may sound like an excellent performance prospect, there are a couple downsides. For instance, with the aformentioned (`many->many`) relationship, you will not be able to store any other columns normally associated with a join table, such as an `updated_at` timestamp. Another downside is that arrays are much harder to query than a join table, even with a GIN index. It should also be noted that PostgreSQL still lacks many features involving arrays, including foreign ids. Arrays should NOT be seen as a direct replacement for (`x->many`) tables/keys, but rather a very performant solution if your database NEEDS to be denormalized.
+
+
+## Expound on this gem's assistance with atomicity.
+So be it! All methods in this gem share the same first argument. When you pass the array column name as the first argument, such as `user.atomic_append(:sports, "Golf")`, it doesn't call the instance's attribute with that name, but rather ignores it, updates the array in the database, then updates the instance's array with the returned columns. What does this mean?
+
+Here's an example of nonatomic arrays. Pretend the code on the left and right are happening at the same time:
+```ruby
+user = User.find(2)                          | user = User.find(2)
+# => <#User id: 2, blog_ids: [4, 16]>        | # => <#User id: 2, blog_ids: [4, 16]>
+user.update({blog_ids: user.blog_ids+=[20]}) | ...  
+# => <#User id: 2, blog_ids: [4, 16, 20]>    | ...
+...                                          | user.update({blog_ids: user.blog_ids+=[35]})
+...                                          | # => <#User id: 2, blog_ids: [4, 16, 35]>
+```
+The same user was being updated on both the left and right, and because the instance on the right side was updated last, it over-wrote the left side's added `blog_id` of `20` with its own `blog_id` update of `35`.
+
+Here's how this gem works in the same situation.
+```ruby
+user = User.find(2)                          | user = User.find(2)
+# => <#User id: 2, blog_ids: [4, 16]>        | # => <#User id: 2, blog_ids: [4, 16]>
+user.atomic_append(:blog_ids, 20)            | ...
+# => <#User id: 2, blog_ids: [4, 16, 20]>    | ...
+...                                          | user.atomic_append(:blog_ids, 35)
+...                                          | # => <#User id: 2, blog_ids: [4, 16, 20, 35]>
+```
+The user's `blog_ids` will now include both `20` and `35` because this gem's methods append the value to the raw data array in the db first, then return the rows and re-hydrate the instance.
+
+## Releases
+
+`1.0.0` - Initial release.
+
+`1.1.0` - Replaced `IN` with `JOIN` clause for `atomic_relate`, providing much better performance with large arrays.
+
+
+## Etcetera
+
+Apologies for any syntax highlighting or grammar issues above.
+
+There is also a class method that this gem uses internally called `execute_and_wrap`. It was heavily influenced by `find_by_sql` in ActiveRecord, so thank you to the Rails guys.
+
+This gem is focused on being both lightweight and performance-oriented. The entire gem is only about fifty lines of actual code. I tried to make the API as simple and predictable as possible. It was tested against Ruby-2.1.0, ActiveRecord 4.0.x, and Postgres 9.3. If you are looking to use the JRuby-AR adapter, this gem is very easy to replicate and modify to fit with the JRuby-AR adapter. I tried it with an earlier iteration of this gem and had no problems adapting it, but I have not tested this version of the gem with JRuby.
+
+This gem is especially powerful if your favorite animal is either a Unicorn or a Puma.
+
+If you find any issues or have any suggestions to improve this gem, open an issue!
+
 
-TODO: Write usage instructions here
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/atomic_arrays/fork )
+1. Fork it ( https://github.com/twincharged/atomic_arrays/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/atomic_arrays.gemspec

@@ -8,12 +8,12 @@ Gem::Specification.new do |spec|
   spec.version       = AtomicArrays::VERSION
   spec.authors       = ["Joseph"]
   spec.email         = ["joseph.cs.ritchie@gmail.com"]
-  spec.summary       = %q{ActiveRecord extension for atomically updating PostgreSQL arrays.}
-  spec.description   = %q{AtomicArrays aims to assist ActiveRecord with updating Postgres arrays
-                          by offering a couple simple methods to change arrays in both the database
-                          and the instance it is called on. These methods are atomic in nature
-                          because they update the arrays in the database without relying on the current
-                          object's instantiated arrays.}
+  spec.summary       = %q{ActiveRecord extension for atomic operations on PostgreSQL arrays.}
+  spec.description   = %q{AtomicArrays is a lightweight gem that aims to assist ActiveRecord
+                          with PostgreSQL array operations by offering a couple simple methods
+                          to update arrays in the database and the instance that it is called on.
+                          These methods are atomic in nature because they update the arrays in
+                          the database without relying on the current object's instantiated arrays.}
   spec.homepage      = "https://github.com/twincharged/atomic_arrays"
   spec.license       = "MIT"
 

data/lib/atomic_arrays.rb

@@ -30,7 +30,7 @@ module AtomicArrays
       raise "Relates to a class, not a string or integer." if (related_class.is_a?(Integer) || related_class.is_a?(String))
       (table, field) = self.prepare_array_query(field)
       related_table = related_class.table_name.inspect
-      return result = related_class.execute_and_wrap(%Q{SELECT #{related_table}.* FROM #{related_table} WHERE #{related_table}.id IN (SELECT unnest(#{table}.#{field}) FROM #{table} WHERE #{table}.id = #{self.id}) LIMIT #{limit}})
+      return result = related_class.execute_and_wrap(%Q{SELECT #{related_table}.* FROM #{related_table} JOIN (SELECT unnest(#{table}.#{field}) AS id FROM #{table} WHERE #{table}.id = #{self.id}) u USING (id) LIMIT #{limit}})
   end
 
   def execute_array_query(field, value, array_method)
@@ -47,7 +47,7 @@ module AtomicArrays
 
   def prepare_array_vals(value)
       prep_array = []
-      [*value].map {|val| val = "\'#{val}\'" if val.class == String; prep_array.push(val)} 
+      [*value].map {|val| val = "\'#{val}\'" if val.class == String; prep_array.push(val)}
       return prep_array.join(", ")
   end
 

data/lib/atomic_arrays/version.rb

@@ -1,3 +1,3 @@
 module AtomicArrays
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/spec/spec_helper.rb

@@ -4,7 +4,11 @@ require "rspec"
 require "yaml"
 
 ActiveRecord::Base.establish_connection(YAML.load_file(File.expand_path("../db/database.yml", __FILE__))["test"])
-# load File.dirname(__FILE__) + '/migrations.rb'
+
+RSpec.configure do |config|
+  config.color = true
+  config.tty = true
+end
 
 
 class User < ActiveRecord::Base
@@ -16,6 +20,8 @@ class Comment < ActiveRecord::Base
   include AtomicArrays
 end
 
+# Seed
+
 Comment.create({id: 1, user_id: 1, body: "from user 1!!!", tags: ["#fun"]})
 Comment.create({id: 2, user_id: 2, body: "from user 2!!!", liker_ids: [4,5]})
 Comment.create({id: 3, user_id: 3, body: "from user 2!!!", tags: ["#fun", "#coolpostbro"]})

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atomic_arrays
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Joseph
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-25 00:00:00.000000000 Z
+date: 2014-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -81,11 +81,11 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '4.0'
 description: |-
-  AtomicArrays aims to assist ActiveRecord with updating Postgres arrays
-                            by offering a couple simple methods to change arrays in both the database
-                            and the instance it is called on. These methods are atomic in nature
-                            because they update the arrays in the database without relying on the current
-                            object's instantiated arrays.
+  AtomicArrays is a lightweight gem that aims to assist ActiveRecord
+                            with PostgreSQL array operations by offering a couple simple methods
+                            to update arrays in the database and the instance that it is called on.
+                            These methods are atomic in nature because they update the arrays in
+                            the database without relying on the current object's instantiated arrays.
 email:
 - joseph.cs.ritchie@gmail.com
 executables: []
@@ -128,7 +128,7 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: ActiveRecord extension for atomically updating PostgreSQL arrays.
+summary: ActiveRecord extension for atomic operations on PostgreSQL arrays.
 test_files:
 - spec/atomic_arrays_spec.rb
 - spec/db/001_create_users.rb