datasource.mdx

title	Datasource
description	Datasource protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Driver Identifier

Can be a built-in driver or a plugin-contributed driver (e.g., "com.vendor.snowflake").

**Source:** `packages/spec/src/data/datasource.zod.ts`

TypeScript Usage

import { Datasource, DatasourceCapabilities, DriverDefinition, DriverType, ExternalDatasourceSettings, ModeSchema } from '@objectstack/spec/data';
import type { Datasource, DatasourceCapabilities, DriverDefinition, DriverType, ExternalDatasourceSettings, Mode } from '@objectstack/spec/data';

// Validate data
const result = Datasource.parse(data);

---

Datasource

Properties

Property	Type	Required	Description
name	string	✅	Unique datasource identifier
label	string	optional	Display label
driver	string	✅	Underlying driver type
config	Record<string, any>	✅	Driver specific configuration
pool	Object	optional	Connection pool settings
readReplicas	Record<string, any>[]	optional	Read-only replica configurations
capabilities	Object	optional	Capability overrides
healthCheck	Object	optional	Datasource health check configuration
ssl	Object	optional	SSL/TLS configuration for secure database connections
retryPolicy	Object	optional	Connection retry policy for transient failures
description	string	optional	Internal description
active	boolean	✅	Is datasource enabled
autoConnect	boolean	✅	Force a live driver connection at boot even when managed + unrouted (ADR-0062 D2).
schemaMode	Enum<'managed' | 'external' | 'validate-only'>	✅	Schema ownership mode
external	Object	optional	External datasource federation settings (schemaMode != "managed")
origin	Enum<'code' | 'runtime'>	✅	Datasource provenance (server-managed, read-only)

---

DatasourceCapabilities

Properties

Property	Type	Required	Description
transactions	boolean	✅
queryFilters	boolean	✅
queryAggregations	boolean	✅
querySorting	boolean	✅
queryPagination	boolean	✅
queryWindowFunctions	boolean	✅
querySubqueries	boolean	✅
joins	boolean	✅
fullTextSearch	boolean	✅
readOnly	boolean	✅
dynamicSchema	boolean	✅

---

DriverDefinition

Properties

Property	Type	Required	Description
id	string	✅	Unique driver identifier (e.g. "postgres")
label	string	✅	Display label (e.g. "PostgreSQL")
description	string	optional
icon	string	optional
configSchema	Record<string, any>	✅	JSON Schema for connection configuration
capabilities	Object	optional

---

---

ExternalDatasourceSettings

External datasource federation settings (schemaMode != "managed")

Properties

Property	Type	Required	Description
label	string	optional	Display label, e.g. "Snowflake — ANALYTICS / PROD"
allowedSchemas	string[]	optional	Whitelist of remote schemas/databases that may be exposed.
allowWrites	boolean	✅	Global write gate. Individual objects must also opt in via object.external.writable.
validation	Object	✅	Boot/drift validation policy
credentialsRef	string	optional	Reference into the secrets store; never inline credentials.
queryTimeoutMs	number	✅	Hard cap on per-query execution time.
requirePermission	string	optional	Optional convenience: gate the entire datasource behind a single role.

---

ModeSchema

Schema ownership mode

Allowed Values

• managed
• external
• validate-only

---