Geode GQL for Visual Studio Code

Full-featured GQL (Graph Query Language) and Cypher support for the Geode graph database.

Features

Language Support

• Syntax Highlighting: Full TextMate grammar for GQL and Cypher
• Code Snippets: 45+ snippets for common query patterns
• Language Server: Real-time diagnostics, hover docs, completions
• Formatting: Auto-format GQL documents

Query Execution

• Run Query: Execute the current file (Ctrl+Enter / Cmd+Enter)
• Run Selection: Execute selected text (Ctrl+Shift+Enter)
• Explain Query: View query execution plan
• Results Table: View results in formatted table panel
• Graph Visualization: Automatic graph view for node/relationship results

Graph Visualization

• High-Performance Rendering: WebGL-accelerated via Cytoscape.js, supports 10,000+ nodes
• Neo4j-Style Display: Nodes colored by label, sized by degree
• Multiple Layouts: Force-directed, hierarchical, circular, grid, concentric
• Graph Exploration:
  • Double-click to expand node neighbors
  • Right-click for context menu (expand, hide, find paths)
  • Side panel for detailed node/edge properties
  • Path finding between any two nodes
• Interactive Features: Search, filter, cluster, lock positions
• Export: Save graphs as PNG or SVG

Connection Management

• Multiple Profiles: Save and manage multiple database connections
• Secure Credentials: Passwords stored in VS Code secure storage
• Auto-Connect: Optionally connect on startup
• Connection Status: Status bar shows current connection

Query Management

• Query History: Track all executed queries with success/failure status
• Saved Queries: Save favorite queries with categories
• Export/Import: Export saved queries to JSON, import from files
• Re-run: Easily re-run queries from history

Schema Explorer

• Live Schema: Browse node labels and relationship types from database
• Properties: View properties for each label/type
• Statistics: See node and relationship counts

Performance Tools

• Metrics Panel: Real-time performance metrics dashboard
• Query Profiling: Track slow queries
• Latency Histograms: Visualize query latency distribution
• Export Metrics: Export metrics to JSON

AI Integration (MCP)

• MCP Server: Model Context Protocol integration for AI assistants
• 8 MCP Tools: Query, schema, counts, paths, explain, create nodes/relationships
• AI-Assisted: Let AI assistants interact with your database

Prerequisites

None. The VSIX bundles the geode-ui server and the geode graph-DB binary; the extension boots them on activation. The host system does not need the geode CLI installed.

If you need to point at an external geode server, configure the host/port through the Geode sidebar UI. The bundled binaries continue to run alongside; they provide LSP and the management UI.

Installation

Install Extension

Option 1: VS Code Marketplace (Recommended)

# Install via command line
code --install-extension codeprosorg.geode-vscode

# Or search in VS Code:
# 1. Open VS Code
# 2. Press Ctrl+Shift+X (Cmd+Shift+X on macOS)
# 3. Search for "Geode"
# 4. Click Install

Option 2: Manual Installation from VSIX

# Download a VSIX from releases or build one locally, then:
code --install-extension geode-vscode-<version>.vsix

# Or in VS Code: Extensions → ... → Install from VSIX

Option 3: Build and Install VSIX (From Source)

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Package as VSIX
npm run package

# Install in VS Code
code --install-extension geode-vscode-<version>.vsix

Option 4: Development Mode (F5 Debugging)

1. Open this folder in VS Code
2. Run npm install
3. Press F5 to launch Extension Development Host
4. Open a .gql file in the new window

Option 5: Using Make

make install
make dev

Usage

Keyboard Shortcuts

Commands (Command Palette)

Query Execution:

• Geode: Run GQL Query - Execute current file
• Geode: Run Selected Query - Execute selection
• Geode: Explain Query Plan - Show execution plan

Connection:

• Geode: Add Connection - Add new connection profile
• Geode: Connect to Geode Server - Connect to database
• Geode: Disconnect from Server - Disconnect

Tools:

• Geode: Show Performance Metrics - Open metrics dashboard
• Geode: Show Graph Visualization - Open graph visualization panel
• Geode: Visualize Query as Graph - Execute and visualize as graph
• Geode: Show GQL Documentation - Open reference panel
• Geode: Restart Language Server - Restart LSP

Saved Queries:

• Geode: Save Query - Save current query
• Geode: Export All Queries - Export to JSON
• Geode: Import Queries - Import from JSON

MCP (AI Integration):

• Geode: List MCP Tools - Show available MCP tools
• Geode: Execute MCP Tool - Run an MCP tool

Snippets

Type these prefixes and press Tab:

Basic Queries:

Data Modification:

Aggregations:

Advanced:

Transactions:

Performance:

Utilities:

Sidebar Views

The Geode sidebar (click the database icon) contains:

1. Connections - Manage database connections
2. Schema Explorer - Browse database schema
3. Query History - View executed queries
4. Saved Queries - Access saved/favorite queries

Configuration

Settings in VS Code (Ctrl+,):

Troubleshooting

LSP Not Starting

1. Check Output panel: View -> Output -> "Geode GQL" for bundled server logs.

2. Increase startup timeout if the bundled server is slow to initialise:

   "geode.bundledServer.startupTimeoutMs": 20000
   

3. Set geode.bundledServer.logLevel to "debug" for verbose output.

No Syntax Highlighting

1. Check file extension is .gql, .cypher, .gcypher, or .pgql
2. Check bottom-right shows "GQL" or "Cypher" as language
3. Try: Command Palette -> "Change Language Mode" -> GQL

Query Execution Fails

1. Check Output panel for detailed error messages.
2. Add or verify a connection profile via the Geode sidebar.
3. Use Geode: Restart Language Server to reset the LSP.

Connection Issues

1. Verify any external server is running and accessible.
2. Configure host and port through the Geode sidebar UI.
3. Check firewall settings.

Bundled Components

The VSIX bundles two binaries (per-platform variants under resources/bin/<platform>/):

• geode-ui - Go server that hosts the React management UI and proxies API requests.
• geode - Geode graph-DB binary (provides LSP and query execution; used by sub-plan 6 and later).

Licenses for both are collected into resources/THIRD_PARTY_LICENSES.txt at build time.

Build matrix (per platform): linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64. CI uses vsce package --target <platform> to produce one VSIX per platform.

Development

# Install dependencies
npm install

# Watch mode (auto-recompile)
npm run watch

# In another terminal, press F5 in VS Code to debug

Project Structure

geode-vscode/
├── package.json                    # Extension manifest
├── tsconfig.json                   # TypeScript config
├── src/
│   ├── extension.ts                # Main extension entry
│   ├── client/
│   │   ├── GeodeClientWrapper.ts   # CLI-based database client
│   │   └── EnhancedConnectionManager.ts
│   ├── connections/
│   │   ├── ConnectionManager.ts    # Connection profile management
│   │   └── ConnectionsTreeProvider.ts
│   ├── views/
│   │   ├── SchemaExplorerProvider.ts
│   │   ├── EnhancedSchemaExplorerProvider.ts
│   │   ├── QueryHistoryProvider.ts
│   │   └── SavedQueriesProvider.ts
│   ├── panels/
│   │   ├── ResultsTablePanel.ts    # Query results display
│   │   ├── GraphViewPanel.ts       # Graph visualization
│   │   ├── PerformanceMetricsPanel.ts
│   │   └── QueryPlanPanel.ts
│   └── mcp/
│       └── GeodeMCPServer.ts       # MCP integration
├── syntaxes/
│   └── gql.tmLanguage.json         # Syntax highlighting
├── snippets/
│   └── gql.json                    # Code snippets (45+)
└── language-configuration.json

Supported File Types

MCP Tools for AI Assistants

The extension provides MCP (Model Context Protocol) tools for AI integration:

License

Apache License 2.0 - See LICENSE for details.

Copyright 2024-2026 CodePros