> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jupyter SQL Extension

> Effortlessly analyze your SyneHQ-connected data sources from Jupyter notebooks—no credentials required.

![](https://i.ibb.co/Q3xBCLTC/Twitter-post-3-1.png)

## Overview

SyneHQ’s Jupyter SQL Extension brings secure, unified, and credential-free database access to your Jupyter environment. All connections and permissions are managed by SyneHQ’s platform, making analytics and data science simpler, safer, and faster.

* **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**

   ```shellscript theme={"system"}
   pip install syne-sql-extension 
   ```
2. **Load the extension in Jupyter**

   ```python theme={"system"}
   %load_ext syne_sql_extension
   ```
3. **Connect and query**

   ```python theme={"system"}
   %%sql analytics_db 
   SELECT * FROM users LIMIT 10 
   ```

***

## Using Python Variables

Parameterize your queries safely and expressively:

```python theme={"system"}
user_limit = 50 
dept = 'Sales'  

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

Supported substitution for:

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

Expression evaluation is sandboxed; dangerous patterns (`import`, `eval`, `os`, etc.) are blocked.

***

## Output Formats

```python theme={"system"}
# 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 
```

Assign result to a variable for downstream analysis/plotting:

```python theme={"system"}
%%sql analytics_db 
users_df >> SELECT * FROM users LIMIT 100  
```

```python theme={"system"}
# Use as DataFrame in notebook: 
users_df.groupby("country")["id"].count().plot(kind="bar") 
```

***

## Connection Management

List all available SyneHQ connections:

```python theme={"system"}
%%sql --list-connections 
```

Test a connection:

```python theme={"system"}
%%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:

  ```python theme={"system"}
  %%sql db --verbose
  SELECT * FROM data 
  ```

Common issues:

* 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.

Blocked dangerous queries, e.g.:

```python theme={"system"}
user_input = "'; DROP TABLE users; --"  # blocked  

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

Safe queries use parameter binding:

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

***

## Advanced Usage

Async and cached queries:

```python theme={"system"}
%%sql db --cache 
SELECT expensive_query() FROM big_table 
```

Example: Assign results, plot, and visualize:

```python theme={"system"}
%%sqlconnect analytics_db 
sales >> SELECT category, SUM(amount) AS total FROM orders GROUP BY category 
```

```python theme={"system"}
sales.plot.bar(x="category", y="total") 
```

***

## Support and Contributions

* **Documentation:** [docs.synehq.com](https://docs.synehq.com/)
* **Source Code:** [GitHub](https://github.com/SyneHQ/jupyter-sql-extension)
* **Issues & Feature Requests:** [GitHub Issues](https://github.com/SyneHQ/jupyter-sql-extension/issues)
* **Email Support:** [support@synehq.com](mailto:support@synehq.com)

***

**Made with ❤️ by the SyneHQ team**\
*Secure, seamless analytics for every data scientist.*

***