Fetching rows as native arrays for better static analysis

.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cat:*)",
+      "Bash(wc:*)",
+      "Bash(composer run phpstan:*)",
+      "mcp__jetbrains__list_directory_tree",
+      "mcp__jetbrains__get_file_text_by_path",
+      "Bash(git stash:*)",
+      "Bash(grep:*)",
+      "Bash(cd W:/Nette/Database/src/Bridges/DatabaseTracy && cmd //c compile.bat 2>&1)",
+      "Bash(cd \"W:/Nette/Database/src/Bridges/DatabaseTracy\" && cmd /c \"compile.bat\" 2>&1)",
+      "Bash(cd:*)"
+    ]
+  }
+}

.gitattributes

@@ -1,9 +1,11 @@
 .gitattributes  export-ignore
 .github/        export-ignore
 .gitignore      export-ignore
+AGENTS.md       export-ignore
 ncs.*           export-ignore
 phpstan*.neon   export-ignore
 src/**/*.latte  export-ignore
+docs/           export-ignore
 tests/          export-ignore
 
 *.php*          diff=php

.github/workflows/tests.yml

@@ -3,15 +3,17 @@ name: Tests
 on: [push, pull_request]
 
 env:
-    php-extensions: mbstring, intl, pdo_sqlsrv-5.12.0
+    # pdo_sqlsrv is deliberately unpinned: no single release covers the whole matrix
+    # (5.12 = PHP 8.1-8.3, 5.13 = PHP 8.3-8.5), so let setup-php pick a compatible one
+    php-extensions: mbstring, intl, pdo_sqlsrv
     php-tools: "composer:v2, pecl"
 
 jobs:
     tests:
-        runs-on: ubuntu-22.04
+        runs-on: ubuntu-24.04
         strategy:
             matrix:
-                php: ['8.1', '8.2', '8.3', '8.4', '8.5']
+                php: ['8.3', '8.4', '8.5']
 
             fail-fast: false
 
@@ -49,7 +51,7 @@ jobs:
             - uses: actions/checkout@v6
             - uses: shivammathur/setup-php@v2
               with:
-                  php-version: 8.1
+                  php-version: 8.3
                   coverage: none
 
             - name: Create databases.ini

AGENTS.md

@@ -0,0 +1,81 @@
+# To My Agents!
+
+It is my fervent wish that this file guide every AI coding agent working with code in this repository.
+
+## Documentation
+
+Any distilled, agent-facing documentation for this package - how it works
+internally and the rationale behind key design decisions - lives in `docs/`.
+Consult it before non-trivial changes; it is the source of truth from which the
+public manual is distilled.
+
+Two independent worlds - the low-level core and the Explorer (ActiveRow) layer -
+each with sharp edges (lazy execution, accessed-column narrowing, N+1 batching,
+context-detected preprocessor modes). Read `docs/internals/` before touching them.
+
+## Project Overview
+
+**Nette Database** is a database abstraction layer offering two components:
+
+1. **Core** - a PDO wrapper with an advanced SQL preprocessor and parameter
+   substitution.
+2. **Explorer** - an ActiveRow layer (inspired by NotORM) with convention-based
+   relationships and automatic N+1 prevention.
+
+Supports MySQL, PostgreSQL, SQLite, MS SQL Server, and Oracle.
+
+- **PHP Version**: 8.3 - 8.5
+- **Package**: `nette/database`
+
+## Essential Commands
+
+```bash
+# Run all tests
+vendor/bin/tester tests -s -C
+
+# Run one test directory / file
+vendor/bin/tester tests/Database/Explorer -s -C
+vendor/bin/tester tests/Database/Explorer/Explorer.basic.phpt -s -C
+
+# Static analysis (PHPStan level 8 + nette/phpstan-rules)
+composer phpstan
+```
+
+Most tests connect to real MySQL/PostgreSQL/MS SQL servers via
+`@dataProvider databases.ini`. Bring the servers up with the repo's
+`docker-compose.yml` (`docker compose up -d`, wait for `healthy`) before running
+them; a `Connection refused` / `could not find driver` failure means the servers
+aren't up yet, not a broken test.
+
+## Conventions
+
+- Every file starts with `declare(strict_types=1);`; everything typed; single
+  quotes unless the string contains an apostrophe; Nette Coding Standard.
+- Use generic annotations for IDE/PHPStan support: `@return Selection<ProductRow>`,
+  `@template T of ActiveRow`. Method phpDoc starts with a 3rd-person verb (Returns,
+  Formats, Checks); document a param/return only when it adds info beyond the type.
+- Tests are Nette Tester `.phpt` files; use `@dataProvider databases.ini` to run
+  against every engine, `test()` / `testException()` with descriptive names, and
+  **no comment before `test()`**. Fixtures: `tests/Database/files/{driver}-nette_test1.sql`.
+
+## Working in this repo
+
+- **The Explorer is lazy and self-narrowing.** `accessColumn` is the single seam
+  every read passes through; a first query fetches `SELECT *`, later ones narrow to
+  the accessed columns (cached), and relations are batched to avoid N+1. The cache
+  key even depends on the call-site (`debug_backtrace`) - a real refactor trap. See
+  `docs/internals/explorer.md`.
+- **The SQL preprocessor picks its array mode from surrounding SQL context**
+  (`?and`/`?set`/`?values`/`?order`/`?list`), so the same array expands differently
+  after `WHERE` vs `SET` vs `INSERT`. See `docs/internals/sql-preprocessor.md`.
+- **Nested transactions use a depth counter, not savepoints** - only the outermost
+  `transaction()` issues a real BEGIN/COMMIT/ROLLBACK; there is no partial rollback.
+  There is no `TypeConverter` class either (DB->PHP conversion is
+  `Helpers::normalizeRow`). Don't document designed-but-absent features as present.
+- **Array expansion is a mass-assignment surface.** Passing raw user input as the
+  array to `insert`/`update`/`where` lets an attacker set arbitrary columns and
+  inject operators/SQL via keys - always whitelist columns first. Full guidance is
+  web-manual material.
+- User-facing how-to (Explorer/Selection API, `?`-placeholder reference, NEON
+  config, transactions, Reflection API) is manual material and lives in the public
+  web docs, not here.

composer.json

@@ -15,21 +15,24 @@
 		}
 	],
 	"require": {
-		"php": "8.1 - 8.5",
+		"php": "8.3 - 8.5",
 		"ext-pdo": "*",
-		"nette/caching": "^3.2",
-		"nette/utils": "^4.0"
+		"nette/caching": "^3.4",
+		"nette/utils": "^4.1"
 	},
 	"require-dev": {
 		"nette/tester": "^2.6",
 		"nette/di": "^3.1",
 		"mockery/mockery": "^1.6@stable",
-		"tracy/tracy": "^2.9",
+		"tracy/tracy": "^2.12",
 		"phpstan/phpstan": "^2.1@stable",
 		"phpstan/extension-installer": "^1.4@stable",
 		"nette/phpstan-rules": "^1.0",
 		"jetbrains/phpstorm-attributes": "^1.2"
 	},
+	"conflict": {
+		"tracy/tracy": "<2.12"
+	},
 	"autoload": {
 		"classmap": ["src/"],
 		"psr-4": {
@@ -43,7 +46,7 @@
 	},
 	"extra": {
 		"branch-alias": {
-			"dev-master": "3.2-dev"
+			"dev-master": "3.3-dev"
 		}
 	},
 	"config": {

docker-compose.yml

@@ -40,6 +40,33 @@ services:
             timeout: 5s
             retries: 5
 
+    postgres16:
+        image: postgres:16
+        ports:
+            - "5435:5432"
+        environment:
+            POSTGRES_USER: postgres
+            POSTGRES_PASSWORD: postgres
+            POSTGRES_DB: nette_test
+        healthcheck:
+            test: pg_isready
+            interval: 10s
+            timeout: 5s
+            retries: 5
+
+    mariadb:
+        image: mariadb:11.4
+        ports:
+            - "3308:3306"
+        environment:
+            MARIADB_ROOT_PASSWORD: root
+            MARIADB_DATABASE: nette_test
+        healthcheck:
+            test: healthcheck.sh --connect --innodb_initialized
+            interval: 10s
+            timeout: 5s
+            retries: 5
+
     mssql:
         image: mcr.microsoft.com/mssql/server:2022-latest
         ports:

docs/internals/connection-drivers.md

@@ -0,0 +1,54 @@
+# Connection & drivers
+
+## Execution path
+
+`Connection` connects **lazily** — the constructor opens the PDO only when the `lazy`
+option is falsy; otherwise the first `getPdo()`/`getDriver()`/`preprocess()` triggers
+`connect()` (which also instantiates the driver from `PDO::ATTR_DRIVER_NAME`, builds
+the `SqlPreprocessor`, and fires `onConnect`).
+
+`query()` = `preprocess()` (which runs the preprocessor only when there are
+parameters) → `new ResultSet(...)`. **The SQL actually executes in the `ResultSet`
+constructor, not in `query()`** — so timing, binding, and exception conversion all
+live there (see results-and-types.md). The `fetch*` shortcuts on `Connection` just
+delegate to `query(...)->fetch*()`.
+
+## The `Driver` dialect abstraction
+
+Each engine implements `Driver`: `delimite` (identifier quoting — MySQL backticks,
+PgSql double-quotes, both doubling), `formatDateTime`/`formatDateInterval`/`formatLike`,
+`applyLimit`, schema reflection (`getTables`/`getColumns`/`getIndexes`/`getForeignKeys`/
+`getColumnTypes`), `convertException`, and `isSupported` over the `Support*` feature
+constants.
+
+**`applyLimit` is the most dialect-divergent piece** — MySQL uses `LIMIT` (with the
+`LIMIT 18446744073709551615 OFFSET` trick for offset-only), PgSql separate `LIMIT`/
+`OFFSET`, SQL Server `OFFSET … ROWS FETCH NEXT … ROWS ONLY`, MS SQL/ODBC inject a
+`TOP n` (no offset), Oracle wraps in a `ROWNUM` subquery. Result-set type detection is
+per-driver `getColumnTypes`: PgSql and MsSql map the whole result set via
+`Helpers::detectTypes`, MySQL/SQLite/Sqlsrv go column-by-column via
+`Helpers::detectType`, and Odbc/Oci detect nothing. MySQL adds dialect rules
+(`NEWDECIMAL` precision 0 → integer, `TINY` len 1 + `convertBoolean` → bool, `TIME` →
+interval).
+
+## Exception mapping
+
+```
+\PDOException → DriverException
+                 ├── ConnectionException → ConnectionLostException  (Retryable)
+                 ├── ConstraintViolationException
+                 │     ├── ForeignKey / NotNull / Unique / CheckConstraintViolation
+                 ├── DeadlockException      (Retryable)
+                 └── LockTimeoutException   (Retryable)
+```
+
+Note `Deadlock`/`LockTimeout` extend `DriverException` **directly**, not the
+constraint hierarchy, and the three retryable ones implement the `RetryableException`
+marker (used by `transaction()` retries). The mapping is **per driver** in
+`convertException`: MySQL keys on the numeric error code, PgSql on the SQLSTATE; an
+unrecognized error falls back to a bare `DriverException::from()`. `DriverException::from`
+parses `errorInfo`, or the `SQLSTATE[..] [..] ..` pattern from the message when
+`errorInfo` is absent. Conversion is invoked in the `ResultSet` constructor (which also
+attaches the query string and params) and in `getInsertId`; `connect()`/`quote()` use
+`ConnectionException::from`/`DriverException::from` directly because the driver may not
+exist yet.