pg_spec_helper 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b0b5b3c3620c2ddbf235b94c07c33e9c4242ba5221c5d92997c0504ec550448
-  data.tar.gz: e71a455e469526f1bfe9ef599e4dd37a3dea1e49d0fd18c11ac4cf11035c4a6d
+  metadata.gz: 682ffdd64498aa86215c2af590284dfb04be55dcfaf1b70bfe5f5f88a5475d2c
+  data.tar.gz: 7fdd1581c726301dd48c23d9b386f78823177418e581ad76f042cea87d4583e1
 SHA512:
-  metadata.gz: e433948e243dfdce36e6d6bdd894a18b1bcd9e30b3f622bd4ea2788af1366525c8384c33fff2eeb426548727c85c74c6ce42ce5e3e9006102fd018cbbf068bda
-  data.tar.gz: bdbbbb5df25c8456ec9c09aed3b5f9eae6eb869cd8c2b0395a031613beb744477a7f59cc47474b10b35daed5b6fda9a11111fcd71fd5e18d3f188cce0c26c475
+  metadata.gz: f977a9357f41a826585e15a9946d3769cbd33ecd9f592368cdc8b80276a243474a6cabb7d3ccdb170baf0565e62b1d5c2144ed75a4b5159620de7f65cdfc245c
+  data.tar.gz: c880c669479515f49910e7855ca8f90ad6f4a24cc5d48859bc9203fae22852ecdd9345622249f61ee6fcd6f859402ac3ce73d94372e0542b60ee8d847e4e7ba0

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.1.0](https://github.com/craigulliott/pg_spec_helper/compare/v1.0.0...v1.1.0) (2023-07-10)
+
+
+### Features
+
+* documentation, get methods to retrieve current database structure, and full test coverage ([d6c6230](https://github.com/craigulliott/pg_spec_helper/commit/d6c623055d3ac2920bdc4f805973df7f25208329))
+
 ## 1.0.0 (2023-07-08)
 
 

data/README.md

@@ -1,17 +1,36 @@
 # PGSpecHelper
 
-Monitor and generate database migrations based on difference between current schema and configuration.
 
 [![Gem Version](https://badge.fury.io/rb/pg_spec_helper.svg)](https://badge.fury.io/rb/pg_spec_helper)
 [![Specs](https://github.com/craigulliott/pg_spec_helper/actions/workflows/specs.yml/badge.svg)](https://github.com/craigulliott/pg_spec_helper/actions/workflows/specs.yml)
 [![Types](https://github.com/craigulliott/pg_spec_helper/actions/workflows/types.yml/badge.svg)](https://github.com/craigulliott/pg_spec_helper/actions/workflows/types.yml)
 [![Coding Style](https://github.com/craigulliott/pg_spec_helper/actions/workflows/linter.yml/badge.svg)](https://github.com/craigulliott/pg_spec_helper/actions/workflows/linter.yml)
 
+
+### What this gem is
+
+A helper class for setting up and easily tearing down PostgreSQL database **structure** within a testing environment.
+
+If you are building something which depends on specific database structure, and that structure changes depending on specific tests within your test suite, then this gem is for you.
+
+For example, [platformer](https://www.github.com/craigulliott/platformer) and [dynamic_migrations](https://www.github.com/craigulliott/dynamic_migrations) are two packages which make use of this gem.
+
+
+### What this gem is not
+
+This gem is concerned with the **structure** of your database, not the data/records within your database. If you are looking for a gem which can add data/records to your database within your test suite, then check out [factory_bot](https://github.com/thoughtbot/factory_bot). If you are looking for a tool to reset the state of your database (clear records) after your test suite has completed, then check out [database_cleaner](https://github.com/DatabaseCleaner/database_cleaner).
+
+
 ## Key Features
 
-* Create tables, columns, constraints, indexes and primary/foreign keys
+* Easily create basic tables, columns, constraints, indexes and primary/foreign keys for your specs
+* Provides convenient methods for testing the presence of various database objects
 * Resets your database after each spec, only if the spec made changes
-
+* Ignores `information_schema` and any schemas or tables beginning with `pg_`
+* Configurable to ignore other schemas (such as `postgis`)
+* Automatically resets and recreates the `public` schema
+* Can track and refresh materialized views
+* Easily access the `PG::Connection` object via `pg_spec_helper.connection` to execute your own SQL
 
 ## Installation
 
@@ -29,11 +48,88 @@ Note, this gem depends on the postgres gem `pg`, which depends on the `libpq` pa
 # required for pg gem on apple silicon
 brew install libpq
 export PATH="/opt/homebrew/opt/libpq/bin:$PATH"
-``
+```
 
 ## Getting Started
 
-Todo
+#### Setting up rspec
+
+Install PG Spec Helper into your `spec/spec_helper.rb`
+
+```ruby
+require "pg_spec_helper"
+
+RSpec.configure do |config|
+
+  # make pg_spec_helper conveniently accessable within your test suite
+  config.add_setting :pg_spec_helper
+  config.pg_spec_helper = PGSpecHelper.new(database: :my_database, host: :localhost, port: 5432, username: 'username', password: '**********')
+
+  # optionally add additional schemas which should be ignored
+  config.pg_spec_helper.ignore_schema :postgis
+  config.pg_spec_helper.ignore_schema :some_other_schema
+
+  # If your package uses materialized views which need to be
+  # refreshed after structural changes have occured to your database,
+  # then you can track them and refresh them automatically
+  #
+  # here, the materialized view `my_materialized_view` will be refreshed
+  # automatically after any calls to create_schema, or create_table
+  config.pg_spec_helper.track_materialized_view :public, :my_materialized_view, [
+    :create_schema,
+    :create_table
+  ]
+
+  # assert that your test suite is empty before running the test suite
+  config.before(:suite) do
+    # optionally provide DYNAMIC_MIGRATIONS_CLEAR_DB_ON_STARTUP=true to
+    # force reset your database structure
+    if ENV["DYNAMIC_MIGRATIONS_CLEAR_DB_ON_STARTUP"]
+      config.pg_spec_helper.reset! true
+    else
+      # raise an error unless your database structure is empty
+      config.pg_spec_helper.assert_database_empty!
+    end
+  end
+
+  # reset your database structure after each test (this deletes all
+  # schemas and tables and then recreates the `public` schema)
+  config.after(:each) do
+    config.pg_spec_helper.reset!
+  end
+end
+
+```
+
+The configuration above will assert that your database is completely empty before the test suite runs. If your database is not empty, then an error will be raised.
+
+If rspec crashed or exited prematurely on the last execution of your test suite, then you can tell pg_spec_helper to forcefully clear your database.
+
+`DYNAMIC_MIGRATIONS_CLEAR_DB_ON_STARTUP=true bundle exec rspec`
+
+#### An example test which requires some specific structure
+
+```ruby
+RSpec.describe PGSpecHelper do
+  let(:pg_spec_helper) { RSpec.configuration.pg_spec_helper }
+
+  describe 'where the table `my_schema`.`my_table` exists in the database' do
+    before(:each) do
+      pg_spec_helper.create_schema :my_schema
+      pg_spec_helper.create_table :my_schema, :my_table
+      pg_spec_helper.create_column :my_schema, :my_table, :my_column, :integer
+      pg_spec_helper.create_primary_key :my_schema, :my_schema, :my_table, [:my_column]
+    end
+
+    it "test something which required that table to exist" do
+      expect().to_not raise_error
+    end
+  end
+end
+```
+
+
+See https://github.com/craigulliott/pg_spec_helper/tree/main/lib/pg_spec_helper for all the methods which are available on this class.
 
 
 ## Development

data/lib/pg_spec_helper/columns.rb

@@ -2,18 +2,25 @@
 
 class PGSpecHelper
   module Columns
+    # create a column for the provided table
     def create_column schema_name, table_name, column_name, type
-      # validate the type exists
-      PGSpecHelper::Postgres::DataTypes.validate_type_exists! type
       # note the `type` is safe from sql_injection due to the validation above
       connection.exec(<<-SQL)
         ALTER TABLE #{connection.quote_ident schema_name.to_s}.#{connection.quote_ident table_name.to_s}
-          ADD COLUMN #{connection.quote_ident column_name.to_s} #{type}
+          ADD COLUMN #{connection.quote_ident column_name.to_s} #{sanitize_name type}
       SQL
-      # refresh the cached representation of the database structure
-      refresh_structure_cache_materialized_view
-      # note that the database has been reset and there are no changes
-      @has_changes = true
+    end
+
+    # return an array of column names for the provided table
+    def get_column_names schema_name, table_name
+      rows = connection.exec_params(<<-SQL, [schema_name.to_s, table_name.to_s])
+        SELECT column_name
+        FROM information_schema.columns
+        WHERE table_schema = $1
+          AND table_name = $2
+        ORDER BY ordinal_position;
+      SQL
+      rows.map { |row| row["column_name"].to_sym }
     end
   end
 end

data/lib/pg_spec_helper/connection.rb

@@ -6,20 +6,14 @@ class PGSpecHelper
     end
 
     def connection
-      unless @connection
-        @connection = PG.connect(
-          host: @host,
-          port: @port,
-          user: @username,
-          password: @password,
-          dbname: @database,
-          sslmode: "prefer"
-        )
-        # after initial connect, we refresh the cached representation of
-        # the database structure and constaints
-        refresh_structure_cache_materialized_view
-        refresh_validation_cache_materialized_view
-      end
+      @connection ||= PG.connect(
+        host: @host,
+        port: @port,
+        user: @username,
+        password: @password,
+        dbname: @database,
+        sslmode: "prefer"
+      )
       @connection
     end
   end

data/lib/pg_spec_helper/empty_database.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class PGSpecHelper
+  module EmptyDatabase
+    class DatabaseNotEmptyError < StandardError
+    end
+
+    # We assert there are no schemas before we run the test suite because it
+    # requires starting with an empty database.
+    #
+    # We could clear it automatically here, but don't want to risk deleting data
+    # in case the configuration is wrong and this is connected to an unexpected
+    # database.
+    def assert_database_empty!
+      public_schema_exists = false
+      get_schema_names.each do |schema_name|
+        # we expect the public schema to exist, but assert that it is empty later
+        if schema_name == :public
+          public_schema_exists = true
+          next
+        end
+        raise DatabaseNotEmptyError, "Expected no schemas to exist, but found `#{schema_name}` in `#{@database}` on `#{@host}`. Your test suite might have failed to complete the last time it was run. Please delete all schemas. If you are certain this is pointed at the correct database, then you can set DYNAMIC_MIGRATIONS_CLEAR_DB_ON_STARTUP=true on your console and execute these specs again to automatically clear the database."
+      end
+      # assert that the public schema exists
+      raise DatabaseNotEmptyError, "Public schema does not exist" unless public_schema_exists
+      # assert the public schema has no tables
+      raise DatabaseNotEmptyError, "Public schema is not empty" unless get_table_names(:public).empty?
+      # the database is empty, return true
+      true
+    end
+  end
+end

data/lib/pg_spec_helper/foreign_keys.rb

@@ -2,20 +2,30 @@
 
 class PGSpecHelper
   module ForeignKeys
+    # Create a foreign key
     def create_foreign_key schema_name, table_name, column_names, foreign_schema_name, foreign_table_name, foreign_column_names, foreign_key_name
-      column_names_sql = column_names.map { |n| connection.quote_ident n.to_s }.join(", ")
-      foreign_column_names_sql = column_names.map { |n| connection.quote_ident n.to_s }.join(", ")
+      column_names_sql = column_names.map { |n| sanitize_name n }.join(", ")
+      foreign_column_names_sql = foreign_column_names.map { |n| sanitize_name n }.join(", ")
       # add the foreign key
       connection.exec(<<-SQL)
-        ALTER TABLE #{connection.quote_ident schema_name.to_s}.#{connection.quote_ident table_name.to_s}
-          ADD CONSTRAINT #{connection.quote_ident foreign_key_name.to_s}
+        ALTER TABLE #{sanitize_name schema_name}.#{sanitize_name table_name}
+          ADD CONSTRAINT #{sanitize_name foreign_key_name}
           FOREIGN KEY (#{column_names_sql})
-            REFERENCES #{connection.quote_ident foreign_schema_name.to_s}.#{connection.quote_ident foreign_table_name.to_s} (#{foreign_column_names_sql})
+            REFERENCES #{sanitize_name foreign_schema_name}.#{sanitize_name foreign_table_name} (#{foreign_column_names_sql})
       SQL
-      # refresh the cached representation of the database foreign keys
-      refresh_keys_and_unique_constraints_cache_materialized_view
-      # note that the database has been reset and there are no changes
-      @has_changes = true
+    end
+
+    # returns a list of foreign keys for the provided table
+    def get_foreign_key_names schema_name, table_name
+      rows = connection.exec_params(<<-SQL, [schema_name.to_s, table_name.to_s])
+        SELECT constraint_name
+        FROM information_schema.table_constraints
+        WHERE table_schema = $1
+          AND table_name = $2
+          AND constraint_type = 'FOREIGN KEY'
+        ORDER BY constraint_name;
+      SQL
+      rows.map { |row| row["constraint_name"].to_sym }
     end
   end
 end

data/lib/pg_spec_helper/ignored_schemas.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class PGSpecHelper
+  module IgnoredSchemas
+    # add a schema to the list of ignored schemas
+    def ignore_schema schema_name
+      @ignored_schemas ||= []
+      @ignored_schemas << schema_name.to_sym
+    end
+
+    # get a list of ignored schemas
+    def ignored_schemas
+      ([:information_schema] + (@ignored_schemas || []))
+    end
+  end
+end

data/lib/pg_spec_helper/indexes.rb

@@ -2,15 +2,25 @@
 
 class PGSpecHelper
   module Indexes
-    def create_index schema_name, table_name, column_names, index_name, type, deferrable, initially_deferred
+    # Create an index
+    def create_index schema_name, table_name, column_names, index_name
+      column_names_sql = column_names.map { |n| sanitize_name n }.join(", ")
       connection.exec(<<-SQL)
         CREATE INDEX #{connection.quote_ident index_name.to_s}
-          ON #{connection.quote_ident schema_name.to_s}.#{connection.quote_ident table_name.to_s} (b, c)
+          ON #{connection.quote_ident schema_name.to_s}.#{connection.quote_ident table_name.to_s} (#{column_names_sql})
       SQL
-      # refresh the cached representation of the database indexes
-      refresh_index_cache_materialized_view
-      # note that the database has been reset and there are no changes
-      @has_changes = true
+    end
+
+    # get a list of index names for the provided table
+    def get_index_names schema_name, table_name
+      rows = connection.exec_params(<<-SQL, [schema_name.to_s, table_name.to_s])
+        SELECT indexname
+        FROM pg_indexes
+        WHERE schemaname = $1
+          AND tablename = $2
+        ORDER BY indexname;
+      SQL
+      rows.map { |row| row["indexname"].to_sym }
     end
   end
 end

data/lib/pg_spec_helper/materialized_views.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+class PGSpecHelper
+  module MaterializedViews
+    class MaterializedViewNotTrackedError < StandardError
+    end
+
+    # add the name of a materialized view to a list of views which will
+    # be refreshed after each type of change
+    def track_materialized_view schema_name, materialized_view_name, refresh_after
+      @materialized_views ||= {}
+      @materialized_views[schema_name.to_sym] ||= {}
+
+      # ensure the refresh_after contains at least one trackable method
+      unless refresh_after.is_a?(Array) && refresh_after.count
+        raise ArgumentError, "refresh_after must be an array of trackable method names"
+      end
+
+      # ensure each method in the refresh_after list is trackable
+      refresh_after.each do |method_name|
+        assert_trackable_method_name! method_name
+      end
+
+      @materialized_views[schema_name.to_sym][materialized_view_name.to_sym] = {
+        # assume does not exist until proven otherwise
+        exists: false,
+        # list of methods which should trigger a refresh of this
+        # materialized view
+        refresh_after: refresh_after
+      }
+    end
+
+    private
+
+    # return true if the materialized view exists, otherwise false
+    def materialized_view_exists? schema_name, materialized_view_name
+      # assert this materialized view is being tracked
+      assert_materialized_view_tracked! schema_name, materialized_view_name
+
+      # return true if we've already determined that the materialized view exists
+      # otherwise, check the database and cache the result of the existance check
+      #
+      # the check will be made every time the method is called, until the first
+      # time the materialized view is found to exist, at which point the method
+      # will always return true
+      @materialized_views[schema_name.to_sym][materialized_view_name.to_sym][:exists] ||= connection.exec(<<~SQL).count > 0
+        SELECT TRUE AS exists FROM pg_matviews WHERE schemaname = '#{sanitize_name schema_name}' AND matviewname = '#{sanitize_name materialized_view_name}';
+      SQL
+    end
+
+    # refresh all materialized views that have been tracked
+    def refresh_all_materialized_views
+      @materialized_views&.each do |schema_name, views|
+        views.each do |materialized_view_name, view|
+          if materialized_view_exists? schema_name, materialized_view_name
+            refresh_materialized_view schema_name, materialized_view_name
+          end
+        end
+      end
+    end
+
+    # whenever schema changes are made from within the test suite we need to
+    # rebuild the materialized views that hold a cached representation of the
+    # database structure
+    def refresh_materialized_view schema_name, materialized_view_name
+      # assert this materialized view is being tracked
+      assert_materialized_view_tracked! schema_name, materialized_view_name
+
+      # refresh the view if it exists
+      if materialized_view_exists? schema_name, materialized_view_name
+        connection.exec(<<~SQL)
+          REFRESH MATERIALIZED VIEW #{connection.quote_ident schema_name.to_s}.#{connection.quote_ident materialized_view_name.to_s};
+        SQL
+      end
+    end
+
+    # assert that the provided materialized view is being tracked
+    def assert_materialized_view_tracked! schema_name, materialized_view_name
+      # assert any materialized views are being tracked
+      if @materialized_views.nil?
+        raise MaterializedViewNotTrackedError, "no materialized views are being tracked"
+      end
+      # assert this materialized view is being tracked
+      unless @materialized_views.key? schema_name.to_sym
+        raise MaterializedViewNotTrackedError, "no materialized views for schema `#{schema_name}` are being tracked"
+      end
+      # assert this materialized view is being tracked
+      unless @materialized_views[schema_name.to_sym].key? materialized_view_name.to_sym
+        raise MaterializedViewNotTrackedError, "materialized view `#{schema_name}`.`#{materialized_view_name}` is not being tracked"
+      end
+      # the materialized view does exist, so return true
+      true
+    end
+  end
+end

data/lib/pg_spec_helper/primary_keys.rb

@@ -3,17 +3,30 @@
 class PGSpecHelper
   module PrimaryKeys
     # add a primary_key to the provided table which covers the provided columns
-    def add_primary_key schema_name, table_name, column_names
+    def create_primary_key schema_name, table_name, column_names, primary_key_name
       column_names_sql = column_names.map { |n| connection.quote_ident n.to_s }.join(", ")
       # add the primary_key
       connection.exec(<<-SQL)
-        ALTER TABLE #{connection.quote_ident schema_name.to_s}.#{connection.quote_ident table_name.to_s}
-          ADD PRIMARY KEY (#{column_names_sql})
+        ALTER TABLE #{sanitize_name schema_name.to_s}.#{sanitize_name table_name.to_s}
+          ADD CONSTRAINT #{sanitize_name primary_key_name}
+          PRIMARY KEY (#{column_names_sql})
       SQL
-      # refresh the cached representation of the database primary_key keys
-      refresh_keys_and_unique_constraints_cache_materialized_view
-      # note that the database has been reset and there are no changes
-      @has_changes = true
+    end
+
+    # get the primary_key name for the provided table
+    def get_primary_key_name schema_name, table_name
+      # get the primary_key name
+      rows = connection.exec(<<-SQL, [schema_name.to_s, table_name.to_s])
+        SELECT
+          constraint_name
+        FROM
+          information_schema.table_constraints
+        WHERE
+          table_schema = $1
+          AND table_name = $2
+          AND constraint_type = 'PRIMARY KEY'
+      SQL
+      rows.map { |r| r["constraint_name"].to_sym }.first
     end
   end
 end

data/lib/pg_spec_helper/reset.rb

@@ -0,0 +1,12 @@
+class PGSpecHelper
+  module Reset
+    # reset the database to its original state
+    def reset! force = false
+      if force || has_changes?
+        delete_all_schemas cascade: true
+        # reset the tracking of changes
+        @methods_used = {}
+      end
+    end
+  end
+end

data/lib/pg_spec_helper/sanitize.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class PGSpecHelper
+  module Sanitize
+    class UnsafePostgresNameError < StandardError
+    end
+
+    # returns a sanitized version of the provided name, raises an error
+    # if it is not valid
+    #
+    # this is probably unnessesary due to this gem being used within a test
+    # suite and not a production application, but it is here for completeness
+    # and an abundance of caution
+    def sanitize_name name
+      # ensure the name is a string
+      name = name.to_s
+      # ensure the name is not empty
+      raise UnsafePostgresNameError, "name cannot be empty" if name.empty?
+      # ensure the name does not contain invalid characters
+      raise UnsafePostgresNameError, "name contains invalid characters" unless /\A[a-zA-Z0-9_-]+\z/.match?(name)
+      # return the name
+      name
+    end
+  end
+end

data/lib/pg_spec_helper/schemas.rb

@@ -2,66 +2,46 @@
 
 class PGSpecHelper
   module Schemas
-    # We assert there are no schemas before we run the test suite because it
-    # requires starting with an empty database.
-    #
-    # We could clear it automatically here, but don't want to risk deleting data
-    # in case the configuration is wrong and this is connected to an unexpected
-    # database.
-    def assert_database_empty!
-      public_schema_exists = false
-      get_schema_names.each do |schema_name|
-        if schema_name == "public"
-          public_schema_exists = true
-          next
-        end
-        next if schema_name.start_with? "pg_"
-        next if schema_name == "postgis"
-        next if schema_name == "information_schema"
-        raise "Expected no schemas to exist, but found `#{schema_name}` in `#{@database}` on `#{@host}`. Your test suite might have failed to complete the last time it was run. Please delete all schemas. If you are certain this is pointed at the correct database, then you can set DYNAMIC_MIGRATIONS_CLEAR_DB_ON_STARTUP=true on your console and execute these specs again to automatically clear the database."
-      end
-      # assert that the public schema exists
-      raise "Public schema does not exist" unless public_schema_exists
-      # assert the public schema has no tables
-      raise "Public scheama is not empty" unless get_table_names(:public).empty?
-    end
-
+    # create a new schema in the database
     def create_schema schema_name
       connection.exec(<<-SQL)
         CREATE SCHEMA #{connection.quote_ident schema_name.to_s};
       SQL
-      # refresh the cached representation of the database structure
-      refresh_structure_cache_materialized_view
-      # note that the structure has changed, so that the database can be reset between tests
-      @has_changes = true
     end
 
+    # return a list of the schema names in the database
     def get_schema_names
+      ignored_schemas_sql = ignored_schemas.map { |n| sanitize_name n }.join("', '")
+      # return a list of the schema names from the database
       results = connection.exec(<<-SQL)
         SELECT schema_name
-          FROM information_schema.schemata;
+          FROM information_schema.schemata
+        WHERE
+          schema_name NOT IN ('#{ignored_schemas_sql}')
+          AND schema_name NOT LIKE 'pg_%';
       SQL
-      schema_names = results.map { |row| row["schema_name"] }
+      schema_names = results.map { |row| row["schema_name"].to_sym }
       schema_names.sort
     end
 
+    # delete all schemas in the database
     def delete_all_schemas cascade: false
+      # delete all schemas
       get_schema_names.each do |schema_name|
-        next if schema_name.start_with? "pg_"
-        next if schema_name == "postgis"
-        next if schema_name == "public"
-        next if schema_name == "information_schema"
         connection.exec(<<-SQL)
+          -- temporarily set the client_min_messages to WARNING to
+          -- suppress the NOTICE messages about cascading deletes
+          SET client_min_messages TO WARNING;
           DROP SCHEMA #{connection.quote_ident schema_name.to_s} #{cascade ? "CASCADE" : ""};
+          SET client_min_messages TO NOTICE;
         SQL
       end
-      # refresh the cached representation of the database structure
-      # as removing objects can affect them
-      refresh_structure_cache_materialized_view
-      refresh_validation_cache_materialized_view
-      refresh_keys_and_unique_constraints_cache_materialized_view
-      # note that the database has been reset and there are no changes
-      @has_changes = true
+      # recreate the default `public` schema
+      create_schema :public
+    end
+
+    def schema_exists? schema_name
+      get_schema_names.include? schema_name.to_sym
     end
   end
 end

data/lib/pg_spec_helper/tables.rb

@@ -2,30 +2,36 @@
 
 class PGSpecHelper
   module Tables
+    # create a new table in the provided schema
     def create_table schema_name, table_name
       connection.exec(<<-SQL)
-        CREATE TABLE #{connection.quote_ident schema_name.to_s}.#{connection.quote_ident table_name.to_s}(
+        CREATE TABLE #{sanitize_name schema_name.to_s}.#{sanitize_name table_name.to_s}(
           -- tables are created empty, and have columns added to them later
         );
       SQL
-      # refresh the cached representation of the database structure
-      refresh_structure_cache_materialized_view
-      # note that the structure has changed, so that the database can be reset between tests
-      @has_changes = true
     end
 
+    # return an array of table names for the provided schema
     def get_table_names schema_name
       rows = connection.exec_params(<<-SQL, [schema_name.to_s])
         SELECT table_name FROM information_schema.tables
-          WHERE table_schema = $1
+          WHERE
+            table_schema = $1
+            AND table_name NOT LIKE 'pg_%';
       SQL
-      rows.map { |row| row["table_name"] }
+      table_names = rows.map { |row| row["table_name"].to_sym }
+      table_names.sort
     end
 
+    # delete all tables in the provided schema
     def delete_tables schema_name
       get_table_names(schema_name).each do |table_name|
         connection.exec(<<-SQL)
-          DROP TABLE #{connection.quote_ident schema_name.to_s}.#{connection.quote_ident table_name.to_s} CASCASE
+          -- temporarily set the client_min_messages to WARNING to
+          -- suppress the NOTICE messages about cascading deletes
+          SET client_min_messages TO WARNING;
+          DROP TABLE #{sanitize_name schema_name.to_s}.#{sanitize_name table_name.to_s} CASCADE;
+          SET client_min_messages TO NOTICE;
         SQL
       end
     end

data/lib/pg_spec_helper/track_changes.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+class PGSpecHelper
+  module TrackChanges
+    class UntrackableMethodNameError < StandardError
+    end
+
+    # this is a list of methods that have their useage tracked, this
+    # is used to determine what actions need to be taken when calling
+    # reset! between tests
+    TRACKED_METHOD_CALLS = [
+      :create_schema,
+      :create_table,
+      :create_column
+    ]
+
+    # returns true if any changes have been made to the database structure
+    # optionally pass in a method name to check if that specific method was used
+    def has_changes? method_name = nil
+      if method_name.nil?
+        methods_used.keys.count > 0
+      else
+        assert_trackable_method_name! method_name
+        methods_used[method_name] || false
+      end
+    end
+
+    private
+
+    # track that the provided method name has been used, this allows us to determine later
+    # which methods have been used and what actions need to be taken to reset the database
+    def track_change method_name
+      assert_trackable_method_name! method_name
+      @methods_used ||= {}
+      @methods_used[method_name] ||= true
+    end
+
+    # returns a hash representation of methods which have been used
+    def methods_used
+      @methods_used || {}
+    end
+
+    # raises an error if the provided method name is not trackable, otherwise returns true
+    def assert_trackable_method_name! method_name
+      unless TRACKED_METHOD_CALLS.include? method_name.to_sym
+        raise UntrackableMethodNameError, "method `#{method_name}` is not trackable"
+      end
+      true
+    end
+
+    # overide the trackable methods and record when they are used
+    # this allows us to determine what actions need to be taken
+    # to reset the datasbe between tests
+    def install_trackable_methods
+      TRACKED_METHOD_CALLS.each do |method_name|
+        # keep a pointer to the original method
+        original_method = self.class.instance_method(method_name)
+        # ovveride the original method
+        self.class.define_method(method_name) do |*args|
+          # note that this method was called
+          track_change method_name
+          # call the original method
+          original_method.bind_call(self, *args)
+        end
+      end
+    end
+  end
+end

data/lib/pg_spec_helper/unique_constraints.rb

@@ -3,7 +3,7 @@
 class PGSpecHelper
   module UniqueConstraints
     # add a unique constraint to the provided table and columns
-    def add_unique_constraint schema_name, table_name, column_names, constraint_key_name
+    def create_unique_constraint schema_name, table_name, column_names, constraint_key_name
       column_names_sql = column_names.map { |n| connection.quote_ident n.to_s }.join(", ")
       # add the constraint key
       connection.exec(<<-SQL)
@@ -11,10 +11,22 @@ class PGSpecHelper
           ADD CONSTRAINT #{connection.quote_ident constraint_key_name.to_s}
           UNIQUE (#{column_names_sql})
       SQL
-      # refresh the cached representation of the database constraint keys
-      refresh_keys_and_unique_constraints_cache_materialized_view
-      # note that the database has been reset and there are no changes
-      @has_changes = true
+    end
+
+    # get a list of unique constraints for the provided table
+    def get_unique_constraint_names schema_name, table_name
+      # get the unique constraint names
+      rows = connection.exec(<<-SQL, [schema_name.to_s, table_name.to_s])
+        SELECT
+          constraint_name
+        FROM
+          information_schema.table_constraints
+        WHERE
+          table_schema = $1
+          AND table_name = $2
+          AND constraint_type = 'UNIQUE'
+      SQL
+      rows.map { |r| r["constraint_name"].to_sym }
     end
   end
 end

data/lib/pg_spec_helper/validations.rb

@@ -2,6 +2,7 @@
 
 class PGSpecHelper
   module Validations
+    # create a validation on the provided table and columns
     def create_validation schema_name, table_name, validation_name, check_clause
       # todo the check_clause is vulnerable to sql injection (although this is very low risk because
       #      it is only ever provided by the test suite, and is never provided by the user)
@@ -9,10 +10,22 @@ class PGSpecHelper
         ALTER TABLE #{connection.quote_ident schema_name.to_s}.#{connection.quote_ident table_name.to_s}
           ADD CONSTRAINT #{connection.quote_ident validation_name.to_s} CHECK (#{check_clause})
       SQL
-      # refresh the cached representation of the database structure
-      refresh_validation_cache_materialized_view
-      # note that the database has been reset and there are no changes
-      @has_changes = true
+    end
+
+    # return a list of validation names for the provided table
+    def get_validation_names schema_name, table_name
+      # get the validation names
+      rows = connection.exec(<<-SQL, [schema_name.to_s, table_name.to_s])
+        SELECT
+          constraint_name
+        FROM
+          information_schema.table_constraints
+        WHERE
+          table_schema = $1
+          AND table_name = $2
+          AND constraint_type = 'CHECK'
+      SQL
+      rows.map { |r| r["constraint_name"].to_sym }
     end
   end
 end

data/lib/pg_spec_helper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class PGSpecHelper
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/pg_spec_helper.rb

@@ -5,8 +5,9 @@ require "pg"
 
 require "pg_spec_helper/version"
 
-require "pg_spec_helper/configuration"
 require "pg_spec_helper/connection"
+require "pg_spec_helper/sanitize"
+require "pg_spec_helper/ignored_schemas"
 require "pg_spec_helper/schemas"
 require "pg_spec_helper/tables"
 require "pg_spec_helper/columns"
@@ -15,14 +16,18 @@ require "pg_spec_helper/foreign_keys"
 require "pg_spec_helper/unique_constraints"
 require "pg_spec_helper/primary_keys"
 require "pg_spec_helper/indexes"
-require "pg_spec_helper/validation_cache"
-require "pg_spec_helper/structure_cache"
-require "pg_spec_helper/foreign_key_cache"
-require "pg_spec_helper/index_cache"
+require "pg_spec_helper/materialized_views"
+require "pg_spec_helper/reset"
+require "pg_spec_helper/empty_database"
+require "pg_spec_helper/track_changes"
 
 class PGSpecHelper
-  include Configuration
+  class MissingRequiredOptionError < StandardError
+  end
+
   include Connection
+  include Sanitize
+  include IgnoredSchemas
   include Schemas
   include Tables
   include Columns
@@ -31,36 +36,34 @@ class PGSpecHelper
   include UniqueConstraints
   include PrimaryKeys
   include Indexes
-  include ValidationCache
-  include StructureCache
-  include ForeignKeyCache
-  include IndexCache
+  include MaterializedViews
+  include Reset
+  include EmptyDatabase
+  include TrackChanges
 
   attr_reader :database, :username, :password, :host, :port
 
-  def initialize name
-    load_configuration_for :postgres, name
-
-    @database = require_configuration_value(:database).to_sym
-    @host = require_configuration_value :host
-    @port = require_configuration_value :port
-    @username = require_configuration_value :username
-    @password = optional_configuration_value :password
+  def initialize database:, username:, host:, port:, password: nil
+    # assert that all required options are present
+    raise MissingRequiredOptionError, "database is required" if database.nil?
+    raise MissingRequiredOptionError, "host is required" if host.nil?
+    raise MissingRequiredOptionError, "username is required" if username.nil?
 
-    # will be set to true if any changes are made to the database structure
-    # this is used to determine if the structure needs to be reset between tests
-    @has_changes = false
-  end
-
-  def has_changes?
-    @has_changes
-  end
+    # record the configuration
+    @database = database
+    @host = host
+    @port = port || 5432
+    @username = username
+    # password is optional
+    @password = password
 
-  def reset! force = false
-    if force || @has_changes
-      delete_all_schemas cascade: true
-      # note that the database has been reset and there are no changes
-      @has_changes = false
-    end
+    # the TrackChanges module is used to track high level changes which are
+    # made to the database using this class, this allows us to reach out to the
+    # database and reset it only when needed.
+    #
+    # The `install_trackable_methods` method will override the methods which
+    # we are tracking with a new proxy method which will record when the method
+    # is called before subsequently calling the original method.
+    install_trackable_methods
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pg_spec_helper
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Craig Ulliott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-08 00:00:00.000000000 Z
+date: 2023-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -52,18 +52,19 @@ files:
 - README.md
 - lib/pg_spec_helper.rb
 - lib/pg_spec_helper/columns.rb
-- lib/pg_spec_helper/configuration.rb
 - lib/pg_spec_helper/connection.rb
-- lib/pg_spec_helper/foreign_key_cache.rb
+- lib/pg_spec_helper/empty_database.rb
 - lib/pg_spec_helper/foreign_keys.rb
-- lib/pg_spec_helper/index_cache.rb
+- lib/pg_spec_helper/ignored_schemas.rb
 - lib/pg_spec_helper/indexes.rb
+- lib/pg_spec_helper/materialized_views.rb
 - lib/pg_spec_helper/primary_keys.rb
+- lib/pg_spec_helper/reset.rb
+- lib/pg_spec_helper/sanitize.rb
 - lib/pg_spec_helper/schemas.rb
-- lib/pg_spec_helper/structure_cache.rb
 - lib/pg_spec_helper/tables.rb
+- lib/pg_spec_helper/track_changes.rb
 - lib/pg_spec_helper/unique_constraints.rb
-- lib/pg_spec_helper/validation_cache.rb
 - lib/pg_spec_helper/validations.rb
 - lib/pg_spec_helper/version.rb
 homepage: 

data/lib/pg_spec_helper/configuration.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-class PGSpecHelper
-  module Configuration
-    class MissingConfigurationError < StandardError
-    end
-
-    class ConfigurationNotLoadedError < StandardError
-    end
-
-    class MissingRequiredNameError < StandardError
-    end
-
-    class MissingRequiredDatabaseTypeError < StandardError
-    end
-
-    def load_configuration_for database_type, name
-      @name = name.to_s
-      @database_type = database_type.to_s
-
-      raise MissingRequiredNameError unless @name
-      raise MissingRequiredDatabaseTypeError unless @database_type
-
-      configuration = load_configuration_file
-
-      if configuration[@database_type].nil?
-        raise MissingConfigurationError, "no database configuration found for #{name} in database.yaml"
-      end
-
-      if configuration[@database_type][@name].nil?
-        raise MissingConfigurationError, "no configuration found for #{database_type}.#{name} in database.yaml"
-      end
-
-      @configuration = configuration[@database_type][@name]
-    end
-
-    def optional_configuration_value key
-      @configuration[key.to_s]
-    end
-
-    def require_configuration_value key
-      raise ConfigurationNotLoadedError unless @configuration
-
-      @configuration[key.to_s] || raise(MissingConfigurationError, "no #{key} found for configuration #{@database_type}.#{@name}")
-    end
-
-    def load_configuration_file
-      YAML.load_file("config/database.yaml")
-    end
-  end
-end

data/lib/pg_spec_helper/foreign_key_cache.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-class PGSpecHelper
-  module ForeignKeyCache
-    # whenever schema changes are made from within the test suite we need to
-    # rebuild the materialized views that hold a cached representation of the
-    # database foreign keys
-    def refresh_keys_and_unique_constraints_cache_materialized_view
-      # the first time we detect the presence of the marerialized view, we no longer need to
-      # check for it
-      @keys_and_unique_constraints_cache_exists ||= keys_and_unique_constraints_cache_exists?
-      if @keys_and_unique_constraints_cache_exists
-        connection.exec(<<~SQL)
-          REFRESH MATERIALIZED VIEW public.pg_spec_helper_keys_and_unique_constraints_cache;
-        SQL
-      end
-    end
-
-    def keys_and_unique_constraints_cache_exists?
-      exists = connection.exec(<<~SQL)
-        SELECT TRUE AS exists FROM pg_matviews WHERE schemaname = 'public' AND matviewname = 'pg_spec_helper_keys_and_unique_constraints_cache';
-      SQL
-      exists.count > 0
-    end
-  end
-end

data/lib/pg_spec_helper/index_cache.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-class PGSpecHelper
-  module IndexCache
-    # whenever schema changes are made from within the test suite we need to
-    # rebuild the materialized views that hold a cached representation of the
-    # database indexes
-    def refresh_index_cache_materialized_view
-      # the first time we detect the presence of the marerialized view, we no longer need to
-      # check for it
-      @index_cache_exists ||= index_cache_exists?
-      if @index_cache_exists
-        connection.exec(<<~SQL)
-          REFRESH MATERIALIZED VIEW public.pg_spec_helper_index_cache;
-        SQL
-      end
-    end
-
-    def index_cache_exists?
-      exists = connection.exec(<<~SQL)
-        SELECT TRUE AS exists FROM pg_matviews WHERE schemaname = 'public' AND matviewname = 'pg_spec_helper_index_cache';
-      SQL
-      exists.count > 0
-    end
-  end
-end

data/lib/pg_spec_helper/structure_cache.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-class PGSpecHelper
-  module StructureCache
-    # whenever schema changes are made from within the test suite we need to
-    # rebuild the materialized views that hold a cached representation of the
-    # database structure
-    def refresh_structure_cache_materialized_view
-      # the first time we detect the presence of the marerialized view, we no longer need to
-      # check for it
-      @structure_cache_exists ||= structure_cache_exists?
-      if @structure_cache_exists
-        connection.exec(<<~SQL)
-          REFRESH MATERIALIZED VIEW public.pg_spec_helper_structure_cache;
-        SQL
-      end
-    end
-
-    def structure_cache_exists?
-      exists = connection.exec(<<~SQL)
-        SELECT TRUE AS exists FROM pg_matviews WHERE schemaname = 'public' AND matviewname = 'pg_spec_helper_structure_cache';
-      SQL
-      exists.count > 0
-    end
-  end
-end

data/lib/pg_spec_helper/validation_cache.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-class PGSpecHelper
-  module ValidationCache
-    # whenever schema changes are made from within the test suite we need to
-    # rebuild the materialized views that hold a cached representation of the
-    # database structure
-    def refresh_validation_cache_materialized_view
-      # the first time we detect the presence of the marerialized view, we no longer need to
-      # check for it
-      @validations_cache_exists ||= validations_cache_exists?
-      if @validations_cache_exists
-        connection.exec(<<~SQL)
-          REFRESH MATERIALIZED VIEW public.pg_spec_helper_validations_cache;
-        SQL
-      end
-    end
-
-    def validations_cache_exists?
-      exists = connection.exec(<<~SQL)
-        SELECT TRUE AS exists FROM pg_matviews WHERE schemaname = 'public' AND matviewname = 'pg_spec_helper_validations_cache';
-      SQL
-      exists.count > 0
-    end
-  end
-end