neo4j-aura-provisioning-skill

使用する場面

• Aura インスタンスを作成するとき（CLI、REST API、Python、Terraform）
• インスタンスを一時停止、再開、サイズ変更、削除するとき
• 作成レスポンスから初期認証情報をダウンロードするとき
• インスタンスのステータスをポーリングするとき：creating → running
• CI/CD のプロビジョニングまたはティアダウンのパイプラインを設定するとき
• インスタンスのティア（Free、Professional、Business Critical、VDC）を選択するとき

使用しない場面

• 稼働中の DB に対する Cypher クエリ → neo4j-cypher-skill
• Aura 上の GDS アルゴリズム → neo4j-gds-skill（プラグイン付き Pro）または neo4j-aura-graph-analytics-skill（サーバーレス）
• neo4j-admin / cypher-shell → neo4j-cli-tools-skill
• アプリケーションのドライバー設定 → 言語用ドライバースキル（python、javascript、java、go、dotnet）を使用

---

インスタンスのティア選択表

ティア	API タイプコード	メモリ	GDS	レプリカ	使用する場面
AuraDB Free	free-db	1 GB	❌	❌	開発／デモ；ノード数 ≤200k／リレーション数 400k
AuraDB Professional	professional-db	2–64 GB	プラグイン利用可能	❌	本番ワークロード
AuraDB Business Critical	business-critical	4–384 GB	プラグイン利用可能	✅	HA、マルチ AZ、SLA
AuraDB VDC	enterprise-db	カスタム	✅	✅	専用インフラ、コンプライアンス
AuraDS Professional	professional-ds	2–64 GB	✅ ビルトイン	❌	データサイエンス／GDS
AuraDS Enterprise	enterprise-ds	カスタム	✅	✅	エンタープライズ向け GDS

AuraDB Free の制限：ノード数 200k、リレーション数 400k；72 時間操作がないと自動一時停止；一時停止状態が 30 日を超えると削除；サイズ変更不可。

---

認証の設定

CLI（aura-cli v1.7+）

インストール（pip ではなくバイナリ）：

# macOS
curl -L https://github.com/neo4j/aura-cli/releases/latest/download/aura-cli-darwin-amd64.tar.gz | tar xz
sudo mv aura-cli /usr/local/bin/
aura-cli -v          # verify

認証情報を追加（console.neo4j.io → Account Settings → API Credentials から取得）：

aura-cli credential add \
  --name "my-creds" \
  --client-id "$AURA_CLIENT_ID" \
  --client-secret "$AURA_CLIENT_SECRET"
aura-cli credential use --name "my-creds"

確認：

aura-cli instance list --output table

REST API — Bearer トークンの取得

トークンエンドポイント：POST https://api.neo4j.io/oauth/token トークンの有効期限：3600 s（1 h）。403 が返された場合 → トークンを更新します。

TOKEN=$(curl -s --request POST 'https://api.neo4j.io/oauth/token' \
  --user "${AURA_CLIENT_ID}:${AURA_CLIENT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  | jq -r '.access_token')
echo "Token: ${TOKEN:0:20}..."

以降のすべての呼び出しで使用します：--header "Authorization: Bearer $TOKEN"

---

ステップ 1 — テナント（プロジェクト）の一覧表示

CLI：

aura-cli tenants list --output table
# Copy TENANT_ID for create operations

REST：

curl -s https://api.neo4j.io/v1/tenants \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {id, name}'

---

ステップ 2 — インスタンスの作成

重要：出力をすぐに保存してください。 初期パスワードが表示されるのは一度だけで、後から取得することはできません。 紛失した場合は、削除して作り直してください。それ以外の作業を始める前に aura-creds.json を保存します。

CLI

aura-cli instance create \
  --name "my-instance" \
  --cloud-provider gcp \
  --region europe-west1 \
  --type professional-db \
  --tenant-id "$TENANT_ID" \
  --output json | tee aura-creds.json

# Extract for .env
INSTANCE_ID=$(jq -r '.id' aura-creds.json)
PASSWORD=$(jq -r '.password' aura-creds.json)

REST API（完全な作成リクエスト）

RESPONSE=$(curl -s -X POST https://api.neo4j.io/v1/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":           "my-instance",
    "cloud_provider": "gcp",
    "region":         "europe-west1",
    "type":           "professional-db",
    "tenant_id":      "'"$TENANT_ID"'",
    "memory":         "4GB",
    "version":        "5"
  }')
echo "$RESPONSE" | tee aura-creds.json
INSTANCE_ID=$(echo "$RESPONSE" | jq -r '.data.id')
PASSWORD=$(echo "$RESPONSE"   | jq -r '.data.password')

インスタンス作成リクエストのボディフィールド：

フィールド	必須	値
name	✅	任意の文字列
cloud_provider	✅	gcp aws azure
region	✅	リージョン表を参照
type	✅	ティア表を参照
tenant_id	✅	テナント一覧から取得
memory	✗	1GB 2GB 4GB 8GB … 384GB
version	✗	5（デフォルト）

---

ステップ 3 — RUNNING になるまでポーリング（重要 — すべての操作は非同期）

すべてのライフサイクル操作（作成、一時停止、再開、サイズ変更）は非同期です。ステータスが running（一時停止操作の場合は paused）になるまで、接続や次の操作を試みないでください。

poll_status() {
  local INSTANCE_ID=$1 TARGET=$2 MAX_WAIT=${3:-600}
  local ELAPSED=0 STATUS
  echo "Polling for status=$TARGET (max ${MAX_WAIT}s)..."
  while [ $ELAPSED -lt $MAX_WAIT ]; do
    STATUS=$(aura-cli instance get --instance-id "$INSTANCE_ID" --output json \
             | jq -r '.status' 2>/dev/null)
    echo "  [${ELAPSED}s] status=$STATUS"
    [ "$STATUS" = "$TARGET" ] && echo "Ready." && return 0
    [ "$STATUS" = "destroying" ] && echo "ERROR: instance is being destroyed" && return 1
    sleep 10; ELAPSED=$((ELAPSED + 10))
  done
  echo "TIMEOUT after ${MAX_WAIT}s — last status: $STATUS" && return 1
}

poll_status "$INSTANCE_ID" "running" 600

REST での同等の処理：

while true; do
  STATUS=$(curl -s "https://api.neo4j.io/v1/instances/$INSTANCE_ID" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.data.status')
  [ "$STATUS" = "running" ] && break
  sleep 10
done

ステータスのライフサイクル：

creating → running → pausing → paused → resuming → running
                  ↘ destroying → (gone)

---

ステップ 4 — .env を書き込み、確認する

CONNECTION_URI="neo4j+s://${INSTANCE_ID}.databases.neo4j.io"

cat > .env <<EOF
NEO4J_URI=${CONNECTION_URI}
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=${PASSWORD}
NEO4J_DATABASE=neo4j
AURA_INSTANCE_ID=${INSTANCE_ID}
EOF

# Ensure .env never committed
grep -q '^\.env$' .gitignore 2>/dev/null || echo '.env' >> .gitignore

# Verify connectivity
cypher-shell -a "$CONNECTION_URI" -u neo4j -p "$PASSWORD" "RETURN 'connected' AS status"

---

ステップ 5 — ライフサイクル操作

すべての操作には、インスタンスが正しい状態である必要があります。状態が不正な操作は 4xx エラーを返します。

一時停止

必要な状態：running

aura-cli instance pause --instance-id "$INSTANCE_ID"
poll_status "$INSTANCE_ID" "paused" 600

再開

必要な状態：paused

aura-cli instance resume --instance-id "$INSTANCE_ID"
poll_status "$INSTANCE_ID" "running" 900   # resume can take longer

サイズ変更（Professional 以上のみ — Free は対象外）

必要な状態：running；サイズ変更中もインスタンスは利用可能です。

# REST only — CLI resize not available in v1.7
curl -s -X PATCH "https://api.neo4j.io/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memory": "8GB"}'
poll_status "$INSTANCE_ID" "running" 600
# Cannot reduce below current usage level

削除

取り消しできません。データが必要な場合は、事前にスナップショットをエクスポートしてください。

aura-cli instance delete --instance-id "$INSTANCE_ID"
# No poll needed — immediate

REST：

curl -s -X DELETE "https://api.neo4j.io/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $TOKEN"

---

Python CI/CD プロビジョニングスクリプト

import os, time, requests

CLIENT_ID     = os.environ["AURA_CLIENT_ID"]
CLIENT_SECRET = os.environ["AURA_CLIENT_SECRET"]
BASE          = "https://api.neo4j.io/v1"

def get_token() -> str:
    r = requests.post(
        "https://api.neo4j.io/oauth/token",
        auth=(CLIENT_ID, CLIENT_SECRET),
        data={"grant_type": "client_credentials"},
    )
    r.raise_for_status()
    return r.json()["access_token"]

def auth_headers(token: str) -> dict:
    return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

def create_instance(token: str, tenant_id: str, **kwargs) -> dict:
    payload = {"tenant_id": tenant_id, "version": "5", **kwargs}
    r = requests.post(f"{BASE}/instances", headers=auth_headers(token), json=payload)
    r.raise_for_status()
    return r.json()["data"]   # contains id, password, connection_url

def poll_status(token: str, instance_id: str, target: str, timeout: int = 600) -> None:
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{BASE}/instances/{instance_id}", headers=auth_headers(token))
        r.raise_for_status()
        status = r.json()["data"]["status"]
        print(f"  status={status}")
        if status == target:
            return
        if status == "destroying":
            raise RuntimeError("Instance destroyed unexpectedly")
        time.sleep(10)
    raise TimeoutError(f"Instance {instance_id} did not reach '{target}' in {timeout}s")

# --- usage ---
token    = get_token()
instance = create_instance(
    token,
    tenant_id = os.environ["AURA_TENANT_ID"],
    name           = "ci-test-instance",
    cloud_provider = "aws",
    region         = "us-east-1",
    type           = "professional-db",
    memory         = "2GB",
)
# SAVE CREDENTIALS IMMEDIATELY — password never retrievable again
print(f"ID:       {instance['id']}")
print(f"URI:      neo4j+s://{instance['id']}.databases.neo4j.io")
print(f"Password: {instance['password']}")   # log to secure vault NOW

poll_status(token, instance["id"], "running", timeout=600)
print("Instance ready.")

---

リージョンコード

AWS

リージョンコード	場所
us-east-1	米国バージニア州北部
us-east-2	米国オハイオ州
us-west-2	米国オレゴン州
eu-west-1	アイルランド
eu-west-3	パリ
eu-central-1	フランクフルト
ap-southeast-1	シンガポール
ap-southeast-2	シドニー
ap-south-1	ムンバイ
sa-east-1	サンパウロ

GCP

リージョンコード	場所
europe-west1	ベルギー
europe-west3	フランクフルト
europe-west4	オランダ
us-central1	アイオワ州
us-east1	サウスカロライナ州
us-east4	バージニア州北部
asia-east1	台湾
asia-northeast1	東京
asia-southeast1	シンガポール
australia-southeast1	シドニー

Azure

リージョンコード	場所
eastus	米国東部
eastus2	米国東部 2
westeurope	オランダ
northeurope	アイルランド
uksouth	ロンドン
southeastasia	シンガポール
brazilsouth	ブラジル
koreacentral	韓国

エンタープライズティア（Business Critical、VDC）では、プロバイダーごとに20以上のリージョンが追加されます。全リストはコンソールでご確認ください。 無料ティアはGCPのみで、利用できるリージョンは一部に限られます。

---

Terraform プロバイダー

terraform {
  required_providers {
    neo4jaura = {
      source  = "neo4j-labs/neo4jaura"
    }
  }
}

provider "neo4jaura" {
  client_id     = var.aura_client_id       # or AURA_CLIENT_ID env var
  client_secret = var.aura_client_secret   # or AURA_CLIENT_SECRET env var
}

resource "neo4jaura_instance" "db" {
  name           = "prod-db"
  type           = "professional-db"
  cloud_provider = "gcp"
  region         = "europe-west1"
  memory         = "4GB"
  project_id     = var.aura_project_id   # Terraform uses project_id (REST API: tenant_id)
}

output "neo4j_uri" {
  value     = neo4jaura_instance.db.connection_url
  sensitive = false
}
output "neo4j_password" {
  value     = neo4jaura_instance.db.password
  sensitive = true
}

terraform apply の後、インフラストラクチャを準備完了とする前にステータスをポーリングしてください。Terraform のリソース作成は、API 呼び出しが完了した時点で戻り、データベースが running になるまで待つわけではありません。

---

よくあるエラー

エラー	原因	対処方法
動作していたのに 403 Forbidden が発生する	トークンの有効期限切れ（TTL 1 時間）	get_token() を再実行します
作成時に 409 Conflict が発生する	テナント内に同じ名前がすでに存在する	名前を変更するか、既存のものを削除します
一時停止時に 422 が発生する	インスタンスが running ではない	ステータスを確認し、進行中の操作が完了するまで待ちます
再開時に 422 が発生する	インスタンスが paused ではない	ステータスを確認します
サイズ変更時に 422 が発生する	現在の使用量を下回る	先にデータを減らします。使用量を下回るサイズには縮小できません
リージョンが見つからない	そのティアがリージョンをサポートしていない	GCP では Free ティアのみを使用します。Pro/BC は3つすべてのクラウドで利用できます
作成後に認証情報が失われる	パスワードが返されるのは作成時のみ	削除して再作成します。リセット機能はありません
429 Too Many Requests	レート制限に達した（Free は25リクエスト/分、Pro+ は125リクエスト/分）	ポーリング呼び出しの間に time.sleep(2) を追加します
instance list が空の結果を返す	誤った認証情報が有効になっている	aura-cli credential use --name <name>

---

API レート制限

ティア	リクエスト/分
Free / Pro Trial（課金なし）	25
課金ありの Pro、BC、VDC	125

ポーリング間隔：Free では制限内に収めるため10秒以上、Pro+ では5秒が安全です。 5xx レスポンスに Retry-After ヘッダーがある場合は、その秒数だけ待ってから再試行します。

---

セキュリティルール

• 初期認証情報を .env に書き込み、先に進む前に .env が .gitignore に含まれていることを確認します
• CI ログに PASSWORD を絶対に出力しないでください。シークレット保管庫（AWS Secrets Manager、GitHub secret、Vault）に書き込みます
• from_env() / os.environ を使用し、認証情報をハードコードしないでください
• .env がない場合：python-dotenv の load_dotenv() が自動的に読み込みます。読み込みに失敗しない限り、ユーザーに入力を求めないでください

---

WebFetch — 最新ドキュメント

内容	URL
REST API 仕様（OpenAPI）	https://neo4j.com/docs/aura/platform/api/specification/
CLI リファレンス	https://neo4j.com/docs/aura/aura-cli/
リージョン一覧	https://neo4j.com/docs/aura/managing-instances/regions/
認証の詳細	https://neo4j.com/docs/aura/api/authentication/
インスタンス操作	https://neo4j.com/docs/aura/managing-instances/instance-actions/

---

チェックリスト

• URI／ユーザー／パスワードを含む .env を作成し、.env を .gitignore に追加
• 作成直後に初期認証情報を安全なストレージに保存
• 作成後に poll_status を呼び出す。ステータスが running になる前に接続しないでください
• 一時停止／再開後に poll_status を呼び出す
• 適切なティアを選択（開発には Free、本番環境には Pro+、HA には BC）
• 選択したティアとクラウドプロバイダーで利用可能なリージョンであることを確認
• すべての作成／一覧表示操作にテナント ID を指定（マルチテナント組織では必須）
• トークンの発行から1時間以上経過した場合（または403を受信した場合）は更新
• 削除についてユーザーの確認を得る。データは完全に失われ、復元できません