# vectorwrap 0.3.0a2 [](https://pypi.org/project/vectorwrap/)
**One API — multiple vector databases**
Switch between PostgreSQL, MySQL, and SQLite vector backends with a single line of code. Perfect for prototyping, testing, and production deployments.
## 🚀 Quick Start
```bash
# Core install (PostgreSQL + MySQL support)
pip install vectorwrap
# Add SQLite support (requires system SQLite with extension support)
pip install "vectorwrap[sqlite]"
```
```python
from vectorwrap import VectorDB
# Your embedding function (use OpenAI, Hugging Face, etc.)
def embed(text: str) -> list[float]:
# Return your 1536-dim embeddings here
return [0.1, 0.2, ...]
# Connect to any supported database
db = VectorDB("postgresql://user:pass@host/db") # or mysql://... or sqlite:///path.db
db.create_collection("products", dim=1536)
# Insert vectors with metadata
db.upsert("products", 1, embed("Apple iPhone 15 Pro"), {"category": "phone", "price": 999})
db.upsert("products", 2, embed("Samsung Galaxy S24"), {"category": "phone", "price": 899})
# Semantic search with filtering
results = db.query(
collection="products",
query_vector=embed("latest smartphone"),
top_k=5,
filter={"category": "phone"}
)
print(results) # → [(1, 0.023), (2, 0.087)]
```
## 🗄️ Supported Backends
| Database | Vector Type | Indexing | Installation | Notes |
|----------|-------------|----------|--------------|-------|
| **PostgreSQL 16+ + pgvector** | `VECTOR(n)` | HNSW | `CREATE EXTENSION vector;` | Production ready |
| **MySQL 8.2+ HeatWave** | `VECTOR(n)` | Automatic | Built-in | Native vector support |
| **MySQL ≤8.0 (legacy)** | JSON arrays | None | Built-in | Slower, Python distance |
| **SQLite + sqlite-vss** | Virtual table | HNSW | `pip install "vectorwrap[sqlite]"` | Great for prototyping |
## 📖 Examples
### Complete Example with OpenAI Embeddings
```python
from openai import OpenAI
from vectorwrap import VectorDB
client = OpenAI()
def embed(text: str) -> list[float]:
response = client.embeddings.create(
model="text-embedding-3-small",
input=text
)
return response.data[0].embedding
# Use any database - just change the connection string!
db = VectorDB("postgresql://user:pass@localhost/vectors")
db.create_collection("documents", dim=1536)
# Add some documents
documents = [
("Python is a programming language", {"topic": "programming"}),
("Machine learning uses neural networks", {"topic": "ai"}),
("Databases store structured data", {"topic": "data"}),
]
for i, (text, metadata) in enumerate(documents):
db.upsert("documents", i, embed(text), metadata)
# Search for similar content
query = "What is artificial intelligence?"
results = db.query("documents", embed(query), top_k=2)
for doc_id, distance in results:
print(f"Document {doc_id}: distance={distance:.3f}")
```
### Database-Specific Connection Strings
```python
# PostgreSQL with pgvector
db = VectorDB("postgresql://user:password@localhost:5432/mydb")
# MySQL (8.2+ with native vectors or legacy JSON mode)
db = VectorDB("mysql://user:password@localhost:3306/mydb")
# SQLite (local file or in-memory)
db = VectorDB("sqlite:///./vectors.db")
db = VectorDB("sqlite:///:memory:")
```
## 🛠️ API Reference
### `VectorDB(connection_string: str)`
Create a vector database connection.
### `create_collection(name: str, dim: int)`
Create a new collection for vectors of dimension `dim`.
### `upsert(collection: str, id: int, vector: list[float], metadata: dict = None)`
Insert or update a vector with optional metadata.
### `query(collection: str, query_vector: list[float], top_k: int = 5, filter: dict = None)`
Find the `top_k` most similar vectors. Returns list of `(id, distance)` tuples.
**Filtering Support:**
- PostgreSQL & MySQL: Native SQL filtering
- SQLite: Adaptive oversampling (fetches more results, then filters)
## 🔧 Installation Notes
### SQLite Setup
SQLite support requires loadable extensions. On some systems you may need:
```bash
# macOS with Homebrew
brew install sqlite
export LDFLAGS="-L$(brew --prefix sqlite)/lib"
export CPPFLAGS="-I$(brew --prefix sqlite)/include"
pip install "vectorwrap[sqlite]"
# Or use system package manager
# Ubuntu: apt install libsqlite3-dev
# CentOS: yum install sqlite-devel
```
### PostgreSQL Setup
```sql
-- Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;
```
### MySQL Setup
MySQL 8.2+ has native `VECTOR` type support. For older versions, vectorwrap automatically falls back to JSON storage with Python-based distance calculations.
## 🎯 Use Cases
- **Prototyping**: Start with SQLite, scale to PostgreSQL
- **Testing**: Use SQLite in-memory databases for fast tests
- **Multi-tenant**: Different customers on different database backends
- **Migration**: Move vector data between database systems seamlessly
- **Hybrid deployments**: PostgreSQL for production, SQLite for edge computing
## 🚧 Roadmap
Coming soon:
- **DuckDB** with `duckdb-vss` extension
- **Redis** with RediSearch
- **Elasticsearch** with dense vector fields
- **Qdrant** and **Weaviate** support
- **Batch operations** for bulk inserts
- **Index configuration** options
## 📝 License
MIT © 2025 Mihir Ahuja
---
**[PyPI Package](https://pypi.org/project/vectorwrap/) • [GitHub Repository](https://github.com/mihirahuja/vectorwrap) • [Report Issues](https://github.com/mihirahuja/vectorwrap/issues)**
Raw data
{
"_id": null,
"home_page": null,
"name": "vectorwrap",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "vector, database, embeddings, similarity, search, postgresql, mysql, sqlite",
"author": null,
"author_email": "Mihir Ahuja <mihir@example.com>",
"download_url": "https://files.pythonhosted.org/packages/b5/f1/c2e1fa085a06ef10aefbd9abe9a7ab3622f31f8ebcde852e9ab07e733819/vectorwrap-0.3.0a2.tar.gz",
"platform": null,
"description": "# vectorwrap 0.3.0a2 [](https://pypi.org/project/vectorwrap/)\n\n**One API \u2014 multiple vector databases**\n\nSwitch between PostgreSQL, MySQL, and SQLite vector backends with a single line of code. Perfect for prototyping, testing, and production deployments.\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Core install (PostgreSQL + MySQL support)\npip install vectorwrap\n\n# Add SQLite support (requires system SQLite with extension support)\npip install \"vectorwrap[sqlite]\"\n```\n\n```python\nfrom vectorwrap import VectorDB\n\n# Your embedding function (use OpenAI, Hugging Face, etc.)\ndef embed(text: str) -> list[float]:\n # Return your 1536-dim embeddings here\n return [0.1, 0.2, ...] \n\n# Connect to any supported database\ndb = VectorDB(\"postgresql://user:pass@host/db\") # or mysql://... or sqlite:///path.db\ndb.create_collection(\"products\", dim=1536)\n\n# Insert vectors with metadata\ndb.upsert(\"products\", 1, embed(\"Apple iPhone 15 Pro\"), {\"category\": \"phone\", \"price\": 999})\ndb.upsert(\"products\", 2, embed(\"Samsung Galaxy S24\"), {\"category\": \"phone\", \"price\": 899})\n\n# Semantic search with filtering\nresults = db.query(\n collection=\"products\",\n query_vector=embed(\"latest smartphone\"),\n top_k=5,\n filter={\"category\": \"phone\"}\n)\nprint(results) # \u2192 [(1, 0.023), (2, 0.087)]\n```\n\n## \ud83d\uddc4\ufe0f Supported Backends\n\n| Database | Vector Type | Indexing | Installation | Notes |\n|----------|-------------|----------|--------------|-------|\n| **PostgreSQL 16+ + pgvector** | `VECTOR(n)` | HNSW | `CREATE EXTENSION vector;` | Production ready |\n| **MySQL 8.2+ HeatWave** | `VECTOR(n)` | Automatic | Built-in | Native vector support |\n| **MySQL \u22648.0 (legacy)** | JSON arrays | None | Built-in | Slower, Python distance |\n| **SQLite + sqlite-vss** | Virtual table | HNSW | `pip install \"vectorwrap[sqlite]\"` | Great for prototyping |\n\n## \ud83d\udcd6 Examples\n\n### Complete Example with OpenAI Embeddings\n\n```python\nfrom openai import OpenAI\nfrom vectorwrap import VectorDB\n\nclient = OpenAI()\n\ndef embed(text: str) -> list[float]:\n response = client.embeddings.create(\n model=\"text-embedding-3-small\",\n input=text\n )\n return response.data[0].embedding\n\n# Use any database - just change the connection string!\ndb = VectorDB(\"postgresql://user:pass@localhost/vectors\")\ndb.create_collection(\"documents\", dim=1536)\n\n# Add some documents\ndocuments = [\n (\"Python is a programming language\", {\"topic\": \"programming\"}),\n (\"Machine learning uses neural networks\", {\"topic\": \"ai\"}),\n (\"Databases store structured data\", {\"topic\": \"data\"}),\n]\n\nfor i, (text, metadata) in enumerate(documents):\n db.upsert(\"documents\", i, embed(text), metadata)\n\n# Search for similar content\nquery = \"What is artificial intelligence?\"\nresults = db.query(\"documents\", embed(query), top_k=2)\n\nfor doc_id, distance in results:\n print(f\"Document {doc_id}: distance={distance:.3f}\")\n```\n\n### Database-Specific Connection Strings\n\n```python\n# PostgreSQL with pgvector\ndb = VectorDB(\"postgresql://user:password@localhost:5432/mydb\")\n\n# MySQL (8.2+ with native vectors or legacy JSON mode) \ndb = VectorDB(\"mysql://user:password@localhost:3306/mydb\")\n\n# SQLite (local file or in-memory)\ndb = VectorDB(\"sqlite:///./vectors.db\")\ndb = VectorDB(\"sqlite:///:memory:\")\n```\n\n## \ud83d\udee0\ufe0f API Reference\n\n### `VectorDB(connection_string: str)`\nCreate a vector database connection.\n\n### `create_collection(name: str, dim: int)`\nCreate a new collection for vectors of dimension `dim`.\n\n### `upsert(collection: str, id: int, vector: list[float], metadata: dict = None)`\nInsert or update a vector with optional metadata.\n\n### `query(collection: str, query_vector: list[float], top_k: int = 5, filter: dict = None)`\nFind the `top_k` most similar vectors. Returns list of `(id, distance)` tuples.\n\n**Filtering Support:**\n- PostgreSQL & MySQL: Native SQL filtering\n- SQLite: Adaptive oversampling (fetches more results, then filters)\n\n## \ud83d\udd27 Installation Notes\n\n### SQLite Setup\nSQLite support requires loadable extensions. On some systems you may need:\n\n```bash\n# macOS with Homebrew\nbrew install sqlite\nexport LDFLAGS=\"-L$(brew --prefix sqlite)/lib\"\nexport CPPFLAGS=\"-I$(brew --prefix sqlite)/include\"\npip install \"vectorwrap[sqlite]\"\n\n# Or use system package manager\n# Ubuntu: apt install libsqlite3-dev\n# CentOS: yum install sqlite-devel\n```\n\n### PostgreSQL Setup\n```sql\n-- Enable pgvector extension\nCREATE EXTENSION IF NOT EXISTS vector;\n```\n\n### MySQL Setup\nMySQL 8.2+ has native `VECTOR` type support. For older versions, vectorwrap automatically falls back to JSON storage with Python-based distance calculations.\n\n## \ud83c\udfaf Use Cases\n\n- **Prototyping**: Start with SQLite, scale to PostgreSQL\n- **Testing**: Use SQLite in-memory databases for fast tests \n- **Multi-tenant**: Different customers on different database backends\n- **Migration**: Move vector data between database systems seamlessly\n- **Hybrid deployments**: PostgreSQL for production, SQLite for edge computing\n\n## \ud83d\udea7 Roadmap\n\nComing soon:\n- **DuckDB** with `duckdb-vss` extension\n- **Redis** with RediSearch\n- **Elasticsearch** with dense vector fields\n- **Qdrant** and **Weaviate** support\n- **Batch operations** for bulk inserts\n- **Index configuration** options\n\n## \ud83d\udcdd License\n\nMIT \u00a9 2025 Mihir Ahuja\n\n---\n\n**[PyPI Package](https://pypi.org/project/vectorwrap/) \u2022 [GitHub Repository](https://github.com/mihirahuja/vectorwrap) \u2022 [Report Issues](https://github.com/mihirahuja/vectorwrap/issues)**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "One API for vector search across Postgres (pgvector), MySQL HeatWave, and SQLite",
"version": "0.3.0a2",
"project_urls": {
"Homepage": "https://github.com/mihirahuja/vectorwrap",
"Issues": "https://github.com/mihirahuja/vectorwrap/issues",
"Repository": "https://github.com/mihirahuja/vectorwrap"
},
"split_keywords": [
"vector",
" database",
" embeddings",
" similarity",
" search",
" postgresql",
" mysql",
" sqlite"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "64e9d3d4444417cef1d7d310a36c85d87c3477b6f3b4ceda2bc1d3ea46884963",
"md5": "fbfa038feecaac3c45a030c5b93bbd30",
"sha256": "1806f91c0ec92d0f85233ffb68b98867dbb3fb51b2b3c547b4352beca64af0f8"
},
"downloads": -1,
"filename": "vectorwrap-0.3.0a2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fbfa038feecaac3c45a030c5b93bbd30",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8313,
"upload_time": "2025-07-29T04:01:03",
"upload_time_iso_8601": "2025-07-29T04:01:03.707226Z",
"url": "https://files.pythonhosted.org/packages/64/e9/d3d4444417cef1d7d310a36c85d87c3477b6f3b4ceda2bc1d3ea46884963/vectorwrap-0.3.0a2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b5f1c2e1fa085a06ef10aefbd9abe9a7ab3622f31f8ebcde852e9ab07e733819",
"md5": "f708bb161f26a0001e53fbd21da4d257",
"sha256": "fedbaa80db38b9e34d3eaa1a2d0b949a602c805e12b455389ca8eceab894a01f"
},
"downloads": -1,
"filename": "vectorwrap-0.3.0a2.tar.gz",
"has_sig": false,
"md5_digest": "f708bb161f26a0001e53fbd21da4d257",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 9886,
"upload_time": "2025-07-29T04:01:04",
"upload_time_iso_8601": "2025-07-29T04:01:04.544484Z",
"url": "https://files.pythonhosted.org/packages/b5/f1/c2e1fa085a06ef10aefbd9abe9a7ab3622f31f8ebcde852e9ab07e733819/vectorwrap-0.3.0a2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 04:01:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mihirahuja",
"github_project": "vectorwrap",
"github_not_found": true,
"lcname": "vectorwrap"
}
JSON
