Nette Database
**************

.[perex]
Nette Database es una capa de base de datos potente y elegante para PHP, centrada en la sencillez y en las funciones inteligentes. Ofrece dos formas de trabajar con la base de datos: el [Explorer |explorer] para desarrollar aplicaciones rápidamente, o el [enfoque SQL |SQL way] para manipular las consultas directamente.

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


[Enfoque SQL|sql-way]
=====================
- consultas seguras y parametrizadas
- control preciso sobre la estructura de la consulta SQL
- cuando se escriben consultas complejas con funciones avanzadas
- optimizar el rendimiento con funciones SQL concretas

</div>

<div>


[Explorer |explorer]
====================
- desarrollar rápido sin escribir SQL
- manejo intuitivo de las relaciones entre tablas
- aprovechar la optimización automática de las consultas
- adecuado para un trabajo rápido y cómodo con la base de datos

</div>

</div>


Instalación
===========

Descargue e instale la biblioteca con [Composer|best-practices:composer]:

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


Bases de datos compatibles
==========================

Nette Database soporta las siguientes bases de datos:

|* Servidor de base de datos |* Nombre DSN |* Soporte en Explorer
|-----------------------|--------------|-----------------------|
| MySQL (>= 5.1)        | mysql        | SÍ                    |
| PostgreSQL (>= 9.0)   | pgsql        | SÍ                    |
| SQLite 3 (>= 3.8)     | sqlite       | SÍ                    |
| Oracle                | oci          | NO                    |
| MS SQL (PDO_SQLSRV)   | sqlsrv       | SÍ                    |
| MS SQL (PDO_DBLIB)    | mssql        | NO                    |
| ODBC                  | odbc         | NO                    |


Dos enfoques para trabajar con la base de datos
===============================================

Nette Database le da a elegir: puede escribir las consultas SQL directamente (enfoque SQL) o dejar que se generen automáticamente (Explorer). Veamos cómo resuelven ambos enfoques las mismas tareas:

[Enfoque SQL|sql-way] - consultas SQL

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

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

// Muestra (no es óptimo, genera N consultas adicionales)
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";
	}
}
```

[Enfoque Explorer|explorer] - generación automática de SQL

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

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

// Muestra (genera automáticamente solo 2 consultas optimizadas)
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";
	}
}
```

El enfoque Explorer genera y optimiza las consultas SQL automáticamente. En el ejemplo anterior, el enfoque SQL genera N+1 consultas (una para los autores y luego una para los libros de cada autor), mientras que Explorer optimiza las consultas automáticamente y ejecuta solo dos: una para los autores y otra para todos sus libros.

Ambos enfoques se pueden combinar libremente en su aplicación según haga falta.


Conexión y configuración
========================

Para conectarse a la base de datos basta con crear una instancia de la clase [api:Nette\Database\Connection]:

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

El parámetro `$dsn` (Data Source Name) es el mismo que [usa PDO |https://www.php.net/manual/en/pdo.construct.php#refsect1-pdo.construct-parameters], p. ej. `host=127.0.0.1;dbname=test`. En caso de fallo lanza una `Nette\Database\ConnectionException`.

Un método más cómodo lo ofrece, sin embargo, la [configuración de la aplicación |configuration], donde solo hay que añadir una sección `database`. Eso crea los objetos necesarios y también un panel de base de datos en la barra de [Tracy |tracy:].

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

El objeto de la conexión se puede después [obtener como servicio del contenedor DI |dependency-injection:passing-dependencies], p. ej.:

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

Más información sobre la [configuración de la base de datos|configuration].


Creación manual de Explorer
---------------------------

Si no usa el contenedor DI de Nette, puede crear una instancia de `Nette\Database\Explorer` manualmente:

```php
// conexión a la base de datos
$connection = new Nette\Database\Connection('mysql:host=127.0.0.1;dbname=mydatabase', 'user', 'password');
// almacenamiento de caché, implementa Nette\Caching\Storage, p. ej.:
$storage = new Nette\Caching\Storages\FileStorage('/path/to/temp/dir');
// se ocupa de la reflexión de la estructura de la base de datos
$structure = new Nette\Database\Structure($connection, $storage);
// define las reglas de mapeo de nombres de tablas, columnas y claves foráneas
$conventions = new Nette\Database\Conventions\DiscoveredConventions($structure);
$explorer = new Nette\Database\Explorer($connection, $structure, $conventions, $storage);
```


Gestión de la conexión
======================

Al crear un objeto `Connection`, la conexión se establece automáticamente. Si quiere retrasarla, use el modo lazy: actívelo en la [configuración|configuration] con `lazy`, o así:

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

Para gestionar la conexión use los métodos `connect()`, `disconnect()` y `reconnect()`.
- `connect()` crea la conexión si todavía no existe y puede lanzar una `Nette\Database\ConnectionException`.
- `disconnect()` cierra la conexión actual a la base de datos.
- `reconnect()` cierra la conexión y vuelve a conectarse a la base de datos. Este método también puede lanzar una `Nette\Database\ConnectionException`.

Además puede vigilar los eventos relacionados con la conexión mediante el evento `onConnect`, que es un array de callbacks que se llaman después de establecer la conexión con la base de datos.

```php
// se ejecuta tras conectar con la base de datos
$database->onConnect[] = function($database) {
	echo "Connected to the database";
};
```

El evento `onQuery` funciona de forma parecida: es un array de callbacks invocados después de cada consulta ejecutada (y cuando una consulta falla), útil para el registro o el perfilado.


Barra de depuración de Tracy
============================

Si usa [Tracy |tracy:], el panel Database de la Debug Bar se activa automáticamente. Muestra todas las consultas ejecutadas, sus parámetros, el tiempo de ejecución y el lugar del código desde el que se llamaron.

[* db-panel.webp *]