Overview
ODBC provides a standard interface for database connectivity, allowing tools like:- BI Tools: Tableau, Power BI, Looker, Metabase
- Database Clients: DBeaver, DataGrip, SQL Workbench
- Applications: Any application supporting ODBC
Prerequisites
ODBC Driver Manager
Install an ODBC driver manager on your system:macOS
Linux (Ubuntu/Debian)
Linux (RHEL/CentOS)
Windows
Windows includes ODBC driver manager by default.Arrow Flight SQL ODBC Driver
Spice uses Arrow Flight SQL, which requires a compatible ODBC driver:- Download the Arrow Flight SQL ODBC driver from Apache Arrow releases
- Install the driver on your system
- Register the driver with your ODBC driver manager
Connection Configuration
DSN Configuration
Create a Data Source Name (DSN) for Spice:On macOS/Linux
Edit/etc/odbc.ini (system-wide) or ~/.odbc.ini (user):
On Windows
- Open ODBC Data Source Administrator
- Click Add
- Select Arrow Flight SQL ODBC Driver
- Configure:
- Data Source Name: Spice
- Host: localhost
- Port: 50051
- Authentication: Username/Password or API Key
Connection String
Alternatively, use a connection string directly:Default Ports
| Service | Port | Description |
|---|---|---|
| HTTP API | 8090 | SQL queries, health checks |
| Arrow Flight | 50051 | Flight and Flight SQL (ODBC/JDBC) |
| Metrics | 9090 | Prometheus metrics |
Authentication
Username and Password
API Key (Bearer Token)
No Authentication
Connecting from Applications
Python (pyodbc)
Installation
Using DSN
Using Connection String
Parameterized Queries
R (odbc)
Installation
Basic Usage
C# (.NET)
Using System.Data.Odbc
Parameterized Query
Business Intelligence Tools
Tableau
- Open Tableau Desktop
- Click Connect → Other Databases (ODBC)
- Select DSN:
Spice - Click Sign In
- Select tables and build visualizations
Power BI
- Open Power BI Desktop
- Click Get Data → ODBC
- Select DSN:
Spice - Choose Import or DirectQuery
- Click OK and load data
DBeaver
- Create new connection
- Select ODBC
- Configure:
- DSN: Spice
- Or use connection string
- Test connection
- Execute SQL queries
DataGrip
- Add new Data Source
- Select ODBC
- Choose DSN:
Spice - Test connection
- Query your data
Troubleshooting
Test ODBC Connection
macOS/Linux
Windows
Use ODBC Data Source Administrator → Test ConnectionCommon Issues
Driver Not Found
Error:[IM002] [unixODBC][Driver Manager]Data source name not found
Solution: Verify driver is installed and registered in odbcinst.ini:
Connection Refused
Error:Connection refused to localhost:50051
Solution:
- Verify Spice is running:
spice status - Check Flight port: default is 50051
- Check firewall settings
Authentication Failed
Error:Authentication failed
Solution:
- Verify username/password or API key
- Check authentication type in connection string
- Ensure authentication is configured in Spice runtime
SSL/TLS Errors
Error:SSL connection failed
Solution:
- For local development, set
UseEncryption=0 - For production, configure TLS in Spice runtime
- Verify certificate paths
Debug Mode
Enable ODBC tracing:macOS/Linux
Edit~/.odbcinst.ini:
Windows
- Open ODBC Data Source Administrator
- Go to Tracing tab
- Click Start Tracing Now
Performance Optimization
Batch Fetching
Increase fetch size for better performance:Connection Pooling
Reuse connections for better performance:Best Practices
- Use DSN for easier management across multiple applications
- Enable connection pooling for better performance
- Use parameterized queries to prevent SQL injection
- Batch fetch results for large datasets
- Close connections when done to free resources
- Use read-only mode when possible for BI tools
Related APIs
- Arrow Flight SQL API - Native Flight SQL protocol
- JDBC Connectivity - Java database connectivity
- ADBC - Arrow Database Connectivity
- SQL Query API - HTTP-based SQL queries