GitHub - pgEdge/pgedge-docloader: A tool for converting HTML and RST docs into Markdown, and loading them into PostgreSQL.

https://github.com/pgEdge/pgedge-docloader • Feb 1, 2026 10:42

Extracto

A tool for converting HTML and RST docs into Markdown, and loading them into PostgreSQL. - pgEdge/pgedge-docloader

Resumen

Resumen Principal

El pgEdge Document Loader es una herramienta de línea de comandos robusta y especializada, diseñada para optimizar la ingesta y gestión de contenido documental en bases de datos PostgreSQL. Su funcionalidad central radica en la conversión automática de diversos formatos de documentos, incluyendo HTML, Markdown, reStructuredText y SGML/DocBook, a un formato unificado de Markdown. Este proceso no solo estandariza el contenido, sino que también extrae metadata esencial como títulos, nombres de archivo y marcas de tiempo, enriqueciendo así los datos almacenados. La flexibilidad del cargador se manifiesta en su capacidad para procesar información de múltiples fuentes, desde archivos individuales y directorios hasta repositorios Git completos, facilitando una automatización significativa en la creación de una base de conocimiento estructurada y consultable dentro de PostgreSQL. Su diseño prioriza la integración con la base de datos, ofreciendo configuraciones detalladas para el mapeo de columnas y la adición de metadatos personalizados, lo que lo convierte en una solución integral para desarrolladores y administradores que buscan centralizar y contextualizar su documentación.

Elementos Clave

Conversión Automática y Extracción de Metadata: El pgEdge Document Loader destaca por su capacidad de transformar automáticamente documentos en formatos variados (HTML, Markdown, reStructuredText, y DocBook SGML/XML) a Markdown. Durante esta conversión, el cargador extrae automáticamente metadatos clave como títulos, nombres de archivo y marcas de tiempo, lo que permite una indexación y búsqueda más eficiente del contenido cargado en la base de datos.
Soporte Extenso para Fuentes de Datos y Formatos: La herramienta ofrece una notable flexibilidad al permitir la carga de documentos desde diversas fuentes, incluyendo archivos individuales, directorios, patrones glob y, fundamentalmente, repositorios Git. Esta última característica es crucial para la gestión de documentación versionada. Además de los formatos mencionados, su amplio soporte garantiza que una gran variedad de fuentes de contenido pueda ser procesada y unificada.
Integración y Configuración Profunda con PostgreSQL: El Document Loader está intrínsecamente ligado a PostgreSQL, requiriendo una tabla predefinida con columnas específicas (como id, title, content, filename). Permite una configuración detallada del mapeo de columnas y la inclusión de columnas de metadatos personalizadas con valores fijos, lo que dota a los usuarios de un control granular sobre cómo se almacena y organiza la información dentro de la base de datos.
Operación Transaccional y Seguridad Robusta: Para asegurar la integridad de los datos, el proceso de carga es transaccional, lo que significa que todas las operaciones son un "todo o nada" con rollback automático en caso de fallo, garantizando que la base de datos se mantenga en un estado consistente. En cuanto a la seguridad, la herramienta soporta la gestión de contraseñas de PostgreSQL a través de variables de entorno, archivos .pgpass o mediante solicitud interactiva, lo que ofrece opciones seguras para la autenticación.

Análisis e Implicaciones

La existencia del pgEdge Document Loader implica una simplificación significativa para la gestión de documentación técnica y de conocimiento dentro de entornos que utilizan PostgreSQL. Al automatizar la conversión y la extracción de metadatos, reduce la carga manual y mejora la calidad de los datos, lo que facilita el desarrollo de aplicaciones que requieran una búsqueda semántica o un análisis de contenido estructurado directamente desde la base de datos. Esto es particularmente relevante para proyectos con una gran cantidad de documentación dispersa en múltiples formatos y repositorios, donde la unificación y accesibilidad son críticas.

Contexto Adicional

El proyecto se encuentra en desarrollo activo y anima a la comunidad a realizar contribuciones, lo que sugiere un futuro continuo de mejoras y nuevas funcionalidades. Está licenciado bajo la PostgreSQL License, fomentando su uso y modificación en un entorno de código abierto.

Contenido

pgEdge Document Loader

pgEdge Document Loader is a command-line tool for loading documents from various formats into PostgreSQL databases. Full documentation is available here.

The pgEdge Document Loader automatically converts documents (HTML, Markdown, reStructuredText, and SGML/DocBook) to Markdown format and loads them into a PostgreSQL database with extracted metadata.

Features

The pgEdge Document Loader automatically converts documents (HTML, Markdown, reStructuredText, and DocBook SGML/XML) to Markdown format and loads them into a PostgreSQL database with extracted metadata.

Features

Multiple Format Support: HTML, Markdown, reStructuredText, and DocBook SGML/XML
Git Repository Support: Clone and process docs directly from Git repositories
Automatic Conversion: All formats converted to Markdown
Metadata Extraction: Titles, filenames, timestamps
Flexible Input: Single file, directory, glob patterns, or Git repository URL
Database Flexibility: Configurable column mappings
Custom Metadata Columns: Add fixed values to custom columns for every row
Update Mode: Update existing rows or insert new ones
Transactional: All-or-nothing processing with automatic rollback
Secure: Password from environment, .pgpass, or interactive prompt
Configuration Files: Reusable YAML configuration

Document Loader Quickstart

Before installing and using pgEdge Document Loader, download and install:

Go 1.23 or later
PostgreSQL 14 or later

Getting started with pgEdge Document Loader involves three steps:

Install the tool.
Create a table in your Postgres database to hold the loaded content.
Run the pgedge-docloader executable.

Installing pgEdge Document Loader

Use the following commands to download and build pgedge-docloader:

git clone https://github.com/pgedge/pgedge-docloader.git
cd pgedge-docloader
make build
make install

Creating a Postgres Table

Before invoking Document Loader, you must configure a Postgres database and create a table with the appropriate columns to hold the extracted documentation content:

CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT NOT NULL,
    source BYTEA,
    filename TEXT UNIQUE,
    modified TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Invoking pgedge-docloader

When invoking pgedge-docloader, you can specify configuration preferences on the command line, or with a configuration file.

The following command invokes Document Loader on the command line:

# Load Markdown files into PostgreSQL
pgedge-docloader \
  --source ./docs \
  --db-host localhost \
  --db-name mydb \
  --db-user myuser \
  --db-table documents \
  --col-doc-content content \
  --col-file-name filename

To manage deployment preferences in a configuration file, save your deployment details in a file, and then include the --config keyword when invoking pgedge-docloader:

# Create config.yml
cat > config.yml <<EOF
source: "./docs"
db-host: localhost
db-name: mydb
db-user: myuser
db-table: documents
col-doc-content: content
col-file-name: filename
update: true
EOF

# Run with a configuration file
export PGPASSWORD=mypassword
pgedge-docloader --config config.yml

For a comprehensive Quickstart Guide, visit here.

Developer Notes

This project is under active development. See the documentation for the latest features and updates.

The pgEdge Document Loader Makefile includes clauses that run test cases or invoke the go linter. Use the following commands:

Running Tests

Linting

Your contributions are welcome! Please feel free to submit issues and pull requests.

Support

Documentation: pgEdge Docloader
Issues: GitHub Issues

License

This project is licensed under the PostgreSQL License.