Deja de escribir instrucciones INSERT a mano: usa un convertidor JSON a SQL

Exportaste 200 filas de datos de usuarios desde un servicio de terceros. El formato es JSON. Tu base de datos necesita instrucciones SQL INSERT. Y por alguna razón, estás pensando en escribirlas a mano.

El proceso mental va más o menos así: abrir el archivo JSON, observar la estructura, escribir la instrucción CREATE TABLE, luego comenzar con las instrucciones INSERT. La primera toma dos minutos. La segunda toma un minuto. Para la décima tienes una rutina. Para la cincuentésima has introducido un error tipográfico que no notarás hasta que el import falle con un error de restricción.

Hay una mejor manera. El convertidor JSON a SQL toma tu arreglo JSON, infiere el esquema y produce SQL listo para ejecutar — instrucciones INSERT en bloque, con los nombres de columna correctos y valores entre comillas. Esta guía explica qué hace, cómo usarlo de manera efectiva y dónde todavía necesitarás hacer limpieza manual.

Qué hace la herramienta realmente

En resumen: pegas un arreglo JSON de objetos, seleccionas un dialecto SQL, y la herramienta genera dos cosas — una instrucción CREATE TABLE basada en el esquema inferido, y una serie de instrucciones INSERT para tus datos.

La inferencia de tipos es la parte interesante. La herramienta mira los valores en tu JSON y hace suposiciones razonables sobre los tipos SQL. Las cadenas se convierten en VARCHAR o TEXT. Los números se convierten en INT o FLOAT. Los booleanos se convierten en BOOLEAN o TINYINT(1) dependiendo de tu dialecto. Los valores null toman VARCHAR nullable por defecto.

También maneja automáticamente las diferencias de formato entre dialectos SQL — nombres de columna con backticks para MySQL, identificadores con comillas dobles para PostgreSQL, NVARCHAR para columnas de texto de SQL Server.

Un ejemplo realista

Digamos que tienes un export JSON de una app SaaS. El export de la tabla de usuarios se ve así:

[
  {
    "id": 1,
    "name": "Alice Chen",
    "email": "alice@example.com",
    "age": 31,
    "active": true,
    "created_at": "2025-01-15T09:23:00Z"
  },
  {
    "id": 2,
    "name": "Ben Kowalski",
    "email": "ben@example.com",
    "age": 28,
    "active": false,
    "created_at": "2025-02-03T14:55:00Z"
  },
  {
    "id": 3,
    "name": "Sara Okonkwo",
    "email": "sara@example.com",
    "age": 34,
    "active": true,
    "created_at": "2025-03-11T08:00:00Z"
  }
]

Pega esto, selecciona MySQL, y la salida se ve así:

CREATE TABLE `users` (
  `id` INT,
  `name` VARCHAR(255),
  `email` VARCHAR(255),
  `age` INT,
  `active` BOOLEAN,
  `created_at` VARCHAR(255)
);

INSERT INTO `users` (`id`, `name`, `email`, `age`, `active`, `created_at`) VALUES
(1, 'Alice Chen', 'alice@example.com', 31, TRUE, '2025-01-15T09:23:00Z'),
(2, 'Ben Kowalski', 'ben@example.com', 28, FALSE, '2025-02-03T14:55:00Z'),
(3, 'Sara Okonkwo', 'sara@example.com', 34, TRUE, '2025-03-11T08:00:00Z');

Para 200 filas obtendrías la misma estructura pero con un lote de 200 valores. Eso es la producción de quizás treinta segundos de pegar y hacer clic, versus quince minutos de escritura propensa a errores.

Nota algunas cosas en esta salida. El campo created_at está tipado como VARCHAR(255) en lugar de DATETIME — llegaremos a por qué eso importa. El nombre de la tabla toma por defecto users; la herramienta puede permitirte especificarlo. El CREATE TABLE no incluye restricciones PRIMARY KEY o NOT NULL — eso es tu trabajo.

Diferencias de dialecto que vale la pena conocer

El selector de "dialecto SQL" importa más de lo que podría parecer. Las diferencias de sintaxis entre bases de datos son pequeñas pero causarán errores si eliges el incorrecto.

MySQL usa backticks para citar identificadores: `column_name`. Esto es importante si tu nombre de columna colisiona con una palabra reservada de MySQL (como order, key, index o values). MySQL también usa TINYINT(1) para booleanos en esquemas más antiguos, aunque BOOLEAN funciona en MySQL 5.7+.

PostgreSQL usa comillas dobles para identificadores: "column_name". Tiene tipos nativos BOOLEAN y TIMESTAMP WITH TIME ZONE. También tiene SERIAL y BIGSERIAL para claves primarias auto-incrementales, que es diferente de AUTO_INCREMENT de MySQL.

SQLite es permisivo sobre tipos — SQLite usa "afinidad de tipos" en lugar de tipos estrictos, por lo que una columna declarada como TEXT puede almacenar enteros y viceversa. Para la salida SQLite a menudo verás nombres de tipo más simples como TEXT e INTEGER.

SQL Server usa NVARCHAR en lugar de VARCHAR para cadenas de texto Unicode, y corchetes para citar identificadores: [column_name]. SQL Server también usa BIT para valores booleanos en lugar de BOOLEAN o TINYINT.

Si vas a importar en una base de datos específica, selecciona ese dialecto. Si vas a ejecutar el SQL manualmente y adaptarlo, cualquier dialecto te da un punto de partida utilizable — solo ten en cuenta qué necesitarás cambiar.

Inferencia de tipos: qué funciona bien y dónde falla

La herramienta es bastante buena en los casos comunes:

• 123 en JSON se convierte en INT en SQL
• 123.45 se convierte en FLOAT o DECIMAL
• "hello" se convierte en VARCHAR(255) o TEXT
• true / false se convierte en BOOLEAN o TINYINT(1)
• null se convierte en una columna nullable, generalmente tipada como VARCHAR

Donde falla es en cualquier lugar donde JSON usa cadenas para representar datos que no son cadenas.

Los números de teléfono son una trampa clásica. Si tu JSON tiene "phone": "12345", eso es una cadena en JSON, y obtendrás VARCHAR(255) — lo cual es correcto, ya que los números de teléfono deben almacenarse como cadenas (ceros iniciales, códigos de país con +, números formateados). Pero si alguien almacenó números de teléfono como enteros simples en el sistema fuente, podrías ver "phone": 12345 y obtener INT. Entonces tu import eliminaría silenciosamente los ceros iniciales y el formato.

Los campos de fecha y hora casi siempre saldrán como VARCHAR porque JSON no tiene tipo de fecha nativo. "2025-01-15T09:23:00Z" es solo una cadena para JSON. Si necesitas una columna DATETIME o TIMESTAMP adecuada, cambia el tipo de columna en la instrucción CREATE TABLE después de generarla. Los datos en sí se importarán correctamente ya que SQL analizará la cadena ISO 8601 al insertar en una columna TIMESTAMP.

Los IDs que parecen números son más difíciles. Un campo id con valor 1042 será tipado como INT. Eso puede estar bien — o tu sistema puede usar UUIDs o IDs alfanuméricos que simplemente son todos numéricos en las primeras filas de tu muestra. Si la fila 201 tiene id: "a1b2c3", tu import fallará.

Los campos de texto grandes serán tipados como VARCHAR(255). Si un campo contiene contenido más largo — cuerpos de artículos, descripciones, datos serializados — necesitarás cambiar el tipo a TEXT o LONGTEXT en MySQL, o TEXT en PostgreSQL (sin límite de longitud).

La regla general: siempre revisa la instrucción CREATE TABLE generada antes de ejecutarla. Las instrucciones INSERT generalmente están bien, pero la inferencia del esquema es donde se necesita el juicio humano.

Inserciones en lote: por qué importan

Para conjuntos de datos pequeños — diez o veinte filas — no importa mucho si insertas una fila a la vez o en lotes. Para conjuntos de datos más grandes, la diferencia es significativa.

Un INSERT de fila única se ve así:

INSERT INTO `users` (`id`, `name`, `email`) VALUES (1, 'Alice', 'alice@example.com');
INSERT INTO `users` (`id`, `name`, `email`) VALUES (2, 'Ben', 'ben@example.com');
-- ... 198 instrucciones más

Un INSERT en lote se ve así:

INSERT INTO `users` (`id`, `name`, `email`) VALUES
(1, 'Alice', 'alice@example.com'),
(2, 'Ben', 'ben@example.com'),
(3, 'Sara', 'sara@example.com'),
-- ... hasta 100 filas
;

INSERT INTO `users` (`id`, `name`, `email`) VALUES
(101, 'David', 'david@example.com'),
-- ... siguiente lote
;

La versión en lote es más rápida por dos razones. Primero, hay un viaje de red por lote en lugar de uno por fila. Segundo, la base de datos puede optimizar mejor una escritura grande única que muchas pequeñas — la sobrecarga de transacción, las actualizaciones de índice y el registro de escritura anticipada ocurren una vez por instrucción en lugar de una vez por fila.

La razón por la que los convertidores típicamente limitan los lotes a 100-500 filas en lugar de poner todo en una instrucción es la memoria y la confiabilidad. Una instrucción INSERT única de 10,000 filas puede alcanzar límites de memoria, ser lenta de analizar, y si falla a mitad del camino, no tienes retroalimentación útil sobre qué filas fueron el problema. Los lotes más pequeños son más prácticos.

Qué no hará la herramienta

Ser claro sobre las limitaciones te ahorra una sesión de depuración más adelante.

Sin claves foráneas. El convertidor no sabe nada sobre las relaciones entre tablas. Si tu JSON tiene un campo user_id que referencia otra tabla, obtienes una columna INT simple — sin restricción FOREIGN KEY, sin cláusula REFERENCES. Necesitarás agregar esas manualmente.

Sin índices. El CREATE TABLE generado no tiene definiciones de índice. Si vas a importar un conjunto de datos grande y luego consultarlo, necesitarás agregar definiciones INDEX o UNIQUE INDEX en columnas por las que filtrarás o unirás. Este es siempre un paso post-importación.

Sin marcado de clave primaria. La herramienta puede crear una columna id INT pero no le agregará PRIMARY KEY o AUTO_INCREMENT. Si quieres que id sea una clave primaria auto-incremental adecuada, agrega PRIMARY KEY AUTO_INCREMENT a esa definición de columna en MySQL, o cambia a SERIAL en PostgreSQL.

Sin tipos complejos o anidados. Si el valor de un campo es un objeto o arreglo, la herramienta no puede aplanarlo en un esquema relacional. Típicamente lo serializará como cadena JSON o omitirá el campo. Necesitas decidir: almacenarlo como columna JSON (MySQL 5.7+ y PostgreSQL soportan columnas JSON nativas), aplanarlo en columnas separadas, o normalizarlo en una tabla separada.

Sin lógica upsert. Las instrucciones generadas son INSERT simples sin manejo de conflictos. Si las ejecutas contra una tabla que ya tiene datos con claves primarias superpuestas, obtendrás errores de violación de restricción. Para importaciones idempotentes, necesitarías INSERT IGNORE en MySQL, ON CONFLICT DO NOTHING en PostgreSQL, o MERGE en SQL Server — ninguno de los cuales la herramienta agrega automáticamente.

Sin transacciones. La salida no está envuelta en BEGIN TRANSACTION / COMMIT. Para importaciones grandes, envolver todo en una transacción es una buena práctica — si algo falla a mitad del camino, puedes hacer rollback limpiamente. Agrégalo tú mismo alrededor de las instrucciones generadas.

Cuándo usar esta herramienta vs otras opciones

El convertidor JSON a SQL es la herramienta correcta para un conjunto específico de situaciones. No es la herramienta correcta para todo.

Úsalo cuando:

• Tienes una importación de datos única desde una fuente externa
• Estás migrando datos entre bases de datos y necesitas un dump SQL rápido
• Estás configurando una base de datos de demo o prueba con datos de aspecto realista
• Estás trabajando directamente con SQL y no tienes una pila de aplicación corriendo
• Necesitas compartir datos con alguien que solo tiene acceso SQL

Recurre a tu ORM o herramienta ETL cuando:

• Necesitas datos de seed repetibles y versionados — herramientas como db seed de Prisma, fixtures de Django o archivos seed de Rails se integran con tu flujo de migración y pueden volver a ejecutarse de forma segura
• La importación es compleja e involucra transformar datos, no solo insertarlos
• Necesitas manejar relaciones y restricciones de clave foránea programáticamente
• Estás haciendo esto regularmente en un horario — escribe un script ETL adecuado o usa una herramienta como Apache NiFi, dbt o incluso un script Python simple con pandas y sqlalchemy

El convertidor JSON a SQL es esencialmente un atajo para el escenario "solo necesito meter estos datos en una tabla". Cuando el escenario es más complejo que eso, necesitas una herramienta más compleja.

Un flujo de trabajo práctico

Aquí está la secuencia que funciona bien:

1. Formatea tu JSON primero. Si tu export está minificado, pégalo primero en el formateador JSON. Esto te permite revisar la estructura y detectar cualquier problema antes de convertir.

2. Verifica la estructura del arreglo. El convertidor espera un arreglo JSON de objetos donde cada objeto tiene las mismas claves de nivel superior. Si tu export está envuelto en un objeto raíz ({"data": [...]}) en lugar de ser un arreglo simple, extrae el arreglo primero.

3. Selecciona tu dialecto y pega el JSON. Copia el SQL generado.

4. Revisa el CREATE TABLE. Antes de ejecutar cualquier cosa, lee los tipos de columna y corrige cualquiera que parezca incorrecto — especialmente los campos de fecha, los campos de texto grande y cualquier campo numérico que debería ser una cadena.

5. Agrega las restricciones que necesitas. Marca la clave primaria, agrega NOT NULL donde sea apropiado, agrega UNIQUE en columnas de email, y agrega cualquier restricción FOREIGN KEY.

6. Ejecuta primero el CREATE TABLE, luego los INSERTs. Si la tabla ya existe y estás reimportando, decide si haces primero DROP TABLE IF EXISTS o usas alguna estrategia de resolución de conflictos.

7. Verifica el conteo de filas. Después de la importación, ejecuta SELECT COUNT(*) FROM your_table; y compara con el número de filas en tu JSON. Si coinciden, has terminado.

Formateando el SQL de salida

El SQL generado generalmente es legible pero no siempre está formateado según tus estándares. Si quieres las instrucciones INSERT formateadas de manera consistente — columnas alineadas, mayúsculas consistentes para palabras clave — pasa la salida por el formateador SQL. No cambiará la semántica pero hace el SQL más fácil de revisar y comparar diferencias.

Resumen

Escribir instrucciones INSERT a mano para grandes conjuntos de datos JSON es una de esas tareas donde la automatización tiene más sentido. El convertidor JSON a SQL maneja la conversión mecánica: lee tu arreglo, infiere tipos, genera un esquema y produce instrucciones INSERT en lote en tu dialecto objetivo.

Las partes que aún requieren tu atención son la revisión del esquema (tipos, restricciones, índices), el manejo de datos anidados y hacer la lógica INSERT idempotente si necesitas volver a ejecutarla. La herramienta hace el 90% que es puramente mecánico. El 10% restante es el juicio de diseño de base de datos que ninguna automatización puede reemplazar.

Si trabajas regularmente con datos JSON, otros dos herramientas valen la pena marcar junto a esta: el formateador JSON para revisar y limpiar tu entrada, y el formateador SQL para ordenar la salida generada antes de confirmarla en un archivo de migración.