active_record_pgnats 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d170a81eb308b003ad5a6c3eed99da1101d584bf46249cf66a458c6057a8641
+  data.tar.gz: e16809da5ed462c0af895d6fcc1fba5215f1ff0f8947646290c47ca24ff321bc
+SHA512:
+  metadata.gz: '009a011ba3566c2a05af7f10a6494eebc3f3213cb55d1dba0beb75129d154b6c08bef87c3f9cfbf092db92ef672581d19704cc0cbe351d92cca4a87311e07c8e'
+  data.tar.gz: b37d38071d69ff6dbd8dac221e74b301b86edccdf30bf422f5b0ec231d06fdd203368321d590bed3ba3e5a53bf6ac7452b86a229a8b5d2605a9d5adbb71f3d3a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan K
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,201 @@
+# active_record_pgnats
+
+Active Record migrations for [pgnats](https://github.com/luxms/pgnats), the
+Postgres extension that publishes to and subscribes from NATS.
+
+Modelled on [F(x)](https://github.com/teoljungberg/fx) and
+[pg_cron-rails](https://github.com/n-at-han-k/pg_cron-rails): migration
+statements, reversibility through the command recorder, and a schema dumper so
+`schema.rb` carries what the extension holds.
+
+Two gems in this repository, sharing one `lib/` tree:
+
+| gem | what it is |
+|---|---|
+| `active_record_pgnats` | the statements, the adapter and the dumper. Active Record only — no `railties`, no `Rails.root`, no railtie |
+| `active_record_pgnats-rails` | a railtie installing the hooks at the `on_load :active_record` moment, and generators for the migrations |
+
+```ruby
+# Gemfile -- Active Record on its own
+gem "active_record_pgnats"
+```
+
+```ruby
+require "active_record_pgnats"   # installs the statements, recorder and dumper
+```
+
+```ruby
+# Gemfile -- Rails
+gem "active_record_pgnats-rails"
+```
+
+Under Rails the core defers: requiring it does nothing until the railtie runs
+the install, because Active Record may not be loaded when the bundle is. Use the
+`-rails` gem there rather than the core on its own.
+
+```sh
+rails generate active_record_pgnats:server nats --host=127.0.0.1 --port=4222
+rails generate active_record_pgnats:subscription events.user.created handle_user_created
+rails generate active_record_pgnats:publish_trigger maps_devices --subject="devices.%s.%s"
+```
+
+pgnats itself has to be loaded by the server (`shared_preload_libraries =
+'pgnats'`) and enabled in the database. That part is Active Record's own:
+
+```ruby
+enable_extension "pgnats"
+```
+
+Every statement below is a no-op when the extension is not installed, so a
+migration still runs against a database without pgnats instead of needing its
+own guard.
+
+## The server
+
+pgnats keeps its entire configuration on a foreign server, and allows exactly
+one per database — its own event trigger raises on a second.
+
+```ruby
+class ConfigureNats < ActiveRecord::Migration[7.2]
+  def change
+    create_nats_server :nats, host: "127.0.0.1", port: 4222
+  end
+end
+```
+
+Options: `host`, `port`, `capacity`, `tls_ca_path`, `tls_cert_path`,
+`tls_key_path`, `notify_subject`, `patroni_url`. Anything else raises — the
+wrapper's validator accepts a typo that pgnats then ignores, which is a bad way
+to find out. Values are cast to text, because every FDW option is text.
+
+Changing them is declarative: the hash is the desired state, and an option left
+out is dropped.
+
+```ruby
+update_nats_server :nats,
+  host: "127.0.0.1", capacity: 256,
+  revert_to: {host: "127.0.0.1"}
+```
+
+The adapter diffs against the catalog to pick `SET` or `ADD` per option, since
+`ALTER SERVER` rejects the wrong one, and follows every change with
+`pgnats_reload_conf()` so the running background worker picks it up instead of
+waiting for its next connect.
+
+`revert_to:` is what makes `update_nats_server` and `drop_nats_server`
+reversible. Without it a rollback raises `IrreversibleMigration` rather than
+leaving the database unconfigured.
+
+## Subscriptions
+
+```ruby
+create_nats_subscription "events.user.created", function: "handle_user_created"
+```
+
+The function has to exist already and must take a single `bytea` — the message
+payload. Create it in an earlier migration; F(x) coexists with this gem and is
+the obvious way. A subscription needs no `revert_to`: the subject and the
+function are the whole of it.
+
+Note what this buys you: a core NATS subscription, so no replay and no acks.
+Messages published while the database is down are gone.
+
+## Publishing row changes
+
+```ruby
+create_nats_publish_trigger :maps_devices, subject: "pg_changes.%s.%s"
+```
+
+Writes a trigger function and an `AFTER INSERT OR UPDATE OR DELETE` trigger,
+both named `nats_publish_<table>`. `subject` is a format string given the table
+name and the lowercased operation, so one definition covers all three. The
+payload is `{table, op, at, row}`, with `row` the new tuple (the old one on a
+delete).
+
+The publish is wrapped in its own `BEGIN … EXCEPTION WHEN OTHERS THEN NULL`, so
+a NATS problem can never roll back the write that fired the trigger. Put another
+way: this is best-effort, and pgnats' JetStream publish does not wait for an
+ack, so a subject no stream covers is dropped silently. Create the stream first.
+
+`drop_nats_publish_trigger :maps_devices, revert_to_subject: "pg_changes.%s.%s"`
+to go the other way.
+
+## schema.rb
+
+The dumper appends the server and its subscriptions after the tables:
+
+```ruby
+  create_nats_server :nats, host: "127.0.0.1", port: "4222"
+
+  create_nats_subscription "events.user.created", function: "handle_user_created"
+```
+
+It hooks `#tables` rather than `#extensions`, which is F(x)'s choice and is
+load-bearing: `#extensions` is private and is redefined by the PostgreSQL
+dumper, so a prepended module never intercepts it and the section silently never
+appears.
+
+Publish triggers are **not** dumped here. Once created they are an ordinary
+function and trigger, which F(x) dumps as `create_function` / `create_trigger`
+and `structure.sql` carries anyway; emitting them twice would make a schema load
+fail.
+
+## Using another connection
+
+```ruby
+ActiveRecordPgnats.configure do |config|
+  config.adapter = ActiveRecordPgnats::Adapters::Postgres.new(SomeOtherModel)
+end
+```
+
+It defaults to `ActiveRecord::Base`, which is almost always right: the foreign
+server and `pgnats.subscriptions` live in the application's own database.
+
+## Alongside F(x)
+
+Safe to load together. Every helper here, private ones included, is prefixed
+`nats_` / `_nats_` on purpose — both modules are included into
+`ActiveRecord::ConnectionAdapters::AbstractAdapter`, and a shared private name
+shadows F(x)'s copy for every migration in the application. pg_cron-rails
+learned this the hard way: its `resolve_sql_definition` took one argument fewer
+than F(x)'s, so every `create_function` in the host app died with
+`ArgumentError: wrong number of arguments (given 4, expected 3)`.
+
+## Development
+
+```bash
+nix develop   # or direnv allow
+bin/setup     # install dependencies
+bin/test      # run the tests
+bin/console   # interactive prompt
+```
+
+```sh
+bin/test                                                  # no database needed
+DATABASE_URL=postgres:///my_db bin/test test/integration   # against real pgnats
+```
+
+The unit suite runs against a fake adapter. The integration spec skips itself
+unless `DATABASE_URL` is set and pgnats is installed there.
+
+One Gemfile covers the whole repository. Neither of its own gems is in the
+bundle — the devshell puts `lib/` on `RUBYLIB` — so no lockfile records a
+version and a bump has nothing to keep in step. After touching the Gemfile,
+`nix develop --command bundix -l`.
+
+Each gem carries its own version, changelog (`CHANGELOG-<gem>.md`) and tag
+(`<gem>-v1.2.3`), and is released on its own schedule with
+[gem_kit-release](https://github.com/n-at-han-k/gem_kit):
+
+```bash
+gem kit bump patch --gem active_record_pgnats-rails
+gem kit changelog --write --gem active_record_pgnats-rails
+gem kit release --gem active_record_pgnats-rails
+```
+
+`active_record_pgnats-rails` derives its dependency on the core from the core's
+own version, so a bump there does not have to be written out twice.
+
+## License
+
+[MIT](LICENSE)

data/lib/active_record_pgnats/adapters/postgres/connection.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module ActiveRecordPgnats
+  module Adapters
+    class Postgres
+      # Answers whether pgnats is installed in this database.
+      #
+      # @api private
+      class Connection < SimpleDelegator
+        # Whether the extension is there to be used.
+        #
+        # @returns [Boolean] false until CREATE EXTENSION has run, which additionally needs pgnats in shared_preload_libraries and a restart. Every caller checks first, so a migration or a dump against a database without it is a no-op rather than an error.
+        def pgnats_enabled?
+          extension_enabled?("pgnats")
+        end
+      end
+    end
+  end
+end

data/lib/active_record_pgnats/adapters/postgres/query_executor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActiveRecordPgnats
+  module Adapters
+    class Postgres
+      # Runs a query and maps its rows to domain objects.
+      # @api private
+      class QueryExecutor
+        def self.call(...)
+          new(...).call
+        end
+
+        def initialize(connection:, query:, model_class:)
+          @connection = connection
+          @query = query
+          @model_class = model_class
+        end
+
+        def call
+          connection.execute(query).map { |row| model_class.new(row) }
+        end
+
+        private
+
+          attr_reader :connection, :query, :model_class
+      end
+    end
+  end
+end

data/lib/active_record_pgnats/adapters/postgres/servers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "active_record_pgnats/server"
+require "active_record_pgnats/adapters/postgres/query_executor"
+
+module ActiveRecordPgnats
+  module Adapters
+    class Postgres
+      # Fetches pgnats' foreign server from the connection.
+      #
+      # @api private
+      class Servers
+        # Selected by wrapper, not by name: the name is the migration's to choose, and pgnats itself joins pg_foreign_data_wrapper on fdwname to find it.
+        SERVERS_QUERY = <<~SQL.freeze
+          SELECT
+              s.srvname AS name,
+              s.srvoptions AS options
+          FROM pg_foreign_server s
+          JOIN pg_foreign_data_wrapper w
+              ON w.oid = s.srvfdw
+          WHERE w.fdwname = 'pgnats_fdw'
+          ORDER BY s.srvname;
+        SQL
+
+        def self.all(connection)
+          QueryExecutor.call(connection: connection, query: SERVERS_QUERY, model_class: Server)
+        end
+      end
+    end
+  end
+end

data/lib/active_record_pgnats/adapters/postgres/subscriptions.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "active_record_pgnats/subscription"
+require "active_record_pgnats/adapters/postgres/query_executor"
+
+module ActiveRecordPgnats
+  module Adapters
+    class Postgres
+      # Fetches subscriptions from pgnats' own table.
+      #
+      # @api private
+      class Subscriptions
+        # pgnats.subscriptions is the durable state its worker reads on start, so there is no catalog view to read instead.
+        SUBSCRIPTIONS_QUERY = <<~SQL.freeze
+          SELECT subject, callback
+          FROM pgnats.subscriptions
+          ORDER BY subject, callback;
+        SQL
+
+        def self.all(connection)
+          QueryExecutor.call(connection: connection, query: SUBSCRIPTIONS_QUERY, model_class: Subscription)
+        end
+      end
+    end
+  end
+end

data/lib/active_record_pgnats/adapters/postgres.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "active_record_pgnats/adapters/postgres/connection"
+require "active_record_pgnats/adapters/postgres/servers"
+require "active_record_pgnats/adapters/postgres/subscriptions"
+require "active_record_pgnats/publish_trigger"
+
+module ActiveRecordPgnats
+  module Adapters
+    # The Postgres adapter, the only engine pgnats has.
+    class Postgres
+      def initialize(connectable = ActiveRecord::Base)
+        @connectable = connectable
+      end
+
+      def pgnats_enabled?
+        connection.pgnats_enabled?
+      end
+
+      # @return [Array<ActiveRecordPgnats::Server>]
+      def servers
+        if pgnats_enabled?
+          Servers.all(connection)
+        else
+          []
+        end
+      end
+
+      # @return [Array<ActiveRecordPgnats::Subscription>]
+      def subscriptions
+        if pgnats_enabled?
+          Subscriptions.all(connection)
+        else
+          []
+        end
+      end
+
+      def create_server(name, options)
+        execute(<<~SQL)
+          CREATE SERVER #{quote_name(name)} FOREIGN DATA WRAPPER pgnats_fdw
+            OPTIONS (#{options.map { |key, value| "#{key} #{quote(value)}" }.join(", ")});
+        SQL
+
+        reload_conf
+      end
+
+      # Moves the server's options to the given set.
+      #
+      # @parameter name [String | Symbol] the server to alter.
+      # @parameter options [Hash] the desired state, not a patch: anything absent is dropped.
+      # @returns [void]
+      def update_server(name, options)
+        # ALTER SERVER takes SET for an option already present and ADD for one that is not, and rejects the wrong verb, so the current options are read back and diffed.
+        current = server_options(name)
+
+        changes = options.map { |key, value| "#{current.key?(key) ? "SET" : "ADD"} #{key} #{quote(value)}" }
+        changes += (current.keys - options.keys).map { |key| "DROP #{key}" }
+
+        if changes.empty?
+          nil
+        else
+          execute("ALTER SERVER #{quote_name(name)} OPTIONS (#{changes.join(", ")});")
+          reload_conf
+        end
+      end
+
+      def drop_server(name)
+        execute("DROP SERVER #{quote_name(name)};")
+        reload_conf
+      end
+
+      def create_subscription(subject, function)
+        execute("SELECT nats_subscribe(#{quote(subject)}, #{quote(function)}::regproc);")
+      end
+
+      def drop_subscription(subject, function)
+        execute("SELECT nats_unsubscribe(#{quote(subject)}, #{quote(function)}::regproc);")
+      end
+
+      def create_publish_trigger(table, subject)
+        execute(PublishTrigger.sql(table: table, subject: subject))
+      end
+
+      def drop_publish_trigger(table)
+        execute(PublishTrigger.drop_sql(table: table))
+      end
+
+      # Tells the background worker to re-read the options.
+      #
+      # @returns [void] without this the new configuration only takes effect on the next connect.
+      def reload_conf
+        execute("SELECT pgnats_reload_conf();")
+      end
+
+      private
+
+        attr_reader :connectable
+
+        def connection
+          Connection.new(connectable.connection)
+        end
+
+        def execute(sql)
+          connection.execute(sql)
+        end
+
+        def server_options(name)
+          servers.find { |server| server.name == name.to_s }&.options || {}
+        end
+
+        def quote(value)
+          connection.quote(value.to_s)
+        end
+
+        def quote_name(name)
+          connection.quote_table_name(name)
+        end
+    end
+  end
+end

data/lib/active_record_pgnats/command_recorder.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ActiveRecordPgnats
+  # Makes the statements reversible.
+  module CommandRecorder
+    %i[
+      create_nats_server update_nats_server drop_nats_server
+      create_nats_subscription drop_nats_subscription
+      create_nats_publish_trigger drop_nats_publish_trigger
+    ].each do |statement|
+      define_method(statement) do |*args, &block|
+        record(statement, args, &block)
+      end
+      ruby2_keywords statement
+    end
+
+    # Inverts a server creation.
+    #
+    # @parameter args [Array] the recorded arguments.
+    # @returns [Array] the statement to run instead, and its arguments. A subscription inverts on its own, subject plus function being the whole of it; the server does not, its options being the definition, so a migration that drops or rewrites them has to say what to go back to.
+    def invert_create_nats_server(args)
+      [:drop_nats_server, args]
+    end
+
+    def invert_drop_nats_server(args)
+      _nats_invert_server(:create_nats_server, args)
+    end
+
+    def invert_update_nats_server(args)
+      _nats_invert_server(:update_nats_server, args)
+    end
+
+    def invert_create_nats_subscription(args)
+      [:drop_nats_subscription, args]
+    end
+
+    def invert_drop_nats_subscription(args)
+      [:create_nats_subscription, args]
+    end
+
+    def invert_create_nats_publish_trigger(args)
+      [:drop_nats_publish_trigger, [args.first]]
+    end
+
+    def invert_drop_nats_publish_trigger(args)
+      name, options = args
+      subject = (options || {})[:revert_to_subject]
+
+      unless subject
+        raise ActiveRecord::IrreversibleMigration,
+          "`drop_nats_publish_trigger` is reversible only if given a `revert_to_subject`"
+      end
+
+      [:create_nats_publish_trigger, [name, Hash.ruby2_keywords_hash({subject: subject})]]
+    end
+
+    private
+
+      def _nats_invert_server(method, args)
+        name, options = args
+        revert_to = (options || {})[:revert_to]
+
+        unless revert_to
+          raise ActiveRecord::IrreversibleMigration,
+            "`#{method}` is reversible only if given a `revert_to`"
+        end
+
+        [method, [name, Hash.ruby2_keywords_hash(revert_to.to_h)]]
+      end
+  end
+end

data/lib/active_record_pgnats/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActiveRecordPgnats
+  class Configuration
+    # The adapter statements run through. Defaults to the Postgres adapter over ActiveRecord::Base's own connection: pgnats' foreign server and its subscriptions table live in the application's database, so that is the connection that can see them.
+    attr_accessor :adapter
+
+    def initialize(adapter: Adapters::Postgres.new)
+      @adapter = adapter
+    end
+  end
+end

data/lib/active_record_pgnats/publish_trigger.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ActiveRecordPgnats
+  # Builds the SQL for a publishing trigger.
+  #
+  # @api private
+  module PublishTrigger
+    module_function
+
+    def name_for(table)
+      "nats_publish_#{table}"
+    end
+
+    def sql(table:, subject:, name: nil)
+      name ||= name_for(table)
+
+      <<~SQL
+        CREATE OR REPLACE FUNCTION #{name}() RETURNS trigger
+        LANGUAGE plpgsql AS $pgnats$
+        DECLARE
+          payload jsonb;
+        BEGIN
+          IF TG_OP = 'DELETE' THEN
+            payload := to_jsonb(OLD);
+          ELSE
+            payload := to_jsonb(NEW);
+          END IF;
+
+          -- A NATS problem must never roll back the write that fired the trigger.
+          BEGIN
+            PERFORM nats_publish_json_stream(
+              format(#{quote(subject)}, TG_TABLE_NAME, lower(TG_OP)),
+              json_build_object('table', TG_TABLE_NAME, 'op', TG_OP, 'at', now(), 'row', payload)
+            );
+          EXCEPTION WHEN OTHERS THEN
+            NULL;
+          END;
+
+          RETURN NULL;
+        END
+        $pgnats$;
+
+        DROP TRIGGER IF EXISTS #{name} ON #{table};
+
+        CREATE TRIGGER #{name}
+          AFTER INSERT OR UPDATE OR DELETE ON #{table}
+          FOR EACH ROW EXECUTE FUNCTION #{name}();
+      SQL
+    end
+
+    def drop_sql(table:, name: nil)
+      name ||= name_for(table)
+
+      <<~SQL
+        DROP TRIGGER IF EXISTS #{name} ON #{table};
+        DROP FUNCTION IF EXISTS #{name}();
+      SQL
+    end
+
+    def quote(value)
+      "'#{value.to_s.gsub("'", "''")}'"
+    end
+  end
+end

data/lib/active_record_pgnats/schema_dumper.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActiveRecordPgnats
+  # Writes the server and its subscriptions into schema.rb.
+  #
+  # @api private
+  module SchemaDumper
+    # Appends the pgnats section to the schema.
+    #
+    # @parameter stream [IO] the schema being written.
+    # @returns [void] #tables is the hook, as it is in F(x) and for the same reason: #extensions is private and is redefined by the PostgreSQL-specific dumper, so a prepended module never intercepts it and the dump comes out silently missing its pgnats section.
+    def tables(stream)
+      # After super, because a subscription names a function that a statement above it creates.
+      super
+
+      nats_servers(stream)
+      nats_subscriptions(stream)
+    end
+
+    private
+
+      def nats_servers(stream)
+        ActiveRecordPgnats.database.servers.each do |server|
+          stream.puts
+          stream.puts(server.to_schema)
+        end
+      end
+
+      def nats_subscriptions(stream)
+        ActiveRecordPgnats.database.subscriptions.each do |subscription|
+          stream.puts
+          stream.puts(subscription.to_schema)
+        end
+      end
+  end
+end

data/lib/active_record_pgnats/server.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ActiveRecordPgnats
+  # pgnats' foreign server, as pg_foreign_server holds it.
+  #
+  # @api private
+  class Server
+    include Comparable
+
+    attr_reader :name, :options
+
+    def initialize(row)
+      @name = row.fetch("name")
+      @options = self.class.parse_options(row.fetch("options"))
+    end
+
+    # Parses srvoptions into a hash.
+    #
+    # @parameter value [Array | String] a Postgres text[] of "key=value" items, which the pg adapter hands over either as an Array or as the raw "{a=b,c=d}" literal.
+    # @returns [Hash] option name => value.
+    def self.parse_options(value)
+      if value.is_a?(Array)
+        items = value
+      else
+        items = value.to_s.delete_prefix("{").delete_suffix("}").split(",")
+      end
+
+      items.to_h do |item|
+        key, _, rest = item.to_s.partition("=")
+        [key, rest]
+      end
+    end
+
+    def <=>(other)
+      name <=> other.name
+    end
+
+    def ==(other)
+      name == other.name && options == other.options
+    end
+
+    def to_schema
+      <<~SCHEMA.then { |schema| schema.gsub(/^(?=.)/, "  ") }
+        create_nats_server :#{name}, #{options.map { |key, value| "#{key}: #{value.inspect}" }.join(", ")}
+      SCHEMA
+    end
+  end
+end

data/lib/active_record_pgnats/statements.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module ActiveRecordPgnats
+  # The migration DSL for pgnats.
+  module Statements
+    # The options pgnats reads off its foreign server.
+    SERVER_OPTIONS = %i[
+      host port capacity tls_ca_path tls_cert_path tls_key_path notify_subject patroni_url
+    ].freeze
+
+    # Creates pgnats' foreign server, its whole configuration.
+    #
+    # @example
+    #   create_nats_server :nats, host: "127.0.0.1", port: 4222
+    #
+    # @parameter name [String | Symbol] the server's name, the migration's to choose.
+    # @parameter revert_to [Hash] unused here; the command recorder reads it when inverting.
+    # @parameter options [Hash] any of {SERVER_OPTIONS}.
+    # @returns [void] nothing happens at all when pgnats is not installed in this database.
+    def create_nats_server(name, revert_to: nil, **options)
+      # pgnats permits exactly one server on the pgnats_fdw wrapper per database -- its own event trigger raises on a second -- so later changes go through #update_nats_server.
+      if ActiveRecordPgnats.database.pgnats_enabled?
+        ActiveRecordPgnats.database.create_server(name, _nats_validated_options(options))
+      end
+    end
+
+    # Changes the server's options to exactly those given.
+    #
+    # @parameter name [String | Symbol] the server to alter.
+    # @parameter revert_to [Hash] the options to restore on rollback; without it the migration is irreversible.
+    # @parameter options [Hash] the options the server should end up with. Declarative, not additive: anything left out is dropped.
+    # @returns [void]
+    def update_nats_server(name, revert_to: nil, **options)
+      if ActiveRecordPgnats.database.pgnats_enabled?
+        ActiveRecordPgnats.database.update_server(name, _nats_validated_options(options))
+      end
+    end
+
+    # Drops the server, leaving pgnats unconfigured.
+    #
+    # @parameter name [String | Symbol] the server to drop.
+    # @parameter revert_to [Hash] the options to recreate it with on rollback; without it the migration is irreversible.
+    # @returns [void]
+    def drop_nats_server(name, revert_to: nil)
+      if ActiveRecordPgnats.database.pgnats_enabled?
+        ActiveRecordPgnats.database.drop_server(name)
+      end
+    end
+
+    # Subscribes a Postgres function to a NATS subject.
+    #
+    # @example
+    #   create_nats_subscription "events.user.created", function: "handle_user_created"
+    #
+    # @parameter subject [String] the NATS subject to subscribe to.
+    # @parameter function [String | Symbol] the function the background worker calls. It must exist already and take a single bytea, the message payload.
+    # @returns [void]
+    def create_nats_subscription(subject, function:)
+      # nats_subscribe resolves the name to an OID, so create the function in an earlier migration -- F(x) is the obvious way -- or this fails.
+      if ActiveRecordPgnats.database.pgnats_enabled?
+        ActiveRecordPgnats.database.create_subscription(subject, function)
+      end
+    end
+
+    # Unsubscribes the function from the subject.
+    #
+    # @parameter subject [String] the subject it was subscribed to.
+    # @parameter function [String | Symbol] the function to stop calling.
+    # @returns [void]
+    def drop_nats_subscription(subject, function:)
+      if ActiveRecordPgnats.database.pgnats_enabled?
+        ActiveRecordPgnats.database.drop_subscription(subject, function)
+      end
+    end
+
+    # Publishes every row change on a table.
+    #
+    # @example
+    #   create_nats_publish_trigger :maps_devices, subject: "pg_changes.%s.%s"
+    #
+    # @parameter table [String | Symbol] the table to watch.
+    # @parameter subject [String] a format string given the table name and the lowercased operation, so one definition covers insert, update and delete.
+    # @parameter revert_to_subject [String] unused here; the command recorder reads it when inverting a drop.
+    # @returns [void]
+    def create_nats_publish_trigger(table, subject:, revert_to_subject: nil)
+      # The function and the trigger are ordinary ones once created, so the schema dumper leaves them alone: F(x) dumps them, and structure.sql carries them either way.
+      if ActiveRecordPgnats.database.pgnats_enabled?
+        ActiveRecordPgnats.database.create_publish_trigger(table, subject)
+      end
+    end
+
+    # Drops the publish trigger and its function.
+    #
+    # @parameter table [String | Symbol] the table it watches.
+    # @parameter revert_to_subject [String] the subject to recreate it with on rollback; without it the migration is irreversible.
+    # @returns [void]
+    def drop_nats_publish_trigger(table, revert_to_subject: nil)
+      if ActiveRecordPgnats.database.pgnats_enabled?
+        ActiveRecordPgnats.database.drop_publish_trigger(table)
+      end
+    end
+
+    private
+
+      # Rejects unknown options and stringifies the rest.
+      #
+      # @parameter options [Hash] the options as the migration wrote them.
+      # @returns [Hash] the same options with keys and values as strings, because every FDW option is text.
+      # @raises [ArgumentError] when an option is not one pgnats reads: the wrapper's validator accepts a typo that pgnats then ignores.
+      def _nats_validated_options(options)
+        unknown = options.keys.map(&:to_sym) - SERVER_OPTIONS
+
+        unless unknown.empty?
+          message = "unknown pgnats server option(s): #{unknown.join(", ")}. Known options: #{SERVER_OPTIONS.join(", ")}"
+
+          raise ArgumentError, message, caller
+        end
+
+        options.to_h { |key, value| [key.to_s, value.to_s] }
+      end
+  end
+end

data/lib/active_record_pgnats/subscription.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActiveRecordPgnats
+  # A row of pgnats.subscriptions: a subject and its function.
+  #
+  # @api private
+  class Subscription
+    include Comparable
+
+    attr_reader :subject, :function
+
+    def initialize(row)
+      @subject = row.fetch("subject")
+      @function = row.fetch("callback")
+    end
+
+    def <=>(other)
+      [subject, function] <=> [other.subject, other.function]
+    end
+
+    def ==(other)
+      subject == other.subject && function == other.function
+    end
+
+    def to_schema
+      <<~SCHEMA.then { |schema| schema.gsub(/^(?=.)/, "  ") }
+        create_nats_subscription #{subject.inspect}, function: #{function.inspect}
+      SCHEMA
+    end
+  end
+end

data/lib/active_record_pgnats/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveRecordPgnats
+  VERSION = "1.0.0"
+end

data/lib/active_record_pgnats.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require "active_record_pgnats/version"
+require "active_record_pgnats/adapters/postgres"
+require "active_record_pgnats/command_recorder"
+require "active_record_pgnats/configuration"
+require "active_record_pgnats/publish_trigger"
+require "active_record_pgnats/schema_dumper"
+require "active_record_pgnats/server"
+require "active_record_pgnats/statements"
+require "active_record_pgnats/subscription"
+
+# Migration methods for pgnats, Active Record only.
+module ActiveRecordPgnats
+  class << self
+    # Installs the statements, the recorder and the dumper.
+    #
+    # @returns [Boolean] true the first time, false once the hooks are in place.
+    def load
+      if @loaded
+        false
+      else
+        ActiveRecord::ConnectionAdapters::AbstractAdapter.include(Statements)
+        ActiveRecord::Migration::CommandRecorder.include(CommandRecorder)
+        ActiveRecord::SchemaDumper.prepend(SchemaDumper)
+        @loaded = true
+      end
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    attr_writer :configuration
+
+    def configure
+      yield configuration
+    end
+
+    def database
+      configuration.adapter
+    end
+  end
+end
+
+unless defined?(::Rails::Railtie)
+  ActiveRecordPgnats.load
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: active_record_pgnats
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nathan K
+bindir: bin
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !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: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: |
+  Adds methods to ActiveRecord::Migration to manage pgnats: its foreign server,
+  its subject subscriptions, and triggers that publish row changes to NATS.
+  Active Record only -- Rails support lives in the sibling
+  active_record_pgnats-rails gem.
+email:
+- nathankidd@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/active_record_pgnats.rb
+- lib/active_record_pgnats/adapters/postgres.rb
+- lib/active_record_pgnats/adapters/postgres/connection.rb
+- lib/active_record_pgnats/adapters/postgres/query_executor.rb
+- lib/active_record_pgnats/adapters/postgres/servers.rb
+- lib/active_record_pgnats/adapters/postgres/subscriptions.rb
+- lib/active_record_pgnats/command_recorder.rb
+- lib/active_record_pgnats/configuration.rb
+- lib/active_record_pgnats/publish_trigger.rb
+- lib/active_record_pgnats/schema_dumper.rb
+- lib/active_record_pgnats/server.rb
+- lib/active_record_pgnats/statements.rb
+- lib/active_record_pgnats/subscription.rb
+- lib/active_record_pgnats/version.rb
+homepage: https://github.com/n-at-han-k/active-record-pgnats
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/n-at-han-k/active-record-pgnats
+  source_code_uri: https://github.com/n-at-han-k/active-record-pgnats
+  changelog_uri: https://github.com/n-at-han-k/active-record-pgnats/blob/main/CHANGELOG-active_record_pgnats.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Active Record migrations for the pgnats extension.
+test_files: []