exwiw 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b66bdb8ccf3d2043c0a903c70071e0f070b41b9fd89dbc09e3c5385c9b4916c1
-  data.tar.gz: cf1224f47635113127f2e1fcf38f161c539f7b68f0bb8c85ba0c428fa6a202d1
+  metadata.gz: 12765a8f130dec0055149beb7ba69b37c9b548758cfbd8dd807c1499a9fbf0b5
+  data.tar.gz: 9165cda22d6e4eb2ff97a6d386510a04f37d353e2b31ea4b6bada2fc1ad2adb7
 SHA512:
-  metadata.gz: 41a4ef3c8a6da41ccbb92d7e42a519c5260a1bbcf53ce9cdcfe3a18dbca55d509c7ca1492e726bdb82bfc8c101a0a6bcee1dec1c051ceae44910009801d4b64d
-  data.tar.gz: ce5cdc2e96fcacbfc2a7c3ca23c72a22a1c3e765da2e69ad21fd9ebd87bbfdc3619e54a0c6eb5ae94321e4dc1b8651ca73a965cf33509ecafba9349b8a894883
+  metadata.gz: eb9ad3e65e4b8756574b5c97fec28be38cc708604cbdaffcb772bd8958b183a067dffafa44078705ed00346be27a9aa81bd68a212b7bcecf635a84d6a7f86adc
+  data.tar.gz: fd47a8459abec5a56ab2c64c7cecc4ffa916608b2cf9278a68a2985defa18812b4f09b70a54b8d6ac498a305022644a0a0d923358a5a06143dedcb550aab7e84

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-06-23
+
+### Changed
+
+- **`replace_with` now preserves NULL.** A NULL source value stays NULL instead of being replaced by the masked literal (all adapters: MySQL, PostgreSQL, SQLite, MongoDB). Previously masking a nullable column clobbered NULL into a non-NULL value, losing the "not set" signal in the dump and making `.nil?`/`.present?`-dependent code behave differently than against production. The SQL adapters now wrap the masking expression in `CASE WHEN <column> IS NOT NULL THEN <masked> ELSE NULL END`, and the MongoDB adapter skips masking a field whose value is nil or absent. This is a behavior change for **nullable** masked columns only — `NOT NULL` columns are unaffected, and an empty string is a real value that is still masked (only true NULL/absent is preserved). It removes the need for hand-written `raw_sql` `CASE` workarounds to keep NULLs.
+
+## [0.6.2] - 2026-06-21
+
 ## [0.6.1] - 2026-06-20
 
 ## [0.6.0] - 2026-06-20

data/README.md

@@ -253,12 +253,18 @@ The config generator is provided as a Rake task.
 bundle exec rake exwiw:schema:generate
 ```
 
-By default, the schema files will be saved in the `exwiw/schema` directory. You can specify a different output directory by setting the `EXWIW_SCHEMA_DIR_PATH` environment variable:
+The output directory is resolved in this order:
+
+1. the `EXWIW_SCHEMA_DIR_PATH` environment variable, if set;
+2. otherwise `schema_dir` from the config file (`exwiw.yml` / `exwiw.yaml` in the current directory), so the generator and the `exwiw` CLI share one location without repeating the path;
+3. otherwise the `exwiw/schema` default.
 
 ```sh
 EXWIW_SCHEMA_DIR_PATH=custom_directory bundle exec rake exwiw:schema:generate
 ```
 
+As with the CLI, a relative `schema_dir` in the config file is resolved relative to the config file's own directory.
+
 #### Tidying stale config (`schema:tidy`)
 
 `schema:generate` adds and updates config files for the tables it finds, but it never deletes the config file of a table that has been dropped from the application. To reconcile the existing config against the current schema, run:
@@ -608,6 +614,12 @@ and you can use the column name with `{}` to replace the value with the column v
 For example, Let assume we have the record which id is 1,
 then "user{id}@example.com" will be replaced with "user1@example.com".
 
+`replace_with` **preserves NULL**: a source value that is `NULL` (or, for MongoDB, an
+absent field) is left as-is instead of being replaced by the masked literal, so the
+"not set" signal survives into the dump. Only true `NULL`/absent is preserved — an empty
+string is a real value and is still masked. Because of this you do not need to hand-write a
+`raw_sql` `CASE WHEN ... IS NOT NULL ...` to keep NULLs.
+
 #### `raw_sql`
 
 It will used instead of the original value.

data/lib/exwiw/adapter/mongodb_adapter.rb

@@ -514,6 +514,11 @@ module Exwiw
       # pair, with all per-config lookups hoisted into the plan.
       private def apply_mask_plan!(doc, plan)
         plan.masked_fields.each do |name, segments|
+          # Preserve a NULL / absent source value instead of clobbering it into a
+          # masked literal. `doc[name].nil?` is true for both an explicit nil and
+          # an absent key, so an absent key is left absent (not created).
+          next if doc[name].nil?
+
           doc[name] = render_template(segments, doc)
         end
         plan.embedded.each do |child|

data/lib/exwiw/adapter/mysql_adapter.rb

@@ -330,7 +330,7 @@ module Exwiw
           end
 
           replaced = parts.join(", ")
-          "CONCAT(#{replaced})"
+          null_preserving(ast, column, "CONCAT(#{replaced})")
         else
           raise "Unreachable case: #{column.inspect}"
         end

data/lib/exwiw/adapter/postgresql_adapter.rb

@@ -456,7 +456,7 @@ module Exwiw
           end
 
           replaced = parts.join(", ")
-          "CONCAT(#{replaced})"
+          null_preserving(ast, column, "CONCAT(#{replaced})")
         else
           raise "Unreachable case: #{column.inspect}"
         end

data/lib/exwiw/adapter/sqlite_adapter.rb

@@ -298,7 +298,7 @@ module Exwiw
           end
 
           replaced = parts.join(" || ")
-          "(#{replaced})"
+          null_preserving(ast, column, "(#{replaced})")
         else
           raise "Unreachable case: #{column.inspect}"
         end

data/lib/exwiw/adapter.rb

@@ -202,6 +202,17 @@ module Exwiw
       rescue => e
         "<unavailable: #{e.class}: #{e.message}>"
       end
+
+      # Wrap a masking expression so a NULL source value stays NULL instead of
+      # being clobbered into a non-NULL literal. The guard checks the masked
+      # column itself (`column.name`) — not any other column the template may
+      # reference — so only true NULL is preserved; an empty string is a real
+      # value and is still masked. The column reference uses the same
+      # `<from_table>.<col>` form as the Plain branch. Shared by the SQL
+      # adapters' #compile_column_name ReplaceWith handling.
+      private def null_preserving(ast, column, masked_expr)
+        "CASE WHEN #{ast.from_table_name}.#{column.name} IS NOT NULL THEN #{masked_expr} ELSE NULL END"
+      end
     end
 
     # @params [Exwiw::QueryAst] query_ast

data/lib/exwiw/config_file.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Exwiw
+  # Minimal reader for the exwiw config YAML (exwiw.yml / exwiw.yaml).
+  #
+  # The CLI has its own, richer config handling (CLI#apply_config_file!); this
+  # module exists for contexts that have no CLI in scope — chiefly the
+  # `exwiw:schema:*` rake tasks, which otherwise only knew the
+  # EXWIW_SCHEMA_DIR_PATH env var and a hard-coded default. It deliberately
+  # reads only what those tasks need (schema_dir) and never aborts the process:
+  # an absent or unreadable config simply yields nil so the caller can fall back.
+  module ConfigFile
+    # Mirrors CLI::DEFAULT_CONFIG_PATHS; .yml wins when both are present.
+    DEFAULT_PATHS = %w[exwiw.yml exwiw.yaml].freeze
+
+    module_function
+
+    # The `schema_dir` from the config file, expanded to an absolute path
+    # relative to the config file's own directory (matching the CLI). Returns
+    # nil when no config file is found, it cannot be parsed, or it does not set
+    # `schema_dir`. Pass an explicit `path` to read a specific file; otherwise
+    # the default paths are looked up in the current directory.
+    def schema_dir(path = nil)
+      path ||= DEFAULT_PATHS.map { |p| File.expand_path(p) }.find { |p| File.file?(p) }
+      return nil if path.nil? || !File.file?(path)
+
+      config =
+        begin
+          YAML.safe_load(File.read(path))
+        rescue Psych::SyntaxError
+          nil
+        end
+      return nil unless config.is_a?(Hash)
+
+      value = config["schema_dir"]
+      return nil if value.nil?
+
+      # Strip a trailing slash and resolve relative to the config file's
+      # directory, exactly as CLI#expand_dir does.
+      value = value.end_with?("/") ? value[0..-2] : value
+      File.expand_path(value, File.dirname(File.expand_path(path)))
+    end
+  end
+end

data/lib/exwiw/explain_runner.rb

@@ -24,6 +24,7 @@ module Exwiw
       table_by_name = configs.each_with_object({}) { |config, hash| hash[config.name] = config }
 
       target = table_by_name[@dump_target.table_name]
+      validate_target_exists!(target)
       adapter.validate_as_dump_target!(target) if target
 
       dumpable_configs = configs.select { |c| adapter.dumpable?(c) }
@@ -62,6 +63,21 @@ module Exwiw
       end
     end
 
+    # Reject a `--target-table` (or `--target-collection`) absent from the loaded
+    # schema; mirrors Runner#validate_target_exists! so explain and export fail the
+    # same way on a typo. `target` is the looked-up config (nil when not found).
+    #
+    # TODO: same caveat as Runner#validate_target_exists! — this checks the schema
+    # (schema_dir JSON), not the live DB connection; verifying against the
+    # connection would need a table-exists capability on each adapter. revisit.
+    private def validate_target_exists!(target)
+      return if @dump_target.table_name.nil?
+      return unless target.nil?
+
+      raise ArgumentError,
+            "--target-table '#{@dump_target.table_name}' does not exist in the schema (#{@schema_dir})."
+    end
+
     private def validate_ignored(configs)
       ignored_names = configs.select { |c| c.ignore }.map(&:name).to_set
       return if ignored_names.empty?

data/lib/exwiw/runner.rb

@@ -36,6 +36,7 @@ module Exwiw
       table_by_name = configs.each_with_object({}) { |config, hash| hash[config.name] = config }
 
       target = table_by_name[@dump_target.table_name]
+      validate_target_exists!(target)
       adapter.validate_as_dump_target!(target) if target
 
       dumpable_configs = configs.select { |c| adapter.dumpable?(c) }
@@ -211,6 +212,24 @@ module Exwiw
       ignored_names.each { |n| @logger.info("Table '#{n}' is marked ignore:true (schema will be included, data extraction skipped)") }
     end
 
+    # Reject a `--target-table` (or `--target-collection`) that does not match any
+    # table/collection in the loaded schema. Without this a typo'd target silently
+    # matched nothing and produced an empty dump with no indication of the mistake.
+    # `target` is the looked-up config (nil when not found); a nil dump target
+    # (dump-all / scope-column mode) is allowed through.
+    #
+    # TODO: this checks the loaded schema (schema_dir JSON), not the live DB
+    # connection — a table that exists in the database but has no schema config
+    # is still rejected here. We may instead want to verify existence against the
+    # connection (would need a table-exists capability on each adapter). revisit.
+    private def validate_target_exists!(target)
+      return if @dump_target.table_name.nil?
+      return unless target.nil?
+
+      raise ArgumentError,
+            "--target-table '#{@dump_target.table_name}' does not exist in the schema (#{@schema_dir})."
+    end
+
     private def validate_rails_managed_target!(configs)
       return if @dump_target.table_name.nil?
 

data/lib/exwiw/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exwiw
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/exwiw.rb

@@ -6,6 +6,7 @@ require "json"
 require "serdes"
 
 require_relative "exwiw/ext_json"
+require_relative "exwiw/config_file"
 require_relative "exwiw/belongs_to"
 require_relative "exwiw/table_column"
 require_relative "exwiw/table_config"

data/lib/tasks/exwiw.rake

@@ -2,12 +2,23 @@
 
 namespace :exwiw do
   namespace :schema do
+    # Output directory for the generated schema config. Precedence:
+    #   1. EXWIW_SCHEMA_DIR_PATH env var (explicit per-run override)
+    #   2. schema_dir in the exwiw config file (exwiw.yml/.yaml), so generating
+    #      the schema and running the `exwiw` CLI agree on one location without
+    #      repeating the path
+    #   3. the historical "exwiw/schema" default
+    # Resolved at task-run time (after `require "exwiw"` has loaded ConfigFile).
+    resolve_schema_dir = lambda do
+      ENV["EXWIW_SCHEMA_DIR_PATH"] || Exwiw::ConfigFile.schema_dir || "exwiw/schema"
+    end
+
     desc "Generate schema from application"
     task generate: :environment do
       require "exwiw"
 
       Exwiw::SchemaGenerator.from_rails_application(
-        output_dir: ENV["EXWIW_SCHEMA_DIR_PATH"] || "exwiw/schema",
+        output_dir: resolve_schema_dir.call,
       ).generate!
     end
 
@@ -16,7 +27,7 @@ namespace :exwiw do
       require "exwiw"
 
       result = Exwiw::SchemaGenerator.from_rails_application(
-        output_dir: ENV["EXWIW_SCHEMA_DIR_PATH"] || "exwiw/schema",
+        output_dir: resolve_schema_dir.call,
       ).tidy!
 
       if result.empty?
@@ -47,7 +58,7 @@ namespace :exwiw do
       require "exwiw"
 
       Exwiw::MongoidSchemaGenerator.from_rails_application(
-        output_dir: ENV["EXWIW_SCHEMA_DIR_PATH"] || "exwiw/schema",
+        output_dir: resolve_schema_dir.call,
         skip_unsupported: ENV["EXWIW_SKIP_UNSUPPORTED"] == "1",
       ).generate!
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Shia
@@ -61,6 +61,7 @@ files:
 - lib/exwiw/after_insert_hook.rb
 - lib/exwiw/belongs_to.rb
 - lib/exwiw/cli.rb
+- lib/exwiw/config_file.rb
 - lib/exwiw/ddl_postprocessor.rb
 - lib/exwiw/determine_table_processing_order.rb
 - lib/exwiw/embedded_in.rb