You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 17988ad
Browse filesBrowse the repository at this point in the historyBrowse files
docs(skills,adr): teach the code-defined datasource credential route (OS_DATASOURCE_NAME_PASSWORD behind the host switch)
skills/objectstack-data/rules/datasources.md: the credential section now says a
code-declared datasource reads its password at connect from the variable derived
from its name while the host switch OS_DATASOURCE_ENV_CREDENTIALS is on (the CLI
host defaults it on, a library composition is off, on/off only), that a declared
credentialsRef or connector still wins with no fallback, and the operator's
caution that an installed package may declare a datasource of any free name and
so read that variable. The added text is paid for under the token ratchet by
deleting restatements in the same file; the file lands at 910 of 911 tokens.
ADR-0015: the Amended-by line, an inline correction of the D7 note's "that stays
true for a database", the section 10 credentials bullet, and a dated amendment
note under section 10 recording the route, its guards, the failure text and the
trust consequence. ADR-0062 D3: a dated amendment recording the slot's place in
the connect's resolution order.
A patch changeset for @objectstack/skills, which ships skills/**.
Claude-Session: https://claude.ai/code/session_01FEkQ5phX4SAaFQKww3TfKb
Co-authored-by: Claude <noreply@anthropic.com>
docs(skills): objectstack-data teaches the code-defined datasource credential route (`OS_DATASOURCE_<NAME>_PASSWORD`, behind the host switch)
6
+
7
+
Clause-②: no
8
+
Metadata-protocol: none
9
+
10
+
-**Before.**`rules/datasources.md` taught `credentialsRef` and `connector` as the only credential channels. A datasource defined in code has no `sys_secret:` handle to point at (the Setup form refuses a code-origin datasource, and nothing else mints one), so an agent following the rule wrote a reference the connect could never resolve.
11
+
-**Now.** The credential section says a code-declared datasource reads its password at connect from `OS_DATASOURCE_<NAME>_PASSWORD` (the name upper-cased) while the host switch `OS_DATASOURCE_ENV_CREDENTIALS` is `on`; that `os serve`, `os start` and `os dev` default it on, a library composition leaves it off, and the switch takes `on` or `off` only; that a declared `credentialsRef` or `connector` still wins and never falls back to the variable; and the operator's caution that an installed package may declare a datasource of any free name and so read that variable.
12
+
- The file stays under its token ceiling: the new text is paid for by deleting restatements in the same file (the field-reference pointer the references index already carries, the `writable` and `columnMap` restatements of their own sections, the `datasource` field default the SKILL.md field table carries, and two detail clauses). No ceiling moves, no frontmatter, schema or behaviour changes.
**Amended by**: [ADR-0143](./0143-outbound-connector-auth-is-open-tier.md) (2026-10-27), attribution only — see the note below. D7 (2026-10-29, ruling 6486136301 on #27298) — an API-backed datasource may borrow a declared connector instance's credential through `external.connector`; see the D7 note below. #27688 (2026-10-30), example only — §8's `credentialsRef` is a `sys_secret:` handle, the only form the shipped secret binder resolves; see the note under §8. #27917 (2026-10-30), dialect list only — §4.6 names the `odata` vocabulary the matrix gained with #27745.
7
+
**Amended by**: [ADR-0143](./0143-outbound-connector-auth-is-open-tier.md) (2026-10-27), attribution only — see the note below. D7 (2026-10-29, ruling 6486136301 on #27298) — an API-backed datasource may borrow a declared connector instance's credential through `external.connector`; see the D7 note below. #27688 (2026-10-30), example only — §8's `credentialsRef` is a `sys_secret:` handle, the only form the shipped secret binder resolves; see the note under §8. #27917 (2026-10-30), dialect list only — §4.6 names the `odata` vocabulary the matrix gained with #27745.#28208 (2026-10-31, ruling 6525963988 on #27687) — a datasource defined in code reads its credential at connect from `OS_DATASOURCE_<NAME>_PASSWORD`, behind the host switch `OS_DATASOURCE_ENV_CREDENTIALS`; see the note under §10 and the correction in the D7 note.
8
8
9
9
> **Amendment note D7 (2026-10-29, ruling 6486136301, letter A) — a second credential channel.**
10
10
> §10 says credentials reach a datasource only through `credentialsRef`. That stays true for a
11
-
> database. An **API-backed** datasource (a plugin-contributed driver over a vendor API, such as
11
+
> database *(amended 2026-10-31, #28208: a database datasource defined in code has a third route,
12
+
> the environment variable derived from its name — see the note under §10)*. An **API-backed**
13
+
> datasource (a plugin-contributed driver over a vendor API, such as
12
14
> OData) may instead name a declared connector instance in `external.connector` and borrow that
13
15
> instance's credential — whichever kind its `auth` declares (`ConnectorInstanceAuthSchema`:
14
16
> `bearer`, `api-key` and `basic` today; ADR-0143 D2 adds the grant-bearing `oauth2`,
@@ -766,7 +768,9 @@ managed Postgres for low-latency joins.
766
768
component that resolves the actual connection string. *(Amended by
767
769
D7, see the note at the top: an API-backed datasource may instead
768
770
borrow a declared connector instance's credential through
769
-
`external.connector`.)*
771
+
`external.connector`.)**(Amended 2026-10-31, #28208, see the note below: a datasource
772
+
defined in code, which has no handle to point at, reads its credential at connect from the
773
+
environment variable derived from its name.)*
770
774
-**Connection pools** default conservatively for external mode
771
775
(`max: 5`) to protect the remote system; `pool` may be overridden.
772
776
-**Timeouts** are enforced at the driver. AI tool calls additionally
@@ -787,6 +791,66 @@ managed Postgres for low-latency joins.
787
791
otherwise federated objects fall back to poll-based change feeds.
788
792
This is out of scope for v1.
789
793
794
+
> **Amendment note (2026-10-31, #28208 — ruling 6525963988 on #27687, option 5; the failure text and
795
+
> the collision claim as PR #28325 left them) — a third credential route, for a datasource defined
796
+
> in code.** A datasource declared in code (`defineDatasource`, a package's `*.datasource.ts`) has
797
+
> no `sys_secret:` handle to point `credentialsRef` at: the Setup → Datasources form refuses a
798
+
> code-origin datasource, and nothing else mints one. Its route is the runtime environment. At
799
+
> connect, `DatasourceConnectionService` reads `OS_DATASOURCE_<NAME>_PASSWORD`, `<NAME>` being the
800
+
> datasource name upper-cased with every character outside `[A-Z0-9]` replaced by `_` (`warehouse`
Copy file name to clipboardExpand all lines: docs/adr/0062-external-datasource-runtime.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -91,6 +91,10 @@ Auto-connect must not change apps that today declare datasources that are *decor
91
91
92
92
`DatasourceConnectionService` resolves `external.credentialsRef` (and any `secret` config fields) through the host-provided `SecretBinder` over `ICryptoProvider`**before** building the driver. Open-core default is `InMemoryCryptoProvider`; a datasource that needs a secret the host cannot decrypt **fails closed** (clear boot error, datasource left unconnected — not a silent skip). This reuses the exact mechanism the runtime-admin "Add Datasource" wizard already uses, so code- and runtime-origin secrets converge.
93
93
94
+
> **Amendment (2026-10-31, #28208 — ruling 6525963988 on #27687, option 5; the failure text and the collision claim as PR #28325 left them) — a second resolution source at the same point, for a datasource defined in code.** `credentialsRef` and the ADR-0015 D7 connector borrow keep the point above and keep failing closed. A datasource the host registers from code can carry neither: the Setup → Datasources form refuses a code-origin datasource, so no `sys_secret:` handle is ever minted for one. For it, `DatasourceConnectionService.connect()` has a third step at that same point — after the `credentialsRef` resolution and the connector borrow, before the driver factory — taken only when neither channel is declared, the connect is not `asDefault`, the trigger is `declared-auto`, the name is in the host's code-datasource set (the `code-datasource-names` service: provenance, never a record's `origin`), and the host opted in. The step reads the environment variable `OS_DATASOURCE_<NAME>_PASSWORD` (`datasourceEnvCredentialVar`, `packages/services/service-datasource/src/datasource-env-credential.ts`: the name upper-cased, each character outside `[A-Z0-9]` replaced by `_`) and hands a non-empty value to the factory as the connection's `secret`.
95
+
>
96
+
> The opt-in is the host switch `OS_DATASOURCE_ENV_CREDENTIALS`. The datasource-admin plugin wires the slot into the service only when the switch reads `on` (unset or empty is off; any other value refuses the boot at `init()`), and only the CLI host stamps `on` as its default — `os serve`, which `os start` and `os dev` run (`packages/cli/src/utils/datasource-env-credentials-default.ts`); a library composition never sees the slot. An unset variable leaves the build as it was: a driver refusal is `failed-degraded` with the driver's own error, followed by `(note: datasource 'NAME' is defined in code and reads its credential from OS_DATASOURCE_NAME_PASSWORD at connect, which is not set on this host)`, and a declared reference that fails never falls through to the variable. Two live connects whose names derive one variable are refused at the second (`failed-credentials`, naming both datasources and the variable; a connect that failed releases its claim). The value reaches nothing but the factory, and no message carries it. **Default behavior** below gains one line: a datasource defined in code connects with the credential its derived variable holds when the host opted in. Who may then read that variable — any installed package declaring the name — is recorded as an operator's caution in ADR-0015 §10's amendment note. Not taken: a variable named in metadata, and an environment fallback behind a declared reference.
97
+
94
98
### D4 — Visibility converges on the metadata registry (shipped, ratified here)
95
99
96
100
Code-defined datasources surface in `GET /api/v1/datasources`, `GET /api/v1/meta/datasource` and **Setup → Datasources** via the single in-memory metadata registry, stamped `origin: 'code'` (read-only in the admin UI). Shipped in #2157 (the in-memory metadata fallback was missing `registerInMemory`, silently skipping registration on the host-config boot path). This ADR ratifies that the metadata registry is the single source for datasource listing across all boot paths; the admin `listDatasources` and `protocol.getMetaItems` both read it.
0 commit comments