Aurora DSQL 스토리지

Aurora DSQL 스토리지 구현은 IAM 인증과 함께 Amazon Aurora DSQL을 사용하는 스토리지를 제공합니다.

Aurora DSQL은 PostgreSQL 확장 기능(CREATE EXTENSION), including pgvector. 벡터 저장의 경우 다음과 같은 별도의 벡터 저장소를 사용하십시오.@mastra/s3vectors.

설치

npm install @mastra/dsql@beta

전제조건

• Amazon Aurora DSQL 클러스터
• DSQL 클러스터에 대한 액세스 권한이 있는 AWS 자격 증명(IAM 인증)

용법

import { DSQLStore } from '@mastra/dsql'

const storage = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
  // region is auto-detected from host, or specify explicitly:
  // region: 'us-east-1',
  // user: 'admin', // default
  // database: 'postgres', // default
})

// Initialize the store (creates tables if needed)
await storage.init()

매개변수

id:

string

이 스토어 인스턴스의 고유 식별자

host:

string

DSQL 클러스터 엔드포인트(예: abc123.dsql.us-east-1.on.aws)

pool?:

pg.Pool

미리 구성된 pg.Pool 인스턴스입니다. 연결 풀을 직접 제어하려면 사용하세요. host 구성과 함께 사용할 수 없습니다.

user?:

string

데이터베이스 사용자입니다. Aurora DSQL의 관리자 역할은 'admin'입니다.

database?:

string

데이터베이스 이름입니다. Aurora DSQL은 클러스터마다 'postgres'라는 단일 데이터베이스를 제공합니다.

region?:

string

AWS 리전입니다. 제공하지 않으면 host에서 추출합니다.

schemaName?:

string

Mastra 테이블과 인덱스가 생성되는 PostgreSQL 스키마 이름입니다.

customCredentialsProvider?:

AwsCredentialIdentityProvider

IAM 인증을 위한 사용자 지정 AWS 자격 증명 Provider입니다.

max?:

number

풀의 최대 연결 수입니다.

min?:

number

풀의 최소 연결 수입니다.

idleTimeoutMillis?:

number

유휴 연결을 이 시간(밀리초)이 지나면 닫습니다.

maxLifetimeSeconds?:

number

최대 연결 수명(초)입니다. Aurora DSQL의 60분 연결 제한으로 인해 3600보다 작아야 합니다.

connectionTimeoutMillis?:

number

연결 획득 제한 시간(밀리초)입니다.

allowExitOnIdle?:

boolean

모든 연결이 유휴 상태일 때 프로세스가 종료되도록 허용합니다.

생성자 예

다음과 같은 방법으로 DSQLStore를 인스턴스화할 수 있습니다.

import { DSQLStore } from '@mastra/dsql'

// Basic configuration (region auto-detected from host)
const store1 = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
})

// With explicit region and schema
const store2 = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
  region: 'us-east-1',
  schemaName: 'my_app',
})

// With custom credentials provider
import { fromNodeProviderChain } from '@aws-sdk/credential-providers'

const store3 = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
  customCredentialsProvider: fromNodeProviderChain(),
})

// With connection pool settings
const store4 = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
  max: 20,
  min: 2,
  idleTimeoutMillis: 300000,
  maxLifetimeSeconds: 3000,
  connectionTimeoutMillis: 10000,
})

// Using a pre-configured pg.Pool
import { Pool } from 'pg'
import { AuroraDSQLClient } from '@aws/aurora-dsql-node-postgres-connector'

const pool = new Pool({
  host: 'abc123.dsql.us-east-1.on.aws',
  Client: AuroraDSQLClient,
  region: 'us-east-1',
})

const store5 = new DSQLStore({
  id: 'my-dsql-store',
  pool,
})

추가 참고사항

스키마 관리

저장소 구현은 스키마 생성 및 업데이트를 자동으로 처리합니다. 다음 테이블이 생성됩니다.

• mastra_workflow_snapshot: Workflow 상태 및 실행 데이터를 저장합니다.
• mastra_threads: 대화 스레드를 저장합니다.
• mastra_messages: 개별 메시지를 저장합니다.
• mastra_ai_spans: Observability을 위해 범위 데이터를 저장합니다.
• mastra_scorers: 점수 및 평가 데이터를 저장합니다.
• mastra_resources: 자원 작업 Memory 데이터를 저장합니다.
• mastra_agents: Agent 데이터를 저장합니다.

초기화

스토리지를 Mastra 클래스에 전달하면 스토리지 작업 전에 init()이 자동으로 호출됩니다.

import { Mastra } from '@mastra/core'
import { DSQLStore } from '@mastra/dsql'

const storage = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
})

const mastra = new Mastra({
  storage, // init() is called automatically
})

Mastra 없이 스토어를 직접 사용하는 경우 테이블을 생성하려면 init()을 명시적으로 호출해야 합니다.

import { DSQLStore } from '@mastra/dsql'

const storage = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
})

// Required when using storage directly
await storage.init()

// Access domain-specific stores via getStore()
const memoryStore = await storage.getStore('memory')
const thread = await memoryStore?.getThreadById({ threadId: '...' })

경고

init()을 호출하지 않으면 테이블이 생성되지 않으며 스토리지 작업이 아무 알림 없이 실패하거나 오류를 발생시킵니다.

직접 데이터베이스 및 풀 액세스

DSQLStore기본 데이터베이스 클라이언트와 pg.Pool 인스턴스를 모두 공개 필드로 노출합니다.

storage.db // Database client for executing queries
storage.pool // Underlying pg.Pool instance

직접 쿼리 및 사용자 정의 트랜잭션 관리를 지원합니다. 다음 필드를 사용하는 경우:

• 적절한 연결 및 트랜잭션 처리는 사용자의 책임입니다.
• 스토어를 닫으면(storage.close()) 스토어가 생성한 연결 풀이 제거됩니다.
• 직접 액세스하면 DSQLStore 메서드가 제공하는 추가 로직이나 유효성 검사를 우회합니다. 이 접근 방식은 낮은 수준의 액세스가 필요한 고급 시나리오를 위한 것입니다.

Aurora DSQL 세부 사항

IAM 전용 인증

연결은 IAM으로 인증되므로 데이터베이스 비밀번호가 필요하지 않습니다. @mastra/dsql은 @aws/aurora-dsql-node-postgres-connector를 사용하여 수명이 짧은 인증 토큰을 생성합니다. customCredentialsProvider를 통해 사용자 지정 자격 증명 Provider를 제공할 수 있습니다.

단일 데이터베이스, 스키마 기반 격리

각 클러스터는 postgres라는 단일 데이터베이스를 제공합니다. 논리적 분리는 스키마를 통해 이루어집니다. schemaName 옵션은 Mastra 테이블이 생성될 위치를 제어합니다.

PostgreSQL 확장 없음

CREATE EXTENSION은 지원되지 않습니다. 여기에는 pgvector, PostGIS 등이 포함됩니다. 벡터 스토리지에는 DSQLStore와 함께 @mastra/s3vectors 같은 별도의 스토어를 사용하세요.

JSON이 텍스트로 저장됨

JSON/JSONB는 쿼리 유형으로 사용할 수 있지만 열 유형으로는 사용할 수 없습니다. @mastra/dsql은 구조화된 필드(메타데이터, 콘텐츠 등)를 TEXT 열에 저장하고 쿼리 시점에 JSON으로 캐스팅합니다.

스키마 및 DDL 제약조건

일부 PostgreSQL 기능은 사용할 수 없습니다.

• 외래 키 제약조건
• TRUNCATE
• 동기식CREATE INDEX

인덱스는 CREATE INDEX ASYNC를 사용하여 비동기식으로 생성됩니다. 스토어의 init() 및 인덱스 도우미 API는 이러한 제약 조건을 준수합니다.

트랜잭션 및 낙관적 동시성

Aurora DSQL은 낙관적 동시성 제어(OCC)를 사용하며 경합이 있는 경우 재시도 가능한 OCC 오류를 반환할 수 있습니다. 거래 기간과 규모에 제한이 있습니다. 대규모 대량 작업은 애플리케이션 수준에서 더 작은 배치로 분할되어야 합니다.

연결 수명

개별 연결은 약 60분으로 제한됩니다. 기본값 maxLifetimeSeconds: 3300을 사용하면 이 제한에 도달하기 전에 연결이 재활용됩니다.

사용예

Agent에 Memory 추가

Agent에 Aurora DSQL Memory를 추가하려면 Memory 클래스를 사용하고 DSQLStore를 사용하는 새 storage 키를 생성하세요. host는 Aurora DSQL 클러스터 엔드포인트를 가리켜야 합니다.

src/mastra/agents/example-dsql-agent.ts

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { DSQLStore } from '@mastra/dsql'

export const dsqlAgent = new Agent({
  id: 'dsql-agent',
  name: 'DSQL Agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new DSQLStore({
      id: 'dsql-agent-storage',
      host: process.env.DSQL_HOST!,
    }),
    options: {
      generateTitle: true, // Explicitly enable automatic title generation
    },
  }),
})

Agent 사용

memoryOptions를 사용하여 이 요청의 회상 범위를 지정하세요. lastMessages: 5를 설정하여 최신 메시지 기반 회상을 제한하고, semanticRecall을 사용하여 가장 관련성이 높은 topK: 3개의 메시지를 가져오세요. 각 일치 항목 주변의 컨텍스트를 제공하도록 인접 메시지 messageRange: 2개도 포함됩니다.

src/test-dsql-agent.ts

import 'dotenv/config'

import { mastra } from './mastra'

const threadId = '123'
const resourceId = 'user-456'

const agent = mastra.getAgent('dsql-agent')

const message = await agent.stream('My name is Mastra', {
  memory: {
    thread: threadId,
    resource: resourceId,
  },
})

await message.textStream.pipeTo(new WritableStream())

const stream = await agent.stream("What's my name?", {
  memory: {
    thread: threadId,
    resource: resourceId,
  },
  memoryOptions: {
    lastMessages: 5,
    semanticRecall: {
      topK: 3,
      messageRange: 2,
    },
  },
})

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}

인덱스 관리

Aurora DSQL 스토리지는 쿼리 성능을 최적화하는 인덱스 관리 기능을 제공합니다.

자동 성과 지표

Aurora DSQL 스토리지는 일반적인 쿼리 패턴에 대해 초기화 중에 복합 인덱스를 자동으로 생성합니다.

• mastra_threads_resourceid_createdat_idx: (resourceId, createdAt)
• mastra_messages_thread_id_createdat_idx: (thread_id, createdAt)
• mastra_ai_spans_traceid_startedat_idx: (traceId, startedAt)
• mastra_ai_spans_parentspanid_startedat_idx: (parentSpanId, startedAt)
• mastra_ai_spans_name_idx: (name)
• mastra_ai_spans_spantype_startedat_idx: (spanType, startedAt)
• mastra_scores_trace_id_span_id_created_at_idx: (traceId,spanId,createdAt) Aurora DSQL은 CREATE INDEX ASYNC를 사용하여 이러한 인덱스를 비동기식으로 생성합니다. 인덱스 생성이 비동기식이므로 init() 직후에는 새 인덱스를 사용하지 못할 수 있습니다. 인덱스가 없어도 스토어는 계속 작동하지만, 인덱스 생성이 완료될 때까지 쿼리가 느려질 수 있습니다.

사용자 정의 색인 생성

특정 쿼리 패턴을 최적화하기 위해 추가 인덱스를 만듭니다.

await storage.createIndex({
  name: 'idx_threads_resource',
  table: 'mastra_threads',
  columns: ['resourceId'],
})

await storage.createIndex({
  name: 'idx_messages_composite',
  table: 'mastra_messages',
  columns: ['thread_id', 'createdAt'],
})

Aurora DSQL은 CREATE INDEX ASYNC에서 ASC/DESC를 허용하지 않습니다. 이를 포함하면 자동으로 제거됩니다.

인덱스 옵션

name:

string

인덱스의 고유 이름

table:

string

테이블 이름(예: 'mastra_threads')

columns:

string[]

열 이름 배열입니다. Aurora DSQL 호환성을 위해 ASC/DESC 수정자는 자동으로 제거됩니다.

unique?:

boolean

고유 인덱스를 생성합니다.

concurrent?:

boolean

Aurora DSQL에서는 무시됩니다. 인덱스는 항상 비동기식으로 생성됩니다.

where?:

string

부분 인덱스 조건입니다.

method?:

string

Aurora DSQL에서는 무시됩니다. btree 인덱스만 지원됩니다.

opclass?:

string

Aurora DSQL에서는 무시됩니다.

storage?:

Record<string, any>

Aurora DSQL에서는 무시됩니다.

tablespace?:

string

Aurora DSQL에서는 무시됩니다. 테이블스페이스는 지원되지 않습니다.

인덱스 관리

기존 인덱스를 나열하고 모니터링합니다.

// List all indexes
const allIndexes = await storage.listIndexes()
console.log(allIndexes)
// [
//   {
//     name: 'mastra_threads_pkey',
//     table: 'mastra_threads',
//     columns: ['id'],
//     unique: true,
//     size: '16 KB',
//     definition: 'CREATE UNIQUE INDEX...'
//   },
//   ...
// ]

// List indexes for a specific table
const threadIndexes = await storage.listIndexes('mastra_threads')

// Get detailed statistics for an index
const stats = await storage.describeIndex('idx_threads_resource')
console.log(stats)
// {
//   name: 'idx_threads_resource',
//   table: 'mastra_threads',
//   columns: ['resourceId'],
//   unique: false,
//   size: '128 KB',
//   definition: 'CREATE INDEX idx_threads_resource...',
//   method: 'btree',
//   scans: 1542,
//   tuples_read: 45230,
//   tuples_fetched: 12050
// }

// Drop an index
await storage.dropIndex('idx_threads_status')

스키마별 인덱스

사용자 정의 스키마를 사용하면 스키마 접두사를 사용하여 인덱스가 생성됩니다.

const storage = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
  schemaName: 'custom_schema',
})

// Creates index as: custom_schema_idx_threads_status
await storage.createIndex({
  name: 'idx_threads_status',
  table: 'mastra_threads',
  columns: ['status'],
})

관련 자료

• Aurora DSQL 설명서
• SQL 참조
• 지원되는 SQL 기능
• 지원되지 않는 PostgreSQL 기능
• 지원되는 데이터 유형
• 비동기 인덱스