psqlpy-python · chandr-andr · May 27, 2025 · May 27, 2025 · May 27, 2025
diff --git a/Cargo.toml b/Cargo.toml
@@ -10,7 +10,14 @@ crate-type = ["cdylib"]
 
 [dependencies]
 deadpool-postgres = { git = "https://github.com/chandr-andr/deadpool.git", branch = "psqlpy" }
-pyo3 = { version = "0.23.4", features = ["chrono", "experimental-async", "rust_decimal", "py-clone", "macros", "multiple-pymethods"] }
+pyo3 = { version = "0.23.4", features = [
+    "chrono",
+    "experimental-async",
+    "rust_decimal",
+    "py-clone",
+    "macros",
+    "multiple-pymethods",
+] }
 pyo3-async-runtimes = { git = "https://github.com/chandr-andr/pyo3-async-runtimes.git", branch = "psqlpy", features = [
     "tokio-runtime",
 ] }

diff --git a/docs/.vuepress/sidebar.ts b/docs/.vuepress/sidebar.ts
@@ -46,6 +46,15 @@ export default sidebar({
             "advanced_type_usage",
           ]
         },
+        {
+          text: "Row Factories Usage",
+          prefix: "row_factories/",
+          collapsible: true,
+          children: [
+            "row_factories",
+            "predefined_row_factories",
+          ]
+        },
         {
           text: "Frameworks Usage",
           prefix: "frameworks/",
@@ -58,15 +67,6 @@ export default sidebar({
             "robyn",
           ]
         },
-        {
-          text: "Row Factories Usage",
-          prefix: "row_factories/",
-          collapsible: true,
-          children: [
-            "row_factories",
-            "predefined_row_factories",
-          ]
-        },
       ],
     },
     {

diff --git a/docs/README.md b/docs/README.md
@@ -28,10 +28,9 @@ highlights:
         details: PSQLPy is under active development.
 ---
 ## What is PSQLPy
-`PSQLPy` is a new Python driver for `PostgreSQL` fully written in Rust. It was inspired by `Psycopg3` and `AsyncPG`.
+`PSQLPy` is a Python driver for `PostgreSQL` fully written in Rust. It was inspired by `Psycopg3` and `AsyncPG`.
 This project has two main goals:
-Make a interaction with the database as fast as possible and now `PSQLPy` shows itself to be times faster than the above drivers.
-Don't make useless abstractions and make it like a mirror to `PostgreSQL`.
+We found that communication with the database can be faster and safer, so we tried to implement a new PostgreSQL driver in Rust for Python.
 
 It has all necessary components to create high-load and fault tolerance applications.
 
@@ -59,4 +58,5 @@ pip install git+https://github.com/psqlpy-python/psqlpy
 
 ## Join community!
 You can get support from the creators and users of `PSQLPy` in some social media:
-- [Telegram](https://t.me/+f3Y8mYKgXxhmYThi)
+- [Telegram](https://t.me/+f3Y8mYKgXxhmYThi)
+- [Discord](https://discord.gg/ugNhzmhZ)
diff --git a/docs/components/connection.md b/docs/components/connection.md
@@ -24,11 +24,10 @@ async def main() -> None:
 ```python
 from psqlpy import connect
 
-db_connection: Final = connect(
-    dsn="postgres://postgres:postgres@localhost:5432/postgres",
-)
-
 async def main() -> None:
+    db_connection: Final = await connect(
+        dsn="postgres://postgres:postgres@localhost:5432/postgres",
+    )
     await db_connection.execute(...)
 ```
 

diff --git a/docs/components/cursor.md b/docs/components/cursor.md
@@ -3,44 +3,93 @@ title: Cursor
 ---
 
 `Cursor` objects represents server-side `Cursor` in the `PostgreSQL`. [PostgreSQL docs](https://www.postgresql.org/docs/current/plpgsql-cursors.html).
+::: important
+Cursor always lives inside a transaction. If you don't begin transaction explicitly, it will be opened anyway.
+:::
 
 ## Cursor Parameters
 
 - `querystring`: specify query for cursor.
 - `parameters`: parameters for the querystring. Default `None`
-- `fetch_number`: default fetch number. It is used in `fetch()` method and in async iterator. Default 10
-- `scroll`: is cursor scrollable or not. Default as in `PostgreSQL`.
+- `fetch_number`: default fetch number. It is used in `fetch()` method and in async iterator.
 
-## Cursor as async iterator
+## Usage
 
-The most common situation is using `Cursor` as async iterator.
+Cursor can be used in different ways.
 
+::: tabs
+@tab Pre-Initialization
 ```python
 from psqlpy import ConnectionPool, QueryResult
 
+async def main() -> None:
+    db_pool = ConnectionPool()
+    connection = await db_pool.connection()
+
+    cursor = connection.cursor(
+        querystring="SELECT * FROM users WHERE id > $1",
+        parameters=[100],
+        fetch_number=10,
+    )
+    await cursor.start()
+```
+
+@tab Post-Initialization
+```python
+from psqlpy import ConnectionPool, QueryResult
 
 async def main() -> None:
     db_pool = ConnectionPool()
+    connection = await db_pool.connection()
+
+    cursor = connection.cursor()
+    await cursor.execute(
+        querystring="SELECT * FROM users WHERE id > $1",
+        parameters=[100],
+    )
+    result: QueryResult = await cursor.fetchone()
+```
 
+@tab Async Context Manager
+```python
+from psqlpy import ConnectionPool, QueryResult
 
+async def main() -> None:
+    db_pool = ConnectionPool()
     connection = await db_pool.connection()
-    transaction = await connection.transaction()
-
-    # Here we fetch 5 results in each iteration.
-    async with cursor in transaction.cursor(
-        querystring="SELECT * FROM users WHERE username = $1",
-        parameters=["Some_Username"],
-        fetch_number=5,
-    ):
-        async for fetched_result in cursor:
-            dict_result: List[Dict[Any, Any]] = fetched_result.result()
-            ... # do something with this result.
+
+    async with connection.cursor(
+        querystring="SELECT * FROM users WHERE id > $1",
+        parameters=[100],
+        array_size=10,
+    ) as cursor:
+        result: QueryResult = await cursor.fetchone()
 ```
 
-## Cursor methods
+@tab Async Iterator
+```python
+from psqlpy import ConnectionPool, QueryResult
 
-There are a lot of methods to work with cursor.
+async def main() -> None:
+    db_pool = ConnectionPool()
+    connection = await db_pool.connection()
+
+    cursor = connection.cursor(
+        querystring="SELECT * FROM users WHERE id > $1",
+        parameters=[100],
+        fetch_number=10,
+    )
+    await cursor.start()
 
+    async for result in cursor:
+        print(result)
+```
+:::
+
+## Cursor attributes
+- `array_size`: get and set attribute. Used in async iterator and `fetch_many` method.
+
+## Cursor methods
 ### Start
 Declare (create) cursor.
 
@@ -58,14 +107,53 @@ async def main() -> None:
     await cursor.close()
 ```
 
-### Fetch
+### Execute
 
-You can fetch next `N` records from the cursor.
-It's possible to specify `N` fetch record with parameter `fetch_number`, otherwise will be used `fetch_number` from the `Cursor` initialization.
+Initialize cursor and make it ready for fetching.
+
+::: important
+If you initialized cursor with `start` method or via context manager, you don't have to use this method.
+:::
+
+#### Parameters:
+- `querystring`: specify query for cursor.
+- `parameters`: parameters for the querystring. Default `None`
 
 ```python
 async def main() -> None:
-    result: QueryResult = await cursor.fetch(
-        fetch_number=100,
+    await cursor.execute(
+        querystring="SELECT * FROM users WHERE id > $1",
+        parameters=[100],
     )
+    result: QueryResult = await cursor.fetchone()
+```
+
+### Fetchone
+
+Fetch one result from the cursor.
+
+```python
+async def main() -> None:
+    result: QueryResult = await cursor.fetchone()
+```
+
+### Fetchmany
+
+Fetch N results from the cursor. Default is `array_size`.
+
+#### Parameters:
+- `size`: number of records to fetch.
+
+```python
+async def main() -> None:
+    result: QueryResult = await cursor.fetchmany(size=10)
+```
+
+### Fetchall
+
+Fetch all results from the cursor.
+
+```python
+async def main() -> None:
+    result: QueryResult = await cursor.fetchall()
 ```
diff --git a/docs/components/transaction.md b/docs/components/transaction.md
@@ -407,8 +407,6 @@ async def main() -> None:
 - `querystring`: Statement string.
 - `parameters`: List of list of parameters for the statement string.
 - `fetch_number`: rewrite default fetch_number. Default is 10.
-- `scroll`: make cursor scrollable or not. Default is like in `PostgreSQL`.
-- `prepared`: prepare querystring or not.
 
 From `Transaction` you can create new `Cursor` object which represents cursor in the `PostgreSQL`. [PostgreSQL Docs](https://www.postgresql.org/docs/current/plpgsql-cursors.html)
 

diff --git a/docs/introduction/introduction.md b/docs/introduction/introduction.md
@@ -5,15 +5,14 @@ title: What is PSQLPy?
 `PSQLPy` is a new Python driver for PostgreSQL fully written in Rust. It was inspired by `Psycopg3` and `AsyncPG`.
 
 With `PSQLPy` you can:
-- Make an interaction with the PostgeSQL in your application much faster (2-3 times).
+- Make an interaction with the PostgeSQL in your application faster.
 - Be sure that there won't be any unexpected errors.
-- Don't usually go to the documentation to search every question - we have awesome docstrings for every component.
+- Don't usually go to the documentation to search every question - we have docstrings for every component.
 - Use `MyPy` (or any other Python type checker) with confidence that exactly the types specified in the typing will be returned.
 - Concentrate on writing your code, not understanding new abstractions in this library, we only have classes which represents PostgreSQL object (transaction, cursor, etc).
 
 ::: info
-It is extremely important to understand that the library will provide a noticeable acceleration in working with the database only if your queries are optimized.
-Otherwise, there will be acceleration, but not so significant
+The library will provide a noticeable acceleration in working with the database only if your queries are optimized.
 :::
 
 ## Important notes
@@ -22,4 +21,5 @@ But in some situations this behavior can break you application. As an example, i
 
 ## Join community!
 You can get support from the creators of `PSQLPy` in some social media:
-- [Telegram](https://t.me/+f3Y8mYKgXxhmYThi)
+- [Telegram](https://t.me/+f3Y8mYKgXxhmYThi)
+- [Discord](https://discord.gg/ugNhzmhZ)
diff --git a/python/tests/test_cursor.py b/python/tests/test_cursor.py
@@ -65,6 +65,22 @@ async def test_cursor_as_async_context_manager(
     assert len(results.result()) == number_database_records
 
 
+async def test_cursor_as_async_iterator(
+    psql_pool: ConnectionPool,
+    table_name: str,
+    number_database_records: int,
+) -> None:
+    connection = await psql_pool.connection()
+    all_results = []
+    async with connection.cursor(
+        querystring=f"SELECT * FROM {table_name}",
+    ) as cursor:
+        async for results in cursor:
+            all_results.extend(results.result())
+
+    assert len(all_results) == number_database_records
+
+
 async def test_cursor_send_underlying_connection_to_pool(
     psql_pool: ConnectionPool,
     table_name: str,

diff --git a/src/connection/traits.rs b/src/connection/traits.rs
@@ -1,5 +1,5 @@
 use postgres_types::{ToSql, Type};
 use pyo3::PyAny;
 use tokio_postgres::{Row, Statement, ToStatement};

 use crate::exceptions::rust_errors::PSQLPyResult;
@@ -58,7 +58,7 @@
        if let Some(level) = isolation_level {
            let level = &level.to_str_level();
            querystring.push_str(format!(" ISOLATION LEVEL {level}").as_str());
        };

        querystring.push_str(match read_variant {
            Some(ReadVariant::ReadOnly) => " READ ONLY",
@@ -101,39 +101,3 @@
 
     fn rollback(&mut self) -> impl std::future::Future<Output = PSQLPyResult<()>>;
 }
-
-// pub trait Cursor {
-//     fn build_cursor_start_qs(
-//         &self,
-//         cursor_name: &str,
-//         scroll: &Option<bool>,
-//         querystring: &str,
-//     ) -> String {
-//         let mut cursor_init_query = format!("DECLARE {cursor_name}");
-//         if let Some(scroll) = scroll {
-//             if *scroll {
-//                 cursor_init_query.push_str(" SCROLL");
-//             } else {
-//                 cursor_init_query.push_str(" NO SCROLL");
-//             }
-//         }
-
-//         cursor_init_query.push_str(format!(" CURSOR FOR {querystring}").as_str());
-
-//         cursor_init_query
-//     }
-
-//     fn start_cursor(
-//         &mut self,
-//         cursor_name: &str,
-//         scroll: &Option<bool>,
-//         querystring: String,
-//         prepared: &Option<bool>,
-//         parameters: Option<pyo3::Py<PyAny>>,
-//     ) -> impl std::future::Future<Output = PSQLPyResult<()>>;
-
-//     fn close_cursor(
-//         &mut self,
-//         cursor_name: &str,
-//     ) -> impl std::future::Future<Output = PSQLPyResult<()>>;
-// }
diff --git a/src/driver/common.rs b/src/driver/common.rs
@@ -132,18 +132,18 @@
     ($name:ident) => {
         #[pymethods]
         impl $name {
-            #[pyo3(signature = (querystring=None, parameters=None, fetch_number=None))]
+            #[pyo3(signature = (querystring=None, parameters=None, array_size=None))]
             pub fn cursor(
                 &self,
                 querystring: Option<String>,
                 parameters: Option<Py<PyAny>>,
-                fetch_number: Option<i32>,
+                array_size: Option<i32>,
             ) -> PSQLPyResult<Cursor> {
                 Ok(Cursor::new(
                     self.conn.clone(),
                     querystring,
                     parameters,
-                    fetch_number,
+                    array_size,
                     self.pg_config.clone(),
                     None,
                 ))
@@ -160,11 +160,11 @@
        #[pymethods]
        impl $name {
            #[pyo3(signature = (querystring, parameters=None))]
            pub async fn prepare(
                &self,
                querystring: String,
                parameters: Option<pyo3::Py<PyAny>>,
            ) -> PSQLPyResult<PreparedStatement> {
                let Some(conn) = &self.conn else {
                    return Err(RustPSQLDriverError::ConnectionClosedError);
                };
@@ -191,7 +191,7 @@
    ($name:ident, $val:expr $(,)?) => {
        #[pymethods]
        impl $name {
            pub async fn commit(&mut self) -> PSQLPyResult<()> {
                let conn = self.conn.clone();
                let Some(conn) = conn else {
                    return Err(RustPSQLDriverError::TransactionClosedError("1".into()));
@@ -206,7 +206,7 @@
                Ok(())
            }

            pub async fn rollback(&mut self) -> PSQLPyResult<()> {
                let conn = self.conn.clone();
                let Some(conn) = conn else {
                    return Err(RustPSQLDriverError::TransactionClosedError("2".into()));
@@ -231,13 +231,13 @@
        #[pymethods]
        impl $name {
            #[pyo3(signature = (source, table_name, columns=None, schema_name=None))]
            pub async fn binary_copy_to_table(
                self_: pyo3::Py<Self>,
                source: Py<PyAny>,
                table_name: String,
                columns: Option<Vec<String>>,
                schema_name: Option<String>,
            ) -> PSQLPyResult<u64> {
                let db_client = pyo3::Python::with_gil(|gil| self_.borrow(gil).conn.clone());
                let mut table_name = quote_ident(&table_name);
                if let Some(schema_name) = schema_name {

diff --git a/src/driver/connection.rs b/src/driver/connection.rs
@@ -1,5 +1,5 @@
 use deadpool_postgres::Pool;
-use pyo3::{ffi::PyObject, pyclass, pyfunction, pymethods, Py, PyAny, PyErr};
+use pyo3::{pyclass, pyfunction, pymethods, Py, PyAny, PyErr};
 use std::sync::Arc;
 use tokio::sync::RwLock;
 use tokio_postgres::Config;
@@ -158,7 +158,7 @@
        read_conn_g.in_transaction()
    }

    async fn __aenter__<'a>(self_: Py<Self>) -> PSQLPyResult<Py<Self>> {
        let (db_client, db_pool, pg_config) = pyo3::Python::with_gil(|gil| {
            let self_ = self_.borrow(gil);
            (
@@ -191,7 +191,7 @@
    }

    #[allow(clippy::unused_async)]
    async fn __aexit__<'a>(
        self_: Py<Self>,
        _exception_type: Py<PyAny>,
        exception: Py<PyAny>,
@@ -278,7 +278,7 @@
    /// 1) Cannot convert python parameters
    /// 2) Cannot execute querystring.
    #[pyo3(signature = (querystring, parameters=None, prepared=None))]
    pub async fn execute_many<'a>(
        self_: pyo3::Py<Self>,
        querystring: String,
        parameters: Option<Vec<Py<PyAny>>>,
@@ -369,7 +369,7 @@
    /// 2) Cannot execute querystring.
    /// 3) Query returns more than one row
    #[pyo3(signature = (querystring, parameters=None, prepared=None))]
    pub async fn fetch_val<'a>(
        self_: pyo3::Py<Self>,
        querystring: String,
        parameters: Option<pyo3::Py<PyAny>>,

diff --git a/src/driver/cursor.rs b/src/driver/cursor.rs
@@ -1,8 +1,7 @@
 use std::sync::Arc;
 
 use pyo3::{
-    exceptions::PyStopAsyncIteration, pyclass, pymethods, types::PyNone, Py, PyAny, PyErr,
-    PyObject, Python,
+    exceptions::PyStopAsyncIteration, pyclass, pymethods, Py, PyAny, PyErr, PyObject, Python,
 };
 use tokio::sync::RwLock;
 use tokio_postgres::{Config, Portal as tp_Portal};
@@ -33,14 +32,14 @@
 }

 impl Cursor {
    pub fn new(
        conn: Option<Arc<RwLock<PSQLPyConnection>>>,
        querystring: Option<String>,
        parameters: Option<Py<PyAny>>,
        array_size: Option<i32>,
        pg_config: Arc<Config>,
        statement: Option<PsqlpyStatement>,
    ) -> Self {
        Self {
            conn,
            transaction: None,
@@ -60,7 +59,7 @@
        let Some(portal) = &self.inner else {
            return Err(RustPSQLDriverError::TransactionClosedError("4".into()));
        };
        transaction.query_portal(&portal, size).await
    }
 }

@@ -91,7 +90,7 @@
        slf
    }

    async fn __aenter__<'a>(slf: Py<Self>) -> PSQLPyResult<Py<Self>> {
        let (conn, querystring, parameters, statement) = Python::with_gil(|gil| {
            let self_ = slf.borrow(gil);
            (
@@ -107,21 +106,21 @@
        };
        let mut write_conn_g = conn.write().await;

        let (txid, inner_portal) = match querystring {
            Some(querystring) => {
                write_conn_g
                    .portal(Some(&querystring), &parameters, None)
                    .await?
            }
            None => {
                let Some(statement) = statement else {
                    return Err(RustPSQLDriverError::CursorStartError(
                        "Cannot start cursor".into(),
                    ));
                };
                write_conn_g.portal(None, &None, Some(&statement)).await?
            }
        };

        Python::with_gil(|gil| {
            let mut self_ = slf.borrow_mut(gil);
@@ -134,7 +133,7 @@
    }

    #[allow(clippy::needless_pass_by_value)]
    async fn __aexit__<'a>(
        &mut self,
        _exception_type: Py<PyAny>,
        exception: Py<PyAny>,
@@ -158,7 +157,7 @@
    fn __anext__(&self) -> PSQLPyResult<Option<PyObject>> {
        let txid = self.transaction.clone();
        let portal = self.inner.clone();
        let size = self.array_size.clone();

        let py_future = Python::with_gil(move |gil| {
            rustdriver_future(gil, async move {
@@ -168,14 +167,14 @@
                let Some(portal) = &portal else {
                    return Err(RustPSQLDriverError::TransactionClosedError("6".into()));
                };
                let result = txid.query_portal(&portal, size).await?;

                if result.is_empty() {
                    return Err(PyStopAsyncIteration::new_err(
                        "Iteration is over, no more results in portal",
                    )
                    .into());
                };

                Ok(result)
            })
@@ -190,10 +189,10 @@
        };
        let mut write_conn_g = conn.write().await;

        let (txid, inner_portal) = match &self.querystring {
            Some(querystring) => {
                write_conn_g
                    .portal(Some(&querystring), &self.parameters, None)
                    .await?
            }
            None => {
@@ -202,7 +201,7 @@
                        "Cannot start cursor".into(),
                    ));
                };
                write_conn_g.portal(None, &None, Some(&statement)).await?
            }
        };