Como crear tablas en la base de datos al activar un plugin (dbDelta) en WordPress

Contents

Introducción

Crear tablas en la base de datos al activar un plugin en WordPress es una tarea habitual cuando se necesita persistir datos propios. WordPress incluye la función dbDelta (en el archivo wp-admin/includes/upgrade.php) diseñada para crear y actualizar tablas a partir de una sentencia SQL CREATE TABLE respetando el prefijo de tablas, el juego de caracteres y evitando sobrescribir datos. Este artículo explica en detalle cómo usar dbDelta correctamente, ejemplos prácticos, consideraciones para multisite, mantenimiento y errores comunes.

¿Por qué usar dbDelta?

  • Compara y actualiza: dbDelta no solo crea tablas, también intenta modificar la estructura cuando detecta diferencias entre la definición SQL y la tabla existente.
  • Mantiene datos: evita eliminar la tabla y perder datos hace alteraciones cuando es posible.
  • Sigue convenciones de WP: se integra con el prefijo de tablas (wpdb->prefix) y respeta charset/collate mediante wpdb->get_charset_collate().

Preparación: conceptos clave

  • wpdb: objeto global para interactuar con la base de datos. wpdb->prefix añade el prefijo configurado en WordPress.
  • wpdb->get_charset_collate(): devuelve la cláusula correcta de charset y collate para usar en la creación de tablas (ej. DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci).
  • require_once ABSPATH . wp-admin/includes/upgrade.php: obliga a incluir la definición de dbDelta antes de llamarla.
  • Formateo del SQL: dbDelta es sensible al formato. Use CREATE TABLE en mayúsculas y termine la instrucción con punto y coma (). Defina claves (PRIMARY KEY, UNIQUE KEY, KEY) explícitamente.

Ejemplo completo: crear una tabla al activar el plugin

A continuación un ejemplo funcional que muestra la creación de la tabla, guardado de la versión de esquema y actualización posterior.

prefix . my_plugin_items

    // Charset y collate adecuados
    charset_collate = wpdb->get_charset_collate()

    // SQL: nota la sintaxis y el punto y coma al final
    sql = CREATE TABLE table_name (
      id mediumint(9) NOT NULL AUTO_INCREMENT,
      created_at datetime NOT NULL DEFAULT 0000-00-00 00:00:00,
      user_id bigint(20) unsigned NOT NULL DEFAULT 0,
      title varchar(191) NOT NULL,
      content longtext NOT NULL,
      status tinyint(1) NOT NULL DEFAULT 1,
      PRIMARY KEY  (id),
      KEY user_id (user_id),
      KEY status (status)
    ) charset_collate

    // Cargar la función dbDelta
    require_once ABSPATH . wp-admin/includes/upgrade.php
    dbDelta( sql )

    // Guardar la versión del esquema en options para futuras actualizaciones
    add_option( my_plugin_db_version, MY_PLUGIN_DB_VERSION )
}
?>

Explicación del ejemplo

  • Usamos wpdb->prefix para que la tabla respete el prefijo del sitio.
  • varchar(191) en lugar de 255: recomendado para índices únicos o compatibilidad con utf8mb4 y largos límite de índice (InnoDB utf8mb4).
  • dbDelta requiere la declaración de claves (PRIMARY KEY, KEY) y que el SQL termine con punto y coma.
  • Guardamos la versión del esquema en options para poder detectar y aplicar actualizaciones posteriores al activar o cargar el plugin.

Actualizar la estructura de la tabla (migrations)

Para añadir columnas o índices en versiones futuras del plugin, actualice la constante de versión y ejecute dbDelta con la nueva definición SQL. Un patrón común es comprobar la opción guardada y ejecutar la rutina de actualización si hay desajuste.

prefix . my_plugin_items
    charset_collate = wpdb->get_charset_collate()

    // Nueva definición con columna añadida priority
    sql = CREATE TABLE table_name (
      id mediumint(9) NOT NULL AUTO_INCREMENT,
      created_at datetime NOT NULL DEFAULT 0000-00-00 00:00:00,
      user_id bigint(20) unsigned NOT NULL DEFAULT 0,
      title varchar(191) NOT NULL,
      content longtext NOT NULL,
      status tinyint(1) NOT NULL DEFAULT 1,
      priority smallint(5) NOT NULL DEFAULT 0,
      PRIMARY KEY  (id),
      KEY user_id (user_id),
      KEY status (status)
    ) charset_collate

    require_once ABSPATH . wp-admin/includes/upgrade.php
    dbDelta( sql )
}
?>

Notas sobre actualizaciones

  • dbDelta puede añadir columnas y añadir índices, pero no siempre elimina columnas antiguas ni cambia ciertas propiedades complejas. En algunos casos puede ser necesario crear una tabla temporal, migrar datos y renombrar.
  • Siempre pruebe el proceso de actualización en un entorno de desarrollo antes de desplegar en producción.

Uninstall vs Deactivate: eliminar tablas

Decidir si eliminar tablas al desinstalar es una decisión de diseño. Las buenas prácticas suelen ser:

  • Al desactivar: no borrar datos (permitir reactivar sin pérdida).
  • Al desinstalar (borrado final): ofrecer la opción de eliminar datos o eliminar automáticamente si así lo desea el desarrollador. Use register_uninstall_hook o un archivo uninstall.php.
prefix . my_plugin_items
wpdb->query( DROP TABLE IF EXISTS table_name )

// Borrar opciones
delete_option( my_plugin_db_version )
delete_option( my_plugin_settings )
?>

Consideraciones para Multisite (red)

En instalaciones multisite, si el plugin se activa a nivel de red, debe crear la tabla en cada blog de la red (a menos que sea tabla global y se use wpdb->base_prefix). Ejemplo para crear en todos los blogs:

 ids ) )
        foreach ( blog_ids as blog_id ) {
            switch_to_blog( blog_id )
            my_plugin_activate() // función que crea la tabla para el blog actual
            restore_current_blog()
        }
    } else {
        my_plugin_activate()
    }
}
?>

Errores comunes y cómo solucionarlos

  1. Tabla no creada: ¿Incluyó require_once ABSPATH . wp-admin/includes/upgrade.php antes de dbDelta? ¿Terminó la SQL con punto y coma?
  2. dbDelta no detecta cambios: dbDelta espera un formato concreto. Asegúrese de que los tipos y claves estén en la sentencia CREATE TABLE y no use ALTER TABLE para dbDelta. A veces necesita reproducir exactamente el formato que dbDelta espera (espacios, comas, mayúsculas).
  3. Índices en utf8mb4: Si define UNIQUE o índices en varchar largos, use varchar(191) para evitar errores de límite de índice en MySQL/InnoDB con utf8mb4.
  4. Primary key ausente: dbDelta funciona mejor si hay una PRIMARY KEY definida añada una columna id AUTO_INCREMENT como práctica estándar.
  5. Problemas con comillas/backticks: Use una construcción simple: CREATE TABLE table_name (…). Evite usos extraños de comillas que cambien el patrón que dbDelta compara.

Buenas prácticas

  • Versione el esquema y guárdelo en options (p. ej. my_plugin_db_version). Compare y aplique migraciones cuidadosamente.
  • Use wpdb->prefix para tablas por sitio o wpdb->base_prefix para tablas globales en multisite.
  • Pruebe las migraciones en entornos idénticos a producción (mismo motor de BD y collation).
  • Documente cambios en el esquema y proporcione scripts de migración claros.
  • Prefiera InnoDB y utf8mb4 cuando sea posible. Utilice wpdb->get_charset_collate() para consistencia.
  • No confíe únicamente en dbDelta para cambios complejos: a veces es necesario SQL de ALTER directo o una migración manual.

Recursos útiles

Checklist rápido antes de activar en producción

  • ¿Incluye require_once ABSPATH . wp-admin/includes/upgrade.php?
  • ¿Usa wpdb->get_charset_collate() en la sentencia CREATE TABLE?
  • ¿La SQL termina con punto y coma?
  • ¿Tiene PRIMARY KEY y los KEY/UNIQUE necesarios declarados?
  • ¿Guardó la versión del esquema y agregó lógica de actualización?
  • ¿Probó el proceso en una copia del entorno de producción?

Con estos pasos y cuidados podrá crear y mantener tablas en la base de datos de forma segura usando dbDelta en sus plugins de WordPress. El código de ejemplo proporciona un punto de partida sólido que puede adaptar a sus necesidades reales.


Acepto donaciones de BAT's mediante el navegador Brave 🙂

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *