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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab179fc458edf7769718303b7c917edba788409afed458bbac3e1fc9218a66b5
-  data.tar.gz: '09dfcc2e6511356388f563e8fc1162c0e39b07bd84bef10533cb7dba5d6c1924'
+  metadata.gz: 63761a2adb2fa1ca3880becd7c22f5271fd4a4b342a780000848d55f7d9d42d3
+  data.tar.gz: ac2f451538877658f9617dce4b13d8c93ad370f4123255e72db2f7954a069241
 SHA512:
-  metadata.gz: e52938f3330417d8e5bd5f24041523e3617ba88417849ff711c9e4b2b6b68d812e8b655a66cba996f913782fd9dbf827a6dc1e774c34b5572097c1173ab030f0
-  data.tar.gz: b0b434295569cbb5f68fc3252eedb58255945e76eb3eb155e4c532a08ecfb69baba1fdd9a91f021b048209aeaf29482e9aab280469381c93591e757601322605
+  metadata.gz: d78db6130783dbe45247819ac453fc95bc1fbcc36b6bf2bd790a8dfaea28a6861db69f852fa6b7f611762988444974ee00bffc6eca849c8fa7ca9cfbf7fc1748
+  data.tar.gz: 382d87f3aa62444be9143a324820f4a7bca471fe5d98e4970a43d3d8a1984e5ef7a6c9c0cab615b79c9c3c05fc9dd2de44767942a5649c1487167e78088dc533

data/README.md

@@ -103,6 +103,9 @@ Nothing in the binding uses it.
   and `self_check_job` returns `nil` for the replaced job or one whose
   transform was dropped. With no drain worker anywhere in the fleet a job
   stays `:queued`.
+- `Trellis::Metrics.render_prometheus`: the process-wide metrics registry as
+  Prometheus text, for a `/metrics` route the app already serves (the
+  binding opens no port; see [Metrics](#metrics)). It needs no handle.
 
 ```ruby
 require "trellis/pg"
@@ -144,10 +147,59 @@ 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 |
+| `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).
+
+### Metrics
+
+The engine's metrics live in one registry per process, holding the series of
+every handle in it; `Trellis::Metrics.render_prometheus` renders them in
+Prometheus's text format. Every series carries a `trellis_instance` label
+(`<database>/<catalog schema>`), so instances in one process stay apart, and
+`trellis_instance_up` is 1 while an instance's handle runs and 0 after it
+shuts down. The metrics themselves are listed in
+[`docs/observability.md`](../../docs/observability.md).
+
+The binding opens no port, so serve the text from a route of the app's own:
 
-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`.
+```ruby
+# config/routes.rb
+get "/metrics", to: proc {
+  [200, { "content-type" => "text/plain; version=0.0.4" }, [Trellis::Metrics.render_prometheus]]
+}
+```
+
+Under a forking server each worker process has its own registry, holding
+only its own handles' series, so Prometheus scrapes each worker (or the
+worker handle, `staging: true`, runs in a process of its own that it
+scrapes). A process forked while its parent had a handle running can't
+render the registry, as it can't connect: it raises
+`Trellis::ForkedHandleError` (see [Forking servers](#forking-servers)).
 
 ### Several instances
 
@@ -501,6 +553,7 @@ source rows; a test database has none, so that is immediate. Runtime state
 ## Layout
 
 - `lib/`: the `Trellis` module and `Trellis::Instance`, its error classes and its `Data` values,
+  `Trellis::Metrics`,
   the Rails integration (`trellis/railtie.rb`, `trellis/migration.rb`),
   loaded only in an app that has Rails, and the test helpers
   (`trellis/test_support.rb`), loaded only when required.

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/metrics.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Trellis
+  # The engine's metrics, in Prometheus text exposition format: the Rust
+  # crate's trellis::Metrics#render_prometheus
+  # (docs/decisions/0009-observability-decisions.md).
+  #
+  # The registry is process-wide: one body holds the series of every Trellis
+  # handle in this process, so it needs no handle and works before
+  # Trellis.connect and after Trellis.shutdown. Every series carries a
+  # trellis_instance="<database>/<catalog schema>" label, so instances in one
+  # process stay apart. trellis_instance_up is 1 while an instance has a
+  # running handle and 0 after its last one shuts down; the other gauges of a
+  # stopped instance disappear after 60 seconds. See docs/observability.md.
+  #
+  # The binding opens no port. Serve the text from a route the app already
+  # has, for example in Rails:
+  #
+  #   # config/routes.rb
+  #   get "/metrics", to: proc {
+  #     [200, { "content-type" => "text/plain; version=0.0.4" }, [Trellis::Metrics.render_prometheus]]
+  #   }
+  #
+  # In a forking server each worker process has its own registry, holding
+  # only its own handles' series, so scrape every worker (or run the worker
+  # handle, staging: true, in a process of its own and scrape that).
+  #
+  # A process forked while its parent had an engine running may have
+  # inherited the registry's lock held, so rendering there raises
+  # Trellis::ForkedHandleError, as Trellis.connect does.
+  module Metrics
+    # Renders the registry's current contents: # HELP and # TYPE lines, then
+    # each series' samples.
+    def self.render_prometheus
+      Native.render_prometheus
+    end
+  end
+end

data/lib/trellis/pg.rb

@@ -24,6 +24,7 @@ else
 end
 
 require_relative "instance"
+require_relative "metrics"
 
 # Embedded Trellis for Ruby apps: a native extension over the `trellis`
 # crate's BlockingTrellis, so a Rails app can define and run streaming
@@ -48,6 +49,7 @@ require_relative "instance"
 # - Operations: request_backfill, detect_capture_disruptions, has_live_drain_workers?,
 #   has_live_staging_worker?, watermark_token, await_converged, self_check,
 #   self_check_job.
+# - Metrics: Trellis::Metrics.render_prometheus, which needs no handle.
 #
 #   # A deploy's migration step: the defaults run nothing in the background.
 #   Trellis.connect(url: "host=localhost dbname=app")
@@ -71,7 +73,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-gamma"
 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.gamma
 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
@@ -25,6 +25,7 @@ files:
 - lib/trellis/4.0/trellis_ruby.so
 - lib/trellis/error.rb
 - lib/trellis/instance.rb
+- lib/trellis/metrics.rb
 - lib/trellis/migration.rb
 - lib/trellis/pg.rb
 - lib/trellis/railtie.rb