Skip to Content

Dinaup.Database

PGClient conecta con PostgreSQL y ofrece lecturas tipadas, inserción, actualización, upsert parametrizado, lectura por lotes y opciones de pool y reintentos.

PGClient, del módulo Dinaup.Database, ejecuta SQL contra PostgreSQL y devuelve los resultados como valores, listas, diccionarios o modelos. Con PG Sync activado, lee la réplica de los datos de tu empresa.

Antes de empezar

  • Paquete Dinaup instalado. Ver SDK .NET.
  • Host, puerto, usuario, contraseña y base de datos, o una cadena de conexión.
using Dinaup.Database;
using Dinaup.Database.Definitions;   // PGClientOptions, BaseModelConverter, PGResult

Conectar

var client = new PGClient();
client.Connect("localhost", 5432, "myuser", "mypassword", "mydatabase");

// Cadena key=value o URI postgresql://
client.Connect("postgresql://user:password@host:5432/dbname?sslmode=require");

// Constructores que conectan en el mismo paso, y la versión asíncrona
var c1 = new PGClient("postgresql://user:password@host:5432/dbname");
var ready = await PGClient.CreateAsync("localhost", 5432, "user", "password", "mydb");

PGClient es seguro entre hilos una vez conectado. EnsureConnectionOk() comprueba la conexión. DuplicateConnection() y DuplicateConnectionAsync() crean otro cliente conectado con las mismas opciones, esquema y DefaultTags. Expone IsConnected, Host, Port, DatabaseName, CurrentSchema, Description (alias de Options.ApplicationName) y Options. Implementa IDisposable.

PGClientOptions

Se pasa al constructor (new PGClient(options)) y no cambia después.

PropiedadDefectoQué controla
MaxPoolSize / MinPoolSize10 / 1Conexiones máximas y mínimas del pool.
CommandTimeoutSeconds30Tiempo máximo por comando.
ConnectTimeoutSeconds15Tiempo máximo para abrir la conexión.
MaxRetries3Reintentos ante un fallo transitorio de conexión. Los errores SQL no se reintentan: llegan como excepciones de Npgsql.
RetryBaseDelayMs / RetryMaxDelayMs500 / 8000Espera entre reintentos, que crece en potencias de 2 hasta el máximo.
ApplicationName""Nombre de aplicación de la conexión.
Schema""Esquema por defecto.
UseSsltrueNegocia TLS en la conexión por parámetros.

Leer

MétodoDevuelve
ReadValue(SQL)La primera celda de la primera fila como string, o null si no hay filas.
ReadList(SQL)List<string> con la primera columna de cada fila.
ReadKVDictionary(SQL)Dictionary<string, string> con dos columnas: clave y valor.
ReadDictionaryList(SQL)Un diccionario por fila. La variante síncrona es un IEnumerable que se recorre según llegan las filas; la asíncrona, una List.
ReadObjectList<T>(SQL)Objetos T que heredan de BaseModelConverter.
ReadModel<T>(cols, SQL)Objetos T mapeados desde las columnas indicadas.
ReadModelsUpdated<T>(fromDate)Los T modificados desde una fecha, según LastModifiedFieldDatetimeUTC del modelo.
Read(SQL, receiveColumns, optimizeMemory = false)Un PGResult con Data, ColumnMappings, ResultCount y lectura fila a fila (ReadNextRow, Item(columna), ToDictionary).
ReadCopy(SQL, optimizeMemory = false)Las celdas como string[] plano por el protocolo COPY, entre 5 y 10 veces más rápido. Sin metadatos.

Cada método tiene su variante Async.

int total = client.ReadValue("SELECT COUNT(*) FROM test_table;").INT(0);
var nombres = client.ReadList("SELECT name FROM test_table ORDER BY id;");
foreach (var reg in client.ReadDictionaryList("SELECT id, name FROM test_table WHERE id < 10;"))
    Console.WriteLine($"{reg["id"]}: {reg["name"]}");

Modelos con BaseModelConverter

Una clase que hereda de BaseModelConverter declara la tabla, las columnas y cómo pasar de diccionario a propiedades (FromDic) y al revés (ToDic):

public class TestModel : BaseModelConverter
{
    public int Id { get; set; }
    public string Name { get; set; }

    public override string Table => "test_table";
    public override string[] Fields => new[] { "id", "name" };
    public override string LastModifiedFieldDatetimeUTC => "";   // vacío: ReadModelsUpdated no aplica

    public override void FromDic(Dictionary<string, string> dic)
    {
        Id = dic.GetM("id").INT(0);
        Name = dic.GetM("name");
    }

    public override Dictionary<string, string> ToDic() => new() { { "id", Id.STR() }, { "name", Name } };
}

var modelos = client.ReadObjectList<TestModel>("SELECT * FROM test_table ORDER BY id;");

GetM, INT y STR son Utilidades del SDK.

Escribir

Las escrituras van parametrizadas. Los nombres de tabla y columna solo admiten letras, dígitos, guion bajo y un punto opcional. Un null en el diccionario se envía como NULL.

MétodoQué hace
ExecuteNonQuery(SQL)Ejecuta una sentencia y devuelve las filas afectadas.
InsertRecord(tableName, record) / InsertRecords(tableName, records)Inserta una fila o varias en una sentencia.
UpdateRecord(tableName, dataDict, idField, idValue)Actualiza la fila cuyo idField vale idValue.
InsertOrIgnoreRecord(tableName, dataDict)Inserta si no hay conflicto; devuelve bool.
InsertOrUpdateRecord(tableName, dataDict, idField, updateFields = null)INSERT con ON CONFLICT (idField) DO UPDATE. updateFields limita las columnas que se actualizan.
InsertOrUpdateRecords(tableName, dataDicts, idField, updateFields = null)El mismo upsert para varias filas en un viaje.

Cada método tiene su variante Async.

client.InsertRecord("test_table", new Dictionary<string, string> { { "name", "Nuevo" }, { "value", "123" } });
client.UpdateRecord("test_table", new Dictionary<string, string> { { "value", "999" } }, "id", "1");
client.InsertOrUpdateRecord("test_table", new Dictionary<string, string> { { "id", "100" }, { "name", "Registro100" } }, "id");

Leer por lotes

Los métodos BatchRead piden una consulta de recuento y otra de datos, y devuelven lotes de batchSize filas. startFrom salta las primeras.

MétodoDevuelve
BatchReadDictionaries(description, countSQL, dataSQL, batchSize, startFrom = 0)Iterador de lotes, cada uno una List<Dictionary<string, string>>.
BatchReadObjects<T>(description, countSQL, dataSQL, batchSize, startFrom = 0)Igual, con objetos T de BaseModelConverter.
BatchReadDictionariesAsync, BatchReadObjectsAsyncLa lista completa de lotes. Para procesar los lotes según llegan, usa el iterador síncrono.
foreach (var lote in client.BatchReadDictionaries("Lectura en lotes",
    "SELECT COUNT(*) FROM test_table", "SELECT id, name FROM test_table ORDER BY id", 1000))
{
    Console.WriteLine($"Lote de {lote.Count} registros");
}

Etiquetas de consulta

PGClient añade a cada consulta un comentario sqlcommenter (/*clave='valor'*/) con las etiquetas fijas de DefaultTags y dos parámetros opcionales de cada método: description, el motivo, y op, la operación en curso. En los BatchRead, description es el primer parámetro. Sin etiquetas, el SQL sale tal cual.

client.DefaultTags["app"] = "importador-nocturno";
await client.ReadListAsync("SELECT name FROM test_table;", description: "import.nombres", op: "tick.importar");
// SELECT name FROM test_table /*app='importador-nocturno',description='import.nombres',op='tick.importar'*/;

Los valores se quedan en letras y dígitos sin tildes, _, -, . y /, con los espacios como _ y hasta 120 caracteres.

En esta página