데이터 소스

datasource는 외부 데이터 저장소에 대한 이름이 지정된 연결입니다. 데이터 소스를 선언함으로써 ObjectOS를 비즈니스가 이미 운영 중인 데이터베이스 — 프로덕션 PostgreSQL, 리포팅용 MySQL 복제본, MongoDB 클러스터 — 로 지정한 다음, 객체를 거기에 바인딩합니다. 객체가 일단 바인딩되면 플랫폼의 나머지 모든 것(REST/GraphQL API, 권한, 플로우, 대시보드, 그리고 AI 에이전트)이 행이 물리적으로 어디에 있는지 신경 쓰지 않고 해당 데이터에 대해 균일하게 동작합니다.

이것은 ObjectOS의 가장 실용적인 도입 경로 중 하나입니다: 레거시 시스템을 마이그레이션하는 대신, 거기에 연결하고, 관심 있는 테이블을 객체로 모델링한 다음, 데이터를 있는 그대로 두면서 그 위에 AI 네이티브 기능 — 채팅, 분석, 자동화 — 으로 확장합니다.

데이터 소스란

각 데이터 소스는 DatasourceSchema로 검증되는 평범한 객체입니다. 핵심 필드는 다음과 같습니다:

기본 제공되는 드라이버는 다음과 같습니다:

데이터 소스 선언하기

데이터 소스는 스택에 선언되며 defineStack으로 조립됩니다. 각 연결을 타입이 지정된 Datasource 객체로 정의한 다음, datasources 아래에 나열하세요:

// src/datasources/business.datasource.ts
import type { Datasource } from '@objectstack/spec';

// 기존 프로덕션 데이터베이스에 연결합니다. 자격 증명은 환경에서
// 가져옵니다 — 소스에 비밀 값을 인라인으로 넣지 마세요.
export const BusinessDb: Datasource = {
  name: 'business_primary',
  label: 'Business System (Postgres)',
  driver: 'postgres',
  config: {
    connection: {
      host: process.env.BIZ_DB_HOST,
      port: Number(process.env.BIZ_DB_PORT ?? 5432),
      user: process.env.BIZ_DB_USER,
      password: process.env.BIZ_DB_PASSWORD,
      database: process.env.BIZ_DB_NAME,
    },
  },
  pool: { min: 1, max: 10 },
  active: true,
};

// objectstack.config.ts
import { defineStack } from '@objectstack/spec';
import * as objects from './src/objects/index.js';
import { BusinessDb } from './src/datasources/business.datasource.js';

export default defineStack({
  manifest: { id: 'app.example.crm-extend', namespace: 'biz', version: '1.0.0' },
  datasources: [BusinessDb],
  objects: Object.values(objects),
});

defineDatasource() 헬퍼는 없습니다. 데이터 소스는 datasources 배열에 넣는 Datasource 객체일 뿐입니다 — 프레임워크 저장소의 examples/app-crm 스택이 하는 것과 정확히 동일합니다.

객체를 데이터 소스에 바인딩하기

모든 객체에는 datasource 필드가 있습니다. 기본값은 'default'(기본 데이터베이스)입니다. 특정 객체를 연결된 시스템 중 하나로 라우팅하려면 이 값을 설정하세요:

import { ObjectSchema, Field } from '@objectstack/spec/data';

export const Customer = ObjectSchema.create({
  name: 'biz_customer',
  label: 'Customer',
  datasource: 'business_primary', // ← 읽기/쓰기가 비즈니스 DB로 전달됨
  fields: {
    name:  Field.text({ label: 'Name', required: true }),
    email: Field.text({ label: 'Email' }),
    tier:  Field.select({ label: 'Tier', options: [/* … */] }),
  },
});

datasourceMapping을 사용한 중앙 집중식 라우팅

객체를 하나씩 바인딩하는 것은 소수일 때는 괜찮습니다. 네임스페이스나 패키지 전체에 대해서는 스택에 라우팅 규칙을 한 번 선언하세요. 규칙은 순서대로(또는 priority에 따라) 평가되며, 첫 번째 일치가 우선합니다:

export default defineStack({
  datasources: [BusinessDb, AnalyticsReplica],
  datasourceMapping: [
    { namespace: 'biz',            datasource: 'business_primary' },
    { objectPattern: 'report_*',   datasource: 'analytics_replica' },
    { package: 'com.example.logs', datasource: 'business_primary' },
    { default: true,               datasource: 'default' },
  ],
});

규칙은 namespace, package, objectPattern(glob), 또는 default로 일치하며, 대상 datasource를 지정합니다. 이렇게 하면 데이터 거주(data-residency) 결정이 객체 파일 전반에 흩어지는 대신 한곳에 모입니다.

기존 테이블에서 객체 생성하기

모든 테이블에 대해 객체를 손으로 작성할 필요는 없습니다. 오늘날 레거시 스키마를 ObjectOS로 가져오는 가장 빠른 방법은 코딩 에이전트(Claude Code)를 사용하여 비즈니스 테이블을 스캔하고 소스 수준의 객체 정의를 생성하는 것입니다 — 테이블당 하나의 *.object.ts 파일로, 프레임워크가 기대하는 형태 그대로입니다.

hotcrm 레퍼런스 앱이 그 형태의 표준 예시입니다: 각 테이블은 Field.* 정의와 함께 ObjectSchema.create({ … })를 사용하는 src/objects/<name>.object.ts 파일이며, 모두 defineStack으로 조립됩니다. 일반적인 흐름은 다음과 같습니다:

1. 비즈니스 데이터베이스를 데이터 소스로 연결합니다(위 참조).
2. Claude Code를 스키마로 지정합니다. 연결된 데이터베이스 — 테이블 이름, 컬럼, 타입, 외래 키 — 를 인트로스펙션하고, SQL 컬럼을 Field.* 타입에 매핑하고 외래 키를 Field.lookup(...)에 매핑하여 테이블당 하나의 ObjectSchema.create 파일을 생성하도록 요청하세요. 각 객체의 datasource를 연결로 설정하거나(또는 datasourceMapping에 의존하세요).
3. 생성된 객체를 검토하고 다듬습니다 — 레이블, 필드 그룹, 검증, 권한을 추가하세요. 출력은 hotcrm/src/objects/*.object.ts와 마찬가지로 여러분이 소유하고 커밋하는 일반적인 소스입니다.
4. 실행합니다. 이제 객체는 바인딩된 데이터 소스를 통해 기존 테이블을 읽고 씁니다.

생성된 객체가 평범한 소스이기 때문에 완전한 제어권을 갖습니다: 맞는 것은 유지하고, 노출하고 싶지 않은 컬럼은 버리고, 플랫폼이 소유할 필요가 전혀 없었던 데이터베이스 위에 ObjectOS 기능(이력 추적, 활동, 공유 규칙)을 계층화하세요.

기능 인식 쿼리 푸시다운

각 데이터 소스는 DatasourceCapabilities를 알립니다 — 필터, 정렬, 페이지네이션, 집계, 조인, 전문(full-text) 검색, 트랜잭션 등을 처리할 수 있는지 여부입니다. ObjectQL은 이를 사용하여 데이터베이스에 푸시다운할 것과 메모리에서 평가할 것을 결정합니다:

기능이 풍부한 SQL 데이터 소스는 거의 모든 것을 푸시다운합니다. 제한적이거나 읽기 전용인 소스는 동일한 쿼리 결과를 얻지만, 더 많은 작업이 엔진에서 수행됩니다. 드라이버 기본값보다 더 잘 알고 있을 때는 capabilities 필드를 통해 데이터 소스별로 알려진 기능 집합을 재정의할 수 있습니다.

연결된 데이터에 대한 AI

테이블이 일단 객체로 모델링되면 AI 계층이 무료로 그 위에서 동작합니다. ObjectOS의 에이전트와 도구 — list_objects, describe_object, query_records, aggregate_data, 그리고 데이터 채팅 에이전트 — 는 모두 ObjectQL을 거치며, ObjectQL은 각 객체를 바인딩된 데이터 소스로 라우팅합니다. 이것이 의미하는 바는:

• 사용자가 레거시 비즈니스 시스템에 있는 데이터에 대해 자연어로 질문할 수 있고, 답은 실제 행에 대해 계산됩니다.
• 도구 호출과 쿼리는 호출하는 사용자의 권한을 존중합니다 — AI는 로그인한 사용자에게 허용된 것보다 더 많이 보지 못합니다.
• 동일한 에이전트, 플로우, 대시보드가 객체가 기본 데이터베이스에 의해 뒷받침되든 외부 비즈니스 시스템에 의해 뒷받침되든 동작합니다.

채팅 및 에이전트 계층을 연결하는 방법은 AI 서비스와 AI Agents를 참고하고, default 데이터 소스를 뒷받침하는 기본 데이터베이스 구성은 Runtime을 참고하세요.

보안 참고 사항

• 자격 증명을 인라인으로 넣지 마세요. 위에서 보여준 것처럼 host/user/password를 환경 변수(또는 시크릿 매니저)에서 가져오세요.
• 쓸 의도가 없는 시스템에는 읽기 전용 연결을 사용하세요 — 소스의 readOnly 기능(또는 읽기 전용 DB 사용자)을 설정하여 우발적인 쓰기가 프로덕션에 도달하지 못하게 하세요.
• 권한으로 범위를 지정하세요. 객체 및 필드 수준 권한은 네이티브 객체에 적용되는 것과 정확히 동일하게 연결된 데이터에 적용됩니다.

로드맵: 제품 내 외부 데이터 소스 페더레이션

위의 흐름 — 데이터베이스 연결, 객체 모델링, 코딩 에이전트로 생성 — 은 기본 제공 빌딩 블록으로 오늘날 동작합니다. 더 풍부한 턴키(turn-key) 페더레이션 경험이 ADR-0015(상태: Proposed) 아래에서 활발히 설계되고 있습니다. 계획되어 있지만 아직 출시되지 않은 것들:

• ObjectOS가 소유하지 않은 테이블을 마이그레이션하려 시도하지 않고 바인딩할 수 있도록 하는 schemaMode(managed / external / validate-only).
• 객체 필드를 기존 컬럼에 매핑하는 객체의 external 바인딩 하위 레코드.
• 한 단계로 스키마를 가져오고 객체를 스캐폴딩하는 os datasource introspect / validate CLI.
• 외부 소유 스키마에 대한 부팅 시점 및 쓰기 시점 안전 게이트, 그리고 전체 흐름을 위한 Studio 마법사.

이것들이 출시되기 전까지는 문서화된 경로를 선호하세요: 데이터 소스를 선언하고, 객체를 바인딩하고(생성된 것이든 손으로 작성한 것이든), 먼저 비프로덕션 사본에 대해 검증하세요.

다음으로 갈 곳

• Runtime — default 뒤에 있는 기본 데이터베이스
• AI 서비스 — 채팅, 임베딩, RAG, MCP
• AI Agents — 객체에 대한 선언적 에이전트
• Objects — ObjectSchema.create 작성 인터페이스
• examples/app-crm 데이터 소스 — 실제 데이터 소스 + 라우팅 예제