---
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").

<Callout type="info">
**Source:** `packages/spec/src/data/datasource.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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 |
| **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`


---

