Jupyter SQL Extension

​

Overview

• Zero-Credential Data Access: No manual credential handling or connection strings.
• Unified Platform Integration: All available SyneHQ data sources accessible via magic commands.
• Enterprise-Grade Security: RBAC, SSO, audit logging, and query validation.
• Rich Output Support: Pandas DataFrames, HTML tables, JSON, and custom charting.

​

Feature Highlights

​

🔐 Secure Connection Management

• All connections managed by SyneHQ’s API and internal services.
• Credential-free, enterprise authentication (SSO/OAuth supported).
• Automatic connection pooling, retries, and failover.

​

🛡️ Security and Validation

• Advanced SQL injection prevention, dangerous operation detection.
• Queries fully audited and validated.
• Fine-grained access controls match SyneHQ platform RBAC.

​

📊 Rich Output Formatting

• Results as Pandas DataFrames (default).
• HTML tables with sorting/filtering; ideal for reports.
• JSON output for API and automation workflows.
• Easy chart and visualization integration.

​

🔄 Advanced Query Features

• Python variable substitution with intuitive, safe syntax.
• Evaluate expressions, lists, and functions within SQL.
• Named result assignment and direct variable usage.
• Support for async execution and smart query caching.

​

📈 Performance and Monitoring

• Query execution metrics and optimization guidance.
• Connection health checks, retries, and robust error recovery.

​

Quick Start

1. Install the extension
   pip install syne-sql-extension 
   
2. Load the extension in Jupyter
   %load_ext syne_sql_extension
   
3. Connect and query
   %%sql analytics_db 
   SELECT * FROM users LIMIT 10 
   

​

Using Python Variables

user_limit = 50 
dept = 'Sales'  

%%sql hr_db 
SELECT name, email FROM employees WHERE department = {dept} LIMIT {user_limit}

• Strings, numbers, lists/tuples, booleans, None (as SQL NULL), datetime objects, safe Python expressions.

​

Output Formats

# DataFrame (default): 
%%sql sales_db --format dataframe 
SELECT product, SUM(revenue) AS total FROM sales GROUP BY product  

# HTML table: 
%%sql sales_db --format html 
SELECT * FROM products WHERE price > 100  

# JSON: %%sql api_db --format json 
SELECT config FROM settings WHERE active = true 

%%sql analytics_db 
users_df >> SELECT * FROM users LIMIT 100  

# Use as DataFrame in notebook: 
users_df.groupby("country")["id"].count().plot(kind="bar") 

​

Connection Management

%%sql --list-connections 

%%sql my_db_connection 
SELECT 1

​

Error Handling & Troubleshooting

• Human-readable exception messages: connection errors, invalid SQL, permission issues.
• All errors are logged with audit trails in SyneHQ.
• Enable debug mode for verbose logs:
  %%sql db --verbose
  SELECT * FROM data 
  

• Extension not loading: %load_ext syne_sql_extension (confirm installation)
• Permissions error: Confirm access in SyneHQ admin UI.
• Network issues: Ensure connectivity to SyneHQ APIs.

​

Security

• All queries validated/sanitized before submission.
• No secrets or credentials ever present in Python code or notebooks.
• Queries, errors, and outputs are fully audited via SyneHQ.

user_input = "'; DROP TABLE users; --"  # blocked  

%%sql db 
SELECT * FROM users WHERE name = '{user_input}'

user_input = "Jane Doe" 
%%sql --connection-id db 
SELECT * FROM users WHERE name = {user_input}

​

Advanced Usage

%%sql db --cache 
SELECT expensive_query() FROM big_table 

%%sqlconnect analytics_db 
sales >> SELECT category, SUM(amount) AS total FROM orders GROUP BY category 

sales.plot.bar(x="category", y="total") 

​

Support and Contributions

• Documentation: docs.synehq.com
• Source Code: GitHub
• Issues & Feature Requests: GitHub Issues
• Email Support: support@synehq.com