Skip to main content

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

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.2.tar.gz (437.5 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.2-py3-none-any.whl (482.4 kB view details)

Uploaded Python 3

singlestoredb-1.17.2-cp38-abi3-win_amd64.whl (520.3 kB view details)

Uploaded CPython 3.8+Windows x86-64

singlestoredb-1.17.2-cp38-abi3-win32.whl (522.6 kB view details)

Uploaded CPython 3.8+Windows x86

singlestoredb-1.17.2-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.2-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.2-cp38-abi3-macosx_10_9_universal2.whl (553.5 kB view details)

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

File details

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

File metadata

  • Download URL: singlestoredb-1.17.2.tar.gz
  • Upload date:
  • Size: 437.5 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.2.tar.gz
Algorithm Hash digest
SHA256 6ae7a0defa59001327f5b13a7112532a0733b2f2ca5d2ff61de7da54296f3fe8
MD5 e6a4efaf5978977e631a889f8413ebec
BLAKE2b-256 06d4d3f15faab2389901b4da22579fd2cdae0f0cc2948c07852b1d5e8423846d

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.2.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.2-py3-none-any.whl.

File metadata

  • Download URL: singlestoredb-1.17.2-py3-none-any.whl
  • Upload date:
  • Size: 482.4 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.2-py3-none-any.whl
Algorithm Hash digest
SHA256 8ed8d8970f228c4cfd707cbdfeaa529017fa1760a4cbf6e73fa4c25317e0db30
MD5 1fc5a3b75308ea39b9d85aa3f3380927
BLAKE2b-256 acaff9b7498f59a73de3ca1cee7a1c5bb7c3d971e14dc15cda35cf306054294d

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.2-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.2-cp38-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for singlestoredb-1.17.2-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 fed17104d6d2218b2eac4d1594e3fe67c326c74293bb469e6f918ae4ed357e3a
MD5 177e4fe11297740dfea38758073f451b
BLAKE2b-256 7d8e57ee7405e383fcdecae4f7f6d44f076c1f2844a7aa0fff127aced666e4cb

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.2-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.2-cp38-abi3-win32.whl.

File metadata

  • Download URL: singlestoredb-1.17.2-cp38-abi3-win32.whl
  • Upload date:
  • Size: 522.6 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.2-cp38-abi3-win32.whl
Algorithm Hash digest
SHA256 0063b8420b1d28363e688417b933863166e508e5a307b1791359dbf8171f4c2c
MD5 8d06efd5d467633c2ed8798822206aed
BLAKE2b-256 2627c5604980599b5f65b1c2919d94c6588ef5fa5099abe0799ce4d505e33a9f

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.2-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.2-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for singlestoredb-1.17.2-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e1d4b0ba7bc6adb78305e58d8d0dd17546ae16be9c36259d41b0defdea6d91e2
MD5 56c328b0fab16ccc93e8ce7d09d38e9c
BLAKE2b-256 97420fd208e63998b399df9f6502d0bde3008f6534375b02f9b8e78aeb100dc2

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.2-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.2-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for singlestoredb-1.17.2-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 863bc4874819ebc464391716e71ece35ab2b3135a03c762311752ad0f5cfca46
MD5 f827b9d8d544d493b33eb3ff6a6e31a6
BLAKE2b-256 79cb9ca907822a71102e4b8cdd49b6a6bfa81d6eeabe4a005d89184ff75e7848

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.2-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.2-cp38-abi3-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for singlestoredb-1.17.2-cp38-abi3-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 6d42833561ee96a94e1c091530ebdb57f30d81095f083837a737ef125aa9e36e
MD5 da285a84a4162c31575494b35d757b69
BLAKE2b-256 93ca22cec05f5452c1ba60ba16815e8197693a28e13615d6d26d59078be7bf7e

See more details on using hashes here.

Provenance

The following attestation bundles were made for singlestoredb-1.17.2-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.2 This release

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