diff --git a/.changeset/23768-datasources-default-host-reserved.md b/.changeset/23768-datasources-default-host-reserved.md new file mode 100644 index 00000000000..249058a77d2 --- /dev/null +++ b/.changeset/23768-datasources-default-host-reserved.md @@ -0,0 +1,9 @@ +--- +'@objectstack/skills': patch +--- + +docs(skills): the `objectstack-data` datasources rule states that `default` is host-reserved — the host connects it from `OS_DATABASE_URL`, and a stack that declares a datasource named `default` is refused (#23768) + +Clause-②: no + +`skills/objectstack-data/rules/datasources.md`'s opening paragraph read "Most apps need only the `default` datasource; declare more to read/write a separate or external database." "Declare more" implied that `default` is declared too, and a stack whose `datasources` collection carries an entry named `default` is refused at `defineStack`, `os validate`, publish and boot: the host declares and connects `default` itself. The sentence is replaced by the rule the spec and runtime hold: `default` is host-reserved, the host connects it from `OS_DATABASE_URL`, a stack that declares a datasource named `default` is refused, and a datasource is declared under its own name only to read/write a separate or external database. The added words are paid for inside the same file by deleting two restatements of the field reference: "`external` settings are required when `schemaMode !== 'managed'`" (the schema refuses the omission itself) and "Set `autoConnect: true` to force a live connection" (the auto-connect list two lines above already names it). No behaviour changes; nothing an author writes changes. diff --git a/skills/objectstack-data/rules/datasources.md b/skills/objectstack-data/rules/datasources.md index 4e8310862bc..f39634a1381 100644 --- a/skills/objectstack-data/rules/datasources.md +++ b/skills/objectstack-data/rules/datasources.md @@ -2,8 +2,10 @@ A **datasource** (`defineDatasource`, a `*.datasource.ts` metadata file) is a connection to a data store. Objects route to one via their `datasource` field -(default: `'default'`). Most apps need only the `default` datasource; declare more -to read/write a **separate** or **external** database. +(default: `'default'`). `default` is host-reserved: the host connects it from +`OS_DATABASE_URL`, and a stack that declares a datasource named `default` is +refused. Declare a datasource under its own name only to read/write a +**separate** or **external** database. Full field reference: `node_modules/@objectstack/spec/src/data/datasource.zod.ts`. @@ -15,8 +17,6 @@ Full field reference: `node_modules/@objectstack/spec/src/data/datasource.zod.ts | `external` | A mature external DB ObjectStack does **not** own; DDL forbidden; boot mismatch **fails**. | | `validate-only` | Like `external`, but a mismatch **warns** instead of failing boot. | -`external` settings are **required** when `schemaMode !== 'managed'`. - ## Federated (external) objects An object on an external datasource binds to its remote table via `external`: @@ -55,7 +55,7 @@ objects' read metadata registered **automatically at boot** — no `onEnable` / 4. a **`datasourceMapping` rule routes at least one object to it**. A `managed` datasource that nothing routes to stays **metadata-only** — visible but -not connected. Set `autoConnect: true` to force a live connection. +not connected. ⚠️ A `datasourceMapping` rule is **routing, not a hint**. A rule pointing at a datasource that cannot be connected fails the boot, and a query against a mapped