transient_record 1.0.0 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9567dc6a94b5693ba7522664172ec95257734f81820307ed705d1a8a55323aef
-  data.tar.gz: 82833fbb5361c27361347d89b38fb709a102fa5be820be30710a5b1debc061de
+  metadata.gz: 5307d695a68a4250343b0cb8866055f626153fcebde0f0bf69213ef791c777e1
+  data.tar.gz: 8b0185a7d93b93c179ccf69dc8cc497a4012f9dca66e1bf3d90decddf2375963
 SHA512:
-  metadata.gz: 2a5ce0b5c9859a9e88ee78b119891cbc8f2daaa930db25a52fb14a6e93723d1d91e850a67f99fd70b8c1ccda80a52f206bb83a529f8cd52e1e11c9e9fe89c657
-  data.tar.gz: 3c64275220d6138377788c9e294b3f67f5285801ac977e03933489a65654604248a757feeca210cd7b642c01d08941e534d510f9814c252d1d5e8885b298f4d7
+  metadata.gz: 43af400d4dccdfeebd0d5a01c7d7631fb2e43b00453b76fafd7e2e0f2f41bea66b0aa4abdbf057a3139d7dd06d903e5f54ba90c02994f7e44b9449a205729013
+  data.tar.gz: 3c84c3764e9b8c65c1703062b6f1e4ce4a60d89823f6472a9d20ac7b6157073bb3b8082304597f01617c87e084ca361fd5407546b3d9ddecd0796d8120a8d5ad

data/README.md

@@ -16,22 +16,19 @@ Installing Transient Record is a two-step process.
 You can include Transient Record in your `Gemfile`:
 
 ```ruby
+# Add the following to use the most recent release:
 gem "transient_record", group: :test
+
+# Alternatively, you can use the most recent development version:
+gem "transient_record", github: "gregnavis/transient_record", group: :test
 ```
 
+Don't forget to run `bundle install`.
+
 The above assumes it'll be used for testing purposes only, hence the `test`
 group. However, if you intend to use the gem in other circumstances then you may
 need to adjust the group accordingly.
 
-If you'd like to use the latest development release then use the line below
-instead:
-
-```ruby
-gem "transient_record", github: "gregnavis/transient_record", group: :test
-```
-
-After modifying `Gemfile`, run `bundle install`.
-
 ### Step 2: Integrating with the Test Suite
 
 After installing the gem, Transient Record must be integrated with the test
@@ -39,6 +36,9 @@ suite. `TransientRecord.cleanup` must be called around every test case: before
 (to prepare a clean database state for the test case) and after (to leave the
 database in a clean state).
 
+**Transient Record is not prepared to work with parallel test suites, so ensure
+tests that use it run sequentially.**
+
 The snippet below demonstrates integrations with various testing libraries:
 
 ```ruby
@@ -79,7 +79,24 @@ end
 ## Usage
 
 Transient Record can be used to create temporary tables and, optionally, models
-backed by them.
+backed by them. First, you need to define a Transient Record **context**.
+
+A context is a module associated to a specific Active Record base class (like
+`ActiveRecord::Base` or `ApplicationRecord`) that's used to connect to the
+database and as a base class for transient models. Contexts are needed to
+support multiple databases, as Active Record organizes database connections
+around base classes. Consult [the Rails Guides](https://guides.rubyonrails.org/active_record_multiple_databases.html#setting-up-your-application) to learn more
+about using Active Record with multiple databases.
+
+**If you connect to only one database then you need just one context for
+`ActiveRecord::Base`**.
+
+A context is a Ruby module used to define transient tables and models. Here's
+how a context for `ActiveRecord::Base` can be defined:
+
+```ruby
+Primary = TransientRecord.context_for ActiveRecord::Base
+```
 
 A table can be created by calling `create_table`: a thin wrapper around the
 method of the same name in Active Record. The only difference is the method
@@ -87,10 +104,11 @@ in Transient Record implemented a fluent interface that allows calling
 `define_model` on the return value.
 
 For example, the statement below creates a table named `users` with two one
-string column `name` and one integer column `age`:
+string column `name` and one integer column `age` using the `Primary` context
+introduced above:
 
 ```ruby
-create_table :users do |t|
+Primary.create_table :users do |t|
   t.string :name, null: false
   t.integer :age, null: false
 end
@@ -101,18 +119,18 @@ for details.
 
 In order to define a model backed by that table `define_model` can be called
 **on the return value** of `create_table` with a block containing the model
-class body. For example, to define 
+class body. For example, to define
 
 ```ruby
-create_table :users do |t|
+Primary.create_table :users do |t|
   # ...
 end.define_model do
   validates :email, presence: true
 end
 ```
 
-Models are automatically assigned to constants in `TransientRecord::Models`. The
-example above creates `TransientRecord::Models::User`, and is equivalent to:
+Models are automatically assigned to constants. In the example above, the user
+model is assigned to `Primary::User` via code roughly equivalent to:
 
 ```ruby
 class TransientRecord::Models::User < ActiveRecord::Base
@@ -129,8 +147,7 @@ reason it was decided to use regular tables with an explicit cleanup step.
 
 Transient Record may not work properly in parallelized test suites, e.g. if two
 test workers attempt to create a table with the same name then it's likely to
-result in an error. Full support for parallelism **is** on the roadmap, so feel
-free to report any errors and contribute updates.
+result in an error.
 
 ## Author
 

data/lib/transient_record.rb

@@ -2,80 +2,127 @@
 
 # Transient Record helps define transient tables and Active Record models.
 #
-# Defining a transient table and model is a two-step process:
+# It's essential to understand Transient Record Contexts in order to use the
+# library effectively. Let's start the discussion with how Active Record handles
+# connections.
 #
-# 1. {#create_table} to create the table.
-# 2. {#define_model} to define the model.
+# Active Record organizes connection pools around classes. Connecting to
+# multiple databases requires defining multiple abstract classes. For example:
+#
+#     class ApplicationRecord < ActiveRecord::Base
+#     end
+#
+#     class AnalyticsRecord < ApplicationRecord
+#       self.abstract_class = true
+#
+#       connects_to database: { writing: :analytics }
+#     end
+#
+# In this case, +ApplicationRecord.connection+ returns a connection to the
+# primary database and +AnalyticsRecord.connection+ returns a connection to the
+# other database.
+#
+# A context is related to an Active Record base class that's used to access the
+# database directly and to define transient models. After defining an Active
+# Record base class, a context can be created by calling {.context_for} and
+# **must** be assigned to a constant.
+#
+# After the context is created, you can create tables and models by calling
+# {Context#create_table} and {Context#define_model}. When you're done, call
+# {.cleanup} to drop all transient tables and models
+#
+# @example Creating a table and a model
+#   # Define the context for classes using ActiveRecord::Base to connect. It's
+#   # a constant defined outside of the test suite.
+#   Primary = TransientRecord.context_for ActiveRecord::Base
 #
-# @example Creating a table without a model
 #   # #create_table is a wrapper around #create_table in Active Record, and
 #   # works almost exactly like the that method.
-#   TransientRecord.create_table :users do |t|
-#     t.string :email, null: false
-#   end
-#
-# @example Creating a table and a model using fluent interface
-#   # The difference between #create_table and its Active Record counterpart is
-#   # the return value: Transient Record allows calling #define_model on it.
-#   TransientRecord.create_table :users do |t|
+#   Primary.create_table :users do |t|
 #     t.string :email, null: false
 #   end.define_model do
 #     validates :email, presence: true
 #   end
 #
-#   # The transient model can be referenced via TransientRecord::Models::User.
-#   # For example, a new user instance can be instantiated via:
-#   user = TransientRecord::Models::User.new email: nil
+#   # Instantiate the model
+#   user = Primary::User.new email: nil
+#
+#   # Clean up when done.
+#   TransientRecord.cleanup
 #
-# @example Creating a table and a model with regular interface
-#   # Assuming the users table has been created (using Transient Record or
-#   # another method), a User model can be defined via:
-#   TransientRecord.define_model :User do
+# @example Defining a model for a pre-existing table
+#   Primary = TransientRecord.context_for ActiveRecord::Base
+#
+#   Primary.define_model :User do
 #     validates :email, presence: true
 #   end
-module TransientRecord
+#
+#   user = Primary::User.new email: nil
+#
+# @example Creating a table and a model in another database
+#   #
+#   Analytics = TransientRecord.context_for AnalyticsRecord
+#
+#   Analytics.create_table :events do |t|
+#     # ...
+#   end.define_model do
+#     # ...
+#   end
+#
+#   event = Analytics::Event.new
+class TransientRecord
   # Transient Record version number.
-  VERSION = "1.0.0"
+  VERSION = "2.0.0.rc1"
 
-  # A module where all temporary models are defined.
-  #
-  # Models defined via {TransientRecord.define_model}, {TransientRecord#define_model}
-  # or {ModelDefinitionProxy#define_model} are put here in order to avoid
-  # polluting the top-level namespace, potentially conflicting with identically
-  # named constants defined elsewhere.
-  #
-  # @example
-  #   # If a transient users table and its corresponding User model are defined then ...
-  #   TransientRecord.create_table :users do |t|
-  #     t.string :email, null: false
-  #   end.define_model do
-  #     validates :email, presence: true
-  #   end
-  #
-  #   # ... the user model can be referenced via:
-  #   TransientRecord::Models::User
-  module Models
-    # Remove all constants from the module.
+  # A class representing Transient Record errors.
+  class Error < RuntimeError; end
+
+  # A mapping of Active Record base classes to TransientRecord::Contexts.
+  @contexts = {}
+
+  class << self
+    # Creates a namespace for tables and models corresponding to the given base
+    # class.
     #
-    # This method is used by {TransientRecord.cleanup} to undefine temporary
-    # model classes.
+    # Active Record sets up connection pools for abstract Active Record model
+    # classes.
     #
-    # @api private
-    def self.remove_all_consts
-      constants.each { |name| remove_const name }
+    # @param base_class [Class] class inheriting from {::ActiveRecord::Base}
+    # @return [Module] module where transient models will be defined; the module
+    #   extends {Context}, so it's instance methods can be called on the module.
+    def context_for base_class
+      @contexts[base_class] ||= Context.create base_class
     end
-  end
 
-  def create_table *args, &block
-    TransientRecord.create_table(*args, &block)
+    def cleanup
+      @contexts.each_value(&:cleanup)
+      nil
+    end
   end
 
-  def define_model *args, &block
-    TransientRecord.define_model(*args, &block)
-  end
+  # A module for creating Transient Record contexts.
+  #
+  # A context is a Ruby module (created via +Module.new+) and extended with
+  # {Context}. This means instance methods below should be called as module
+  # methods on a context, **not** as instance methods.
+  module Context
+    # Creates a context corresponding to the specified base class.
+    #
+    # @param base_class [Class] Active Record class to use to connect to the
+    #   database and as a base class for models.
+    #
+    # @return [Module] context module used as a namespace for models
+    #
+    # @api private
+    def self.create base_class
+      Module.new do
+        extend Context
+        @base_class       = base_class
+        @transient_tables = []
+      end
+    end
 
-  class << self
-    # Create a transient table.
+    # Creates a transient table.
     #
     # This method can be considered to be a wrapper around +#create_table+ in
     # Active Record, as it forwards its arguments and the block.
@@ -87,130 +134,122 @@ module TransientRecord
     # +temporary: true+ via options, which Active Record will recognized out of
     # the box.
     #
-    # Transient tables must be dropped explicitly by calling {.cleanup}.
+    # Transient tables must be dropped explicitly by calling {.cleanup} or
+    # {#cleanup}.
     #
     # @param table_name [String, Symbol] name of the table to create.
     # @param options [Hash] options to use during table creation; they are
     #   forwarded as is to +create_table+ in Active Record.
     #
-    # @yield [table] table definition forwarded to +create_table+ in Active
-    #   Record.
+    # @yield [table] table definition block forwarded to +create_table+ in
+    #   Active Record.
     #
     # @return [ModelDefinitionProxy]
     #
     # @see https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-create_table Documentation for #create_table in Ruby on Rails
     def create_table table_name, options = {}, &block
       table_name = table_name.to_sym
+      @transient_tables << table_name
 
-      ::ActiveRecord::Migration.suppress_messages do
-        ::ActiveRecord::Migration.create_table table_name, **options, &block
-      end
+      @base_class.connection.create_table table_name, **options, &block
 
-      # Return a proxy object allowing the caller to chain #define_model
-      # right after creating a table so that it can be followed by the model
-      # definition.
-      ModelDefinitionProxy.new table_name
+      ModelDefinitionProxy.new self, table_name
     end
 
-    # Define a transient Active Record model.
+    # Defines a transient Active Record model.
     #
     # Calling this method is roughly equivalent to defining a class inheriting
-    # from +ActiveRecord::Base+ with class body defined by the block passed to
-    # the method.
+    # from the class the context corresponds to and with class body defined by
+    # the block passed to the method.
     #
-    # Transient models must be removed explicitly by calling {.cleanup}.
+    # Transient models must be removed explicitly by calling {.cleanup} or
+    # {#cleanup}.
     #
     # @example
+    #   Primary = TransientRecord.context_for ApplicationRecord
+    #
     #   # The following method call ...
-    #   TransientRecord.define_model(:User) do
+    #   Primary.define_model(:User) do
     #     validates :email, presence: true
     #   end
     #
     #   # ... is roughly equivalent to this class definition.
-    #   class TransientRecord::Models::User < ActiveRecord::Base
+    #   class Primary::User < ApplicationRecord
     #     validates :email, presence: true
     #   end
     #
     #
     # @param model_name [String, Symbol] name of model to define.
-    # @param base_class [Class] model base class.
     #
-    # @yield expects the class body to be passed via the block
+    # @yield class definition
     #
     # @return [nil]
-    def define_model model_name, base_class = ::ActiveRecord::Base, &block
-      model_name = model_name.to_sym
-
-      # Normally, when a class is defined via `class MyClass < MySuperclass` the
-      # .name class method returns the name of the class when called from within
-      # the class body. However, anonymous classes defined via Class.new DO NOT
-      # HAVE NAMES. They're assigned names when they're assigned to a constant.
-      # If we evaluated the class body, passed via block here, in the class
-      # definition below then some Active Record macros would break
-      # (e.g. has_and_belongs_to_many) due to nil name.
-      #
-      # We solve the problem by defining an empty model class first, assigning to
-      # a constant to ensure a name is assigned, and then reopening the class to
-      # give it a non-trivial body.
-      klass = Class.new base_class
-      Models.const_set model_name, klass
+    def define_model model_name, &block
+      klass = Class.new @base_class
+      const_set model_name, klass
 
       klass.class_eval(&block) if block_given?
 
       nil
     end
 
-    # Drop transient tables and models.
+    # Drops transient tables and models.
     #
-    # This method **MUST** be called after every test cases that used Transient
-    # Record, as it's responsible for ensuring a clean slate for the next run.
-    # It does the following:
+    # Calling this method removes all models and drops all tables created within
+    # this context. Instead of calling this method, you usually should
+    # {.cleanup} to cleanup **all** contexts.
     #
-    # 1. Remove all models defined via {.define_model}.
-    # 2. Drop all tables created via {.create_table}.
-    # 3. Start garbage collection.
+    # Calling this method does the following:
     #
-    # The last step is to ensure model classes are actually removed, and won't
-    # appear among the descendants hierarchy of +ActiveRecord::Base+.
+    # 1. Remove all models defined via {#define_model}.
+    # 2. Drop all tables created via {#create_table}.
+    # 3. Run garbage collection to ensure model classes are truly removed. This
+    #    may be needed in some versions of Active Record.
     #
     # @return [nil]
     def cleanup
-      Models.remove_all_consts
+      constants.each { |name| remove_const name }
 
-      connection = ::ActiveRecord::Base.connection
-      tables_to_remove = connection.tables
+      tables_to_remove = @transient_tables
       drop_attempts = tables_to_remove.count * (1 + tables_to_remove.count) / 2
 
       drop_attempts.times do
-        table = tables_to_remove.shift
+        table = tables_to_remove.pop
         break if table.nil?
 
         begin
-          connection.drop_table table, force: :cascade, if_exists: true
+          @base_class.connection.drop_table table, force: :cascade, if_exists: true
         rescue ActiveRecord::InvalidForeignKey, ActiveRecord::StatementInvalid
           # ActiveRecord::StatementInvalid is raised by MySQL when attempting to
           # drop a table that has foreign keys referring to it.
-          tables_to_remove << table
+          tables_to_remove.unshift(table)
         end
       end
 
+      if !@transient_tables.empty?
+        raise Error.new(<<~ERROR)
+          The following transient tables could not be removed: #{@transient_tables.join(', ')}.
+        ERROR
+      end
+
       GC.start
 
       nil
     end
   end
 
-  # A model definition proxy is a helper class used to implement a fluent
-  # interface to callers allowing them to create a table and its corresponding
+  # A model definition proxy is a helper class implementing a fluent
+  # interface allowing callers to create a table and its corresponding
   # model in close succession. It's marked private as there's no need for
-  # callers to access it.
+  # callers to access it directly.
   class ModelDefinitionProxy
-    def initialize table_name
-      @table_name = table_name.to_s
+    def initialize context, table_name
+      @context    = context
+      @table_name = table_name
     end
 
     def define_model &block
-      TransientRecord.define_model @table_name.classify, &block
+      @context.define_model @table_name.to_s.classify, &block
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: transient_record
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0.rc1
 platform: ruby
 authors:
 - Greg Navis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-24 00:00:00.000000000 Z
+date: 2023-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -28,98 +28,98 @@ dependencies:
   name: mysql2
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.5.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.5.3
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.1.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.1.4
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.5.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.5.4
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 12.3.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 12.3.3
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.9.28
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.9.28
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.43.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.43.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.6.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.6.0
 description:
@@ -148,11 +148,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.2.33
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Define transient tables and Active Record models for testing purposes.