Data Sources

#Source Model

A source is explicitly attached to one persistent agent. Attachment validates the non-secret configuration, discovers structure, establishes an exact read scope, and atomically commits a current catalog snapshot before the source becomes usable.

Daita currently supports two catalog-backed source adapters:

• SQLite
• PostgreSQL

The local workspace is a separate Files surface. CSV, TSV, JSON/NDJSON, and Parquet files are not attached as catalog sources.

#Attach

Use the focused convenience methods:

sqlite = await agent.attach_sqlite(
    "/absolute/path/sales.db",
    name="Sales",
)
 
postgres = await agent.attach_postgresql(
    host="db.example.com",
    database="analytics",
    username="daita_agent",
    credential=credential,
    schemas=("public", "reporting"),
    ssl_mode="verify-full",
    name="Analytics",
)

or pass a public source record to agent.attach(...). SourceRegistration contains the stable source ID, adapter identity, display name, admitted non-secret configuration, lifecycle timestamps, and active status.

PostgreSQL attachment begins with read access and no update access. Enabling the narrow update capability is a separate permissioned operation.

#Select and Scope

sources = await agent.list_sources()
selected = await agent.select_source("Sales")
active = await agent.active_source()
 
result = await agent.run(
    "Summarize last month's revenue",
    source_id=selected.id,
)

Selectors accept an active source ID, display name, or unambiguous display-name alias. A new conversation can pin one source independently of the persistent default. An existing conversation cannot silently switch to a conflicting source.

#Source Permissions

Read authority exists in a dedicated SourceReadScope, not in connection JSON. Each active source uses one of three modes:

Inspect, preview, and atomically apply an exact state:

inspection = await agent.inspect_source_permissions(source.id)
 
preview = await agent.preview_source_permissions(
    source_id=source.id,
    read_mode="selected",
    read_resource_ids=(resource_id,),
    postgresql_update_scopes={},
)
 
# Present preview.summary to the operator before applying.
updated = await agent.apply_source_permissions(
    source_id=source.id,
    confirmation_fingerprint=preview.confirmation_fingerprint,
)

The preview is in-process, revision-bound, and exact. Catalog or permission drift requires a fresh preview. PostgreSQL update scopes use the same control plane and may automatically add the read access required for preview and revalidation.

In the terminal, /source permissions provides the guided flow for both read and PostgreSQL update scopes.

#Refresh and Edit

registration = await agent.refresh_source(selected.id)

Refresh reopens the persisted admitted configuration, rediscovers structure, and replaces the current catalog snapshot only after successful discovery. Existing permissions remain exact; future tables are not automatically write-enabled.

Source editing validates and catalogs the proposed replacement before a redacted confirmation and atomic handoff. If validation or confirmation fails, the working connection remains active. Matching read intent is preserved, PostgreSQL update scopes are cleared, and the next question starts a new conversation.

Use /source edit in the terminal or the public edit_sqlite_source(), edit_postgresql_source(), and edit_source() methods with a confirmation handler.

#Detach

detached = await agent.detach(selected.id)

Detachment revokes read and update scopes and disables future access. It never changes source data or database grants. A Daita-owned PostgreSQL credential is deleted; the non-secret inactive registration remains as lifecycle history until the agent is deleted.

Headless automation must confirm detachment:

daita detach atlas <source-id> --yes

Continue with Catalog, Querying, and PostgreSQL Updates.