English | 中文README

LangChain – Volcengine MySQL Ecosystem

A unified, lightweight adapter package for LangChain users who work with MySQL in Volcengine environments. It provides one import surface for two powerful, externally-available database backends:

• veDB for MySQL: A cloud-native, high-performance database service from Volcengine.
• RDS for MySQL: A fully managed, stable, and scalable relational database service.

Both adapters are bundled in this package, offering a consistent, attribute-style API for creating and using vector stores and retrievers.

Overview

Official docs: veDB for MySQL · RDS for MySQL

This package simplifies using veDB for MySQL and RDS for MySQL as vector stores in LangChain applications. It abstracts the backend-specific details and provides a clean, unified interface.

• For veDB for MySQL: It leverages the vedbsearch client library for efficient vector search.
• For RDS for MySQL: It utilizes the native vector indexing and search capabilities available in recent versions.

Features

• Unified API: A single package to interact with both veDB for MySQL and RDS for MySQL.

• Attribute-style Access: Use vedb.vector_store and mysql.vector_store to get configured vector store instances.

• Easy Configuration: Configure database connections and embedding functions with configure() and set_embedding().

• Standard LangChain Integration: Fully compatible with the LangChain ecosystem, including chains and other components.

Installation

Install the unified SDK:

pip install langchain-volcengine-mysql

This single installation includes all necessary components to connect to both veDB for MySQL and RDS for MySQL.

Import Style & Backend Selection

Select the backend by importing the corresponding submodule and configuring defaults.

# veDB for MySQL
from langchain_volcengine_mysql import vedb
vedb.configure(host="...", user="...", password="...", database="...", table_name="...", embedding_function=embeddings)
vector_store = vedb.vector_store
retriever = vedb.retriever

# RDS for MySQL
from langchain_volcengine_mysql import mysql
mysql.configure(host="...", user="...", password="...", database="...", table_name="...", embedding_function=embeddings)
vector_store = mysql.vector_store
retriever = mysql.retriever

Quickstart

Choose a backend by importing the corresponding submodule. Then, configure it and access the vector_store or retriever attributes.

Vector Store (veDB for MySQL)

from langchain_core.embeddings import FakeEmbeddings
from langchain_volcengine_mysql import vedb

# 1. Configure the connection and embedding function
embeddings = FakeEmbeddings(size=768)
vedb.configure(
    host="your-vedb-host.example.com",
    port=3306,
    user="your_user",
    password="your_password",
    database="your_db",
    table_name="vector_embeddings",
    embedding_dim=768,
    embedding_function=embeddings,
)

# 2. Access the vector store and retriever
vector_store = vedb.vector_store
retriever = vedb.retriever

# 3. Add texts and perform searches
vector_store.add_texts(
    [
        "veDB for MySQL is a cloud-native database in Volcengine.",
        "LangChain is a framework for building LLM applications.",
    ],
    metadatas=[{"source": "doc1"}, {"source": "doc2"}],
)

# Similarity search via vector store
results = vector_store.similarity_search("What is veDB?", k=1)
print(results)

# Retriever usage: fetch relevant documents
docs = retriever.get_relevant_documents("What is veDB?")
print([d.page_content for d in docs])

Vector Store (RDS for MySQL)

from langchain_core.embeddings import FakeEmbeddings
from langchain_volcengine_mysql import mysql

# 1. Configure the connection and embedding function
embeddings = FakeEmbeddings(size=1024)
mysql.configure(
    host="your-mysql-host.example.com",
    port=3306,
    user="your_user",
    password="your_password",
    database="your_db",
    table_name="langchain_vectors",
    embedding_function=embeddings,
)

# 2. Access the vector store and retriever
vector_store = mysql.vector_store
retriever = mysql.retriever

# 3. Add texts and perform searches
vector_store.add_texts(
    ["Example sentence one.", "Example sentence two."],
    metadatas=[{"source": "demo1"}, {"source": "demo2"}],
)

# Similarity search via vector store
print(vector_store.similarity_search("Example", k=2))

# Retriever usage: fetch relevant documents
docs = retriever.get_relevant_documents("Example")
print([d.page_content for d in docs])

Configuration

Configuration is handled at the module level using the configure() function.

Configuration Parameters

Parameter	Type	Description	veDB	RDS
host	str	Database host.	✅	✅
port	int	Database port.	✅	✅
user	str	Database user.	✅	✅
password	str	Database password.	✅	✅
database	str	Database name.	✅	✅
table_name	str	Table for storing vectors.	✅	✅
embedding_function	Embeddings	LangChain embeddings model.	✅	✅
embedding_dim	int	Dimension of the vectors.	✅	❌
index_name	str	Name of the vector index.	❌	✅
distance	MySQLVectorDistance or str	Distance metric for search.	❌	✅

Environment Variables

As an alternative to configure(), you can set environment variables for the connection parameters. The embedding_function must still be set using set_embedding().

Getting a Volcano Engine Account & veDB/RDS for MySQL (Quick Guide)

• Sign up or log in to the Volcano Engine Console.
• Enable the veDB for MySQL or RDS for MySQL service.
• Create a MySQL-compatible instance.
• Note your connection info: host, port, database, user, password.
• Configure IP allowlist and TLS if required.
• Map these values into the SDK via vedb.configure(...) / mysql.configure(...).

# veDB for MySQL
from langchain_volcengine_mysql import vedb
vedb.configure(
    host="vedb-host.example.com",
    port=3306,
    user="admin",
    password="***",
    database="app_db",
    table_name="vectors",
    embedding_function=embeddings,
)

# RDS for MySQL
from langchain_volcengine_mysql import mysql
mysql.configure(
    host="rds-host.example.com",
    port=3306,
    user="admin",
    password="***",
    database="app_db",
    table_name="vectors",
    embedding_function=embeddings,
)

For full provisioning steps and pricing, refer to Volcano Engine official docs.

API Reference

Submodules

• langchain_volcengine_mysql.vedb:

  • vector_store: Attribute to get a configured VectorStore instance.
  • retriever: Attribute to get a configured VectorStoreRetriever.
  • configure(**config): Sets the default configuration for the module.
  • set_embedding(embedding_function): Sets the embedding function.

• langchain_volcengine_mysql.mysql:

  • vector_store: Attribute to get a configured VectorStore instance.
  • retriever: Attribute to get a configured VectorStoreRetriever.
  • configure(**config): Sets the default configuration for the module.
  • set_embedding(embedding_function): Sets the embedding function.

Advanced Usage

Using the Retriever with Chains

The retriever can be seamlessly integrated into LangChain chains.

from langchain.chains import RetrievalQA
from langchain_community.llms import FakeStreamingLLM

# Assuming `mysql.retriever` is already configured
retriever = mysql.retriever

# Create a QA chain
qa_chain = RetrievalQA.from_chain_type(
    llm=FakeStreamingLLM(),
    chain_type="stuff",
    retriever=retriever,
)

# Run the chain
question = "What is an example sentence?"
response = qa_chain.run(question)
print(response)

Schema and Index Management (RDS for MySQL)

The RDS for MySQL vector store provides helper methods to manage the database schema and vector index.

# Create the table and HNSW index
vector_store.create_schema(
    table_name="my_documents",
    vector_size=1024,
    algorithm_params={"distance": "l2", "M": 16, "ef_construction": 100},
)

# Drop the index
vector_store.drop_index()

# Drop the table
vector_store.drop_table()

Troubleshooting

• ConfigError: Raised if required configuration parameters are missing when accessing vector_store or retriever. Ensure you have called configure() with all necessary parameters.
• Connection Issues: Verify that the host, port, user, password, and database are correct and that the network connection to the database is allowed.
• veDB Dependencies: The veDB adapter relies on the vedbsearch client library. If you encounter issues, ensure it is correctly installed and configured in your environment.

Security

If you discover a potential security issue in this project, please notify ByteDance Security via our security center or by emailing sec@bytedance.com. Please do not create a public GitHub issue.

Code of Conduct

Please see the CODE_OF_CONDUCT.md file for details.

Contributing

Please see the CONTRIBUTING.md file for details.

License

This project is licensed under the Apache-2.0 License.