> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# Aurora DSQLストレージ

Aurora DSQLストレージ実装は、IAM認証を使用するAmazon Aurora DSQLストレージを提供します。

Aurora DSQLは、`pgvector`を含むPostgreSQL拡張機能（`CREATE EXTENSION`）をサポートしていません。ベクトルストレージには、`@mastra/s3vectors`などの独立したベクトルストアを使用してください。

## インストール

```bash
npm install @mastra/dsql@beta
```

## 前提条件

- Amazon Aurora DSQLクラスター
- DSQLクラスターにアクセスできるAWS認証情報（IAM認証）

## 使用方法

```typescript
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'という名前のデータベースを1つ公開します。

**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`は、次の方法でインスタンス化できます。

```typescript
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`: 会話Threadを保存
- `mastra_messages`: 個々のメッセージを保存
- `mastra_ai_spans`: Observability用のspanデータを保存
- `mastra_scorers`: スコアリングと評価のデータを保存
- `mastra_resources`: リソースのワーキングメモリデータを保存
- `mastra_agents`: Agentデータを保存

### 初期化

ストレージをMastraクラスに渡すと、ストレージ操作の前に`init()`が自動で呼び出されます。

```typescript
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()`を明示的に呼び出す必要があります。

```typescript
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インスタンスの両方をpublicフィールドとして公開します。

```typescript
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`の1つだけです。論理的な分離にはスキーマを使用します。Mastraのテーブルを作成する場所は`schemaName`オプションで制御します。

#### 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にメモリを追加する

AgentにAurora DSQLメモリを追加するには、`Memory`クラスを使用し、`DSQLStore`で新しい`storage`キーを作成します。`host`にはAurora DSQLクラスターのエンドポイントを指定してください。

```typescript
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`件のメッセージも含まれます。

```typescript
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()`の直後には新しいインデックスを利用できない場合があります。インデックスがなくてもストアは動作し続けますが、作成が完了するまではクエリが遅くなる可能性があります。

### カスタムインデックスを作成する

特定のクエリパターンを最適化するには、追加のインデックスを作成します。

```typescript
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では無視されます。テーブルスペースはサポートされていません。

### インデックスを管理する

既存のインデックスを一覧表示し、監視します。

```typescript
// 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')
```

### スキーマ固有のインデックス

カスタムスキーマを使用すると、スキーマのプレフィックス付きでインデックスが作成されます。

```typescript
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ドキュメント](https://docs.aws.amazon.com/aurora-dsql/)
- [SQLリファレンス](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-aurora-dsql-sql.html)
- [サポートされるSQL機能](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-supported-sql-features.html)
- [サポートされないPostgreSQL機能](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-unsupported-features.html)
- [サポートされるデータ型](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-supported-data-types.html)
- [非同期インデックス](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-create-index-async.html)