Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ jobs:
strategy:
fail-fast: false
matrix:
python-version: ['3.9', '3.12']
poetry-version: [1.8]
python-version: ['3.9', '3.12', '3.10']
poetry-version: ['1.8']

steps:
- uses: actions/checkout@v3
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ jobs:
fail-fast: false
matrix:
python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
poetry-version: [1.8]
poetry-version: ['1.8']

steps:
- uses: actions/checkout@v3
Expand Down
50 changes: 45 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,11 @@ import ydb_dbapi

connection = ydb_dbapi.connect(
host="localhost", port="2136", database="/local"
) # sync connection
) # sync connection

async_connection = await ydb_dbapi.async_connect(
host="localhost", port="2136", database="/local"
) # async connection
) # async connection
```

For TLS connections, pass PEM certificate contents as `bytes` through
Expand Down Expand Up @@ -53,6 +53,40 @@ async with async_connection.cursor() as cursor:
rows = await cursor.fetchall()
```

## Stream cursors (server-side cursor)

By default results are fetched and buffered by the driver as soon as
`execute()` is called. For large result sets pass `stream_results=True`
to `cursor()`: the driver then streams result sets lazily, fetching the
next chunk only when `fetch*()` needs it.

```python
with connection.cursor(stream_results=True) as cursor:
cursor.execute("SELECT id, val FROM table")

while True:
row = cursor.fetchone()
if row is None:
break
print(row)
```

```python
async with async_connection.cursor(stream_results=True) as cursor:
await cursor.execute("SELECT id, val FROM table")

rows = await cursor.fetchall()
```

Notes:
- `rowcount` is `-1` while the stream is still being consumed and is
reported only after all remaining rows have been fetched or the cursor is
closed.
- In an interactive transaction only one stream cursor may be active at a
time: `commit()`, `rollback()` and executing another query while a stream
cursor is still streaming raise `ProgrammingError`. Fetch all rows or
close the cursor first.

## Query parameters

### Standard mode (`pyformat=True`)
Expand All @@ -68,7 +102,9 @@ and infer YDB types from Python values automatically.

```python
connection = ydb_dbapi.connect(
host="localhost", port="2136", database="/local",
host="localhost",
port="2136",
database="/local",
pyformat=True,
)

Expand Down Expand Up @@ -127,7 +163,9 @@ with connection.cursor() as cursor:
"INSERT INTO events (id, payload) VALUES (%(id)s, %(payload)s)",
{
"id": ydb.TypedValue(99, ydb.PrimitiveType.Int32),
"payload": ydb.TypedValue('{"key": "value"}', ydb.PrimitiveType.Json),
"payload": ydb.TypedValue(
'{"key": "value"}', ydb.PrimitiveType.Json
),
},
)
```
Expand All @@ -152,7 +190,9 @@ Use `$name` placeholders in the query and supply a `dict` with

```python
connection = ydb_dbapi.connect(
host="localhost", port="2136", database="/local",
host="localhost",
port="2136",
database="/local",
)

with connection.cursor() as cursor:
Expand Down
118 changes: 118 additions & 0 deletions tests/test_connections.py
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,101 @@ def _test_cursor_is_reusable_after_commit(
connection.cursor().execute_scheme("DROP TABLE test_tx_context")
)

def _test_stream_cursor_fetch(self, connection: dbapi.Connection) -> None:
cur = connection.cursor()
maybe_await(cur.execute_scheme("DROP TABLE IF EXISTS stream_table"))
maybe_await(
cur.execute_scheme(
"""
CREATE TABLE stream_table (
id Int64 NOT NULL,
val Int64,
PRIMARY KEY(id)
)
"""
)
)
maybe_await(
cur.execute(
"UPSERT INTO stream_table (id, val) "
"VALUES (0,0),(1,1),(2,2),(3,3)"
)
)
maybe_await(cur.close())

stream = connection.cursor(stream_results=True)
maybe_await(stream.execute("SELECT id FROM stream_table ORDER BY id"))

assert stream.rowcount == -1
assert maybe_await(stream.fetchmany(size=3)) == [(0,), (1,), (2,)]
assert stream.rowcount == -1
assert maybe_await(stream.fetchall()) == [(3,)]
assert stream.rowcount == 4

maybe_await(stream.close())
maybe_await(
connection.cursor().execute_scheme("DROP TABLE stream_table")
)

def _test_stream_cursor_interactive_transaction_guard(
self, connection: dbapi.Connection
) -> None:
cur = connection.cursor()
maybe_await(
cur.execute_scheme("DROP TABLE IF EXISTS stream_guard_table")
)
maybe_await(
cur.execute_scheme(
"""
CREATE TABLE stream_guard_table (
id Int64 NOT NULL,
val Int64,
PRIMARY KEY(id)
)
"""
)
)
maybe_await(
cur.execute(
"UPSERT INTO stream_guard_table (id, val) "
"VALUES (0,0),(1,1),(2,2),(3,3)"
)
)
maybe_await(cur.close())

connection.set_isolation_level(dbapi.IsolationLevel.SERIALIZABLE)
maybe_await(connection.begin())

stream = connection.cursor(stream_results=True)
maybe_await(
stream.execute("SELECT id FROM stream_guard_table ORDER BY id")
)
assert connection._current_cursor is stream

other = connection.cursor()
with pytest.raises(dbapi.ProgrammingError):
maybe_await(other.execute("SELECT id FROM stream_guard_table"))

with pytest.raises(dbapi.ProgrammingError):
maybe_await(connection.commit())

rows = []
while True:
row = maybe_await(stream.fetchone())
if row is None:
break
rows.append(row)
assert len(rows) == 4
assert connection._current_cursor is None

maybe_await(connection.rollback())

maybe_await(other.close())
maybe_await(stream.close())
maybe_await(
connection.cursor().execute_scheme("DROP TABLE stream_guard_table")
)

def _test_connection(self, connection: dbapi.Connection) -> None:
maybe_await(connection.commit())
maybe_await(connection.rollback())
Expand Down Expand Up @@ -665,6 +760,14 @@ def test_get_view_names(self, connection: dbapi.Connection) -> None:
def test_get_table_names(self, connection: dbapi.Connection) -> None:
self._test_get_table_names(connection)

def test_stream_cursor_fetch(self, connection: dbapi.Connection) -> None:
self._test_stream_cursor_fetch(connection)

def test_stream_cursor_interactive_transaction_guard(
self, connection: dbapi.Connection
) -> None:
self._test_stream_cursor_interactive_transaction_guard(connection)


class TestAsyncConnection(BaseDBApiTestSuit):
@pytest_asyncio.fixture
Expand Down Expand Up @@ -826,3 +929,18 @@ async def test_get_table_names(
self, connection: dbapi.AsyncConnection
) -> None:
await greenlet_spawn(self._test_get_table_names, connection)

@pytest.mark.asyncio
async def test_stream_cursor_fetch(
self, connection: dbapi.AsyncConnection
) -> None:
await greenlet_spawn(self._test_stream_cursor_fetch, connection)

@pytest.mark.asyncio
async def test_stream_cursor_interactive_transaction_guard(
self, connection: dbapi.AsyncConnection
) -> None:
await greenlet_spawn(
self._test_stream_cursor_interactive_transaction_guard,
connection,
)
Loading
Loading