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,118 @@
+# 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, Mongo/PermissionFilter, Mongo/TenantFilter, Tenancy
+ - `Event/` -- DomainEvent, DispatcherHook, plus Collection/{Created,Deleted} and Document/{Created,Deleted,Updated}
+ - `ORM/` -- EntityManager, EntityMapper, EntityMetadata, EntityState, IdentityMap, MetadataFactory, UnitOfWork, ColumnMapping, EmbeddableMapping, RelationshipMapping, plus `Mapping/` (Entity, Column, Id, HasMany, HasOne, BelongsTo, Embedded, Permissions, Tenant, Pre/{Persist,Remove,Update}, Post/{Persist,Remove,Update}, etc.)
+ - `Schema/` -- Introspector, Diff, Change, ChangeType, 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',