Podatkovna zbirka Nette
***********************

.[perex]
Nette Database je zmogljiv in eleganten sloj podatkovne baze za PHP, znan po svoji preprostosti in pametnih funkcijah. Ne zahteva zapletene konfiguracije ali ustvarjanja entitet, zato lahko z njo začnete delati takoj.

Z Nette Database lahko delate na dva načina:

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


[Neposredni SQL |Direct SQL]
============================
- Varne, parametrirane poizvedbe
- Natančen nadzor nad strukturo poizvedb SQL
- Idealno za pisanje zapletenih poizvedb z naprednimi funkcijami
- Optimizacija zmogljivosti z uporabo posebnih funkcij SQL

</div>

<div>


[Raziskovalec |Explorer]
========================
- Hiter razvoj brez pisanja SQL
- Intuitivno upravljanje razmerij med tabelami
- Samodejna optimizacija poizvedb
- Odlično za hitro in priročno interakcijo s podatkovno bazo

</div>

</div>


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

Knjižnico lahko prenesete in namestite s [programom Composer |best-practices:composer]:

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


Povezava in konfiguracija .[#toc-connection-and-configuration]
==============================================================

Če se želite povezati s podatkovno zbirko, preprosto ustvarite primerek razreda [api:Nette\Database\Connection]:

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

Parameter `$dsn` (ime vira podatkov) ima enako obliko, kot jo [uporablja PDO |https://www.php.net/manual/en/pdo.construct.php#refsect1-pdo.construct-parameters], npr. `host=127.0.0.1;dbname=test`. Če povezava ne uspe, se vrže razred `Nette\Database\ConnectionException`.

Vendar je priročnejša metoda uporaba [konfiguracije aplikacije |configuration]. Dodajte razdelek `database` in ustvarjeni bodo potrebni objekti, vključno s ploščo podatkovne zbirke v [Tracy |tracy:] Debug Bar.

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

Po tem lahko objekt povezave [pridobite kot storitev iz vsebnika DI, |dependency-injection:passing-dependencies] npr:

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

Za več informacij glejte [Konfiguracija podatkovne baze |configuration].


Dva pristopa k delu s podatkovno bazo .[#toc-two-approaches-to-database-work]
=============================================================================

V podatkovni zbirki Nette lahko poizvedbe SQL pišete neposredno (neposredni pristop) ali pustite, da se SQL generira samodejno (pristop raziskovalca). Oglejmo si, kako oba pristopa rešujeta iste naloge:

[Neposredni pristop |direct-sql] - pisanje poizvedb SQL

```php
// Vstavljanje zapisa
$database->query('INSERT INTO books', [
	'author_id' => $authorId,
	'title' => $bookData->title,
	'published_at' => new DateTime,
]);

// Pridobivanje zapisov: avtorji knjig
$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
');

// Prikaz (ni optimalno, ustvarja N dodatnih poizvedb)
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";
	}
}
```

[Raziskovalni pristop |explorer] - samodejno generiranje SQL

```php
// Vstavljanje zapisa
$database->table('books')->insert([
	'author_id' => $authorId,
	'title' => $bookData->title,
	'published_at' => new DateTime,
]);

// Pridobivanje zapisov: avtorji knjig
$authors = $database->table('authors')
	->where('active', 1);

// Prikaz (samodejno ustvari le 2 optimizirani poizvedbi)
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";
	}
}
```

Pristop Explorer samodejno generira in optimizira poizvedbe SQL. V zgornjem primeru neposredni pristop ustvari N+1 poizvedb (eno za avtorje in eno za knjige vsakega avtorja), medtem ko raziskovalec izvede le dve optimizirani poizvedbi - eno za avtorje in drugo za vse njihove knjige.

Oba pristopa lahko po potrebi poljubno kombinirate v svoji aplikaciji.


Upravljanje povezav .[#toc-connection-management]
=================================================

Ko ustvarite objekt `Connection`, se ta samodejno poveže s podatkovno bazo. Če želite povezavo odložiti, v [konfiguraciji |configuration] omogočite leni način z nastavitvijo `lazy`, ali pa to storite na naslednji način:

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

Za upravljanje povezave uporabite metode `connect()`, `disconnect()` in `reconnect()`.
- `connect()` vzpostavi povezavo, če še ni bila vzpostavljena, in lahko vrže metodo `Nette\Database\ConnectionException`.
- `disconnect()` prekine povezavo s podatkovno zbirko.
- `reconnect()` prekine povezavo in se nato ponovno poveže s podatkovno zbirko, pri čemer lahko vrže tudi `Nette\Database\ConnectionException`.

Poleg tega lahko spremljate dogodke povezave z uporabo dogodka `onConnect`, ki je niz povratnih klicev, izvedenih po vzpostavitvi povezave s podatkovno bazo.

```php
// se pokliče po vzpostavitvi povezave s podatkovno bazo
$database->onConnect[] = function($database) {
	echo "Connected to the database";
};
```


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

Če uporabljate [program Tracy |tracy:], je plošča Podatkovna baza v vrstici za odpravljanje napak samodejno omogočena. Na njej so prikazane vse izvedene poizvedbe, njihovi parametri, čas izvedbe in mesto v kodi, kjer so bile poklicane.

[* db-panel.webp *]


Podprte zbirke podatkov .[#toc-supported-databases]
===================================================

Podatkovna baza Nette podpira naslednje podatkovne baze:

| **Server zbirke podatkov** | **Naziv DNS** | **Podpora za raziskovalca** |
|-----------------------|--------------|-----------------------|
| MySQL (>= 5.1) | mysql | YES |
| PostgreSQL (>= 9.0) | pgsql | DA |
| SQLite 3 (>= 3.8) | sqlite | DA | DA |
| Oracle | oci | NE |
| MS SQL (PDO_SQLSRV) | sqlsrv | DA |
| MS SQL (PDO_DBLIB) | mssql | NE |
| ODBC | odbc | NE | NE