Aurora DSQLストレージ

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

Aurora DSQLは、pgvectorを含むPostgreSQL拡張機能（CREATE EXTENSION）をサポートしていません。ベクトルストレージには、@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'という名前のデータベースを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は、次の方法でインスタンス化できます。

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()が自動で呼び出されます。

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

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クラスターのエンドポイントを指定してください。

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機能
• サポートされるデータ型
• 非同期インデックス