feat: add migrate_data parameter support for hypertables (fixes #16)

Adds the ability to specify whether existing data should be migrated when converting a regular PostgreSQL table to a TimescaleDB hypertable.

Implementation:
  - Added MigrateData property to CreateHypertableOperation
  - Added MigrateData annotation constant to HypertableAnnotations
  - Added MigrateData property to HypertableAttribute
  - Added WithMigrateData() fluent API method to HypertableTypeBuilder
  - Updated HypertableConvention to process MigrateData from attribute
  - Updated HypertableModelExtractor to extract MigrateData annotation
  - Updated HypertableOperationGenerator to generate migrate_data => true SQL

Testing:
  - Added 19 unit tests across 5 test files
  - Added 5 integration tests verifying end-to-end behavior

Author: sebastian-ederer

README.md

@@ -24,6 +24,7 @@ Seamlessly define and manage **TimescaleDB hypertables** using standard EF Core
 - **Time Partitioning**: Easily specify the primary time column and set the `chunk_time_interval`.
 - **Space Partitioning**: Add additional dimensions for hash or range partitioning to further optimize queries.
 - **Chunk Time Interval**: Configure chunk intervals to balance performance and storage efficiency.
+- **Data Migration**: Control whether existing data should be migrated when converting a regular table to a hypertable using `migrate_data`.
 - **Compression & Chunk Skipping**: Enable TimescaleDB's native compression and configure chunk skipping to improve query performance.
 
 ### Reorder Policies
@@ -97,7 +98,9 @@ public class WeatherDataConfiguration : IEntityTypeConfiguration<WeatherData>
                // Optional: Enable chunk skipping for faster queries on this column.
                .WithChunkSkipping(x => x.Time)
                // Optional: Set the chunk interval. Can be a string ("7 days") or long (microseconds).
-               .WithChunkTimeInterval("86400000");
+               .WithChunkTimeInterval("86400000")
+               // Optional: Migrate existing data when converting to hypertable (defaults to false).
+               .WithMigrateData(true);
     }
 }
 ```
@@ -108,7 +111,10 @@ public class WeatherDataConfiguration : IEntityTypeConfiguration<WeatherData>
 For simpler configurations, you can use the [Hypertable] attribute directly on your model class.
 
 ```csharp
-[Hypertable(nameof(Time), ChunkSkipColumns = new[] { "Time" }, ChunkTimeInterval = "86400000")]
+[Hypertable(nameof(Time),
+    ChunkSkipColumns = new[] { "Time" },
+    ChunkTimeInterval = "86400000",
+    MigrateData = true)]
 [PrimaryKey(nameof(Id), nameof(Time))]
 public class DeviceReading
 {

src/Eftdb/Configuration/Hypertable/HypertableAnnotations.cs

@@ -8,6 +8,7 @@ public static class HypertableAnnotations
         public const string IsHypertable = "TimescaleDB:IsHypertable";
         public const string HypertableTimeColumn = "TimescaleDB:TimeColumnName";
         public const string EnableCompression = "TimescaleDB:EnableCompression";
+        public const string MigrateData = "TimescaleDB:MigrateData";
         public const string ChunkTimeInterval = "TimescaleDB:ChunkTimeInterval";
         public const string ChunkSkipColumns = "TimescaleDB:ChunkSkipColumns";
         public const string AdditionalDimensions = "TimescaleDB:AdditionalDimensions";

src/Eftdb/Configuration/Hypertable/HypertableAttribute.cs

@@ -10,10 +10,15 @@ public sealed class HypertableAttribute : Attribute
         public string TimeColumnName { get; } = string.Empty;
 
         /// <summary>
-        /// 
+        /// Specifies whether compression is enabled on the hypertable.
         /// </summary>
         public bool EnableCompression { get; set; } = false;
 
+        /// <summary>
+        /// Specifies whether existing data should be migrated when converting a table to a hypertable.
+        /// </summary>
+        public bool MigrateData { get; set; } = false;
+
         /// <summary>
         /// Defines the duration of time covered by each chunk in a hypertable.
         /// </summary>

src/Eftdb/Configuration/Hypertable/HypertableConvention.cs

@@ -37,6 +37,11 @@ public void ProcessEntityTypeAdded(IConventionEntityTypeBuilder entityTypeBuilde
                     entityTypeBuilder.HasAnnotation(HypertableAnnotations.EnableCompression, true);
                 }
 
+                if (attribute.MigrateData == true)
+                {
+                    entityTypeBuilder.HasAnnotation(HypertableAnnotations.MigrateData, true);
+                }
+
                 if (attribute.ChunkSkipColumns != null && attribute.ChunkSkipColumns.Length > 0)
                 {
                     /// Chunk skipping requires compression to be enabled

src/Eftdb/Configuration/Hypertable/HypertableTypeBuilder.cs

@@ -128,6 +128,25 @@ public static EntityTypeBuilder<TEntity> EnableCompression<TEntity>(
             return entityTypeBuilder;
         }
 
+        /// <summary>
+        /// Specifies whether existing data should be migrated when converting a table to a hypertable.
+        /// </summary>
+        /// <remarks>
+        /// When converting an existing table to a hypertable, this parameter controls whether existing data
+        /// is migrated into chunks. If set to false, only new data will be stored in chunks.
+        /// Defaults to <c>false</c> to match TimescaleDB's default behavior.
+        /// </remarks>
+        /// <typeparam name="TEntity">The entity type being configured.</typeparam>
+        /// <param name="entityTypeBuilder">The builder for the entity type.</param>
+        /// <param name="migrateData">A boolean indicating whether to migrate existing data. Defaults to <c>true</c>.</param>
+        public static EntityTypeBuilder<TEntity> WithMigrateData<TEntity>(
+            this EntityTypeBuilder<TEntity> entityTypeBuilder,
+            bool migrateData = true) where TEntity : class
+        {
+            entityTypeBuilder.HasAnnotation(HypertableAnnotations.MigrateData, migrateData);
+            return entityTypeBuilder;
+        }
+
         /// <summary>
         /// Extracts the property name from a member access lambda expression.
         /// </summary>

src/Eftdb/Generators/HypertableOperationGenerator.cs

@@ -24,9 +24,11 @@ public List<string> Generate(CreateHypertableOperation operation)
             string qualifiedTableName = sqlHelper.Regclass(operation.TableName, operation.Schema);
             string qualifiedIdentifier = sqlHelper.QualifiedIdentifier(operation.TableName, operation.Schema);
 
+            string migrateDataParam = operation.MigrateData ? ", migrate_data => true" : "";
+
             List<string> statements =
             [
-                $"SELECT create_hypertable({qualifiedTableName}, '{operation.TimeColumnName}');"
+                $"SELECT create_hypertable({qualifiedTableName}, '{operation.TimeColumnName}'{migrateDataParam});"
             ];
 
             // ChunkTimeInterval

src/Eftdb/Internals/Features/Hypertables/HypertableModelExtractor.cs

@@ -76,6 +76,7 @@ public static IEnumerable<CreateHypertableOperation> GetHypertables(IRelationalM
 
                 string chunkTimeInterval = entityType.FindAnnotation(HypertableAnnotations.ChunkTimeInterval)?.Value as string ?? DefaultValues.ChunkTimeInterval;
                 bool enableCompression = entityType.FindAnnotation(HypertableAnnotations.EnableCompression)?.Value as bool? ?? false;
+                bool migrateData = entityType.FindAnnotation(HypertableAnnotations.MigrateData)?.Value as bool? ?? false;
 
                 yield return new CreateHypertableOperation
                 {
@@ -84,6 +85,7 @@ public static IEnumerable<CreateHypertableOperation> GetHypertables(IRelationalM
                     TimeColumnName = timeColumnName,
                     ChunkTimeInterval = chunkTimeInterval ?? DefaultValues.ChunkTimeInterval,
                     EnableCompression = enableCompression,
+                    MigrateData = migrateData,
                     ChunkSkipColumns = chunkSkipColumns,
                     AdditionalDimensions = additionalDimensions
                 };

src/Eftdb/Operations/CreateHypertableOperation.cs

@@ -10,6 +10,7 @@ public class CreateHypertableOperation : MigrationOperation
         public string TimeColumnName { get; set; } = string.Empty;
         public string ChunkTimeInterval { get; set; } = string.Empty;
         public bool EnableCompression { get; set; }
+        public bool MigrateData { get; set; } = false;
         public IReadOnlyList<string>? ChunkSkipColumns { get; set; }
         public IReadOnlyList<Dimension>? AdditionalDimensions { get; set; }
     }

tests/Eftdb.Tests/Configuration/HypertableAttributeTests.cs

@@ -169,5 +169,43 @@ public void ChunkSkipColumns_CanBeSetToEmptyArray()
         Assert.Empty(attr.ChunkSkipColumns);
     }
 
+    [Fact]
+    public void MigrateData_DefaultsToFalse()
+    {
+        // Arrange & Act
+        HypertableAttribute attr = new("Timestamp");
+
+        // Assert
+        Assert.False(attr.MigrateData);
+    }
+
+    [Fact]
+    public void MigrateData_CanBeSetToTrue()
+    {
+        // Arrange
+        HypertableAttribute attr = new("Timestamp")
+        {
+            // Act
+            MigrateData = true
+        };
+
+        // Assert
+        Assert.True(attr.MigrateData);
+    }
+
+    [Fact]
+    public void MigrateData_CanBeSetToFalse()
+    {
+        // Arrange
+        HypertableAttribute attr = new("Timestamp")
+        {
+            // Act
+            MigrateData = false
+        };
+
+        // Assert
+        Assert.False(attr.MigrateData);
+    }
+
     #endregion
 }

tests/Eftdb.Tests/Conventions/HypertableConventionTests.cs

@@ -595,4 +595,202 @@ public void Attribute_Should_Produce_Same_Annotations_As_FluentAPI()
     }
 
     #endregion
+
+    #region Should_Process_Hypertable_With_MigrateData_True
+
+    [Hypertable("Timestamp", MigrateData = true)]
+    private class MigrateDataTrueEntity
+    {
+        public DateTime Timestamp { get; set; }
+        public double Value { get; set; }
+    }
+
+    private class MigrateDataTrueContext : DbContext
+    {
+        public DbSet<MigrateDataTrueEntity> Entities => Set<MigrateDataTrueEntity>();
+
+        protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
+            => optionsBuilder.UseNpgsql("Host=localhost;Database=test;Username=test;Password=test")
+                            .UseTimescaleDb();
+
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<MigrateDataTrueEntity>(entity =>
+            {
+                entity.HasNoKey();
+                entity.ToTable("MigrateDataTrue");
+            });
+        }
+    }
+
+    [Fact]
+    public void Should_Process_Hypertable_With_MigrateData_True()
+    {
+        using MigrateDataTrueContext context = new();
+        IModel model = GetModel(context);
+        IEntityType entityType = model.FindEntityType(typeof(MigrateDataTrueEntity))!;
+
+        Assert.Equal(true, entityType.FindAnnotation(HypertableAnnotations.IsHypertable)?.Value);
+        Assert.Equal(true, entityType.FindAnnotation(HypertableAnnotations.MigrateData)?.Value);
+    }
+
+    #endregion
+
+    #region Should_Not_Apply_MigrateData_When_False
+
+    [Hypertable("Timestamp", MigrateData = false)]
+    private class MigrateDataFalseEntity
+    {
+        public DateTime Timestamp { get; set; }
+        public double Value { get; set; }
+    }
+
+    private class MigrateDataFalseContext : DbContext
+    {
+        public DbSet<MigrateDataFalseEntity> Entities => Set<MigrateDataFalseEntity>();
+
+        protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
+            => optionsBuilder.UseNpgsql("Host=localhost;Database=test;Username=test;Password=test")
+                            .UseTimescaleDb();
+
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<MigrateDataFalseEntity>(entity =>
+            {
+                entity.HasNoKey();
+                entity.ToTable("MigrateDataFalse");
+            });
+        }
+    }
+
+    [Fact]
+    public void Should_Not_Apply_MigrateData_When_False()
+    {
+        using MigrateDataFalseContext context = new();
+        IModel model = GetModel(context);
+        IEntityType entityType = model.FindEntityType(typeof(MigrateDataFalseEntity))!;
+
+        // MigrateData annotation should be null when the attribute property is false
+        Assert.Null(entityType.FindAnnotation(HypertableAnnotations.MigrateData));
+        // But IsHypertable should still be set
+        Assert.Equal(true, entityType.FindAnnotation(HypertableAnnotations.IsHypertable)?.Value);
+    }
+
+    #endregion
+
+    #region Should_Not_Apply_MigrateData_By_Default
+
+    [Hypertable("Timestamp")]
+    private class MigrateDataDefaultEntity
+    {
+        public DateTime Timestamp { get; set; }
+        public double Value { get; set; }
+    }
+
+    private class MigrateDataDefaultContext : DbContext
+    {
+        public DbSet<MigrateDataDefaultEntity> Entities => Set<MigrateDataDefaultEntity>();
+
+        protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
+            => optionsBuilder.UseNpgsql("Host=localhost;Database=test;Username=test;Password=test")
+                            .UseTimescaleDb();
+
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<MigrateDataDefaultEntity>(entity =>
+            {
+                entity.HasNoKey();
+                entity.ToTable("MigrateDataDefault");
+            });
+        }
+    }
+
+    [Fact]
+    public void Should_Not_Apply_MigrateData_By_Default()
+    {
+        using MigrateDataDefaultContext context = new();
+        IModel model = GetModel(context);
+        IEntityType entityType = model.FindEntityType(typeof(MigrateDataDefaultEntity))!;
+
+        // When MigrateData is not explicitly set in attribute, annotation should be null
+        Assert.Null(entityType.FindAnnotation(HypertableAnnotations.MigrateData));
+        // But IsHypertable should still be set
+        Assert.Equal(true, entityType.FindAnnotation(HypertableAnnotations.IsHypertable)?.Value);
+    }
+
+    #endregion
+
+    #region MigrateData_Attribute_Should_Produce_Same_Annotation_As_FluentAPI
+
+    [Hypertable("Timestamp", MigrateData = true)]
+    private class MigrateDataAttributeEntity
+    {
+        public DateTime Timestamp { get; set; }
+        public double Value { get; set; }
+    }
+
+    private class MigrateDataFluentEntity
+    {
+        public DateTime Timestamp { get; set; }
+        public double Value { get; set; }
+    }
+
+    private class MigrateDataAttributeContext : DbContext
+    {
+        public DbSet<MigrateDataAttributeEntity> Entities => Set<MigrateDataAttributeEntity>();
+
+        protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
+            => optionsBuilder.UseNpgsql("Host=localhost;Database=test;Username=test;Password=test")
+                            .UseTimescaleDb();
+
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<MigrateDataAttributeEntity>(entity =>
+            {
+                entity.HasNoKey();
+                entity.ToTable("MigrateDataEquivalence");
+            });
+        }
+    }
+
+    private class MigrateDataFluentContext : DbContext
+    {
+        public DbSet<MigrateDataFluentEntity> Entities => Set<MigrateDataFluentEntity>();
+
+        protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
+            => optionsBuilder.UseNpgsql("Host=localhost;Database=test;Username=test;Password=test")
+                            .UseTimescaleDb();
+
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<MigrateDataFluentEntity>(entity =>
+            {
+                entity.HasNoKey();
+                entity.ToTable("MigrateDataEquivalence");
+                entity.IsHypertable(x => x.Timestamp)
+                      .WithMigrateData(true);
+            });
+        }
+    }
+
+    [Fact]
+    public void MigrateData_Attribute_Should_Produce_Same_Annotation_As_FluentAPI()
+    {
+        using MigrateDataAttributeContext attributeContext = new();
+        using MigrateDataFluentContext fluentContext = new();
+
+        IModel attributeModel = GetModel(attributeContext);
+        IModel fluentModel = GetModel(fluentContext);
+
+        IEntityType attributeEntity = attributeModel.FindEntityType(typeof(MigrateDataAttributeEntity))!;
+        IEntityType fluentEntity = fluentModel.FindEntityType(typeof(MigrateDataFluentEntity))!;
+
+        Assert.Equal(
+            attributeEntity.FindAnnotation(HypertableAnnotations.MigrateData)?.Value,
+            fluentEntity.FindAnnotation(HypertableAnnotations.MigrateData)?.Value
+        );
+        Assert.Equal(true, attributeEntity.FindAnnotation(HypertableAnnotations.MigrateData)?.Value);
+    }
+
+    #endregion
 }