trellis-pg 0.1.0.pre.alpha-aarch64-linux → 0.1.0.pre.beta-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab179fc458edf7769718303b7c917edba788409afed458bbac3e1fc9218a66b5
-  data.tar.gz: '09dfcc2e6511356388f563e8fc1162c0e39b07bd84bef10533cb7dba5d6c1924'
+  metadata.gz: 6966a6e7b852cf951a4599b76e95cca5c937783cb856bf36466b135f1dd4b7f8
+  data.tar.gz: 9ff1a7ec48a54a20f647a20b996eee9f8f638046489bf58a2f4dcc7f123ddda8
 SHA512:
-  metadata.gz: e52938f3330417d8e5bd5f24041523e3617ba88417849ff711c9e4b2b6b68d812e8b655a66cba996f913782fd9dbf827a6dc1e774c34b5572097c1173ab030f0
-  data.tar.gz: b0b434295569cbb5f68fc3252eedb58255945e76eb3eb155e4c532a08ecfb69baba1fdd9a91f021b048209aeaf29482e9aab280469381c93591e757601322605
+  metadata.gz: 6309cad2e8a86315b428ae7dfdfc75fa5c66ea632972b85ce096b50615c1411e5fe2d1c157becd1bca4e32f47627adafb8dbc11ff619ee5804fea86746eae82b
+  data.tar.gz: 2e090a38bb47cf3c54fbfacc8100f5a9f255320aca827ef7d6f7a476f31bb2462857cee304bbdd435fa14f7d074703759ff56f9ddd6a2bfd6365ceba55288221

data/README.md

@@ -144,10 +144,33 @@ Trellis.shutdown
 | `staging:` | `false` | run the staging worker (installs change capture, starts backfills) here |
 | `drain_threads:` | `0` | threads applying staged changes to the targets |
 | `worker_threads:` | `2` | the threads of each Rust runtime a handle owns (its calls', and its background client's), invisible to Ruby's own sizing |
-
-The defaults run nothing in the background. Exactly one process in a fleet
-should set `staging: true`, and some process must run drain threads, or no
-definition ever reaches `:live`.
+| `max_call_pool_size:` | `20` | the most connections the handle's call pool opens; the background pool is sized by `staging:` and `drain_threads:` |
+| `call_pool_wait_timeout_ms:` | `30_000` | how long a call waits for a free call-pool connection before a `ConnectivityError` |
+
+The defaults run nothing in the background. Some process in a fleet must set
+`staging: true` and some process must run drain threads, or no definition ever
+reaches `:live`. Any number of processes may set `staging: true`: one takes the
+producer lock and leads, the rest stand by and take over when it goes away, so a
+rolling deploy needs no operator step. Under a preforking Puma with
+`TRELLIS_WORKER=1`, every Puma worker connects with `staging: true`, so all but
+one stand by; that is harmless, and each polls the lock every 5 seconds (see
+[Rolling deploys](../../docs/embedding.md#rolling-deploys)).
+
+### Resources
+
+At the defaults, a handle holds up to 20 Postgres connections (its call pool,
+opened as calls need them and closed after 60 seconds idle) and 3 threads. A
+worker handle (`staging: true, drain_threads: N`) also owns a background pool
+of up to `2N + 5` connections (`2N + 4` without staging, `1` with staging
+alone), closed after 60 seconds idle, and two connections that stay open: the
+staging session and one `LISTEN` shared by its drain threads. It holds 6
+threads: drain threads are tasks on its runtime, not OS threads. Its memory is
+bounded by row counts, not bytes: about `N` × 100,000 changed rows' images at
+its peak. `max_call_pool_size:` lowers the 20 (the background pool is sized by
+the handle's roles, not by an option), and `worker_threads:` sets the threads.
+Every handle (each `Trellis::Instance` too) costs this again. The full
+accounting is in
+[`docs/embedding.md`](../../docs/embedding.md#what-a-handle-uses).
 
 ### Several instances
 

data/lib/trellis/error.rb

@@ -82,7 +82,7 @@ module Trellis
   #
   # Also Trellis.connect's error in a process forked while its parent had a
   # handle running, which may have inherited a lock that handle's threads
-  # held (issue #600): shut down before forking (Puma's before_fork).
+  # held: shut down before forking (Puma's before_fork).
   class ForkedHandleError < ValidationError
   end
 

data/lib/trellis/instance.rb

@@ -98,7 +98,7 @@ module Trellis
   # forked child's calls on an instance it inherited raise
   # Trellis::ForkedHandleError, and its shutdown leaves the parent's handle
   # alone and does nothing. So does Instance.connect in a child forked while
-  # any instance of its parent was running (issue #600).
+  # any instance of its parent was running.
   class Instance
     extend Checks
     include Checks
@@ -111,7 +111,7 @@ module Trellis
       # Connects a new instance and returns it. Raises ForkedHandleError in
       # a process forked while its parent had an instance running
       # (connected, connecting, or not yet fully shut down): it may have
-      # inherited a lock one of that instance's threads held (issue #600).
+      # inherited a lock one of that instance's threads held.
       #
       # - url: where the database is, as a libpq connection string
       #   ("host=... dbname=...") or URL. Nothing is read from the environment.
@@ -121,8 +121,10 @@ module Trellis
       # - target_schema: the schema a bare target table name is created in.
       # - staging: whether this process runs the instance's staging worker,
       #   which installs change capture on the source tables and starts each
-      #   new transform's backfill. Exactly one process in a fleet should,
-      #   per instance.
+      #   new transform's backfill. Any number of processes may set it: one
+      #   takes the instance's producer lock and leads, the rest stand by and
+      #   take over when it goes away, so a rolling deploy needs no
+      #   operator step.
       # - drain_threads: how many threads apply staged changes to the targets.
       #   Some process must run at least one per instance, or no definition
       #   reaches :live.
@@ -130,13 +132,20 @@ module Trellis
       #   instance owns (its calls', and its background client's), invisible
       #   to Ruby's own thread sizing, so kept small and explicit. Each
       #   instance has its own; nothing is shared between instances.
+      # - max_call_pool_size: the most connections this instance's call pool
+      #   (its API calls) opens at once. Connections open as calls need them
+      #   and close after 60 seconds idle. The background client's pool is
+      #   sized by staging and drain_threads, not by this.
+      # - call_pool_wait_timeout_ms: how long a call waits for a free call-pool
+      #   connection before failing with a ConnectivityError.
       #
       # The defaults (staging: false, drain_threads: 0) run nothing in the
       # background, which is what a migration step or a console wants. The
       # staging worker reads Trellis's tables as it starts, so a staging: true
       # connect to an unmigrated schema fails: migrate first.
       def connect(url:, schema: "trellis", target_schema: "public", staging: false,
-                  drain_threads: 0, worker_threads: 2)
+                  drain_threads: 0, worker_threads: 2, max_call_pool_size: 20,
+                  call_pool_wait_timeout_ms: 30_000)
         string_option!(:url, url)
         string_option!(:schema, schema)
         string_option!(:target_schema, target_schema)
@@ -152,7 +161,19 @@ module Trellis
                 "worker_threads must be a positive Integer, got: #{worker_threads.inspect}"
         end
 
-        handle = Native.connect(url, schema, target_schema, staging, drain_threads, worker_threads)
+        unless max_call_pool_size.is_a?(Integer) && max_call_pool_size >= 1
+          raise ValidationError,
+                "max_call_pool_size must be a positive Integer, got: #{max_call_pool_size.inspect}"
+        end
+        unless call_pool_wait_timeout_ms.is_a?(Integer) &&
+               call_pool_wait_timeout_ms.between?(0, MAX_TIMEOUT_MS)
+          raise ValidationError,
+                "call_pool_wait_timeout_ms must be a non-negative Integer, got: " \
+                "#{call_pool_wait_timeout_ms.inspect}"
+        end
+
+        handle = Native.connect(url, schema, target_schema, staging, drain_threads, worker_threads,
+                                max_call_pool_size, call_pool_wait_timeout_ms)
         instance = new(handle, schema)
         register(instance)
         instance

data/lib/trellis/pg.rb

@@ -71,7 +71,7 @@ require_relative "instance"
 # calls on a handle it inherited raise Trellis::ForkedHandleError, except
 # Trellis.shutdown, which leaves the parent's handle alone and does nothing.
 # So does Trellis.connect in a child forked while its parent's handle was
-# running (issue #600).
+# running.
 module Trellis
   @default = nil
   @lock = Mutex.new

data/lib/trellis/railtie.rb

@@ -49,7 +49,7 @@ module Trellis
   # - config.trellis.connect_on_boot = false, for a server that forks with
   #   no hook to shut the handle down first (see below).
   #
-  # A handle doesn't survive fork (issue #600). A preforking server that
+  # A handle doesn't survive fork. A preforking server that
   # loads the app before forking (Puma's preload_app!, on by default with
   # more than one worker) must shut the boot handle down before it forks,
   # and connect one in each worker:

data/lib/trellis/schema_dump.rb

@@ -10,7 +10,7 @@ module Trellis
   # appends the `INSERT`s that describe how the schema came to be. A database
   # built from the file (`db:schema:load`, `db:prepare`, the test database
   # `maintain_test_schema!` loads) then has every transform defined, with no
-  # Trellis step to run: Trellis's worker finds the definitions unbuilt and builds them (issue #644, ADR-0010).
+  # Trellis step to run: Trellis's worker finds the definitions unbuilt and builds them (ADR-0010).
   #
   # Needs `config.active_record.schema_format = :sql`: a `schema.rb` can't
   # carry another schema's tables or triggers. With `:ruby`, the dump raises
@@ -156,7 +156,7 @@ module Trellis
 
       # The keywords of a libpq connection string or URI. A failure names
       # what was being read and never the string or libpq's message, which
-      # can quote part of a password (as Trellis's own parse does, #608).
+      # can quote part of a password (as Trellis's own parse does).
       def conninfo(url, what)
         PG::Connection.conninfo_parse(url.to_s).to_h { |entry| [entry[:keyword], entry[:val]] }
       rescue PG::Error

data/lib/trellis/values.rb

@@ -376,11 +376,11 @@ module Trellis
   Divergence = Data.define(:kind, :key, :column, :persisted, :recomputed, :table, :detail)
 
   # The configuration this process's handle connected with, as Trellis.config
-  # returns it: connect's schema and target_schema, and the connection pool's
-  # size cap and how long a call waits for a free connection.
+  # returns it: connect's schema and target_schema, and the handle's call pool
+  # as it was built: max_call_pool_size and call_pool_wait_timeout_ms.
   #
   # Not the url: a connection string can carry a password, and a Config is
   # the kind of value that ends up in a log line whole. The caller already
   # has the url it connected with.
-  Config = Data.define(:schema, :target_schema, :pool_max_size, :pool_wait_timeout_ms)
+  Config = Data.define(:schema, :target_schema, :max_call_pool_size, :call_pool_wait_timeout_ms)
 end

data/lib/trellis/version.rb

@@ -3,5 +3,5 @@
 module Trellis
   # The trellis-pg gem's version: the Trellis release's, which a
   # `v<VERSION>` tag releases (docs/releasing.md).
-  VERSION = "0.1.0-alpha"
+  VERSION = "0.1.0-beta"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trellis-pg
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha
+  version: 0.1.0.pre.beta
 platform: aarch64-linux
 authors:
 - Salesforce
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-26 00:00:00.000000000 Z
+date: 2026-10-29 00:00:00.000000000 Z
 dependencies: []
 description: |
   A native extension over the trellis crate's BlockingTrellis, so a Rails