Use query lib

.github/workflows/codeql-analysis.yml

@@ -1,6 +1,6 @@
 name: "CodeQL"
 
-on: [ pull_request ]
+on: [ pull_request, workflow_dispatch ]
 jobs:
   lint:
     name: CodeQL
@@ -13,8 +13,13 @@ jobs:
           fetch-depth: 2
 
       - run: git checkout HEAD^2
+        if: github.event_name == 'pull_request'
 
       - name: Run CodeQL
         run: |
-          docker run --rm -v $PWD:/app -w /app phpswoole/swoole:5.1.8-php8.3-alpine sh -c \
-          "composer install --profile --ignore-platform-reqs && composer check"
+          container=$(docker create composer:2.8)
+          docker cp "$container":/usr/bin/composer /tmp/composer
+          docker rm "$container"
+          docker run --rm -v $PWD:/app -v /tmp/composer:/usr/local/bin/composer:ro -w /app php:8.5.8-cli-alpine sh -c \
+          "composer install --profile --ignore-platform-req='ext-*' && \
+           composer check"

.github/workflows/linter.yml

@@ -1,6 +1,6 @@
 name: "Linter"
 
-on: [ pull_request ]
+on: [ pull_request, workflow_dispatch ]
 jobs:
   lint:
     name: Linter
@@ -13,8 +13,13 @@ jobs:
           fetch-depth: 2
 
       - run: git checkout HEAD^2
+        if: github.event_name == 'pull_request'
 
       - name: Run Linter
         run: |
-          docker run --rm -v $PWD:/app -w /app phpswoole/swoole:5.1.8-php8.3-alpine sh -c \
-          "composer install --profile --ignore-platform-reqs && composer lint"
+          container=$(docker create composer:2.8)
+          docker cp "$container":/usr/bin/composer /tmp/composer
+          docker rm "$container"
+          docker run --rm -v $PWD:/app -v /tmp/composer:/usr/local/bin/composer:ro -w /app php:8.5.8-cli-alpine sh -c \
+          "composer install --profile --ignore-platform-reqs && \
+           composer lint"

.github/workflows/tests.yml

@@ -6,9 +6,10 @@ concurrency:
 
 env:
   IMAGE: databases-dev
-  CACHE_KEY: databases-dev-${{ github.event.pull_request.head.sha }}
+  CACHE_KEY: databases-dev-${{ github.event.pull_request.head.sha || github.sha }}
+  CACHE_5_KEY: databases-dev-cache-5-${{ github.event.pull_request.head.sha || github.sha }}
 
-on: [pull_request]
+on: [pull_request, workflow_dispatch]
 
 jobs:
   setup:
@@ -25,6 +26,7 @@ jobs:
         uses: docker/build-push-action@1104d471370f9806843c095c1db02b5a90c5f8b6 # v3.3.1
         with:
           context: .
+          file: Dockerfile
           push: false
           tags: ${{ env.IMAGE }}
           load: true
@@ -60,34 +62,48 @@ jobs:
           docker compose up -d --wait
 
       - name: Run Unit Tests
-        run: docker compose exec tests vendor/bin/phpunit /usr/src/code/tests/unit
+        run: docker compose exec -e XDEBUG_MODE=off tests vendor/bin/paratest --configuration phpunit.xml --functional --processes 4 /usr/src/code/tests/unit
 
   adapter_test:
-    name: Adapter Tests
+    name: "Adapter Tests (${{ matrix.adapter }})"
     runs-on: ubuntu-latest
     needs: setup
     strategy:
       fail-fast: false
       matrix:
-        adapter:
-          [
-            MongoDB,
-            MariaDB,
-            MySQL,
-            Postgres,
-            SQLite,
-            Memory,
-            Mirror,
-            Pool,
-            Redis,
-            SharedTables/MongoDB,
-            SharedTables/MariaDB,
-            SharedTables/MySQL,
-            SharedTables/Postgres,
-            SharedTables/SQLite,
-            SharedTables/Redis,
-            Schemaless/MongoDB,
-          ]
+        include:
+          - adapter: MongoDB
+            profiles: "--profile mongo"
+          - adapter: MariaDB
+            profiles: "--profile mariadb"
+          - adapter: MySQL
+            profiles: "--profile mysql"
+          - adapter: Postgres
+            profiles: "--profile postgres"
+          - adapter: SQLite
+            profiles: ""
+          - adapter: Memory
+            profiles: ""
+          - adapter: Mirror
+            profiles: "--profile mariadb --profile mariadb-mirror --profile redis-mirror"
+          - adapter: Pool
+            profiles: "--profile mysql"
+          - adapter: Redis
+            profiles: ""
+          - adapter: SharedTables/MongoDB
+            profiles: "--profile mongo"
+          - adapter: SharedTables/MariaDB
+            profiles: "--profile mariadb"
+          - adapter: SharedTables/MySQL
+            profiles: "--profile mysql"
+          - adapter: SharedTables/Postgres
+            profiles: "--profile postgres"
+          - adapter: SharedTables/SQLite
+            profiles: ""
+          - adapter: SharedTables/Redis
+            profiles: ""
+          - adapter: Schemaless/MongoDB
+            profiles: "--profile mongo"
 
     steps:
       - name: checkout
@@ -103,7 +119,80 @@ jobs:
       - name: Load and Start Services
         run: |
           docker load --input /tmp/${{ env.IMAGE }}.tar
-          docker compose up -d --wait
+          docker compose ${{ matrix.profiles }} up -d --wait
+
+      - name: Run Tests
+        run: docker compose exec -T -e XDEBUG_MODE=off tests vendor/bin/paratest --configuration phpunit.xml --functional --processes 4 /usr/src/code/tests/e2e/Adapter/${{matrix.adapter}}Test.php
+
+  setup_cache_5:
+    name: Setup & Build Docker Image (utopia-php/cache 5.x)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+
+      - name: Build Docker Image
+        uses: docker/build-push-action@1104d471370f9806843c095c1db02b5a90c5f8b6 # v3.3.1
+        with:
+          context: .
+          file: Dockerfile
+          build-args: |
+            UTOPIA_CACHE_VERSION=^5.1
+          push: false
+          tags: ${{ env.IMAGE }}
+          load: true
+          cache-from: |
+            type=gha
+            type=gha,scope=cache-5
+          cache-to: type=gha,mode=max,scope=cache-5
+          outputs: type=docker,dest=/tmp/${{ env.IMAGE }}.tar
+
+      - name: Cache Docker Image
+        uses: actions/cache@6f8efc29b200d32929f49075959781ed54ec270c # v3.5.0
+        with:
+          key: ${{ env.CACHE_5_KEY }}
+          path: /tmp/${{ env.IMAGE }}.tar
+
+  cache_5_test:
+    name: "Cache 5.x Tests (${{ matrix.suite }})"
+    runs-on: ubuntu-latest
+    needs: setup_cache_5
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - suite: Unit
+            profiles: ""
+            path: /usr/src/code/tests/unit
+          - suite: MariaDB
+            profiles: "--profile mariadb"
+            path: /usr/src/code/tests/e2e/Adapter/MariaDBTest.php
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Load Cache
+        uses: actions/cache@6f8efc29b200d32929f49075959781ed54ec270c # v3.5.0
+        with:
+          key: ${{ env.CACHE_5_KEY }}
+          path: /tmp/${{ env.IMAGE }}.tar
+          fail-on-cache-miss: true
+
+      - name: Load and Start Services
+        run: |
+          docker load --input /tmp/${{ env.IMAGE }}.tar
+          docker compose ${{ matrix.profiles }} up -d --wait
+
+      - name: Show utopia-php/cache Version
+        run: |
+          docker compose exec -T tests php -r '
+            require "vendor/autoload.php";
+            echo "utopia-php/cache ", \Composer\InstalledVersions::getPrettyVersion("utopia-php/cache"), PHP_EOL;
+          '
 
       - name: Run Tests
-        run: docker compose exec -T tests vendor/bin/phpunit /usr/src/code/tests/e2e/Adapter/${{matrix.adapter}}Test.php --debug
+        run: docker compose exec -T -e XDEBUG_MODE=off tests vendor/bin/paratest --configuration phpunit.xml --functional --processes 4 ${{ matrix.path }}

.gitignore

@@ -12,3 +12,4 @@ Makefile
 .envrc
 .vscode
 tmp
+*.sql

AGENTS.md

@@ -0,0 +1,117 @@
+# Utopia Database
+
+PHP database abstraction library with a unified API across MariaDB 10.5, MySQL 8.0, PostgreSQL 13+, SQLite 3.38+, and MongoDB.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `composer build` | Build Docker containers |
+| `composer start` | Start all database containers in background |
+| `composer test` | Run tests in Docker (ParaTest, 4 parallel processes) |
+| `composer lint` | Check formatting (Pint, PSR-12) |
+| `composer format` | Auto-format code |
+| `composer check` | Static analysis (PHPStan, max level, 2GB) |
+
+Run a single test:
+```bash
+docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests/e2e/Adapter/MariaDBTest.php
+docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests/unit/Validator/SomeTest.php
+```
+
+## Stack
+
+- PHP 8.5+, Docker Compose for test databases
+- ParaTest (parallel PHPUnit), Pint (PSR-12), PHPStan (max level)
+- Test databases: MariaDB 10.11, MySQL 8.0.43, PostgreSQL 16, SQLite, MongoDB 8.0.14
+- Redis 8.2.1 for caching tests
+
+## Project layout
+
+- **src/Database/** -- core library (PSR-4 namespace `Utopia\Database\`)
+  - `Database.php` -- main API class (uses trait composition for organization)
+  - `Adapter.php` -- base adapter class all engines extend
+  - `Adapter/` -- engine implementations: MariaDB, MySQL, Postgres, SQLite, Mongo, Memory, Redis, Pool, ReadWritePool
+  - `Adapter/SQL.php` -- shared SQL adapter base (MariaDB, MySQL, Postgres, SQLite extend this)
+  - `Adapter/Feature/` -- capability interfaces for adapter features
+  - `Document.php` -- JSON document model (extends ArrayObject)
+  - `Mirror.php` -- database mirroring/replication
+  - `Query.php` -- query builder extension
+  - `Attribute.php` -- attribute type definitions
+  - `Index.php` -- index management
+  - `Relationship.php` -- relationship definitions
+  - `Traits/` -- Database.php composition: Attributes, Collections, Databases, Documents, Indexes, Relationships, Transactions
+  - `Hook/` -- event hooks and interceptors: Lifecycle, Named, Decorator, Transform, Read, Write, WriteContext, Interceptor, Permissions, Relationships, Tenancy, PermissionFilter, TenantFilter, the join and raw-builder filters, Mongo/PermissionFilter, Mongo/TenantFilter
+  - `Event/` -- Domain, DispatcherHook, plus Collection/{Created,Deleted}, Document/{Created,Deleted,Updated} and Documents/{Created,Deleted,Updated}
+  - `Cache/` -- `find()` query cache (QueryCache, Invalidator) and cache bookkeeping
+  - `State/` -- per-coroutine state (Value) and Snapshot
+  - `Validator/` -- input validators (21 top-level + Authorization/, Queries/, Query/)
+  - `Helpers/` -- ID, Permission, Role utilities
+  - `Exception/` -- 20 exception types (Authorization, Duplicate, Limit, Query, Timeout, etc.)
+
+- **tests/unit/** -- unit tests for validators, helpers, etc.
+- **tests/e2e/Adapter/** -- E2E tests against real databases
+  - `Base.php` -- abstract test class all adapter tests extend
+  - `Scopes/` -- test trait mixins (DocumentTests, AttributeTests, CollectionTests, PermissionTests, RelationshipTests, SpatialTests, VectorTests, etc.)
+  - Each adapter test (MariaDBTest, PostgresTest, etc.) extends Base and gets all scope traits
+
+## Key patterns
+
+**Multi-adapter:** Single `Database` class with engine-specific `Adapter` implementations. SQL adapters share `SQL.php` base; MongoDB has its own.
+
+**Document model:** Documents are ArrayObject subclasses with reserved attributes: `$id`, `$sequence`, `$createdAt`, `$updatedAt`, `$collection`, `$permissions`.
+
+**Hook system:** Pluggable hooks for permissions, relationships, tenancy filtering, and lifecycle events. Hooks registered on the Database instance.
+
+**Custom document types:**
+```php
+$database->setDocumentType('users', User::class);
+$user = $database->getDocument('users', 'id123'); // Returns User instance
+```
+
+**Trait composition:** `Database.php` splits its API across 7 traits in `Traits/` for organization. Each trait groups related operations (documents, attributes, indexes, etc.).
+
+**Connection pooling:** `Pool` adapter wraps multiple connections. `ReadWritePool` distributes reads and writes to separate pools.
+
+**Query builder:** Integrates with `utopia-php/query`. Queries grouped by type: filters, selections, aggregations, ordering, pagination.
+
+## Testing patterns
+
+- E2E tests extend `Base.php` which provides setUp/tearDown for real database connections
+- Test functionality split into trait mixins in `Scopes/` -- each adapter test includes all relevant traits
+- Unit tests in `tests/unit/` for validators and helpers
+- Tests check for `ext-swoole` and skip if missing
+
+## Docker services
+
+```bash
+composer build && composer start   # Start all databases
+```
+
+Services (activated via Docker Compose profiles):
+- `mariadb` (host port 8703), `mysql` (8706), `postgres` (8701), `mongo` (9706)
+- `redis` (8708) for caching
+- Mirror variants for replication tests
+- `adminer` (port 8700, debug profile) for database UI
+
+## Load testing
+
+```bash
+bin/load --adapter=mariadb      # Populate test data
+bin/index --adapter=mariadb     # Create indexes
+bin/query --adapter=mariadb     # Run queries
+bin/compare                     # Visualize at localhost:8708
+```
+
+## Conventions
+
+- PSR-12 via Pint, PSR-4 autoloading
+- One class per file, filename matches class name
+- Full type hints on all parameters and returns, readonly properties for immutable data
+- Imports: alphabetical, single per statement, grouped by const/class/function
+- Constants: UPPER_SNAKE_CASE
+- Methods: camelCase with verb prefixes (get*, set*, create*, update*, delete*)
+
+## Cross-repo context
+
+Changes to the Query builder or Adapter interface may break appwrite. Run `composer test` in both repos after adapter changes.