{"id":21679,"library":"pangres","title":"Pangres","description":"Pangres is a Python library that provides efficient upsert (insert/update) functionality for pandas DataFrames into SQL databases (PostgreSQL, MySQL, SQLite) via SQLAlchemy. It supports both synchronous and asynchronous operations, with automatic table creation and schema inference. The current version is 4.2.1, with monthly or irregular releases.","status":"active","version":"4.2.1","language":"python","source_language":"en","source_url":"https://github.com/ThibTrip/pangres","tags":["pandas","sqlalchemy","upsert","postgresql","mysql","sqlite","etl"],"install":[{"cmd":"pip install pangres","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Upsert operations require DataFrames","package":"pandas","optional":false},{"reason":"Database connection and operations","package":"sqlalchemy","optional":false},{"reason":"Required for SQLAlchemy >= 2.0 compatibility (>=1.7.2)","package":"alembic","optional":false},{"reason":"Dependency added in v4.2.0 for version parsing","package":"packaging","optional":false},{"reason":"Recommended for PostgreSQL connections","package":"psycopg2","optional":true},{"reason":"Required for async PostgreSQL support","package":"asyncpg","optional":true},{"reason":"Required for async SQLite support","package":"aiosqlite","optional":true},{"reason":"Required for async MySQL support","package":"aiomysql","optional":true}],"imports":[{"note":"While 'import pangres; pangres.upsert(...)' works, direct import is preferred.","wrong":"import pangres","symbol":"upsert","correct":"from pangres import upsert"},{"note":"Async upsert function introduced in v4.1.","wrong":"","symbol":"aupsert","correct":"from pangres import aupsert"}],"quickstart":{"code":"import pandas as pd\nfrom sqlalchemy import create_engine\nfrom pangres import upsert\n\nengine = create_engine('postgresql://user:pass@localhost/db')\ndf = pd.DataFrame({'id': [1, 2], 'value': ['a', 'b']}).set_index('id')\nupsert(con=engine, df=df, table_name='my_table', if_row_exists='update')","lang":"python","description":"Inserts or updates rows in PostgreSQL using a DataFrame with a primary key index. The engine can be replaced with a connection for transaction control."},"warnings":[{"fix":"Use 'con=' instead of 'engine='.","message":"In v4.0, the first argument 'engine' was renamed to 'con', and now accepts both engines and connections. Old code using 'engine=' keyword will break.","severity":"breaking","affected_versions":"<4.0"},{"fix":"Explicitly set chunksize=10000 to restore old behavior.","message":"In v4.0, the 'chunksize' parameter default changed from 10000 to None (insert all rows at once). If you relied on the old default, your upserts may now attempt huge transactions.","severity":"breaking","affected_versions":"<4.0"},{"fix":"Ensure you create an async engine with create_async_engine from sqlalchemy.ext.asyncio.","message":"When using async (aupsert), the input 'con' must be an async SQLAlchemy engine or connection, not a sync one. Mixing sync/async will raise an error.","severity":"gotcha","affected_versions":">=4.1"},{"fix":"Upgrade pangres to >=4.2.0.","message":"Support for Python 3.12 was added in v4.2.0 with a new dependency 'packaging'. Users on Python 3.12 must upgrade to v4.2.0+.","severity":"deprecated","affected_versions":"<4.2.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use 'from pangres import upsert' or upgrade to v4.2.1 where exports are fixed.","cause":"After 'import pangres', the upsert function is not directly accessible as a module attribute in older versions or due to missing exports.","error":"AttributeError: module 'pangres' has no attribute 'upsert'"},{"fix":"Ensure the DataFrame index has a name (e.g., df.index.name = 'id'). For MultiIndex, ensure all level names are unique and match the database primary key columns.","cause":"Pangres requires the DataFrame index to be named (as a column in the database). An unnamed index or MultiIndex with duplicate level names causes this.","error":"sqlalchemy.exc.InvalidRequestError: A value is required for a bound parameter in the WHERE clause"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}