{"id":2239,"library":"python-arango","title":"Python Driver for ArangoDB","description":"Python-Arango is the official Python driver for ArangoDB, a scalable multi-model database that natively supports documents, graphs, and key-values. It provides a comprehensive API for interacting with ArangoDB, including managing databases, collections, documents, graphs, and executing AQL queries. The library is actively maintained with regular releases, currently at version 8.3.1.","status":"active","version":"8.3.1","language":"en","source_language":"en","source_url":"https://github.com/arangodb/python-arango","tags":["arangodb","database","nosql","driver","document-database","graph-database"],"install":[{"cmd":"pip install python-arango --upgrade","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.10 or higher.","package":"Python","optional":false}],"imports":[{"symbol":"ArangoClient","correct":"from arango import ArangoClient"}],"quickstart":{"code":"import os\nfrom arango import ArangoClient\nfrom arango.exceptions import ServerConnectionError, ArangoClientError, CollectionCreateError, DatabaseCreateError\n\n# Configuration from environment variables (replace with your ArangoDB instance details)\nARANGO_HOSTS = os.environ.get('ARANGO_HOSTS', 'http://localhost:8529')\nARANGO_USERNAME = os.environ.get('ARANGO_USERNAME', 'root')\nARANGO_PASSWORD = os.environ.get('ARANGO_PASSWORD', 'your_arangodb_password') # Default root password is often empty or 'root'\nTEST_DB_NAME = \"my_test_db_reg\"\nTEST_COLLECTION_NAME = \"my_collection_reg\"\n\ntry:\n    # Initialize the client for ArangoDB\n    client = ArangoClient(hosts=ARANGO_HOSTS)\n\n    # Connect to \"_system\" database as root user to manage other databases\n    sys_db = client.db(\"_system\", username=ARANGO_USERNAME, password=ARANGO_PASSWORD)\n\n    # Create a new database if it doesn't exist\n    if not sys_db.has_database(TEST_DB_NAME):\n        sys_db.create_database(TEST_DB_NAME)\n        print(f\"Database '{TEST_DB_NAME}' created.\")\n    else:\n        print(f\"Database '{TEST_DB_NAME}' already exists.\")\n\n    # Connect to the specific database\n    db = client.db(TEST_DB_NAME, username=ARANGO_USERNAME, password=ARANGO_PASSWORD)\n\n    # Create a new collection if it doesn't exist\n    if not db.has_collection(TEST_COLLECTION_NAME):\n        collection = db.create_collection(TEST_COLLECTION_NAME)\n        print(f\"Collection '{TEST_COLLECTION_NAME}' created.\")\n    else:\n        collection = db.collection(TEST_COLLECTION_NAME)\n        print(f\"Collection '{TEST_COLLECTION_NAME}' already exists.\")\n\n    # Insert new documents into the collection\n    docs = [\n        {\"name\": \"Alice\", \"age\": 30},\n        {\"name\": \"Bob\", \"age\": 24},\n        {\"name\": \"Charlie\", \"age\": 35}\n    ]\n    collection.insert_many(docs)\n    print(f\"Inserted {len(docs)} documents.\")\n\n    # Execute an AQL query and iterate through the result cursor\n    cursor = db.aql.execute(f\"FOR doc IN {TEST_COLLECTION_NAME} FILTER doc.age > 25 RETURN doc.name\")\n    filtered_names = [name for name in cursor]\n    print(f\"Names of people older than 25: {filtered_names}\")\n\nexcept ServerConnectionError as e:\n    print(f\"Failed to connect to ArangoDB server at {ARANGO_HOSTS}: {e}. Ensure ArangoDB is running.\")\nexcept ArangoClientError as e:\n    print(f\"ArangoDB Client Error: {e}\")\nexcept (CollectionCreateError, DatabaseCreateError) as e:\n    print(f\"Error during ArangoDB resource creation: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to connect to an ArangoDB instance, create a new database and collection (if they don't exist), insert multiple documents, and execute a simple AQL query to retrieve filtered data. Ensure ArangoDB is running and accessible, and set the `ARANGO_HOSTS`, `ARANGO_USERNAME`, and `ARANGO_PASSWORD` environment variables for authentication, or adjust the default values in the code."},"warnings":[{"fix":"Migrate your transaction logic to the new API, manually calling `begin_transaction()` and `commit()`/`abort()` as per the updated documentation. Results are returned immediately instead of job objects.","message":"The transaction API was overhauled in `python-arango` version 5.0.0 to align with ArangoDB 3.5+'s new transaction REST API. This removed context managers (e.g., `with db.begin_transaction():`) and changed method signatures. Code using the old transaction patterns will break.","severity":"breaking","affected_versions":"5.0.0+"},{"fix":"If developing an asynchronous application, install `python-arango-async` (`pip install python-arango-async`) and use its `AsyncArangoClient` and related asynchronous methods.","message":"For `asyncio` applications, use the dedicated `python-arango-async` library. `python-arango` is a synchronous driver, and using it in an asynchronous context will lead to blocking I/O and potential performance bottlenecks.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that `BatchDatabase` and `BatchJob` instances are managed within a single thread context and that a new `BatchDatabase` instance is created for each batch execution if further operations are needed after a commit.","message":"Instances of `BatchDatabase` and `BatchJob` are stateful and should not be shared across multiple threads. A `BatchDatabase` instance also cannot be reused after its `commit()` method has been called.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}