Add database driver extensibility documentation and Redis reference implementation

.github/workflows/ci.yml

@@ -10,6 +10,16 @@ jobs:
   build:
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    services:
+      redis:
+        image: redis
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     strategy:
       matrix:
         node-version: [18.x, 20.x]

README.md

@@ -112,22 +112,39 @@ main();
 
 ObjectQL isolates the "What" (Query) from the "How" (Execution).
 
-### SQL Driver (`@objectql/driver-sql`)
+### Official Drivers
+
+#### SQL Driver (`@objectql/driver-sql`)
 
 * Supports PostgreSQL, MySQL, SQLite, SQL Server.
 * **Smart Hybrid Mode:** Automatically maps defined fields to SQL columns and undefined fields to a `_jsonb` column. This gives you the speed of SQL with the flexibility of NoSQL.
 
-### Mongo Driver (`@objectql/driver-mongo`)
+#### Mongo Driver (`@objectql/driver-mongo`)
 
 * Native translation to Aggregation Pipelines.
 * High performance for massive datasets.
 
-### SDK / Remote Driver (`@objectql/sdk`)
+#### SDK / Remote Driver (`@objectql/sdk`)
 
 * **The Magic:** You can run ObjectQL in the **Browser**.
 * Instead of connecting to a DB, it connects to an ObjectQL Server API.
 * The API usage remains exactly the same (`repo.find(...)`), but it runs over HTTP.
 
+### Extensibility
+
+ObjectQL's driver architecture supports custom database implementations. Potential databases include:
+
+* **Key-Value Stores:** Redis, Memcached, etcd
+* **Search Engines:** Elasticsearch, OpenSearch, Algolia
+* **Graph Databases:** Neo4j, ArangoDB
+* **Time-Series:** InfluxDB, TimescaleDB
+* **Cloud Databases:** DynamoDB, Firestore, Cosmos DB
+
+**Want to add support for your database?** Check out:
+* [Driver Extensibility Guide](./docs/guide/drivers/extensibility.md) - Lists potential databases and their implementation complexity
+* [Implementing Custom Drivers](./docs/guide/drivers/implementing-custom-driver.md) - Step-by-step guide with code examples
+* [Redis Driver Example](./packages/drivers/redis/) - Reference implementation
+
 ---
 
 ## 🛠️ Validation & Logic

docs/guide/drivers/extensibility.md

@@ -0,0 +1,178 @@
+# Driver Extensibility Guide
+
+ObjectQL is designed to support multiple database backends through its **Driver** abstraction layer. This guide explains how to extend ObjectQL with additional database types.
+
+## Current Official Drivers
+
+ObjectQL currently provides official support for:
+
+| Driver | Package | Databases Supported | Status |
+|--------|---------|---------------------|--------|
+| **SQL Driver** | `@objectql/driver-sql` | PostgreSQL, MySQL, SQLite, SQL Server | ✅ Production Ready |
+| **MongoDB Driver** | `@objectql/driver-mongo` | MongoDB 4.0+ | ✅ Production Ready |
+| **SDK/Remote Driver** | `@objectql/sdk` | HTTP-based ObjectQL servers | ✅ Production Ready |
+
+## Potential Database Types for Extension
+
+ObjectQL's Driver interface can theoretically support any database system. Here are common database types that could be implemented:
+
+### Key-Value Stores
+
+| Database | Use Case | Implementation Complexity |
+|----------|----------|--------------------------|
+| **Redis** | Caching, real-time data, pub/sub | 🟢 Low - Simple key-value operations |
+| **Memcached** | Distributed caching | 🟢 Low - Basic get/set operations |
+| **etcd** | Configuration management, service discovery | 🟡 Medium - Hierarchical keys |
+
+### Document Databases
+
+| Database | Use Case | Implementation Complexity |
+|----------|----------|--------------------------|
+| **CouchDB** | Multi-master replication, offline-first | 🟡 Medium - Similar to MongoDB |
+| **Firebase/Firestore** | Real-time sync, mobile apps | 🟡 Medium - Cloud-native features |
+| **RavenDB** | .NET integration, ACID transactions | 🟡 Medium - Advanced indexing |
+
+### Wide Column Stores
+
+| Database | Use Case | Implementation Complexity |
+|----------|----------|--------------------------|
+| **Cassandra** | High availability, time-series data | 🔴 High - Distributed architecture |
+| **HBase** | Hadoop ecosystem, big data | 🔴 High - Complex data model |
+| **DynamoDB** | AWS-native, serverless | 🟡 Medium - Single-table design patterns |
+
+### Search Engines
+
+| Database | Use Case | Implementation Complexity |
+|----------|----------|--------------------------|
+| **Elasticsearch** | Full-text search, analytics | 🟡 Medium - Query DSL mapping |
+| **OpenSearch** | Fork of Elasticsearch, AWS managed | 🟡 Medium - Similar to Elasticsearch |
+| **Algolia** | Hosted search, real-time indexing | 🟢 Low - REST API based |
+| **Meilisearch** | Typo-tolerant search | 🟢 Low - Simple REST API |
+
+### Graph Databases
+
+| Database | Use Case | Implementation Complexity |
+|----------|----------|--------------------------|
+| **Neo4j** | Social networks, recommendation engines | 🔴 High - Cypher query language |
+| **ArangoDB** | Multi-model (graph + document) | 🟡 Medium - AQL query language |
+| **OrientDB** | Multi-model graph database | 🟡 Medium - SQL-like syntax |
+
+### Time-Series Databases
+
+| Database | Use Case | Implementation Complexity |
+|----------|----------|--------------------------|
+| **InfluxDB** | Metrics, IoT, monitoring | 🟡 Medium - Time-based queries |
+| **TimescaleDB** | PostgreSQL extension for time-series | 🟢 Low - SQL compatible |
+| **Prometheus** | Monitoring and alerting | 🟡 Medium - PromQL query language |
+
+### NewSQL Databases
+
+| Database | Use Case | Implementation Complexity |
+|----------|----------|--------------------------|
+| **CockroachDB** | Distributed SQL, PostgreSQL compatible | 🟢 Low - PostgreSQL protocol |
+| **TiDB** | MySQL compatible, horizontal scaling | 🟢 Low - MySQL protocol |
+| **YugabyteDB** | PostgreSQL compatible, cloud-native | 🟢 Low - PostgreSQL protocol |
+
+### Cloud-Native Databases
+
+| Database | Use Case | Implementation Complexity |
+|----------|----------|--------------------------|
+| **AWS DynamoDB** | Serverless, auto-scaling | 🟡 Medium - NoSQL patterns |
+| **Google Cloud Firestore** | Real-time sync, mobile | 🟡 Medium - Document-based |
+| **Azure Cosmos DB** | Multi-model, global distribution | 🟡 Medium - Multiple APIs |
+| **Supabase** | PostgreSQL-as-a-service | 🟢 Low - PostgreSQL protocol |
+| **PlanetScale** | MySQL-compatible, serverless | 🟢 Low - MySQL protocol |
+
+### Columnar Databases
+
+| Database | Use Case | Implementation Complexity |
+|----------|----------|--------------------------|
+| **ClickHouse** | OLAP, analytics, data warehousing | 🔴 High - Column-oriented queries |
+| **Apache Druid** | Real-time analytics | 🔴 High - Complex aggregations |
+
+### Embedded Databases
+
+| Database | Use Case | Implementation Complexity |
+|----------|----------|--------------------------|
+| **LevelDB** | Embedded key-value store | 🟢 Low - Simple operations |
+| **RocksDB** | High-performance embedded DB | 🟢 Low - LevelDB-compatible |
+| **LMDB** | Memory-mapped key-value store | 🟢 Low - Fast read operations |
+
+## Implementation Complexity Guide
+
+- 🟢 **Low Complexity** (1-2 weeks): Database has SQL compatibility or simple REST API, straightforward query mapping
+- 🟡 **Medium Complexity** (3-6 weeks): Custom query language, moderate feature mapping required
+- 🔴 **High Complexity** (2-3 months): Distributed systems, complex data models, significant architectural differences
+
+## Choosing a Database to Implement
+
+When deciding which database to add support for, consider:
+
+### 1. **Use Case Alignment**
+- Does the database solve a specific problem for ObjectQL users?
+- Does it complement existing drivers?
+
+### 2. **Community Demand**
+- Is there active interest in this database?
+- Are there existing GitHub issues requesting it?
+
+### 3. **Technical Feasibility**
+- How well does the database's data model map to ObjectQL's abstraction?
+- Does it support required operations (CRUD, filters, sorting)?
+
+### 4. **Maintenance Burden**
+- Is the database actively maintained?
+- Does it have a stable API?
+- Is there good documentation?
+
+### 5. **Ecosystem Maturity**
+- Are there quality Node.js/TypeScript clients?
+- Is the client library actively maintained?
+
+## Recommended First Extensions
+
+Based on community needs and implementation complexity, we recommend prioritizing:
+
+1. **Redis Driver** - High demand, simple implementation, excellent for caching
+2. **Elasticsearch Driver** - Popular for search features, clear use case
+3. **DynamoDB Driver** - AWS ecosystem, serverless applications
+4. **ClickHouse Driver** - Analytics and reporting use cases
+
+## Getting Started
+
+To implement a custom driver:
+
+1. Review the [Driver Implementation Guide](./implementing-custom-driver.md)
+2. Study existing driver implementations:
+   - [`@objectql/driver-sql`](../../../packages/drivers/sql/src/index.ts) - SQL databases
+   - [`@objectql/driver-mongo`](../../../packages/drivers/mongo/src/index.ts) - MongoDB
+3. Review the [Driver Interface](../../../packages/foundation/types/src/driver.ts)
+4. Follow the [Driver Testing Guide](./testing-drivers.md) (coming soon)
+
+## Community Drivers
+
+We encourage the community to create and maintain third-party drivers for additional databases. If you've implemented a driver, please:
+
+1. Follow the ObjectQL driver conventions
+2. Include comprehensive tests
+3. Document configuration and usage
+4. Submit a PR to add your driver to this list
+
+### Publishing Community Drivers
+
+Name your package following the convention: `@your-org/objectql-driver-<database>`
+
+Example: `@acme/objectql-driver-redis`
+
+## Need Help?
+
+- 📖 Read the [Driver Implementation Guide](./implementing-custom-driver.md)
+- 💬 Join the [ObjectQL Discord](https://discord.gg/objectql) (if available)
+- 🐛 [Open a GitHub Issue](https://github.com/objectstack-ai/objectql/issues)
+- 📧 Contact the maintainers
+
+## Related Documentation
+
+- [SQL Driver Documentation](./sql.md)
+- [MongoDB Driver Documentation](./mongo.md)
+- [Driver Interface Reference](../../../packages/foundation/types/src/driver.ts)