PetToys.BigDecimal.Npgsql 1.0.1

PetToys.BigDecimal.Npgsql

PostgreSQL helpers for PetToys.BigDecimal.Core: they map the arbitrary numeric values that PostgreSQL allows - and that decimal cannot hold - onto BigDecimal when reading and writing through Npgsql.

Bring your own configured NpgsqlConnection or data source; this package only deals with the value mapping.

Installation

dotnet add package PetToys.BigDecimal.Npgsql

The core type's own package, PetToys.BigDecimal.Core, comes along as a dependency.

Releases go to nuget.org, so the command above is all that is needed. Prereleases are published to GitHub Packages instead: that feed has to be added to your nuget.config, and it requires a personal access token with read:packages even for a public package.

Usage

Register the mapping once, on the data source:

using Npgsql;
using PetToys.BigDecimal.Numerics;

await using var source = new NpgsqlDataSourceBuilder(connectionString)
    .UseBigDecimal()
    .Build();

Then ask for the type where you want it:

await using var command = source.CreateCommand(
    "SELECT total FROM invoices WHERE id = $1");
command.Parameters.Add(new NpgsqlParameter { Value = invoiceId });

await using var reader = await command.ExecuteReaderAsync();
await reader.ReadAsync();

BigDecimal total = reader.GetBigDecimal("total");

Writing needs nothing but the value:

command.Parameters.Add(new NpgsqlParameter { Value = total });

numeric[] maps as well, to BigDecimal[], List<BigDecimal> and their nullable forms; and a binary COPY import goes through the same mapping, which is the path to use for more than a handful of rows.

UseBigDecimal is also an extension on INpgsqlTypeMapper, so it works from a configuration callback and on NpgsqlSlimDataSourceBuilder.

Registering it does not change anything else

BigDecimal is for the columns that need it, not a replacement for System.Decimal across an application, and the registration is built that way. A numeric column read with GetValue is still a decimal, GetFieldType still reports decimal, and a DataTable still fills with decimal. Code written before this package was referenced reads exactly what it read before. BigDecimal is reached by asking for it, per read.

What round-trips, and what does not

The type's own bounds are 77 significant digits, a largest magnitude of 2^256-1, and a range of 1e-255 to approximately 1.157e77.

Only one direction can fail. Every value of the type fits a numeric, so writing never overflows and never rounds. Reading is the direction with a boundary, and GetBigDecimal names the column when a value crosses it:

Column 'total' at ordinal 0 holds a numeric whose integer part is larger than
BigDecimal can represent: ...

That naming is what the accessors are for. Reading the same column through GetFieldValue<BigDecimal> or through Dapper gets the same mapping and the same OverflowException, without the column name.

Through Entity Framework Core, add PetToys.BigDecimal.Npgsql.EntityFrameworkCore: it maps a numeric column to a BigDecimal property over this package's registration, and the value the caller can name there is the property, read off the DbUpdateException Entity Framework raises.

Requirements

• Npgsql 10.0.3, up to but not including 11. The mapping registers through Npgsql.Internal, which is the driver's only extension point for a new type and is published as experimental, so the floor is the version this package was built against and the range is closed at the major. A driver major that reshapes the extension point therefore fails at restore rather than at the first read; the ceiling moves once the new major has been tested against.
• Trimmed and Native AOT publishing both work. This assembly is marked IsAotCompatible, and Npgsql 10.0.3 is itself marked trimmable, so the closure a publish trims carries no unmarked assembly. Both forms are verified by publishing a probe over this package and running it against a real server, not by a clean analyzer pass. Under Native AOT, build the data source with NpgsqlSlimDataSourceBuilder, which is Npgsql's own route for that case and which UseBigDecimal overloads; the slim builder starts with nothing enabled, so a numeric[] needs EnableArrays() on it. A trimmed build can use either builder. Serializing a BigDecimal to JSON in such an application needs a source-generated context, which is a System.Text.Json rule rather than one of this package's; the core package's README carries the detail.
• PostgreSQL 14 or later for the infinities. That is where numeric gained the sign codes that carry them. Everything else works on any supported server; against an older one, writing an infinity is refused by the server itself and this package does not emulate or substitute anything.

Links

• Source and documentation
• Report an issue

License

Provided under the Apache License, Version 2.0.