호스팅된 데이터베이스

CLI에서 완전관리형 데이터베이스를 프로비저닝하거나platform프로젝트 설정을 선택하고 프로젝트에 첨부하세요. Mastra는 공급자를 통해 이를 생성하고 자격 증명을 안전하게 저장하며, 데이터베이스가 준비되면 연결 세부 정보를 런타임 환경 변수로 주입하므로 복사하거나 구성할 연결 문자열이 없습니다.

mastra env db create --kind turso

호스팅된 데이터베이스를 사용하는 경우

프로젝트에 다음을 포함하여 플랫폼에서 관리하는 내구성 있는 스토리지가 필요한 경우 호스팅된 데이터베이스를 사용하세요.

• Agent Memory: 세션 전반에 걸쳐 대화 기록 및 작업 기억과 의미적 회상을 유지합니다.
• 애플리케이션 데이터: 런타임 시 프로젝트에 필요한 관계형 또는 구조화된 데이터를 저장하고 검색합니다.
• 벡터 검색: 검색 증강 생성 및 의미 검색을 위한 임베딩을 저장합니다.

공급자

호스팅된 데이터베이스는 현재 Turso와 Postgres라는 두 공급자를 통해 제공되며 MongoDB는 곧 출시될 예정입니다. 데이터베이스를 연결할 때 하나를 선택한 다음, 주입된 변수를 코드의 일치하는 Mastra 스토리지 어댑터에 연결하세요.

각 공급자는 고정된 변수 이름 세트를 주입합니다.DATABASE_URL for Postgres and separate TURSO_* variables는 Turso용입니다. 이러한 이름은 각 environment 내에서 고유해야 하므로 environment당 Provider별로 최대 하나의 database만 사용할 수 있습니다. 서로 다른 workloads에 별도의 stores가 필요하면 Turso와 Postgres를 같은 프로젝트에 연결하세요.

대부분의 Agent 중심 프로젝트의 경우Turso 가 가장 간단한 시작점입니다. Agent Memory, conversation history, tenant별 격리에 적합한 가벼운 SQLite 호환 engine을 제공합니다. 다음을 선택하세요: Postgres workload에 전체 SQL, relational schemas 또는 Mastra runtime 상태를 넘어서는 구조화된 application 데이터가 필요할 때 사용합니다. MongoDB (coming soon)는 SQL에 명확히 매핑되지 않는 workloads를 위해 document storage와 내장 vector search를 추가할 예정입니다.

공급자	엔진
Turso	LibSQL, SQLite-compatible	Agent memory, per-tenant isolation
PostgreSQL	Serverless Postgres	Relational workloads, structured data
MongoDB	Document 및 vector search	Document storage, vector search (coming soon)

데이터베이스 범위

데이터베이스는 다음 두 범위 중 하나에 연결됩니다.

• 환경 범위: 기본값입니다. 단일 환경에 연결되어 데이터가 환경 간에 격리된 상태로 유지됩니다(예: 별도의 프로덕션 및 스테이징 데이터베이스). 프로젝트에 하나의 환경이 있는 경우mastra env db create 하나만 있으면 자동으로 선택하며, 여러 개가 있으면 CLI에서 하나를 선택하라는 Prompt가 표시됩니다.
• 프로젝트 범위: 모든 프로젝트가 공유하는 하나의 데이터베이스environments. Opt in with --shared. Its variables are injected into every deploy.

범위는 데이터베이스를 연결할 때 설정되고 다음과 같이 표시됩니다.mastra env db list.

동일한 공급자에 대해 범위가 겹칠 수 없습니다. 프로젝트 범위 데이터베이스는 이미 모든 환경에 해당 변수를 주입하므로 동일한 공급자의 환경 범위 데이터베이스 연결은 변수 이름 충돌로 인해 거부됩니다. 공유 데이터베이스에서 환경별 데이터베이스로 이동하려면 먼저 프로젝트 범위 데이터베이스를 삭제한 후 환경당 하나의 데이터베이스를 연결하세요. 데이터베이스를 삭제하면 모든 데이터와 함께 공급자와 함께 데이터베이스도 파괴됩니다. 범위를 전환하기 전에 유지해야 하는 모든 것을 내보냅니다. 서로 다른 환경의 환경 범위 데이터베이스는 충돌하지 않으며, 각 배포는 자체 환경에 대한 변수만 수신합니다.

CLI로 연결

이 명령을 미리 실행할 필요는 없습니다. 프로젝트에 호스팅된 데이터베이스가 필요하지만 아직 없는 경우,mastra deploy 는 deploy preflight check가 실행될 때 하나를 연결하도록 제안합니다. 수락하면 CLI를 벗어나지 않고 deploy가 계속됩니다.

또는 미리 데이터베이스를 생성하고 연결하세요. CLI는 준비될 때까지 폴링하며 몇 초 정도 걸립니다.

# Scoped to a single environment (the CLI picks the only one, or prompts if there are several)
mastra env db create --kind turso

# Scoped to a specific environment
mastra env db create staging --kind turso

# Shared by all environments
mastra env db create --kind turso --shared

지원되는 종류는turso and neon (Postgres). Useful flags:

• --shared: 모든 환경에서 공유되는 프로젝트 범위의 데이터베이스를 연결합니다. 환경 인수와 결합할 수 없습니다.
• --name <name>: 데이터베이스 이름. 기본값은 프로젝트 슬러그에서 파생된 이름입니다.
• --region <region>: 프로젝트 범위 데이터베이스의 공급자 지역 ID(예:fra). Environment 범위 databases는 자동으로 해당 environment의 region 근처에 배치되며, 명시적인 --region is ignored.
• --no-wait: 폴링 대신 즉시 반환합니다. 나중에 진행 상황을 확인하세요.mastra env db show.
• --json: 기계가 읽을 수 있는 출력입니다. 프로젝트에 여러 환경이 있는 경우--json requires an environment argument or --shared (no interactive prompt).

연결된 데이터베이스를 검사하고 관리합니다.

mastra env db list
mastra env db show <database>
mastra env db delete <database>

mastra env db list각 데이터베이스의 종류, 상태, 범위, 주입된 변수 이름을 보여줍니다.mastra env db show 는 secret 값을 마스킹한 상태로 연결 방법을 출력합니다. 다음을 전달하세요: --show-secrets to reveal them. mastra env db delete 는 Provider에서 database와 그 안의 모든 데이터를 영구적으로 삭제합니다. Databases를 생성하고 삭제하려면 조직의 admin role이 필요합니다.

프로젝트 설정에서 연결

1. 다음에서 프로젝트를 엽니다.platform and go to Project Settings.

2. 열기Database section, then select Add database.

3. 선택provider (Turso 또는 Postgres)입니다. 연결하기 전에 Providers를 전환할 수 있습니다.

4. 데이터베이스를 구성합니다.

   • 이름: 프로젝트 내의 데이터베이스에 대한 레이블입니다.
   • 지역: 데이터베이스가 호스팅되는 위치입니다. 사용자에게 가장 가까운 지역을 선택하세요. Turso의 기본값은 다음과 같습니다.sjc (San Jose)가 기본값이며 전 세계 20곳 이상의 locations에서 사용할 수 있습니다. Postgres의 기본값은 aws-us-west-2 이며 미국, EU, APAC의 AWS 및 Azure regions에서 사용할 수 있습니다.

5. 선택하다Attach database. Provisioning은 background에서 실행됩니다. Database는 다음 상태로 시작하며: provisioning state and moves to ready Provider가 설정을 완료하면 해당 상태가 됩니다. 연결 세부 정보는 server runtime environment variables로 프로젝트에 자동 삽입됩니다.

프로젝트 설정에서 연결된 데이터베이스는 프로젝트 범위입니다. 사용CLI to attach an environment-scoped database.

코드에서 연결

데이터베이스가 있을 때ready, Provider가 provisioning을 완료하고 platform이 연결 세부 정보를 관리형 environment variables로 삽입한 상태입니다. 다음에서 상태를 확인하세요: Project Settings → Database, each attached database shows provisioning while setup runs in the background, then ready when you can connect. Open a ready 데이터베이스를 열어 환경 변수와 복사하여 붙여 넣을 수 있는 코드 조각을 확인하세요. 수동 구성 없이 해당 변수를 Mastra 스토리지 어댑터에 연결하세요.

투르소(LibSQL)

Turso는 두 가지 환경 변수를 노출합니다.TURSO_DATABASE_URL and TURSO_AUTH_TOKEN. The following example connects a LibSQLStore using those variables.

src/mastra/storage.ts

import { LibSQLStore } from '@mastra/libsql'

export const storage = new LibSQLStore({
  id: 'mastra-storage',
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
})

어댑터를 설치합니다.

npm

npm install @mastra/libsql@latest

pnpm

pnpm add @mastra/libsql@latest

Yarn

yarn add @mastra/libsql@latest

Bun

bun add @mastra/libsql@latest

포스트그레SQL

PostgreSQL은 단일을 노출합니다.DATABASE_URL connection string. The following example connects a PostgresStore using that variable.

src/mastra/storage.ts

import { PostgresStore } from '@mastra/pg'

export const storage = new PostgresStore({
  connectionString: process.env.DATABASE_URL!,
})

어댑터를 설치합니다.

npm

npm install @mastra/pg@latest

pnpm

pnpm add @mastra/pg@latest

Yarn

yarn add @mastra/pg@latest

Bun

bun add @mastra/pg@latest

통과storage instance to your Mastra configuration에 추가하여 Agents, Memory, Workflows에서 사용할 수 있도록 합니다:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { storage } from './storage'

export const mastra = new Mastra({
  storage,
})

환경변수

각 공급자는 고정된 관리 환경 변수 세트를 주입합니다. 데이터베이스가 실행 중일 때 프로젝트에서 이러한 기능을 사용할 수 있습니다.ready. You don't define them yourself.

공급자	변수
투르소	TURSO_DATABASE_URL, TURSO_AUTH_TOKEN
Postgres	DATABASE_URL

경고

연결 자격 증명을 비밀로 취급합니다. 인증 토큰(TURSO_AUTH_TOKEN) and the Postgres connection string (DATABASE_URL)는 데이터에 대한 전체 액세스 권한을 부여합니다. Platform은 기본적으로 이를 마스킹하며 요청 시에만 표시합니다.

데이터베이스 관리

• 연결 세부정보 보기: 열기ready 프로젝트 설정에서 database를 열어 environment variables와 복사하여 붙여 넣을 수 있는 code snippet을 확인하세요.
• 삭제: 프로젝트에서 데이터베이스를 제거하면 공급자와 함께 데이터베이스가 삭제되고 삽입된 환경 변수가 지워집니다. 이는 되돌릴 수 없으므로 더 이상 데이터가 필요하지 않은지 확인하세요.