SonnetDB Python Connector

The Python connector is a dependency-free ctypes wrapper over the stable SonnetDB C ABI from connectors/c.

It exposes:

• sonnetdb.connect / Connection.execute / Connection.execute_non_query
• forward-only result cursors with typed getters and tuple iteration
• Connection.flush, sonnetdb.version, and sonnetdb.last_error
• a light DB-API-style Connection.cursor() facade

Connection.close() releases the native handle and does not report best-effort shutdown diagnostics. Call Connection.flush() when you need an explicit durability check before closing.

The first version intentionally does not implement SQL parameters because the native ABI currently accepts a single SQL string.

Requirements

• Python 3.10+
• a native SonnetDB C library built for the current platform:
  • Windows: SonnetDB.Native.dll
  • Linux: SonnetDB.Native.so

Build the C connector first:

cmake -S connectors/c --preset windows-x64
cmake --build artifacts/connectors/c/win-x64 --config Release

Run the Quickstart on Windows

cd connectors/python
$native = (Resolve-Path ../c/native/SonnetDB.Native/bin/Release/net10.0/win-x64/native).Path
$env:SONNETDB_NATIVE_LIB_DIR = $native
python examples/quickstart.py

Run the Quickstart on Linux

cmake -S connectors/c --preset linux-x64
cmake --build artifacts/connectors/c/linux-x64

cd connectors/python
native="$(realpath ../../artifacts/connectors/c/linux-x64)"
SONNETDB_NATIVE_LIB_DIR="$native" LD_LIBRARY_PATH="$native:${LD_LIBRARY_PATH:-}" \
  python examples/quickstart.py

API Sketch

import sonnetdb

with sonnetdb.connect("./data-python") as connection:
    connection.execute_non_query("CREATE MEASUREMENT cpu (host TAG, usage FIELD FLOAT)")
    connection.execute_non_query(
        "INSERT INTO cpu (time, host, usage) VALUES "
        "(1710000000000, 'edge-1', 0.42),"
        "(1710000001000, 'edge-1', 0.73)"
    )

    with connection.execute("SELECT time, host, usage FROM cpu LIMIT 10") as result:
        print(result.columns)
        for timestamp, host, usage in result:
            print(timestamp, host, usage)

DB-API-Style Cursor

with sonnetdb.connect("./data-python") as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT time, host, usage FROM cpu")
        rows = cursor.fetchall()

The cursor facade is intentionally small. Non-empty parameters passed to cursor.execute(sql, parameters) raise NotSupportedError until the native ABI gains parameter binding.

Native Library Resolution

The connector looks for the native library in this order:

1. SONNETDB_NATIVE_LIBRARY as a full path, or a directory containing the library.
2. SONNETDB_NATIVE_LIB_DIR.
3. Common local build outputs under artifacts/connectors/c and connectors/c/native/SonnetDB.Native/bin.

Set one of the environment variables when running from outside the SonnetDB repository.

Tests

cd connectors/python
$env:SONNETDB_NATIVE_LIB_DIR = (Resolve-Path ../c/native/SonnetDB.Native/bin/Release/net10.0/win-x64/native).Path
python -m unittest discover -s tests