{"id":29027537,"url":"https://github.com/axonops/async-python-cassandra-client","last_synced_at":"2026-05-03T12:33:49.852Z","repository":{"id":299384481,"uuid":"1002762162","full_name":"axonops/async-python-cassandra-client","owner":"axonops","description":"A Python library designed to make the Python Cassandra© driver compatible with modern async frameworks","archived":false,"fork":false,"pushed_at":"2025-07-15T12:19:00.000Z","size":1434,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-09T01:07:23.924Z","etag":null,"topics":["async","asyncio","cassandra","cassandra-database","cassandra-driver","fastapi","python"],"latest_commit_sha":null,"homepage":"https://axonops.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/axonops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-16T05:27:22.000Z","updated_at":"2025-12-07T11:27:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"0b18115d-d6dc-4003-a885-09389174141f","html_url":"https://github.com/axonops/async-python-cassandra-client","commit_stats":null,"previous_names":["axonops/async-python-cassandra-client"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/axonops/async-python-cassandra-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fasync-python-cassandra-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fasync-python-cassandra-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fasync-python-cassandra-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fasync-python-cassandra-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axonops","download_url":"https://codeload.github.com/axonops/async-python-cassandra-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fasync-python-cassandra-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32569712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","asyncio","cassandra","cassandra-database","cassandra-driver","fastapi","python"],"created_at":"2025-06-26T06:30:54.691Z","updated_at":"2026-05-03T12:33:49.833Z","avatar_url":"https://github.com/axonops.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Async Python Cassandra© Client\n\n[![CI Status](https://github.com/axonops/async-python-cassandra-client/workflows/Main%20Branch%20CI/badge.svg)](https://github.com/axonops/async-python-cassandra-client/actions)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python Version](https://img.shields.io/pypi/pyversions/async-cassandra)](https://pypi.org/project/async-cassandra/)\n[![PyPI Version](https://img.shields.io/pypi/v/async-cassandra)](https://pypi.org/project/async-cassandra/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue)](http://mypy-lang.org/)\n\n\u003e 📢 **Early Release**: This is an early release of async-cassandra. While it has been tested extensively, you may encounter edge cases. We welcome your feedback and contributions! Please report any issues on our [GitHub Issues](https://github.com/axonops/async-python-cassandra-client/issues) page.\n\n## 📦 Repository Structure\n\nThis is a monorepo containing two related Python packages:\n\n- **[async-cassandra](libs/async-cassandra/)** - The main async wrapper for the Cassandra Python driver, enabling async/await operations with Cassandra\n- **[async-cassandra-bulk](libs/async-cassandra-bulk/)** - (🚧 Active Development) High-performance bulk operations extension for async-cassandra\n\n## 📑 Table of Contents\n\n- [📦 Repository Structure](#-repository-structure)\n- [✨ Overview](#-overview)\n- [🏗️ Why create this framework?](#️-why-create-this-framework)\n  - [Understanding Async vs Sync](#understanding-async-vs-sync)\n  - [The Benefits](#the-benefits)\n  - [🔄 True Async Paging](#-true-async-paging)\n- [⚠️ Important Limitations](#️-important-limitations)\n- [🚀 Key Features](#-key-features)\n- [🔀 Alternative Libraries](#-alternative-libraries)\n- [📋 Requirements](#-requirements)\n  - [🔌 CQL Protocol Version Requirement](#-cql-protocol-version-requirement)\n- [🔧 Installation](#-installation)\n  - [async-cassandra (Main Library)](#async-cassandra-main-library)\n  - [async-cassandra-bulk (Coming Soon)](#async-cassandra-bulk-coming-soon)\n- [📚 Quick Start](#-quick-start)\n- [🤝 Contributing](#-contributing)\n- [📞 Support](#-support)\n- [📖 Documentation](#-documentation)\n  - [Getting Started](#getting-started)\n  - [Advanced Topics](#advanced-topics)\n  - [Examples](#examples)\n- [🎯 Running the Examples](#-running-the-examples)\n  - [Running Examples](#running-examples)\n  - [Running with External Cassandra](#running-with-external-cassandra)\n  - [Example Descriptions](#example-descriptions)\n- [⚡ Performance](#-performance)\n- [📝 License](#-license)\n- [🙏 Acknowledgments](#-acknowledgments)\n- [⚖️ Legal Notices](#️-legal-notices)\n\n## ✨ Overview\n\n**async-cassandra** is a Python library that enables the Cassandra driver to work seamlessly with async frameworks like FastAPI, aiohttp, and Quart. It provides an async/await interface that prevents blocking your application's event loop while maintaining full compatibility with the DataStax Python driver.\n\nWhen using the standard Cassandra driver in async applications, blocking operations can freeze your entire service. This wrapper solves that critical issue by bridging the gap between Cassandra's thread-based I/O and Python's async ecosystem, ensuring your web services remain responsive under load.\n\n## 🏗️ Why create this framework?\n\n### Understanding Async vs Sync\n\nIn async Python applications, an **event loop** manages all operations in a single thread. Think of it like a smart traffic controller - it efficiently switches between tasks whenever one is waiting for I/O (like a database query). This allows handling thousands of concurrent requests without creating thousands of threads.\n\n**The key issue**: When you use the standard Cassandra driver (which is synchronous) inside an async web framework like FastAPI or aiohttp, you create a blocking problem. The synchronous driver operations block the event loop, preventing your async application from handling other requests.\n\n**Important clarification**: This blocking issue only occurs when:\n1. You're building an async application (using FastAPI, aiohttp, Quart, etc.)\n2. You use synchronous database operations inside async handlers\n\nIf you're building a traditional synchronous application (Flask, Django without async views), the standard Cassandra driver works fine and you don't need this wrapper.\n\nHere's a concrete example showing the problem and solution:\n\n```python\n# ❌ Synchronous code in an async handler - BLOCKS the event loop\nfrom fastapi import FastAPI\nfrom cassandra.cluster import Cluster\n\napp = FastAPI()\ncluster = Cluster(['localhost'])\nsession = cluster.connect()\n\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: str):\n    # This blocks the event loop! While this query runs,\n    # your FastAPI app cannot process ANY other requests\n    result = session.execute(\"SELECT * FROM users WHERE id = %s\", [user_id])\n    return {\"user\": result.one()}\n```\n\n```python\n# ✅ Async code with our wrapper - NON-BLOCKING\nfrom contextlib import asynccontextmanager\nfrom fastapi import FastAPI\nfrom async_cassandra import AsyncCluster\n\nsession = None\nuser_stmt = None\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n    global session, user_stmt\n    # Use context managers for proper resource management\n    async with AsyncCluster(['localhost']) as cluster:\n        async with cluster.connect() as session:\n            # Prepare statement for better performance\n            user_stmt = await session.prepare(\n                \"SELECT * FROM users WHERE id = ?\"\n            )\n            yield  # App runs here\n            # Cleanup happens automatically\n\napp = FastAPI(lifespan=lifespan)\n\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: str):\n    # This doesn't block! The event loop remains free to handle\n    # other requests while waiting for the database response\n    result = await session.execute(user_stmt, [user_id])\n    return {\"user\": result.one()}\n```\n\nThe key difference: with the sync driver, each database query blocks your entire async application from handling other requests. With async-cassandra, the event loop remains free to process other work while waiting for database responses.\n\n### The Benefits\n\nThis library provides true async/await support, enabling:\n\n- **Non-blocking Operations**: Prevents your async application from freezing during database queries\n- **Framework Compatibility**: Works naturally with FastAPI, aiohttp, and other async frameworks\n- **Clean Async Code**: Use async/await syntax throughout your application\n- **Better Concurrency Management**: Leverage the event loop for handling concurrent requests\n\nSee our [Architecture Overview](docs/architecture.md) for technical details, or learn more about [What This Wrapper Actually Solves (And What It Doesn't)](docs/why-async-wrapper.md#what-this-wrapper-actually-solves-and-what-it-doesnt).\n\n### 🔄 True Async Paging\n\nThe standard Cassandra driver's manual paging (`fetch_next_page()`) is synchronous, which blocks your entire async application:\n\n```python\n# ❌ With standard driver - blocks the event loop\nresult = await session.execute(\"SELECT * FROM large_table\")\nwhile result.has_more_pages:\n    result.fetch_next_page()  # This blocks! Your app freezes here\n\n# ✅ With async-cassandra streaming - truly async\nresult = await session.execute_stream(\"SELECT * FROM large_table\")\nasync for row in result:\n    await process_row(row)  # Non-blocking, other requests keep flowing\n```\n\nThis is critical for web applications where blocking the event loop means all other requests stop being processed. For a detailed explanation of this issue, see our [streaming documentation](docs/streaming.md).\n\n## ⚠️ Important Limitations\n\nThis wrapper makes the cassandra-driver compatible with async Python applications, but it's important to understand what it does and doesn't do:\n\n**What it DOES**:\n- ✅ Prevents blocking the event loop\n- ✅ Provides async/await syntax\n- ✅ Enables use with async frameworks (FastAPI, aiohttp)\n- ✅ Allows concurrent operations via event loop\n\n**What it DOESN'T do**:\n- ❌ Make the underlying I/O truly asynchronous (still uses threads)\n- ❌ Provide performance improvements over the sync driver\n- ❌ Remove thread pool limitations (concurrency still bounded by driver's [thread pool size](docs/thread-pool-configuration.md))\n- ❌ Eliminate thread overhead\n\nThe cassandra-driver uses blocking sockets and thread pools internally. This wrapper provides a compatibility layer but cannot change the fundamental architecture. For a detailed technical analysis, see our [Why Async Wrapper](docs/why-async-wrapper.md) documentation.\n\n## 🚀 Key Features\n\n- **Async/await interface** for all Cassandra operations\n- **Streaming support** for memory-efficient processing of large result sets\n- **Automatic retry logic** for SELECT queries, with idempotency checking for writes\n- **Connection monitoring** and health checking capabilities\n- **Metrics collection** with pluggable backends (in-memory, Prometheus)\n- **Type hints** throughout the codebase\n- **Compatible** with standard cassandra-driver types (Statement, PreparedStatement, etc.)\n- **Context manager support** for proper resource cleanup\n\n## 🔀 Alternative Libraries\n\nSeveral other async Cassandra drivers exist for Python, each with different design approaches:\n\n- **[ScyllaPy](https://github.com/Intreecom/scyllapy)**: Rust-based driver with Python bindings\n- **[Acsylla](https://github.com/acsylla/acsylla)**: C++ driver wrapper using Cython\n- **[DataStax AsyncioReactor](https://github.com/datastax/python-driver)**: Experimental asyncio support in the official driver\n\nSee our [comparison guide](docs/alternatives-comparison.md) for technical differences between these libraries.\n\n\n## 📋 Requirements\n\n- Python 3.12 or higher\n- Apache Cassandra 4.0+ (for CQL protocol v5 support)\n- cassandra-driver 3.29.2+\n- CQL Protocol v5 or higher (see below)\n\n### 🔌 CQL Protocol Version Requirement\n\n**async-cassandra requires CQL protocol v5 or higher** for all connections. We verify this requirement after connection to ensure you get the best available protocol version.\n\n```python\n# Recommended: Let driver negotiate to highest available\ncluster = AsyncCluster(['localhost'])  # Negotiates to highest (currently v5)\nawait cluster.connect()  # Fails if negotiated \u003c v5\n\n# Explicit versions (v5+):\ncluster = AsyncCluster(['localhost'], protocol_version=5)  # Forces v5 exactly\n\n# This raises ConfigurationError immediately:\ncluster = AsyncCluster(['localhost'], protocol_version=4)  # ❌ Not supported\n```\n\n**Why We Enforce v5+ (and not v4 or older):**\n\n1. **Async Performance**: Protocol v5 introduced features that significantly improve async operations:\n   - Better streaming control for large result sets\n   - Improved connection management per host\n   - More efficient prepared statement handling\n\n2. **Testing \u0026 Maintenance**: Supporting older protocols would require:\n   - Testing against Cassandra 2.x/3.x (v3/v4 protocols)\n   - Handling protocol-specific quirks and limitations\n   - Maintaining compatibility code for deprecated features\n\n3. **Security \u0026 Features**: Older protocols lack:\n   - Modern authentication mechanisms\n   - Proper error reporting for async contexts\n   - Features required for cloud-native deployments\n\n4. **Industry Standards**:\n   - Cassandra 4.0 (with v5) was released in July 2021\n   - Major cloud providers default to v5+\n   - Cassandra 3.x reached EOL in 2023\n\n**What This Means for You:**\n\nWhen connecting:\n- **Cassandra 4.0+**: Automatically uses v5 (highest currently supported)\n- **Cassandra 3.x or older**: Connection fails with:\n```\nConnectionError: Connected with protocol v4 but v5+ is required.\nYour Cassandra server only supports up to protocol v4.\nasync-cassandra requires CQL protocol v5 or higher (Cassandra 4.0+).\nPlease upgrade your Cassandra cluster to version 4.0 or newer.\n```\n\n**Upgrade Options:**\n- **Self-hosted**: Upgrade to Cassandra 4.0+ or 5.0 and consider AxonOps to help manage your cluster\n- **AxonOps**: Supports Cassandra 4.0+ (and earlier releases also)\n- **AWS Keyspaces**: Already supports v5\n- **Azure Cosmos DB**: Check current documentation\n- **DataStax Astra**: Supports v5+ by default\n\nWe understand this requirement may be inconvenient for some users, but it allows us to provide a better, more maintainable async experience while focusing our testing and development efforts on modern Cassandra deployments.\n\n## 🔧 Installation\n\n### async-cassandra (Main Library)\n\n```bash\n# From PyPI\npip install async-cassandra\n\n# From source (for development)\ncd libs/async-cassandra\npip install -e .\n```\n\n### async-cassandra-bulk (Coming Soon)\n\n\u003e 🚧 **In Active Development**: async-cassandra-bulk is currently under development and not yet available on PyPI. It will provide high-performance bulk operations for async-cassandra.\n\n## 📚 Quick Start\n\n```python\nimport asyncio\nfrom async_cassandra import AsyncCluster\n\nasync def main():\n    # Connect to Cassandra\n    cluster = AsyncCluster(['localhost'])\n    session = await cluster.connect()\n\n    # Execute queries\n    result = await session.execute(\"SELECT * FROM system.local\")\n    print(f\"Connected to: {result.one().cluster_name}\")\n\n    # Clean up\n    await session.close()\n    await cluster.shutdown()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nFor more detailed examples, see our [Getting Started Guide](docs/getting-started.md).\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see:\n- [Contributing Guidelines](CONTRIBUTING.md) - How to contribute\n- [Developer Documentation](developerdocs/) - Development setup, testing, and architecture\n\n**Important**: All contributors must sign our [Contributor License Agreement (CLA)](CLA.md) before their pull request can be merged.\n\n## 📞 Support\n\n- **Issues**: Please report bugs and feature requests on our [GitHub Issues](https://github.com/axonops/async-python-cassandra-client/issues) page\n- **Community**: For questions and discussions, visit our [GitHub Discussions](https://github.com/axonops/async-python-cassandra-client/discussions)\n- **Company**: Learn more about AxonOps at [https://axonops.com](https://axonops.com)\n\n## 📖 Documentation\n\n### Getting Started\n- [Getting Started Guide](docs/getting-started.md) - **Start here!**\n- [API Reference](docs/api.md) - Detailed API documentation\n- [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and solutions\n- [Understanding Context Managers](docs/context-managers-explained.md) - Deep dive into Python context managers\n\n### Advanced Topics\n- [Architecture Overview](docs/architecture.md) - Technical deep dive\n- [Connection Pooling Guide](docs/connection-pooling.md) - Understanding Python driver limitations\n- [Thread Pool Configuration](docs/thread-pool-configuration.md) - Tuning the driver's executor\n- [Streaming Large Result Sets](docs/streaming.md) - Efficiently handle large datasets\n- [Performance Guide](docs/performance.md) - Optimization tips and benchmarks\n- [Retry Policies](docs/retry-policies.md) - Why we have our own retry policy\n- [Metrics and Monitoring](docs/metrics-monitoring.md) - Track performance and health\n\n### Examples\n- [FastAPI Integration](libs/async-cassandra/examples/fastapi_app/README.md) - Complete REST API example\n- [More Examples](libs/async-cassandra/examples/) - Additional usage patterns\n\n## 🎯 Running the Examples\n\nThe async-cassandra library includes comprehensive examples demonstrating various features and use cases. Examples are located in the `libs/async-cassandra/examples/` directory.\n\n### Running Examples\n\nFirst, navigate to the async-cassandra directory:\n```bash\ncd libs/async-cassandra\n```\n\nThen run any example with: `make example-\u003cname\u003e`\n\n- **`make example-basic`** - Basic connection and query execution\n- **`make example-streaming`** - Memory-efficient streaming of large result sets with True Async Paging\n- **`make example-context-safety`** - Demonstrates proper context manager usage and resource isolation\n- **`make example-export-large-table`** - Export large tables to CSV with progress tracking\n- **`make example-export-parquet`** - Export data to Parquet format with complex data types\n- **`make example-metrics`** - Comprehensive metrics collection and performance monitoring\n- **`make example-metrics-simple`** - Basic metrics collection example\n- **`make example-realtime`** - Real-time data processing with sliding window analytics\n- **`make example-streaming-demo`** - Visual demonstration that streaming doesn't block the event loop\n\n### Running with External Cassandra\n\nIf you have Cassandra running elsewhere:\n\n```bash\n# From the libs/async-cassandra directory:\ncd libs/async-cassandra\n\n# Single node\nCASSANDRA_CONTACT_POINTS=10.0.0.1 make example-streaming\n\n# Multiple nodes\nCASSANDRA_CONTACT_POINTS=10.0.0.1,10.0.0.2,10.0.0.3 make example-streaming\n\n# With custom port\nCASSANDRA_CONTACT_POINTS=cassandra.example.com CASSANDRA_PORT=9043 make example-basic\n```\n\n### Example Descriptions\n\n- **Basic Example**: Shows fundamental operations like connecting, executing queries, and using prepared statements\n- **Streaming Examples**: Demonstrate True Async Paging for processing millions of rows without memory issues\n- **Export Examples**: Show how to export Cassandra data to various formats (CSV, Parquet) with progress tracking\n- **Metrics Examples**: Illustrate performance monitoring, query tracking, and connection health checking\n- **Real-time Processing**: Demonstrates processing time-series IoT data with concurrent operations\n- **Context Safety Demo**: Proves that errors in one operation don't affect others when using context managers\n\nEach example includes detailed comments explaining the concepts and best practices. Start with `example-basic` if you're new to the library.\n\n## ⚡ Performance\n\nasync-cassandra enables your async Python application to work with Cassandra without blocking the event loop. While it doesn't eliminate the underlying driver's thread pool, it prevents those blocking operations from freezing your entire application. This is crucial for web servers where a blocked event loop means no requests can be processed.\n\nThe wrapper's primary benefit is **compatibility**, not raw performance. It allows you to use Cassandra in async applications like FastAPI without sacrificing the responsiveness of your service.\n\nFor performance optimization tips and understanding the limitations, see our [Performance Guide](docs/performance.md).\n\n## 📝 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- DataStax™ for the [Python Driver for Apache Cassandra](https://github.com/datastax/python-driver)\n- The Python asyncio community for inspiration and best practices\n- All contributors who help make this project better\n\n## ⚖️ Legal Notices\n\n*This project may contain trademarks or logos for projects, products, or services. Any use of third-party trademarks or logos are subject to those third-party's policies.*\n\n**Important**: This project is not affiliated with, endorsed by, or sponsored by the Apache Software Foundation or the Apache Cassandra project. It is an independent framework developed by [AxonOps](https://axonops.com).\n\n- **AxonOps** is a registered trademark of AxonOps Limited.\n- **Apache**, **Apache Cassandra**, **Cassandra**, **Apache Spark**, **Spark**, **Apache TinkerPop**, **TinkerPop**, **Apache Kafka** and **Kafka** are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries.\n- **DataStax** is a registered trademark of DataStax, Inc. and its subsidiaries in the United States and/or other countries.\n\n### Copyright\n\nThis project is an independent work and has not been authorized, sponsored, or otherwise approved by the Apache Software Foundation.\n\n### License Compliance\n\nThis project uses the Apache License 2.0, which is compatible with the Apache Cassandra project. We acknowledge and respect all applicable licenses of dependencies used in this project.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by the \u003ca href=\"https://axonops.com\"\u003eAxonOps\u003c/a\u003e Team\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxonops%2Fasync-python-cassandra-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxonops%2Fasync-python-cassandra-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxonops%2Fasync-python-cassandra-client/lists"}