activerecord-sqlite-types 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 873091c3ae92306fad28b8bdef1ab2895e614c057a4bc984737946f8a824e195
-  data.tar.gz: b3fb232c0eb97337a0d0ad1b15595ed0ca86ccd2a2beaddd6ee01b5a03687980
+  metadata.gz: f959c0cd5e305d5ff04b053a280c8dc20d1f731f548c0b4625e6c6cd3db52887
+  data.tar.gz: 8401efafe0d900337d772313489636ee66343b0fefc9d88568758d45f1894daa
 SHA512:
-  metadata.gz: 1590a06734245552d6f3ef569ba637a50d692e48e344c57dd053489b0aab96cb8d1fa5c6f478513dec2d29bda19d2becd61dbb3d6f4292ed0dc8fd3a39e33cb8
-  data.tar.gz: 6f64ddd2a5e0ad9dfd414f97b9e0d249a21d171c92306c8b83e1faf1289f2be4807b7434a59bbe08869b4f1e1deb53ca89cd842528743c96cff075160e3364f4
+  metadata.gz: a986c9134475c7b79a7cde4c7d5e7ee0e68697cb6a4f59e47ac94e3e4dbf1f40cae397a735dbb1bb093ff8599f73d64daf46085da5f6ba356fa3d295d1c2b63a
+  data.tar.gz: c7b6677372b165e0958b4f2c7af73a77829c2d71f21fdd93260ca3a132b19f4e7cf7e56b5037a7f112cd9cabf30c09f1e364de2044349763a9e9e9033c6fba76

data/.mutant.yml

@@ -0,0 +1,18 @@
+---
+usage: opensource
+includes:
+  - lib
+  - test
+requires:
+  - sqlite_types
+  - generators/sqlite_types/migration/migration_generator
+environment_variables:
+  SIMPLECOV_DISABLED: "1"
+integration:
+  name: minitest
+jobs: 1
+mutation:
+  timeout: 30.0
+matcher:
+  subjects:
+    - SQLiteTypes*

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-14
+
+### Added
+
+- Add Rails migration generator for PostgreSQL-to-SQLite type preparation migrations
+- Add migration helpers for reversible `inet`, `interval`, and PostgreSQL array conversions
+- Add exact `text[]` rollback support and nested-array rollback validation for PostgreSQL migrations
+- Add integration tests for ActiveRecord persistence, querying, migration data preservation, and generator output
+- Preserve PostgreSQL array `NULL` elements across SQLite JSON-backed array types and migration rollbacks
+- Preserve PostgreSQL array element order during JSON-to-array rollback conversions
+- Add PostgreSQL rollback preflight validation for incompatible JSON array elements before schema changes
+- Add PostgreSQL rollback preflight validation for the actual target array casts before schema changes
+- Lock affected PostgreSQL array tables during rollback validation and restoration when a migration transaction is open
+- Preserve SQL `NULL` array elements when restoring PostgreSQL `json`/`jsonb` arrays
+- Reject invalid nested JSON array shapes without relying on PostgreSQL scalar array-length errors
+- Serialize `:datetime` arrays in PostgreSQL-compatible timestamp JSON format for migrated-row equality queries
+- Allow JSON-backed array subtypes to store broader JSON values after migration with best-effort subtype casting
+- Reject JSON array numeric values that Rails would serialize as strings or `null`
+- Match PostgreSQL `inet` casting for blank and invalid string assignments by casting them to `nil`
+
 ## [0.2.0] - 2025-10-24
 
 ### Fixed

data/README.md

@@ -18,11 +18,45 @@ And then execute:
 bundle install
 ```
 
+## Migration Generator
+
+Generate a rollback-aware type-preparation migration while your application is still running on PostgreSQL:
+
+```bash
+bin/rails generate sqlite_types:migration prepare_sqlite_types \
+  --inet users.current_sign_in_ip users.last_sign_in_ip \
+  --interval timings.time_offset \
+  --array events.relationship_statuses:string event_classes.summary_points:text:nested email_notification_logs.attachments:hash
+```
+
+The generator creates a migration that includes `SQLiteTypes::MigrationHelpers`:
+
+```ruby
+class PrepareSqliteTypes < ActiveRecord::Migration[7.1]
+  include SQLiteTypes::MigrationHelpers
+
+  def change
+    change_inet_to_string :users, :current_sign_in_ip
+    change_inet_to_string :users, :last_sign_in_ip
+    change_interval_to_string :timings, :time_offset
+    change_array_to_json :events, :relationship_statuses, :string
+    change_array_to_json :event_classes, :summary_points, :text, nested: true
+    change_array_to_json :email_notification_logs, :attachments, :hash
+  end
+end
+```
+
+The generated migration is PostgreSQL-only. Run it while the application is still backed by PostgreSQL, then keep the app on PostgreSQL long enough to verify the SQLite-compatible column types with your normal Rails code, staging traffic, and test suite. After that, copy the prepared data to SQLite with a separate data migration tool.
+
+On the way up, `change_array_to_json` converts PostgreSQL array columns to `jsonb` and adds a `jsonb_typeof(...) = 'array'` check constraint. On PostgreSQL rollback, it rebuilds the original array column through a temporary column so data compatible with the original PostgreSQL type remains reversible. Nullability is preserved unless you pass `null:` explicitly. The default assumes PostgreSQL-style empty-array defaults; if a column has different default semantics, edit the generated migration and pass `default:` explicitly. Use `:text` when the original column was `text[]`; `:string` restores a Rails `string`/`varchar[]` column. Array element order and SQL `NULL` elements are preserved. Rollbacks lock affected array tables when running inside Rails' default PostgreSQL migration transaction, preflight JSON shape, element compatibility, and the actual PostgreSQL target casts before changing schema, then raise `ActiveRecord::IrreversibleMigration` for incompatible values. Nested PostgreSQL arrays must remain rectangular with non-empty inner arrays because PostgreSQL multidimensional arrays cannot represent ragged JSON arrays or preserve empty inner arrays.
+
 ## Available Types
 
 ### IpAddress
 
 Replaces PostgreSQL's `inet` type with a string representation that preserves IP address functionality.
+The Ruby value is an `IPAddr`, matching Rails' PostgreSQL `inet` type. `IPAddr` normalizes CIDR host bits when casting values like `192.0.2.15/24`; the migration helper preserves existing database text during the SQL type change, but new model assignments follow Rails' `IPAddr` semantics.
+Blank or invalid string assignments cast to `nil`, matching Rails' PostgreSQL `inet` type. String query values are validated and then kept as written, so queries against migrated rows with preserved host bits match PostgreSQL `inet` text behavior. Invalid strings passed directly to query/persistence serialization are rejected instead of being stored as text.
 
 **Usage:**
 
@@ -36,15 +70,12 @@ end
 **Migration:**
 
 ```ruby
-class MigrateInetToString < ActiveRecord::Migration[7.0]
-  def up
-    change_column :users, :current_sign_in_ip, :string
-    change_column :users, :last_sign_in_ip, :string
-  end
+class MigrateInetToString < ActiveRecord::Migration[7.1]
+  include SQLiteTypes::MigrationHelpers
 
-  def down
-    change_column :users, :current_sign_in_ip, :inet, using: 'current_sign_in_ip::inet'
-    change_column :users, :last_sign_in_ip, :inet, using: 'last_sign_in_ip::inet'
+  def change
+    change_inet_to_string :users, :current_sign_in_ip
+    change_inet_to_string :users, :last_sign_in_ip
   end
 end
 ```
@@ -53,7 +84,11 @@ end
 
 Replaces PostgreSQL arrays with JSON-backed arrays, supporting querying via SQLite's JSON functions.
 
-**Supported subtypes:** `:integer`, `:string`, `:hash`, `:datetime`
+**Supported subtypes:** `:integer`, `:string`, `:text`, `:hash`, `:json`, `:jsonb`, `:datetime`
+
+All subtypes preserve `nil` elements, matching PostgreSQL array `NULL` elements. At runtime, `SQLiteTypes::Array` casts values only when they already fit the declared subtype; for example, integer strings become integers and datetime strings become `Time` values. Values outside the declared subtype are still allowed when they are native JSON values, because SQLite JSON storage can hold broader data after migration.
+
+For example, `:integer` can store integers outside PostgreSQL `integer[]`/`int4[]` bounds and even non-integer JSON values; those values are valid for SQLite but can make a future rollback to the original PostgreSQL column type fail cleanly before schema changes. The same broader-value rule applies to `:string`, `:text`, `:hash`, and `:datetime`; rollback restores `:string` and `:text` through PostgreSQL text conversion, while incompatible values in other subtypes can block rollback. `:datetime` serializes time values in the same timestamp string shape PostgreSQL `to_jsonb(timestamp[])` uses, so equality queries can match migrated rows. The `:json` and `:jsonb` subtypes accept native JSON values only; non-finite floats and Ruby numerics that Rails would encode as strings, such as `BigDecimal`, `Rational`, and `Complex`, are rejected to avoid silent type changes or `null` writes.
 
 **Usage:**
 
@@ -68,15 +103,12 @@ end
 **Migration:**
 
 ```ruby
-class MigrateArrayToJson < ActiveRecord::Migration[7.0]
-  def up
-    change_column :users, :personality_traits, :json
-    change_column :users, :favorite_numbers, :json
-  end
+class MigrateArrayToJson < ActiveRecord::Migration[7.1]
+  include SQLiteTypes::MigrationHelpers
 
-  def down
-    change_column :users, :personality_traits, :text, array: true, default: [], using: 'personality_traits::text[]'
-    change_column :users, :favorite_numbers, :integer, array: true, default: [], using: 'favorite_numbers::integer[]'
+  def change
+    change_array_to_json :users, :personality_traits, :string
+    change_array_to_json :users, :favorite_numbers, :integer
   end
 end
 ```
@@ -88,6 +120,7 @@ For array querying functionality, see [Stephen Margheim's article on enhancing R
 ### Interval
 
 Replaces PostgreSQL's `interval` type with ISO8601 duration strings.
+Fixed-length `ActiveSupport::Duration` values are serialized through their total seconds, so equivalent durations like `150.minutes` and `2.hours + 30.minutes` use the same queryable representation. Variable durations with month or year parts keep their calendar components.
 
 **Usage:**
 
@@ -100,25 +133,23 @@ end
 **Migration:**
 
 ```ruby
-class MigrateIntervalToString < ActiveRecord::Migration[7.0]
-  def up
-    change_column :events, :duration, :string
-  end
+class MigrateIntervalToString < ActiveRecord::Migration[7.1]
+  include SQLiteTypes::MigrationHelpers
 
-  def down
-    change_column :events, :duration, :interval, using: 'duration::interval'
+  def change
+    change_interval_to_string :events, :duration
   end
 end
 ```
 
 ## Migration Strategy
 
-The recommended approach for migrating from PostgreSQL to SQLite is incremental and reversible:
+The recommended approach for migrating from PostgreSQL to SQLite is incremental and reversible while data remains compatible with the original PostgreSQL column types:
 
 1. **Prepare while still on PostgreSQL:**
    - Add custom type declarations to your models
    - Run migrations to change column types (e.g., `inet` → `string`)
-   - Test thoroughly - migrations are reversible!
+   - Test thoroughly; rollbacks are preflighted and reversible for compatible data.
 
 2. **Switch to SQLite:**
    - Update `database.yml` to point to SQLite
@@ -133,7 +164,7 @@ For a detailed migration guide, see [this presentation on migrating from Postgre
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests with SimpleCov's 100% line and branch coverage gates. Run `bundle exec standardrb` for style checks and `bundle exec mutant run` for the mutation test suite. The default `rake` task runs all three gates.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 

data/lib/activerecord-sqlite-types.rb

@@ -1,8 +1,12 @@
 require "active_record"
+require "active_support/time"
+require "date"
+require "ipaddr"
 require_relative "sqlite_types/version"
 require_relative "sqlite_types/ip_address"
 require_relative "sqlite_types/array"
 require_relative "sqlite_types/interval"
+require_relative "sqlite_types/migration_helpers"
 
 module SQLiteTypes
 end

data/lib/generators/sqlite_types/migration/migration_generator.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require "sqlite_types/migration_helpers"
+
+module SQLiteTypes
+  module Generators
+    class MigrationGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      IDENTIFIER_PATTERN = /\A[a-zA-Z_]\w*\z/
+      ARRAY_MODIFIERS = %w[nested].freeze
+
+      namespace "sqlite_types:migration"
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :inet,
+        type: :array,
+        default: [],
+        banner: "table.column",
+        desc: "inet columns to migrate to string"
+      class_option :interval,
+        type: :array,
+        default: [],
+        banner: "table.column",
+        desc: "interval columns to migrate to string"
+      class_option :array,
+        type: :array,
+        default: [],
+        banner: "table.column:subtype[:nested]",
+        desc: "PostgreSQL array columns to migrate to json/jsonb"
+
+      def self.next_migration_number(dirname)
+        if timestamped_migrations?
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        else
+          "%.3d" % (current_migration_number(dirname) + 1)
+        end
+      end
+
+      def self.timestamped_migrations?
+        return ActiveRecord.timestamped_migrations if ActiveRecord.respond_to?(:timestamped_migrations)
+        return ActiveRecord::Base.timestamped_migrations if ActiveRecord::Base.respond_to?(:timestamped_migrations)
+
+        true
+      end
+
+      def create_migration_file
+        validate_column_options!
+
+        migration_template "migration.rb.tt", "db/migrate/#{file_name}.rb"
+      end
+
+      private
+
+      def validate_column_options!
+        return if inet_columns.any? || interval_columns.any? || array_columns.any?
+
+        raise Rails::Generators::Error, "Provide at least one --inet, --interval, or --array column"
+      end
+
+      def migration_version
+        ActiveRecord::Migration.current_version
+      end
+
+      def inet_columns
+        @inet_columns ||= Array(options[:inet]).map { |spec| parse_column_spec(spec) }
+      end
+
+      def interval_columns
+        @interval_columns ||= Array(options[:interval]).map { |spec| parse_column_spec(spec) }
+      end
+
+      def array_columns
+        @array_columns ||= Array(options[:array]).map { |spec| parse_array_spec(spec) }
+      end
+
+      def parse_column_spec(spec)
+        table_name, column_name = spec.to_s.split(".", 2)
+        raise Rails::Generators::Error, "Expected column as table.column, got #{spec.inspect}" if table_name.empty? || column_name.to_s.empty?
+        validate_identifier! table_name, "table"
+        validate_identifier! column_name, "column"
+
+        ColumnSpec.new(table_name: table_name, column_name: column_name)
+      end
+
+      def parse_array_spec(spec)
+        column_spec, subtype, *modifiers = spec.to_s.split(":")
+        raise Rails::Generators::Error, "Expected array column as table.column:subtype, got #{spec.inspect}" if subtype.to_s.empty?
+        validate_array_subtype! subtype
+        validate_array_modifiers! modifiers
+
+        column = parse_column_spec(column_spec)
+        ArraySpec.new(
+          table_name: column.table_name,
+          column_name: column.column_name,
+          subtype: subtype,
+          nested: modifiers.include?("nested")
+        )
+      end
+
+      def validate_identifier!(value, label)
+        return if value.match?(IDENTIFIER_PATTERN)
+
+        raise Rails::Generators::Error, "Invalid #{label} identifier: #{value.inspect}"
+      end
+
+      def validate_array_subtype!(subtype)
+        return if SQLiteTypes::MigrationHelpers::SUPPORTED_ARRAY_SUBTYPES.include?(subtype.to_sym)
+
+        raise Rails::Generators::Error, "Unsupported array subtype: #{subtype.inspect}"
+      end
+
+      def validate_array_modifiers!(modifiers)
+        unknown_modifiers = modifiers - ARRAY_MODIFIERS
+        return if unknown_modifiers.empty?
+
+        raise Rails::Generators::Error, "Unsupported array modifier: #{unknown_modifiers.first.inspect}"
+      end
+
+      ColumnSpec = Struct.new(:table_name, :column_name, keyword_init: true)
+      ArraySpec = Struct.new(:table_name, :column_name, :subtype, :nested, keyword_init: true)
+    end
+  end
+end

data/lib/generators/sqlite_types/migration/templates/migration.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "sqlite_types/migration_helpers"
+
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= migration_version %>]
+  include SQLiteTypes::MigrationHelpers
+
+  def change
+<% inet_columns.each do |column| -%>
+    change_inet_to_string :<%= column.table_name %>, :<%= column.column_name %>
+<% end -%>
+<% interval_columns.each do |column| -%>
+    change_interval_to_string :<%= column.table_name %>, :<%= column.column_name %>
+<% end -%>
+<% array_columns.each do |column| -%>
+    change_array_to_json :<%= column.table_name %>, :<%= column.column_name %>, :<%= column.subtype %><%= ", nested: true" if column.nested %>
+<% end -%>
+  end
+end

data/lib/sqlite_types/array.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require "date"
+
 module SQLiteTypes
   class Array < ActiveRecord::Type::Json
-    SUPPORTED_SUBTYPES = %i[integer string hash datetime].freeze
+    SUPPORTED_SUBTYPES = %i[integer string text hash json jsonb datetime].freeze
+    POSTGRESQL_TIMESTAMP_JSON_FORMAT = "%Y-%m-%dT%H:%M:%S.%6N"
 
     def initialize(subtype, nested: false)
+      subtype = subtype.to_sym if subtype.respond_to?(:to_sym)
       raise ArgumentError, "Unsupported subtype: #{subtype}" unless SUPPORTED_SUBTYPES.include?(subtype)
 
       @subtype = subtype
@@ -15,19 +19,25 @@ module SQLiteTypes
     def deserialize(value)
       return if value.nil?
 
-      array = parse_to_array(value)
+      array = parse_array(value)
 
       if @nested
-        array.map { |nested_array| parse_to_array(nested_array).map { |element| cast_element(element) } }
+        array.map do |nested_array|
+          parse_array(nested_array, nested: true).map { |element| cast_element(element) }
+        end
       else
         array.map { |element| cast_element(element) }
       end
     end
 
     def serialize(value)
-      raise ArgumentError, "Invalid value: #{value}" if !valid?(value)
+      return super if value.nil?
 
-      super
+      # Normalize through the same cast path as reads so persisted values and equality queries
+      # use one canonical JSON representation for the declared subtype.
+      array = deserialize(value)
+      array = serialize_datetime_array(array) if @subtype == :datetime
+      super(array)
     end
 
     # Use "=" instead of "IN" in WHERE clause, to match PostgreSQL arrays
@@ -37,41 +47,108 @@ module SQLiteTypes
 
     private
 
-    def valid?(value)
-      return true if value.nil?
-      return false if !value.is_a?(::Array)
-      return value.all? { |nested_array| nested_array.is_a?(::Array) } if @nested
-
-      true
-    end
-
-    def parse_to_array(value)
-      case value
+    def parse_array(value, nested: false)
+      array = case value
       when ::String
         begin
           parsed = ::ActiveSupport::JSON.decode(value)
-          parsed.is_a?(::Array) ? parsed : nil
+          parsed if parsed.instance_of?(::Array)
         rescue JSON::ParserError
           nil
         end
       when ::Array
         value
       end
+
+      return array if array
+
+      description = nested ? "nested array" : "array"
+      raise ArgumentError, "Invalid #{description} value: #{value.inspect}"
     end
 
     def cast_element(elem)
+      raise ArgumentError, "Invalid #{@subtype} array element: #{elem.inspect}" unless storable_element?(elem)
+
       case @subtype
       when :integer
-        elem.to_i
-      when :string
-        elem.to_s
+        integer_string?(elem) ? cast_integer_element(elem) : elem
+      when :string, :text
+        elem
       when :hash
-        elem.to_h
+        elem.is_a?(::Hash) ? elem.to_h : elem
+      when :json, :jsonb
+        elem
       when :datetime
-        elem.is_a?(::String) ? ::DateTime.parse(elem).in_time_zone : elem
+        cast_datetime_element(elem)
       else
         raise ArgumentError, "Unsupported subtype: #{@subtype}"
       end
     end
+
+    def storable_element?(elem)
+      return true if @subtype == :datetime && datetime_like?(elem)
+
+      json_compatible?(elem)
+    end
+
+    def datetime_like?(value)
+      value.acts_like?(:time) || value.is_a?(::Date)
+    end
+
+    def integer_string?(value)
+      value.is_a?(::String) && value.match?(/\A[+-]?\d+\z/)
+    end
+
+    def cast_integer_element(value)
+      Integer(value, 10)
+    end
+
+    def cast_datetime_element(value)
+      return value.respond_to?(:in_time_zone) ? value.in_time_zone : value if datetime_like?(value)
+      return value unless value.is_a?(::String)
+
+      parse_datetime(value)&.in_time_zone || value
+    end
+
+    def parse_datetime(value)
+      ::DateTime.parse(value)
+    rescue ArgumentError
+      nil
+    end
+
+    def serialize_datetime_array(array)
+      if @nested
+        array.map { |nested_array| nested_array.map { |element| serialize_datetime_element(element) } }
+      else
+        array.map { |element| serialize_datetime_element(element) }
+      end
+    end
+
+    def serialize_datetime_element(element)
+      return element unless element.acts_like?(:time)
+
+      postgresql_timestamp_json(element)
+    end
+
+    def postgresql_timestamp_json(element)
+      # PostgreSQL to_jsonb(timestamp[]) emits timestamp text without a time-zone suffix,
+      # and omits the fractional part when it is zero.
+      element.to_time.utc.strftime(POSTGRESQL_TIMESTAMP_JSON_FORMAT).sub(/(\.\d*?)0+\z/, "\\1").delete_suffix(".")
+    end
+
+    def json_compatible?(value)
+      case value
+      when nil, true, false, ::String, ::Integer
+        true
+      when ::Float
+        value.finite?
+      when ::Array
+        value.all? { |element| json_compatible?(element) }
+      when ::Hash
+        value.all? do |key, element|
+          (key.is_a?(::String) || key.instance_of?(::Symbol)) && json_compatible?(element)
+        end
+      end
+    end
   end
 end

data/lib/sqlite_types/interval.rb

@@ -7,7 +7,7 @@ module SQLiteTypes
     def serialize(value)
       case value
       when ::ActiveSupport::Duration
-        value.iso8601(precision: precision)
+        canonical_duration(value).iso8601(precision: precision)
       when ::Numeric
         ::ActiveSupport::Duration.build(value).iso8601(precision: precision)
       else
@@ -21,10 +21,14 @@ module SQLiteTypes
 
     private
 
+    def canonical_duration(value)
+      return value if value.variable?
+
+      ::ActiveSupport::Duration.build(value)
+    end
+
     def cast_value(value)
       case value
-      when ::ActiveSupport::Duration
-        value
       when ::String
         begin
           ::ActiveSupport::Duration.parse(value)

data/lib/sqlite_types/ip_address.rb

@@ -7,23 +7,49 @@ module SQLiteTypes
 
       case value
       when ::IPAddr
-        "#{value}/#{value.prefix}"
+        serialize_ipaddr(value)
       when ::String
-        ip_addr = ::IPAddr.new(value)
-        "#{ip_addr}/#{ip_addr.prefix}"
+        ::IPAddr.new(value)
+        value
       else
         raise ArgumentError, "Invalid IP address: #{value}"
       end
     end
 
+    def changed?(old_value, new_value, _new_value_before_type_cast)
+      !serialize_for_change(old_value).eql?(serialize_for_change(new_value))
+    end
+
+    def changed_in_place?(raw_old_value, new_value)
+      !serialize_for_change(raw_old_value).eql?(serialize_for_change(new_value))
+    rescue ArgumentError
+      true
+    end
+
     private
 
+    def serialize_ipaddr(value)
+      "#{value}/#{value.prefix}"
+    end
+
+    def serialize_for_change(value)
+      return if value.nil?
+
+      cast_value(value)
+    end
+
     def cast_value(value)
       case value
       when ::IPAddr
         value
       when ::String
-        ::IPAddr.new(value)
+        begin
+          ::IPAddr.new(value)
+        rescue ::IPAddr::InvalidAddressError
+          # Rails' PostgreSQL inet type casts invalid string assignments to nil;
+          # serialization still raises for invalid query and persistence values.
+          nil
+        end
       else
         raise ArgumentError, "Invalid IP address: #{value}"
       end

data/lib/sqlite_types/migration_helpers.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/filters"
+require "digest"
+require_relative "array"
+
+module SQLiteTypes
+  module MigrationHelpers
+    DEFAULT_NOT_PROVIDED = Object.new.freeze
+    POSTGRESQL_IDENTIFIER_LIMIT = 63
+    SUPPORTED_ARRAY_SUBTYPES = SQLiteTypes::Array::SUPPORTED_SUBTYPES
+
+    def change_inet_to_string(table_name, column_name, **options)
+      require_postgresql_adapter!
+
+      reversible do |dir|
+        dir.up do
+          change_column table_name, column_name, :string, **options.merge(using: "#{quote_column_name(column_name)}::text")
+        end
+
+        dir.down do
+          change_column table_name, column_name, :inet, **options.merge(using: "#{quote_column_name(column_name)}::inet")
+        end
+      end
+    end
+
+    def change_interval_to_string(table_name, column_name, **options)
+      require_postgresql_adapter!
+
+      reversible do |dir|
+        dir.up do
+          change_column table_name, column_name, :string, **options.merge(using: "#{quote_column_name(column_name)}::text")
+        end
+
+        dir.down do
+          change_column table_name, column_name, :interval, **options.merge(using: "#{quote_column_name(column_name)}::interval")
+        end
+      end
+    end
+
+    def change_array_to_json(
+      table_name,
+      column_name,
+      subtype,
+      nested: false,
+      null: nil,
+      default: [],
+      constraint_name: nil
+    )
+      require_postgresql_adapter!
+
+      subtype = normalize_array_subtype(subtype)
+      constraint_name ||= default_array_constraint_name(table_name, column_name)
+      sqlite_types_array_columns << [table_name, column_name, subtype, nested]
+
+      reversible do |dir|
+        dir.up do
+          options = {}
+          options[:null] = null unless null.nil?
+
+          change_array_default table_name, column_name, from: default, to: nil
+          change_column table_name, column_name, :jsonb, **options.merge(using: "to_jsonb(#{quote_column_name(column_name)})")
+          change_array_default table_name, column_name, from: nil, to: default
+          add_check_constraint table_name, "jsonb_typeof(#{quote_column_name(column_name)}) = 'array'", name: constraint_name
+        end
+
+        dir.down do
+          validate_registered_postgresql_array_rollbacks!
+          remove_check_constraint table_name, name: constraint_name
+          restore_postgresql_array_column table_name, column_name, subtype, nested: nested, null: resolved_null(table_name, column_name, null), default: default
+        end
+      end
+    end
+
+    private
+
+    def require_postgresql_adapter!
+      return if connection.adapter_name.downcase.include?("postgresql")
+
+      raise ActiveRecord::MigrationError,
+        "SQLiteTypes migration helpers must run on PostgreSQL before migrating data to SQLite"
+    end
+
+    def normalize_array_subtype(subtype)
+      subtype = subtype.to_sym if subtype.respond_to?(:to_sym)
+      raise ArgumentError, "Unsupported array subtype: #{subtype}" unless SUPPORTED_ARRAY_SUBTYPES.include?(subtype)
+
+      subtype
+    end
+
+    def change_array_default(table_name, column_name, from:, to:)
+      return if from.equal?(DEFAULT_NOT_PROVIDED) || to.equal?(DEFAULT_NOT_PROVIDED)
+      return if from == to
+
+      change_column_default table_name, column_name, from: from, to: to
+    end
+
+    def restore_postgresql_array_column(table_name, column_name, subtype, nested:, null:, default:)
+      temporary_column_name = temporary_array_column_name(column_name)
+
+      add_column table_name, temporary_column_name, postgresql_array_subtype(subtype), **postgresql_array_column_options(null: null, default: default)
+      execute "UPDATE #{quote_table_name(table_name)} SET #{quote_column_name(temporary_column_name)} = #{postgresql_array_restore_expression(quote_column_name(column_name), subtype, nested)};"
+      remove_column table_name, column_name
+      rename_column table_name, temporary_column_name, column_name
+    end
+
+    def postgresql_array_restore_expression(column_sql, subtype, nested)
+      "CASE WHEN #{column_sql} IS NULL THEN NULL ELSE COALESCE((#{postgresql_array_expression(column_sql, subtype, nested)}), '{}') END"
+    end
+
+    def postgresql_array_subtype(subtype)
+      case subtype
+      when :hash
+        :jsonb
+      else
+        subtype
+      end
+    end
+
+    def postgresql_array_expression(column_sql, subtype, nested)
+      if nested
+        inner_expression = postgresql_array_expression("sqlite_types_outer.value", subtype, false)
+        return "SELECT array_agg((#{inner_expression}) ORDER BY sqlite_types_outer.ordinality) FROM jsonb_array_elements(#{column_sql}) WITH ORDINALITY AS sqlite_types_outer(value, ordinality)"
+      end
+
+      case subtype
+      when :string, :text
+        "SELECT array_agg(sqlite_types_element.value ORDER BY sqlite_types_element.ordinality) FROM jsonb_array_elements_text(#{column_sql}) WITH ORDINALITY AS sqlite_types_element(value, ordinality)"
+      when :integer
+        "SELECT array_agg(sqlite_types_element.value::int ORDER BY sqlite_types_element.ordinality) FROM jsonb_array_elements_text(#{column_sql}) WITH ORDINALITY AS sqlite_types_element(value, ordinality)"
+      when :datetime
+        "SELECT array_agg(sqlite_types_element.value::timestamp ORDER BY sqlite_types_element.ordinality) FROM jsonb_array_elements_text(#{column_sql}) WITH ORDINALITY AS sqlite_types_element(value, ordinality)"
+      when :json
+        "SELECT array_agg(CASE WHEN jsonb_typeof(sqlite_types_element.value) = 'null' THEN NULL ELSE sqlite_types_element.value::json END ORDER BY sqlite_types_element.ordinality) FROM jsonb_array_elements(#{column_sql}) WITH ORDINALITY AS sqlite_types_element(value, ordinality)"
+      when :hash, :jsonb
+        "SELECT array_agg(CASE WHEN jsonb_typeof(sqlite_types_element.value) = 'null' THEN NULL ELSE sqlite_types_element.value END ORDER BY sqlite_types_element.ordinality) FROM jsonb_array_elements(#{column_sql}) WITH ORDINALITY AS sqlite_types_element(value, ordinality)"
+      else
+        raise ArgumentError, "Unsupported array subtype: #{subtype}"
+      end
+    end
+
+    def validate_postgresql_nested_array_shape!(table_name, column_name)
+      column_sql = "sqlite_types_row.#{quote_column_name(column_name)}"
+      invalid_row = select_value "SELECT 1 FROM #{quote_table_name(table_name)} AS sqlite_types_row WHERE #{column_sql} IS NOT NULL AND (jsonb_typeof(#{column_sql}) <> 'array' OR EXISTS (SELECT 1 FROM jsonb_array_elements(#{column_sql}) AS sqlite_types_outer(value) WHERE CASE WHEN jsonb_typeof(sqlite_types_outer.value) <> 'array' THEN true ELSE jsonb_array_length(sqlite_types_outer.value) = 0 END) OR (SELECT COUNT(DISTINCT jsonb_array_length(sqlite_types_outer.value)) FROM jsonb_array_elements(#{column_sql}) AS sqlite_types_outer(value) WHERE jsonb_typeof(sqlite_types_outer.value) = 'array') > 1) LIMIT 1"
+
+      return unless invalid_row
+
+      raise ActiveRecord::IrreversibleMigration,
+        "Cannot restore #{table_name}.#{column_name} to a PostgreSQL multidimensional array; nested JSON arrays must be rectangular and inner arrays must be non-empty"
+    end
+
+    def validate_postgresql_array_elements!(table_name, column_name, subtype, nested:)
+      column_sql = "sqlite_types_row.#{quote_column_name(column_name)}"
+      invalid_condition = postgresql_invalid_array_element_condition("sqlite_types_element.value", subtype)
+      invalid_row = if nested
+        select_value "SELECT 1 FROM #{quote_table_name(table_name)} AS sqlite_types_row WHERE #{column_sql} IS NOT NULL AND EXISTS (SELECT 1 FROM jsonb_array_elements(#{column_sql}) AS sqlite_types_outer(value) WHERE jsonb_typeof(sqlite_types_outer.value) = 'array' AND EXISTS (SELECT 1 FROM jsonb_array_elements(sqlite_types_outer.value) AS sqlite_types_element(value) WHERE #{invalid_condition})) LIMIT 1"
+      else
+        select_value "SELECT 1 FROM #{quote_table_name(table_name)} AS sqlite_types_row WHERE #{column_sql} IS NOT NULL AND EXISTS (SELECT 1 FROM jsonb_array_elements(#{column_sql}) AS sqlite_types_element(value) WHERE #{invalid_condition}) LIMIT 1"
+      end
+
+      return unless invalid_row
+
+      raise ActiveRecord::IrreversibleMigration,
+        "Cannot restore #{table_name}.#{column_name} to a PostgreSQL #{subtype} array; JSON elements are not compatible with the target array subtype"
+    end
+
+    def postgresql_invalid_array_element_condition(element_sql, subtype)
+      type_sql = "jsonb_typeof(#{element_sql})"
+
+      case subtype
+      when :string, :text
+        "false"
+      when :datetime
+        "#{type_sql} NOT IN ('string', 'null')"
+      when :integer
+        "CASE WHEN #{type_sql} = 'null' THEN false WHEN #{type_sql} IN ('number', 'string') THEN (#{element_sql} #>> '{}') !~ '^[+-]?[0-9]+$' ELSE true END"
+      when :hash, :json, :jsonb
+        "false"
+      else
+        raise ArgumentError, "Unsupported array subtype: #{subtype}"
+      end
+    end
+
+    def validate_registered_postgresql_array_rollbacks!
+      return if @sqlite_types_array_rollbacks_validated
+
+      lock_registered_postgresql_array_tables!
+
+      sqlite_types_array_columns.each do |table_name, column_name, subtype, nested|
+        validate_postgresql_array_shape!(table_name, column_name, subtype)
+        validate_postgresql_nested_array_shape!(table_name, column_name) if nested
+        validate_postgresql_array_elements!(table_name, column_name, subtype, nested: nested)
+        validate_postgresql_array_restore_cast!(table_name, column_name, subtype, nested: nested)
+      end
+
+      @sqlite_types_array_rollbacks_validated = true
+    end
+
+    def lock_registered_postgresql_array_tables!
+      return if connection.respond_to?(:transaction_open?) && !connection.transaction_open?
+
+      sqlite_types_array_columns.map(&:first).uniq.each do |table_name|
+        execute "LOCK TABLE #{quote_table_name(table_name)} IN SHARE ROW EXCLUSIVE MODE"
+      end
+    end
+
+    def validate_postgresql_array_shape!(table_name, column_name, subtype)
+      column_sql = "sqlite_types_row.#{quote_column_name(column_name)}"
+      invalid_row = select_value "SELECT 1 FROM #{quote_table_name(table_name)} AS sqlite_types_row WHERE #{column_sql} IS NOT NULL AND jsonb_typeof(#{column_sql}) <> 'array' LIMIT 1"
+
+      return unless invalid_row
+
+      raise ActiveRecord::IrreversibleMigration,
+        "Cannot restore #{table_name}.#{column_name} to a PostgreSQL #{subtype} array; JSON value is not an array"
+    end
+
+    def validate_postgresql_array_restore_cast!(table_name, column_name, subtype, nested:)
+      column_sql = "sqlite_types_row.#{quote_column_name(column_name)}"
+      select_value "SELECT COUNT(*) FROM #{quote_table_name(table_name)} AS sqlite_types_row WHERE #{column_sql} IS NOT NULL AND (#{postgresql_array_restore_expression(column_sql, subtype, nested)}) IS NOT NULL"
+    rescue ActiveRecord::StatementInvalid => error
+      raise ActiveRecord::IrreversibleMigration,
+        "Cannot restore #{table_name}.#{column_name} to a PostgreSQL #{subtype} array; PostgreSQL rejected the rollback cast: #{error.message.lines.first&.strip}"
+    end
+
+    def sqlite_types_array_columns
+      @sqlite_types_array_columns ||= []
+    end
+
+    def postgresql_array_column_options(null:, default:)
+      options = {array: true}
+      options[:null] = null unless null.nil?
+      return options if default.equal?(DEFAULT_NOT_PROVIDED)
+
+      options.merge(default: default)
+    end
+
+    def resolved_null(table_name, column_name, null)
+      return null unless null.nil?
+      return unless connection.respond_to?(:columns)
+
+      connection.columns(table_name).find { |column| column.name == column_name.to_s }&.null
+    end
+
+    def default_array_constraint_name(table_name, column_name)
+      truncate_identifier("#{table_name}_#{column_name}_array_check")
+    end
+
+    def temporary_array_column_name(column_name)
+      truncate_identifier("#{column_name}_sqlite_types_tmp")
+    end
+
+    def truncate_identifier(identifier)
+      identifier = identifier.to_s
+      return identifier if identifier.length <= POSTGRESQL_IDENTIFIER_LIMIT
+
+      digest = Digest::SHA256.hexdigest(identifier)[0, 10]
+      "#{identifier[0, POSTGRESQL_IDENTIFIER_LIMIT - digest.length - 1]}_#{digest}"
+    end
+  end
+end

data/lib/sqlite_types/version.rb

@@ -1,3 +1,3 @@
 module SQLiteTypes
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/sqlite_types.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "activerecord-sqlite-types"

data/sig/sqlite_types.rbs

@@ -1,4 +1,32 @@
 module SQLiteTypes
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class IpAddress < ActiveRecord::Type::String
+    def serialize: (untyped value) -> String?
+    def changed?: (untyped old_value, untyped new_value, untyped new_value_before_type_cast) -> bool
+    def changed_in_place?: (untyped raw_old_value, untyped new_value) -> bool
+  end
+
+  class Array < ActiveRecord::Type::Json
+    SUPPORTED_SUBTYPES: ::Array[Symbol]
+
+    def initialize: ((Symbol | String) subtype, ?nested: bool) -> void
+    def deserialize: (untyped value) -> ::Array[untyped]?
+    def serialize: (untyped value) -> untyped
+    def force_equality?: (untyped value) -> bool
+  end
+
+  class Interval < ActiveRecord::Type::Value
+    def serialize: (untyped value) -> untyped
+    def type_cast_for_schema: (untyped value) -> String
+  end
+
+  module MigrationHelpers
+    DEFAULT_NOT_PROVIDED: untyped
+    SUPPORTED_ARRAY_SUBTYPES: ::Array[Symbol]
+
+    def change_inet_to_string: ((Symbol | String) table_name, (Symbol | String) column_name, **untyped options) -> untyped
+    def change_interval_to_string: ((Symbol | String) table_name, (Symbol | String) column_name, **untyped options) -> untyped
+    def change_array_to_json: ((Symbol | String) table_name, (Symbol | String) column_name, (Symbol | String) subtype, ?nested: bool, ?null: bool, ?default: untyped, ?constraint_name: String?) -> untyped
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-sqlite-types
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Wojtek Wrona
@@ -38,6 +38,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
 description: Provides custom ActiveRecord types to handle PostgreSQL-specific data
   types (inet, interval, arrays) when migrating to SQLite in Rails applications.
 email:
@@ -46,19 +74,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".envrc"
-- ".standard.yml"
+- ".mutant.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- devenv.lock
-- devenv.nix
-- devenv.yaml
 - lib/activerecord-sqlite-types.rb
+- lib/generators/sqlite_types/migration/migration_generator.rb
+- lib/generators/sqlite_types/migration/templates/migration.rb.tt
+- lib/sqlite_types.rb
 - lib/sqlite_types/array.rb
 - lib/sqlite_types/interval.rb
 - lib/sqlite_types/ip_address.rb
+- lib/sqlite_types/migration_helpers.rb
 - lib/sqlite_types/version.rb
 - sig/sqlite_types.rbs
 homepage: https://github.com/wojtodzio/activerecord-sqlite-types

data/.envrc

@@ -1,5 +0,0 @@
-export DIRENV_WARN_TIMEOUT=20s
-
-eval "$(devenv direnvrc)"
-
-use devenv

data/.standard.yml

@@ -1,3 +0,0 @@
-# For available configuration options, see:
-#   https://github.com/standardrb/standard
-ruby_version: 3.1

data/Rakefile

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "minitest/test_task"
-
-Minitest::TestTask.create
-
-require "standard/rake"
-
-task default: %i[test standard]

data/devenv.lock

@@ -1,171 +0,0 @@
-{
-  "nodes": {
-    "devenv": {
-      "locked": {
-        "dir": "src/modules",
-        "lastModified": 1761156818,
-        "owner": "cachix",
-        "repo": "devenv",
-        "rev": "949fc6dc8f36f38e1cceb1bf1673c4e995a6a766",
-        "type": "github"
-      },
-      "original": {
-        "dir": "src/modules",
-        "owner": "cachix",
-        "repo": "devenv",
-        "type": "github"
-      }
-    },
-    "flake-compat": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1747046372,
-        "owner": "edolstra",
-        "repo": "flake-compat",
-        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
-        "type": "github"
-      },
-      "original": {
-        "owner": "edolstra",
-        "repo": "flake-compat",
-        "type": "github"
-      }
-    },
-    "flake-compat_2": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1747046372,
-        "owner": "edolstra",
-        "repo": "flake-compat",
-        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
-        "type": "github"
-      },
-      "original": {
-        "owner": "edolstra",
-        "repo": "flake-compat",
-        "type": "github"
-      }
-    },
-    "flake-utils": {
-      "inputs": {
-        "systems": "systems"
-      },
-      "locked": {
-        "lastModified": 1731533236,
-        "owner": "numtide",
-        "repo": "flake-utils",
-        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
-        "type": "github"
-      },
-      "original": {
-        "owner": "numtide",
-        "repo": "flake-utils",
-        "type": "github"
-      }
-    },
-    "git-hooks": {
-      "inputs": {
-        "flake-compat": "flake-compat",
-        "gitignore": "gitignore",
-        "nixpkgs": [
-          "nixpkgs"
-        ]
-      },
-      "locked": {
-        "lastModified": 1760663237,
-        "owner": "cachix",
-        "repo": "git-hooks.nix",
-        "rev": "ca5b894d3e3e151ffc1db040b6ce4dcc75d31c37",
-        "type": "github"
-      },
-      "original": {
-        "owner": "cachix",
-        "repo": "git-hooks.nix",
-        "type": "github"
-      }
-    },
-    "gitignore": {
-      "inputs": {
-        "nixpkgs": [
-          "git-hooks",
-          "nixpkgs"
-        ]
-      },
-      "locked": {
-        "lastModified": 1709087332,
-        "owner": "hercules-ci",
-        "repo": "gitignore.nix",
-        "rev": "637db329424fd7e46cf4185293b9cc8c88c95394",
-        "type": "github"
-      },
-      "original": {
-        "owner": "hercules-ci",
-        "repo": "gitignore.nix",
-        "type": "github"
-      }
-    },
-    "nixpkgs": {
-      "locked": {
-        "lastModified": 1758532697,
-        "owner": "cachix",
-        "repo": "devenv-nixpkgs",
-        "rev": "207a4cb0e1253c7658c6736becc6eb9cace1f25f",
-        "type": "github"
-      },
-      "original": {
-        "owner": "cachix",
-        "ref": "rolling",
-        "repo": "devenv-nixpkgs",
-        "type": "github"
-      }
-    },
-    "nixpkgs-ruby": {
-      "inputs": {
-        "flake-compat": "flake-compat_2",
-        "flake-utils": "flake-utils",
-        "nixpkgs": [
-          "nixpkgs"
-        ]
-      },
-      "locked": {
-        "lastModified": 1759902829,
-        "owner": "bobvanderlinden",
-        "repo": "nixpkgs-ruby",
-        "rev": "5fba6c022a63f1e76dee4da71edddad8959f088a",
-        "type": "github"
-      },
-      "original": {
-        "owner": "bobvanderlinden",
-        "repo": "nixpkgs-ruby",
-        "type": "github"
-      }
-    },
-    "root": {
-      "inputs": {
-        "devenv": "devenv",
-        "git-hooks": "git-hooks",
-        "nixpkgs": "nixpkgs",
-        "nixpkgs-ruby": "nixpkgs-ruby",
-        "pre-commit-hooks": [
-          "git-hooks"
-        ]
-      }
-    },
-    "systems": {
-      "locked": {
-        "lastModified": 1681028828,
-        "owner": "nix-systems",
-        "repo": "default",
-        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
-        "type": "github"
-      },
-      "original": {
-        "owner": "nix-systems",
-        "repo": "default",
-        "type": "github"
-      }
-    }
-  },
-  "root": "root",
-  "version": 7
-}

data/devenv.nix

@@ -1,14 +0,0 @@
-{ pkgs, ... }:
-
-{
-  languages = {
-    ruby = {
-      version = "3.1";
-      enable = true;
-    };
-  };
-
-  packages = with pkgs; [
-    (sqlite.override { interactive = true; })
-  ];
-}

data/devenv.yaml

@@ -1,8 +0,0 @@
-inputs:
-  nixpkgs:
-    url: github:cachix/devenv-nixpkgs/rolling
-  nixpkgs-ruby:
-    url: github:bobvanderlinden/nixpkgs-ruby
-    inputs:
-      nixpkgs:
-        follows: nixpkgs