Baza de date Nette
******************

.[perex]
Nette Database este un strat de bază de date puternic și elegant pentru PHP, cunoscut pentru simplitatea și caracteristicile sale inteligente. Nu necesită configurare complexă sau generare de entități, permițându-vă să începeți să lucrați cu el imediat.

Cu Nette Database, puteți lucra în două moduri:

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


[SQL direct |Direct SQL]
========================
- Interogări sigure, parametrizate
- Control precis asupra structurii interogărilor SQL
- Ideal pentru scrierea de interogări complexe cu funcții avansate
- Optimizarea performanței utilizând funcții SQL specifice

</div>

<div>


[Explorator |Explorer]
======================
- Dezvoltare rapidă fără a scrie SQL
- Gestionarea intuitivă a relațiilor dintre tabele
- Optimizarea automată a interogărilor
- Excelent pentru interacțiuni rapide și convenabile cu baza de date

</div>

</div>


Instalare .[#toc-installation]
==============================

Puteți descărca și instala biblioteca utilizând [Composer |best-practices:composer]:

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


Conectare și configurare .[#toc-connection-and-configuration]
=============================================================

Pentru a vă conecta la baza de date, creați pur și simplu o instanță a clasei [api:Nette\Database\Connection]:

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

Parametrul `$dsn` (Data Source Name) urmează același format [utilizat de PDO |https://www.php.net/manual/en/pdo.construct.php#refsect1-pdo.construct-parameters], de exemplu, `host=127.0.0.1;dbname=test`. În cazul în care conexiunea eșuează, se aruncă clasa `Nette\Database\ConnectionException`.

Cu toate acestea, o metodă mai convenabilă este de a utiliza [configurația aplicației |configuration]. Adăugați o secțiune `database`, iar obiectele necesare vor fi create, inclusiv un panou pentru baza de date în [Tracy |tracy:] Debug Bar.

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

După aceasta, obiectul conexiune poate fi [preluat ca serviciu din containerul DI |dependency-injection:passing-dependencies], de ex:

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

Pentru mai multe informații, consultați [configurarea bazei de date |configuration].


Două abordări ale lucrului cu baza de date .[#toc-two-approaches-to-database-work]
==================================================================================

Cu Nette Database, puteți scrie interogări SQL direct (abordare directă) sau puteți lăsa ca SQL să fie generat automat (abordare Explorer). Să vedem cum rezolvă ambele abordări aceleași sarcini:

[Abordare directă |direct-sql] - Scrierea interogărilor SQL

```php
// Introduceți o înregistrare
$database->query('INSERT INTO books', [
	'author_id' => $authorId,
	'title' => $bookData->title,
	'published_at' => new DateTime,
]);

// Recuperarea înregistrărilor: autori de cărți
$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
');

// Afișare (nu este optim, generează N interogări suplimentare)
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";
	}
}
```

[Abordare Explorer |explorer] - Generarea automată SQL

```php
// Introduceți o înregistrare
$database->table('books')->insert([
	'author_id' => $authorId,
	'title' => $bookData->title,
	'published_at' => new DateTime,
]);

// Recuperarea înregistrărilor: autori de cărți
$authors = $database->table('authors')
	->where('active', 1);

// Afișare (generează automat doar 2 interogări optimizate)
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";
	}
}
```

Abordarea Explorer generează și optimizează automat interogările SQL. În exemplul de mai sus, abordarea directă generează N+1 interogări (una pentru autori și una pentru cărțile fiecărui autor), în timp ce Explorer efectuează doar două interogări optimizate - una pentru autori și alta pentru toate cărțile acestora.

Puteți combina liber ambele abordări în aplicația dvs. în funcție de necesități.


Gestionarea conexiunilor .[#toc-connection-management]
======================================================

Atunci când creați un obiect `Connection`, acesta se conectează automat la baza de date. Dacă doriți să întârziați conectarea, activați modul leneș în [configurare |configuration] prin setarea `lazy`, sau procedați astfel:

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

Pentru a gestiona conexiunea, utilizați metodele `connect()`, `disconnect()`, și `reconnect()`.
- `connect()` stabilește o conexiune dacă aceasta nu a fost deja stabilită și poate arunca un mesaj `Nette\Database\ConnectionException`.
- `disconnect()` se deconectează de la baza de date.
- `reconnect()` se deconectează și apoi se reconectează la baza de date și poate genera, de asemenea, o eroare `Nette\Database\ConnectionException`.

În plus, puteți monitoriza evenimentele de conectare utilizând evenimentul `onConnect`, care este o matrice de callback-uri executate după conectarea la baza de date.

```php
// Apelat după conectarea la baza de date
$database->onConnect[] = function($database) {
	echo "Connected to the database";
};
```


Bara de depanare Tracy .[#toc-tracy-debug-bar]
==============================================

Dacă utilizați [Tracy |tracy:], panoul Database din Debug Bar este activat automat. Acesta afișează toate interogările executate, parametrii acestora, timpul de execuție și locația din cod în care au fost apelate.

[* db-panel.webp *]


Baze de date acceptate .[#toc-supported-databases]
==================================================

Nette Database suportă următoarele baze de date:

| **Database Server** | **DSN Name** | **Explorer Support** |
|-----------------------|--------------|-----------------------|
| MySQL (>= 5.1) | mysql | YES |
| PostgreSQL (>= 9.0) | pgsql | DA |
| SQLite 3 (>= 3.8) | sqlite | DA |
| Oracle | oci | NU |
| MS SQL (PDO_SQLSRV) | sqlsrv | DA |
| MS SQL (PDO_DBLIB) | mssql | NU |
| ODBC | odbc | NU |