Banco de dados Nette
********************

.[perex]
O Nette Database é uma camada de banco de dados poderosa e elegante para PHP, conhecida por sua simplicidade e recursos inteligentes. Ele não requer configuração complexa nem geração de entidades, permitindo que você comece a trabalhar com ele imediatamente.

Com o Nette Database, você pode trabalhar de duas maneiras:

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


[SQL direto |Direct SQL]
========================
- Consultas seguras e parametrizadas
- Controle preciso sobre a estrutura das consultas SQL
- Ideal para escrever consultas complexas com funções avançadas
- Otimize o desempenho usando funções SQL específicas

</div>

<div>


[Explorador |Explorer]
======================
- Desenvolvimento rápido sem escrever SQL
- Tratamento intuitivo de relacionamentos entre tabelas
- Otimização automática de consultas
- Excelente para interações rápidas e convenientes com o banco de dados

</div>

</div>


Instalação .[#toc-installation]
===============================

Você pode fazer download e instalar a biblioteca usando o [Composer |best-practices:composer]:

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


Conexão e configuração .[#toc-connection-and-configuration]
===========================================================

Para se conectar ao banco de dados, basta criar uma instância da classe [api:Nette\Database\Connection]:

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

O parâmetro `$dsn` (Data Source Name) segue o mesmo formato [usado pelo PDO |https://www.php.net/manual/en/pdo.construct.php#refsect1-pdo.construct-parameters], por exemplo, `host=127.0.0.1;dbname=test`. Se a conexão falhar, será lançado o erro `Nette\Database\ConnectionException`.

No entanto, um método mais conveniente é usar [a configuração do aplicativo |configuration]. Adicione uma seção `database` e os objetos necessários serão criados, inclusive um painel de banco de dados na [Tracy |tracy:] Debug Bar.

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

Depois disso, o objeto de conexão pode ser [recuperado como um serviço do contêiner DI |dependency-injection:passing-dependencies], por exemplo:

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

Para obter mais informações, consulte [configuração do banco de dados |configuration].


Duas abordagens para o trabalho com banco de dados .[#toc-two-approaches-to-database-work]
==========================================================================================

Com o Nette Database, você pode escrever consultas SQL diretamente (abordagem direta) ou deixar que o SQL seja gerado automaticamente (abordagem Explorer). Vamos ver como as duas abordagens resolvem as mesmas tarefas:

[Abordagem direta |direct-sql] - Escrevendo consultas SQL

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

// Recuperar registros: autores de livros
$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
');

// Exibir (não é o ideal, gera N consultas adicionais)
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";
	}
}
```

[Abordagem Explorer |explorer] - Geração automática de SQL

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

// Recuperar registros: autores de livros
$authors = $database->table('authors')
	->where('active', 1);

// Exibir (gera automaticamente apenas 2 consultas otimizadas)
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";
	}
}
```

A abordagem Explorer gera e otimiza as consultas SQL automaticamente. No exemplo acima, a abordagem Direct gera N+1 consultas (uma para os autores e outra para os livros de cada autor), enquanto a Explorer executa apenas duas consultas otimizadas - uma para os autores e outra para todos os seus livros.

Você pode combinar livremente as duas abordagens em seu aplicativo, conforme necessário.


Gerenciamento de conexões .[#toc-connection-management]
=======================================================

Quando você cria um objeto `Connection`, ele se conecta ao banco de dados automaticamente. Se quiser atrasar a conexão, ative o modo preguiçoso na [configuração |configuration], definindo `lazy`, ou faça-o desta forma:

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

Para gerenciar a conexão, use os métodos `connect()`, `disconnect()` e `reconnect()`.
- `connect()` estabelece uma conexão se ela ainda não tiver sido estabelecida e pode lançar um `Nette\Database\ConnectionException`.
- `disconnect()` desconecta-se do banco de dados.
- `reconnect()` desconecta e, em seguida, reconecta-se ao banco de dados e também pode lançar um `Nette\Database\ConnectionException`.

Além disso, você pode monitorar os eventos de conexão usando o evento `onConnect`, que é uma matriz de retornos de chamada executados após a conexão com o banco de dados.

```php
// Chamado após a conexão com o banco de dados
$database->onConnect[] = function($database) {
	echo "Connected to the database";
};
```


Barra de depuração Tracy .[#toc-tracy-debug-bar]
================================================

Se você usa [o Tracy |tracy:], o painel Banco de dados na Barra de depuração é ativado automaticamente. Ele exibe todas as consultas executadas, seus parâmetros, o tempo de execução e o local no código em que foram chamadas.

[* db-panel.webp *]


Bancos de dados compatíveis .[#toc-supported-databases]
=======================================================

O Nette Database é compatível com os seguintes bancos de dados:

| **Servidor de banco de dados** | **Nome do DSN** | **Suporte ao explorador** |
|-----------------------|--------------|-----------------------|
| MySQL (>= 5.1) | mysql | YES |
| PostgreSQL (>= 9.0) | pgsql | YES |
| SQLite 3 (>= 3.8) | sqlite | YES |
| Oracle | oci | NÃO | SIM
| MS SQL (PDO_SQLSRV) | sqlsrv | SIM |
| MS SQL (PDO_DBLIB) | mssql | NÃO
| ODBC | odbc | NÃO