{"id":7897,"library":"adbc-driver-flightsql","title":"ADBC Driver for Apache Arrow Flight SQL","description":"adbc-driver-flightsql is a Python driver for connecting to databases via Apache Arrow Flight SQL. It provides both a low-level ADBC API and a DBAPI 2.0-compatible interface for efficient, Arrow-native data transfer. The library is actively maintained as part of the Apache Arrow ADBC project, with frequent releases, typically on a monthly or bi-monthly cadence. The current version is 1.11.0.","status":"active","version":"1.11.0","language":"en","source_language":"en","source_url":"https://github.com/apache/arrow-adbc/tree/main/python/adbc_driver_flightsql","tags":["adbc","arrow","flightsql","database","sql","driver","analytics","olap"],"install":[{"cmd":"pip install adbc-driver-flightsql pyarrow","lang":"bash","label":"Install with PyArrow"}],"dependencies":[{"reason":"Essential for Arrow-native data handling with ADBC, especially when fetching query results as Arrow objects.","package":"pyarrow","optional":false},{"reason":"Often used in examples for bulk ingestion workflows with Flight SQL.","package":"duckdb","optional":true}],"imports":[{"note":"The primary interface for creating connections is the 'connect' function from the dbapi submodule.","wrong":"import adbc_driver_flightsql","symbol":"connect","correct":"from adbc_driver_flightsql.dbapi import connect"}],"quickstart":{"code":"import os\nfrom adbc_driver_flightsql.dbapi import connect\n\n# Replace with your Flight SQL server URI and authentication details\nFLIGHT_SQL_URI = os.environ.get('ADBC_FLIGHT_SQL_URI', 'grpc+tls://localhost:50050')\nFLIGHT_SQL_USERNAME = os.environ.get('ADBC_FLIGHT_SQL_USERNAME', '')\nFLIGHT_SQL_PASSWORD = os.environ.get('ADBC_FLIGHT_SQL_PASSWORD', '')\n\ndb_options = {}\nif FLIGHT_SQL_USERNAME and FLIGHT_SQL_PASSWORD:\n    db_options['username'] = FLIGHT_SQL_USERNAME\n    db_options['password'] = FLIGHT_SQL_PASSWORD\n\ntry:\n    with connect(FLIGHT_SQL_URI, db_kwargs=db_options) as conn:\n        with conn.cursor() as cursor:\n            cursor.execute('SELECT 1 as example_column')\n            result = cursor.fetch_arrow_table()\n            print('Query successful!')\n            print(result.to_pandas())\nexcept Exception as e:\n    print(f\"Error connecting or querying: {e}\")\n    print(\"Please ensure your Flight SQL server is running and accessible,\")\n    print(\"and ADBC_FLIGHT_SQL_URI, USERNAME, and PASSWORD are correctly set if required.\")\n","lang":"python","description":"This quickstart demonstrates connecting to an Apache Arrow Flight SQL server using the DBAPI 2.0 interface, executing a simple query, and fetching results as an Arrow Table. Connection details and authentication are typically passed via the URI and `db_kwargs` parameter, using environment variables for sensitive information."},"warnings":[{"fix":"Pass appropriate `db_kwargs` or `conn_kwargs` to the `connect` function, such as `db_kwargs={'username': 'user', 'password': 'pass'}` or `db_kwargs={'adbc.flight.sql.authorization_header': 'Bearer <token>'}`. Consult your Flight SQL server's documentation for required authentication schemes.","message":"Authentication is not enabled by default. You must explicitly configure authentication using database options (e.g., 'username', 'password', or 'adbc.flight.sql.authorization_header') for secured Flight SQL endpoints.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set specific timeout options via `db_kwargs` or `conn_kwargs`. For example, `db_kwargs={'adbc.flight.sql.rpc.timeout_seconds.connect': '60', 'adbc.flight.sql.rpc.timeout_seconds.query': '120'}` to increase connection and query timeouts respectively.","message":"The driver implements various timeouts (connection, query execution, data fetching, data upload). Long-running operations may fail without explicit timeout configuration. Default timeouts might be too short for large datasets or complex queries.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to version 1.10.0 or later and utilize the new `adbc_ingest` method for bulk data loading, which offers improved performance and automatic schema inference.","message":"The API for bulk ingestion changed significantly in version 1.10.0 with the introduction of a new convenience API. Older patterns for bulk ingestion might still work but are less efficient or recommended.","severity":"deprecated","affected_versions":"Before 1.10.0"},{"fix":"Always install `adbc-driver-flightsql` alongside `pyarrow`: `pip install adbc-driver-flightsql pyarrow`.","message":"PyArrow is a core dependency for practical use, especially when working with query results. While `adbc-driver-flightsql` can be installed alone, most operations that return data will expect `pyarrow` to be present for Arrow Table/RecordBatch handling.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed: `pip install adbc-driver-flightsql`. Verify the import statement is `from adbc_driver_flightsql.dbapi import connect`.","cause":"The `adbc-driver-flightsql` package is not installed or the import path is incorrect.","error":"ModuleNotFoundError: No module named 'adbc_driver_flightsql.dbapi'"},{"fix":"Check the Flight SQL server's status, ensure the URI (host and port) is correct, and verify network connectivity between your client and the server. Also check for firewall rules.","cause":"The Flight SQL server specified in the URI is unreachable, not running, or blocking the connection (e.g., firewall).","error":"gRPC RPC Error: 14 UNAVAILABLE: Connect Failed"},{"fix":"Provide valid authentication details via `db_kwargs` in the `connect` function, such as `db_kwargs={'username': 'your_user', 'password': 'your_password'}` or `db_kwargs={'adbc.flight.sql.authorization_header': 'Bearer <your_token>'}`.","cause":"The Flight SQL server requires authentication, but no credentials or an invalid authentication header were provided by the client.","error":"gRPC RPC Error: 16 UNAUTHENTICATED: No authentication configured"},{"fix":"Convert your data to an `pyarrow.Table` or `pyarrow.RecordBatch` before passing it to ADBC functions. For example, `arrow_table = pa.Table.from_pandas(df)`.","cause":"Attempting to use a pandas DataFrame (or similar non-Arrow object) directly with ADBC functions that expect an Arrow Table or RecordBatch, especially during bulk ingestion.","error":"TypeError: Cannot convert value of type <class 'pandas.core.frame.DataFrame'> to an Arrow Table."}]}