Nette adatbázis
***************

.[perex]
A Nette Database egy nagy teljesítményű és elegáns adatbázis réteg PHP-hoz, amely egyszerűségéről és intelligens funkcióiról ismert. Nem igényel bonyolult konfigurációt vagy entitásgenerálást, így azonnal elkezdhet vele dolgozni.

A Nette Database segítségével kétféleképpen dolgozhat:

<div class="grid gap-3">
<div>


[Közvetlen SQL |Direct SQL]
===========================
- Biztonságos, paraméterezett lekérdezések
- Az SQL-lekérdezések szerkezetének pontos ellenőrzése
- Ideális összetett lekérdezések írásához fejlett függvényekkel
- A teljesítmény optimalizálása speciális SQL függvények használatával

</div>

<div>


[Explorer |Explorer]
====================
- Gyors fejlesztés SQL írása nélkül
- A táblák közötti kapcsolatok intuitív kezelése
- Automatikus lekérdezés-optimalizálás
- Nagyszerű a gyors és kényelmes adatbázis-interakciókhoz

</div>

</div>


Telepítés .[#toc-installation]
==============================

A könyvtárat a [Composer |best-practices:composer] segítségével töltheti le és telepítheti:

```shell
composer require nette/database
```


Csatlakozás és konfiguráció .[#toc-connection-and-configuration]
================================================================

Az adatbázishoz való csatlakozáshoz egyszerűen hozzon létre egy példányt a [api:Nette\Database\Connection] osztályból:

```php
$database = new Nette\Database\Connection($dsn, $user, $password);
```

A `$dsn` (adatforrás neve) paraméter ugyanazt a formátumot követi, mint [amit a PDO használ |https://www.php.net/manual/en/pdo.construct.php#refsect1-pdo.construct-parameters], pl. `host=127.0.0.1;dbname=test`. Ha a kapcsolat sikertelen, akkor a `Nette\Database\ConnectionException`.

Kényelmesebb módszer azonban az [alkalmazás konfigurációjának |configuration] használata. Adjon hozzá egy `database` szakaszt, és a szükséges objektumok létrejönnek, beleértve egy adatbázis panelt a [Tracy |tracy:] Debug Barban.

```neon
database:
	dsn: 'mysql:host=127.0.0.1;dbname=test'
	user: root
	password: password
```

Ezt követően a kapcsolat objektum [szolgáltatásként lekérhető a DI konténerből |dependency-injection:passing-dependencies], pl:

```php
class Model
{
	public function __construct(
		private Nette\Database\Connection $database,
	) {
	}
}
```

További információért lásd: [Adatbázis konfiguráció |configuration].


Az adatbázis-munka két megközelítése .[#toc-two-approaches-to-database-work]
============================================================================

A Nette Database segítségével vagy közvetlenül írhat SQL-lekérdezéseket (közvetlen megközelítés), vagy hagyhatja, hogy az SQL automatikusan generálódjon (felfedező megközelítés). Lássuk, hogyan oldja meg mindkét megközelítés ugyanazt a feladatot:

[Közvetlen megközelítés |direct-sql] - SQL-lekérdezések írása

```php
// Rekord beszúrása
$database->query('INSERT INTO books', [
	'author_id' => $authorId,
	'title' => $bookData->title,
	'published_at' => new DateTime,
]);

// Rekordok lekérdezése: könyvszerzők
$result = $database->query('
	SELECT authors.*, COUNT(books.id) AS books_count
	FROM authors
	LEFT JOIN books ON authors.id = books.author_id
	WHERE authors.active = 1
	GROUP BY authors.id
');

// Megjelenítés (nem optimális, N további lekérdezést generál)
foreach ($result as $author) {
	$books = $database->query('
		SELECT * FROM books
		WHERE author_id = ?
		ORDER BY published_at DESC
	', $author->id);

	echo "Author $author->name has written $author->books_count books:\n";

	foreach ($books as $book) {
		echo "- $book->title\n";
	}
}
```

[Explorer megközelítés |explorer] - Automatikus SQL generálás

```php
// Rekord beszúrása
$database->table('books')->insert([
	'author_id' => $authorId,
	'title' => $bookData->title,
	'published_at' => new DateTime,
]);

// Rekordok lekérdezése: könyvszerzők
$authors = $database->table('authors')
	->where('active', 1);

// Megjelenítés (automatikusan csak 2 optimalizált lekérdezést generál)
foreach ($authors as $author) {
	$books = $author->related('books')
		->order('published_at DESC');

	echo "Author $author->name has written {$books->count()} books:\n";

	foreach ($books as $book) {
		echo "- $book->title\n";
	}
}
```

Az Explorer megközelítés automatikusan generálja és optimalizálja az SQL-lekérdezéseket. A fenti példában a közvetlen megközelítés N+1 lekérdezést generál (egyet a szerzőkre és egyet az egyes szerzők könyveire), míg az Explorer csak két optimalizált lekérdezést hajt végre - egyet a szerzőkre és egyet az összes könyvükre.

Szükség szerint szabadon kombinálhatja a két megközelítést az alkalmazásban.


Kapcsolatkezelés .[#toc-connection-management]
==============================================

Amikor létrehoz egy `Connection` objektumot, az automatikusan csatlakozik az adatbázishoz. Ha késleltetni szeretné a csatlakozást, engedélyezze a [konfigurációban |configuration] a lusta üzemmódot a `lazy` beállításával, vagy tegye ezt a következőképpen:

```php
$database = new Nette\Database\Connection($dsn, $user, $password, ['lazy' => true]);
```

A kapcsolat kezeléséhez használja a `connect()`, a `disconnect()` és a `reconnect()` metódusokat.
- A `connect()` létrehozza a kapcsolatot, ha az még nem jött létre, és dobhat egy `Nette\Database\ConnectionException`.
- A `disconnect()` megszakítja a kapcsolatot az adatbázissal.
- A `reconnect()` megszakítja a kapcsolatot, majd újra csatlakozik az adatbázishoz, és szintén dobhat egy `Nette\Database\ConnectionException`.

Ezenkívül a kapcsolati eseményeket a `onConnect` esemény segítségével is figyelemmel kísérheti, amely az adatbázishoz való kapcsolódás után végrehajtott visszahívások tömbje.

```php
// Az adatbázishoz való csatlakozás után hívódik
$database->onConnect[] = function($database) {
	echo "Connected to the database";
};
```


Tracy Debug Bar .[#toc-tracy-debug-bar]
=======================================

Ha a [Tracy-t |tracy:] használja, a hibakeresési sáv adatbázis panelje automatikusan engedélyezve van. Megjeleníti az összes végrehajtott lekérdezést, azok paramétereit, a végrehajtás idejét és a kódban a meghívás helyét.

[* db-panel.webp *]


Támogatott adatbázisok .[#toc-supported-databases]
==================================================

A Nette Database a következő adatbázisokat támogatja:

| **Adatbáziskiszolgáló** | **DSN név** | **Explorer támogatás** | |
|-----------------------|--------------|-----------------------|
| MySQL (>= 5.1) | mysql | IGEN |
| PostgreSQL (>= 9.0) | pgsql | IGEN |
| SQLite 3 (>= 3.8) | sqlite | YES | YES |
| Oracle | oci | NEM | NEM |
| MS SQL (PDO_SQLSRV) | sqlsrv | IGEN | YES |
| MS SQL (PDO_DBLIB) | mssql | NEM | NEM | MS SQL (PDO_DBLIB) | mssql | NEM |
| ODBC | odbc | NEM | NEM |