fn_registry/python/functions/infra/duckdb_table_schema.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
duckdb_table_schema	function	py	infra	1.0.0	impure	def duckdb_table_schema(db_path: str, table: str) -> dict	Devuelve el schema (columnas y tipos) de una tabla DuckDB abierta en modo solo lectura (duckdb.connect(db_path, read_only=True)), de modo que nunca crea ni modifica la base. La conexion se cierra siempre en try/finally. Ejecuta DESCRIBE <table> con el identificador de tabla validado contra ^[A-Za-z_][A-Za-z0-9_]*$ y citado (DESCRIBE no admite parametros posicionales). Devuelve un dict sin lanzar (estilo del grupo duckdb): {status:'ok', table, columns:[{name,type}]} en exito y {status:'error', error} en fallo. type es el tipo DuckDB tal cual (BIGINT, DOUBLE, VARCHAR...). Es la introspeccion de columnas del grupo duckdb, util para mapear tipos a otro motor (p.ej. PostgreSQL). Depende del paquete duckdb (1.5.2 en python/.venv).	duckdb sql introspection schema readonly				false	error_py_core	re duckdb	name desc db_path ruta al archivo DuckDB. Debe existir: el modo read_only NO crea la base. Un path inexistente devuelve {status:'error'}. name desc table nombre de la tabla a inspeccionar. Se valida contra ^[A-Za-z_][A-Za-z0-9_]*$ antes de interpolarlo en el DESCRIBE (que no admite parametro posicional para el identificador). Un identificador invalido devuelve {status:'error'} sin tocar la base.	dict. En exito: {status:'ok', table:str, columns:[{name:str, type:str},...]} donde type es el tipo DuckDB tal cual lo reporta el motor. En error (sin lanzar): {status:'error', error:str}.	true	test_schema_devuelve_columnas_y_tipos test_identificador_invalido_devuelve_status_error test_tabla_inexistente_devuelve_status_error test_db_inexistente_devuelve_status_error	python/functions/infra/duckdb_table_schema_test.py	python/functions/infra/duckdb_table_schema.py

Ejemplo

import sys
sys.path.insert(0, "python/functions")
import duckdb
from infra.duckdb_table_schema import duckdb_table_schema

db = "/tmp/almacen.duckdb"
con = duckdb.connect(db)
con.execute("CREATE TABLE ventas (id BIGINT, region VARCHAR, total DOUBLE, ok BOOLEAN)")
con.close()

res = duckdb_table_schema(db, "ventas")
print(res["status"])    # ok
print(res["table"])     # ventas
print(res["columns"])
# [{'name': 'id', 'type': 'BIGINT'}, {'name': 'region', 'type': 'VARCHAR'},
#  {'name': 'total', 'type': 'DOUBLE'}, {'name': 'ok', 'type': 'BOOLEAN'}]

Cuando usarla

Cuando necesitas el schema de una tabla DuckDB sin abrir la base en escritura: mapear tipos DuckDB a otro motor (es el paso (a) de duckdb_to_postgres_py_pipelines), validar que una tabla tiene las columnas esperadas tras una ingesta, o mostrar el schema en una UI. Usa duckdb_list_tables_py_infra antes para descubrir que tablas hay. El dict de salida es directamente serializable a JSON.

Gotchas

• Lectura real de un archivo en disco (impura). El modo read_only=True exige que el archivo ya exista: no crea la base. Si db_path no existe, devuelve {status:'error', ...}.
• El identificador table se valida contra ^[A-Za-z_][A-Za-z0-9_]*$ porque DESCRIBE NO admite parametro posicional para el nombre de tabla y hay que interpolarlo. Un nombre con espacios, comillas, puntos o intento de inyeccion devuelve {status:'error', error:'invalid table identifier'} sin tocar la base.
• El type es el tipo DuckDB literal (BIGINT, DOUBLE, VARCHAR, DECIMAL(10,2), STRUCT(...), ...). Si lo vas a traducir a otro motor, contempla los tipos parametrizados y compuestos: pueden requerir mapeo con perdida (a TEXT).
• DuckDB es single-writer: una base bloqueada en escritura por otro proceso con version distinta puede fallar al abrir en read-only; el error se devuelve, no se lanza.