El módulo file_fdw proporciona el conector de datos externos
(foreign-data wrapper) file_fdw, que se puede utilizar para acceder a archivos de datos
en el sistema de archivos del servidor, o para ejecutar programas en el servidor
y leer su salida. El archivo de datos o la salida del programa debe estar en un formato
que pueda ser leído por COPY FROM;
consulta COPY para más detalles.
El acceso a los archivos de datos es actualmente de solo lectura.
Una tabla externa creada con este conector puede tener las siguientes opciones:
filename
Especifica el archivo a leer. Las rutas relativas son relativas al
directorio de datos (data directory).
Se debe especificar filename o program,
pero no ambos.
program
Especifica el comando a ejecutar. La salida estándar de este
comando se leerá como si se hubiera utilizado COPY FROM PROGRAM.
Se debe especificar program o filename,
pero no ambos.
format
Especifica el formato de datos,
el mismo que la opción FORMAT de COPY.
header
Especifica si los datos tienen una línea de cabecera,
lo mismo que la opción HEADER de COPY.
delimiter
Especifica el carácter delimitador de datos,
el mismo que la opción DELIMITER de COPY.
quote
Especifica el carácter de comilla de datos,
el mismo que la opción QUOTE de COPY.
escape
Especifica el carácter de escape de datos,
el mismo que la opción ESCAPE de COPY.
null
Especifica la cadena nula de datos,
la misma que la opción NULL de COPY.
default
Especifica la cadena que representa un valor por defecto,
la misma que la opción DEFAULT de COPY.
encoding
Especifica la codificación de datos,
la misma que la opción ENCODING de COPY.
on_error
Especifica cómo comportarse cuando se encuentra un error al convertir el
valor de entrada de una columna a su tipo de datos,
lo mismo que la opción ON_ERROR de COPY.
reject_limit
Especifica el número máximo de errores tolerados al convertir el valor de
entrada de una columna a su tipo de datos, lo mismo que la opción
REJECT_LIMIT de COPY.
log_verbosity
Especifica la cantidad de mensajes emitidos por file_fdw,
lo mismo que la opción LOG_VERBOSITY de COPY.
Ten en cuenta que mientras COPY permite especificar opciones como HEADER
sin un valor correspondiente, la sintaxis de opciones de tablas externas
requiere que haya un valor en todos los casos. Para activar las opciones
de COPY que normalmente se escriben sin valor, puedes pasar
el valor TRUE, ya que todas esas opciones son booleanas.
Una columna de una tabla externa creada con este conector puede tener las siguientes opciones:
force_not_null
Esta es una opción booleana. Si es verdadera, especifica que los valores de la
columna no deben compararse con la cadena nula (es decir, la opción
null a nivel de tabla). Esto tiene el mismo efecto
que listar la columna en la opción FORCE_NOT_NULL de
COPY.
force_null
Esta es una opción booleana. Si es verdadera, especifica que los valores de la
columna que coinciden con la cadena nula se devuelven como NULL
incluso si el valor está entre comillas. Sin esta opción, solo los valores sin
comillas que coinciden con la cadena nula se devuelven como NULL.
Esto tiene el mismo efecto que listar la columna en la opción
FORCE_NULL de COPY.
La opción FORCE_QUOTE de COPY
no está soportada actualmente por file_fdw.
Estas opciones solo se pueden especificar para una tabla externa o sus columnas, no
en las opciones del conector de datos externos (foreign-data wrapper) file_fdw, ni en las
opciones de un servidor o mapeo de usuario que use el conector.
Cambiar las opciones a nivel de tabla requiere ser superusuario o tener los privilegios
del rol pg_read_server_files (para usar un nombre de archivo) o
del rol pg_execute_server_program (para usar un programa),
por razones de seguridad: solo ciertos usuarios deberían poder controlar qué archivo se
lee o qué programa se ejecuta. En principio, se podría permitir a los usuarios comunes
cambiar las otras opciones, pero eso no está soportado en este momento.
Al especificar la opción program, ten en cuenta que la cadena de la opción
es ejecutada por la shell. Si necesitas pasar argumentos al comando que provengan de
una fuente no confiable, debes tener cuidado de limpiar o escapar cualquier carácter
que pueda tener un significado especial para la shell. Por razones de seguridad, es
mejor usar una cadena de comando fija, o al menos evitar pasar cualquier entrada de
usuario en ella.
Para una tabla externa que usa file_fdw, EXPLAIN muestra
el nombre del archivo a leer o del programa a ejecutar. Para un archivo, a menos que se
especifique COSTS OFF, también se muestra el tamaño del archivo
(en bytes).
Example F.1. Crear una tabla externa para los registros CSV de PostgreSQL
Uno de los usos obvios de file_fdw es hacer que
el registro de actividad de PostgreSQL esté disponible como una tabla para realizar consultas. Para
hacer esto, primero debes estar registrando en un archivo CSV,
que aquí llamaremos pglog.csv. Primero, instala file_fdw
como una extensión:
CREATE EXTENSION file_fdw;
Luego crea un servidor externo:
CREATE SERVER pglog FOREIGN DATA WRAPPER file_fdw;
Ahora estás listo para crear la tabla de datos externa. Con el
comando CREATE FOREIGN TABLE, tendrás que definir
las columnas de la tabla, el nombre del archivo CSV y su formato:
CREATE FOREIGN TABLE pglog ( log_time timestamp(3) with time zone, user_name text, database_name text, process_id integer, connection_from text, session_id text, session_line_num bigint, command_tag text, session_start_time timestamp with time zone, virtual_transaction_id text, transaction_id bigint, error_severity text, sql_state_code text, message text, detail text, hint text, internal_query text, internal_query_pos integer, context text, query text, query_pos integer, location text, application_name text, backend_type text, leader_pid integer, query_id bigint ) SERVER pglog OPTIONS ( filename 'log/pglog.csv', format 'csv' );
Eso es todo — ahora puedes consultar tu log directamente. En producción, por supuesto, necesitarías definir alguna forma de manejar la rotación de logs.
Example F.2. Crear una tabla externa con una opción en una columna
Para configurar la opción force_null en una columna, usa la
palabra clave OPTIONS.
CREATE FOREIGN TABLE films ( code char(5) NOT NULL, title text NOT NULL, rating text OPTIONS (force_null 'true') ) SERVER film_server OPTIONS ( filename 'films/db.csv', format 'csv' );