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,12 @@ 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"
+          docker run --rm -v $PWD:/app -w /app php:8.4-cli-alpine sh -c \
+          "php -r \"copy('https://getcomposer.org/installer', '/tmp/composer-setup.php');\" && \
+           php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer && \
+           composer install --profile --ignore-platform-reqs && \
+           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,10 @@ 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"
+          "composer install --profile --ignore-platform-reqs && \
+           composer lint"

.github/workflows/tests.yml

@@ -6,9 +6,9 @@ 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 }}
 
-on: [pull_request]
+on: [pull_request, workflow_dispatch]
 
 jobs:
   setup:
@@ -25,6 +25,7 @@ jobs:
         uses: docker/build-push-action@1104d471370f9806843c095c1db02b5a90c5f8b6 # v3.3.1
         with:
           context: .
+          file: Dockerfile
           push: false
           tags: ${{ env.IMAGE }}
           load: true
@@ -60,34 +61,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 +118,7 @@ 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 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 /usr/src/code/tests/e2e/Adapter/${{matrix.adapter}}Test.php

.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) |
+| `composer coverage` | Check test coverage (90% minimum required) |
+
+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.4+, 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, 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: Async, Attributes, Collections, Databases, Documents, Entities, Indexes, Relationships, Transactions
+  - `Hook/` -- event hooks and interceptors: Lifecycle, Permissions, Relationships, TenantFilter, Transform, Read, Write, WriteContext, Interceptor, Decorator, PermissionFilter, MongoPermissionFilter, MongoTenantFilter, Tenancy
+  - `ORM/` -- EntityManager, EntityMapper, EntityMetadata, EntityState, IdentityMap, MetadataFactory, UnitOfWork, ColumnMapping, EmbeddableMapping, RelationshipMapping, plus `Mapping/` subdirectory (PHP attribute annotations: Entity, Column, Id, HasMany, HasOne, BelongsTo, Embedded, Permissions, Tenant, etc.)
+  - `Schema/` -- Introspector, SchemaDiff, SchemaChange, SchemaChangeType, DiffResult
+  - `Validator/` -- input validators (19 top-level + subdirectories)
+  - `Helpers/` -- ID, Permission, Role utilities
+  - `Exception/` -- 18 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 9 traits in `Traits/` for organization. Each trait groups related operations (documents, attributes, indexes, entities, 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` (port 3306), `mysql` (port 3307), `postgres` (port 5432), `mongo` (port 27017)
+- `redis` (port 6379) 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.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

Dockerfile

@@ -115,8 +115,6 @@ RUN EXT_DIR=$(php-config --extension-dir) \
 RUN echo extension=redis.so >> /usr/local/etc/php/conf.d/redis.ini
 RUN echo extension=swoole.so >> /usr/local/etc/php/conf.d/swoole.ini
 RUN echo extension=pcov.so >> /usr/local/etc/php/conf.d/pcov.ini
-RUN echo extension=xdebug.so >> /usr/local/etc/php/conf.d/xdebug.ini
-
 RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
 
 RUN echo "opcache.enable_cli=1" >> $PHP_INI_DIR/php.ini
@@ -131,6 +129,6 @@ COPY ./dev /usr/src/code/dev
 RUN if [ "$DEBUG" = "true" ]; then cp /usr/src/code/dev/xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini; fi
 RUN if [ "$DEBUG" = "true" ]; then mkdir -p /tmp/xdebug; fi
 RUN if [ "$DEBUG" = "false" ]; then rm -rf /usr/src/code/dev; fi
-RUN if [ "$DEBUG" = "false" ]; then rm -f $(php-config --extension-dir)/xdebug.so; fi
+RUN if [ "$DEBUG" = "false" ]; then rm -f /usr/local/etc/php/conf.d/xdebug.ini; fi
 
 CMD [ "tail", "-f", "/dev/null" ]

README.md

@@ -633,22 +633,22 @@ $database->createRelationship(
 ); 
 
 // Relationship onDelete types
-Database::RELATION_MUTATE_CASCADE, 
-Database::RELATION_MUTATE_SET_NULL,
-Database::RELATION_MUTATE_RESTRICT,
+ForeignKeyAction::Cascade->value,
+ForeignKeyAction::SetNull->value,
+ForeignKeyAction::Restrict->value,
 
 // Update the relationship with the default reference attributes
 $database->updateRelationship(
     collection: 'movies', 
     id: 'users', 
-    onDelete: Database::RELATION_MUTATE_CASCADE
+    onDelete: ForeignKeyAction::Cascade->value
 ); 
 
 // Update the relationship with custom reference attributes
 $database->updateRelationship(
     collection: 'movies', 
     id: 'users', 
-    onDelete: Database::RELATION_MUTATE_CASCADE, 
+    onDelete: ForeignKeyAction::Cascade->value,
     newKey: 'movies_id', 
     newTwoWayKey: 'users_id', 
     twoWay: true
@@ -755,25 +755,25 @@ $database->decreaseDocumentAttribute(
 // Update the value of an attribute in a document
 
 // Set types
-Document::SET_TYPE_ASSIGN, // Assign the new value directly
-Document::SET_TYPE_APPEND, // Append the new value to end of the array
-Document::SET_TYPE_PREPEND // Prepend the new value to start of the array
+SetType::Assign, // Assign the new value directly
+SetType::Append, // Append the new value to end of the array
+SetType::Prepend // Prepend the new value to start of the array
 Note: Using append/prepend with an attribute which is not an array, it will be set to an array containing the new value.
 
 $document->setAttribute(key: 'name', 'Chris Smoove')
-         ->setAttribute(key: 'age', 33, Document::SET_TYPE_ASSIGN);
+         ->setAttribute(key: 'age', 33, SetType::Assign);
 
 $database->updateDocument(
-    collection: 'users', 
-    id: $document->getId(), 
+    collection: 'users',
+    id: $document->getId(),
     document: $document
-);         
+);
 
 // Update the permissions of a document
-$document->setAttribute('$permissions', Permission::read(Role::any()), Document::SET_TYPE_APPEND)
-         ->setAttribute('$permissions', Permission::create(Role::any()), Document::SET_TYPE_APPEND)
-         ->setAttribute('$permissions', Permission::update(Role::any()), Document::SET_TYPE_APPEND)
-         ->setAttribute('$permissions', Permission::delete(Role::any()), Document::SET_TYPE_APPEND)
+$document->setAttribute('$permissions', Permission::read(Role::any()), SetType::Append)
+         ->setAttribute('$permissions', Permission::create(Role::any()), SetType::Append)
+         ->setAttribute('$permissions', Permission::update(Role::any()), SetType::Append)
+         ->setAttribute('$permissions', Permission::delete(Role::any()), SetType::Append)
 
 $database->updateDocument(
     collection: 'users',