Connections

A connection is a stored, named reference to one external database. It carries the datasource type, the host and port, the database name, the credentials, and any TLS settings. Every extraction job and every schema call addresses a datasource by the connection’s configName, never by its host. Fetcher owns the credential from the moment it arrives. It encrypts the password before storage and never returns it.

​

What a connection holds

---

The Manager rejects an invalid TLS mode for the declared type. Each database driver accepts a different set of modes, and Fetcher validates the mode against the type before it stores the record.

​

Lifecycle

---

​

Encrypted credentials

---

Fetcher derives four independent keys from the single APP_ENC_KEY master key, through HKDF-SHA256. One of those keys protects datasource credentials. The password reaches storage encrypted with AES-256-GCM, and the stored record keeps the APP_ENC_KEY_VERSION that protected it. That version is what makes key rotation tractable: a record states which key opens it. The empty key version carries meaning. It marks an internal datasource — one an operator declares through DATASOURCE_{NAME}_* environment variables rather than through the API. Fetcher builds those connections in memory at startup and keeps no record of them at rest. The operator’s own secret manager owns the credential. See Configuration.

​

Testing a connection

---

The test operation does real work. It builds the connector, opens the datasource, runs the driver’s own connectivity check, and closes the connector on every path — success or failure. The response carries latencyMs, the observed round trip in milliseconds. Use it as a signal about the network path between Fetcher and the datasource, not as a benchmark of the database. The endpoint is rate-limited to 10 tests per minute per connection. A caller past that budget receives 429 Too Many Requests with a wait hint. The limit lives in the Manager, not in the Engine, so an embedded host sets its own policy. A failed test tells you that the connection failed. It does not tell you why in driver terms. Fetcher discards the underlying error, because that text can carry a DSN or a credential.

​

The 409 on active jobs

---

The rule exists to keep a running extraction consistent with the connection it planned against. A host swap or a credential change mid-extraction would leave a job reading from a datasource nobody asked for. The Engine enforces the gate through an optional port, not through a hard dependency on job storage. The Manager answers the question from its job repository. An embedded host answers it however it tracks work — an in-memory set, a distributed lock, or a flat “no”. A host that supplies nothing gets no gate, and mutations proceed.

​

Host safety in multi-tenant mode

---

With MULTI_TENANT_ENABLED=true, Fetcher validates the host of every tenant-supplied connection before it dials. Validation runs at two layers:

• At request parsing, a check without DNS rejects a blocked IP literal outright.
• In the datasource factory, a resolving check rejects blocked hostnames such as localhost and cloud metadata names, then rejects every address the hostname resolves to.

Private ranges, loopback, and cloud metadata endpoints are blocked. A rejected host returns 400. The guard never applies to internal datasources. An operator who configures a datasource through environment variables has already made that decision.

​

Migration operations

---

Two operations exist only for connections that predate product scoping:

• GET /v1/management/connections/unassigned lists connections with no product.
• POST /v1/management/connections/{id}/assign attaches one to the product in the X-Product-Name header.

The assignment is one-time and irreversible. A second attempt on an already-assigned connection returns a conflict.

​

Next steps

---