Skip to content

Commit 3dd1707

Browse files
emattizavn50dpg
authored and
vn50dpg
committed
Added Engine Disposal Documentation
Created hyperlink to SQLAlchemy docs for Engine Disposal responsibilities of user. Unified wording of legacy support for sqlite
1 parent 5b0a2a6 commit 3dd1707

File tree

2 files changed

+32
-13
lines changed

2 files changed

+32
-13
lines changed

doc/source/whatsnew/v0.25.1.rst

+1
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,7 @@ I/O
105105

106106
- Avoid calling ``S3File.s3`` when reading parquet, as this was removed in s3fs version 0.3.0 (:issue:`27756`)
107107
- Better error message when a negative header is passed in :func:`pandas.read_csv` (:issue:`27779`)
108+
- Added notes on Engine Disposal and user responsibility to multiple sql related function docstrings (:issue:`23086`)
108109
-
109110

110111
Plotting

pandas/io/sql.py

+31-13
Original file line numberDiff line numberDiff line change
@@ -140,10 +140,14 @@ def execute(sql, con, cur=None, params=None):
140140
----------
141141
sql : string
142142
SQL query to be executed.
143-
con : SQLAlchemy connectable(engine/connection) or sqlite3 connection
144-
Using SQLAlchemy makes it possible to use any DB supported by the
145-
library.
146-
If a DBAPI2 object, only sqlite3 is supported.
143+
con : SQLAlchemy connectable (engine/connection) or database string URI
144+
or DBAPI2 connection (fallback mode)
145+
Using SQLAlchemy makes it possible to use any DB supported by that
146+
library. Legacy support is provided for sqlite3.Connection objects.
147+
Note: The user is responsible for engine disposal and connection
148+
closure for the SQLAlchemy connectable. See `EngineDisposal
149+
<https://docs.sqlalchemy.org/en/13/core/connections.html?highlight=engine#engine-disposal>`_.
150+
147151
cur : deprecated, cursor is obtained from connection, default: None
148152
params : list or tuple, optional, default: None
149153
List of parameters to pass to execute method.
@@ -187,6 +191,9 @@ def read_sql_table(
187191
con : SQLAlchemy connectable or str
188192
A database URI could be provided as as str.
189193
SQLite DBAPI connection mode not supported.
194+
Note: The user is responsible for engine disposal and connection
195+
closure for the SQLAlchemy connectable. See `EngineDisposal
196+
<https://docs.sqlalchemy.org/en/13/core/connections.html?highlight=engine#engine-disposal>`_.
190197
schema : str, default None
191198
Name of SQL schema in database to query (if database flavor
192199
supports this). Uses default schema if None (default).
@@ -279,11 +286,15 @@ def read_sql_query(
279286
----------
280287
sql : string SQL query or SQLAlchemy Selectable (select or text object)
281288
SQL query to be executed.
282-
con : SQLAlchemy connectable(engine/connection), database string URI,
289+
con : SQLAlchemy connectable(engine/connection) or database string URI
283290
or sqlite3 DBAPI2 connection
284-
Using SQLAlchemy makes it possible to use any DB supported by that
285-
library.
286-
If a DBAPI2 object, only sqlite3 is supported.
291+
Using SQLAlchemy makes it possible to use any DB supported by
292+
that library. Legacy support is provided for sqlite3.Connection
293+
objects.
294+
Note: The user is responsible for engine disposal and connection
295+
closure for the SQLAlchemy connectable. See `EngineDisposal
296+
<https://docs.sqlalchemy.org/en/13/core/connections.html?highlight=engine#engine-disposal>`_.
297+
287298
index_col : string or list of strings, optional, default: None
288299
Column(s) to set as index(MultiIndex).
289300
coerce_float : boolean, default True
@@ -359,9 +370,12 @@ def read_sql(
359370
SQL query to be executed or a table name.
360371
con : SQLAlchemy connectable (engine/connection) or database string URI
361372
or DBAPI2 connection (fallback mode)
362-
363373
Using SQLAlchemy makes it possible to use any DB supported by that
364-
library. If a DBAPI2 object, only sqlite3 is supported.
374+
library. Legacy support is provided for sqlite3.Connection objects.
375+
Note: The user is responsible for engine disposal and connection
376+
closure for the SQLAlchemy connectable. See `EngineDisposal
377+
<https://docs.sqlalchemy.org/en/13/core/connections.html?highlight=engine#engine-disposal>`_.
378+
365379
index_col : string or list of strings, optional, default: None
366380
Column(s) to set as index(MultiIndex).
367381
coerce_float : boolean, default True
@@ -459,9 +473,13 @@ def to_sql(
459473
Name of SQL table.
460474
con : SQLAlchemy connectable(engine/connection) or database string URI
461475
or sqlite3 DBAPI2 connection
462-
Using SQLAlchemy makes it possible to use any DB supported by that
463-
library.
464-
If a DBAPI2 object, only sqlite3 is supported.
476+
Using SQLAlchemy makes it possible to use any DB supported by
477+
that library. Legacy support is provided for sqlite3.Connection
478+
objects.
479+
Note: The user is responsible for engine disposal and connection
480+
closure for the SQLAlchemy connectable. See `EngineDisposal
481+
<https://docs.sqlalchemy.org/en/13/core/connections.html?highlight=engine#engine-disposal>`_.
482+
465483
schema : string, default None
466484
Name of SQL schema in database to write to (if database flavor
467485
supports this). If None, use default schema (default).

0 commit comments

Comments
 (0)