[DOP-15749] - add ExecuteOptions, FetchOptions

docs/changelog/next_release/274.feature.rst

@@ -0,0 +1,37 @@
+Divide general ``JDBCOptions`` into ``FetchOptions`` for fetching data and ``ExecuteOptions`` for executing statements.
+
+Before:
+
+.. code-block:: python
+
+    from onetl.connection import Postgres
+
+    postgres = Postgres(...)
+    df = postgres.fetch(
+        "SELECT * FROM some.mytable WHERE key = 'something'",
+        options=Postgres.JDBCOptions(fetchsize=1000, query_timeout=30),
+    )
+
+    postgres.execute(
+        "UPDATE some.mytable SET value = 'new' WHERE key = 'something'",
+        options=Postgres.JDBCOptions(query_timeout=30),
+    )
+
+After:
+
+.. code-block:: python
+
+    from onetl.connection import Postgres
+
+    # Using FetchOptions for fetching data
+    postgres = Postgres(...)
+    df = postgres.fetch(
+        "SELECT * FROM some.mytable WHERE key = 'something'",
+        options=Postgres.FetchOptions(fetchsize=1000),
+    )
+
+    # Using ExecuteOptions for executing statements
+    postgres.execute(
+        "UPDATE some.mytable SET value = 'new' WHERE key = 'something'",
+        options=Postgres.ExecuteOptions(query_timeout=30),
+    )

docs/conf.py

@@ -54,7 +54,6 @@
     "sphinx_copybutton",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "sphinxcontrib.autodoc_pydantic",
     "sphinxcontrib.towncrier",  # provides `towncrier-draft-entries` directive
     "sphinxcontrib.plantuml",
     "sphinx.ext.extlinks",

docs/connection/db_connection/clickhouse/execute.rst

@@ -17,10 +17,10 @@ There are 2 ways to execute some statement in Clickhouse
 Use ``Clickhouse.fetch``
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use this method to execute some ``SELECT`` query which returns **small number or rows**, like reading
+Use this method to perform some ``SELECT`` query which returns **small number or rows**, like reading
 Clickhouse config, or reading data from some reference table. Method returns Spark DataFrame.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`FetchOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCFetchOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -50,7 +50,7 @@ Examples
 
     df = clickhouse.fetch(
         "SELECT value FROM some.reference_table WHERE key = 'some_constant'",
-        options=Clickhouse.JDBCOptions(query_timeout=10),
+        options=Clickhouse.FetchOptions(query_timeout=10),
     )
     clickhouse.close()
     value = df.collect()[0][0]  # get value from first row and first column
@@ -60,7 +60,7 @@ Use ``Clickhouse.execute``
 
 Use this method to execute DDL and DML operations. Each method call runs operation in a separated transaction, and then commits it.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`ExecuteOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCExecuteOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -98,7 +98,7 @@ Examples
             ENGINE = MergeTree()
             ORDER BY id
             """,
-            options=Clickhouse.JDBCOptions(query_timeout=10),
+            options=Clickhouse.ExecuteOptions(query_timeout=10),
         )
 
 Notes
@@ -113,7 +113,13 @@ Options
 
 .. currentmodule:: onetl.connection.db_connection.jdbc_mixin.options
 
-.. autopydantic_model:: JDBCOptions
+.. autopydantic_model:: JDBCFetchOptions
+    :member-order: bysource
+    :model-show-field-summary: false
+    :field-show-constraints: false
+
+
+.. autopydantic_model:: JDBCExecuteOptions
     :member-order: bysource
     :model-show-field-summary: false
     :field-show-constraints: false

docs/connection/db_connection/greenplum/execute.rst

@@ -17,10 +17,10 @@ There are 2 ways to execute some statement in Greenplum
 Use ``Greenplum.fetch``
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Use this method to execute some ``SELECT`` query which returns **small number or rows**, like reading
+Use this method to perform some ``SELECT`` query which returns **small number or rows**, like reading
 Greenplum config, or reading data from some reference table. Method returns Spark DataFrame.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`FetchOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCFetchOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -50,7 +50,7 @@ Examples
 
     df = greenplum.fetch(
         "SELECT value FROM some.reference_table WHERE key = 'some_constant'",
-        options=Greenplum.JDBCOptions(query_timeout=10),
+        options=Greenplum.FetchOptions(query_timeout=10),
     )
     greenplum.close()
     value = df.collect()[0][0]  # get value from first row and first column
@@ -60,7 +60,7 @@ Use ``Greenplum.execute``
 
 Use this method to execute DDL and DML operations. Each method call runs operation in a separated transaction, and then commits it.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`ExecuteOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCExecuteOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -99,7 +99,7 @@ Examples
             )
             DISTRIBUTED BY id
             """,
-            options=Greenplum.JDBCOptions(query_timeout=10),
+            options=Greenplum.ExecuteOptions(query_timeout=10),
         )
 
 Interaction schema
@@ -145,7 +145,13 @@ Options
 
 .. currentmodule:: onetl.connection.db_connection.jdbc_mixin.options
 
-.. autopydantic_model:: JDBCOptions
+.. autopydantic_model:: JDBCFetchOptions
+    :member-order: bysource
+    :model-show-field-summary: false
+    :field-show-constraints: false
+
+
+.. autopydantic_model:: JDBCExecuteOptions
     :member-order: bysource
     :model-show-field-summary: false
     :field-show-constraints: false

docs/connection/db_connection/mssql/execute.rst

@@ -17,10 +17,10 @@ There are 2 ways to execute some statement in MSSQL
 Use ``MSSQL.fetch``
 ~~~~~~~~~~~~~~~~~~~
 
-Use this method to execute some ``SELECT`` query which returns **small number or rows**, like reading
+Use this method to perform some ``SELECT`` query which returns **small number or rows**, like reading
 MSSQL config, or reading data from some reference table. Method returns Spark DataFrame.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`FetchOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCFetchOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -49,7 +49,7 @@ Examples
 
     df = mssql.fetch(
         "SELECT value FROM some.reference_table WHERE key = 'some_constant'",
-        options=MSSQL.JDBCOptions(query_timeout=10),
+        options=MSSQL.FetchOptions(query_timeout=10),
     )
     mssql.close()
     value = df.collect()[0][0]  # get value from first row and first column
@@ -59,7 +59,7 @@ Use ``MSSQL.execute``
 
 Use this method to execute DDL and DML operations. Each method call runs operation in a separated transaction, and then commits it.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`ExecuteOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCExecuteOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -97,15 +97,21 @@ Examples
                 value NUMBER
             )
             """,
-            options=MSSQL.JDBCOptions(query_timeout=10),
+            options=MSSQL.ExecuteOptions(query_timeout=10),
         )
 
 Options
 -------
 
 .. currentmodule:: onetl.connection.db_connection.jdbc_mixin.options
 
-.. autopydantic_model:: JDBCOptions
+.. autopydantic_model:: JDBCFetchOptions
+    :member-order: bysource
+    :model-show-field-summary: false
+    :field-show-constraints: false
+
+
+.. autopydantic_model:: JDBCExecuteOptions
     :member-order: bysource
     :model-show-field-summary: false
     :field-show-constraints: false

docs/connection/db_connection/mysql/execute.rst

@@ -17,10 +17,10 @@ There are 2 ways to execute some statement in MySQL
 Use ``MySQL.fetch``
 ~~~~~~~~~~~~~~~~~~~
 
-Use this method to execute some ``SELECT`` query which returns **small number or rows**, like reading
+Use this method to perform some ``SELECT`` query which returns **small number or rows**, like reading
 MySQL config, or reading data from some reference table. Method returns Spark DataFrame.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`FetchOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCFetchOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -50,7 +50,7 @@ Examples
 
     df = mysql.fetch(
         "SELECT value FROM some.reference_table WHERE key = 'some_constant'",
-        options=MySQL.JDBCOptions(query_timeout=10),
+        options=MySQL.FetchOptions(query_timeout=10),
     )
     mysql.close()
     value = df.collect()[0][0]  # get value from first row and first column
@@ -60,7 +60,7 @@ Use ``MySQL.execute``
 
 Use this method to execute DDL and DML operations. Each method call runs operation in a separated transaction, and then commits it.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`ExecuteOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCExecuteOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -98,15 +98,21 @@ Examples
             )
             ENGINE = InnoDB
             """,
-            options=MySQL.JDBCOptions(query_timeout=10),
+            options=MySQL.ExecuteOptions(query_timeout=10),
         )
 
 Options
 -------
 
 .. currentmodule:: onetl.connection.db_connection.jdbc_mixin.options
 
-.. autopydantic_model:: JDBCOptions
+.. autopydantic_model:: JDBCFetchOptions
+    :member-order: bysource
+    :model-show-field-summary: false
+    :field-show-constraints: false
+
+
+.. autopydantic_model:: JDBCExecuteOptions
     :member-order: bysource
     :model-show-field-summary: false
     :field-show-constraints: false

docs/connection/db_connection/oracle/execute.rst

@@ -20,7 +20,7 @@ Use ``Oracle.fetch``
 Use this method to execute some ``SELECT`` query which returns **small number or rows**, like reading
 Oracle config, or reading data from some reference table. Method returns Spark DataFrame.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`FetchOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCFetchOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -50,7 +50,7 @@ Examples
 
     df = oracle.fetch(
         "SELECT value FROM some.reference_table WHERE key = 'some_constant'",
-        options=Oracle.JDBCOptions(query_timeout=10),
+        options=Oracle.FetchOptions(query_timeout=10),
     )
     oracle.close()
     value = df.collect()[0][0]  # get value from first row and first column
@@ -60,7 +60,7 @@ Use ``Oracle.execute``
 
 Use this method to execute DDL and DML operations. Each method call runs operation in a separated transaction, and then commits it.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`ExecuteOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCExecuteOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -98,15 +98,21 @@ Examples
                 value NUMBER
             )
             """,
-            options=Oracle.JDBCOptions(query_timeout=10),
+            options=Oracle.ExecuteOptions(query_timeout=10),
         )
 
 Options
 -------
 
 .. currentmodule:: onetl.connection.db_connection.jdbc_mixin.options
 
-.. autopydantic_model:: JDBCOptions
+.. autopydantic_model:: JDBCFetchOptions
+    :member-order: bysource
+    :model-show-field-summary: false
+    :field-show-constraints: false
+
+
+.. autopydantic_model:: JDBCExecuteOptions
     :member-order: bysource
     :model-show-field-summary: false
     :field-show-constraints: false

docs/connection/db_connection/postgres/execute.rst

@@ -20,7 +20,7 @@ Use ``Postgres.fetch``
 Use this method to execute some ``SELECT`` query which returns **small number or rows**, like reading
 Postgres config, or reading data from some reference table. Method returns Spark DataFrame.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`FetchOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCFetchOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -48,7 +48,7 @@ Examples
 
     df = postgres.fetch(
         "SELECT value FROM some.reference_table WHERE key = 'some_constant'",
-        options=Postgres.JDBCOptions(query_timeout=10),
+        options=Postgres.FetchOptions(query_timeout=10),
     )
     postgres.close()
     value = df.collect()[0][0]  # get value from first row and first column
@@ -58,7 +58,7 @@ Use ``Postgres.execute``
 
 Use this method to execute DDL and DML operations. Each method call runs operation in a separated transaction, and then commits it.
 
-Method accepts :obj:`JDBCOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCOptions>`.
+Method accepts :obj:`ExecuteOptions <onetl.connection.db_connection.jdbc_mixin.options.JDBCExecuteOptions>`.
 
 Connection opened using this method should be then closed with ``connection.close()`` or ``with connection:``.
 
@@ -96,15 +96,21 @@ Examples
                 value real
             )
             """,
-            options=Postgres.JDBCOptions(query_timeout=10),
+            options=Postgres.ExecuteOptions(query_timeout=10),
         )
 
 Options
 -------
 
 .. currentmodule:: onetl.connection.db_connection.jdbc_mixin.options
 
-.. autopydantic_model:: JDBCOptions
+.. autopydantic_model:: JDBCFetchOptions
+    :member-order: bysource
+    :model-show-field-summary: false
+    :field-show-constraints: false
+
+
+.. autopydantic_model:: JDBCExecuteOptions
     :member-order: bysource
     :model-show-field-summary: false
     :field-show-constraints: false