This page describes Darling v3.13.0. The source of this page is on GitHub at that version.
Audience: operators.
This page covers the store that the Darling service runs for itself in managed mode. It moved here from the Darling operator guide.
With postgres.managed = true (the sample’s default), the service runs its own bundled PostgreSQL 18 + TimescaleDB and a from-zero install needs no database provisioning at all. Windows only, like every DPAPI surface here.
{
"postgres": {
"managed": true,
"port": 5641,
"dataDirectory": null
}
}
What first run does. The service looks for pg-runtime\pgsql\ beside its binary, extracting it from pg-runtime.zip when only the zip is present (deleting the extracted directory is therefore always safe — it self-heals). If the data directory has no cluster, it generates a 32-character random password, protects it with DPAPI LocalMachine into pg-credential.dpapi beside the data directory (credential first, so a crash mid-initdb never strands a cluster nobody can log into), then runs initdb with scram-sha-256 auth, data checksums, and UTF8/C locale. A marker-guarded block appended to postgresql.conf preloads TimescaleDB, sets the port, and restricts listening to 127.0.0.1; a second versioned block sizes background workers up for the per-hypertable compression jobs, DERIVED from the live hypertable count so it cannot go stale as collectors are added (timescaledb.max_background_workers = hypertables + 2, max_worker_processes = 3 + that + 8 — today 57 and 68 for 55 hypertables; PostgreSQL’s default of 8 workers cannot launch them); a third versioned block sizes memory from the host’s physical RAM for the up-to-500-servers case (shared_buffers = min(25% RAM, 1GB), effective_cache_size = 75% RAM, maintenance_work_mem = min(max(5% RAM, 1536MB), 25% RAM, 2048MB), and a deliberately-modest per-connection work_mem = clamp(RAM/512, 16MB, 64MB) — on an 8 GB box that is shared_buffers 1024MB / work_mem 16MB; the stock 128 MB / 4 MB defaults are fine at small scale but bottleneck at fleet scale). Later blocks re-state single settings that field measurement moved: a fifth caps shared_buffers for the co-located store, a sixth turns on the log-rotation ring, and a seventh carries the maintenance_work_mem floor that TimescaleDB’s compression sort runs on (measured at ~+70% compression throughput on a 16 GB-class host, plateauing by 1536 MB). postgresql.conf takes the LAST assignment of a setting, so these override without rewriting anything. Every append is re-checked on every start, so a crash between initdb and the append heals itself instead of silently degrading — and clusters initialized before a given block existed gain it on their next start (effective at the next PostgreSQL restart). Then pg_ctl start, CREATE DATABASE darling, and the normal startup path (migrations, TimescaleDB adoption — you should see N/N collector table(s) are hypertables, both numbers equal and equal to the collector count; a converted count BELOW the total means some table stayed plain and the line above it says which) continues exactly as in bring-your-own mode. The connection string is derived from the stored credential; the Viewer and the MCP host on the same machine derive it the same way, so nothing needs configuring there either.
One service-owned settings file, darling-managed.conf (#4215). Every setting the service manages lives in darling-managed.conf, next to the data directory, rewritten whole on every start. postgresql.conf gets a single include 'darling-managed.conf' line at its end; nothing else in postgresql.conf is the service’s.
No opt-out. The service puts the include line back, with a warning, if you remove it — there is no config knob that turns this off. A managed store’s settings must be readable and reproducible from one file, and a missing include is the failure mode the service refuses to hide: without it PostgreSQL silently falls back to its own defaults (work_mem at 4MB, for example) instead of refusing to start. If you want a setting the service does not manage, add a line below the include in postgresql.conf, or set it with ALTER SYSTEM; either one wins over darling-managed.conf.
The include sits at the end of postgresql.conf and overrides any line of yours above it. random_page_cost is set only by darling-managed.conf, so a store that was set up before it became managed can still hold your own line for it above the include. If postgresql.conf assigns it above the include, the service leaves that key out of the file and your value stays in force. The log names the key, the value and the line at Information level on every start. Remove or comment out your line to let the managed value apply from the next start.
By default TimescaleDB sends a usage report to Timescale’s server about once a day and checks for a newer version. The managed store turns that off with timescaledb.telemetry_level = 'off' in darling-managed.conf (#7446), so it makes no outbound call you did not choose. A store set up by an earlier build gets the setting at its next start. You change nothing. A store you run yourself (postgres.managed = false) is never changed.
With the level off, TimescaleDB’s own policy_telemetry job logs a failed run every day, because a switched-off report counts as a failed run. So the service unschedules that job while the level is off, at each start and again right after a new store gets its extension. To turn the report back on, run ALTER SYSTEM SET timescaledb.telemetry_level = 'basic' and restart the service. postgresql.auto.conf is read after darling-managed.conf, so your value wins, and the next start schedules the job again. The Docker Compose store sets the level on its command: line, which outranks ALTER SYSTEM. To turn the report back on there, remove that setting from the file.
Downgrading to a build before 3.9. Stop the service first. Every migration to darling-managed.conf keeps a backup of the postgresql.conf it replaced, named postgresql.conf.pre-4215.<utc>.bak, beside the data directory. Restore that file over the current postgresql.conf before starting the older build. An older build has no knowledge of darling-managed.conf: skip the restore and it appends its own marker-guarded blocks below the include line, which still win, but the file keeps growing with each downgrade.
Lines below the include survive a major PostgreSQL upgrade. A major-version upgrade carries postgresql.auto.conf (the ALTER SYSTEM file) into the new cluster. It also carries the lines added below the include in postgresql.conf (#4358). The new major version can reject a line, and then that line is not carried and the log says so.
Why scram and not trust, even loopback-only. Trust auth would hand superuser to any local code that can open a loopback socket — every other local user, and network-capable-but-not-filesystem-capable attack primitives like SSRF from a co-hosted app. With scram the credential travels on the wire, failed attempts are auditable, and access is confined to what can read the DPAPI-protected credential file. listen_addresses = '127.0.0.1' keeps the server unreachable off the machine on top — unless you deliberately opt into a LAN endpoint (see Opt-in Network Endpoints (LAN)), which reconciles listen_addresses, a hostssl pg_hba rule, and TLS on every start and is otherwise off.
Lifecycle. On shutdown the service stops the server (pg_ctl stop -m fast) only when it started it. A server that was already running — an operator’s own pg_ctl, or a postmaster that survived a service crash — is adopted for connections but never stopped: you’ll see already running … will not stop it in the log, and the service keeps collecting into it.
The runtime zip. pg-runtime.zip ships beside the service binary in packaged releases. Building from source, produce it once with Darling\tools\fetch-pg-runtime.ps1 — it downloads the pinned EDB PostgreSQL 18 binaries and TimescaleDB, verifies their SHA256, prunes what the service doesn’t need, and writes the zip to Darling\artifacts\; copy it next to the built service exe.
When a package ships a new runtime. Every start compares the shipped pg-runtime.zip with a record of the one it extracted (pg-runtime\pg-runtime.sha256). A difference swaps the runtime: the current one is rescued to pg-runtime-prev, the new one is extracted, and a store on an older PostgreSQL major is upgraded in place with pg_upgrade. When the new runtime also moves TimescaleDB, the store’s extension is moved before the store opens (#3908). The service starts the store on a private loopback port with TimescaleDB’s background workers off, runs ALTER EXTENSION timescaledb UPDATE as the first statement of a session of its own, verifies it, stops the store, and only then starts it normally. Nothing else can connect in that window, so no session and no background job ever sees the extension change under it. It costs one extra start and stop of the store, only on a start where the extension has to move or has not been read yet. The version the store ended on is recorded in darling-timescaledb.version in the data directory. The runtime also carries the libraries of the TimescaleDB versions earlier releases shipped. So a store whose update fails still opens on its own version: the service raises a Critical Store Runtime Upgrade alert with the reason, and retries on its next start. Rolling back to an earlier release keeps this runtime in place. Releases before 3.3 never swap an extracted runtime, 3.3 through 3.8 find pg-runtime\pg-runtime.stamp pinned to the package they shipped, and this release will not swap in, or extract, a package that has no libraries for the store’s recorded TimescaleDB. Keep the pg-runtime folder when you roll back: a clean reinstall of 3.8 or earlier extracts that release’s own runtime, which cannot open a store already on TimescaleDB 2.30.1. One cost of a rollback past 3.9: 3.8.0’s hourly store-size sweep does not understand TimescaleDB 2.29+ (#3918), so that series stops until you upgrade again. Collection is unaffected.
Server log. The bundled server’s own log is pg.log beside the data directory — that’s where PostgreSQL explains a refused start; bootstrap errors in the service log quote its tail.