exwiw 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55e0eecbd5d7117c263f00fb43c36e2bcc31c75eb4b7ef0255402bec2ac108dc
-  data.tar.gz: '0913f0804ad33023661b947f88cc86adfeb98ef6b047a93f0ba1f09cea52cec9'
+  metadata.gz: 83bb3c7245d9174e5d16e85e6de2a530b58ca445b570d692c5198682fc43b9ef
+  data.tar.gz: cee17f919dab949c82942eae146a1d6182909ab6ef595e8cfc7d4c3f744d1ede
 SHA512:
-  metadata.gz: bb152c10da5489d005660f458ee8cc526a199a15618e41a625694df6d8cca5df623916c14996f03df1ee969b1c51e43b12fc1b7a8676f2754ae01c7211deb251
-  data.tar.gz: 55ae136ec956f3a3e15d522e3d71388765ab206911e5662e653522d35e3126fb1d67711051bfd19d8cc2a7457194f84065ecc49dde38d7faaca67fddfb70da1f
+  metadata.gz: d655b0e5d55759932d7ab6646cb9ed9d0b699e6c96e6061863091eded7914c736b74c558e8a96d132ea94ef668376ae372a9eacf23f978d52540bf31c38c7c18
+  data.tar.gz: 5e068572f70d2b1869e5dffceba9f681d0b153c0947da3fd7b35d746e7f33bbc6c2d5fa25d23c9dfa0f190e14d3304ec6f2940aa19168749aa05b303c572ea10

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-05-31
+
+### Changed
+
+- Adapter names are now driver-agnostic: `--adapter=mysql` and `--adapter=sqlite` replace the driver-flavored `mysql2` / `sqlite3` as the canonical names (`postgresql` and `mongodb` are unchanged). The CLI stays backward compatible — `mysql2` and `sqlite3` are accepted as aliases and folded onto the canonical name, and the matching is case-insensitive so a Rails app's `connection.adapter_name` (e.g. `Mysql2`, `SQLite`) is absorbed too. There is intentionally no `trilogy` adapter *name*: the MySQL adapter now connects through whichever of the `mysql2` or `trilogy` gem is installed (preferring `mysql2`), so an app on either driver works by passing `--adapter=mysql`. trilogy's typed result values are normalized back to the same raw strings `mysql2`'s `cast: false` returns, so the generated SQL is identical regardless of driver. **Breaking** only for code using the library classes directly: `Exwiw::Adapter::Mysql2Adapter` → `Exwiw::Adapter::MysqlAdapter` and `Exwiw::Adapter::Sqlite3Adapter` → `Exwiw::Adapter::SqliteAdapter`. The `EXWIW_DATABASE_ADAPTER` value passed to `--after-insert-hook` is now the canonical name (`mysql` / `sqlite`).
+
 ## [0.3.1] - 2026-05-31
 
 ### Changed

data/README.md

@@ -37,11 +37,27 @@ gem install exwiw
 
 ## Supported Databases
 
-- mysql2
+- mysql
 - postgresql
-- sqlite3
+- sqlite
 - mongodb (experimental, see [MongoDB notes](#mongodb-notes))
 
+Adapter names are driver-agnostic — they name the database, not the Ruby driver
+or Rails ActiveRecord adapter. For backward compatibility and to absorb the Rails
+adapter spelling, the following aliases are also accepted (case-insensitive):
+
+| `--adapter` value | Aliases accepted |
+| --- | --- |
+| `mysql` | `mysql2` |
+| `sqlite` | `sqlite3` |
+
+So `--adapter=mysql2` and `--adapter=mysql` both select the same MySQL adapter.
+
+For MySQL, exwiw connects through whichever of the `mysql2` or `trilogy` gem is
+available (preferring `mysql2`), so an app on either driver works without any
+extra setup. There is no separate `trilogy` adapter name — pass `--adapter=mysql`
+either way.
+
 ## Usage
 
 exwiw has two subcommands:
@@ -55,7 +71,7 @@ exwiw has two subcommands:
 # dump & masking all records from database to dump.sql based on schema.json
 # pass database password as an environment variable 'DATABASE_PASSWORD'
 exwiw \
-  --adapter=mysql2 \
+  --adapter=mysql \
   --host=localhost \
   --port=3306 \
   --user=reader \
@@ -92,7 +108,7 @@ This command will generate sql files in the `dump` directory.
 idx means the order of the dump. bigger idx might depend on smaller idx,
 so you should import the dump in order.
 
-`insert-000-schema.sql` is generated by shelling out to the database client tools (`mysqldump` for `mysql2`, `pg_dump` for `postgresql`, and the sqlite3 driver for `sqlite3`), so the corresponding client must be available on PATH when running exwiw. The output is post-processed to make it idempotent: `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS` (where the engine supports it), and PostgreSQL's `ALTER TABLE ... ADD CONSTRAINT` statements are wrapped in `DO $$ ... EXCEPTION WHEN duplicate_object`.
+`insert-000-schema.sql` is generated by shelling out to the database client tools (`mysqldump` for `mysql`, `pg_dump` for `postgresql`, and the sqlite3 driver for `sqlite`), so the corresponding client must be available on PATH when running exwiw. The output is post-processed to make it idempotent: `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS` (where the engine supports it), and PostgreSQL's `ALTER TABLE ... ADD CONSTRAINT` statements are wrapped in `DO $$ ... EXCEPTION WHEN duplicate_object`.
 
 you need to delete the records before importing the dump,
 `delete-{idx}-{table_name}.sql` will help you to do that.
@@ -101,7 +117,7 @@ idx meaning is the same as insert sql.
 
 ### `exwiw explain`
 
-Print the compiled SQL and its `EXPLAIN` output (estimate-only; `EXPLAIN QUERY PLAN` on SQLite) for each query that `dump` would run, to stdout. No SELECT is executed. Supported for `mysql2`, `postgresql`, and `sqlite3`. The `mongodb` adapter is not yet supported.
+Print the compiled SQL and its `EXPLAIN` output (estimate-only; `EXPLAIN QUERY PLAN` on SQLite) for each query that `export` would run, to stdout. No SELECT is executed. Supported for `mysql`, `postgresql`, and `sqlite`. The `mongodb` adapter is not yet supported.
 
 ```bash
 # preview the queries exwiw would run, without executing the SELECTs

data/lib/exwiw/adapter/{mysql2_adapter.rb → mysql_adapter.rb}

@@ -2,7 +2,7 @@
 
 module Exwiw
   module Adapter
-    class Mysql2Adapter < Base
+    class MysqlAdapter < Base
       def build_query(table, dump_target, table_by_name)
         Exwiw::QueryAstBuilder.run(table.name, table_by_name, dump_target, @logger)
       end
@@ -11,17 +11,17 @@ module Exwiw
         sql = commented_sql(query_ast)
 
         @logger.debug("  Executing SQL: \n#{sql}")
-        connection.query(sql, cast: false, as: :array).to_a
+        connection.query(sql).rows
       end
 
       def explain(query_ast)
         sql = commented_sql(query_ast)
 
         @logger.debug("  Executing EXPLAIN: \n#{sql}")
-        rows = connection.query("EXPLAIN #{sql}", cast: false).to_a
-        rows.each_with_index.flat_map do |row, i|
+        result = connection.query("EXPLAIN #{sql}")
+        result.rows.each_with_index.flat_map do |row, i|
           ["*************************** #{i + 1}. row ***************************"] +
-            row.map { |k, v| "#{k}: #{v}" }
+            result.fields.zip(row).map { |k, v| "#{k}: #{v}" }
         end.join("\n")
       end
 
@@ -257,17 +257,7 @@ module Exwiw
       end
 
       private def connection
-        @connection ||=
-          begin
-            require 'mysql2'
-            Mysql2::Client.new(
-              host: @connection_config.host,
-              port: @connection_config.port,
-              username: @connection_config.user,
-              password: @connection_config.password,
-              database: @connection_config.database_name
-            )
-          end
+        @connection ||= MysqlClient.new(@connection_config)
       end
     end
   end

data/lib/exwiw/adapter/mysql_client.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Exwiw
+  module Adapter
+    # Thin wrapper over the MySQL driver so MysqlAdapter does not care whether the
+    # host app ships the `mysql2` gem or the `trilogy` gem. exwiw only runs simple
+    # SELECT / EXPLAIN queries, so both drivers are normalized to the same shape:
+    # rows as arrays of String|nil plus the column names.
+    #
+    # Values are normalized to strings to match mysql2's `cast: false` mode, where
+    # every column comes back as a raw string and is quoted uniformly downstream
+    # (see MysqlAdapter#escape_value). mysql2 already returns strings in that mode;
+    # trilogy always casts to Ruby types (Integer / BigDecimal / Time / Date / ...),
+    # so its values are stringified back into the same literal form here.
+    class MysqlClient
+      # Immutable value object: a query's column names and its rows.
+      Result = Data.define(:fields, :rows)
+
+      # Pick the available driver, preferring mysql2 (exwiw's historical default).
+      # require returns false when already loaded, so this is safe to call repeatedly.
+      def self.detect_driver
+        require 'mysql2'
+        :mysql2
+      rescue LoadError
+        begin
+          require 'trilogy'
+          :trilogy
+        rescue LoadError
+          raise LoadError,
+                "exwiw needs the 'mysql2' or 'trilogy' gem to connect to MySQL. " \
+                "Add `gem \"mysql2\"` (or `gem \"trilogy\"`) to your Gemfile."
+        end
+      end
+
+      # Render a driver-returned value as the raw string mysql2's `cast: false`
+      # would have produced, so trilogy's typed values quote identically.
+      def self.stringify_value(value)
+        case value
+        when nil then nil
+        when String then value
+        when Time
+          # Emit fractional seconds only when present. A Time can't tell us the
+          # column's declared precision, so a zero fraction on a DATETIME(6)
+          # column comes out as "...:00" here whereas mysql2's `cast: false`
+          # echoes the raw "...:00.000000"; both re-insert to the same instant.
+          value.nsec.zero? ? value.strftime('%Y-%m-%d %H:%M:%S') : value.strftime('%Y-%m-%d %H:%M:%S.%6N')
+        when Date then value.strftime('%Y-%m-%d')
+        when true then '1'
+        when false then '0'
+        else
+          if defined?(BigDecimal) && value.is_a?(BigDecimal)
+            value.to_s('F')
+          else
+            value.to_s
+          end
+        end
+      end
+
+      attr_reader :driver
+
+      # `driver:` is mainly a test seam to force a specific driver; in normal use
+      # it is auto-detected.
+      def initialize(connection_config, driver: nil)
+        @connection_config = connection_config
+        @driver = (driver || self.class.detect_driver).to_sym
+        ensure_driver_loaded!
+      end
+
+      # @param sql [String]
+      # @return [Result] fields (Array<String>) and rows (Array<Array<String|nil>>)
+      def query(sql)
+        case @driver
+        when :mysql2
+          res = raw.query(sql, cast: false, as: :array)
+          Result.new(res.fields, res.to_a)
+        when :trilogy
+          res = raw.query(sql)
+          rows = res.rows.map { |row| row.map { |value| self.class.stringify_value(value) } }
+          Result.new(res.fields, rows)
+        else
+          raise "Unsupported MySQL driver: #{@driver.inspect}"
+        end
+      end
+
+      private def ensure_driver_loaded!
+        case @driver
+        when :mysql2 then require 'mysql2'
+        when :trilogy then require 'trilogy'
+        else raise "Unsupported MySQL driver: #{@driver.inspect}"
+        end
+      end
+
+      private def raw
+        @raw ||= build_raw
+      end
+
+      private def build_raw
+        options = {
+          host: @connection_config.host,
+          port: @connection_config.port&.to_i,
+          username: @connection_config.user,
+          password: @connection_config.password,
+          database: @connection_config.database_name,
+        }.compact
+
+        case @driver
+        when :mysql2 then Mysql2::Client.new(options)
+        when :trilogy then Trilogy.new(options)
+        end
+      end
+    end
+  end
+end

data/lib/exwiw/adapter/{sqlite3_adapter.rb → sqlite_adapter.rb}

@@ -2,7 +2,7 @@
 
 module Exwiw
   module Adapter
-    class Sqlite3Adapter < Base
+    class SqliteAdapter < Base
       def build_query(table, dump_target, table_by_name)
         Exwiw::QueryAstBuilder.run(table.name, table_by_name, dump_target, @logger)
       end
@@ -53,7 +53,7 @@ module Exwiw
         end
 
         File.open(output_path, 'w') do |file|
-          file.puts("-- Auto-generated by exwiw. Idempotent CREATE statements for sqlite3.")
+          file.puts("-- Auto-generated by exwiw. Idempotent CREATE statements for SQLite.")
           file.puts(statements.join("\n"))
         end
         @logger.info("  Wrote #{statements.size} schema statement(s) to #{output_path}.")

data/lib/exwiw/adapter.rb

@@ -2,6 +2,36 @@
 
 module Exwiw
   module Adapter
+    # The adapter names exwiw uses internally. Deliberately driver-agnostic
+    # (e.g. `mysql`, not `mysql2`) so they describe the database, not the Ruby
+    # driver or Rails ActiveRecord adapter that happens to talk to it.
+    CANONICAL_ADAPTERS = %w[mysql sqlite postgresql mongodb].freeze
+
+    # Maps the older driver-flavored spellings onto exwiw's canonical adapter
+    # name, so the CLI stays backward compatible (`--adapter=mysql2` still works)
+    # and a Rails app's `connection.adapter_name` (e.g. "Mysql2", "SQLite") is
+    # absorbed — lookup is case-insensitive (see .normalize_name).
+    #
+    # NOTE: this only normalizes the *name*; exwiw always connects with the
+    # `mysql2` gem (see MysqlAdapter#connection). It is deliberately not aliased
+    # from `trilogy`: a source app using the trilogy driver still needs the
+    # `mysql2` gem available for exwiw to connect, so accepting `--adapter=trilogy`
+    # would falsely imply trilogy support. Use `--adapter=mysql` in that case.
+    ADAPTER_ALIASES = {
+      "mysql2" => "mysql",
+      "sqlite3" => "sqlite",
+    }.freeze
+
+    # Normalize an adapter name to its canonical form. Unknown names are passed
+    # through (downcased) so the caller can reject them with a clear message.
+    # Returns nil for nil input.
+    def self.normalize_name(name)
+      return nil if name.nil?
+
+      key = name.to_s.downcase
+      ADAPTER_ALIASES.fetch(key, key)
+    end
+
     class Base
       attr_reader :connection_config
 
@@ -129,17 +159,17 @@ module Exwiw
     end
 
     def self.build(connection_config, logger)
-      case connection_config.adapter
-      when 'sqlite3'
-        Adapter::Sqlite3Adapter.new(connection_config, logger)
-      when 'mysql2'
-        Adapter::Mysql2Adapter.new(connection_config, logger)
+      case normalize_name(connection_config.adapter)
+      when 'sqlite'
+        Adapter::SqliteAdapter.new(connection_config, logger)
+      when 'mysql'
+        Adapter::MysqlAdapter.new(connection_config, logger)
       when 'postgresql'
         Adapter::PostgresqlAdapter.new(connection_config, logger)
       when 'mongodb'
         Adapter::MongodbAdapter.new(connection_config, logger)
       else
-        raise 'Unsupported adapter'
+        raise "Unsupported adapter: #{connection_config.adapter.inspect}"
       end
     end
   end

data/lib/exwiw/cli.rb

@@ -99,6 +99,19 @@ module Exwiw
     end
 
     private def validate_options!
+      # Fold driver/Rails adapter spellings (mysql2, sqlite3) into exwiw's
+      # canonical names up front, so every check below — and the
+      # EXWIW_DATABASE_ADAPTER passed to hooks — sees the canonical name.
+      @database_adapter = Adapter.normalize_name(@database_adapter)
+
+      # Reject an unknown adapter up front, before checking adapter-specific
+      # options like host/port/password, so the error points at the real problem.
+      unless Adapter::CANONICAL_ADAPTERS.include?(@database_adapter)
+        $stderr.puts "Invalid adapter. Available options are: #{Adapter::CANONICAL_ADAPTERS.join(', ')} " \
+                     "(aliases also accepted: #{Adapter::ADAPTER_ALIASES.keys.join(', ')})"
+        exit 1
+      end
+
       resolve_target_collection_alias!
       resolve_ids_column_alias!
 
@@ -106,7 +119,7 @@ module Exwiw
         validate_explain_only!
       end
 
-      if @database_adapter != "sqlite3"
+      if @database_adapter != "sqlite"
         required_options = {
           "Target database host" => @database_host,
           "Target database port" => @database_port,
@@ -126,12 +139,6 @@ module Exwiw
         end
       end
 
-      valid_adapters = ["mysql2", "postgresql", "sqlite3", "mongodb"]
-      unless valid_adapters.include?(@database_adapter)
-        $stderr.puts "Invalid adapter. Available options are: #{valid_adapters.join(', ')}"
-        exit 1
-      end
-
       if @subcommand == "export"
         @output_dir ||= "dump"
         @output_format ||= "insert"
@@ -227,7 +234,7 @@ module Exwiw
       end
 
       if @ids_column
-        sql_adapters = ["mysql2", "postgresql", "sqlite3"]
+        sql_adapters = ["mysql", "postgresql", "sqlite"]
         unless sql_adapters.include?(@database_adapter)
           $stderr.puts "--ids-column is only supported by the sql adapters (use --ids-field)"
           exit 1
@@ -323,7 +330,7 @@ module Exwiw
           v = v.end_with?("/") ? v[0..-2] : v
           @config_dir = File.expand_path(v)
         end
-        opts.on("-a", "--adapter=ADAPTER", "Database adapter") { |v| @database_adapter = v }
+        opts.on("-a", "--adapter=ADAPTER", "Database adapter: mysql, sqlite, postgresql, mongodb (aliases: mysql2, sqlite3)") { |v| @database_adapter = v }
         opts.on("--database=DATABASE", "Target database name") { |v| @database_name = v }
         opts.on("--target-table=[TABLE]", "Target table for extraction. If omitted, dump all tables.") { |v| @target_table_name = v }
         opts.on("--target-collection=[COLLECTION]", "Alias of --target-table for the mongodb adapter.") { |v| @target_collection_name = v }

data/lib/exwiw/version.rb

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

data/lib/exwiw.rb

@@ -13,8 +13,9 @@ require_relative "exwiw/mongodb_field"
 require_relative "exwiw/mongodb_collection_config"
 require_relative "exwiw/ddl_postprocessor"
 require_relative "exwiw/adapter"
-require_relative "exwiw/adapter/sqlite3_adapter"
-require_relative "exwiw/adapter/mysql2_adapter"
+require_relative "exwiw/adapter/sqlite_adapter"
+require_relative "exwiw/adapter/mysql_client"
+require_relative "exwiw/adapter/mysql_adapter"
 require_relative "exwiw/adapter/postgresql_adapter"
 require_relative "exwiw/adapter/mongodb_adapter"
 require_relative "exwiw/determine_table_processing_order"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Shia
@@ -45,9 +45,10 @@ files:
 - lib/exwiw.rb
 - lib/exwiw/adapter.rb
 - lib/exwiw/adapter/mongodb_adapter.rb
-- lib/exwiw/adapter/mysql2_adapter.rb
+- lib/exwiw/adapter/mysql_adapter.rb
+- lib/exwiw/adapter/mysql_client.rb
 - lib/exwiw/adapter/postgresql_adapter.rb
-- lib/exwiw/adapter/sqlite3_adapter.rb
+- lib/exwiw/adapter/sqlite_adapter.rb
 - lib/exwiw/after_insert_hook.rb
 - lib/exwiw/belongs_to.rb
 - lib/exwiw/cli.rb