Setup

Setup

Requirements

• Prisma 7 (prisma and @prisma/client >=7.0.0). This release targets Prisma 7 only — it relies on the v7 prisma.config.ts + prisma-client generator model.
• TimescaleDB-capable PostgreSQL for both your database and the Prisma shadow database (see Shadow database below). Locally, the timescale/timescaledb image works. Compression additionally needs TimescaleDB ≥ 2.18 (the columnstore API), and the Toolkit hyperfunctions need the timescaledb_toolkit extension (the timescale/timescaledb-ha image, or Tiger Cloud).
• A Prisma driver adapter at runtime (e.g. @prisma/adapter-pg).

Install

npm install prisma-extension-timescaledb
npm install -D prisma @prisma/client
npm install @prisma/adapter-pg            # or your preferred driver adapter

1. Connection settings (prisma.config.ts)

Prisma 7 moves connection settings out of schema.prisma into prisma.config.ts:

import "dotenv/config";
import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: "schema.prisma",
  migrations: { path: "migrations" },
  datasource: {
    url: process.env["DATABASE_URL"],
    // Must point at a TimescaleDB-capable database — see "Shadow database".
    shadowDatabaseUrl: process.env["SHADOW_DATABASE_URL"],
  },
});

# .env
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/app?schema=public"
SHADOW_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/shadow?schema=public"

2. Generate, then migrate

The order matters — run prisma generate before applying migrations so the emitted SQL reflects your current annotations:

npx prisma migrate dev --create-only --name init   # 1. Prisma's own CREATE TABLE migration
npx prisma generate                                # 2. our generator writes the timescale migrations + registry
npx prisma migrate deploy                          # 3. apply all migrations

The generator writes two fixed-name migrations that bracket your own, so ordering and idempotency are guaranteed:

Migration	Sorts	Contents
00000000000000_timescaledb_extension/	first	CREATE EXTENSION IF NOT EXISTS timescaledb — before any table DDL
99999999999999_timescaledb_objects/	last	create_hypertable(...) + continuous aggregates — after Prisma's CREATE TABLEs

All emitted SQL is idempotent (IF NOT EXISTS, if_not_exists => TRUE), so prisma migrate reset replays it from scratch with zero errors and zero manual steps.

Adding data

A hypertable is an ordinary Prisma model, so you insert with the normal Prisma API — no special calls needed. TimescaleDB routes rows into the right time chunks automatically.

await prisma.sensorReading.create({ data: { time: new Date(), deviceId: 1, temperature: 21.5 } });

await prisma.sensorReading.createMany({
  data: [
    { time: new Date("2026-06-15T10:05:00Z"), deviceId: 1, temperature: 20 },
    { time: new Date("2026-06-15T10:25:00Z"), deviceId: 1, temperature: 22 },
  ],
});

Shadow database

prisma migrate dev / migrate reset validate migrations against a temporary shadow database. Because the first migration runs CREATE EXTENSION timescaledb, the shadow database must live on a TimescaleDB-capable server — set shadowDatabaseUrl to a dedicated database on the same image.

Tiger Cloud caveat (honest limitation): Tiger Cloud rejects Prisma's auto-created shadow-database name, so a dedicated shadowDatabaseUrl is mandatory there. This package can't fully paper over that restriction.

A ready-made local setup (docker-compose.yml + an init script that creates the shadow database) ships in the repo.