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
  • Workspace Management: Full API for managing SingleStore Cloud workspaces, clusters, 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-singlestoredb adapter
  • 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 URL
  • SINGLESTOREDB_HOST: Database hostname
  • SINGLESTOREDB_PORT: Database port
  • SINGLESTOREDB_USER: Username
  • SINGLESTOREDB_PASSWORD: Password
  • SINGLESTOREDB_DATABASE: Default database name
  • SINGLESTOREDB_PURE_PYTHON: Set to 1 to 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 tuples
  • namedtuples: Named tuples with column names as attributes
  • dicts: Dictionaries with column names as keys
  • numpy: NumPy arrays
  • pandas: Pandas DataFrames
  • polars: Polars DataFrames
  • arrow: 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 workspace management API for managing SingleStore deployments programmatically. This includes creating and managing workspaces, clusters, regions, and files.

import singlestoredb as s2

# Get a workspace manager (uses SINGLESTOREDB_MANAGEMENT_TOKEN env var by default)
manager = s2.manage_workspaces()

# List all workspaces
for ws in manager.workspaces:
    print(ws.name, ws.state)

# Create a new workspace
ws = manager.workspaces.create(
    name='my-workspace',
    workspace_group_id='<group-id>',
)

See the API documentation for full details on workspace, cluster, 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 workspaces, 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 REGIONS')

# List workspace groups
conn.execute('SHOW WORKSPACE GROUPS')

# List workspaces in a specific group
conn.execute("SHOW WORKSPACES IN GROUP 'my-group' EXTENDED")

# Create a new workspace group
conn.execute("""
    CREATE WORKSPACE GROUP 'analytics-team'
    IN REGION 'US West 2 (Oregon)'
    WITH PASSWORD 'my-password'
    WITH FIREWALL RANGES '10.0.0.0/8'
""")

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 if SINGLESTOREDB_URL is set
  • singlestoredb_connection (session-scoped): Database connection to the test container
  • singlestoredb_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

Project links

Data verified by PyPI on Sep 11, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: SingleStore

GitHub Statistics

Data verified by PyPI on Sep 11, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache-2.0

Requires

Python >=3.9

Provides Extra

dataframe dbt docker ed22519 gssapi ibis kerberos pytest rsa sqlalchemy vectorstore test docs build dev

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

singlestoredb-1.17.3.tar.gz (438.7 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

singlestoredb-1.17.3-py3-none-any.whl (483.8 kB view details)

Uploaded Python 3

singlestoredb-1.17.3-cp38-abi3-win_amd64.whl (521.8 kB view details)

Uploaded CPython 3.8+Windows x86-64

singlestoredb-1.17.3-cp38-abi3-win32.whl (524.1 kB view details)

Uploaded CPython 3.8+Windows x86

singlestoredb-1.17.3-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ x86-64

singlestoredb-1.17.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ ARM64

singlestoredb-1.17.3-cp38-abi3-macosx_10_9_universal2.whl (554.9 kB view details)

Uploaded CPython 3.8+macOS 10.9+ universal2 (ARM64, x86-64)

File details

Details for the file singlestoredb-1.17.3.tar.gz.

File metadata

  • Download URL: singlestoredb-1.17.3.tar.gz
  • Upload date:
  • Size: 438.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for singlestoredb-1.17.3.tar.gz
Algorithm Hash digest
SHA256 3b2225622fdd091f1e39f6cca539ec5edb66fac8fcc04bc49f12f78fb25bf635
MD5 bf1c30513785545122c669b76401f973
BLAKE2b-256 fa3eca4feb3546740f4320e0d39c6ded76607c1b3922464a345ee74f0830c149

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.3.tar.gz:

Publisher: publish.yml on singlestore-labs/singlestoredb-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file singlestoredb-1.17.3-py3-none-any.whl.

File metadata

  • Download URL: singlestoredb-1.17.3-py3-none-any.whl
  • Upload date:
  • Size: 483.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for singlestoredb-1.17.3-py3-none-any.whl
Algorithm Hash digest
SHA256 e7dd5c71ec3ad963c5be410b8afd667e1009d99644e6da335771c0aa4ee7b7f0
MD5 6504e18af99f3be194e55bd82f97ebe9
BLAKE2b-256 18ae49b78a722646a6d6c34d273837bdda6b7a8b0baf2815f93ee89a524fde17

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.3-py3-none-any.whl:

Publisher: publish.yml on singlestore-labs/singlestoredb-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file singlestoredb-1.17.3-cp38-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for singlestoredb-1.17.3-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 878b5ab6a31126b7672adaf681bd200b96c4a51f4b0f6cc8fb09420bc678efd6
MD5 0ef5d8f1a267e31997b0275664780683
BLAKE2b-256 ffa11befe6f77ccc989f881057d65ca5f48ee1beed7ea836e1d20d651f6ddeea

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.3-cp38-abi3-win_amd64.whl:

Publisher: publish.yml on singlestore-labs/singlestoredb-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file singlestoredb-1.17.3-cp38-abi3-win32.whl.

File metadata

  • Download URL: singlestoredb-1.17.3-cp38-abi3-win32.whl
  • Upload date:
  • Size: 524.1 kB
  • Tags: CPython 3.8+, Windows x86
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for singlestoredb-1.17.3-cp38-abi3-win32.whl
Algorithm Hash digest
SHA256 dbd79df2bda832478d632413dc87dddfcc1415b87cad62a6e17bd47031d952a2
MD5 14fe8ebfa2accf804c428ce39506fb97
BLAKE2b-256 712aca861386f6396c499cda1a8f9784bddd04bf0abc462e69aa308262e70799

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.3-cp38-abi3-win32.whl:

Publisher: publish.yml on singlestore-labs/singlestoredb-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file singlestoredb-1.17.3-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for singlestoredb-1.17.3-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9c4a4448a71f4e680b3d04d2fdbc9734709abf1ef998f019fc464721453e73a3
MD5 609d5dab8b9ec20277596059f0c265ec
BLAKE2b-256 1655c50cfe9700540e2a32b6058e7a60e8e6ee8f842e54fa3e951df6884a63b3

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.3-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on singlestore-labs/singlestoredb-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file singlestoredb-1.17.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for singlestoredb-1.17.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 08a750b79bac1b397c7e4284bcae2748099751cfc22e98079a1f8c61c5dadae3
MD5 ae2acce232c160785d6799141e6e8783
BLAKE2b-256 e67f6e6574e88d6586500c3df0eaa62f407b36fb4fceb1e106a8122d2a3ad2ce

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish.yml on singlestore-labs/singlestoredb-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file singlestoredb-1.17.3-cp38-abi3-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for singlestoredb-1.17.3-cp38-abi3-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 bc9076aeb1b45f89956c46804e6411c12f288b8486d382f12e0feddf657538e3
MD5 0cf42ad10e11c2a4551054339c81f6f2
BLAKE2b-256 39eb9275d8d535ca22722afc99d2fe62115185e441871b2597babce49adf135a

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.3-cp38-abi3-macosx_10_9_universal2.whl:

Publisher: publish.yml on singlestore-labs/singlestoredb-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.17.3 This release

7 files

1.17.2

7 files

1.17.1

7 files

1.17.0

7 files

1.16.10

7 files

1.16.9

7 files

1.16.8

7 files

1.16.7

7 files

1.16.6

7 files

1.16.5

7 files

1.16.4

7 files

1.16.3

7 files

1.16.2

7 files

1.16.1

7 files

1.16.0

7 files

1.15.8

7 files

1.15.7

7 files

1.15.6

7 files

1.15.5

7 files

1.15.4

7 files

1.15.3

7 files

1.15.2

7 files

1.15.1

7 files

1.15.0

7 files

1.14.2

7 files

1.14.1

7 files

1.14.0

7 files

1.13.1

7 files

1.13.0

7 files

1.12.4

7 files

1.12.3

7 files

1.12.2

7 files

1.12.1

7 files

1.12.0

7 files

1.11.0

7 files

1.10.0

7 files

1.9.0

7 files

1.8.0

7 files

1.7.2

7 files

1.7.1

7 files

1.7.0

7 files

1.6.3

7 files

1.6.2

7 files

1.6.1

7 files

1.6.0

7 files

1.5.0

7 files

1.4.3

7 files

1.4.2

7 files

1.4.1

7 files

1.4.0

7 files

1.3.1

7 files

1.3.0

7 files

1.2.0

7 files

1.1.0

7 files

1.0.4

7 files

1.0.3

7 files

1.0.2

6 files

1.0.1

6 files

1.0.0

6 files

0.10.7

6 files

0.10.6

6 files

0.10.5

6 files

0.10.4

6 files

0.10.3

6 files

0.10.2

6 files

0.10.1

6 files

0.10.0

6 files

0.9.6

6 files

0.9.5

6 files

0.9.4

6 files

0.9.3

6 files

0.9.2

6 files

0.9.1

6 files

0.9.0

6 files

0.8.9

6 files

0.8.8

6 files

0.8.7

6 files

0.8.6

6 files

0.8.5

6 files

0.8.4

6 files

0.8.3

6 files

0.8.2

6 files

0.8.1

6 files

0.8.0

6 files

0.7.3

6 files

0.7.2

6 files

0.7.1

6 files

0.7.0

6 files

0.6.1

6 files

0.6.0

6 files

0.5.4

6 files

0.5.3

6 files

0.5.2

6 files

0.5.1

6 files

0.5.0

6 files

0.4.0

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.0

2 files

0.0.0

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page