migrate-postgres-tables-to-hypertables

Generate executable migration plans for PostgreSQL tables to TimescaleDB hypertables.

1.8k|104|Updated Jul 23, 2025
One-click install
npx skills add https://github.com/timescale/pg-aiguide --skill migrate-postgres-tables-to-hypertables-timescale
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: migrate-postgres-tables-to-hypertables
Source: https://github.com/timescale/pg-aiguide/tree/main/skills/migrate-postgres-tables-to-hypertables
Command: npx skills add https://github.com/timescale/pg-aiguide --skill migrate-postgres-tables-to-hypertables-timescale

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps DB engineers plan and execute migrations of identified PostgreSQL tables to TimescaleDB hypertables with minimal downtime and validated results.

Core Features & Use Cases

  • Planning: partition column selection, chunk intervals, and PK/constraint adjustments for hypertables.
  • Migration execution strategies: in-place vs blue-green migration with test/validate steps.
  • Validation & compression: performance validation, chunk compression configuration, and monitoring.
  • Use Case: Migrate a large IoT time-series table with up-to-date queries and down-time reduction.

Quick Start

Identify hypertable candidates with companion skill and run the migration planning to generate a step-by-step migration plan. Then execute the plan in your environment with appropriate maintenance window.

Frequently Asked Questions about migrate-postgres-tables-to-hypertables

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate PostgreSQL tables to TimescaleDB hypertables with minimal downtime?

Migrating PostgreSQL tables to TimescaleDB hypertables requires selecting partition columns, defining chunk intervals, adjusting constraints, and applying a blue-green rollout strategy to minimize downtime. You generate an executable plan with step-by-step SQL commands and validation queries.

What is the best way to plan a blue-green migration for hypertables?

Planning a blue-green hypertable migration involves choosing in-place or blue-green execution strategies alongside test and validation steps. This approach generates a concrete migration plan with prerequisite checks, SQL commands, and validation queries to ensure a safe rollout.

How do I choose partition columns and chunk intervals for a TimescaleDB hypertable?

Choosing partition columns and chunk intervals for a TimescaleDB hypertable depends on your time-series data query patterns. The migration plan identifies suitable tables and recommends specific partition columns and intervals to optimize up-to-date queries.

Can I configure compression and validation for hypertables during migration?

Hypertable migration includes planning chunk compression configuration and performance validation. The generated plan provides SQL commands to enable compression and validation queries to monitor performance after migrating your PostgreSQL tables.

Do I need a TimescaleDB-enabled environment to execute a hypertable migration plan?

A TimescaleDB-enabled environment is required to execute the generated hypertable migration plan. The plan provides executable SQL commands and validation queries specifically designed to run within a TimescaleDB environment during a maintenance window.

Why does converting a PostgreSQL table to a hypertable require adjusting PK and UNIQUE constraints?

Converting a PostgreSQL table to a hypertable requires adjusting PK and UNIQUE constraints because TimescaleDB partitioning rules demand all unique constraints include the partition column. The migration plan identifies necessary constraint modifications.