Ir al contenido

S3 y httpfs ​

DuckLocal puede leer objetos de S3 y de almacenamiento compatible con S3 mediante la extensión httpfs de DuckDB. Configúralo desde el botón S3 de la barra de título.

Configura las credenciales ​

El diálogo tiene cuatro campos:

CampoPredeterminadoNotas
Endpoints3.amazonaws.comSe respeta http://; en caso contrario se usa HTTPS
Regiónus-east-1Se envía tal como se escribe
Access Key ID—Obligatorio
Secret Access Key—Obligatorio, enmascarado, con un botón para mostrarlo

Al confirmar se ejecuta el equivalente a:

sql
INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE SECRET ducklocal_s3 (
  TYPE s3, PROVIDER config,
  KEY_ID '…', SECRET '…',
  REGION '…', ENDPOINT '…'
);

Las credenciales duran solo la sesión. No se escriben en disco y se borran cuando abres o cambias de base de datos, así que tienes que volver a configurarlas después. No hay otra forma de borrarlas que volver a configurar.

Explora ​

Una vez configurado, aparece una raíz S3 en la barra lateral. Su contenido se carga solo al desplegarla: la raíz lista los buckets, y cada bucket o prefijo lista sus objetos. Los buckets y los prefijos están ordenados, y los objetos muestran un tamaño legible. Usa el botón de actualizar para recargar un nivel o reintentar tras un error.

El listado se limita a 1000 entradas por nivel, incluso cuando la respuesta dice que hay más disponibles. No hay paginación más profunda, ni cuadro de filtro por prefijo, ni búsqueda: un bucket con más de mil objetos en un nivel parecerá completo cuando no lo está.

Consulta objetos ​

Al hacer clic en un objeto cuya clave tiene una extensión de archivo de datos, se rellena el editor activo con:

sql
SELECT *
FROM 's3://bucket/key'
LIMIT 100;

Eso es una consulta normal: la lectura pasa por httpfs, así que se aplica el comportamiento de read_parquet / read_csv_auto de DuckDB, incluido el pushdown: los filtros y la selección de columnas se empujan a la lectura del archivo. La consulta sustituye lo que tuviera la pestaña activa.

Solo se pueden pulsar las claves reconocidas como archivos de datos. Las extensiones reconocidas son las mismas que para los archivos locales; consulta Fuentes de datos.

Limitaciones ​

  • La exploración es de solo lectura. El explorador no tiene acciones de subir, descargar a un archivo, borrar, copiar ni crear buckets. Las consultas sí descargan datos remotos.
  • Sin tokens de sesión. Nunca se envía la cabecera X-Amz-Security-Token, así que las credenciales temporales de STS no funcionarán: usa claves de larga duración, o un endpoint que acepte solo clave y secreto.
  • El estilo de endpoint es casi siempre automático. Las URL de S3 pueden direccionar un bucket de dos formas: direccionamiento virtual-hosted o estilo de ruta. Se usa el direccionamiento virtual-hosted cuando el host contiene amazonaws.com, y el estilo de ruta en caso contrario. Para pasarelas autoalojadas esto suele ser lo que quieres; para una que necesite el otro estilo, no hay forma de forzarlo.
  • Una región equivocada se reintenta una vez, usando la región que DuckDB devuelve. Si eso también falla, el error se muestra tal cual.
  • Se necesita red: INSTALL httpfs descarga la extensión en el primer uso. La exploración envía solicitudes HTTP o HTTPS al endpoint configurado (http:// selecciona HTTP; en caso contrario se usa HTTPS). Estas solicitudes envían metadatos como nombres de bucket y prefijos de clave, además de información de autenticación en cabeceras firmadas; la exploración no sube archivos de base de datos locales ni resultados de consultas. Las consultas sobre objetos remotos descargan datos a tu máquina mediante httpfs.

Solución de problemas ​

SíntomaCausa probable
La exploración falla justo después de configurarRegión o endpoint incorrectos; revisa el mensaje que aparece en la barra lateral
Errores en un endpoint autoalojadoEstilo de direccionamiento incorrecto, o un endpoint que exige un token de sesión
Error de instalación de httpfsSin red, o un proxy que bloquea la descarga de la extensión
Las credenciales parecen olvidarseSe abrió o se cambió de base de datos, lo que las borra por diseño

Cuando DuckLocal se empaqueta como una app firmada, cargar la extensión httpfs necesita el entitlement com.apple.security.cs.disable-library-validation; el script de empaquetado incluido ya lo lleva.

Publicado bajo la licencia Apache-2.0.