SingleStoreDB Python SDK
The SingleStoreDB Python SDK provides a DB-API 2.0 compatible interface to SingleStore, a high-performance distributed SQL database designed for data-intensive applications including real-time analytics and vector search.
Key Features:
- High Performance: Includes a C extension that delivers up to 10x faster data reading compared to pure Python MySQL connectors
- Multiple Protocols: Connect via MySQL protocol (port 3306) or HTTP Data API (port 9000) using the same interface
- Flexible Result Formats: Return query results as tuples, dictionaries, named tuples, NumPy arrays, Pandas DataFrames, Polars DataFrames, or PyArrow Tables
- Deployment Management: Full API for managing SingleStore Cloud clusters, projects, regions, and files programmatically
- Vector Store: Pinecone-compatible vector database API for similarity search applications with built-in connection pooling
- User-Defined Functions: Deploy Python functions as SingleStore UDFs with automatic type mapping (HTTP/ASGI or plugin-mode via CLI)
- SQLAlchemy Support: Integrate with SQLAlchemy through the optional
sqlalchemy-singlestoredbadapter - Fusion SQL: Extend SQL with custom client-side command handlers
Install
This package can be installed from PyPI using pip:
pip install singlestoredb
Optional Dependencies
The SDK has several optional dependencies for additional functionality:
# Vector store support (Pinecone-compatible API)
pip install 'singlestoredb[vectorstore]'
# SQLAlchemy integration
pip install 'singlestoredb[sqlalchemy]'
# dbt adapter
pip install 'singlestoredb[dbt]'
# Kerberos/GSSAPI authentication
pip install 'singlestoredb[kerberos]'
# RSA key authentication
pip install 'singlestoredb[rsa]'
# Ed25519 key authentication
pip install 'singlestoredb[ed22519]'
# Pytest plugin with Docker test containers
pip install 'singlestoredb[pytest,docker]'
# Multiple extras can be combined
pip install 'singlestoredb[vectorstore,sqlalchemy]'
| Extra | Description |
|---|---|
vectorstore |
Vector database functionality via singlestore-vectorstore |
sqlalchemy |
SQLAlchemy dialect via sqlalchemy-singlestoredb |
ibis / dataframe |
Ibis dataframe interface (SingleStore is natively supported in Ibis) |
dbt |
dbt adapter via dbt-singlestore |
kerberos / gssapi |
Kerberos/GSSAPI authentication support |
rsa |
RSA key exchange for encrypted connections |
ed22519 |
Ed25519 key authentication |
docker |
Docker SDK for automated test container management |
pytest |
Pytest plugin with SingleStoreDB Docker test fixtures |
Documentation
https://singlestore-labs.github.io/singlestoredb-python
Usage
Connections to the SingleStore database are made using the DB-API parameters
host, port, user, password, etc, but they may also be done using
URLs that specify these parameters as well (much like the
SQLAlchemy package).
import singlestoredb as s2
# Connect using the default connector
conn = s2.connect('user:password@host:3306/db_name')
# Create a cursor
cur = conn.cursor()
# Execute SQL
cur.execute('select * from foo')
# Fetch the results
print(cur.description)
for item in cur:
print(item)
# Close the connection
conn.close()
Connecting to the HTTP API is done as follows:
# Use the HTTP API connector
conn = s2.connect('https://user:password@host:8080/db_name')
Configuration
Connection parameters can be set through environment variables, programmatically, or via URL. Environment variables are useful for keeping credentials out of code.
Environment Variables
Key environment variables include:
SINGLESTOREDB_URL: Full connection URLSINGLESTOREDB_HOST: Database hostnameSINGLESTOREDB_PORT: Database portSINGLESTOREDB_USER: UsernameSINGLESTOREDB_PASSWORD: PasswordSINGLESTOREDB_DATABASE: Default database nameSINGLESTOREDB_PURE_PYTHON: Set to1to disable C acceleration
Programmatic Configuration
Options can be set and retrieved using get_option, set_option, and option_context:
import singlestoredb as s2
# Get current option value
current_host = s2.get_option('host')
# Set an option
s2.set_option('results_type', 'pandas')
# Temporarily override options using a context manager
with s2.option_context('results_type', 'dicts'):
conn = s2.connect()
# results will be returned as dicts within this block
Result Formats
Query results can be returned in various formats using the results_type parameter
or option. Supported formats include:
tuples(default): Standard Python tuplesnamedtuples: Named tuples with column names as attributesdicts: Dictionaries with column names as keysnumpy: NumPy arrayspandas: Pandas DataFramespolars: Polars DataFramesarrow: PyArrow Tables
import singlestoredb as s2
conn = s2.connect('user:password@host/db_name')
cur = conn.cursor()
# Return results as dictionaries
cur.execute('SELECT * FROM customers', results_type='dicts')
for row in cur:
print(row['customer_name'])
# Return results as a Pandas DataFrame
cur.execute('SELECT * FROM customers', results_type='pandas')
df = cur.fetchone()
Management API
The SDK provides a management API for managing SingleStore deployments programmatically. This includes creating and managing clusters, projects, regions, and files.
import singlestoredb as s2
# Get a cluster manager (uses SINGLESTOREDB_MANAGEMENT_TOKEN env var by default)
manager = s2.manage_clusters()
# List all clusters
for c in manager.clusters:
print(c.name, c.state)
# Create a new cluster
c = manager.create_cluster(
name='my-cluster',
region='US West 2 (Oregon)',
size='S-00',
)
The API is versioned, and version 2 — the flat Cluster resource shown above —
is the default. Version 1, which called a deployment a Workspace inside a
WorkspaceGroup and is reached through s2.manage_workspaces(), still works
but is deprecated in its entirety. Select a version with the
management.version option (SINGLESTOREDB_MANAGEMENT_VERSION) or by passing
version= to any manage_* function.
See the API documentation for full details on cluster, project, region, and file management.
Vector Store
The SDK includes vector database functionality for similarity search
applications. This requires the singlestore-vectorstore package.
import singlestoredb as s2
# Create a vector database connection with connection pooling
vdb = s2.vector_db(
'user:password@host/db_name',
pool_size=5, # Number of connections in pool
max_overflow=10, # Maximum extra connections
timeout=30, # Connection acquisition timeout
)
# Use vector operations
index = vdb.get_or_create_index('my_index', dimension=768)
The vector_db function returns a VectorDB instance that provides
Pinecone-compatible operations for vector similarity search.
Fusion SQL
Fusion SQL extends the SQL commands handled by the client with custom handlers. These commands are processed locally rather than sent to the database server. Built-in handlers provide SQL-like commands for managing clusters, running notebook jobs, and more.
import os
os.environ['SINGLESTOREDB_FUSION_ENABLED'] = '1'
import singlestoredb as s2
conn = s2.connect()
# Show available cloud regions
conn.execute('SHOW CLUSTER REGIONS')
# List clusters
conn.execute('SHOW CLUSTERS EXTENDED')
# Create a new cluster
conn.execute("""
CREATE CLUSTER 'analytics-team'
IN REGION 'US West 2 (Oregon)'
WITH SIZE 'S-00'
WITH FIREWALL RANGES '10.0.0.0/8'
""")
The WORKSPACE and WORKSPACE GROUP commands, and the version-less
SHOW REGIONS, still work but are deprecated along with the rest of management
API v1.
See singlestoredb/fusion/README.md for details on writing custom Fusion SQL handlers.
Pytest Plugin
The SDK includes a pytest plugin that automatically manages SingleStoreDB Docker containers for integration testing. Install with:
pip install 'singlestoredb[pytest,docker]'
The plugin provides these fixtures:
singlestoredb_test_container(session-scoped): Starts and stops a SingleStoreDB Dev container, or reuses an existing server ifSINGLESTOREDB_URLis setsinglestoredb_connection(session-scoped): Database connection to the test containersinglestoredb_tempdb(function-scoped): Cursor with a fresh temporary database, dropped after the test
The plugin supports pytest-xdist parallel execution with leader/follower
coordination for container lifecycle.
def test_query(singlestoredb_tempdb):
singlestoredb_tempdb.execute('CREATE TABLE t (id INT)')
singlestoredb_tempdb.execute('INSERT INTO t VALUES (1)')
singlestoredb_tempdb.execute('SELECT * FROM t')
assert singlestoredb_tempdb.fetchone() == (1,)
Plugin UDF Server
The SDK ships a high-performance plugin-mode UDF server that runs as a standalone process, communicating with SingleStoreDB over a Unix socket.
# Via the installed CLI entry point
python-udf-server --plugin-name myfuncs --search-path /path/to/modules
# Or as a Python module
python -m singlestoredb.functions.ext.plugin --plugin-name myfuncs
| Option | Env Variable | Default | Description |
|---|---|---|---|
--plugin-name |
PLUGIN_NAME |
(required) | Python module to import |
--search-path |
PLUGIN_SEARCH_PATH |
"" |
Colon-separated module search dirs |
--socket |
PLUGIN_SOCKET_PATH |
auto-generated | Unix socket path |
--n-workers |
PLUGIN_N_WORKERS |
0 (CPU count) |
Worker threads/processes |
--max-connections |
PLUGIN_MAX_CONNECTIONS |
32 |
Socket backlog |
--log-level |
PLUGIN_LOG_LEVEL |
info |
Logging level |
--process-mode |
PLUGIN_PROCESS_MODE |
process |
thread or process concurrency |
Advanced Options
SSL/TLS Configuration
SSL connections can be configured using connection parameters or environment variables:
conn = s2.connect(
'user:password@host/db_name',
ssl_ca='/path/to/ca.pem',
ssl_cert='/path/to/client-cert.pem',
ssl_key='/path/to/client-key.pem',
)
Other Connection Options
conn = s2.connect(
'user:password@host/db_name',
# Performance options
pure_python=False, # Set True to disable C acceleration
buffered=True, # Buffer entire result set in memory
# Data handling
autocommit=True, # Enable autocommit mode
local_infile=True, # Allow LOAD DATA LOCAL INFILE
nan_as_null=True, # Treat NaN as NULL in parameters
inf_as_null=True, # Treat Inf as NULL in parameters
# Extended types
enable_extended_data_types=True, # Enable BSON and vector types
vector_data_format='binary', # Vector format: 'json' or 'binary'
# Connection behavior
connect_timeout=10, # Connection timeout in seconds
multi_statements=True, # Allow multiple statements per query
)
Performance
While this package is based on PyMySQL which is a pure Python-based MySQL connector, it adds various performance enhancements that make it faster than most other connectors. The performance improvements come from changes to the data conversion functions, cursor implementations, and a C extension that is highly optimized to improve row data reading.
The package can be used both in a pure Python mode and as well as a C accelerated mode. Generally speaking, the C accelerated version of the client can read data 10X faster than PyMySQL, 2X faster than MySQLdb, and 1.5X faster than mysql.connector. All of this is done without having to install any 3rd party MySQL libraries!
Benchmarking was done with a table of 3,533,286 rows each containing a datetime,
a float, and eight character columns. The data is the same data set used in
this article.
The client and server were running on the same machine and queries were made
using fetchone, fetchall, fetchmany(1000), and an iterator over the cursor
object (e.g., iter(cur)). The results are shown below.
Buffered
| PyMySQL | MySQLdb | mysql.connector | SingleStore (pure Python) | SingleStore | |
|---|---|---|---|---|---|
| fetchall | 37.0s | 8.7s | 5.6s | 29.0s | 3.7s |
| fetchmany(1000) | 37.4s | 9.2s | 6.2s | 29.6s | 3.6s |
| fetchone | 38.2s | 10.1s | 10.2s | 30.9s | 4.8s |
| iter(cur) | 38.3s | 9.1s | 10.2s | 30.4s | 4.4s |
Unbuffered
| PyMySQL | MySQLdb | mysql.connector | SingleStore (pure Python) | SingleStore | |
|---|---|---|---|---|---|
| fetchall | 39.0s | 6.5s | 5.5s | 30.3s | 5.5s |
| fetchmany(1000) | 39.4s | 7.0s | 6.0s | 30.4s | 4.1s |
| fetchone | 34.5s | 8.9s | 10.1s | 30.8s | 6.6s |
| iter(cur) | 39.0s | 9.0s | 10.2s | 31.4s | 6.0s |
License
This library is licensed under the Apache 2.0 License.
Resources
Metadata
Release files for singlestoredb 1.18.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| singlestoredb-1.18.0.tar.gz | 617.1 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| singlestoredb-1.18.0-py3-none-any.whl | Python 3 | none | any | Details |
| singlestoredb-1.18.0-cp38-abi3-win_amd64.whl | CPython 3.8 | abi3 | Windows x86-64 | Details |
| singlestoredb-1.18.0-cp38-abi3-win32.whl | CPython 3.8 | abi3 | Windows x86-32 | Details |
| singlestoredb-1.18.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.8 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| singlestoredb-1.18.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.8 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| singlestoredb-1.18.0-cp38-abi3-macosx_10_9_universal2.whl | CPython 3.8 | abi3 | macOS 10.9+ universal2 (ARM64, x86-64) | Details |
Total release size: 6.4 MB
Release files / singlestoredb-1.18.0.tar.gz
| Download URL | singlestoredb-1.18.0.tar.gz |
|---|---|
| Size | 617.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0cd13cb2783228ced229ce5e5dbd33417da35dae7b5c86d6d5d76044418cc4b0
|
|
BLAKE2b-256 checksum How to use checksums |
5dba23710582484b59d297918201ee7957733dbafed7b3a86d65c8ba87272ba7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / singlestoredb-1.18.0-py3-none-any.whl
| Download URL | singlestoredb-1.18.0-py3-none-any.whl |
|---|---|
| Size | 675.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ff1b383cb57844239c7d664b1199219a1da20480ffb27d25b3c2b0b5b884dafe
|
|
BLAKE2b-256 checksum How to use checksums |
03b9473fb22aa1bb403db607030edf249c42152bdab9c7a87ca3ff4be0d89641
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / singlestoredb-1.18.0-cp38-abi3-win_amd64.whl
| Download URL | singlestoredb-1.18.0-cp38-abi3-win_amd64.whl |
|---|---|
| Size | 714.9 kB |
| Tags | CPython 3.8 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
f4d012b4d25d419d9190e47e45b3cc1792ef3c285393a79ad57940ec0589a7b7
|
|
BLAKE2b-256 checksum How to use checksums |
8f394b5b590cee1ff409cf2c889b90841d8edf412a8a7444173360908e9a058d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / singlestoredb-1.18.0-cp38-abi3-win32.whl
| Download URL | singlestoredb-1.18.0-cp38-abi3-win32.whl |
|---|---|
| Size | 717.3 kB |
| Tags | CPython 3.8 Windows x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
72de660aa7ac063ceba3cfb51a5cc48a642dd88c65e0620256bb1e259983ddbf
|
|
BLAKE2b-256 checksum How to use checksums |
fb3722fe297dd94621a7110167a015b78cae5e91b9181222b40836dde199c6d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / singlestoredb-1.18.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | singlestoredb-1.18.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
ecaccdcff7927641dc3982b514df4d88cbf26be8d7c4f4a0a87169e1db2fb2d6
|
|
BLAKE2b-256 checksum How to use checksums |
3e16abdcc8afd07114b136f81066ad1959715ee706e2f71244aacd661c4ae70e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / singlestoredb-1.18.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | singlestoredb-1.18.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
38ba0557324ce19e0613579af892f3861ac7dfa07e738d40d0a95d5f6b833283
|
|
BLAKE2b-256 checksum How to use checksums |
751d4b65aecbfd7dc0a907e9bd17e96fb126198d48596cf13a70c2bd26ff8cf0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / singlestoredb-1.18.0-cp38-abi3-macosx_10_9_universal2.whl
| Download URL | singlestoredb-1.18.0-cp38-abi3-macosx_10_9_universal2.whl |
|---|---|
| Size | 747.3 kB |
| Tags | CPython 3.8 abi3 macOS 10.9+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
69473d5242bb77db3efba5ab43b60da0235e2fb6a4c76a5b3e3c2ceeab13b9b9
|
|
BLAKE2b-256 checksum How to use checksums |
7f266f2be08dcfd67f51d863b28544cdc55a0142e3d3291661cbac597d98009c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency log
