GraphQL SQLCommenter

Add GraphQL operation metadata to SQL comments for better query tracking in PlanetScale Query Insights.

Overview

GraphQL SQLCommenter extends Google's sqlcommenter to include GraphQL operation information (operation name, type, and document hash) in SQL query comments. This enables you to:

• Group queries by operation - Filter by graphql_op=getUserProfile in PlanetScale Query Insights
• Track query sources - See which GraphQL queries trigger specific SQL statements
• Monitor performance - Identify slow GraphQL operations causing database bottlenecks
• Debug real-time apps - Track WebSocket/subscription queries
• Optimize patterns - Better understand your application's query patterns

Quick Example

GraphQL Query:

query getUserProfile {
  user(id: 123) {
    name
    email
  }
}

Resulting SQL:

SELECT * FROM users WHERE id = 123
/*graphql_op=getUserProfile,graphql_type=query,graphql_sha=a1b2c3d4e5*/

In PlanetScale Query Insights: Filter by graphql_op='getUserProfile' to see all related SQL queries!

Features

• ✅ HTTP GraphQL - Queries and mutations via HTTP endpoints
• ✅ WebSocket Subscriptions - Real-time GraphQL over WebSockets
• ✅ Django Channels - Full integration with Channels-based GraphQL
• ✅ Sync & Async - Works with both execution modes
• ✅ Named & Unnamed - Handles all operation types
• ✅ Thread-safe - Uses ContextVars for safe concurrency
• ✅ Zero overhead - Minimal performance impact
• ✅ Graceful errors - Fails safely without breaking GraphQL

Installation

pip install graphql-sqlcommenter
# or
uv add graphql-sqlcommenter

Quick Start

Basic Setup (HTTP GraphQL)

# settings.py
MIDDLEWARE = [
    'graphql_sqlcommenter.middleware.SqlCommenterMiddleware',
]

# Optional: Customize paths (defaults to ['/graphql'])
# SQLCOMMENTER_GRAPHQL_PATHS = ['/graphql', '/api/graphql']

Advanced Setup (WebSocket/Subscriptions)

# settings.py
INSTALLED_APPS = [
    'graphql_sqlcommenter',  # Enables Graphene hooks
    'channels',
    'graphene_django',
]

MIDDLEWARE = [
    'graphql_sqlcommenter.middleware.SqlCommenterMiddleware',
]

# Enable WebSocket/subscription support
SQLCOMMENTER_WITH_GRAPHENE_HOOK = True
SQLCOMMENTER_WITH_SUBSCRIPTIONS = True

Use Cases

Track Slow Operations

-- Slow query in PlanetScale
SELECT * FROM orders WHERE user_id IN (...)
/*graphql_op=getUserOrders,graphql_type=query,graphql_sha=xyz789*/

Filter Query Insights by graphql_op='getUserOrders' to see all related queries.

Monitor Real-Time Apps

subscription watchUser {
  userUpdated(userId: "123") { status }
}

All subscription database queries include metadata for monitoring.

Debug N+1 Queries

graphql_op='listUsers' - 1000 queries (N+1 problem!)
graphql_op='getUserProfile' - 2 queries (optimized)

Contributing

Contributions welcome! Please see our issues and discussions.

# Install dependencies
uv sync

# Run tests
just test

# Run all checks (lint, format, type, tests)
just check

License

Apache 2.0 - See LICENSE for details.

Support

• Issues: https://github.com/lincolnloop/graphql-sqlcommenter/issues
• Discussions: https://github.com/lincolnloop/graphql-sqlcommenter/discussions

Acknowledgments

Built with:

• Google SQLCommenter
• Graphene
• Django
• Django Channels

Inspired by Sentry's GraphQL integration.