Sistema de Base de Datos

Sistema de Base de Datos

Pool de conexiones y configuración de bases de datos SQL. Soporta PostgreSQL, MySQL y SQLite.

Tipos de Entrada

Tipo	Descripción
db.sql.postgres	Base de datos PostgreSQL
db.sql.mysql	Base de datos MySQL
db.sql.sqlite	Base de datos SQLite

Configuración

Bases de Datos Estándar (PostgreSQL, MySQL)

src/data/_index.yaml

version: "1.0"
namespace: app.data

entries:
  - name: main_db
    kind: db.sql.postgres
    host: "localhost"
    port: 5432
    database: "myapp"
    username: "dbuser"
    password: "dbpass"
    pool:
      max_open: 25
      max_idle: 5
      max_lifetime: "1h"
    options:
      sslmode: "disable"
    lifecycle:
      auto_start: true

SQLite

  - name: cache_db
    kind: db.sql.sqlite
    file: "/var/data/cache.db"  # Use :memory: para en memoria
    pool:
      max_open: 1
      max_idle: 1
      max_lifetime: "1h"
    options:
      cache: "shared"
    lifecycle:
      auto_start: true

Campos de Conexión

Campos de Base de Datos Estándar

Campo	Tipo	Descripción
host	string	Dirección del host de base de datos
port	int	Número de puerto de base de datos
database	string	Nombre de base de datos
username	string	Usuario de base de datos
password	string	Contraseña de base de datos
pool	object	Configuración del pool de conexiones
options	map	Opciones específicas de la base de datos
lifecycle	object	Configuración de ciclo de vida

Campos de SQLite

Campo	Tipo	Descripción
file	string	Ruta del archivo de base de datos o :memory:
pool	object	Configuración del pool de conexiones
options	map	Opciones específicas de SQLite
lifecycle	object	Configuración de ciclo de vida

Campos de Variables de Entorno

Use el sufijo _env para cargar valores desde variables de entorno o entradas env.variable:

Campo	Descripción
host_env	Host desde variable de entorno
port_env	Puerto desde variable de entorno
database_env	Nombre de base de datos desde entorno
username_env	Usuario desde entorno
password_env	Contraseña desde entorno

- name: prod_db
  kind: db.sql.postgres
  host_env: "DB_HOST"
  port_env: "DB_PORT"
  database_env: "DB_NAME"
  username_env: "DB_USER"
  password_env: "app.secrets:db_password"  # Referencia entrada env.variable

Evite codificar contraseñas en la configuración. Use variables de entorno o entradas env.variable para credenciales. Consulte Entorno para gestión segura de secretos.

Pool de Conexiones

Configure el comportamiento del pool de conexiones. La configuración del pool se mapea al pool de conexiones de database/sql de Go.

Campo	Tipo	Por Defecto	Descripción
max_open	int	0	Conexiones máximas abiertas (0 = ilimitado)
max_idle	int	0	Conexiones máximas inactivas (0 = ilimitado)
max_lifetime	duration	1h	Tiempo de vida máximo de conexión

pool:
  max_open: 25      # Limitar conexiones concurrentes
  max_idle: 5       # Mantener 5 conexiones listas
  max_lifetime: "30m"  # Reciclar conexiones cada 30 minutos

Establezca max_idle menor o igual a max_open. Las conexiones que excedan max_lifetime se cierran y reemplazan, ayudando a recuperarse de conexiones obsoletas.

Formatos DSN

Cada tipo de base de datos construye un DSN desde la configuración:

PostgreSQL {id=“dsn-postgresql”}

postgres://username:password@host:port/database?sslmode=disable

MySQL {id=“dsn-mysql”}

username:password@tcp(host:port)/database?charset=utf8mb4

SQLite {id=“dsn-sqlite”}

file:/path/to/database.db?cache=shared
:memory:?mode=memory

Opciones de Base de Datos

Opciones comunes específicas de base de datos:

PostgreSQL {id=“options-postgresql”}

options:
  sslmode: "require"      # disable, require, verify-ca, verify-full
  connect_timeout: "10"   # Timeout de conexión en segundos
  application_name: "myapp"

MySQL {id=“options-mysql”}

options:
  charset: "utf8mb4"
  parseTime: "true"       # Parsear valores de tiempo a time.Time
  loc: "Local"            # Zona horaria

SQLite {id=“options-sqlite”}

options:
  cache: "shared"         # shared, private
  mode: "rwc"            # ro, rw, rwc, memory
  _journal_mode: "WAL"   # DELETE, TRUNCATE, PERSIST, MEMORY, WAL, OFF

Ejemplos

PostgreSQL con SSL

- name: secure_postgres
  kind: db.sql.postgres
  host: "db.example.com"
  port: 5432
  database: "production"
  username: "app_user"
  password: "${DB_PASSWORD}"
  pool:
    max_open: 50
    max_idle: 10
    max_lifetime: "1h"
  options:
    sslmode: "verify-full"
    sslcert: "/certs/client.crt"
    sslkey: "/certs/client.key"
    sslrootcert: "/certs/ca.crt"
  lifecycle:
    auto_start: true

Réplica de Lectura MySQL

- name: mysql_replica
  kind: db.sql.mysql
  host: "replica.db.example.com"
  port: 3306
  database: "app"
  username: "readonly"
  password_env: "REPLICA_PASSWORD"
  pool:
    max_open: 20
    max_idle: 5
    max_lifetime: "30m"
  options:
    charset: "utf8mb4"
    parseTime: "true"
    readTimeout: "30s"

SQLite En Memoria

- name: test_db
  kind: db.sql.sqlite
  file: ":memory:"
  pool:
    max_open: 1
    max_idle: 1
  options:
    cache: "shared"
    mode: "memory"

Configuración de Múltiples Bases de Datos

entries:
  # Base de datos principal
  - name: users_db
    kind: db.sql.postgres
    host_env: "USERS_DB_HOST"
    port: 5432
    database: "users"
    username_env: "USERS_DB_USER"
    password_env: "USERS_DB_PASSWORD"
    lifecycle:
      auto_start: true

  # Base de datos de analíticas
  - name: analytics_db
    kind: db.sql.mysql
    host_env: "ANALYTICS_DB_HOST"
    port: 3306
    database: "analytics"
    username_env: "ANALYTICS_DB_USER"
    password_env: "ANALYTICS_DB_PASSWORD"
    lifecycle:
      auto_start: true

  # Cache local
  - name: cache
    kind: db.sql.sqlite
    file: "/var/cache/app.db"
    lifecycle:
      auto_start: true

Registro en Tiempo de Ejecución

Las bases de datos pueden registrarse en tiempo de ejecución usando el módulo registry, habilitando configuración dinámica de base de datos basada en el estado de la aplicación o configuración externa.

API Lua

Consulte el Módulo SQL para la API de operaciones de base de datos.

Ver También

• Módulo SQL - Referencia de la API Lua
• Store - Almacén clave-valor respaldado por database.sql
• Queue - Handler de cola respaldado por SQL