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
Dinaupinstalado. 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, PGResultConectar
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.
| Propiedad | Defecto | Qué controla |
|---|---|---|
MaxPoolSize / MinPoolSize | 10 / 1 | Conexiones máximas y mínimas del pool. |
CommandTimeoutSeconds | 30 | Tiempo máximo por comando. |
ConnectTimeoutSeconds | 15 | Tiempo máximo para abrir la conexión. |
MaxRetries | 3 | Reintentos ante un fallo transitorio de conexión. Los errores SQL no se reintentan: llegan como excepciones de Npgsql. |
RetryBaseDelayMs / RetryMaxDelayMs | 500 / 8000 | Espera 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. |
UseSsl | true | Negocia TLS en la conexión por parámetros. |
Leer
| Método | Devuelve |
|---|---|
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étodo | Qué 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étodo | Devuelve |
|---|---|
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, BatchReadObjectsAsync | La 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.