activerecord-shard_for 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a1c8657de406db02ed5d126692643d464da6a34b
-  data.tar.gz: 660d22116ad1eb9fe35c086b3057a14e4a646295
+  metadata.gz: cad523e3ec520b0697848ece57f5703c5d049ea0
+  data.tar.gz: cf3f36c9de0afd5f6f42addc95d9f29081a5d51a
 SHA512:
-  metadata.gz: 33b47bc95f2f8f500ebbeca490977c4d593aa9282260ee087af352a1916e9b03a2ef3348749019087d74fd029c30edbf46d4c98bdd33f3693d42fa866c8e8b3d
-  data.tar.gz: da451ed4f81e438206e8bf45f6c431caad8750e753d9c9eef361893537b43829f0b5affd98c107147b0aa957490691ba7b9ec169c23e7b9c10316437bd2e717e
+  metadata.gz: 18da70aea7e423466d39cd5c677b469320cc18e57f475e60fa82bde5c4370de58bf3c000f8e91c38371ead208842ea91cc848fa3998d257b1bb48171bece222a
+  data.tar.gz: 35261193e6150eefd81f8f323912254edc6448493a701dfaf952edfe3c75bdd8be1ba8c864d7d2e6cf57d415f98fb017de328dd8c545699920b419003d81302f

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG for activerecord-shard_for
 
+## 0.3.0
+
+- Add using syntax. [#8](https://github.com/yuemori/activerecord-shard_for/pull/8)
+
 ## 0.2.1
 
 - Fix raise MissingDistkeyAttribute before callback. [#6](https://github.com/yuemori/activerecord-shard_for/pull/6)

data/README.md

@@ -41,7 +41,9 @@ Or install it yourself as:
 
     $ gem install activerecord-shard_for
 
-## Usage
+# Getting Started
+
+More example to see [wiki](https://github.com/yuemori/activerecord-shard_for/wiki).
 
 Add additional database connection config to database.yml.
 
@@ -103,278 +105,6 @@ alice.save!
 User.all_shards.flat_map {|m| m.find_by(name: 'alice') }.compact
 ```
 
-When you want to execute queries in all nodes in parallel, use .all_shards_in_parallel. It returns `ActiveRecord::ShardFor::AllShardsInParallel` and it offers some collection actions which runs in parallel. It is aliased to .parallel.
-
-```ruby
-User.all_shards_in_parallel.map(&count) #=> 1
-User.parallel.flat_map {|m| m.where(age: 1) }.size #=> 1
-```
-
-Sometimes you want to generates distkey value before validation. Since activerecord-shard_for generates sub class of your models, AR's callback is usesless for this usecase, so activerecord-shard_for offers its own callback method.
-
-```ruby
-class AccessToken < ActiveRecord::Base
-  include ActiveRecord::ShardFor::Model
-  use_cluster :access_token
-  def_distkey :token
-
-  validates :token, presence: true
-
-  def self.generate_token
-    SecureRandom.uuid
-  end
-
-  before_put do |attributes|
-    unless attributes[:token] || attributes['token']
-      attributes[:token] = generate_token
-    end
-  end
-end
-
-access_token = AccessToken.put!
-access_token.token #=> a generated token
-```
-
-If you want to range sharding, `Range` object set to cluster key.
-
-```ruby
-ActiveRecord::ShardFor.configure do |config|
-  config.define_cluster(:user) do |cluster|
-    # unique identifier, connection name
-    cluster.register(0...100, :production_user_001)
-    cluster.register(100...200, :production_user_002)
-    cluster.register(200...300, :production_user_003)
-    cluster.register(300..Float::INFINITY, :production_user_004)
-  end
-end
-
-class User < ActiveRecord::Base
-  include ActiveRecord::ShardFor::Model
-  use_cluster :user, :distkey
-  def_distkey :id
-
-  def self.generate_unique_id
-    # Implement to generate unique id
-  end
-
-  before_put do |attributes|
-    attributes[:id] = generate_unique_id unless attributes[:id]
-  end
-end
-```
-
-## Sharding with Replication
-
-activerecord-shard_for also supports replication.
-
-In case you have 2 shards in cluster and each shard have read replica.
-
-- db-user-101 --replicated--> db-user-102
-- db-user-201 --replicated--> db-user-202
-
-Your database connection configuration might be like this:
-
-```yaml
-# database.yml
-production_user_001:
-  adapter: mysql2
-  username: user_writable
-  host: db-user-101
-production_user_002:
-  adapter: mysql2
-  username: user_writable
-  host: db-user-201
-production_user_readonly_001:
-  adapter: mysql2
-  username: user_readonly
-  host: db-user-102
-production_user_readonly_002:
-  adapter: mysql2
-  username: user_writable
-  host: db-user-202
-```
-
-Your initializer for activerecord-shard_for might be like this:
-
-```ruby
-ActiveRecord::ShardFor.configure do |config|
-  config.define_cluster(:user) do |cluster|
-    cluster.register(0, :production_user_001)
-    cluster.register(1, :production_user_002)
-  end
-
-  config.define_cluster(:user_readonly) do |cluster|
-    # give same key of master
-    cluster.register(0, :production_user_readonly_001)
-    cluster.register(1, :production_user_readonly_002)
-  end
-end
-```
-
-You can split read/write by defining AR model class for each connection:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveRecord::ShardFor::Model
-  use_cluster :user, :hash_modulo
-  def_distkey :email
-end
-
-class UserReadonly < ActiveRecord::Base
-  self.table_name = 'users'
-
-  include ActiveRecord::ShardFor::Model
-  use_cluster :user_readonly, :hash_modulo
-  def_distkey :email
-end
-
-User.put!(name: 'Alice', email: 'alice@example.com')
-UserReadonly.get('alice@example.com')
-```
-
-If you want to switch specific shard to another shard in another cluster, define mapping between each model:
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveRecord::ShardFor::Model
-  use_cluster :user, :hash_modulo
-  def_distkey :email
-
-  replicates_with slave: :UserReadonly
-end
-
-class UserReadonly < ActiveRecord::Base
-  self.table_name = 'users'
-
-  include ActiveRecord::ShardFor::Model
-  use_cluster :user_readonly, :hash_modulo
-  def_distkey :email
-
-  replicates_with master: :User
-end
-```
-
-You can switch to another model which have connection to the shard by calling .switch:
-
-```ruby
-UserReadonly.all_shards do |readonly|
-  target_ids = readonly.where(age: 0).pluck(:id)
-  readonly.switch(:master) do |writable|
-    writable.where(id: target_ids).delete_all
-  end
-end
-```
-
-## Plugin of connection router
-
-If you need to advanced connection routing, implement router class and register this.
-
-### Embeded
-
-Embeded routers:
-
-|name|class|description|
-|:---:|:---:|:---|
-|:hash_modulo|[HashModuloRouter](https://github.com/yuemori/activerecord-shard_for/blob/master/lib/activerecord/shard_for/hash_modulo_router.rb)|use `hash(key) mod connection_count`|
-|:distkey|[DistkeyRouter](https://github.com/yuemori/activerecord-shard_for/blob/master/lib/activerecord/shard_for/distkey_router.rb)|use `distkey` at it is|
-
-Connection Routers specific with cluster in AR model.
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveRecord::ShardFor::Model
-  use_cluster :user, :hash_modulo # use hash_modulo
-  def_distkey :email
-end
-
-class Character < ActiveRecord::Base
-  include ActiveRecord::ShardFor::Model
-  use_cluster :character, :distkey # use distkey at it is
-  def_distkey :shard_no
-end
-```
-
-### Implement
-
-Reference a interface to [HashModuloRouter](https://github.com/yuemori/activerecord-shard_for/blob/master/lib/activerecord/shard_for/hash_modulo_router.rb), [DistkeyRouter](https://github.com/yuemori/activerecord-shard_for/blob/master/lib/activerecord/shard_for/distkey_router.rb) and [ConnectionRouter](https://github.com/yuemori/activerecord-shard_for/blob/master/lib/activerecord/shard_for/connection_router.rb).
-
-Example, simple modulo router:
-
-```ruby
-class SimpleModuloRouter < ActiveRecord::ShardFor::ConnectionRouter
-  def route(key)
-    key.to_i % connection_count
-  end
-end
-```
-
-Your initializer for activerecord-shard_for might be like this:
-
-```ruby
-ActiveRecord::ShardFor.configure do |config|
-  config.register_connection_router(:modulo, SimpleModuloRouter)
-end
-```
-
-And specify router in your AR model.
-
-```ruby
-class User < ActiveRecord::Base
-  include ActiveRecord::ShardFor::Model
-  use_cluster :user, :modulo
-  def_distkey :id
-
-  def self.generate_unique_id
-    # Implement to generate unique id
-  end
-
-  before_put do |attributes|
-    attributes[:id] = generate_unique_id unless attributes[:id]
-  end
-end
-```
-
-## Advanced
-
-More example, sharding key is String:
-
-```ruby
-ActiveRecord::ShardFor.configure do |config|
-  config.define_cluster(:user) do |cluster|
-    # unique identifier, connection name
-    cluster.register('a'..'z', :production_user_001)
-    cluster.register('A'..'Z', :production_user_002)
-    cluster.register('0'..'9', :production_user_003)
-  end
-end
-
-class InitialStringRouter < ActiveRecord::ShardFor::ConnectionRouter
-  def route(key)
-    key.to_s.first
-  end
-end
-
-ActiveRecord::ShardFor.configure do |config|
-  config.register_connection_router(:initial_string, InitialStringRouter)
-end
-
-class User < ActiveRecord::Base
-  include ActiveRecord::ShardFor::Model
-  use_cluster :user, :initial_string
-  def_distkey :id
-
-  def self.generate_unique_id
-    SecureRandom.uuid
-  end
-
-  before_put do |attributes|
-    attributes[:id] = generate_unique_id unless attributes[:id]
-  end
-end
-
-```
-
-
 ## Contributing with ActiveRecord::ShardFor
 
 Contributors are welcome! This is what you need to setup your Octopus development environment:

data/lib/activerecord/shard_for/model.rb

@@ -23,6 +23,16 @@ module ActiveRecord
           self.abstract_class = true
         end
 
+        # Returns a generated model class of included model which specific connection.
+        # @param [Object] shard_key key of a shard connection
+        # @yield [Class] generated model class which key of shard connection
+        # @return [Class] generated model class which key of shard connection
+        def using(shard_key)
+          model = shard_repository.fetch_by_key(shard_key)
+          yield model if block_given?
+          model
+        end
+
         # Returns a generated model class of included model class which has proper
         # connection config for the shard for given key.
         # @param [String] key A value of distkey

data/lib/activerecord/shard_for/version.rb

@@ -1,5 +1,5 @@
 module ActiveRecord
   module ShardFor
-    VERSION = '0.2.1'.freeze
+    VERSION = '0.3.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-shard_for
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - yuemori