Nette Database

https://github.com/nette/database
Admin
Nette Database is a powerful database abstraction layer for PHP that simplifies database access with...
Tokens:93,701
Snippets:687
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Database Initialization Examples

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database.md

Code examples for initializing a Nette Database instance and handling connection errors.

```APIDOC
## `Nette\Database\Database::__construct`

### Description
Creates a new Database instance from a driver instance or a DSN string. When a string is provided, it triggers `createFromDsn(...func_get_args())` for backward compatibility.

### Method
Constructor

### Signature
```php
public function __construct(
	Drivers\Driver|string $driver,
)
```

### Parameters
- **`driver`** (`Drivers\Driver|string`) - Required - Driver instance, or v3-style arguments (dsn string).
```

```APIDOC
## `Nette\Database\Database::createFromParameters`

### Description
Creates a Database instance from an array of parameters. Accepts `createFromParameters(['dsn' => ...], ...)` or `createFromParameters('dsn' => ...)`. Resolves `driverClass` / `driver` / `dsn`, spreads remaining keys into the driver constructor, and applies the four `TypeConverter` flags and `autoCommit`.

### Method
Static factory

### Signature
```php
public static function createFromParameters(
	#[\SensitiveParameter]
	...$params,
): self
```

### Parameters
- **`params`** (`mixed`) - Required - Variadic parameters; can be an associative array or key-value pairs.
```

```APIDOC
## `Nette\Database\Database::createFromDsn`

### Description
Creates a Database instance from a DSN string, username, password, and options. Promotes string-keyed `$options` to top-level parameters, drops `lazy`, and delegates to `createFromParameters()`.

### Method
Static factory

### Signature
```php
public static function createFromDsn(
	string $dsn,
	?string $username = null,
	#[\SensitiveParameter]
	?string $password = null,
	array $options = [],
): self
```

### Parameters
- **`dsn`** (`string`) - Required - The DSN string (e.g., `mysql:host=localhost;dbname=shop`).
- **`username`** (`?string`) - Optional - The database username.
- **`password`** (`?string`) - Optional - The database password.
- **`options`** (`array`) - Optional - Additional driver options.
```

--------------------------------

### Manual registration example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/connection-panel.md

Example of manually registering the ConnectionPanel without DI. It creates an Explorer from a DSN and calls initialize() with named arguments.

```php
use Nette\Bridges\DatabaseTracy\ConnectionPanel;

$db = Nette\Database\Explorer::createFromDsn('sqlite:db.sqlite');
ConnectionPanel::initialize($db, addBarPanel: true, name: 'main', explain: true);
```

--------------------------------

### Fetching rows examples

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/selection.md

Examples of fetching a single row by primary key, fetching the first matching row, and iterating over all rows.

```php
$book = $db->table('book')->get(2);            // ActiveRow with id 2
$first = $db->table('book')->where('year > ?', 2000)->fetch();
foreach ($db->table('book') as $book) { /* ... */ }   // getIterator()
```

--------------------------------

### Custom EXPLAIN command and error visibility example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/connection-panel.md

Example showing how to set a custom EXPLAIN command (e.g., 'EXPLAIN ANALYZE') and increase maxQueries. Also demonstrates catching a DriverException to show the SQL tab on the blue screen.

```php
$panel = ConnectionPanel::initialize($db, name: 'app');
$panel->explain = 'EXPLAIN ANALYZE';    // PostgreSQL-style plan via custom command
$panel->maxQueries = 500;
// $panel->disabled = true;             // turn off at runtime

try {
    $db->query('SELECT * FROM users WHERE id = 1');
} catch (Nette\Database\DriverException $e) {
    // Tracy's blue screen now shows the 'SQL' tab with the failing query
}
```

--------------------------------

### DI-injected Explorer usage example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/explorer.md

Example of using the Explorer service injected via DI in a typical Nette application. Shows a query with placeholders.

```php
// in a Nette application the service is injected:
/** @var Nette\Database\Explorer $db */ // inject database.default
$db->query('UPDATE users SET ? WHERE id = ?', ['active' => 0], 1);
```

--------------------------------

### Example - DI Wiring

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/explorer.md

Shows how the Explorer is typically injected in a Nette application via DI.

```APIDOC
## Example - DI Wiring

### Description
Shows how the Explorer is typically injected in a Nette application via DI.

### Code Example
```php
// in a Nette application the service is injected:
/** @var Nette\Database\Explorer $db */ // inject database.default
$db->query('UPDATE users SET ? WHERE id = ?', ['active' => 0], 1);
```
```

--------------------------------

### Fetch variants example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database.md

Example usage of the fetch variants. Shows how to obtain a Row, a single field, a property from a Row, key-value pairs, and a list of Rows.

```php
$row   = $db->fetch('SELECT * FROM users WHERE id = ?', 1);       // ?Row
$name  = $db->fetchField('SELECT name FROM users WHERE id = ?', 1);
$id    = $db->fetch('SELECT id, name FROM users WHERE id = ?', 1)->id;
$pairs = $db->fetchPairs('SELECT id, name FROM users');           // [id => name]
$all   = $db->fetchAll('SELECT * FROM users WHERE active = ?', 1); // list<Row>
```

--------------------------------

### Literal + preprocess example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database.md

Example of using literal() to embed raw SQL (NOW()) as a parameter. The comment shows the emitted SQL.

```php
$literal = Database::literal('NOW()');
$db->query('UPDATE posts SET published = ? WHERE id = ?', $literal, 7);
// SQL emitted: UPDATE posts SET published = NOW() WHERE id = 7
```

--------------------------------

### Start database containers with Docker Compose

Source: https://github.com/nette/database/blob/master/CLAUDE.md

Start MySQL, PostgreSQL, and MS SQL containers using docker-compose.yml. Wait until all containers report 'healthy' before running tests. Without containers, tests fail with 'Connection refused' or 'could not find driver'.

```bash
docker compose -f W:/Nette/Database/docker-compose.yml up -d
```

--------------------------------

### Install nette/database with Composer

Source: https://github.com/nette/database/blob/master/readme.md

Install the Nette Database package via Composer. Requires PHP 8.3 and supports up to PHP 8.5.

```bash
composer require nette/database
```

--------------------------------

### Run tests against MySQL/PostgreSQL with Docker

Source: https://github.com/nette/database/blob/master/readme.md

Run tests against MySQL, PostgreSQL, etc. by starting Docker containers, copying the configuration, and running the tester.

```bash
docker compose up -d
cp tests/databases.docker.ini tests/Database/databases.ini
composer run tester
```

--------------------------------

### Walk foreign keys example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/reflection.md

Iterates over the foreign keys of the 'book' table, printing each foreign key's name, the referenced table name, and the mapping of local columns to foreign columns. This example demonstrates how to access and display foreign key metadata.

```php
foreach ($reflection->getTable('book')->foreignKeys as $fk) {
    echo $fk->name, ': ', $fk->foreignTable->name, "\n";
    foreach ($fk->localColumns as $i => $local) {
        echo "  {$local->name} -> {$fk->foreignColumns[$i]->name}\n";
    }
}

```

--------------------------------

### Fetch Shortcuts

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database.md

All fetch shortcuts execute query() and read the first row/field from the result. Each method is documented with its signature, parameters, return type, and an example.

```APIDOC
## fetch

### Description
Executes a query and returns the first row as a Row object, or null if no rows are returned.

### Method
fetch

### Signature
public function fetch(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): ?Row

### Parameters
- **$sql** (string) - Required - SQL query string.
- **$params** (mixed, variadic) - Optional - Parameters to be bound to the query.

### Return Value
?Row - The first row of the result set, or null if no rows are returned.

### Example
```php
$row = $db->fetch('SELECT * FROM users WHERE id = ?', 1);
```
```

```APIDOC
## fetchAssoc

### Description
Executes a query and returns the first row as an associative array, or null if no rows are returned.

### Method
fetchAssoc

### Signature
public function fetchAssoc(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): ?array

### Parameters
- **$sql** (string) - Required - SQL query string.
- **$params** (mixed, variadic) - Optional - Parameters to be bound to the query.

### Return Value
?array - The first row as an associative array, or null if no rows are returned.

### Example
```php
$assoc = $db->fetchAssoc('SELECT * FROM users WHERE id = ?', 1);
```
```

```APIDOC
## fetchField

### Description
Executes a query and returns the value of the first field of the first row.

### Method
fetchField

### Signature
public function fetchField(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): mixed

### Parameters
- **$sql** (string) - Required - SQL query string.
- **$params** (mixed, variadic) - Optional - Parameters to be bound to the query.

### Return Value
mixed - The value of the first field of the first row.

### Example
```php
$name = $db->fetchField('SELECT name FROM users WHERE id = ?', 1);
```
```

```APIDOC
## fetchList

### Description
Executes a query and returns the first row as a list, or null if no rows are returned.

### Method
fetchList

### Signature
public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): ?array

### Parameters
- **$sql** (string) - Required - SQL query string.
- **$params** (mixed, variadic) - Optional - Parameters to be bound to the query.

### Return Value
?array - The first row as a list, or null if no rows are returned.

### Example
```php
$list = $db->fetchList('SELECT * FROM users WHERE id = ?', 1);
```
```

```APIDOC
## fetchFields

### Description
Alias of fetchList(). Executes a query and returns the first row as a list, or null if no rows are returned.

### Method
fetchFields

### Signature
public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): ?array

### Parameters
- **$sql** (string) - Required - SQL query string.
- **$params** (mixed, variadic) - Optional - Parameters to be bound to the query.

### Return Value
?array - The first row as a list, or null if no rows are returned.

### Example
```php
$fields = $db->fetchFields('SELECT * FROM users WHERE id = ?', 1);
```
```

```APIDOC
## fetchPairs

### Description
Executes a query and returns all rows as key-value pairs.

### Method
fetchPairs

### Signature
public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): array

### Parameters
- **$sql** (string) - Required - SQL query string.
- **$params** (mixed, variadic) - Optional - Parameters to be bound to the query.

### Return Value
array - An associative array of key-value pairs.

### Example
```php
$pairs = $db->fetchPairs('SELECT id, name FROM users');
```
```

```APIDOC
## fetchAll

### Description
Executes a query and returns all rows as a list of Row objects.

### Method
fetchAll

### Signature
public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): array

### Parameters
- **$sql** (string) - Required - SQL query string.
- **$params** (mixed, variadic) - Optional - Parameters to be bound to the query.

### Return Value
array - A list of Row objects.

### Example
```php
$all = $db->fetchAll('SELECT * FROM users WHERE active = ?', 1);
```
```

```APIDOC
## literal

### Description
Builds an unescaped SqlLiteral embedding raw SQL with nested parameters.

### Method
literal

### Signature
public static function literal(string $value, mixed ...$params): SqlLiteral

### Parameters
- **$value** (string) - Required - Raw SQL string.
- **$params** (mixed, variadic) - Optional - Parameters to be embedded in the literal.

### Return Value
SqlLiteral - An SqlLiteral object representing the raw SQL.

### Example
```php
$literal = Database::literal('NOW()');
$db->query('UPDATE posts SET published = ? WHERE id = ?', $literal, 7);
```
```

--------------------------------

### Custom backend driver example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/drivers.md

Shows how to implement a custom database driver. The driver must provide connect() and createEngine() methods. Pass the driver class via the 'driverClass' parameter to Explorer::createFromParameters(). Implementations may throw DriverException; connection failures are converted to ConnectionException.

```php
use Nette\Database\Drivers;

final class MyDriver implements Drivers\Driver
{
	public function connect(): Drivers\Connection { /* ... */ }
	public function createEngine(Drivers\Connection $connection): Drivers\Engine { /* ... */ }
}

$db = Nette\Database\Explorer::createFromParameters(['driverClass' => MyDriver::class, /* extra ctor args */]);
```

--------------------------------

### Run tests against SQLite

Source: https://github.com/nette/database/blob/master/readme.md

Run the test suite against SQLite without any setup.

```bash
composer run tester
```

--------------------------------

### Select from table with Explorer

Source: https://github.com/nette/database/blob/master/readme.md

Start selecting data from a table by calling table() on the Explorer object.

```php
$selection = $explorer->table('book'); // db table name is "book"
```

--------------------------------

### Example - Row Mapping

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/explorer.md

Demonstrates how to map tables to custom ActiveRow subclasses using setRowMapping.

```APIDOC
## Example - Row Mapping

### Description
Demonstrates how to map tables to custom ActiveRow subclasses using setRowMapping.

### Code Example
```php
use Nette\Database\Explorer;
use Nette\Database\Table\ActiveRow;

class UserRow extends ActiveRow
{
	public function getFullName(): string
	{
		return $this->first_name . ' ' . $this->last_name;
	}
}

$db = Explorer::createFromDsn('sqlite:db.sqlite');
$db->setRowMapping(fn(string $table): string =>
    $table === 'users' ? UserRow::class : ActiveRow::class);

$user = $db->table('users')->get(1);
echo $user->getFullName();           // custom method on the mapped row
echo $user instanceof UserRow;       // true
```
```

--------------------------------

### Handle FileNotFoundException on loadFromFile

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/helpers.md

Example of handling a missing SQL dump file. `Helpers::loadFromFile()` throws `Nette\FileNotFoundException` when the file cannot be opened; the catch block prints the exception message.

```php
use Nette\FileNotFoundException;

try {
    Helpers::loadFromFile($db, '/nonexistent.sql');
} catch (FileNotFoundException $e) {
    echo $e->getMessage();   // Cannot open file '/nonexistent.sql'.
}
```

--------------------------------

### Import SQL dump with progress callback

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/helpers.md

Example of importing an SQL dump with a progress callback. The callback receives the executed command count and a percentage (or null when unknown) and writes progress to STDERR. The method returns the total number of executed commands.

```php
use Nette\Database\Helpers;

$count = Helpers::loadFromFile($db, __DIR__ . '/dump.sql', function (int $count, ?float $percent): void {
    fwrite(STDERR, "[$count] " . ($percent === null ? '…' : round($percent, 1) . '%') . "\n");
});
echo "Executed $count commands";
```

--------------------------------

### DiscoveredConventions usage example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/conventions.md

Shows how to use the default discovered conventions with an SQLite database. The example accesses a related author via the author_id column, which is discovered from foreign key metadata.

```php
$db = Nette\Database\Explorer::createFromDsn('sqlite:shop.sqlite'); // default = discovered
$book = $db->table('book')->get(1);
echo $book->author->name;          // column author_id → table author discovered from FK metadata
```

--------------------------------

### Begin Transaction

Source: https://github.com/nette/database/blob/master/tests/Database.Tracy/panel.html

Starts a transaction in the database. This is the first SQL statement in the query log.

```sql
BEGIN TRANSACTION
```

--------------------------------

### SQL placeholder usage examples

Source: https://github.com/nette/database/blob/master/CLAUDE.md

Examples of SQL preprocessor placeholders: ?name for identifiers (only with trusted values), ?or for OR conditions (auto-detection uses AND by default), and context-aware array processing for INSERT, UPDATE, and WHERE clauses. Each shows the resulting SQL in comments.

```php
// Dynamic identifiers (use only with trusted values!)
$database->query('SELECT ?name FROM ?name', $column, $table);
// SELECT `name` FROM `users` (MySQL)

// OR conditions (auto-detection uses AND by default)
$database->query('SELECT * FROM users WHERE ?or', [
    'name' => 'John',
    'email' => 'john@example.com',
]);
// WHERE `name` = 'John' OR `email` = 'john@example.com'

// Context-aware array processing
$database->query('INSERT INTO users ?', ['name' => 'John', 'year' => 1994]);
// INSERT INTO users (`name`, `year`) VALUES ('John', 1994)

$database->query('UPDATE users SET ? WHERE id = ?', ['name' => 'John'], 1);
// UPDATE users SET `name` = 'John' WHERE id = 1

$database->query('SELECT * FROM users WHERE', ['active' => true, 'role' => 'admin']);
// WHERE `active` = 1 AND `role` = 'admin'
```

--------------------------------

### Rollback on error example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database.md

Demonstrates manual transaction handling with beginTransaction, commit, and rollBack. It catches LogicException when no transaction is active and re-throws the original exception.

```php
use Nette\Database\Database;

try {
    $db->beginTransaction();
    $db->query('UPDATE accounts SET balance = balance - 100 WHERE id = 1');
    if (random_int(0, 1)) {
        throw new \RuntimeException('simulated failure');
    }
    $db->commit();
} catch (\Throwable $e) {
    // roll back only while a transaction is active:
    try {
        $db->rollBack();
    } catch (\LogicException $e2) {
        // 'No active transaction to roll back.' — nothing to undo
    }
    throw $e;
}
```

--------------------------------

### SQL queries without caching (all columns)

Source: https://github.com/nette/database/blob/master/readme.md

Shows the four queries executed by the previous PHP example when caching is disabled. Demonstrates that the explorer fetches all columns and uses IN clauses to load related rows efficiently.

```sql
SELECT * FROM `book`
SELECT * FROM `author` WHERE (`author`.`id` IN (11, 12))
SELECT * FROM `book_tag` WHERE (`book_tag`.`book_id` IN (1, 4, 2, 3))
SELECT * FROM `tag` WHERE (`tag`.`id` IN (21, 22, 23))

```

--------------------------------

### Drivers\PDO\Connection::beginTransaction

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/pdo-drivers.md

Starts a transaction on the underlying PDO connection.

```APIDOC
## Method: `Drivers\PDO\Connection::beginTransaction`

### Description
Initiates a transaction on the PDO connection.

### Signature
```php
public function beginTransaction(): void
```

### Exceptions
- **DriverException** - If the transaction cannot be started, the `PDOException` is wrapped.
```

--------------------------------

### Iterate and fetch variants

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/result.md

Shows how to iterate over a Result object as a one-shot iterator, yielding Row instances, and how to use fetchAll() to get an array for multiple passes.

```php
$result = $db->query('SELECT * FROM users WHERE active = ?', 1);

foreach ($result as $row) {            // Row instances; one-shot iterator
    echo $row->name;
}

// $result->fetchAll() instead of iterating twice
$list = $db->query('SELECT * FROM users')->fetchAll();
while ($row = $list ? array_shift($list) : null) { /* ... */ }
```

--------------------------------

### Relationship access examples

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/active-row.md

Shows usage of implicit and explicit relationship access. The readme flow executes a constant number of batched queries (PK-IN queries per referenced table).

```php
$book  = $db->table('book')->get(2);
echo $book->author->name;                 // ref → author row (1 query, batched)
foreach ($book->related('book_tag') as $tag) { ... }   // has-many group
echo $book->ref('translator')->name;      // explicit
echo $book->related('book_tag', 'book_id'); // forced FK column
```

--------------------------------

### Nested transaction example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database.md

Shows how to use transaction() with a callback. The inner transaction becomes a savepoint, allowing nested transactional logic.

```php
$db->transaction(function (Nette\Database\Explorer $db) {
    $db->query('INSERT INTO orders', ['total' => 99]);
    $db->transaction(function ($db) {          // becomes a savepoint
        $db->query('INSERT INTO items', ['order_id' => $db->getInsertId()]);
    });
});
```

--------------------------------

### where array / whereOr / page example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/selection.md

Shows fluent usage of where() with an array condition, whereOr() for an OR group, and page() to fetch a specific page while optionally capturing the total number of pages via the &$numOfPages reference. The comment notes that $totalPages is only set when the reference argument is passed.

```php
$books = $db->table('book')
    ->where(['author_id' => 11, 'year > ?' => 2001])     // AND
    ->whereOr(['title LIKE ?' => '%PHP%', 'published' => 1]); // OR group

$page = $db->table('book')->page(2, 20, $totalPages);    // 2nd page, 20/page
echo $totalPages;                                        // ceil(count/20), only when &$numOfPages passed
```

--------------------------------

### query() usage with modes

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/sql-preprocessor.md

Shows three typical calls to $db->query() exercising INSERT, UPDATE, and SELECT modes. The examples illustrate multi-insert values, set-mode updates with ? placeholders, and where-clause construction with ? modes. The middle line includes key forms like 'last_login = ?' => [new DateTime, 'name+' => 'x'].

```php
$db->query('INSERT INTO users', [                      // mode values (INSERT), multi-insert
    ['name' => 'A', 'active' => true],
    ['name' => 'B', 'active' => false],
]);

$db->query('UPDATE users SET ? WHERE id = ?', [        // mode set
    'active' => 1,
    'last_login = ?' => [new DateTime, 'name+' => 'x'], // (illustrative key forms)
], 7);

$db->query('SELECT * FROM users WHERE ?', [            // mode and
    'active' => 1,
    'id > ?' => 100,
    'name IN ?' => ['A', 'B'],
]);
```

--------------------------------

### parseColumnType() usage example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/helpers.md

Example call to parseColumnType() with a DECIMAL type string, showing the returned array structure.

```php
Nette\Database\Helpers::parseColumnType('DECIMAL(10,2)');
// ['type' => 'DECIMAL', 'size' => 10, 'scale' => 2, 'parameters' => null]
```

--------------------------------

### Explorer initialization paths

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/explorer.md

Shows three recommended initialization paths: direct DSN with credentials, driver-array factory, and DI-provided (commented).

```php
use Nette\Database\Explorer;

// 1. dsn + credentials (readme form)
$db = new Explorer('mysql:host=localhost;dbname=shop', 'root', 'secret');

// 2. driver-array factory
$db = Explorer::createFromParameters([
    'driver' => 'pdo-sqlite',
    'dsn' => 'sqlite:/path/db.sqlite',
    'convertBoolean' => false,
]);

// 3. DI-provided (see database-extension.md)
```

--------------------------------

### Initialize database with createFromDsn and createFromParameters

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database.md

Shows two equivalent ways to initialize a database connection: using createFromDsn with a MySQL DSN and PDO options, or using createFromParameters with a driver key and DSN.

```php
use Nette\Database\Explorer;

$db = Explorer::createFromDsn('mysql:host=localhost;dbname=shop', 'root', 'secret', [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

// equivalent: driver key or custom class
$db = Explorer::createFromParameters(['driver' => 'pdo-pgsql', 'dsn' => 'pgsql:dbname=shop']);
```

--------------------------------

### Constructor

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/explorer.md

Creates a new Explorer instance. Accepts a Drivers\Driver instance or a DSN string with credentials.

```APIDOC
## Constructor

### Description
Creates a new Explorer instance. Accepts a Drivers\Driver instance or a DSN string with credentials.

### Method
Constructor

### Endpoint
`public function __construct(Drivers\Driver|string $driver, ...$args)`

### Parameters
- **driver** (Drivers\Driver|string) - Required - A Drivers\Driver instance or a DSN string.
- **...$args** (mixed) - Optional - Additional arguments for DSN connection (e.g., username, password).

### Request Example
```php
use Nette\Database\Explorer;

// 1. dsn + credentials (readme form)
$db = new Explorer('mysql:host=localhost;dbname=shop', 'root', 'secret');

// 2. driver-array factory
$db = Explorer::createFromParameters([
    'driver' => 'pdo-sqlite',
    'dsn' => 'sqlite:/path/db.sqlite',
    'convertBoolean' => false,
]);
```

### Response
#### Success Response
Returns a new Explorer instance.

#### Response Example
```php
$db = new Explorer('mysql:host=localhost;dbname=shop', 'root', 'secret');
```
```

--------------------------------

### Fetch single row with get() method

Source: https://github.com/nette/database/blob/master/readme.md

Fetch a single row by primary key using the get() method, which returns an ActiveRow instance.

```php
$book = $explorer->table('book')->get(2); // returns book with id 2
echo $book->title;
echo $book->author_id;
```

--------------------------------

### Error handling for undeclared columns

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/row.md

Error handling example: accessing an undeclared column (with a typo) throws Nette\MemberAccessException. The example catches the exception and prints the message, which includes a did-you-mean hint.

```php
use Nette\MemberAccessException;

$row = $db->fetch('SELECT id, name FROM users WHERE id = 1');

try {
    echo $row->nmae;        // typo
} catch (MemberAccessException $e) {
    echo $e->getMessage();  // Cannot read an undeclared column 'nmae', did you mean 'name'?
}
```

--------------------------------

### ConnectionPanel::initialize() static method signature

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/connection-panel.md

Shows the signature of the static initialize() method for registering the panel with an Explorer instance. Parameters include explorer, addBarPanel, name, explain, bar, and blueScreen.

```php
public static function initialize(
	Explorer $explorer,
	bool $addBarPanel = true,
	string $name = '',
	bool $explain = true,
	?Tracy\Bar $bar = null,
	?Tracy\BlueScreen $blueScreen = null,
): ?self
```

--------------------------------

### Row mapping example with custom ActiveRow

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/explorer.md

Example of mapping tables to custom ActiveRow subclasses. Defines UserRow with a custom method, sets the mapping via setRowMapping, and demonstrates usage.

```php
use Nette\Database\Explorer;
use Nette\Database\Table\ActiveRow;

class UserRow extends ActiveRow
{
	public function getFullName(): string
	{
		return $this->first_name . ' ' . $this->last_name;
	}
}

$db = Explorer::createFromDsn('sqlite:db.sqlite');
$db->setRowMapping(fn(string $table): string =>
    $table === 'users' ? UserRow::class : ActiveRow::class);

$user = $db->table('users')->get(1);
echo $user->getFullName();           // custom method on the mapped row
echo $user instanceof UserRow;       // true
```

--------------------------------

### Run all tests with test85.bat

Source: https://github.com/nette/database/blob/master/CLAUDE.md

Use the wrapper script C:/Tools/cmd/test85.bat to run all tests in the tests directory. The -s and -C flags are used. This is the recommended way to run tests, not vendor/bin/tester directly.

```bash
C:/Tools/cmd/test85.bat W:/Nette/Database/tests -s -C
```

--------------------------------

### Setting up caching and conventions

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database.md

Sets up caching and conventions on an Explorer instance. The setCache() call must precede any table() call. Uses FileStorage and StaticConventions with the given parameters.

```php
$storage = new Nette\Caching\Storages\FileStorage(__DIR__ . '/temp');
$db = Nette\Database\Explorer::createFromDsn('sqlite:db.sqlite');
$db->setCache(new Nette\Caching\Cache($storage));        // must precede any table() call
$db->setConventions(new Nette\Database\Conventions\StaticConventions('id', '%s_id', '%s'));
```

--------------------------------

### Drivers\Driver::connect

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/drivers.md

Establishes a connection to the database and returns a Drivers\Connection instance.

```APIDOC
## `Drivers\Driver::connect`

### Description
Establishes a connection to the database and returns a Drivers\Connection instance.

### Method
`connect(): Drivers\Connection`

### Returns
- **Drivers\Connection** - The connection instance.

### Throws
- **DriverException** - On connection failure.

### Example
```php
public function connect(): Drivers\Connection { /* ... */ }
```
```

--------------------------------

### Create MySQL Explorer via factory parameters

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/pdo-drivers.md

Configures a MySQL connection using Explorer::createFromParameters with driver, DSN, credentials, charset, sqlmode, and PDO options. The comment shows the equivalent createFromDsn call.

```php
use Nette\Database\Explorer;

$db = Explorer::createFromParameters([
    'driver' => 'pdo-mysql',
    'dsn' => 'mysql:host=localhost;dbname=shop',
    'username' => 'root',
    'password' => 'secret',
    'charset' => 'utf8mb4',
    'sqlmode' => 'STRICT_TRANS_TABLES',
    'options' => [PDO::ATTR_TIMEOUT => 5],
]);

// equals: Explorer::createFromDsn('mysql:…', 'root', 'secret', [
//    'charset' => 'utf8mb4', 'sqlmode' => '…', PDO::ATTR_TIMEOUT => 5 ]);
```

--------------------------------

### Error handling on database initialization

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database.md

Demonstrates error handling during initialization: Database::connect() wraps driver failures into ConnectionException, which is caught and its message echoed.

```php
use Nette\Database\Database;
use Nette\Database\ConnectionException;

try {
    $db = Database::createFromDsn('mysql:host=localhost;dbname=shop', 'root', 'wrong');
} catch (ConnectionException $e) {
    // Database::connect() wraps driver failures into ConnectionException
    echo $e->getMessage();
}
```

--------------------------------

### Inspect SQL and parameters during debugging

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/sql-builder.md

Use the internal getSqlBuilder() API to access the builder, then echo getSql() for the SQL and print_r(getParameters()) for bound parameters.

```php
$selection = $db->table('book')->where('author_id', 11)->order('title')->limit(5);

$builder = $selection->getSqlBuilder();            // @internal API
echo $selection->getSql();                          // implicit through Selection
print_r($builder->getParameters());                 // bound parameter list
```

--------------------------------

### Use whereOr() for OR conditions

Source: https://github.com/nette/database/blob/master/CLAUDE.md

whereOr() creates OR conditions. The example shows an array of conditions combined with OR, producing the SQL comment shown.

```php
$table->whereOr([
    'status' => 'active',
    'deleted' => false,
]);
// WHERE (`status` = 'active') OR (`deleted` = 0)
```

--------------------------------

### Minimal Neon configuration for database extension

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database-extension.md

Sets up the database extension with a single default connection using SQLite. The 'default' key is used, and the DSN points to a SQLite file. This configuration enables autowiring of Nette\Database\Explorer for the default connection.

```neon
extensions:
    database: Nette\Bridges\DatabaseDI\DatabaseExtension

database:
    default:
        dsn: 'sqlite:%appDir%/data/db.sqlite'

```

--------------------------------

### Format and JSON output of Nette\Database\DateTime

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/type-converter.md

Shows how to create a DateTime instance, echo it (using __toString() with microsecond precision), json_encode it (using jsonSerialize() to ISO 8601), and use the DateTimeInterface API on a fetched row.

```php
$created = new Nette\Database\DateTime('2024-05-01 10:20:30.123456');
echo $created;                    // 2024-05-01 10:20:30.123456
echo json_encode($created);       // "2024-05-01T10:20:30+00:00"

$row = $db->fetch('SELECT created_at FROM users WHERE id = 1');
echo $row->created_at->format('j.n.Y');   // DateTimeInterface API
```

--------------------------------

### Run single test file with test85.bat

Source: https://github.com/nette/database/blob/master/CLAUDE.md

Run a single test file, e.g., Explorer.basic.phpt, using the wrapper script. The -s and -C flags are used.

```bash
C:/Tools/cmd/test85.bat W:/Nette/Database/tests/Database/Explorer/Explorer.basic.phpt -s -C
```

--------------------------------

### whereOr error handling example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/selection.md

Demonstrates catching Nette\InvalidArgumentException when whereOr() receives a condition with more placeholders than values. The comment shows the exception message: 'Argument count does not match placeholder count.'

```php
use Nette\InvalidArgumentException;

try {
    $db->table('book')->whereOr(['a = ? AND b = ?' => 1]);  // 2 placeholders, 1 value
} catch (InvalidArgumentException $e) {
    // 'Argument count does not match placeholder count.'
}
```

--------------------------------

### Using update() and delete() on an active row

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/active-row.md

Example usage of update() and delete() on an active row. update() returns true when the row was changed, and delete() returns the number of affected rows (1 when deleted).

```php
if ($book->update(['title' => 'New Title'])) {
    echo "changed";
}

$n = $book->delete();   // 1 = deleted
```

--------------------------------

### fetchPairs with callback

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/result.md

Shows how to use fetchPairs with a callback to customize the key-value pairs returned from a query.

```APIDOC
## fetchPairs with callback

### Description
Use fetchPairs with a callback to transform each Row into a key-value pair for the resulting associative array.

### Usage
```php
$pairs = $db->query('SELECT id, first_name, last_name FROM users')->fetchPairs(
    fn(Nette\Database\Row $row): array => [$row->id, "$row->first_name $row->last_name"],
);
// [1 => 'Jim Carr', 2 => 'Ann Lee', ...]
```

### Notes
- The callback receives a Row and must return an array with exactly two elements: the key and the value.
- The result is an associative array mapping keys to values.
```

--------------------------------

### Child insert and delete example

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/grouped-selection.md

Demonstrates inserting and deleting related rows for a book. The insert with a single map forces book_id=1; the delete removes only that book's tags; the list form adds the column to each map.

```php
$book = $db->table('book')->get(1);

$book->related('book_tag')->insert(['tag_id' => 5]);   // book_id=1 forced
$affected = $book->related('book_tag')->delete();       // deletes book 1's tags only

$book->related('book_tag')->insert([
    ['tag_id' => 1],
    ['tag_id' => 2],
]);                                                  // list form, column added to each
```

--------------------------------

### Testing patterns with test() and testException()

Source: https://github.com/nette/database/blob/master/CLAUDE.md

Illustrates the project's testing conventions: a basic test using the test() function to assert on a fetched row and a testException() call to verify an exception type and message.

```php
test('descriptive name of what is being tested', function () use ($explorer) {
    $result = $explorer->table('book')->where('id', 1)->fetch();
    Assert::same('expected', $result->title);
});
```

```php
testException('throws exception for invalid input', function () use ($explorer) {
    $explorer->table('book')->get(999);
}, Nette\InvalidArgumentException::class, 'Expected message pattern');
```

--------------------------------

### Primary key introspection with getPrimaryKey and getPrimaryAutoincrementKey

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/structure.md

Retrieves the primary key and autoincrement column for a table. getPrimaryKey returns a string, array, or null; getPrimaryAutoincrementKey returns the autoincrement column or null. The example prints the autoincrement column if it exists.

```php
$structure = $db->getStructure();                     // @internal API
$primary = $structure->getPrimaryKey('book');         // 'id' | ['a','b'] | null

if ($auto = $structure->getPrimaryAutoincrementKey('book')) {
    echo "autoincrement column: $auto";
}
```

--------------------------------

### ConnectionPanel::initialize()

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/connection-panel.md

Static method to register the debug panel for an Explorer instance. It attaches a blue-screen panel and optionally adds a bar panel, returning the panel instance or null.

```APIDOC
## ConnectionPanel::initialize()

### Description
Static method to register the debug panel for an Explorer instance. It attaches a blue-screen panel and optionally adds a bar panel, returning the panel instance or null.

### Method
static

### Signature
```php
public static function initialize(
	Explorer $explorer,
	bool $addBarPanel = true,
	string $name = '',
	bool $explain = true,
	?Tracy\Bar $bar = null,
	?Tracy\BlueScreen $blueScreen = null,
): ?self
```

### Parameters
- **explorer** (Explorer) - Required - Connection to observe.
- **addBarPanel** (bool) - Optional (default: `true`) - When `false` only the blue-screen panel is registered and `null` is returned.
- **name** (string) - Optional (default: `''`) - Panel name.
- **explain** (bool) - Optional (default: `true`) - Explain flag.
- **bar** (?Tracy\Bar) - Optional (default: `null`) - `Tracy\Debugger::getBar()` when null.
- **blueScreen** (?Tracy\BlueScreen) - Optional (default: `null`) - `Tracy\Debugger::getBlueScreen()` when null.

### Behavior
Attaches `self::renderException(...)` as a blue-screen panel; when `$addBarPanel`, constructs the panel, sets `explain`/`name`, and adds it to the bar. This is the method the deprecated `Helpers::createDebugPanel()` / `initializeTracy()` delegate to.

### Example
```php
use Nette\Bridges\DatabaseTracy\ConnectionPanel;

$db = Nette\Database\Explorer::createFromDsn('sqlite:db.sqlite');
ConnectionPanel::initialize($db, addBarPanel: true, name: 'main', explain: true);
```
```

--------------------------------

### loadFromFile() signature

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/helpers.md

Signature of the static method `Helpers::loadFromFile()`. It executes an SQL dump file against an Explorer connection, supports `DELIMITER <x>` directives, and returns the number of executed commands. Throws `Nette\FileNotFoundException` if the file cannot be opened.

```php
public static function loadFromFile(Explorer $explorer, string $file, ?callable $onProgress = null): int
```

--------------------------------

### SqlPreprocessor::__construct(Explorer $explorer)

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/sql-preprocessor.md

Constructor for the SqlPreprocessor class, accepting an Explorer instance for driver and engine access.

```APIDOC
## SqlPreprocessor::__construct(Explorer $explorer)

### Description
Initializes the SQL preprocessor with the Explorer instance that provides the driver connection and engine for quoting, identifier delimiting, and date/interval formatting.

### Method
Constructor

### Parameters
- **explorer** (Explorer) - Required - Provides the driver connection (for quoting) and the engine (identifier delimiting, date/interval formatting).

### Response
No return value.
```

--------------------------------

### getSql(): string

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/sql-literal.md

Returns the raw SQL fragment stored in the SqlLiteral instance.

```APIDOC
## METHOD getSql(): string

### Description
Returns the raw SQL fragment that this SqlLiteral wraps.

### Returns
- **string** - The raw SQL fragment.

### Example
```php
$literal = Database::literal('UUID()');
$sql = $literal->getSql(); // 'UUID()'
```
```

--------------------------------

### Constructor

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/selection.md

Creates a new Selection instance for a given table.

```APIDOC
## Constructor

### Description
Creates a new Selection instance for a given table.

### Method
Constructor

### Signature
```php
public function __construct(
	Explorer $explorer,
	string $tableName,
)
```

### Parameters
- **explorer** (Explorer) - Required - Owning explorer (source of engine, cache, conventions, structure).
- **tableName** (string) - Required - Table name; may be schema-qualified (`schema.table`) or aliased via `alias()`.

```

--------------------------------

### Fetch shortcut method signatures

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database.md

Method signatures for the fetch shortcuts on the database connection. Each executes query() and reads the first row/field from the result. fetchPairs() returns key-value pairs, literal() builds an unescaped SqlLiteral.

```php
public function fetch(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): ?Row
public function fetchAssoc(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): ?array    // ?array<mixed>
public function fetchField(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): mixed
public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): ?array     // ?list<mixed>
public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): ?array   // alias of fetchList()
public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): array     // array<mixed, mixed>
public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] mixed ...$params): array       // list<Row>
public static function literal(string $value, mixed ...$params): SqlLiteral
```

--------------------------------

### Configure default database connection with DatabaseExtension

Source: https://github.com/nette/database/blob/master/_autodocs/configuration.md

Configure a single default database connection under the `database:` section. The `dsn` is required; `user`, `password`, `conventions`, and `mapping` are optional. The `conventions` value `discovered` is the default and performs no action. The `mapping.convention` pattern uses `*` as a placeholder for the table name, and `mapping.tables` maps specific table names to ActiveRow subclasses.

```neon
database:
    default:
        dsn: 'mysql:host=localhost;dbname=shop'
        user: root
        password: secret
        conventions: discovered
        mapping:
            convention: App\Model\Row\*Row      # App\Model\Row\UserRow for table 'user'
            tables:
                special_table: App\Model\SpecialRow
```

--------------------------------

### beforeCompile(): Attach Tracy ConnectionPanel

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/database-extension.md

Attaches the Nette\Bridges\DatabaseTracy\ConnectionPanel to a database connection when the debugger is enabled or a Tracy\BlueScreen exists. Uses addSetup() with the connection instance, debug mode flag, connection name, and whether EXPLAIN is enabled.

```php
$connection->addSetup(
	[Nette\Bridges\DatabaseTracy\ConnectionPanel::class, 'initialize'],
	[$connection, $this->debugMode, $name, !empty($config->explain)],
);
```

--------------------------------

### Explorer constructor signature

Source: https://github.com/nette/database/blob/master/_autodocs/api-reference/explorer.md

Constructor signature inherited from Database. Accepts a Drivers\Driver instance or a string DSN.

```php
public function __construct(
	Drivers\Driver|string $driver,
)
```
Tokens:
Raw