Neo4j Aura Provisioning Skill

When to Use

• Creating an Aura instance (CLI, REST API, Python, Terraform)
• Pausing, resuming, resizing, or deleting an instance
• Downloading initial credentials from creation response
• Polling instance status: creating → running
• Setting up CI/CD provisioning or teardown pipelines
• Choosing instance tier (Free vs Professional vs Business Critical vs VDC)

When NOT to Use

• Cypher queries against running DB → neo4j-cypher-skill
• GDS algorithms on Aura → neo4j-gds-skill (Pro with plugin) or neo4j-aura-graph-analytics-skill (serverless)
• neo4j-admin / cypher-shell → neo4j-cli-tools-skill
• Application driver setup → use a language driver skill (python, javascript, java, go, dotnet)

---

Instance Tier Decision Table

AuraDB Free limits: 200k nodes, 400k rels; auto-pauses after 72 h inactivity; deleted if paused >30 days; no resize.

---

Auth Setup

CLI (aura-cli v1.7+)

Install (binary, not 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

Add credentials (from 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"

Verify:

aura-cli instance list --output table

REST API — Get Bearer Token

Token endpoint: POST https://api.neo4j.io/oauth/token Token expires: 3600 s (1 h). On 403 → refresh token.

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}..."

Use in all subsequent calls: --header "Authorization: Bearer $TOKEN"

---

Step 1 — List Tenants (Projects)

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}'

---

Step 2 — Create Instance

CRITICAL: Capture output immediately. Initial password shown ONCE — never retrievable again. If lost: delete and recreate. Store aura-creds.json before doing anything else.

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 (full create)

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')

Instance create request body fields:

---

Step 3 — Poll Until RUNNING (CRITICAL — All Ops Are Async)

ALL lifecycle operations (create, pause, resume, resize) are async. Do NOT attempt connection or next operation until status = running (or paused for pause op).

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 equivalent:

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

Status lifecycle:

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

---

Step 4 — Write .env and Verify

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"

---

Step 5 — Lifecycle Operations

All operations require instance in the correct state. Wrong-state ops return 4xx error.

Pause

Required state: running

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

Resume

Required state: paused

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

Resize (Professional+ only — NOT Free)

Required state: running; instance remains available during resize.

# 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

Delete

IRREVERSIBLE. Export snapshots first if data needed.

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 Provisioning Script

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.")

---

Region Codes

AWS

GCP

Azure

Enterprise tiers (Business Critical, VDC) add 20+ additional regions per provider. Check console for full list. Free tier: GCP only; limited subset of regions.

---

Terraform Provider

terraform {
  required_providers {
    aura = {
      source  = "neo4j/neo4j-aura"
    }
  }
}

provider "aura" {
  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 "aura_instance" "db" {
  name           = "prod-db"
  type           = "professional-db"
  cloud_provider = "gcp"
  region         = "europe-west1"
  memory         = "4GB"
  tenant_id      = var.aura_tenant_id
}

output "neo4j_uri" {
  value     = "neo4j+s://${aura_instance.db.id}.databases.neo4j.io"
  sensitive = false
}
output "neo4j_password" {
  value     = aura_instance.db.password
  sensitive = true
}

After terraform apply: poll status before marking infra ready — Terraform resource creation returns when API call completes, not when DB is running.

---

Common Errors

---

API Rate Limits

Poll interval: ≥10 s to stay within limits on Free; 5 s safe on Pro+. On Retry-After header in 5xx response: wait that many seconds before retry.

---

Security Rules

• Write initial credentials to .env; verify .env in .gitignore before proceeding
• Never print PASSWORD in CI logs — write to secrets vault (AWS Secrets Manager, GitHub secret, Vault)
• Use from_env() / os.environ — never hardcode credentials
• If .env absent: python-dotenv load_dotenv() auto-loads; do NOT prompt user unless loading fails

---

WebFetch — Current Docs

---

Checklist

• [ ] .env created with URI/user/password; .env in .gitignore
• [ ] Initial credentials saved to secure storage immediately after create
• [ ] poll_status called after create — do NOT connect before status = running
• [ ] poll_status called after pause/resume
• [ ] Correct tier selected (Free for dev, Pro+ for production, BC for HA)
• [ ] Region confirmed available for chosen tier and cloud provider
• [ ] Tenant ID provided for all create/list operations (required in multi-tenant orgs)
• [ ] Token refreshed if > 1 h old (or 403 received)
• [ ] Delete confirmed by user — data loss is permanent, no recovery

Status: Draft / WIP

neo4j-aura-provisioning-skill

Guides agents through programmatic provisioning of Neo4j Aura instances: aura-cli, Aura REST API, instance lifecycle management, and CI/CD credential handling.

Install:

npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-aura-provisioning-skill

Or paste this link into your coding assistant: https://github.com/neo4j-contrib/neo4j-skills/tree/main/neo4j-aura-provisioning-skill

Aura Agent (No-Code AI Agent)

No/low-code platform in the Aura Console for building AI agents that query AuraDB with natural language.

When to Use

Use Aura Agent for: retrieval assistants over graph data without app code, natural language queries from the console, prototyping agent behavior.

Use LangChain/LangGraph/etc. for: custom orchestration, multi-agent coordination, production deployment outside Aura console.

Prerequisites

In organization settings, both must be enabled:

• Generative AI assistance
• Aura Agent

Tool authentication must be enabled for the project (default ON for orgs created after May 2025; enable manually for older orgs).

How It Works

Agent loop: interpret user input → plan tools → execute tools (read-only graph queries) → generate response.

Tool Types

All tools are read-only. Agent cannot write to the database.

Similarity Search requires: vector index on AuraDB instance + embeddings stored on nodes.

MCP Endpoint

Agents can be exposed as MCP servers for use with external clients (Cursor, Claude Desktop, etc.):

1. Select agent → ... menu → Configure 2. Under Access, select External 3. Enable MCP server toggle → click "Update agent" 4. Copy MCP endpoint: ... menu → "Copy MCP server endpoint"

MCP config for Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "my-aura-agent": {
      "url": "<your-mcp-url>",
      "transport": "http"
    }
  }
}

Authentication: OAuth2 via Aura console. First connection prompts browser login → "Continue with Neo4j Aura" → Accept.

Restart client after adding MCP endpoint (Cursor, Claude Desktop, etc.).

For Claude Desktop and other clients: see https://neo4j.com/docs/aura/aura-agent/

Aura Monitoring and Metrics

Accessing Metrics

Quick view: expand Metrics section at bottom of instance card (shows CPU, Storage, Query Rate for last 24h). Full dashboard: instance card → "View all metrics" button, or Operations → Metrics in left menu.

Metrics Dashboard Tabs

Resources tab:

• CPU Usage — min/max/avg % of CPU capacity
• Storage — % disk used
• Out of Memory Errors — count; critical metric, monitor closely

Instance tab:

• Heap — min/max/avg heap memory for query execution
• Page Cache — % time data found in memory (higher = better; low = disk reads hurting performance)
• Page Cache Evictions — times/min data swapped out; frequent spikes = page cache too small
• Bolt Connections — active Cypher transaction connections
• Garbage Collection — % time freeing memory; high = memory strain

Database tab:

• Store Size, Query Metrics, Transaction counts, Checkpoint/Replan stats

External Monitoring (Prometheus)

Aura exposes a Prometheus-compatible endpoint per project:

https://customer-metrics-api.neo4j.io/api/v1/<project-id>/<metrics-id>/metrics

Authentication: OAuth2 with Client ID + Client Secret from Metrics Integration settings. Token URL: https://api.neo4j.io/oauth/token

Prometheus config:

- job_name: 'aura-metrics'
  scrape_timeout: 30s
  metrics_path: '/api/v1/<project-id>/<metrics-id>/metrics'
  scheme: 'https'
  static_configs:
    - targets: ['customer-metrics-api.neo4j.io']
  oauth2:
    client_id: '<AURA_CLIENT_ID>'
    client_secret: '<AURA_CLIENT_SECRET>'
    token_url: 'https://api.neo4j.io/oauth/token'

Access: project Settings → Metrics Integration.

Keep Client Secret secure — grants access to the entire organization.

Backup and Restore

Snapshots: automatic per tier schedule (see aura-tiers.md) + on-demand manual snapshots. Restore: creates a new instance from snapshot (does not overwrite existing instance). Local backup: download .dump file from console for offline storage.

Query Logs

Access: Operations → Query Logs. Contains: query text, duration, plan, user. Use for: identifying slow queries, security review of query patterns. Security logs: separate tab — tracks auth events, role changes.

Aura Tiers and Connection Details

Tier Comparison

Free auto-pauses after 72h inactivity. Professional/BC/VDC include 7-day free trial (extendable 7 more days).

Connection String Format

URI pattern (all tiers):

NEO4J_URI=neo4j+s://<instance-id>.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=<password from credentials file>
NEO4J_DATABASE=neo4j
AURA_INSTANCEID=<instance-id>

• URI uses neo4j+s:// (TLS enforced) — never bolt:// or neo4j:// for Aura
• Instance ID is fixed at creation; cannot be changed
• Cloud provider and region are fixed at creation — changing either requires a new instance
• Password can be changed later via console; name and size (paid tiers) also changeable

Fixed vs Changeable Settings

Fixed at creation (new instance required to change):

• Cloud provider (AWS, GCP, Azure)
• Region/location
• Instance ID

Changeable later:

• Instance name
• Memory and storage size (paid tiers)
• Password

User Roles

Invite users: Project Settings → Users → Invite Users.

Aura Shared Responsibility

Neo4j manages: infrastructure, DB maintenance, backups, scaling, security/encryption. User manages: data modeling, application code, query optimization, monitoring response.

Aura Data Importer (GUI Import Tool)

Data Importer is built into the Aura console. Access: instance → Import in left sidebar. No Cypher required — visual drag-and-drop CSV-to-graph mapping.

Workflow

1. Add data source — click "New data source" → CSV or TSV → upload file 2. Create node labels — click "Add node label" → set label name → "Map from table" → select columns 3. Set unique identifier — click key icon next to ID property → auto-creates unique constraint + index 4. Create relationships — hover edge of source node → drag to target node → set type → map From/To ID columns 5. Add relationship properties — select relationship → "Map from table" → select extra columns 6. Run import — click "Run import" → enter DB credentials if prompted → wait for summary 7. Save model — name the model → "Save" (reusable for future imports)

Key Behaviors

• Setting a unique identifier automatically creates a constraint and index — enables MERGE semantics on re-import
• Type mismatch: if Data Importer can't convert a value (e.g. text in Integer column), import continues but that node won't have the property — check counts
• Single CSV file can source both nodes AND relationships (denormalized data): map same file to node label and relationship; set From/To ID columns
• Models saved at project level; reusable across instances
• Download model + data: ... menu → "Download model (with data)"; restore via "Open model (with data)"
• Clear existing model: ... menu → "Clear all"

Common Mistakes

Verify After Import

// Node counts by label
MATCH (n) RETURN labels(n)[0] AS label, count(*) AS cnt ORDER BY cnt DESC

// Relationship counts
MATCH ()-[r]->() RETURN type(r) AS rel, count(*) AS cnt ORDER BY cnt DESC

// Sample data
MATCH (n:Movie) RETURN n LIMIT 5

Data Importer vs LOAD CSV

Use Data Importer when: GUI workflow preferred, one-time or occasional import, CSV files available. Use LOAD CSV (Cypher) when: complex transformations, batched large imports, CI/CD pipelines, incremental sync. Use neo4j-import-skill for bulk neo4j-admin import (offline, fastest for millions of rows).