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

# 호스팅된 데이터베이스

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

```bash
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](https://mastra.zisheng.pro/ko/docs/mastra-platform/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는 준비될 때까지 폴링하며 몇 초 정도 걸립니다.

```bash
# 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).

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

```bash
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](https://mastra.zisheng.pro/ko/docs/mastra-platform/overview) 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](#attach-with-the-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](https://mastra.zisheng.pro/ko/reference/storage/libsql) using those variables.

```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**:

```bash
npm install @mastra/libsql@latest
```

**pnpm**:

```bash
pnpm add @mastra/libsql@latest
```

**Yarn**:

```bash
yarn add @mastra/libsql@latest
```

**Bun**:

```bash
bun add @mastra/libsql@latest
```

### 포스트그레SQL

PostgreSQL은 단일을 노출합니다.`DATABASE_URL` connection string. The following example connects a [PostgresStore](https://mastra.zisheng.pro/ko/reference/storage/postgresql) using that variable.

```ts
import { PostgresStore } from '@mastra/pg'

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

어댑터를 설치합니다.

**npm**:

```bash
npm install @mastra/pg@latest
```

**pnpm**:

```bash
pnpm add @mastra/pg@latest
```

**Yarn**:

```bash
yarn add @mastra/pg@latest
```

**Bun**:

```bash
bun add @mastra/pg@latest
```

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

```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을 확인하세요.
- **삭제**: 프로젝트에서 데이터베이스를 제거하면 공급자와 함께 데이터베이스가 삭제되고 삽입된 환경 변수가 지워집니다. 이는 되돌릴 수 없으므로 더 이상 데이터가 필요하지 않은지 확인하세요.