Skip to content

docs(configure): federation ships today, and defineDatasource() exists #252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-bill merged 1 commit into from
Sep 2, 2026
Merged

docs(configure): federation ships today, and defineDatasource() exists #252

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 16 additions & 20 deletions content/docs/configure/data-sources.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,9 +85,14 @@ export default defineStack({
});
```

> There is **no** `defineDatasource()` helper. A datasource is just a
> `Datasource` object you place in the `datasources` array — exactly like
> the `examples/app-crm` stack does in the framework repo.
> **A `defineDatasource()` helper is also available.** The plain
> `Datasource` object above is a valid datasource — it is exactly what the
> `examples/app-crm` stack does in the framework repo — and
> `defineDatasource()`, exported from `@objectstack/spec` (and
> `@objectstack/spec/data`), takes the same config and runs the
> `DatasourceSchema` validation at the point of declaration, so a bad field
> is reported where you wrote it. The framework's own federation guide uses
> it.

## Binding objects to a datasource

Expand Down Expand Up @@ -229,26 +234,17 @@ configuration that backs the `default` datasource.
- **Scope with permissions.** Object- and field-level permissions apply
to connected data exactly as they do to native objects.

## Roadmap: in-product External Datasource Federation
## In-product external datasource federation

The flow above — connect a database, model objects, generate them with a
coding agent — works today with shipped building blocks. A richer,
**turn-key federation** experience is in active design under
coding agent — is the general path. The **turn-key federation** flow on top
of it, specified in
[ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md)
(status: *Proposed*). Planned, **not yet shipped**:

- A `schemaMode` (`managed` / `external` / `validate-only`) so ObjectOS
can bind to tables it does **not** own without trying to migrate them.
- An `external` binding sub-record on objects mapping object fields to
existing columns.
- An `os datasource introspect` / `validate` CLI to import a schema and
scaffold objects in one step.
- Boot-time and write-time **safety gates** for externally-owned schemas,
plus a Studio wizard for the whole flow.

Until those land, prefer the documented path: declare the datasource,
bind objects (generated or hand-written), and verify against a
non-production copy first.
(status: *Accepted*), **ships today**: bind objects to tables ObjectOS does
not own, with validation gates around them.

It is documented once, with the framework docs that own the surface —
[External Datasources (Federation)](https://docs.objectstack.ai/docs/data-modeling/external-datasources).

## Where to go next

Expand Down