PostgreSQL

#Credentials

Use a dedicated least-privileged database role and an explicit secret reference:

from daita.security import SecretReference
 
credential = SecretReference.environment("DAITA_POSTGRES_PASSWORD")

The password is resolved only at the connection boundary. It is never persisted in source configuration. Use a read-only role unless you deliberately enable the narrow structured update capability.

#Probe Schemas

Applications can inspect available non-system schemas before attachment:

probe = await agent.probe_postgresql(
    host="db.example.com",
    database="analytics",
    username="daita_agent",
    credential=credential,
    ssl_mode="verify-full",
)
 
for schema in probe.schemas:
    print(schema.name, schema.has_base_tables)

The probe is bounded and does not persist a source registration.

#Attach

source = await agent.attach_postgresql(
    host="db.example.com",
    database="analytics",
    username="daita_agent",
    credential=credential,
    schemas=("public", "reporting"),
    port=5432,
    ssl_mode="verify-full",
    name="Analytics",
)

Equivalent source-record form:

from daita import PostgreSQLSource
 
source = await agent.attach(
    PostgreSQLSource(
        host="db.example.com",
        database="analytics",
        username="daita_agent",
        credential=credential,
        schemas=("public", "reporting"),
        ssl_mode="verify-full",
        name="Analytics",
    )
)

Supported SSL modes are disable, prefer, allow, require, verify-ca, and verify-full. Attachment grants read scope and zero Daita update scopes.

#Discovery and Permissions

Daita catalogs base tables, columns, supported types, indexes, primary keys, and foreign-key relationships from only the selected schemas. PostgreSQL system schemas are excluded.

Use /source permissions to choose all, selected, or no readable current resources and to enable exact eligible update tables and assignment columns. The Python control plane is inspect_source_permissions(), preview_source_permissions(), and apply_source_permissions().

Connection JSON does not grant read or write authority. Future tables are never automatically update-enabled, and changing the connection clears every update scope.

#Read Boundary

data_query_postgresql runs one validated statement inside a read-only transaction with a bounded timeout. Daita:

1. validates SQL against current catalog facts and source permissions;
2. reconnects through the admitted non-secret registration;
3. rechecks live structure;
4. applies row and byte bounds;
5. rolls back the read-only transaction; and
6. returns a JSON-safe result with exact provenance.

Only a bounded set of functions and supported PostgreSQL types is accepted. Server functions capable of external I/O are outside the read surface.

data_export_postgresql uses the same current SQL and catalog validation, then streams an exact CSV or XLSX artifact rather than returning a partial model projection.

#Edit the Connection

/source edit validates and catalogs a replacement, shows a redacted confirmation, and commits one atomic handoff. A failed edit leaves the existing connection active. Matching read intent is preserved, update scopes are cleared, and a new conversation starts.

Python callers can use edit_postgresql_source() with a confirmation_handler.

#Headless Attachment

daita --workspace /absolute/path/project attach atlas postgresql \
  --host db.example.com \
  --database analytics \
  --username daita_agent \
  --password-env DAITA_POSTGRES_PASSWORD \
  --schema public \
  --schema reporting \
  --ssl-mode verify-full \
  --source-name Analytics