YC.EntityFrameworkCore.TigerData.TimescaleDB 1.0.0

YC.EntityFrameworkCore.TigerData.TimescaleDB

First-class TimescaleDB support for Entity Framework Core, layered on top of the Npgsql EF Core provider.

Configure hypertables, columnstore compression, continuous aggregates, retention/reorder policies and background jobs with the Fluent API or attributes — everything flows through standard EF Core migrations (snapshot-diff, fully bidirectional, no imperative commands). Query with TimescaleDB hyperfunctions (time_bucket, first/last, gapfilling, histograms, UUIDv7) directly from LINQ, and reverse-engineer existing schemas with dotnet ef dbcontext scaffold.

Requirements: EF Core 10, Npgsql.EntityFrameworkCore.PostgreSQL 10, TimescaleDB 2.23+. The modern declarative interface is used (create_hypertable, ALTER TABLE … SET (timescaledb.…)); there is no legacy fallback.

Install

One package — design-time support (migration code generation, scaffolding for dotnet ef) is included:

dotnet add package YC.EntityFrameworkCore.TigerData.TimescaleDB

Setup

Call UseTimescaleDb() after UseNpgsql(...):

services.AddDbContext<MetricsContext>(options => options
    .UseNpgsql(connectionString)
    .UseTimescaleDb());

options.UseNpgsql(cs).UseTimescaleDb(o => o.RebuildData(false));   // disable risky rebuilds everywhere

Intervals

Every duration is expressed type-safely — never a raw string:

Every values: Second, Minute, Hour, Day, Week, Month, Year. Use (int, Every) (or its attribute form) whenever you need Week, Month or Year — those are calendar intervals with no fixed TimeSpan.

Quick start

The same hypertable, configured two ways.

Fluent API:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Reading>(e =>
    {
        e.HasNoKey();                                   // raw time-series → keyless
        e.ToTable("readings");
        e.IsHypertable(x => x.Time, chunkInterval: TimeSpan.FromDays(1));
        e.HasSpacePartition(x => x.DeviceId, partitions: 4);
        e.HasColumnstore(cs => cs
            .SegmentBy(x => x.DeviceId)
            .OrderByDescending(x => x.Time));
        e.HasColumnstorePolicy(after: TimeSpan.FromDays(7));
        e.HasRetentionPolicy(dropAfter: TimeSpan.FromDays(90));
    });
}

Attributes (equivalent):

[Columnstore(CompressAfter = 7, CompressAfterUnit = Every.Day)]
[Retention(90, Every.Day)]
public class Reading
{
    [PartitionColumn(1, Every.Day)]      // declares the hypertable + chunk interval
    [OrderBy(0, Sort.Descending)]        // columnstore ordering
    public DateTimeOffset Time { get; set; }

    [SpacePartition(4)]
    [SegmentBy]                          // columnstore segment column
    public string DeviceId { get; set; } = null!;

    public double Value { get; set; }
}

There is no [Hypertable] attribute — the [PartitionColumn] marker is the hypertable declaration, so compression / retention / dimensions cannot be written without one.

Features

Every feature is documented in FEATURES.md with its Fluent/attribute syntax, defaults and allowable values. Click through:

Migrations — snapshot-driven, no special commands

dotnet ef migrations add records the TimescaleDB configuration as annotations on the table, plus migrationBuilder.Sql(...) for the objects that aren't tables (the extension, continuous aggregates, jobs, reorder policies). There are no imperative commands like ConvertToHypertable() or DisableColumnstore().

The provider's SQL generator turns the annotation delta into real DDL when the migration runs. Because the annotations carry both old and new values, every change is bidirectional automatically — the Down migration emits the exact reverse with no extra code, and re-running migrations add on an unchanged model produces an empty migration.

Transition matrix

Changes TimescaleDB cannot apply in place rebuild the table (CREATE TABLE (LIKE … INCLUDING ALL), copy every row, drop, rename) so data is preserved — nothing is rejected:

The automatic, data-heavy steps (migrate_data, the rebuild row-copy, columnstore decompression) can be toggled per entity or model-wide — see Migration options.

Scaffolding

dotnet ef dbcontext scaffold reverse-engineers hypertables, space dimensions, columnstore settings, retention/ columnstore/reorder policies, chunk skipping, tablespaces and custom jobs. Continuous aggregates are not reverse-engineered (materialized views are outside the Npgsql scaffolding surface).

Notes and limitations

• Primary keys on hypertables must include the partition column (TimescaleDB requires every unique constraint to cover the partitioning columns; validated at model-build time).
• Rebuilds are data-heavy and not free of caveats. Un-converting a hypertable, repartitioning, or changing a space dimension copies every row under lock via CREATE TABLE (LIKE … INCLUDING ALL). PostgreSQL LIKE does not copy FOREIGN KEY constraints (inbound or outbound) and recreates indexes under generated names; the migration includes a warning comment. Re-create FKs and any reorder policy manually afterward.
• Chunk interval changes apply to future chunks only (set_chunk_time_interval); existing chunks keep their interval. Re-chunking historical data is intentionally not performed.
• Chunk skipping requires an ordered scalar column (integer/time, not floating point); the migration enables the timescaledb.enable_chunk_skipping GUC.
• Converting an existing table to a hypertable and disabling the columnstore are data-heavy (row migration / chunk decompression); review the generated migration before running it in production.
• Enabling the columnstore auto-creates a default conversion policy; HasColumnstorePolicy replaces it.
• Direct Compress (Direct-to-Columnstore) is a session-level ingestion GUC (SET timescaledb.enable_direct_compress_insert/copy = on), not a table option — enable it in the session doing the bulk INSERT/COPY. It has no declarative DDL form, so it is outside this package's migration scope (and is a TimescaleDB tech preview).

License

MIT