Skip to content
Back to search

turbular

A MCP server allowing LLM agents to easily connect and retrieve data from any database

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/raeudigerraeffi--turbular/badge.svg)](/listings/raeudigerraeffi--turbular)

HTML

<a href="/listings/raeudigerraeffi--turbular"><img src="/api/listings/raeudigerraeffi--turbular/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Using Docker (Recommended)

1. Clone the repository:

   git clone https://github.com/raeudigerRaeffi/turbular.git
   cd turbular

2. Start the development environment:

   docker-compose -f docker-compose.dev.yml up --build

3. Test the connection:

   ./scripts/test_connection.py

Manual Installation

1. Install Python 3.11 or higher

2. Install dependencies:

   pip install -r requirements.txt

3. Run the server:

   uvicorn app.main:app --reload

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 269 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Turbular
  2. <div align="center">
  3. [![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=for-the-badge&logo=fastapi)](https://fastapi.tiangolo.com/)
  4. [![Python](https://img.shields.io/badge/python-3.11+-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org)
  5. [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](LICENSE)
  6. </div>
  7. Turbular is an open-source Model Context Protocol (MCP) server that enables seamless database connectivity for Language
  8. Models (LLMs). It provides a unified API interface to interact with various database types, making it perfect for AI
  9. applications that need to work with multiple data sources.
  10. ## ✨ Features
  11. - 🔌 **Multi-Database Support**: Connect to various database types through a single API
  12. - 🔄 **Schema Normalization**: Automatically normalize database schemas to correct naming conventions for LLM
  13. compatibility
  14. - 🔒 **Secure Connections**: Support for SSL and various authentication methods
  15. - 🚀 **High Performance**: Optimizes your LLM generated queries
  16. - 📝 **Query Transformation**: Let LLM generate queries against normalized layouts and transform them into their
  17. unnormalized form
  18. - 🐳 **Docker Support**: Easy deployment with Docker and Docker Compose
  19. - 🔧 **Easy to Extend**: Adding new database providers can be easily done by extending
  20. the [BaseDBConnector interface](app/data_oracle/connectors/baseconnector.py)
  21. ## 🗄️ Supported Databases
  22. | Database Type | Status | Icon |
  23. |---------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------|
  24. | PostgreSQL | ✅ | <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/postgresql/postgresql-original.svg" width="20" height="20"> |
  25. | MySQL | ✅ | <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/mysql/mysql-original.svg" width="20" height="20"> |
  26. | SQLite | ✅ | <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/sqlite/sqlite-original.svg" width="20" height="20"> |
  27. | BigQuery | ✅ | <img src="https://www.vectorlogo.zone/logos/google_bigquery/google_bigquery-icon.svg" width="20" height="20"> |
  28. | Oracle | ✅ | <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/oracle/oracle-original.svg" width="20" height="20"> |
  29. | MS SQL | ✅ | <img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/microsoftsqlserver/microsoftsqlserver-plain.svg" width="20" height="20"> |
  30. | Redshift | ✅ | <img src="https://cdn2.iconfinder.com/data/icons/amazon-aws-stencils/100/Database_copy_Amazon_RedShift-512.png" width="20" height="20"> |
  31. ## 🚀 Quick Start
  32. ### Using Docker (Recommended)
  33. 1. Clone the repository:
  34. ```bash
  35. git clone https://github.com/raeudigerRaeffi/turbular.git
  36. cd turbular
  37. ```
  38. 2. Start the development environment:
  39. ```bash
  40. docker-compose -f docker-compose.dev.yml up --build
  41. ```
  42. 3. Test the connection:
  43. ```bash
  44. ./scripts/test_connection.py
  45. ```
  46. ### Manual Installation
  47. 1. Install Python 3.11 or higher
  48. 2. Install dependencies:
  49. ```bash
  50. pip install -r requirements.txt
  51. ```
  52. 3. Run the server:
  53. ```bash
  54. uvicorn app.main:app --reload
  55. ```
  56. ## 🔌 API Reference
  57. ### Database Operations
  58. #### Get Database Schema
  59. ```http
  60. POST /get_schema
  61. ```
  62. Retrieve the schema of a connected database for your LLM agent.
  63. **Parameters:**
  64. - `db_info`: Database connection arguments
  65. - `return_normalize_schema` (optional): Return schema in LLM-friendly format
  66. #### Execute Query
  67. ```http
  68. POST /execute_query
  69. ```
  70. Optimizes query and then execute SQL queries on the connected database.
  71. **Parameters:**
  72. - `db_info`: Database connection arguments
  73. - `query`: SQL query string
  74. - `normalized_query`: Boolean indicating if query is normalized
  75. - `max_rows`: Maximum number of rows to return
  76. - `autocommit`: Boolean for autocommit mode
  77. ### File Management
  78. #### Upload BigQuery Key
  79. ```http
  80. POST /upload-bigquery-key
  81. ```
  82. Upload a BigQuery service account key file.
  83. **Parameters:**
  84. - `project_id`: BigQuery project ID
  85. - `key_file`: JSON key file
  86. #### Upload SQLite Database
  87. ```http
  88. POST /upload-sqlite-file
  89. ```
  90. Upload a SQLite database file.
  91. **Parameters:**
  92. - `database_name`: Name to identify the database
  93. - `db_file`: SQLite database file (.db or .sqlite)
  94. ### Utility Endpoints
  95. #### Health Check
  96. ```http
  97. GET /health
  98. ```
  99. Verify if the API is running.
  100. #### List Supported Databases
  101. ```http
  102. GET /supported-databases
  103. ```
  104. Get a list of all supported database types.
  105. ## 🔧 Development Setup
  106. 1. Fork and clone the repository
  107. 2. Create a development environment:
  108. ```bash
  109. docker-compose -f docker-compose.dev.yml up --build
  110. ```
  111. 3. The development server includes:
  112. - FastAPI server with hot reload
  113. - PostgreSQL test database
  114. - Pre-configured test data
  115. 4. Access the API documentation:
  116. - Swagger UI: http://localhost:8000/docs
  117. - ReDoc: http://localhost:8000/redoc
  118. ## 🤝 Contributing
  119. We welcome contributions! Here's how you can help:
  120. 1. Check out our [contribution guidelines](CONTRIBUTING.md)
  121. 2. Look for [open issues](https://github.com/raeudigerRaeffi/turbular/issues)
  122. 3. Submit pull requests with improvements
  123. 4. Help with documentation
  124. 5. Share your feedback
  125. ### Development Guidelines
  126. - Follow PEP 8 style guide
  127. - Write tests for new features
  128. - Update documentation as needed
  129. - Use meaningful commit messages
  130. ### Roadmap
  131. 1. Add more testing, formatting and commit hooks
  132. 2. Add SSH support for database connection
  133. 3. Add APIs as datasources using [steampipe](https://steampipe.io/)
  134. 4. Enable local schema saving for databases to which the server has already connected
  135. 5. Add more datasources (snowflake, mongodb, excel, etc.)
  136. 6. Add authentication protection to routes
  137. ## 🧪 Testing
  138. Run the test suite:
  139. ```bash
  140. pytest
  141. ```
  142. For development tests with the included PostgreSQL:
  143. ```bash
  144. ./scripts/test_connection.py
  145. ```
  146. ## 📚 Documentation
  147. - [API Documentation](docs/API.md)
  148. - [Contributing Guide](CONTRIBUTING.md)
  149. ## 📝 Connection Examples
  150. ### PostgreSQL
  151. ```python
  152. connection_info = {
  153. "database_type": "PostgreSQL",
  154. "username": "user",
  155. "password": "password",
  156. "host": "localhost",
  157. "port": 5432,
  158. "database_name": "mydb",
  159. "ssl": False
  160. }
  161. ```
  162. ### BigQuery
  163. ```python
  164. connection_info = {
  165. "database_type": "BigQuery",
  166. "path_cred": "/path/to/credentials.json",
  167. "project_id": "my-project",
  168. "dataset_id": "my_dataset"
  169. }
  170. ```
  171. ### SQLite
  172. ```python
  173. connection_info = {
  174. "type": "SQLite",
  175. "database_name": "my_database"
  176. }
  177. ```
  178. ## 🙏 Acknowledgments
  179. - FastAPI for the amazing framework
  180. - SQLAlchemy for database support
  181. - [@henryclickclack](https://github.com/henryclickclack) [Henry Albert Jupiter Hommel](https://www.linkedin.com/in/henry-hommel-304675234/?originalSubdomain=de)
  182. as Co-Developer ❤️
  183. - All our contributors and users
  184. ## 📞 Support
  185. - Create an [issue](https://github.com/raeudigerRaeffi/turbular/issues)
  186. - Email: raffael@turbular.com
  187. ---
  188. <div align="center">
  189. Made with ❤️ by the Turbular Team
  190. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.