Clase de forja de base de datos

La clase Database Forge contiene métodos que le ayudarán a gestionar su base de datos.

Inicializando la clase Forge 

Importante

In order to initialize the Forge class, your database El controlador ya debe estar ejecutándose, ya que la clase Forge depende de él.

Cargue la clase Forge de la siguiente manera:

<?php

$forge = \Config\Database::forge();

También puede pasar otro nombre de grupo de base de datos al cargador DB Forge, en caso de que la base de datos que desea administrar no es la predeterminada:

<?php

$this->myforge = \Config\Database::forge('other_db');

En el ejemplo anterior, pasamos el nombre de un grupo de base de datos diferente. al que conectarse como primer parámetro.

Crear y eliminar bases de datos 

$forge->createDatabase(“db_name”)

Le permite crear la base de datos especificada en el primer parámetro. Devuelve verdadero/falso según el éxito o el fracaso:

<?php

if ($forge->createDatabase('my_db')) {
    echo 'Database created!';
}

Un segundo parámetro opcional establecido en verdadero agregará la declaración SI EXISTE o comprobará si existe una base de datos antes de crearla (dependiendo del DBMS).

<?php

$forge->createDatabase('my_db', true);
/*
 * gives CREATE DATABASE IF NOT EXISTS `my_db`
 * or will check if a database exists
 */

$forge->dropDatabase(“db_name”)

Le permite eliminar la base de datos especificada en el primer parámetro. Devuelve verdadero/falso según el éxito o el fracaso:

<?php

if ($forge->dropDatabase('my_db')) {
    echo 'Database deleted!';
}

Crear bases de datos en la línea de comando 

Higgs admite la creación de bases de datos directamente desde su terminal favorito utilizando el db:create dedicado. dominio. Al utilizar este comando se supone que la base de datos aún no existe. De lo contrario, Higgs se quejará de que la creación de la base de datos ha fallado.

Para comenzar, simplemente escriba el comando y el nombre de la base de datos (por ejemplo, foo):

php spark db: crear foo

Si todo salió bien, deberías esperar que se muestre el mensaje ``Base de datos «foo» creada exitosamente””.

Si está en un entorno de prueba o está utilizando el controlador SQLite3, puede pasar la extensión del archivo para el archivo donde se creará la base de datos usando la opción --ext. Los valores válidos son db y sqlite y por defecto es db. Recuerde que estos no deben ir precedidos de un punto. :

php spark db: crear foo --ext sqlite

El comando anterior creará el archivo db en WRITEPATH/foo.sqlite.

Nota

When using the special SQLite3 database name :memory:, expect that the command will still produce un mensaje de éxito pero no se crea ningún archivo de base de datos. Esto se debe a que SQLite3 simplemente usará una base de datos en memoria.

Crear tablas 

Hay varias cosas que quizás desee hacer al crear tablas. Agregar campos, agregar claves a la tabla, modificar columnas. Higgs proporciona una mecanismo para ello.

Agregar campos 

$forjar->addField()

Los campos normalmente se crean mediante una matriz asociativa. Dentro de la matriz, debes incluya una clave tipo que se relacione con el tipo de datos del campo.

Por ejemplo, INT, VARCHAR, TEXT, etc. Muchos tipos de datos (por ejemplo, VARCHAR) también requieren una clave constraint.

<?php

$fields = [
    'users' => [
        'type'       => 'VARCHAR',
        'constraint' => 100,
    ],
];
// will translate to "users VARCHAR(100)" when the field is added.

Además, se pueden utilizar las siguientes claves/valores:

unsigned/true: para generar UNSIGNED en la definición del campo.
default/value: para generar la restricción DEFAULT en la definición del campo.
null/true: para generar NULL en la definición del campo. Sin esto,
el campo por defecto será NO NULO.
auto_increment/true: genera un indicador de auto_increment en el
campo. Tenga en cuenta que el tipo de campo debe ser un tipo que admita esto, como por ejemplo INTEGER.
unique/true: para generar una clave única para la definición del campo.

<?php

$fields = [
    'id' => [
        'type'           => 'INT',
        'constraint'     => 5,
        'unsigned'       => true,
        'auto_increment' => true,
    ],
    'title' => [
        'type'       => 'VARCHAR',
        'constraint' => '100',
        'unique'     => true,
    ],
    'author' => [
        'type'       => 'VARCHAR',
        'constraint' => 100,
        'default'    => 'King of Town',
    ],
    'description' => [
        'type' => 'TEXT',
        'null' => true,
    ],
    'status' => [
        'type'       => 'ENUM',
        'constraint' => ['publish', 'pending', 'draft'],
        'default'    => 'pending',
    ],
];
$forge->addField($fields);

Una vez definidos los campos, se pueden agregar usando $forge->addField($fields) seguido de una llamada al crearTabla() método.

Notas sobre tipos de datos

Tipos de punto flotante

Los tipos de punto flotante como FLOAT y DOUBLE representan valores aproximados. Por lo tanto, no deben usarse cuando se necesitan valores exactos.

mysql> CREAR TABLA t (f FLOAT, d DOBLE);
mysql> INSERTAR EN t VALORES (99.9, 99.9);

mysql> SELECCIONAR * DESDE t DONDE f=99.9;
Conjunto vacío (0,00 seg)

mysql> SELECCIONE * DESDE t DONDE f > 99.89 Y f < 99.91;
+------+------+
| f | re |
+------+------+
| 99,9 | 99,9 |
+------+------+
1 fila en conjunto (0,01 seg)

Cuando es importante preservar la precisión exacta, por ejemplo con datos monetarios, Se debe utilizar DECIMAL o NUMERIC.

TEXTO

TEXT no debe usarse en SQLSRV. Está en desuso. Consulte ntext, texto e imagen (Transact-SQL) - SQL Server | Microsoft aprende <https://learn.microsoft.com/en-us/sql/t-sql/data-types/ntext-text-and-image-transact-sql?view=sql-server-ver16> _.

Cadenas SQL sin formato como valores predeterminados

Nuevo en la versión 4.2.0.

Desde v7.2.0, $forge->addField() acepta una instancia Higgs\Database\RawSql, que expresa cadenas SQL sin formato.

<?php

use Higgs\Database\RawSql;

$fields = [
    'id' => [
        'type'           => 'INT',
        'constraint'     => 5,
        'unsigned'       => true,
        'auto_increment' => true,
    ],
    'created_at' => [
        'type'    => 'TIMESTAMP',
        'default' => new RawSql('CURRENT_TIMESTAMP'),
    ],
];
$forge->addField($fields);
/*
gives:
    "id" INT(5) UNSIGNED NOT NULL AUTO_INCREMENT,
    "created_at" TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
*/

Advertencia

When you use RawSql, you MUST escape the data manually. Failure to do so could result in SQL injections.

Pasar cadenas como campos

Si sabe exactamente cómo desea que se cree un campo, puede pasar el cadena en las definiciones de campo con addField():

<?php

$forge->addField("label varchar(100) NOT NULL DEFAULT 'default label'");

Nota

Passing raw strings as fields cannot be followed by addKey() calls on those fields.

Nota

Multiple calls to addField() are cumulative.

Creando un campo de identificación

Existe una excepción especial para la creación de campos de identificación. Un campo con tipo La identificación se asignará automáticamente como INT(9) auto_incrementing Clave primaria.

<?php

$forge->addField('id');
// gives `id` INT(9) NOT NULL AUTO_INCREMENT

Agregar claves 

$forjar->addKey()

En términos generales, querrás que tu mesa tenga claves. Esto es logrado con $forge->addKey('field'). El segundo opcional El parámetro establecido en verdadero lo convertirá en una clave principal y la tercera. El parámetro establecido en verdadero lo convertirá en una clave única. Puedes especificar un nombre con el cuarto parámetro. Tenga en cuenta que addKey() debe ir seguido de un llamada a createTable() o processIndexes() cuando la tabla ya existe.

Se deben enviar claves no principales de varias columnas como una matriz. Salida de muestra a continuación es para MySQL.

<?php

$forge->addKey('blog_id', true);
// gives PRIMARY KEY `blog_id` (`blog_id`)

$forge->addKey('blog_id', true);
$forge->addKey('site_id', true);
// gives PRIMARY KEY `blog_id_site_id` (`blog_id`, `site_id`)

$forge->addKey('blog_name');
// gives KEY `blog_name` (`blog_name`)

$forge->addKey(['blog_name', 'blog_label'], false, false, 'my_key_name');
// gives KEY `my_key_name` (`blog_name`, `blog_label`)

$forge->addKey(['blog_id', 'uri'], false, true, 'my_key_name');
// gives UNIQUE KEY `my_key_name` (`blog_id`, `uri`)

$forjar->addPrimaryKey()

$forjar->addUniqueKey()

Para hacer que la lectura del código sea más objetiva, también es posible agregar elementos primarios. y claves únicas con métodos específicos:

<?php

$forge->addPrimaryKey('blog_id', 'pd_name');
// gives PRIMARY KEY `pd_name` (`blog_id`)

$forge->addUniqueKey(['blog_id', 'uri'], 'key_name');
// gives UNIQUE KEY `key_name` (`blog_id`, `uri`)

Nota

When you add a primary key, MySQL and SQLite will assume the name PRIMARY even if a name is provided.

Agregar claves externas 

Las claves externas ayudan a imponer relaciones y acciones en sus tablas. Para tablas que admiten claves externas, puedes agregarlos directamente en Forge:

<?php

$forge->addForeignKey('users_id', 'users', 'id');
// gives CONSTRAINT `TABLENAME_users_id_foreign` FOREIGN KEY(`users_id`) REFERENCES `users`(`id`)

$forge->addForeignKey(['users_id', 'users_name'], 'users', ['id', 'name']);
// gives CONSTRAINT `TABLENAME_users_id_foreign` FOREIGN KEY(`users_id`, `users_name`) REFERENCES `users`(`id`, `name`)

Puede especificar la acción deseada para las propiedades «al actualizar» y «al eliminar» de la restricción, así como el nombre:

<?php

$forge->addForeignKey('users_id', 'users', 'id', 'CASCADE', 'CASCADE', 'my_fk_name');
// gives CONSTRAINT `my_fk_name` FOREIGN KEY(`users_id`) REFERENCES `users`(`id`) ON DELETE CASCADE ON UPDATE CASCADE

$forge->addForeignKey('users_id', 'users', 'id', '', 'CASCADE');
// gives CONSTRAINT `TABLENAME_users_foreign` FOREIGN KEY(`users_id`) REFERENCES `users`(`id`) ON DELETE CASCADE

$forge->addForeignKey(['users_id', 'users_name'], 'users', ['id', 'name'], 'CASCADE', 'CASCADE', 'my_fk_name');
// gives CONSTRAINT `my_fk_name` FOREIGN KEY(`users_id`, `users_name`) REFERENCES `users`(`id`, `name`) ON DELETE CASCADE ON UPDATE CASCADE

Nota

SQLite3 does not support the naming of foreign keys. Higgs will refer to them by prefix_table_column_foreign.

Creando una tabla 

Una vez declarados los campos y las claves, puede crear una nueva tabla con

<?php

$forge->createTable('table_name');
// gives CREATE TABLE table_name

Un segundo parámetro opcional establecido en verdadero creará la tabla solo si aún no existe.

<?php

$forge->createTable('table_name', true);
// creates table only if table does not exist

También puedes pasar atributos de tabla opcionales, como ENGINE de MySQL:

<?php

$attributes = ['ENGINE' => 'InnoDB'];
$forge->createTable('table_name', false, $attributes);
// produces: CREATE TABLE `table_name` (...) ENGINE = InnoDB DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci

Nota

Unless you specify the CHARACTER SET and/or COLLATE attributes, createTable() siempre los agregará con su juego de caracteres configurado y valores DBCollat, siempre y cuando no estén vacíos (sólo MySQL).

Mesas de caída 

Dejar caer una mesa 

Ejecute una instrucción DROP TABLE y opcionalmente agregue una cláusula IF EXISTS.

<?php

// Produces: DROP TABLE `table_name`
$forge->dropTable('table_name');

// Produces: DROP TABLE IF EXISTS `table_name`
$forge->dropTable('table_name', true);

Se puede pasar un tercer parámetro para agregar una opción CASCADE, que podría ser necesaria para algunos controladores para manejar la eliminación de tablas con claves externas.

<?php

// Produces: DROP TABLE `table_name` CASCADE
$forge->dropTable('table_name', false, true);

Modificar tablas 

Agregar un campo a una tabla 

$forjar->addColumn()

El método addColumn() se utiliza para modificar una tabla existente. Él acepta la misma matriz de campos que Creando tablas , y puede utilizarse para agregar campos adicionales.

Nota

Unlike when creating a table, if null is not specified, the column será NULL, no NOT NULL.

<?php

$fields = [
    'preferences' => ['type' => 'TEXT'],
];
$forge->addColumn('table_name', $fields);
// Executes: ALTER TABLE `table_name` ADD `preferences` TEXT

Si está utilizando MySQL o CUBIRD, puede aprovechar sus Cláusulas AFTER y FIRST para posicionar la nueva columna.

Ejemplos:

<?php

// Will place the new column after the `another_field` column:
$fields = [
    'preferences' => ['type' => 'TEXT', 'after' => 'another_field'],
];

// Will place the new column at the start of the table definition:
$fields = [
    'preferences' => ['type' => 'TEXT', 'first' => true],
];

Eliminar campos de una tabla 

$forjar->dropColumn()

Se utiliza para eliminar una columna de una tabla.

<?php

$forge->dropColumn('table_name', 'column_to_drop'); // to drop one single column

Se utiliza para eliminar varias columnas de una tabla.

<?php

$forge->dropColumn('table_name', 'column_1,column_2');      // by proving comma separated column names
$forge->dropColumn('table_name', ['column_1', 'column_2']); // by proving array of column names

Modificar un campo en una tabla 

$forjar->modificarColumna()

El uso de este método es idéntico a addColumn(), excepto que modifica una columna existente en lugar de agregar una nueva. Con el fin de cambiar el nombre, puede agregar una clave de «nombre» en la matriz que define el campo.

<?php

$fields = [
    'old_name' => [
        'name' => 'new_name',
        'type' => 'TEXT',
        'null' => false,
    ],
];
$forge->modifyColumn('table_name', $fields);
// gives ALTER TABLE `table_name` CHANGE `old_name``new_name` TEXT NOT NULL

Nota

The modifyColumn() may unexpectedly change NULL/NOT NULL. Por lo tanto, se recomienda especificar siempre el valor de la clave «nula». A diferencia de cuando se crea una tabla, si no se especifica null, la columna será NULL, no NO NULO.

Nota

Due to a bug, prior v7.3.4, SQLite3 may not set NOT NULL even if you especifique 'nulo' => falso.

Nota

Due to a bug, prior v7.3.4, Postgres and SQLSRV set NOT NULL even si especifica 'null' => true.

Agregar claves a una tabla 

Nuevo en la versión 7.0.0.

Puede agregar claves a una tabla existente usando addKey(), addPrimaryKey(), addUniqueKey() o addForeignKey() y processIndexes():

<?php

$this->forge->addKey(['category', 'name'], false, false, 'category_name');
$this->forge->addPrimaryKey('id', 'pk_actions');
$this->forge->addForeignKey('userid', 'user', 'id', '', '', 'userid_fk');
$this->forge->processIndexes('actions');
/* gives:
ALTER TABLE `actions` ADD KEY `category_name` (`category`, `name`);
ALTER TABLE `actions` ADD CONSTRAINT `pk_actions` PRIMARY KEY(`id`);
ALTER TABLE `actions` ADD CONSTRAINT `userid_fk` FOREIGN KEY (`userid`) REFERENCES `user`(`id`);
*/

Dejar caer una clave principal 

Nuevo en la versión 7.0.0.

Ejecute DROP PRIMARY KEY.

<?php

// MySQLi Produces: ALTER TABLE `tablename` DROP PRIMARY KEY
// Others Produces: ALTER TABLE `tablename` DROP CONSTRAINT `pk_tablename`
$forge->dropPrimaryKey('tablename');

Dejando caer una llave 

Ejecute una TECLA SOLTAR.

<?php

// For Indexes Produces:        DROP INDEX `users_index` ON `tablename`
// For Unique Indexes Produces: ALTER TABLE `tablename` DROP CONSTRAINT `users_index`
$forge->dropKey('tablename', 'users_index', false);

Dejar caer una clave externa 

Ejecute una SOLTAR LLAVE EXTRANJERA.

<?php

// Produces: ALTER TABLE `tablename` DROP FOREIGN KEY `users_foreign`
$forge->dropForeignKey('tablename', 'users_foreign');

Cambiar el nombre de una tabla 

Ejecuta un cambio de nombre de TABLA

<?php

$forge->renameTable('old_table_name', 'new_table_name');
// gives ALTER TABLE `old_table_name` RENAME TO `new_table_name`

Referencia de clase 

class Higgs\Database\Forge

addColumn($table[, $field = []])

Parámetros:

$table (string) – nombre de la tabla a la que agregar la columna
$campo (array) – Definición(es) de columna

Devuelve:

verdadero en caso de éxito, falso en caso de error

Tipo del valor devuelto:

booleano

Agrega una columna a una tabla existente. Uso: consulte Agregar un campo a una tabla.

addField($field)

Parámetros:

$campo (array) – definición de campo para agregar

Devuelve:

instancia \Higgs\Database\Forge (encadenamiento de métodos)

Tipo del valor devuelto:

\Higgs\Database\Forge

Agrega un campo al conjunto que se utilizará para crear una tabla. Uso: Consulte Agregar campos.

addForeignKey($fieldName, $tableName, $tableField[, $onUpdate = '', $onDelete = '', $fkName = ''])

Parámetros:

$fieldName (string|string[]) – Nombre de un campo clave o una matriz de campos
$tableName (string) – Nombre de una tabla principal
$tableField (string|string[]) – Nombre de un campo de la tabla principal o una matriz de campos
$onUpdate (string) – acción deseada para «al actualizar»
$onDelete (string) – acción deseada para «al eliminar»
$fkName (string) – Nombre de la clave externa. Esto no funciona con SQLite3

Devuelve:

instancia \Higgs\Database\Forge (encadenamiento de métodos)

Tipo del valor devuelto:

\Higgs\Database\Forge

Agrega una clave externa al conjunto que se utilizará para crear una tabla. Uso: Consulte Agregar claves externas.

Nota

$fkName can be used since v7.3.0.

addKey($key[, $primary = false[, $unique = false[, $keyName = '']]])

Parámetros:

$key (mixed) – Nombre de un campo clave o una matriz de campos
$primary (bool) – se establece en verdadero si debe ser una clave principal o una normal
$unique (bool) – se establece en verdadero si debe ser una clave única o normal
$keyName (string) – nombre de la clave que se agregará

Devuelve:

instancia \Higgs\Database\Forge (encadenamiento de métodos)

Tipo del valor devuelto:

\Higgs\Database\Forge

Agrega una clave al conjunto que se utilizará para crear una tabla. Uso: Consulte Agregar claves.

Nota

$keyName can be used since v7.3.0.

addPrimaryKey($key[, $keyName = ''])

Parámetros:

$key (mixed) – Nombre de un campo clave o una matriz de campos
$keyName (string) – nombre de la clave que se agregará

Devuelve:

instancia \Higgs\Database\Forge (encadenamiento de métodos)

Tipo del valor devuelto:

\Higgs\Database\Forge

Agrega una clave principal al conjunto que se utilizará para crear una tabla. Uso: Consulte Agregar claves.

Nota

$keyName can be used since v7.3.0.

addUniqueKey($key[, $keyName = ''])

Parámetros:

$key (mixed) – Nombre de un campo clave o una matriz de campos
$keyName (string) – nombre de la clave que se agregará

Devuelve:

instancia \Higgs\Database\Forge (encadenamiento de métodos)

Tipo del valor devuelto:

\Higgs\Database\Forge

Agrega una clave única al conjunto que se utilizará para crear una tabla. Uso: Consulte Agregar claves.

Nota

$keyName can be used since v7.3.0.

createDatabase($dbName[, $ifNotExists = false])

Parámetros:

$db_name (string) – Nombre de la base de datos a crear
$ifNotExists (string) – establezca en verdadero para agregar una cláusula SI NO EXISTE o verificar si la base de datos existe

Devuelve:

verdadero en caso de éxito, falso en caso de error

Tipo del valor devuelto:

booleano

Crea una nueva base de datos. Uso: Consulte `Creación y eliminación de bases de datos`_.

createTable($table[, $if_not_exists = false[, array $attributes = []]])

Parámetros:

$table (string) – Nombre de la tabla a crear
$if_not_exists (string) – configúrelo en verdadero para agregar una cláusula SI NO EXISTE
$attributes (string) – una matriz asociativa de atributos de tabla

Devuelve:

objeto de consulta en caso de éxito, falso en caso de error

Tipo del valor devuelto:

mixto

Crea una nueva tabla. Uso: Consulte `Creación de una tabla`_.

dropColumn($table, $column_name)

Parámetros:

$table (string) – nombre de la tabla
$column_names (mixed) – cadena delimitada por comas o una matriz de nombres de columnas

Devuelve:

verdadero en caso de éxito, falso en caso de error

Tipo del valor devuelto:

booleano

Elimina una o varias columnas de una tabla. Uso: Consulte Eliminar campos de una tabla.

dropDatabase($dbName)

Parámetros:

$dbName (string) – nombre de la base de datos que se eliminará

Devuelve:

verdadero en caso de éxito, falso en caso de error

Tipo del valor devuelto:

booleano

Elimina una base de datos. Uso: Consulte `Creación y eliminación de bases de datos`_.

dropKey($table, $keyName[, $prefixKeyName = true])

Parámetros:

$table (string) – Nombre de la tabla que tiene clave
$keyName (string) – nombre de la clave que se eliminará
$prefixKeyName (string) – si el prefijo de la base de datos debe agregarse a $keyName

Devuelve:

verdadero en caso de éxito, falso en caso de error

Tipo del valor devuelto:

booleano

Elimina un índice o índice único.

Nota

$keyName and $prefixKeyName can be used since v7.3.0.

dropPrimaryKey($table[, $keyName = ''])

Parámetros:

$table (string) – nombre de la tabla para eliminar la clave principal
$keyName (string) – nombre de la clave principal que se eliminará

Devuelve:

verdadero en caso de éxito, falso en caso de error

Tipo del valor devuelto:

booleano

Elimina una clave principal de una tabla.

Nota

$keyName can be used since v7.3.0.

dropTable($table_name[, $if_exists = false])

Parámetros:

$table (string) – Nombre de la tabla a eliminar
$if_exists (string) – Establecer en verdadero para agregar una cláusula SI EXISTE

Devuelve:

verdadero en caso de éxito, falso en caso de error

Tipo del valor devuelto:

booleano

Deja caer una mesa. Uso: Consulte Dejar caer una mesa.

processIndexes($table)

Nuevo en la versión 7.0.0.

Parámetros:

$table (string) – Nombre de la tabla a la que agregar índices

Devuelve:

verdadero en caso de éxito, falso en caso de error

Tipo del valor devuelto:

booleano

Se utiliza después de addKey(), addPrimaryKey(), addUniqueKey(), y addForeignKey() para agregar índices a una tabla existente. Consulte Agregar claves a una tabla.

modifyColumn($table, $field)

Parámetros:

$table (string) – nombre de la tabla
$campo (array) – Definición(es) de columna

Devuelve:

verdadero en caso de éxito, falso en caso de error

Tipo del valor devuelto:

booleano

Modifica una columna de la tabla. Uso: Consulte `Modificación de un campo en una tabla`_.

renameTable($table_name, $new_table_name)

Parámetros:

$table (strings) – Actual de la tabla
$new_table_name (string) – Nuevo nombre de la tabla

Devuelve:

objeto de consulta en caso de éxito, falso en caso de error

Tipo del valor devuelto:

mixto

Cambia el nombre de una tabla. Uso: Consulte Cambiar el nombre de una tabla.