Kole By SyneHQ

Execute queries against your databases using SQL, PostgreSQL commands, or natural language through SyneHQ's Kole platform. Use this skill whenever the user mentions databases, SQL queries, data analysis, PostgreSQL, querying data, database connections, checking database schemas, listing tables, or wants to explore or analyze data in their databases. Also use when user needs to sign up for SyneHQ or get their API credentials. IMPORTANT - Always use this skill when user asks about their data, even if they don't explicitly say "database" or "SQL".

Harsh Vardhan Goswami 🐳@theboringhumane

Install

openclaw skills install @theboringhumane/data-analysis-synehq

kole - Query Your Data with SyneHQ

Execute SQL queries, PostgreSQL commands, and natural language questions against your databases through SyneHQ's intelligent data platform.

⚠️ IMPORTANT: Prerequisites

This skill requires the SyneHQ Kole MCP server to be installed and configured.

Install the MCP Server

bash

# Install via npm
npm install -g @synehq/kole-mcp

# Or from source
git clone https://github.com/synehq/kole-mcp.git
cd kole-mcp
npm install && npm run build

Configure the MCP Server

Create .mcp.json in your project:

json

{
  "synehq-kole": {
    "command": "npx",
    "args": ["-y", "@synehq/kole-mcp@latest"],
    "env": {
      "SYNEHQ_API_KEY": "${SYNEHQ_API_KEY}",
      "SYNEHQ_CONNECTION_ID": "${SYNEHQ_CONNECTION_ID}"
    }
  }
}

Or if you have it installed globally:

json

{
  "synehq-kole": {
    "command": "synehq-kole-mcp",
    "env": {
      "SYNEHQ_API_KEY": "${SYNEHQ_API_KEY}",
      "SYNEHQ_CONNECTION_ID": "${SYNEHQ_CONNECTION_ID}"
    }
  }
}

Set Environment Variables

bash

export SYNEHQ_API_KEY="your_api_key"
export SYNEHQ_CONNECTION_ID="your_connection_id"

Without the MCP server installed, this skill will not work! The skill provides instructions and patterns, but the actual query execution happens through the MCP server's tools.

What is Kole?

Kole is SyneHQ's data query platform that enables you to:

Execute SQL queries against connected databases
Use PostgreSQL-specific commands and DDL operations
Ask questions in natural language and get structured results
Discover database schemas and metadata
Manage multiple database connections
Test connections before querying

Quick Start

First Time User?

If the user doesn't have a SyneHQ account yet, use get_auth_info to get signup instructions:

javascript

get_auth_info()
// Returns: signup URL, login URL, dashboard URL, setup instructions

Check Available Connections

Always start by listing available connections:

javascript

get_connections()
// Shows all database connections with IDs, names, types, and status

Test Connection

Before running queries, verify the connection works:

javascript

test_connection({
  connectionId: "conn_abc123"  // optional if SYNEHQ_CONNECTION_ID env var is set
})

Core Operations

1. Execute SQL Queries

Simple SELECT:

javascript

execute_query({
  query: "SELECT * FROM users WHERE created_at > '2024-01-01' LIMIT 10"
})

With options:

javascript

execute_query({
  query: "SELECT * FROM large_table",
  connectionId: "prod-db",
  limit: 100,
  timeout: 60000,  // 60 seconds
  userId: "analyst_1"  // for audit tracking
})

2. PostgreSQL Mode (psql commands)

Enable PostgreSQL-specific commands with psql: true:

List all tables:

javascript

execute_query({
  query: "\\dt",
  psql: true
})

Describe table structure:

javascript

execute_query({
  query: "\\d+ users",
  psql: true
})

DDL Operations:

javascript

execute_query({
  query: "CREATE TABLE analytics_cache (id SERIAL PRIMARY KEY, query_hash VARCHAR(64), result JSONB)",
  psql: true
})

3. Natural Language Queries

Ask questions in plain English:

javascript

execute_query({
  query: "Show me the top 10 customers by revenue this month"
})

execute_query({
  query: "How many active users signed up last week?"
})

execute_query({
  query: "What are the best-selling products?"
})

4. Database Metadata Discovery

List all tables:

javascript

get_tables({
  database: "production",  // optional filter
  schema: "public"        // optional filter
})

Get detailed table schema:

javascript

get_table_schema({
  database: "production",
  schema: "public",
  table: "users"
})
// Returns: columns, types, constraints, indexes

Common Query Patterns

See references/query-patterns.md for detailed examples. Here are the most common:

Data Exploration

sql

-- Quick table overview
SELECT * FROM users LIMIT 5;

-- Column statistics
SELECT 
  COUNT(*) as total_rows,
  COUNT(DISTINCT email) as unique_emails,
  MIN(created_at) as earliest_user,
  MAX(created_at) as latest_user
FROM users;

Business Analytics

sql

-- Monthly revenue
SELECT 
  DATE_TRUNC('month', order_date) as month,
  COUNT(*) as order_count,
  SUM(total_amount) as revenue
FROM orders
WHERE order_date >= '2024-01-01'
GROUP BY month
ORDER BY month DESC;

-- Customer lifetime value
SELECT 
  user_id,
  COUNT(*) as order_count,
  SUM(total_amount) as lifetime_value
FROM orders
GROUP BY user_id
ORDER BY lifetime_value DESC
LIMIT 20;

Data Quality Checks

sql

-- Find NULL values
SELECT 
  COUNT(*) as total_rows,
  COUNT(*) FILTER (WHERE email IS NULL) as null_emails,
  COUNT(*) FILTER (WHERE phone IS NULL) as null_phones
FROM users;

-- Find duplicates
SELECT 
  email,
  COUNT(*) as duplicate_count
FROM users
GROUP BY email
HAVING COUNT(*) > 1;

Workflow Patterns

Pattern 1: Data Discovery Workflow

When user wants to explore their data:

List connections → get_connections()
Test connection → test_connection()
List tables → get_tables()
Inspect schema → get_table_schema()
Query data → execute_query()

Pattern 2: Analytics Workflow

When user wants to analyze data:

Understand structure → get_table_schema()
Sample data → SELECT * FROM table LIMIT 10
Run aggregations → Complex SELECT with GROUP BY
Iterate based on results

Pattern 3: PostgreSQL Admin Workflow

When user needs database operations:

Check current state → \dt, \d+ table_name (psql mode)
Execute DDL → CREATE, ALTER, DROP (psql mode)
Verify changes → Check with \dt or queries
Create indexes → CREATE INDEX (psql mode)

Best Practices

1. Always Start with Discovery

javascript

// Step 1: List connections
get_connections()

// Step 2: Test the connection
test_connection({ connectionId: "chosen_connection" })

// Step 3: Discover tables
get_tables()

// Step 4: Understand schema
get_table_schema({ database: "db", schema: "public", table: "users" })

// Step 5: Query safely with LIMIT
execute_query({ query: "SELECT * FROM users LIMIT 10" })

2. Use LIMIT for Exploration

Always use LIMIT when exploring large tables:

sql

-- Good: Limited results
SELECT * FROM large_table LIMIT 10

-- Bad: Might return millions of rows
SELECT * FROM large_table

3. Leverage PostgreSQL Features (psql mode)

sql

-- JSON operations
SELECT data->>'name' as name FROM json_table

-- Array operations
SELECT * FROM users WHERE tags @> ARRAY['premium']

-- Window functions
SELECT 
  user_id,
  order_date,
  total_amount,
  ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY order_date DESC) as order_rank
FROM orders

4. Handle Errors Gracefully

javascript

// Always test connection first
const connection = await test_connection()

if (connection.success) {
  // Then run your query
  const result = await execute_query({
    query: "SELECT * FROM users LIMIT 10"
  })
}

5. Use User IDs for Tracking

Track queries with user IDs for audit logs:

javascript

execute_query({
  query: "SELECT * FROM sensitive_table",
  userId: "user_12345"  // Shows up in audit logs
})

6. Set Appropriate Timeouts

For complex queries, increase timeout:

javascript

execute_query({
  query: "SELECT * FROM orders JOIN order_items USING(order_id)",
  timeout: 120000  // 2 minutes
})

Troubleshooting

Connection Issues

Symptom: "Connection failed" or "Invalid credentials"

Solution:

Test connection: test_connection()
List connections to verify ID: get_connections()
Check credentials in SyneHQ dashboard
Verify database is accessible

Query Timeouts

Symptom: Query takes too long and times out

Solution:

javascript

execute_query({
  query: "your_complex_query",
  limit: 100,        // Limit result size
  timeout: 120000    // Increase timeout to 2 minutes
})

Large Result Sets

Symptom: Too much data returned

Solution:

javascript

// Use LIMIT and OFFSET for pagination
execute_query({
  query: "SELECT * FROM users ORDER BY id LIMIT 100 OFFSET 0",
  limit: 100
})

No API Key

Symptom: "SYNEHQ_API_KEY environment variable is required"

Solution:

Get signup info: get_auth_info()
Sign up at https://data.synehq.com/signup
Get API key from Settings → API Keys
Set environment variable: export SYNEHQ_API_KEY="your_key"

Environment Variables

Variable	Required	Default	Purpose
`SYNEHQ_API_KEY`	✅ Yes	-	Authentication
`SYNEHQ_CONNECTION_ID`	⚠️ Recommended	-	Default database connection
`SYNEHQ_BASE_URL`	❌ No	https://cosmos.synehq.com	API endpoint
`SYNEHQ_DATA_URL`	❌ No	https://data.synehq.com	Data API endpoint

Advanced Features

Multi-Connection Scenarios

Query multiple databases in the same session:

javascript

// Production database
execute_query({
  query: "SELECT COUNT(*) as prod_users FROM users",
  connectionId: "prod-db"
})

// Staging database
execute_query({
  query: "SELECT COUNT(*) as staging_users FROM users",
  connectionId: "staging-db"
})

// Analytics database
execute_query({
  query: "SELECT * FROM daily_metrics WHERE date >= CURRENT_DATE - 30",
  connectionId: "analytics-db"
})

Query Performance Analysis

Use EXPLAIN to analyze query performance:

javascript

execute_query({
  query: "EXPLAIN ANALYZE SELECT * FROM users WHERE email LIKE '%@gmail.com'",
  psql: true
})

Database Maintenance

Check table sizes and run maintenance:

javascript

// Check table sizes
execute_query({
  query: `
    SELECT 
      schemaname,
      tablename,
      pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as size
    FROM pg_tables
    WHERE schemaname = 'public'
    ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC
  `,
  psql: true
})

// Vacuum table
execute_query({
  query: "VACUUM ANALYZE users",
  psql: true
})

Security Notes

API keys are transmitted via secure headers (never in URLs)
All communication over HTTPS
User IDs tracked for audit logs
Connection credentials managed server-side
Never expose API keys in client code
Use read-only database users when possible

Resources

Signup: https://data.synehq.com/signup
Login: https://data.synehq.com/login
Dashboard: https://data.synehq.com/dashboard
Documentation: https://docs.synehq.com
Support: support@synehq.com

Quick Reference

Get Started

javascript

get_auth_info()           // Get signup/login URLs
get_connections()          // List all connections
test_connection()          // Test connection

Query Data

javascript

execute_query({ query: "SELECT * FROM users LIMIT 10" })
execute_query({ query: "\\dt", psql: true })  // PostgreSQL mode
execute_query({ query: "Show me top customers" })  // Natural language

Discover Schema

javascript

get_tables()
get_table_schema({ database: "db", schema: "schema", table: "table" })

Built with ❤️ by SyneHQ | Query your data, your way.

Kole By SyneHQ

Install

kole - Query Your Data with SyneHQ

⚠️ IMPORTANT: Prerequisites

Install the MCP Server

Configure the MCP Server

Set Environment Variables

What is Kole?

Quick Start

First Time User?

Check Available Connections

Test Connection

Core Operations

1. Execute SQL Queries

2. PostgreSQL Mode (psql commands)

3. Natural Language Queries

4. Database Metadata Discovery

Common Query Patterns

Data Exploration

Business Analytics

Data Quality Checks

Workflow Patterns

Pattern 1: Data Discovery Workflow

Pattern 2: Analytics Workflow

Pattern 3: PostgreSQL Admin Workflow

Best Practices

1. Always Start with Discovery

2. Use LIMIT for Exploration

3. Leverage PostgreSQL Features (psql mode)

4. Handle Errors Gracefully

5. Use User IDs for Tracking

6. Set Appropriate Timeouts

Troubleshooting

Connection Issues

Query Timeouts

Large Result Sets

No API Key

Environment Variables

Advanced Features

Multi-Connection Scenarios

Query Performance Analysis

Database Maintenance

Security Notes

Resources

Quick Reference

Get Started

Query Data

Discover Schema

Related skills