Cómo importar un CSV en Supabase

Un script para una sola ejecución es una alternativa intermedia razonable. Define expresamente su formato de entrada, ensáyalo y conserva pruebas suficientes para determinar qué ocurrió. Para una importación que un ingeniero realizará una sola vez, suele bastar con un script revisado.

Para cargas recurrentes de clientes, usa la lista de comprobación de la arquitectura de un importador de CSV. El resto de esta página supone que un ingeniero está preparando una importación concreta.

Empieza con una copia de la exportación. Conserva el original para poder explicar cualquier corrección. Anota el delimitador, la codificación, la fila de encabezados y el significado de los valores en blanco. Si un campo es un identificador externo, trátalo como texto aunque todos sus valores visibles contengan dígitos.

Para una tabla de contactos, el origen aprobado podría contener únicamente estos dos campos:

email,display_name
first@example.test,First Contact
second@example.test,"Second, Contact"

La coma entre comillas forma parte del nombre del segundo contacto. Dividir cada línea por las comas crearía un tercer campo. Un campo entre comillas también puede contener un salto de línea, por lo que contar las líneas físicas no permite obtener un recuento fiable de filas.

Revisa los encabezados duplicados y los mapeos antes de importar. Si dos columnas de origen se llaman «Email», hay que elegir expresamente cuál usar. Excluye de forma deliberada las columnas adicionales. No deduzcas que se debe permitir escribir los campos id, tenant_id o created_at de un archivo solo porque sus nombres coincidan.

Exporta la hoja de cálculo deseada como CSV UTF-8 y usa después el mismo método de importación. En Google Sheets, usa Archivo → Descargar → Valores separados por comas para la hoja actual. En Excel, guarda una copia en formato CSV UTF-8. Un libro puede contener varias hojas; un CSV representa una sola tabla plana. Cambiar la extensión de un archivo XLSX a CSV no lo convierte.

Inspecciona el texto exportado antes de cargarlo. Comprueba un identificador con ceros iniciales, una fecha, un decimal y las celdas cuyo valor proceda de una fórmula. Si la hoja ya convirtió 00042 en 42, exportarla como UTF-8 no recuperará los ceros perdidos. Vuelve al origen u obtén una corrección aprobada.

Aclara fechas como 04/05/2026 con el responsable de los datos. No supongas que significa el 5 de abril o el 4 de mayo. Anota la zona horaria prevista para las marcas de tiempo; una fecha de aniversario sin hora no debería sufrir por accidente una conversión de zona horaria. La sincronización continua con una hoja activa es un requisito distinto de esta exportación puntual.

Antes de la primera escritura, prepara una lista breve que indique quién determina el valor de cada campo. Por ejemplo: el correo electrónico y el nombre mostrado proceden del origen aprobado; el tenant, del contexto autorizado de la aplicación; la identidad, de PostgreSQL; y la marca de tiempo de auditoría sigue la regla elegida por la aplicación.

Un valor predeterminado ordinario no prohíbe aportar valores de origen. Una expresión generada es distinta. La ausencia de una columna, un NULL explícito y una cadena vacía también pueden producir resultados diferentes. La guía de valores predeterminados y generados muestra esas diferencias.

Comprueba qué espera tu tabla de destino con PG Import Check si dispones del SQL de migración o del DDL. La herramienta informa de las declaraciones estructurales compatibles de forma local en tu navegador. No inspecciona filas reales, valida el CSV, determina la RLS efectiva ni aprueba una importación en producción. Contrasta por tu cuenta los datos que le facilitas con el esquema realmente desplegado.

Este pequeño ensayo usa una tabla temporal en una base de datos desechable de PostgreSQL 17. Prueba el funcionamiento del CSV sin tocar una tabla de la aplicación. En una sesión conectada de psql, crea la tabla:

CREATE TEMP TABLE import_contacts_demo (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  email text NOT NULL UNIQUE,
  display_name text,
  created_at timestamptz NOT NULL DEFAULT now()
);

Guarda el CSV anterior como contacts.csv en el directorio de trabajo del cliente y ejecuta lo siguiente en una sola línea de psql:

\copy import_contacts_demo (email, display_name) FROM 'contacts.csv' WITH (FORMAT csv, HEADER MATCH, ENCODING 'UTF8')

SELECT id, email, display_name, created_at
FROM import_contacts_demo
ORDER BY id;

El resultado esperado son dos filas, IDs generados distintos, la coma conservada en el segundo nombre y marcas de tiempo de la base de datos. La lista explícita de columnas deja a la base de datos la generación del ID y de la marca de tiempo. En PostgreSQL 17, HEADER MATCH comprueba los nombres y su orden. HEADER true, por sí solo, omite el encabezado; no asigna los valores por nombre.

El comando de copia con barra inversa de psql lee un archivo de la máquina cliente y lo transmite a través de la conexión a la base de datos. COPY FROM '/path', ejecutado en el servidor, lee el sistema de archivos del servidor de base de datos. Supabase no puede leer de ese modo una ruta de tu portátil.

Para una conexión real a Supabase, obtén el endpoint correcto y la configuración SSL en las instrucciones de conexión del proyecto. No incluyas contraseñas en comandos guardados, Git ni capturas de pantalla. Deja que el propietario de la base de datos elija el rol de ejecución y el modo de conexión; este ejemplo con una tabla temporal no establece los permisos de producción.

Un archivo de un cliente puede contener una etiqueta como «Cuenta activa» donde tu enum espera active. Una representación en un área de preparación permite conservar el valor original junto al propuesto y el motivo del cambio. El responsable de negocio aprueba esa traducción y el importador la aplica de forma coherente.

El área de preparación puede ser una tabla temporal, una base de datos desechable independiente o una zona persistente de acceso restringido para un trabajo más largo. Elige según la sensibilidad de los datos y las necesidades de recuperación. No debería ser una tabla desprotegida y expuesta mediante la API de tu aplicación. Prueba en un entorno aislado las restricciones y el comportamiento de escritura relevantes para producción, y anota lo que el ensayo no puede reproducir.

El comportamiento predeterminado de COPY en PostgreSQL se detiene ante un error. Una transacción revertida no deja confirmadas las filas que insertó, pero sí permanecen los lotes anteriores confirmados por separado. Un script con diez solicitudes correctas y una undécima fallida tiene un resultado parcial. No reinicies la importación de todo el archivo basándote solo en el último error.

Incluye las restricciones y los disparadores en la revisión. Una clave foránea necesita una referencia de destino, no solo un número del tipo correcto. Un disparador puede rechazar o modificar una fila y puede iniciar otros procesos. No desactives las comprobaciones de integridad como solución habitual para un archivo rechazado. Consulta la guía de importación con claves foráneas cuando los IDs de origen y de destino sean distintos.

Para archivos grandes, mide el tiempo de ejecución, el uso de disco, el crecimiento del WAL, los bloqueos y la latencia de la aplicación en un ensayo representativo. Elige lotes de tamaño acotado o una ventana de mantenimiento a partir de esas pruebas. El límite de tamaño de archivo del panel no garantiza el rendimiento de ningún otro método.

Cuenta los registros de origen analizados, anota las exclusiones aprobadas y compara el conjunto aceptado resultante con el destino. Si se aceptaron 200 contactos, tener 200 filas insertadas es una prueba útil. Aun así, podrían ser los 200 contactos equivocados o los contactos correctos asignados al tenant incorrecto.

Compara claves de negocio estables, inspecciona los campos transformados importantes y prueba la vía de lectura habitual de la aplicación. Dentro del tenant autorizado, identifica las filas de esta importación mediante una atribución fiable a la importación o un mapeo revisado de IDs de origen a destino. Un filtro de tenant por sí solo incluye las filas existentes. Si no se dispone de esa atribución, compara con una expectativa explícita del estado completo tras la importación e indica la limitación.

La guía de verificación posterior a la importación ofrece ejemplos ejecutables para detectar claves ausentes y valores que no coinciden. Conserva juntos el origen aprobado, el mapeo y el resultado bajo una política de conservación acordada. Esos registros facilitan mucho resolver un intento fallido o una corrección de un cliente.