sealos-database

Sealos Database

識別と検出

• 所有者： sealos-database（/sealos-database、およびデータベースの作成、接続、バックアップ、ログ、アクセスに関するリクエスト）。
• クラス： sealos-cli を介した cloud-local-mutation。デプロイへの引き継ぎは任意で、引き継ぐ際は情報をマスキングします。
• カナリア： DB-REUSE-ENV、DB-CONFIRM-PUBLIC、DB-REDACT-CONNECT。

対象範囲と境界

プロジェクトパスとデータベースの目的を受け取ります。まず分析し、既存のデータベースを一覧表示してから、選択された種類のデータベースを作成または再利用し、既存のアプリケーション環境変数キーのみを設定します。以前の環境変数値とローカル Compose のロールバックを維持します。プライベートアクセスをデフォルトとします。データベースの削除、パブリックアクセス、バックアップの削除、復元時の競合、アクティブなアクセスの無効化は、引き続き承認が必要な操作です。

リスクと確認

パスワード、完全な接続文字列、kubeconfig、認証ファイル、コピーした環境変数の値は決して出力しません。パブリックアクセスまたは破壊的な操作の前には確認を求め、プライベートな代替手段を提示します。CLI の JSON 出力を解析し、選択されたワークスペース、名前空間、データベース、環境変数の変更をリクエストの範囲内に限定します。

ライフサイクルのワークフロー

各リクエストでは、プロジェクトを特定し、データベースの必要性を分析し、CLI／認証／リージョン／ワークスペースを確認してから、作成または再利用の前に一覧表示します。次に、接続情報を取得し、既存の環境変数キーを設定して、接続またはマイグレーションを検証します。リクエストの範囲に限定した success、stopped、または error を出力します。既存のアナライザー優先ワークフローは、以下のドメイン拡張として維持されます。ワークスペースが曖昧な場合、認証情報の応答が利用できない場合、または対象の環境変数が追跡対象である場合は、変更を加える前にリクエストを停止します。

リクエストの契約

input:
  project: local path or repository source
  intent: database type, purpose, and create-or-reuse preference
  access: private by default; public only after confirmation
preconditions:
  - analyzer evidence names the database signal and env key
  - sealos-cli/auth/region/workspace are resolved
  - the selected env file is ignored and the key is known

アクションの順序は analyze -> resolve account/workspace -> list -> create or reuse -> wait -> fetch -> wire -> verify です。選択されたワークスペース、名前空間、データベースの識別情報、環境変数の変更は、リクエストの範囲内に限定します。

段階的な情報開示

各フェーズに到達した時点で、アナライザー、CLI、環境変数の設定、接続性に関する手順を一段階だけ読み込みます。詳細なコマンドが所有するスクリプトやリファレンスに記載されている場合でも、認証情報の取り扱いとパブリックアクセス／破壊的操作の確認事項は、ここで常に確認できるようにします。

出力、停止、エラーの状態

• success：データベースの識別情報／ステータス、リージョン／ワークスペース、環境変数ファイルとキーの名前、マスキング済みの接続またはマイグレーションの証拠、確認状態、および追加のアクセス状態。
• stopped：ワークスペースの曖昧さ、認証情報の準備状況が利用できないこと、追跡対象の環境変数、パブリックアクセス／破壊的操作の確認境界、または前提条件の不足を示し、安全な次のアクションを提示します。承認が必要な操作を実施済みとは主張しません。
• error：アナライザー、CLI、接続、または環境変数への書き込みのステップ、サニタイズ済みの診断カテゴリ、影響を受けた成果物、および復旧アクションを示します。パスワード、URL、認証値、完全な接続文字列はマスキングします。

引き継ぎ

任意のデプロイ引き継ぎでは、以下のタプル全体を使用します。引き継ぎ先は、デプロイの範囲と実行時の証拠を再確認します。

target: sealos-deploy
inputArtifact: redacted database identity, private-access status, approved env-key contract, and connectivity/migration evidence
allowedAction: consume approved Secret/env references within the selected deployment scope
failureReturn: sanitized analyzer, CLI, env, or connectivity diagnostic with the failed phase
responseOwner: sealos-database

データベースへの直接のリクエストでは target: none を使用し、同じ証拠フィールドを維持します。

検証

analyze-project-database.mjs、sealos-cli の JSON 出力、アプリケーションのマイグレーション／接続性の証拠、およびベースラインケース database-positive-reuse-redacted-connectivity と database-violating-unconfirmed-public-or-destructive を使用します。成功として受け入れる前に、環境変数の保持とマスキングを検証します。

このスキルを使用して、開発中のプロジェクトに実際の Sealos Cloud データベースを用意します。デフォルトでは、アプリケーションが必要とするデータベースを特定し、sealos-cli で Sealos データベースを作成または再利用し、接続情報を取得して、必要なローカル環境変数のみを設定し、アプリケーションが接続できることを検証します。

安全ルール

1. 最終回答にデータベースのパスワードや完全な接続文字列を絶対に出力しないでください。
2. 既存の環境変数の値を上書きする前に、確認するか、古い値を保持してください。
3. .env、.env.local、接続文字列、パスワード、kubeconfig、Sealos 認証ファイルをコミットしないでください。
4. パブリックなデータベースアクセスを有効にする前に、必ず確認してください。アプリが Sealos／Devbox 内で実行される場合は、プライベート接続を優先してください。
5. 破壊的な操作（database delete、backup-delete、名前が重複する可能性のある場所への復元、稼働中のアプリが依存するアクセスの無効化）を行う前に、必ず確認してください。
6. デフォルトでは sealos-cli の JSON 出力を使い、テーブル出力をスクレイピングせずに解析してください。

ワークフロー

1. 対象プロジェクトを特定する

pwd または git rev-parse --show-toplevel で作業ディレクトリを確認してください。

プロジェクトディレクトリがある場合は、アナライザーを実行してください。

node <SKILL_DIR>/scripts/analyze-project-database.mjs <project-dir>

アナライザーの結果を出発点として使い、編集する前に、結果に記載された実際のファイルを確認してください。アナライザーは意図的にシークレットの値を出力しません。

2. sealos-cli を確認する

既存の sealos-cli バイナリがあれば、そちらを優先してください。

sealos-cli --version
sealos-cli database --help
sealos-cli whoami

インストールされていない場合は、単発のコマンドに npx -y sealos-cli@latest ... を使ってください。グローバルにインストールする前に確認してください。

認証情報がない場合、または有効期限が切れている場合は、次を実行してください。

sealos-cli login <region>
sealos-cli workspace list
sealos-cli workspace current

ユーザーが想定しているワークスペースを使ってください。複数のワークスペースがあり、対象を特定できない場合は、プロビジョニングする前に確認してください。

3. 新規作成するか再利用するかを選ぶ

まず既存のデータベースを一覧表示してください。

sealos-cli database list -o json

名前、種類、用途が一致する既存のデータベースがあれば再利用してください。プロジェクトに適したデータベースがない場合や、ユーザーが開発用データベースの新規作成を求めている場合は、新しく作成してください。

プロジェクトに明確な追加要件がない限り、開発用の保守的なデフォルト設定を使ってください。

sealos-cli database create postgresql --name <app-dev-db> --cpu 1 --memory 1 --storage 3 --replicas 1 -o json

作成前に、バージョンの選択が重要な場合は、サポートされているバージョンを確認してください。

sealos-cli database versions --type postgresql -o json

サポートされている CLI データベースの種類には、postgresql、mongodb、mysql、apecloud-mysql、redis、kafka、qdrant、nebula、weaviate、milvus、pulsar、clickhouse があります。プロジェクトから検出された種類を使ってください。データベース固有の手がかりがプロジェクトにない場合に限り、postgresql をデフォルトとして使ってください。

4. 準備完了を待ち、接続情報を取得する

データベースが稼働状態になるか、接続情報が取得できるまで、詳細をポーリングしてください。

sealos-cli database get <name> -o json
sealos-cli database connection <name> -o json

現在のコマンド仕様とレスポンスの処理については、references/sealos-cli-database.md を読んでください。

5. 開発環境を接続する

接続情報を、プロジェクトがすでに使用している環境変数に割り当ててください。

プロジェクトの手がかり	推奨する環境変数キー
Prisma、Drizzle、TypeORM、汎用的な Postgres	DATABASE_URL
MySQL 固有の既存設定を使う MySQL アプリ	DATABASE_URL または既存の MYSQL_URL
MongoDB アプリ	MONGODB_URI
Redis キャッシュ／キュー	REDIS_URL

既存のローカル環境変数ファイルの規約に従ってください。

1. Next.js とフロントエンド関連のプロジェクトでは、.env.local を優先してください。
2. リポジトリがローカル開発に .env をすでに使っており、Git で無視されている場合に限り、.env を優先してください。
3. .env.example はドキュメントとしてのみ扱ってください。実際のシークレットを書き込んではいけません。
4. コメントや関係のないキーは保持してください。

接続文字列が目的の形式で直接返されない場合は、sealos-cli database connection の host、port、username、password フィールドから組み立ててください。

6. アプリケーションの接続を検証する

CLI コマンドだけでなく、プロジェクトで通常使われる検証手順を実行してください。

1. プロジェクトに明確なコマンド（prisma migrate、drizzle-kit migrate、db:migrate、db:push）がある場合は、マイグレーションまたはイントロスペクションを実行してください。
2. アプリを起動するか、データベース接続を確立する最小限のテストを実行してください。
3. アプリが Sealos の外部で実行され、プライベートエンドポイントに接続できない場合は、パブリックアクセスを有効にする前に確認してください。

sealos-cli database enable-public <name> -o json
sealos-cli database connection <name> -o json

テスト後にパブリックアクセスが不要になった場合は、無効にしてください。

sealos-cli database disable-public <name> -o json

7. 結果を報告する

次の項目を要約してください。

1. データベース名、種類、リージョン／ワークスペース、ステータス。
2. 更新した環境変数ファイルとキー。シークレットの値は明かさないでください。
3. 検証コマンドと結果。
4. パブリックアクセスの状態と、必要な後続対応。

よくあるタスク

既存のプロジェクトを Sealos データベースに接続する

1. アナライザーを実行します。
2. アナライザーが示した env／config ファイルを確認します。
3. 既存の Sealos データベースを一覧表示します。
4. 一致するデータベースを作成するか、既存のものを再利用します。
5. 接続情報を取得します。
6. 想定される env キーを書き込みます。
7. アプリの DB 検証を実行します。

開発用のローカル Compose データベースを置き換える

1. postgres、mysql、mongo、redis の Compose サービスを参照している、アプリサービスの env 変数を特定します。
2. 同等の Sealos データベースをプロビジョニングします。
3. ユーザーからローカルサービスの削除を依頼された場合を除き、Compose ファイルではなく、アプリのローカル env ファイルのみを更新します。
4. ローカル Compose から簡単にロールバックできるようにします。元の Compose サービスは引き続き利用できます。

Devbox ワークフローにデータベースを追加する

1. Devbox が同じ Sealos ワークスペース内で実行される場合は、プライベートデータベース接続情報を使用します。
2. リポジトリで想定されている Devbox／アプリ環境に env 変数を書き込みます。
3. env 変数を設定してから、Devbox プロセスを再起動または再読み込みします。

参考資料

• scripts/analyze-project-database.mjs - 読み取り専用のプロジェクトデータベース意図アナライザー。
• references/sealos-cli-database.md - sealos-cli database コマンドの仕様。
• references/env-integration.md - env ファイルの安全な編集と接続文字列のマッピング。