SqlCommenter is a Haskell library that implements the SQL Commenter protocol. It provides functionality to add key-value pair attributes as comments to SQL queries, enhancing database observability and making it easier to correlate slow queries with application code.
- Add SQL Commenter attributes to SQL queries
- Parse SQL Commenter attributes from existing SQL queries
- Integration with OpenTelemetry for distributed tracing
- URL-encoding of attribute keys and values
- Support for both single-line and multi-line SQL comments
- Robust parsing that ignores SQL strings and quoted identifiers
You can install SqlCommenter using Cabal or Stack. Add the following to your project's .cabal
file:
dependencies:
sqlcommenter == 0.1.*
Or if you're using Stack, add this to your stack.yaml
:
extra-deps:
- sqlcommenter-0.1.0.0
Then run cabal install
or stack build
respectively.
Here's a simple example of how to use SqlCommenter:
import SqlCommenter
import qualified Data.Map.Strict as M
import Data.Text (Text)
main :: IO ()
main = do
let query = "SELECT * FROM users"
let attributes = M.fromList [("app", "myapp"), ("version", "1.0")]
let commentedQuery = sqlCommenter query attributes
putStrLn $ "Original query: " ++ show query
putStrLn $ "Commented query: " ++ show commentedQuery
This will output:
Original query: "SELECT * FROM users"
Commented query: "SELECT * FROM users /* app='myapp',version='1.0' */"
Use the sqlCommenter
function to add attributes to your SQL queries:
sqlCommenter :: Text -> Map Text Text -> Text
Example:
import SqlCommenter
import qualified Data.Map.Strict as M
import Data.Text (Text)
query :: Text
query = "SELECT * FROM users WHERE id = ?"
attributes :: Map Text Text
attributes = M.fromList
[ ("app", "myapp")
, ("version", "1.0")
, ("db_driver", "postgresql")
]
commentedQuery :: Text
commentedQuery = sqlCommenter query attributes
Use the parseFirstSqlComment
function to extract attributes from an existing SQL query:
parseFirstSqlComment :: Text -> Map Text Text
Example:
import SqlCommenter
import Data.Text (Text)
query :: Text
query = "SELECT * FROM users /* app='myapp',version='1.0' */"
parsedAttributes :: Map Text Text
parsedAttributes = parseFirstSqlComment query
SqlCommenter provides functions to integrate with OpenTelemetry for distributed tracing:
import SqlCommenter
import qualified OpenTelemetry.Trace.Core as OTel
main :: IO ()
main = do
-- Get current SQL Commenter attributes
attrs <- getSqlCommenterAttributes
-- Get attributes with trace data
attrsWithTrace <- getSqlCommenterAttributesWithTraceData
-- Add trace data to existing attributes
span <- OTel.getCurrentSpan
updatedAttrs <- addTraceDataToAttributes span attrs
-- Use the attributes in your SQL query
let query = "SELECT * FROM users"
let commentedQuery = sqlCommenter query updatedAttrs
-- Execute commentedQuery...
Contributions to sqlcommenter
are welcome! Please feel free to submit a Pull Request.
Before submitting a PR, please make sure that:
- Your code adheres to the Haskell Style Guide.
- You've added appropriate documentation and updated the README & CHANGELOG as appropriate.
- You've added tests for new functionality.
- All tests pass when you run
cabal test
.
This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.
- This project is based on the SQL Commenter specification.
- Thanks to the OpenTelemetry community for their work on distributed tracing standards.