{"id":5479,"library":"singlestoredb","title":"SingleStoreDB Python Client","description":"The SingleStoreDB Python Client is a DB-API 2.0 compliant database connector that provides an interface to the SingleStoreDB database and its workspace management APIs. It supports Python 3.9+ and is designed for high-performance interactions with SingleStoreDB, including real-time analytics and vector search. The library maintains a frequent release cadence, typically with minor updates and patches released monthly or bi-monthly.","status":"active","version":"1.16.9","language":"en","source_language":"en","source_url":"https://github.com/singlestore-labs/singlestoredb-python","tags":["database","sql","singlestoredb","client","db-api","orm"],"install":[{"cmd":"pip install singlestoredb","lang":"bash","label":"Install core client"},{"cmd":"pip install 'singlestoredb[sqlalchemy]'","lang":"bash","label":"Install with SQLAlchemy support"},{"cmd":"pip install 'singlestoredb[dataframe]'","lang":"bash","label":"Install with Pandas/Ibis DataFrame support"}],"dependencies":[{"reason":"The client is based on PyMySQL but adds performance enhancements and C extensions for faster data reading.","package":"PyMySQL","optional":false},{"reason":"Provides SQLAlchemy dialect integration.","package":"sqlalchemy-singlestoredb","optional":true},{"reason":"Used for DataFrame-like operations directly within the database.","package":"ibis","optional":true},{"reason":"Used for DataFrame integration with the 'dataframe' extra.","package":"pandas","optional":true}],"imports":[{"symbol":"connect","correct":"import singlestoredb as s2\nconn = s2.connect(...)"},{"symbol":"Connection","correct":"from singlestoredb import Connection # (less common, usually obtained from s2.connect())"},{"symbol":"Cursor","correct":"from singlestoredb import Cursor # (less common, usually obtained from conn.cursor())"}],"quickstart":{"code":"import singlestoredb as s2\nimport os\n\n# Get connection details from environment variables for security\nHOST = os.environ.get('SINGLESTOREDB_HOST', '127.0.0.1')\nPORT = int(os.environ.get('SINGLESTOREDB_PORT', '3306'))\nUSER = os.environ.get('SINGLESTOREDB_USER', 'root')\nPASSWORD = os.environ.get('SINGLESTOREDB_PASSWORD', 'password')\nDATABASE = os.environ.get('SINGLESTOREDB_DATABASE', 'test_db')\n\ntry:\n    # Establish a connection\n    with s2.connect(\n        host=HOST,\n        port=PORT,\n        user=USER,\n        password=PASSWORD,\n        database=DATABASE\n    ) as conn:\n        print(\"Successfully connected to SingleStoreDB!\")\n\n        # Create a cursor object\n        with conn.cursor() as cur:\n            # Execute a query\n            cur.execute(\"CREATE TABLE IF NOT EXISTS my_table (id INT, name VARCHAR(255))\")\n            cur.execute(\"INSERT INTO my_table (id, name) VALUES (%s, %s)\", (1, 'Alice'))\n            conn.commit()\n            print(\"Table created and data inserted.\")\n\n            # Fetch results\n            cur.execute(\"SELECT * FROM my_table\")\n            for row in cur.fetchall():\n                print(row)\n\nexcept s2.Error as e:\n    print(f\"Database error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to connect to a SingleStoreDB instance using environment variables for credentials, create a table, insert data using parameterized queries, and fetch results. The `with` statements ensure connections and cursors are properly closed."},"warnings":[{"fix":"Update all SQL queries to use the Python DB-API 2.0 standard substitution syntax (`%s` for positional, `%(key)s` for named parameters).","message":"The query parameter substitution syntax changed significantly in v0.5.0. Positional parameters changed from `:1` to `%s`, and named parameters from `:key` to `%(key)s`.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Replace `results_format` with `results_type` in your `s2.connect()` calls and any configuration.","message":"The `results_format` connection parameter was renamed to `results_type` in v0.5.0.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Always use placeholders (`%s` or `%(key)s`) and pass parameters as a tuple or dictionary to `cursor.execute()`. The client handles proper escaping and quoting.","message":"Not using parameterized queries (e.g., f-strings or direct string concatenation) can lead to SQL injection vulnerabilities and incorrect query parsing.","severity":"gotcha","affected_versions":"all"},{"fix":"Use Python's `with` statement for `s2.connect()` and `conn.cursor()` to ensure proper resource management, as shown in the quickstart example.","message":"Failing to close database connections and cursors can lead to resource exhaustion and performance issues.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure your environment uses Python 3.9 or higher. For older Python versions, you may need to use an older client version or upgrade your Python environment.","message":"Minimum Python version requirement was raised to 3.8 in v0.8.0. Current version 1.16.9 requires Python 3.9+.","severity":"breaking","affected_versions":">=0.8.0"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}