diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 1404d225eea97..e3dd3f2994f13 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -2488,7 +2488,7 @@ def to_sql( ---------- name : str Name of SQL table. - con : sqlalchemy.engine.Engine or sqlite3.Connection + con : sqlalchemy.engine.(Engine or Connection) or sqlite3.Connection Using SQLAlchemy makes it possible to use any DB supported by that library. Legacy support is provided for sqlite3.Connection objects. The user is responsible for engine disposal and connection closure for the SQLAlchemy @@ -2576,18 +2576,27 @@ def to_sql( >>> engine.execute("SELECT * FROM users").fetchall() [(0, 'User 1'), (1, 'User 2'), (2, 'User 3')] - >>> df1 = pd.DataFrame({'name' : ['User 4', 'User 5']}) - >>> df1.to_sql('users', con=engine, if_exists='append') + An `sqlalchemy.engine.Connection` can also be passed to to `con`: + >>> with engine.begin() as connection: + ... df1 = pd.DataFrame({'name' : ['User 4', 'User 5']}) + ... df1.to_sql('users', con=connection, if_exists='append') + + This is allowed to support operations that require that the same + DBAPI connection is used for the entire operation. + + >>> df2 = pd.DataFrame({'name' : ['User 6', 'User 7']}) + >>> df2.to_sql('users', con=engine, if_exists='append') >>> engine.execute("SELECT * FROM users").fetchall() [(0, 'User 1'), (1, 'User 2'), (2, 'User 3'), - (0, 'User 4'), (1, 'User 5')] + (0, 'User 4'), (1, 'User 5'), (0, 'User 6'), + (1, 'User 7')] - Overwrite the table with just ``df1``. + Overwrite the table with just ``df2``. - >>> df1.to_sql('users', con=engine, if_exists='replace', + >>> df2.to_sql('users', con=engine, if_exists='replace', ... index_label='id') >>> engine.execute("SELECT * FROM users").fetchall() - [(0, 'User 4'), (1, 'User 5')] + [(0, 'User 6'), (1, 'User 7')] Specify the dtype (especially useful for integers with missing values). Notice that while pandas is forced to store the data as floating point,