weaviate-connection

name	weaviate-connection
description	Connect to local Weaviate vector database and verify connection health
version	2.0.0
author	Scott Askinosie
dependencies	["weaviate-local-setup"]

Weaviate Connection Skill

This skill helps you connect to a local Weaviate database instance running in Docker and verify the connection is healthy.

Important Note

This skill is designed for LOCAL Weaviate instances only. Claude Desktop and Claude Web have network restrictions that prevent connections to external services like Weaviate Cloud.

To use these skills, you must run Weaviate locally using Docker. See the weaviate-local-setup skill first.

Purpose

Establish and test connections to local Weaviate vector databases running on localhost.

When to Use This Skill

• User wants to connect to their local Weaviate database
• User needs to verify their Weaviate connection is working
• User asks to check Weaviate health or status
• After starting Weaviate with Docker

Prerequisites Check

BEFORE proceeding, Claude should verify:

1. Python environment is set up (from weaviate-local-setup skill)

   • Virtual environment exists at .venv/
   • Dependencies are installed

2. Weaviate Docker container is running

   • Check with docker ps | grep weaviate
   • If not running, guide user to start it

3. Environment file exists

   • .env file is present
   • Has required variables set

Automated Prerequisites Check

import subprocess
import sys
import os
from pathlib import Path

def check_prerequisites():
    """Check all prerequisites before connecting to Weaviate"""
    print("🔍 Checking prerequisites...\n")

    all_checks_passed = True

    # Check 1: Virtual environment
    venv_path = Path(".venv")
    if venv_path.exists():
        print("✅ Virtual environment found")
    else:
        print("⚠️  No virtual environment found")
        print("   Creating virtual environment...")
        subprocess.run([sys.executable, "-m", "venv", ".venv"])
        print("✅ Virtual environment created")

    # Check 2: Dependencies
    try:
        import weaviate
        from dotenv import load_dotenv
        print("✅ Python dependencies installed")
    except ImportError:
        print("⚠️  Missing dependencies")
        print("   Installing weaviate-client and python-dotenv...")
        subprocess.check_call([sys.executable, "-m", "pip", "install", "-q",
                              "weaviate-client", "python-dotenv"])
        print("✅ Dependencies installed")

    # Check 3: Docker container
    result = subprocess.run(["docker", "ps"], capture_output=True, text=True)
    if "weaviate" in result.stdout:
        print("✅ Weaviate Docker container is running")
    else:
        print("❌ Weaviate Docker container not found")
        print("   Please start Weaviate first:")
        print("   cd weaviate-local-setup && docker-compose up -d")
        all_checks_passed = False

    # Check 4: .env file
    if Path(".env").exists():
        print("✅ .env file found")
    else:
        print("⚠️  .env file not found")
        print("   Creating .env from template...")
        if Path(".env.example").exists():
            import shutil
            shutil.copy(".env.example", ".env")
            print("✅ .env file created")
            print("   Please edit .env and add your API keys if needed")
        else:
            print("❌ No .env.example found")
            all_checks_passed = False

    print("\n" + "="*50)
    if all_checks_passed:
        print("✅ All prerequisites met! Ready to connect.")
    else:
        print("❌ Some prerequisites missing. Please resolve them first.")
    print("="*50 + "\n")

    return all_checks_passed

# Run the check
if __name__ == "__main__":
    check_prerequisites()

Claude should run this check automatically when this skill is loaded.

Requirements

• Python 3.8+
• weaviate-client library (pip install weaviate-client)
• Local Weaviate instance running in Docker (see weaviate-local-setup skill)
• Docker Desktop running

Connection Instructions

Step 1: Ensure Weaviate is Running Locally

Before connecting, verify Weaviate Docker container is running:

# Check if Weaviate is running
docker ps | grep weaviate

# If not running, start it with docker-compose
cd weaviate-local-setup
docker-compose up -d

# Verify Weaviate is ready
curl http://localhost:8080/v1/.well-known/ready

Step 2: Install Dependencies

pip install weaviate-client python-dotenv

Step 3: Configure Environment Variables

Update your .env file for local connection:

# .env file
WEAVIATE_URL=localhost:8080
WEAVIATE_API_KEY=  # Leave empty for local instances

# Optional: Only needed if using these vectorizers
OPENAI_API_KEY=your-openai-key
COHERE_API_KEY=your-cohere-key

Step 4: Create Connection Code

Basic Connection (Recommended):

import weaviate
import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Connect to local Weaviate
client = weaviate.connect_to_local(
    host="localhost",
    port=8080,
    grpc_port=50051
)

# Test the connection
try:
    # Check if client is ready
    if client.is_ready():
        print("✅ Connected to local Weaviate successfully!")

        # Get cluster metadata
        meta = client.get_meta()
        print(f"📦 Weaviate version: {meta.get('version', 'unknown')}")

        # List collections
        collections = client.collections.list_all()
        print(f"\n📚 Found {len(collections)} collections:")
        for name, config in collections.items():
            print(f"  - {name}")
    else:
        print("❌ Connection failed - Weaviate not ready")

except Exception as e:
    print(f"❌ Error connecting to Weaviate: {str(e)}")
    print("\n💡 Make sure Weaviate is running:")
    print("   docker ps | grep weaviate")

finally:
    # Always close the connection
    client.close()

Connection with API Headers (for OpenAI/Cohere vectorizers):

import weaviate
import os
from dotenv import load_dotenv

load_dotenv()

# Connect with API key headers
client = weaviate.connect_to_local(
    host="localhost",
    port=8080,
    grpc_port=50051,
    headers={
        "X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY"),  # Optional
        "X-Cohere-Api-Key": os.getenv("COHERE_API_KEY")   # Optional
    }
)

try:
    if client.is_ready():
        print("✅ Connected to local Weaviate with API headers!")

except Exception as e:
    print(f"❌ Error: {str(e)}")

finally:
    client.close()

Step 5: Verify Connection Health

After connecting, check:

• ✅ Client is ready (client.is_ready())
• ✅ Can retrieve metadata (client.get_meta())
• ✅ Can list collections (client.collections.list_all())

Best Practices

1. Start Docker First: Always ensure Weaviate container is running before connecting
2. Use Environment Variables: Store configuration in .env file
3. Close Connections: Always close the client when done to prevent memory leaks
4. Error Handling: Wrap connection code in try/except blocks
5. Connection Reuse: Keep one client instance per session, don't create multiple
6. Check Docker Status: Use docker ps to verify Weaviate is running

Common Issues

Issue: "Connection refused" or "Cannot connect to localhost:8080"

Solution: Weaviate Docker container is not running

# Check if container is running
docker ps | grep weaviate

# Start Weaviate
cd weaviate-local-setup
docker-compose up -d

# Wait 10-15 seconds for startup, then verify
curl http://localhost:8080/v1/.well-known/ready

Issue: "Port 8080 already in use"

Solution: Another service is using port 8080

# Find what's using port 8080
lsof -i :8080

# Either stop that service, or modify docker-compose.yml to use a different port
# Change ports: - "8081:8080" in docker-compose.yml

Issue: "Docker daemon not running"

Solution: Start Docker Desktop application

Issue: "Module not found: weaviate"

Solution: Install the client library

pip install weaviate-client

Environment Variables Template

# .env file for LOCAL Weaviate
WEAVIATE_URL=localhost:8080
WEAVIATE_API_KEY=  # Leave empty for local

# Optional vectorizer API keys
OPENAI_API_KEY=your-openai-key
COHERE_API_KEY=your-cohere-key
ANTHROPIC_API_KEY=your-anthropic-key

Quick Test Script

Save this as test_connection.py:

import weaviate

# Connect to local Weaviate
client = weaviate.connect_to_local()

try:
    if client.is_ready():
        print("✅ Connected successfully!")
        meta = client.get_meta()
        print(f"📦 Version: {meta.get('version')}")
    else:
        print("❌ Not ready")
except Exception as e:
    print(f"❌ Error: {e}")
finally:
    client.close()

Run it:

python test_connection.py

Next Steps

After establishing connection:

• Use weaviate-collection-manager skill to create and manage collections
• Use weaviate-data-ingestion skill to add data to collections
• Use weaviate-query-agent skill to search and retrieve data

Additional Resources

• Weaviate Python Client Docs
• Weaviate Docker Installation
• Local Weaviate Setup Guide