Skip to main content

Use Neo4j Aura

Neo4j Aura is a fully managed cloud graph database. It's the easiest way to get started with create-context-graph without running Neo4j locally.

Prerequisites​

Step 1: Create an Aura Instance​

  1. Go to console.neo4j.io
  2. Click New Instance
  3. Choose AuraDB Free (or a paid tier for production)
  4. Select a region close to you
  5. Click Create
  6. Save the generated password — you'll need it in the next step

Step 2: Download the .env File​

After creating the instance, Neo4j Aura offers a Download .env button. This file contains your connection credentials:

NEO4J_URI=neo4j+s://xxxxxxxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-generated-password

Save this file somewhere accessible.

Step 3: Scaffold Your Project​

Use the --neo4j-aura-env flag to import your Aura credentials directly:

uvx create-context-graph my-app \
  --domain healthcare \
  --framework pydanticai \
  --neo4j-aura-env /path/to/Neo4j-xxxxxxxx-Created-2026-03-28.txt \
  --demo-data

This will:

  • Parse the .env file for connection details
  • Configure the generated project to use your Aura instance
  • Set neo4j_type to aura automatically

Step 4: Verify the Connection​

After scaffolding, verify the connection:

cd my-app
make test-connection

You should see:

✅ Connected to Neo4j Aura (neo4j+s://xxxxxxxx.databases.neo4j.io)

Step 5: Seed Data and Start​

make install
make seed
make start

Troubleshooting​

Connection refused​

  • Ensure your Aura instance is Running (not paused)
  • Free-tier instances pause after 3 days of inactivity — resume from the Aura console
  • Check that NEO4J_URI starts with neo4j+s:// (TLS required for Aura)

Authentication failed​

  • Double-check the password in your .env file
  • If you lost the password, reset it from the Aura console under Instance settings

Slow queries​

  • Free-tier Aura instances have limited resources — queries may take 2-5 seconds
  • For better performance, upgrade to a paid tier

Further Reading​