DEV Community: Mahdi BEN RHOUMA

Prisma: Can't reach database server at database:5432 on M1

Mahdi BEN RHOUMA — Sun, 13 Sep 2026 17:08:08 +0000

TL;DR

If you see Can't reach database server at 'database':'5432' after moving your Docker Compose setup to an Apple Silicon Mac, the root cause is almost always a race condition: Prisma tries to connect before PostgreSQL finishes starting. Fix it by appending ?connect_timeout=300 to your DATABASE_URL. If that doesn't work, switch to Node 17 or 18 inside your container.

Symptom: PrismaClientInitializationError P1001: Can't reach database server at database:5432
Root cause: PostgreSQL isn't ready when Prisma first connects; M1 Docker startup is slower.
Fix: Add ?connect_timeout=300 to the connection string, or upgrade Node to v17+.
Verification: Run docker-compose exec postgres pg_isready and check the app logs.

The error, decoded

A developer on Stack Overflow reported this exact symptom after switching to an M1 Mac. Their docker-compose.yml defined a PostgreSQL service named test-postgres and a Next.js app using Prisma. The DATABASE_URL pointed to postgres://postgres:postgres@localhost:15432/postgres — note the host localhost and the mapped port 15432. When they ran docker-compose run --publish 5555:5555 next npx prisma migrate dev, Prisma threw:

Can't reach database server at `test-postgres`:`5432`

The same error appeared when the app tried to connect at runtime. The PostgreSQL container was running (visible in Docker Desktop), but the Prisma client inside the next container couldn't establish a TCP connection to the database hostname. The container logs also showed:

ERROR:  relation "_prisma_migrations" does not exist at character 126

That secondary error is a red herring — it means Prisma never got far enough to create the migrations table because the initial connection failed.

The setup is typical: two services in a Compose file, the app referencing the database by its service name (test-postgres), and a port mapping from 15432:5432 on the host. On Intel Macs and Linux, this works. On M1, it breaks.

Why M1 Macs break Docker networking for Prisma and PostgreSQL

Docker Desktop on Apple Silicon runs inside a lightweight Linux VM (using QEMU or Apple's Virtualization framework). The default bridge network and DNS resolution work, but the startup sequence is slower than on bare-metal Linux. PostgreSQL, especially when pulled as a multi-architecture image, may take a few extra seconds to initialize its data directory and begin accepting connections. Prisma, on the other hand, attempts to connect immediately when prisma migrate dev or the app starts.

The error Can't reach database server at 'database':'5432' is a Prisma-level timeout. Under the hood, Prisma uses the pg driver (or its own engine) to open a TCP socket. If the remote host isn't listening yet, the connection is refused, and Prisma retries a few times before giving up. On M1, the window between "container started" and "PostgreSQL ready" is wider, so the default retry window isn't enough.

The localhost hostname in the original DATABASE_URL is also a problem. Inside a container, localhost refers to the container itself, not the Docker host. The developer had mapped port 15432 on the host to 5432 in the PostgreSQL container, but the app container can't reach the host's localhost unless you use host.docker.internal (which requires Docker Desktop 4.x+ and may need extra configuration on M1). The correct approach is to use the Compose service name (test-postgres) and the container port (5432), because both containers are on the same Compose network.

The accepted answer on Stack Overflow (81 upvotes) identified the fix: add ?connect_timeout=300 to the connection string. This tells Prisma to wait up to 300 seconds for the database to become available, giving PostgreSQL enough time to finish starting. Other answers pointed to Node.js version differences: Node 16 on ARM sometimes exhibits slower DNS resolution or different socket behavior, and upgrading to Node 17 or 18 resolved the issue for some users.

The fix: Add a connection timeout to DATABASE_URL

The minimal change is to append ?connect_timeout=300 to your DATABASE_URL. If you're using the service name, the URL should look like this:

# Before (fails on M1)
DATABASE_URL="postgres://postgres:postgres@test-postgres:5432/postgres"

# After (works)
DATABASE_URL="postgres://postgres:postgres@test-postgres:5432/postgres?connect_timeout=300"

If you were mistakenly using localhost and a mapped port, switch to the service name and the internal port:

# Wrong: localhost inside a container points to the container itself
DATABASE_URL="postgres://postgres:postgres@localhost:15432/postgres"

# Correct: use the Compose service name and the container port
DATABASE_URL="postgres://postgres:postgres@test-postgres:5432/postgres?connect_timeout=300"

Update your docker-compose.yml to ensure the app depends on the database and uses the correct environment variable:

services:
  postgres:
    container_name: 'test-postgres'
    restart: unless-stopped
    image: 'postgres:13'
    ports:
      - '15432:5432'
    volumes:
      - 'pgdata:/var/lib/postgresql/data/'
    environment:
      POSTGRES_PASSWORD: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  next:
    build: .
    ports:
      - '3000:3000'
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: "postgres://postgres:postgres@test-postgres:5432/postgres?connect_timeout=300"

The healthcheck and depends_on with condition: service_healthy ensure the next container doesn't start until PostgreSQL is actually accepting connections. This eliminates the race condition entirely, even without the timeout parameter. However, keeping connect_timeout=300 adds an extra safety net.

Alternative fix: Upgrade Node.js

If the timeout alone doesn't resolve the issue, change the Node.js version in your Dockerfile. Several developers on the Stack Overflow thread reported that moving from Node 16 to 17 or 18 fixed the connection error. Update your Dockerfile:

# Before
FROM node:16

# After
FROM node:18

Rebuild the image with docker-compose build --no-cache and restart the stack. The newer Node version handles DNS resolution and socket creation differently on ARM, which can sidestep the underlying networking quirk.

If you're using Next.js, make sure your Prisma client is only instantiated in server components. The DATABASE_URL should never be exposed to the browser. See the Server and Client Boundary guide for how to keep data-fetching logic on the server.

Verify the fix

After applying the changes, bring the stack up:

docker-compose down -v   # clean slate
docker-compose up -d

Check that PostgreSQL is healthy:

docker-compose exec postgres pg_isready -U postgres

Expected output:

/var/run/postgresql:5432 - accepting connections

Now run the Prisma migration from the app container:

docker-compose exec next npx prisma migrate dev

You should see the migration apply without the Can't reach database server error. The app logs should show a successful database connection.

If you need to test raw connectivity from the app container, use nc (netcat):

docker-compose exec next sh -c "nc -zv test-postgres 5432"

Expected output:

test-postgres (172.18.0.2:5432) open

Once the connection is established, you can verify by running a simple query using psql (if you need to exit psql, see How to Exit psql: \q, exit, quit and Ctrl+D).

Two patterns that still trip you up

Pattern 1: Using `localhost` instead of the service name

Inside a Docker container, localhost is the container's own loopback interface. It does not resolve to the host machine or to another container. If your DATABASE_URL uses localhost, Prisma will try to connect to a PostgreSQL instance inside the same container, which doesn't exist. Always use the Compose service name (e.g., test-postgres) and the container port (5432). The host port mapping (15432:5432) is only for external access from your Mac.

Pattern 2: Not waiting for PostgreSQL to be ready

Even with connect_timeout=300, if your app starts before the database container is created, you'll still see the error. The depends_on with condition: service_healthy is the most reliable way to sequence startup. Without it, Docker only waits for the container to start, not for the service inside to be ready. Combine the healthcheck with the timeout for a bulletproof setup.

If you're using Supabase as your database provider, you might also run into connection timeouts; check out Why Your Supabase Queries Are Slow (And How to Fix) for performance tuning. When you're ready to run migrations, ensure your schema doesn't have foreign key issues that could cause constraint violations; see Fix Foreign Key Constraint Violation in Supabase (23503) for a common pitfall.

FAQ

Why does Prisma fail with 'Can't reach database server at database:5432' on M1 Macs?

On Apple Silicon, Docker Desktop runs inside a VM and PostgreSQL initialization can be slower. Prisma attempts to connect before the database is ready, causing a P1001 error. Adding ?connect_timeout=300 to the DATABASE_URL gives Prisma more time to retry and usually resolves the issue.

Does changing the Node.js version fix the Prisma connection error on M1?

Yes, some developers have resolved the error by upgrading from Node 16 to Node 17 or 18. The newer versions handle DNS resolution and networking differently inside Docker on ARM, which can eliminate the connection timeout.

Can I use `host.docker.internal` instead of the service name?

host.docker.internal resolves to the host machine from inside a container. It works on Docker Desktop for Mac, but on M1 it may require Docker Desktop 4.x+ and the --add-host flag in some configurations. Using the Compose service name is simpler and more portable across environments.

How do I test if my database is reachable from inside the container?

Use docker-compose exec <service> pg_isready -U postgres for PostgreSQL, or nc -zv <host> <port> for a generic TCP check. Both commands confirm whether the database is listening before Prisma tries to connect.

Originally published at https://www.iloveblogs.blog

Why useEffect runs twice in Next.js dev

Mahdi BEN RHOUMA — Sat, 12 Sep 2026 22:45:00 +0000

You add a console.log, start next dev, and the effect fires twice. Sometimes that means two fetches, two analytics pings, or two subscriptions.

The root cause is usually not Next.js. React documents this behavior directly: when Strict Mode is on, React runs one extra development-only setup and cleanup cycle before the real setup.

That means the question is not "how do I stop React from doing that?" The question is "why does my effect break when React stress-tests it?"

The broken effect pattern

This is the classic example:

'use client'

import { useEffect, useState } from 'react'

export default function UserList() {
  const [users, setUsers] = useState<string[]>([])

  useEffect(() => {
    fetch('/api/users')
      .then((res) => res.json())
      .then((data) => setUsers(data))
  }, [])

  return <pre>{JSON.stringify(users, null, 2)}</pre>
}

In development, you may see two requests. The effect has no cleanup and no cancellation, so the extra Strict Mode cycle reveals that weakness immediately.

A safer effect

'use client'

import { useEffect, useState } from 'react'

export default function UserList() {
  const [users, setUsers] = useState<string[]>([])

  useEffect(() => {
    const controller = new AbortController()

    async function loadUsers() {
      const res = await fetch('/api/users', { signal: controller.signal })
      const data = await res.json()
      setUsers(data)
    }

    loadUsers().catch((error) => {
      if (error.name !== 'AbortError') throw error
    })

    return () => controller.abort()
  }, [])

  return <pre>{JSON.stringify(users, null, 2)}</pre>
}

Now the cleanup mirrors the setup. That is exactly what the React docs want Strict Mode to test.

What React is actually telling you

If a second setup+cleanup cycle causes visible breakage, your effect is probably doing one of these:

opening a subscription and never unsubscribing
firing a network request with no cancellation
mutating global state during setup
using an effect for something that should happen in response to a user event instead

The better fix in many Next.js apps: move the fetch to the server

In App Router projects, a lot of client useEffect fetching should not be client fetching at all.

If the data is needed to render the page, fetch it in the Server Component page or loader path first. That removes the whole class of duplicate dev-fetch confusion.

// app/users/page.tsx
export default async function Page() {
  const res = await fetch('https://example.com/api/users', {
    cache: 'no-store',
  })
  const users = await res.json()

  return <pre>{JSON.stringify(users, null, 2)}</pre>
}

That is not always the right move, but it is often the right default in modern Next.js.

What not to do first

Do not start by disabling Strict Mode just because the effect is noisy. If the extra cycle exposes a bug, production can still hit the same bug through remounts, navigation, interrupted renders, or subscription leaks.

Use Strict Mode as the warning sign it is meant to be.

When a `useRef` guard is acceptable

For genuinely one-off client actions that cannot be moved elsewhere, a guard can be acceptable:

'use client'

import { useEffect, useRef } from 'react'

export default function ClientPing() {
  const sent = useRef(false)

  useEffect(() => {
    if (sent.current) return
    sent.current = true
    void fetch('/api/ping', { method: 'POST' })
  }, [])

  return null
}

This is a tactical fix, not the first tool to reach for. Prefer clean setup/cleanup or server-side data flow when possible.

For related React and App Router debugging:

References

Fix useEffect Running Twice in React 18 — Strict Mode

Originally published at https://www.iloveblogs.blog

Extract date (yyyy/mm/dd) from a timestamp in PostgreSQL

Mahdi BEN RHOUMA — Sat, 12 Sep 2026 22:44:54 +0000

The original question asks how to extract the yyyy/mm/dd date part from a PostgreSQL timestamp. The accepted answer shows a to_char/to_date round-trip:

This write-up is grounded in the original Stack Overflow question (434 upvotes, 968,809 views).

SELECT to_char(now(), 'YYYY/MM/DD');

SELECT to_date(to_char(now(), 'YYYY/MM/DD'), 'YYYY/MM/DD');

That works, but for a native DATE value you do not need the text round-trip. Use the cast operator :::

SELECT now()::date;

A single colon is not valid PostgreSQL. Write timestamp::date, not timestamp:date.

Accepted answer: to_char(now(), 'YYYY/MM/DD') formats; to_date(to_char(...), 'YYYY/MM/DD') parses the text back to date.
Direct fix: timestamp::date returns a native DATE without text conversion.
Formatting: Use to_char(timestamp, 'YYYY/MM/DD') only when you need text output.
Verification: Check the actual type with pg_typeof() and the column type with \d.

The cast returns the full date, not just the year

timestamp::date and date(timestamp) both return PostgreSQL's native DATE type. That type stores year, month, and day. The default text output is YYYY-MM-DD under the standard DateStyle setting. If another client displays only 2011, the client is not showing the full value. Verify in psql:

SELECT ts, ts::date AS event_date
FROM events
WHERE id = 1;

         ts          | event_date
---------------------+------------
 2011-05-26 09:00:00 | 2011-05-26

Use SELECT pg_typeof(ts::date); to confirm the result is date.

The accepted answer and the direct cast

The accepted answer on the original thread uses a text format/parse sequence:

SELECT to_char(now(), 'YYYY/MM/DD');

SELECT to_date(to_char(now(), 'YYYY/MM/DD'), 'YYYY/MM/DD');

The first statement returns text in the requested yyyy/mm/dd format. The second parses that text back into a date value. This works, but it is an unnecessary round-trip when you only need a native DATE.

Use the direct cast for a native DATE

SELECT ts::date AS event_date
FROM events
WHERE id = 1;

You can also use the SQL-standard function syntax:

SELECT date(ts) AS event_date
FROM events
WHERE id = 1;

Both return a DATE type, ready for insertion into a DATE column. They truncate the time component without rounding.

Use `to_char` only for display

If you need the exact yyyy/mm/dd string, use to_char directly on the timestamp:

SELECT to_char(ts, 'YYYY/MM/DD') AS formatted_date
FROM events
WHERE id = 1;

Keep the column as DATE for storage and sorting; format only when you display the result.

`date_trunc` is not a date extraction

date_trunc('day', ts) returns a timestamp truncated to midnight, not a DATE. It preserves the timestamp type and, for timestamptz, the time zone. Use it only when the target column expects a timestamp and you need to keep the time component at zero. For a plain DATE, use ::date.

For the full syntax and behavior, see the PostgreSQL date/time functions documentation.

Time-zone note: ::date on a timestamptz returns the date in the session’s time zone. If the server is UTC but the data represents New York events, the date can shift by one day. Set the time zone first: SET TIME ZONE 'America/New_York'; then run the cast.

Verify the extracted date

After applying the fix, confirmation is a three-step check: type, value, and insertion.

1. Confirm the column type

Use the \d command in psql to inspect the table. If you’re coming from a MySQL background, you may be used to DESCRIBE. PostgreSQL uses \d instead; we have a full guide on the \d equivalent if you need it.

psql -d yourdb -c "\d events"

 Column     | Type              | Modifiers
------------+-------------------+-----------
 id         | integer           | not null
 ts         | timestamp         |
 event_date | date              |

Look for the date type on the new column.

2. Check the actual value

Query the raw column and force the output with explicit formatting for a sanity check:

SELECT
  ts,
  event_date,
  to_char(event_date, 'YYYY/MM/DD') AS formatted_date
FROM events;

You should see a line like 2011-05-26 | 2011/05/26, proving both the type and the correct day.

3. Insert the value into a `DATE` column

Create a tiny scratch table to simulate the target environment:

CREATE TEMP TABLE test_insert (testd DATE);
INSERT INTO test_insert (testd)
  SELECT ts::date FROM events WHERE id = 1;
SELECT * FROM test_insert;

   testd
------------
 2011-05-26

If the insert succeeds, ::date produced a proper DATE value. When you’re done, you can clean up safely — the approach for dropping test tables without losing production data is covered in How to Drop All Tables in PostgreSQL Safely.

Three common pitfalls during verification

Client shows only 2011 – Verify in psql or run SELECT event_date::text; to see the full string. The cast itself does not truncate the year.
Date shift after cast – Verify the session time zone (SHOW timezone;). If it differs from the data’s origin, set it explicitly as shown above.
“Cannot insert NULL” errors – If source timestamps are nullable, filter them: WHERE ts IS NOT NULL.

FAQ

Why can’t I just do `to_date(to_char(ts, 'YYYY/MM/DD'), 'YYYY/MM/DD')`?

That text round-trip converts the timestamp to text, parses the text back into a date, and can never produce a different result than ts::date — but it costs extra CPU, breaks any plan-time optimisation, and prevents the use of indexes on the expression. Use the direct cast instead.

For example, EXPLAIN SELECT * FROM events WHERE to_date(to_char(event_ts, 'YYYY/MM/DD'), 'YYYY/MM/DD') = '2025-01-15'; shows a sequential scan, while SELECT * FROM events WHERE event_ts::date = '2025-01-15'; can use an index on the expression (event_ts::date). The extra text parsing and function calls also add measurable CPU overhead on large tables.

Does `::date` work in all PostgreSQL versions?

Yes, the cast to date from timestamp has been available since at least PostgreSQL 9.0. All currently supported versions (14, 15, 16, 17, 18) include it. If you are unsure which version you’re running, check this short guide on finding your PostgreSQL version.

Run SELECT version(); in psql — you’ll see output like PostgreSQL 16.3 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.2.1, 64-bit. The ::date cast works identically in every major release back to 9.0, so there’s no compatibility risk.

How do I output the date exactly as `yyyy/mm/dd` without losing the DATE type?

The output format is a presentation layer concern. Keep the column as DATE and use to_char(event_date, 'YYYY/MM/DD') only when you need to display it to a user or generate a report. That way you retain the native type for ordering, indexing, and date arithmetic.

For instance, define a table with a proper DATE column:

CREATE TABLE events (event_date DATE);
INSERT INTO events VALUES ('2025-02-01');

Now query using formatting only for display:

SELECT to_char(event_date, 'YYYY/MM/DD') AS formatted_date FROM events;

That returns 2025/02/01, but the underlying column remains a DATE — so range filters like WHERE event_date BETWEEN '2025-02-01' AND '2025-02-28' use btree indexes efficiently. This avoids the cost of casting text columns on every scan.

Originally published at https://www.iloveblogs.blog

Zero-Downtime Supabase Migrations: Expand/Contract (2026)

Mahdi BEN RHOUMA — Sat, 12 Sep 2026 16:43:54 +0000

Database migrations feel harmless when your app is small. You add a column, change a type, rename a field, push to production, and everything works.

Then you get real users.

Now a migration can break live traffic in three different ways:

Old Vercel functions are still running while new code is deploying.
Postgres takes a lock that blocks reads or writes on a hot table.
Supabase RLS policies, generated TypeScript types, or API assumptions change before the app is ready.

Zero downtime means users keep reading and writing while the schema changes underneath them. It does not mean every migration is instant. It means every migration is backward compatible, observable, and reversible enough that a failed deploy does not become an outage.

This guide gives you a production pattern for Supabase Postgres:

Expand the schema without breaking old code.
Deploy code that understands both old and new shapes.
Backfill existing rows in small batches.
Validate constraints without blocking normal traffic.
Switch reads and writes to the new shape.
Contract the old schema in a later release.
Gate all of it in CI.

If you already read the general Supabase migration strategies guide, this is the operational playbook. It is narrower, more opinionated, and built for production rollouts.

The Mental Model

In a zero-downtime release, database schema and application code move at different speeds.

On Vercel, a production deploy is a rolling change. Some requests can still hit old serverless functions while other requests hit the new build. Supabase Postgres is shared by both. That means the database must support both versions for a while.

Use this sequence:

Phase	Database	Application	Goal
Expand	Add new nullable columns, tables, policies, indexes	Old code still works	Add capacity for the new behavior
Bridge	Keep old and new fields in sync	New code writes both, reads with fallback	Make both versions safe
Backfill	Fill old rows gradually	Code tolerates mixed data	Move historical data
Validate	Add or validate constraints	Code handles validation failures	Prove data is safe
Switch	Read from the new shape	New code no longer depends on old shape	Complete behavior change
Contract	Drop old columns, triggers, policies	Only new code exists	Clean up debt

The important rule: do not expand and contract in the same release.

A destructive migration is not a migration. It is a coordinated product rollout. Treat it that way.

Supabase Migration Workflow

Supabase migrations are SQL files in supabase/migrations. Create them with the CLI:

npx supabase migration new add_account_billing_state

Apply and test locally:

npx supabase start
npx supabase db reset

For remote projects, Supabase tracks applied migrations in supabase_migrations.schema_migrations. Use a dry run before production:

npx supabase db push --dry-run

And inspect history when something feels off:

npx supabase migration list --linked

Two rules keep teams out of trouble:

Do not change production schema through the Table Editor or SQL Editor once migrations own the schema.
Do not edit a migration file after it has been applied to a shared environment.

If remote history and local files drift, use supabase migration repair deliberately. Do not "fix" drift by deleting migrations until production happens to accept the next push.

Set Lock and Statement Timeouts

Every production migration should fail quickly when it cannot get a lock. A blocked migration can block app traffic, and a blocked app can turn into a support incident.

Start risky migration files with timeouts:

set lock_timeout = '5s';
set statement_timeout = '5min';

lock_timeout limits how long Postgres waits to acquire a lock. statement_timeout limits total execution time for a statement. The exact values depend on the table, but the philosophy is consistent: a migration that cannot acquire a safe lock should fail, not wait behind user traffic forever.

For large backfills, do not run one huge UPDATE. Use batches. More on that below.

Safe Change 1: Add a New Nullable Column

Adding a nullable column is the safest expand migration.

set lock_timeout = '5s';
set statement_timeout = '2min';

alter table public.accounts
  add column if not exists billing_status text;

Old code ignores the column. New code can start writing it. Existing rows are null, so reads must tolerate missing values.

If you need a default for new rows, set it separately:

alter table public.accounts
  alter column billing_status set default 'trialing';

Postgres can add a column with a constant default efficiently on modern versions, but volatile defaults and generated columns can still rewrite the table. When in doubt on a hot table, add the column first, backfill, then set defaults and constraints later.

Safe Change 2: Rename a Column

The dangerous version:

alter table public.profiles rename column name to display_name;

That can break old code instantly. A live app may still read name, while new code reads display_name. The safer expand/contract pattern takes multiple releases.

Release 1: Expand

set lock_timeout = '5s';
set statement_timeout = '2min';

alter table public.profiles
  add column if not exists display_name text;

Release 2: Bridge in App Code

New writes should fill both columns:

await supabase
  .from('profiles')
  .update({
    name: input.displayName,
    display_name: input.displayName,
  })
  .eq('id', userId)

Reads should prefer the new column but tolerate old rows:

const profileName = profile.display_name ?? profile.name ?? 'Someone'

Release 3: Backfill

Create a batch function:

create or replace function public.backfill_profile_display_names(batch_size integer default 1000)
returns integer
language plpgsql
security definer
set search_path = public
as $$
declare
  updated_count integer;
begin
  with batch as (
    select id
    from public.profiles
    where display_name is null
      and name is not null
    order by id
    limit batch_size
    for update skip locked
  )
  update public.profiles p
  set display_name = p.name
  from batch
  where p.id = batch.id;

  get diagnostics updated_count = row_count;
  return updated_count;
end;
$$;

Run it repeatedly from a script, admin route, or scheduled job until it returns 0:

select public.backfill_profile_display_names(1000);

FOR UPDATE SKIP LOCKED lets concurrent workers avoid fighting over the same rows. Keep batches small enough that each transaction is boring.

Release 4: Validate

Before you make the new column required, prove the data is ready:

select count(*) as missing_display_names
from public.profiles
where display_name is null;

Then add a check constraint without immediately validating existing rows:

alter table public.profiles
  add constraint profiles_display_name_present
  check (display_name is not null)
  not valid;

Validate in a separate migration:

alter table public.profiles
  validate constraint profiles_display_name_present;

Postgres still scans the table during validation, but it uses a less aggressive lock than adding the constraint in the fully validated form up front.

Release 5: Contract

Only after old code is gone:

set lock_timeout = '5s';
set statement_timeout = '2min';

alter table public.profiles
  drop column if exists name;

This cleanup can wait weeks. Shipping cleanup late is cheaper than causing downtime early.

Safe Change 3: Add a Required Foreign Key

Foreign keys on large tables can be expensive if you validate them immediately. Use NOT VALID first.

set lock_timeout = '5s';
set statement_timeout = '5min';

alter table public.orders
  add column if not exists customer_id uuid;

alter table public.orders
  add constraint orders_customer_id_fkey
  foreign key (customer_id)
  references public.customers(id)
  not valid;

Now backfill customer_id. Once old rows are clean:

alter table public.orders
  validate constraint orders_customer_id_fkey;

If you later need customer_id to be non-null, use the same staged pattern:

alter table public.orders
  add constraint orders_customer_id_present
  check (customer_id is not null)
  not valid;

alter table public.orders
  validate constraint orders_customer_id_present;

Then set NOT NULL in a small final migration after you have measured that it completes quickly:

set lock_timeout = '5s';
set statement_timeout = '2min';

alter table public.orders
  alter column customer_id set not null;

If that lock cannot be acquired in production, it should fail. The validated check constraint still protects data while you retry during a lower-traffic window.

Safe Change 4: Change a Column Type

Changing a column type in place can rewrite the table and rebuild indexes. For hot tables, use a new column.

Example: moving from text status values to a stricter enum.

create type public.invoice_status as enum (
  'draft',
  'open',
  'paid',
  'void',
  'uncollectible'
);

alter table public.invoices
  add column if not exists status_v2 public.invoice_status;

Bridge writes:

const statusV2 = normalizeInvoiceStatus(input.status)

await supabase
  .from('invoices')
  .update({
    status: input.status,
    status_v2: statusV2,
  })
  .eq('id', invoiceId)

Backfill:

create or replace function public.backfill_invoice_status_v2(batch_size integer default 1000)
returns integer
language plpgsql
security definer
set search_path = public
as $$
declare
  updated_count integer;
begin
  with batch as (
    select id
    from public.invoices
    where status_v2 is null
    order by id
    limit batch_size
    for update skip locked
  )
  update public.invoices i
  set status_v2 = case lower(i.status)
    when 'draft' then 'draft'::public.invoice_status
    when 'open' then 'open'::public.invoice_status
    when 'paid' then 'paid'::public.invoice_status
    when 'void' then 'void'::public.invoice_status
    else 'uncollectible'::public.invoice_status
  end
  from batch
  where i.id = batch.id;

  get diagnostics updated_count = row_count;
  return updated_count;
end;
$$;

Switch reads to status_v2, keep the old status column until you are certain no old code writes it, then contract.

Safe Change 5: Create Large Indexes

Postgres regular index creation can block writes. CREATE INDEX CONCURRENTLY avoids blocking inserts, updates, and deletes, but PostgreSQL forbids it inside a transaction block.

That matters because migration runners differ in how they execute SQL files.

For small tables or new tables, a normal index inside a migration is fine:

create index if not exists orders_tenant_created_at_idx
  on public.orders (tenant_id, created_at desc);

For a large hot table, run the concurrent index through a non-transactional path such as a carefully controlled psql maintenance step:

psql "$DATABASE_URL" \
  -v ON_ERROR_STOP=1 \
  -c "set lock_timeout = '5s'" \
  -c "set statement_timeout = '30min'" \
  -c "create index concurrently if not exists orders_tenant_created_at_idx on public.orders (tenant_id, created_at desc)"

Keep it as its own deployment step. Do not hide it inside an unrelated app deploy. If it fails halfway, inspect invalid indexes before retrying:

select
  schemaname,
  relname as table_name,
  indexrelname as index_name
from pg_stat_user_indexes
join pg_index on pg_index.indexrelid = pg_stat_user_indexes.indexrelid
where not pg_index.indisvalid;

Then drop the invalid index concurrently and retry:

drop index concurrently if exists public.orders_tenant_created_at_idx;

RLS Changes Are Schema Changes

RLS policy edits can break production just as hard as column changes. Treat policies as part of the expand/contract rollout.

Suppose you are moving from user-owned rows to organization-owned rows.

Expand

Add the new column and membership policy path:

alter table public.projects
  add column if not exists organization_id uuid;

create policy "Members can read organization projects"
on public.projects
for select
using (
  exists (
    select 1
    from public.memberships
    where memberships.organization_id = projects.organization_id
      and memberships.user_id = auth.uid()
  )
);

Do not drop the old policy yet:

-- Keep this until all rows have organization_id and app reads use org scope.
-- create policy "Users can read own projects" ...

Bridge

New code writes organization_id, but old rows may still rely on user_id. Reads should scope by organization when available and fall back only where explicitly intended.

Contract

After backfill and app rollout:

drop policy if exists "Users can read own projects" on public.projects;

Before contract, run role-impersonation tests. This is a perfect companion to the Supabase RLS policy design guide.

Type Generation Timing

Generated types can accidentally force a breaking change too early.

The safe sequence:

Add expand migration.
Generate types.
Update app code to accept both old and new fields.
Deploy.
Backfill and validate.
Switch code to new field.
Contract old schema.
Generate types again and remove old field references.

Generate Supabase types after migrations are applied to the environment you are targeting:

npx supabase gen types typescript --linked > src/types/database.types.ts

In CI, fail if generated types drift from committed types:

npx supabase gen types typescript --linked > /tmp/database.types.ts
diff -u src/types/database.types.ts /tmp/database.types.ts

That catches the class of bug where a developer changes schema locally but forgets to commit regenerated types.

GitHub Actions CI

This workflow has three jobs:

Lint and test the app.
Validate local migrations by resetting a local Supabase stack.
Dry-run and push migrations to production only on main.

name: Supabase Production Migrations

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  app-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci
      - run: npm run lint
      - run: npm test -- --runInBand

  migration-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: supabase/setup-cli@v1
        with:
          version: latest

      - run: supabase start
      - run: supabase db reset
      - run: supabase migration list --local

  deploy-migrations:
    if: github.ref == 'refs/heads/main'
    needs:
      - app-tests
      - migration-tests
    runs-on: ubuntu-latest
    environment: production
    concurrency:
      group: production-supabase-migrations
      cancel-in-progress: false

    steps:
      - uses: actions/checkout@v4

      - uses: supabase/setup-cli@v1
        with:
          version: latest

      - name: Link Supabase project
        run: supabase link --project-ref "$SUPABASE_PROJECT_ID"
        env:
          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
          SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}
          SUPABASE_PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }}

      - name: Dry-run migrations
        run: supabase db push --dry-run --password "$SUPABASE_DB_PASSWORD"
        env:
          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
          SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}

      - name: Push migrations
        run: supabase db push --password "$SUPABASE_DB_PASSWORD"
        env:
          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
          SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}

Use a GitHub environment approval for production. Schema changes deserve a human checkpoint, especially when they touch hot tables.

For a full deployment pipeline, pair this with the Next.js and Supabase CI/CD guide.

Downloadable Assets

Use the checklist version when you want this process in a pull request template, runbook, or team migration review:

The article examples are intentionally copy/pasteable: the safe rename rollout, batch backfill function, NOT VALID constraint flow, concurrent index maintenance command, and GitHub Actions workflow can each stand alone in a real repo.

Add a Migration Safety Linter

You can catch dangerous SQL with a small script before it reaches production.

// scripts/check-migrations.js
import fs from 'node:fs'
import path from 'node:path'

const migrationsDir = path.join(process.cwd(), 'supabase/migrations')
const riskyPatterns = [
  {
    pattern: /\bdrop\s+column\b/i,
    message: 'DROP COLUMN must be a contract migration with a rollback note.',
  },
  {
    pattern: /\brename\s+column\b/i,
    message: 'RENAME COLUMN is not safe for rolling deploys. Use expand/contract.',
  },
  {
    pattern: /\balter\s+column\b[\s\S]*\bset\s+not\s+null\b/i,
    message: 'SET NOT NULL needs backfill plus validation proof.',
  },
  {
    pattern: /\bcreate\s+index\s+(?!concurrently)/i,
    message: 'Large-table indexes should use a reviewed index plan.',
  },
]

let failed = false

for (const fileName of fs.readdirSync(migrationsDir)) {
  if (!fileName.endsWith('.sql')) continue

  const fullPath = path.join(migrationsDir, fileName)
  const sql = fs.readFileSync(fullPath, 'utf8')

  for (const rule of riskyPatterns) {
    if (rule.pattern.test(sql)) {
      console.error(`${fileName}: ${rule.message}`)
      failed = true
    }
  }
}

if (failed) process.exit(1)

Add it to CI:

- run: node scripts/check-migrations.js

This script is intentionally conservative. It should start conversations, not replace review. Add an allowlist comment convention if your team needs exceptions:

-- migration-safety-reviewed: contract release 2026-05-23
alter table public.profiles drop column if exists name;

Rollback Strategy

Most production database rollbacks should be forward fixes, not time travel.

Rolling back is a decision, not a reflex — the PostgreSQL migration rollback playbook walks through the forward-fix-versus-revert call, lock-aware sequencing, and verification, so you pick the safer path instead of the faster-looking one.

Use this order:

Roll back application code first.
Keep expand migrations in place if they are backward compatible.
Stop backfill workers if they are causing load.
Add a forward migration to restore compatibility if needed.
Use backups or point-in-time recovery only for disaster recovery.

Example: a new app release starts reading display_name, but a subset of rows were not backfilled. Roll back the app to read display_name ?? name, stop the release, run the missing backfill, then redeploy.

Do not drop the new column as your first move. Dropping data to roll back code is how a recoverable deploy turns into a data incident.

Supabase backups are your emergency option. Daily backups and point-in-time recovery are operational safety nets, but restore operations can involve downtime and data loss windows. They are not a normal deploy rollback mechanism.

Migration Safety Checklist

Copy this into the pull request description for any production migration, or use the downloadable checklist as a reusable PR template:

## Migration Safety Checklist

- [ ] This migration has been tested with `supabase db reset`.
- [ ] This migration has been dry-run against the target project.
- [ ] The app code is backward compatible with the old and new schema.
- [ ] This migration does not rename or drop columns needed by the current deploy.
- [ ] Hot-table operations use `lock_timeout` and `statement_timeout`.
- [ ] Large backfills run in batches, not one giant `UPDATE`.
- [ ] New foreign keys or checks use `NOT VALID` before validation.
- [ ] Large indexes have a reviewed concurrent index plan.
- [ ] RLS policies support both old and new access paths during rollout.
- [ ] Supabase generated types are updated in the same PR when needed.
- [ ] Rollback plan is documented.
- [ ] Monitoring owner is named for the deploy window.

For higher-risk migrations, add two more lines:

- [ ] We confirmed the latest usable backup or PITR restore point.
- [ ] We rehearsed the rollback in staging.

Example Rollout: Add Team Billing

Here is the complete expand/contract pattern in one realistic feature.

You are moving billing from individual users to organizations. Existing tables have user_id. New billing tables need organization_id.

Migration 1: Expand

set lock_timeout = '5s';
set statement_timeout = '5min';

alter table public.subscriptions
  add column if not exists organization_id uuid;

alter table public.subscriptions
  add constraint subscriptions_organization_id_fkey
  foreign key (organization_id)
  references public.organizations(id)
  not valid;

create index if not exists subscriptions_organization_id_idx
  on public.subscriptions (organization_id);

Deploy 1: Bridge

New code writes both:

await supabase.from('subscriptions').insert({
  user_id: userId,
  organization_id: organizationId,
  stripe_customer_id: customerId,
  status: 'trialing',
})

Reads use the new organization scope when present, but old rows still work:

const query = supabase
  .from('subscriptions')
  .select('*')
  .or(`organization_id.eq.${organizationId},user_id.eq.${userId}`)

Backfill

create or replace function public.backfill_subscription_organizations(batch_size integer default 500)
returns integer
language plpgsql
security definer
set search_path = public
as $$
declare
  updated_count integer;
begin
  with batch as (
    select s.id, m.organization_id
    from public.subscriptions s
    join public.memberships m on m.user_id = s.user_id
    where s.organization_id is null
    order by s.id
    limit batch_size
    for update skip locked
  )
  update public.subscriptions s
  set organization_id = batch.organization_id
  from batch
  where s.id = batch.id;

  get diagnostics updated_count = row_count;
  return updated_count;
end;
$$;

Run:

select public.backfill_subscription_organizations(500);

Migration 2: Validate

set lock_timeout = '5s';
set statement_timeout = '10min';

alter table public.subscriptions
  validate constraint subscriptions_organization_id_fkey;

alter table public.subscriptions
  add constraint subscriptions_organization_id_present
  check (organization_id is not null)
  not valid;

alter table public.subscriptions
  validate constraint subscriptions_organization_id_present;

Deploy 2: Switch

Now reads use only organization_id. Keep user_id writes for one more deploy if old code may still exist.

Migration 3: Contract

set lock_timeout = '5s';
set statement_timeout = '2min';

alter table public.subscriptions
  drop constraint if exists subscriptions_organization_id_present;

alter table public.subscriptions
  alter column organization_id set not null;

alter table public.subscriptions
  drop column if exists user_id;

This final migration is intentionally boring because all the risky work happened earlier.

What Not to Do

Avoid these in live Supabase projects:

Renaming a column in the same deploy that changes app code.
Dropping a column because TypeScript no longer references it.
Running one giant backfill update on a hot table.
Adding a foreign key to a large table without NOT VALID.
Adding strict RLS policies before data and code are ready.
Trusting local migration success as proof of production safety.
Using a backup restore as a normal rollback plan.

The most dangerous migrations are the ones that look clean in a diff.

Reference Docs

Keep these open while designing production migrations:

The Durable Pattern

Zero-downtime migrations are mostly discipline.

Add before you use. Write both before you read new. Backfill before you require. Validate before you enforce. Drop only after the old code is gone.

That pattern is slower than a one-line ALTER TABLE. It is also the difference between a routine release and a production incident.

Related Incidents

These production incidents are directly traceable to the migration patterns covered in this guide:

INC-009: Migration succeeds in staging and fails in prod — production data volume exposed a lock timeout that staging never triggered
INC-010: Rollback blocks writes for too long — revert migration acquired a table lock during peak traffic

Adjacent Guides

Originally published at https://www.iloveblogs.blog

Window is not defined in Next.js – 2026 Fix for React Apps

Mahdi BEN RHOUMA — Sat, 12 Sep 2026 16:43:44 +0000

You import a component that touches window — a map library, a charting library, a custom script — run npm run dev or deploy to Vercel, and the build dies with:

ReferenceError: window is not defined
    at Object.<anonymous> (/src/components/Map.tsx:12:15)
    at Module._compile (node:internal/modules/cjs/loader:1126:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1180:10)
    at Module.load (node:internal/modules/cjs/loader:1004:32)
    at Function.Module._load (node:internal/modules/cjs/loader:839:12)
    at next/dist/build/webpack/loaders/next-client-pages-loader.js:274:23

The behavior is the same across local development, preview deployments, and production builds: the code runs during server‑side rendering, where window doesn't exist. The fix is to guard the reference or move the code into a client‑only context — this guide covers both patterns, plus the two awkward cases (utility modules and libraries that can't be lazy‑loaded).

The crash happens at import time, not render time

Next.js executes every page component on the server for the initial request. During that phase the JavaScript environment is Node.js, which does not provide a window global. Any top‑level reference to window—whether you call window.innerWidth, window.location, or a library that accesses document—is evaluated as soon as the module is imported. Because the import happens before the component is rendered, the server throws a ReferenceError and the build fails.

The problem is amplified when you use third‑party libraries that assume a browser context. For instance, many map or chart libraries read window.devicePixelRatio at import time. If you bundle them directly in a page component, Next.js will try to evaluate that code on the server, triggering the error.

The relevant code path is:

// src/components/Map.tsx
import React from 'react';
import L from 'leaflet'; // leaflets reads window at import time

export default function Map() {
  const map = L.map('map'); // <-- window is accessed here
  return <div id="map" style={{ height: 400 }} />;
}

When the server imports leaflet, the library immediately accesses window, causing the crash.

Three ways to keep `window` out of the server bundle

Guard the reference with typeof window !== 'undefined'.
Move the code into a useEffect hook so it only runs after the component mounts in the browser.
Load the library dynamically with next/dynamic and disable SSR for that component.

Dynamic import with `ssr: false` (the approach I'd pick)

Below is the minimal change that resolves the error for most cases. I chose the dynamic import approach because it isolates the entire component from server rendering, keeping the bundle size small and avoiding any accidental window access.

// src/components/Map.tsx
'use client';

import React from 'react';
import dynamic from 'next/dynamic';

// Dynamically import the map component without SSR
const LeafletMap = dynamic(() => import('../lib/LeafletMap'), {
  ssr: false,
  loading: () => <p>Loading map…</p>,
});

export default function Map() {
  return (
    <div style=>
      <LeafletMap />
    </div>
  );
}

And the dynamically loaded module:

// src/lib/LeafletMap.tsx
import React, { useEffect, useRef } from 'react';
import L from 'leaflet';
import 'leaflet/dist/leaflet.css';

export default function LeafletMap() {
  const mapContainer = useRef(null);

  useEffect(() => {
    if (!mapContainer.current) return;

    const map = L.map(mapContainer.current).setView([51.505, -0.09], 13);
    L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
      attribution: '&copy; OpenStreetMap contributors',
    }).addTo(map);
  }, []);

  return <div ref={mapContainer} style={{ height: 400 }} />;
}

That single change addresses the cause because the leaflet import now happens only in the browser, after the server has already sent the HTML. The ssr: false flag tells Next.js to skip this component during the server pass, eliminating the window reference entirely.

To apply it to your own component:

Create a new file src/lib/LeafletMap.tsx (or whatever library you’re using) and paste the second snippet above.
Replace the original import in src/components/Map.tsx with the dynamic import shown in the first snippet.
Remove any top‑level window usage from the original component. If you still need a small check, wrap it:

   if (typeof window !== 'undefined') {
     // browser‑only code
   }

Save the files and restart the dev server (npm run dev). The error should disappear.

The `typeof window` guard inside `useEffect`

If you prefer a guard instead of dynamic import, the pattern looks like this:

// src/components/Chart.tsx
import React, { useEffect } from 'react';
import { Chart, registerables } from 'chart.js';
Chart.register(...registerables);

export default function ChartComponent() {
  useEffect(() => {
    if (typeof window === 'undefined') return; // guard

    const ctx = document.getElementById('myChart') as HTMLCanvasElement;
    new Chart(ctx, {
      type: 'bar',
      data: { /* … */ },
    });
  }, []);

  return <canvas id="myChart" />;
}

Both approaches are valid; pick the one that matches your project's style.

Restart the dev server and read the log

Run the development server again:

npm run dev

You should see the usual Next.js startup log without any ReferenceError:

> next dev
  ▲ Next.js 14.x.x
  - Local:        http://localhost:3000
  - Network:      http://0.0.0.0:3000

 ✓ Starting...
 ✓ Ready in 1234ms

Open http://localhost:3000 in a browser. The page that previously crashed now renders the map (or chart) correctly. No red error overlay appears in the console, and the network tab shows the dynamic chunk (LeafletMap.js) loading only after the initial HTML.

If the error persists, double‑check that all imports of the offending library are now behind a guard or dynamic import. A stray import L from 'leaflet' in another component will still trigger the same crash.

When the reference hides in a utility module

Sometimes the window reference lives in a helper file that is imported by many components:

// src/utils/browserOnly.ts
export const isMobile = () => window.innerWidth < 768;

In that case, the guard must be inside the utility:

// src/utils/browserOnly.ts
export const isMobile = () => {
  if (typeof window === 'undefined') return false;
  return window.innerWidth < 768;
};

Or you can export a no‑op fallback for the server:

export const isMobile = typeof window !== 'undefined'
  ? () => window.innerWidth < 768
  : () => false;

Libraries that read `window` the moment they load

Some libraries read window at module evaluation time and cannot be deferred. A common example is an older analytics or scroll-tracking hook from packages like react-use (useWindowSize, useScroll) that accesses window as soon as the module is imported in a server context. The fix is to patch the environment with a small shim:

// src/shims/windowShim.js
if (typeof window === 'undefined') {
  global.window = {} as any;
}

Add this shim as the first import in next.config.js:

// next.config.js
const path = require('path');

module.exports = {
  webpack: (config, { isServer }) => {
    if (isServer) {
      config.entry = async () => {
        const entries = await config.entry();
        entries['main.js'] = [
          path.resolve(__dirname, 'src/shims/windowShim.js'),
          ...entries['main.js'],
        ];
        return entries;
      };
    }
    return config;
  },
};

This approach should be a last resort; the guard or dynamic import is cleaner.

Guard rails so it doesn't come back

Next.js treats every page as a hybrid of server‑side rendering (SSR) and client‑side hydration. Anything that runs at the top level of a module is evaluated on the server first. Because window, document, and navigator are browser‑only globals, they must be accessed after the component mounts. To keep the problem from resurfacing:

Add an ESLint rule (no-restricted-globals) that flags direct window usage outside of a typeof guard.
Write a unit test that renders the component with next/jest in a Node environment and asserts that it does not throw.
Create a shared helper (src/lib/isBrowser.ts) that centralizes the guard:

  // src/lib/isBrowser.ts
  export const isBrowser = typeof window !== 'undefined';

Then use if (isBrowser) { … } throughout the codebase.

By making the guard a first‑class citizen, you reduce the cognitive load and avoid accidental server crashes when adding new third‑party UI widgets.

Originally published at https://www.iloveblogs.blog

Fix useEffect Running Twice in React 18 — Strict Mode

Mahdi BEN RHOUMA — Fri, 11 Sep 2026 23:06:25 +0000

You add a useEffect with an empty dependency array, drop a console.log('effect ran') inside, and on first mount you see:

Effect ran
Effect ran

Or in the network tab, the same fetch fires twice:

Fetching data...
Fetching data...

The instinct is to "fix" it so the effect runs once. That instinct is wrong — the double run is React telling you something is about to break. Here is what it is telling you, and the pattern that makes it stop mattering.

It's not a bug — it's Strict Mode

React 18 Strict Mode, on by default in every dev environment (Create React App, Next.js App Router, Vite), deliberately remounts your component once on initial render to stress-test your cleanup logic. The double log is not a defect in your code or in React — it is a safety probe. It surfaces effects that are not idempotent, so you find them in dev instead of in production. In a production build (npm run build) Strict Mode is disabled and the effect runs once.

The probe catches the patterns that hurt most: a fetch with no cancellation that races when a component unmounts mid-request, a Supabase Realtime subscribe() with no unsubscribe() leaking listeners, a timer with no clearInterval. Naive effects that "work" in dev only because Strict Mode happens to be off would silently corrupt state under real network latency, slow devices, or hot-reload.

The mount-unmount-remount cycle

Under the hood, React does three steps on the very first render of a component in dev:

Mounts the component → runs useEffect.
Immediately unmounts it → runs your cleanup (if you returned one).
Remounts it → runs useEffect again.

That is the entire mechanism. A typical effect that fails the probe looks like this:

// src/app/page.tsx
'use client';

import { useEffect, useState } from 'react';

export default function Page() {
  const [data, setData] = useState<string | null>(null);

  useEffect(() => {
    console.log('Effect ran'); // ← logs twice in dev
    // ❌ Non-idempotent: no cleanup, no cancellation
    fetch('/api/data')
      .then(res => res.json())
      .then(json => setData(json.message));
  }, []);

  return <div>{data ?? 'Loading...'}</div>;
}

fetch is not cancellable by default, so when Strict Mode unmounts after step 1, the in-flight request keeps going; step 3 starts a second request; both resolve and overwrite state — a race. The same shape breaks Supabase Realtime: two subscribe() calls without unsubscribe() in cleanup create duplicate listeners and a memory leak. I cover that case in Optimistic UI Patterns with Next.js Server Actions and Supabase Realtime.

The idempotent effect pattern

The fix is to make the effect cancellable so the first invocation's work is discarded when Strict Mode unmounts it:

// src/app/page.tsx
'use client';

import { useEffect, useState } from 'react';

export default function Page() {
  const [data, setData] = useState<string | null>(null);

  useEffect(() => {
    // ✅ Local flag — belongs to THIS effect invocation only
    let active = true;
    const controller = new AbortController();

    const fetchData = async () => {
      try {
        const res = await fetch('/api/data', { signal: controller.signal });
        const json = await res.json();
        if (active) {
          setData(json.message);
        }
      } catch (err) {
        if (err.name !== 'AbortError') {
          console.error('Fetch failed:', err);
        }
      }
    };

    fetchData();

    // ✅ Cleanup cancels the in-flight request and marks this invocation stale
    return () => {
      active = false;
      controller.abort();
    };
  }, []);

  return <div>{data ?? 'Loading...'}</div>;
}

The detail that matters: active is declared inside the effect, so each invocation has its own independent flag. When Strict Mode runs cleanup between the first and second mount, it sets the first invocation's active to false and aborts its request — the second mount starts fresh with active = true. A shared useRef across invocations would not work: the first effect's cleanup would set the ref to false before the second effect's fetch resolves, silently dropping a valid response.

Steps:

Inside the useEffect body, declare let active = true and const controller = new AbortController().
Pass signal: controller.signal to every fetch inside the effect.
Guard all setState calls with if (active).
Return a cleanup that sets active = false and calls controller.abort().

Confirm it's gone in production

npm run dev

With the corrected pattern, the first fetch is aborted (AbortError is swallowed) and only the second mount's fetch completes, setting state exactly once.

npm run build && npm run start

The double-mount cycle disappears entirely — Strict Mode is off in production, so the effect runs once and the single fetch resolves normally.

If double logs persist in dev after this, check whether your Supabase client is reinitializing on every render. That happens when createClient is called inside a component — move it to a module-level constant or wrap it in useMemo.

Don't disable Strict Mode

You will find blog posts suggesting this:

// ❌ NEVER do this
if (process.env.NODE_ENV === 'development') {
  React.StrictMode = null;
}

Or stripping <React.StrictMode> from root.render(...). This is dangerous. Strict Mode catches real bugs — missing cleanup, race conditions, non-idempotent effects — before they reach production. I have seen teams ship duplicate API calls to production because they disabled Strict Mode to silence the double log.

Treat the double execution as a feature flag: if your effect runs twice in dev, it will break under real conditions. Fix it; do not silence it. I go deeper on React 18's stricter behavior in React Server Components: Complete Deep Dive, including how Server Components sidestep this entirely by not running effects on the server.

useLayoutEffect follows the same rule

useLayoutEffect runs synchronously after DOM mutations but before paint, with the same double-execution behavior in development. Because it blocks rendering, it is more prone to layout thrashing — so the cleanup discipline matters even more:

import { useLayoutEffect } from 'react';

// ✅ Same effect, with cleanup
useLayoutEffect(() => {
  const handleResize = () => console.log('Resized');
  window.addEventListener('resize', handleResize);
  return () => window.removeEventListener('resize', handleResize);
}, []);

In production both useEffect and useLayoutEffect run once. In development both run twice, and both require cleanup.

Spot leaks with a render counter

To see the cycle explicitly, log render and cleanup counts:

// src/app/page.tsx
import { useEffect, useRef } from 'react';

export default function Page() {
  const renderCount = useRef(0);
  renderCount.current += 1;

  useEffect(() => {
    console.log(`Effect #${renderCount.current} ran`);
    return () => {
      console.log(`Cleanup after effect #${renderCount.current}`);
    };
  }, []);

  return <div>Render count: {renderCount.current}</div>;
}

In development:

Effect #1 ran
Cleanup after effect #1
Effect #2 ran

In production:

Effect #1 ran

If you see cleanup logs in production, something is wrong — likely a re-render from state changes, not a remount.

FAQ

Why does useEffect only run twice in development and not in production?

Strict Mode is disabled in production builds. React runs the double-mount only in development to catch side effects — it is a dev-time probe, not runtime behavior.

How can I prevent an API call from firing twice on page load?

Use AbortController to cancel pending requests on cleanup, and guard state updates with a local let active = true flag declared inside the effect. Never assume the first request will "win".

Does useEffect running twice affect performance in production?

No. Strict Mode is off in production; effects run once. The double execution is purely a development-time safety net.

How do I properly clean up a subscription or timer in useEffect?

Return a cleanup function:

useEffect(() => {
  const id = setInterval(() => console.log('Tick'), 1000);
  return () => clearInterval(id);
}, []);

Is using a ref to stop the second execution of useEffect bad practice?

No — useRef for an isMounted flag is standard when you cannot cancel the side effect (e.g., third-party libraries without cancellation APIs). Prefer AbortController when possible.

Why is my console.log appearing twice even with an empty dependency array?

Strict Mode remounts the component in development. Empty dependencies only prevent re-runs on subsequent renders — not the initial double-mount.

How do I handle state updates that trigger another useEffect run (infinite loops)?

Check for accidental dependencies — e.g., passing a new object/array literal as a dependency. Use useMemo or useCallback to stabilize references. I cover this in Next.js Performance Optimization: 10 Essential Techniques.

React Server Components: Complete Deep Dive
Optimistic UI Patterns with Next.js Server Actions and Supabase Realtime
Next.js Hydration Mismatch: 8 Fixes for App Router (2026)
Next.js Performance Optimization: 10 Essential Techniques
Fix React 18 hydration mismatch in Next.js — the other symptom of the same React 18 change. If the double effect also leaves the first paint disagreeing with the server HTML, fix the mismatch before the effect.

Originally published at https://www.iloveblogs.blog

Which version of PostgreSQL am I running? 3 ways to check

Mahdi BEN RHOUMA — Fri, 11 Sep 2026 23:05:44 +0000

TL;DR

If you're staring at a terminal and the only thing on your mind is "Which version of PostgreSQL am I running?", the answer is one command away. The fastest way is psql --version for the client, or SELECT version(); inside a psql session for the server. If you don't have psql installed, pg_config --version works too.

Symptom: You need to know the exact PostgreSQL version to troubleshoot a query, verify feature support, or plan an upgrade.
Root cause: PostgreSQL doesn't advertise its version in an obvious place—you have to ask for it explicitly.
Fix: Use psql --version, SELECT version();, or pg_config --version.
Verification: Run any of those commands and confirm the output matches the version you expect.

The question, decoded

You typed "Which version of PostgreSQL am I running?" into Google because you're in one of these situations:

A query that worked on your local machine fails on production, and you suspect a version mismatch.
You're about to use a feature like GENERATED ALWAYS AS IDENTITY or MERGE and need to know if your server supports it.
A security advisory just dropped and you want to confirm you're on a patched release.
You inherited a database and have no idea what's running under the hood.

The symptom isn't an error message—it's the absence of information. You're logged into a server, maybe you can connect with psql, maybe you can't. The version is there, but you need the right incantation to surface it.

Why you need to know the version

PostgreSQL releases a new major version every year, and each one brings syntax changes, new functions, and sometimes breaking behaviour. If you're writing SQL that uses jsonb_path_query_first() (added in v12) or MERGE (added in v15), running it against an older server will throw a syntax error. The same goes for extensions like pg_cron or pg_net—they have minimum version requirements.

Beyond feature compatibility, the version tells you about security. PostgreSQL 16.4 includes fixes that 16.3 doesn't. If you're on a managed service like Supabase, the platform handles patching, but you still need to know which major version your project is on to plan migrations.

The root cause of the confusion is that PostgreSQL doesn't print its version on login by default. The psql welcome banner shows the version, but only if you connect interactively. If you're scripting or using a GUI, you might never see it. And if psql isn't installed at all, you need another way.

The fix: 3 ways to check your PostgreSQL version

I'll walk through the three methods I use in production, ordered from most common to fallback.

1. psql client version (fastest)

If you have the PostgreSQL client tools installed, this is the one-liner:

psql --version

or the short form:

psql -V

Expected output:

psql (PostgreSQL) 16.3

That tells you the client version, which usually matches the server version if you installed the full PostgreSQL package. But it's not a guarantee—you could have a v16 client talking to a v15 server. If you get psql: command not found, you need to install the client first. I cover that exact scenario in Fix: psql: command not found (Install PostgreSQL Client).

2. SQL query (server version, always accurate)

Connect to the database with psql (or any SQL client) and run:

SELECT version();

The output looks like this:

PostgreSQL 16.3 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 13.2.0, 64-bit

This is the server version—the one that actually matters for query compatibility. It includes the OS, architecture, and compiler details, which can be useful when debugging platform-specific issues.

If you only need the version number without the extra fluff, use:

SHOW server_version;

That returns just 16.3. For scripting, you can also query current_setting('server_version_num') to get an integer like 160003 that's easy to compare programmatically.

3. pg_config (when psql isn't available)

If you're on a server that has the PostgreSQL development headers installed but not the client, pg_config is your friend:

pg_config --version

Output:

PostgreSQL 16.3

This reports the version of the installed server package. It's especially handy in CI pipelines where you might have libpq-dev but not the full psql binary.

Bonus: check via package manager

On Debian/Ubuntu:

dpkg -l | grep postgresql

On RHEL/CentOS:

rpm -qa | grep postgresql

These list installed packages, and the version number is right in the package name (e.g., postgresql-16). This is a quick way to confirm what's installed without needing any PostgreSQL tool at all.

Supabase dashboard

If your database lives on Supabase, you don't need a terminal. Go to your project dashboard → Settings → Database, and the PostgreSQL version is displayed under "Database version". This is the server version your project is running. I use this all the time before testing new features—knowing the version upfront saves me from writing SQL that will fail on deploy. For more on navigating the Supabase SQL editor, see PostgreSQL SHOW TABLES / DESCRIBE TABLE (psql + Supabase).

Verify the version

Pick any method above and run it. You should see a version string that matches what you expect. If you're verifying after an upgrade, compare the output against the target version. For example, after upgrading a Supabase project from v15 to v16, running SELECT version(); should now show PostgreSQL 16.x.

If the version doesn't match, double-check that you're connected to the right host and port. It's easy to accidentally run psql against a local instance when your production database is elsewhere.

Two common pitfalls when checking the version

Pitfall A: client vs. server mismatch

You run psql --version and see 16.3, but SELECT version(); returns 15.7. This happens when the client tools were upgraded independently of the server. Always trust the server version from SELECT version(); for compatibility decisions. The client version only matters for psql-specific features like \gexec or \if meta-commands.

Pitfall B: multiple PostgreSQL installations

On a dev machine, you might have PostgreSQL 14 from the system package manager and PostgreSQL 16 from a Homebrew or Docker install. Running psql might pick up whichever binary is first in your PATH. Use which psql to see which one you're invoking, and if needed, specify the full path to the correct psql binary.

Keep your version knowledge handy

I make it a habit to pin the PostgreSQL version in my project's README and in infrastructure-as-code configs. That way, when I'm debugging a query six months later, I don't have to re-discover which version the staging database is on. If you're using Docker, tag your images with the exact minor version (postgres:16.3) instead of latest to avoid surprise upgrades.

For teams, add a database migration that inserts the current version into a schema_versions table. That gives you an audit trail of when upgrades happened and what version was active at any point in time.

FAQ

How do I check the PostgreSQL version from the command line?

Run psql --version or psql -V to see the client version. To check the server version, connect with psql and run SELECT version(); or use pg_config --version if the development headers are installed.

What is the SQL query to get the PostgreSQL version?

Execute SELECT version(); inside a PostgreSQL session. This returns a string like PostgreSQL 16.3 on x86_64-pc-linux-gnu, compiled by gcc... that includes the full version number and build details.

Originally published at https://www.iloveblogs.blog

NextJS Warning: Extra attributes from the server – Fix 2026

Mahdi BEN RHOUMA — Fri, 11 Sep 2026 23:05:37 +0000

In my own Next.js + Supabase project this line started showing up in the console after I added a third‑party analytics snippet directly inside a component:

Warning: Extra attributes from the server: data-new-gr-c-s-check-loaded="true"

The page is rendered on the server, sent to the browser, and then React tries to hydrate the markup on the client. The server‑side HTML contains a data-new-gr-c-s-check-loaded attribute that the client‑side React tree never creates, so React logs the warning and continues. The behavior is reproducible on local development (npm run dev) as well as on Vercel preview deployments, but only when the offending script is present.

The warning itself is harmless — the page still works — but it signals a hidden source of nondeterminism that can cause subtle bugs, especially when you rely on server‑only data (e.g., Supabase session cookies) that might be overwritten. Here is where the attribute comes from and three ways to make it go away.

Who injects `data-new-gr-c-s-check-loaded`

The warning is a direct result of a hydration mismatch. During the initial render Next.js streams HTML generated by React on the server. After the browser receives that HTML, React mounts the same component tree on the client and expects the DOM to match exactly. If any attribute appears in the server markup that React never renders, it flags the difference as “extra attributes from the server”.

Two common culprits inject the data-new-gr-c-s-check-loaded attribute:

Browser extensions – Grammarly, for example, injects a data-gr-ext-installed attribute onto the <body> element. The server HTML never contains this attribute; the extension adds it client‑side after the page loads. React then sees an attribute in the live DOM that was not in the server markup and logs the hydration warning. Because the injection target is <body>, adding suppressHydrationWarning to the <body> tag (not <html>) is the correct way to silence it in Next.js App Router layouts.
Third‑party scripts added via plain <script> tags – Many analytics or widget providers ask you to paste a <script src="…"> snippet directly into your JSX. If that script writes data-* attributes onto the root element (or any element) during its load phase, the server‑side HTML will miss those attributes, and React will warn.

Both scenarios break the invariant that server and client markup must be identical before hydration.

What React actually compares during hydration

The relevant code path is the client-side hydration reconciler in react-dom. During hydration the client calls warnForExtraAttributes (in ReactDOMComponent.js) which compares the attribute list of each DOM element against what React rendered. Any attribute present in the live DOM that React did not produce triggers the warning you see.

That means the fix has two parts: (1) stop third‑party scripts from mutating the markup, and (2) optionally strip any stray attributes that extensions might add during the initial render.

Fix 1 — load external scripts with `next/script`

next/script defers script execution until after React has hydrated, preventing the script from touching the server‑generated HTML.

// pages/_app.tsx
import type { AppProps } from 'next/app';
import Script from 'next/script';

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <>
      {/* Example: Google Analytics */}
      <Script
        src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"
        strategy="afterInteractive"
      />
      <Script id="ga-init" strategy="afterInteractive">
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
          gtag('config', 'G-XXXXXXX');
        `}
      </Script>

      <Component {...pageProps} />
    </>
  );
}

That single change ensures the analytics script runs after the React tree is already attached, so any data-* attributes it adds will appear only on the client side after hydration, and React will not compare them.

Fix 2 — strip `data-gr-*` attributes in a custom `_document`

If you cannot control a third‑party script (or you need to support users with extensions that inject attributes), you can strip those attributes during the server render. Create a custom _document that removes any data-gr-* attributes from the <html> element before sending HTML to the browser.

// pages/_document.tsx
import Document, { Html, Head, Main, NextScript, DocumentContext } from 'next/document';

export default class MyDocument extends Document {
  static async getInitialProps(ctx: DocumentContext) {
    const initialProps = await Document.getInitialProps(ctx);
    // Clone the HTML to manipulate it safely
    const html = initialProps.html.replace(
      / data-gr-[a-z-]+="[^"]*"/g,
      ''
    );
    return { ...initialProps, html };
  }

  render() {
    return (
      <Html>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

Before / after:

- <Html data-gr-ext-installed="true" data-new-gr-c-s-check-loaded="true">
+ <Html>

The regex removes any attribute that starts with data-gr- or data-new-gr-c-s-check-loaded. This approach is safe because those attributes are never used by your application logic; they are purely injected by external tools.

Fix 3 — defer your own DOM writes to `useEffect`

If you have custom useEffect code that writes attributes, wrap it in a check that runs only after the component is mounted.

// components/AnalyticsProvider.tsx
import { useEffect } from 'react';

export default function AnalyticsProvider() {
  useEffect(() => {
    if (typeof window !== 'undefined') {
      const script = document.createElement('script');
      script.src = 'https://example.com/widget.js';
      script.async = true;
      document.body.appendChild(script);
    }
  }, []);

  return null;
}

By ensuring the script runs after the first paint, you avoid contaminating the server markup.

Triage checklist

Identify the offending script – Look at the warning’s attribute name. If it contains gr-, suspect Grammarly or a similar extension. If it’s a custom analytics name, locate the <script> tag you added.
Replace raw <script> tags with the next/script component as shown above. Use strategy="afterInteractive" for most cases.
Add a custom _document if you need a blanket removal of data-gr-* attributes. Paste the code exactly; the regex will strip any matching attribute.
Run the dev server (npm run dev). The warning should disappear.
Deploy and verify on Vercel preview; the warning should stay gone because the server‑side HTML no longer contains the extra attributes.

Confirming the hydration is clean

Run the development server:

npm run dev

Open http://localhost:3000 in a clean browser (disable extensions). You should see no warning in the terminal or browser console.

> next dev
ready - started server on http://localhost:3000

If the warning still appears, open the page source (Ctrl+U) and search for data-new-gr-c-s-check-loaded. If it is absent, the server markup is clean. Then open the DevTools Elements panel and look for the same attribute; if it appears only after the page loads, it means a client‑side script is still injecting it, and you need to adjust the script’s loading strategy.

When the source is out of your hands

Extension‑only injection. If you cannot control the user’s browser extensions, the _document sanitisation is the reliable fix. The regex will strip the attribute regardless of which extension added it.

Inline scripts that write attributes early. If you have an inline script that runs before React hydrates (e.g., a legacy analytics snippet placed in pages/index.tsx), move it to next/script with strategy="afterInteractive" or wrap it in a useEffect as shown earlier. This prevents the attribute from existing in the server HTML.

Keeping server markup deterministic

React’s hydration algorithm assumes a deterministic render: given the same props and state, the server and client must produce identical DOM trees. Anything that mutates the DOM between the server response and the client render breaks that assumption. The safest pattern is:

Never embed raw <script> tags that execute synchronously. Use next/script with an explicit loading strategy.
Avoid DOM manipulation in the top‑level component body; always place it inside useEffect or useLayoutEffect.
Test with extensions disabled or use a headless browser (e.g., Playwright) to catch unexpected attribute injection before shipping.
Add a lint rule (via ESLint) that flags <script> JSX elements without next/script. Example rule configuration can be found in the official Next.js ESLint plugin.

By keeping the server‑generated markup pure and deferring any side‑effects until after hydration, you eliminate the “Extra attributes from the server” warning and keep your Next.js + Supabase app stable.

Originally published at https://www.iloveblogs.blog

TypeScript 6.0 Migration: What Actually Breaks in Next.js/Supabase

Mahdi BEN RHOUMA — Fri, 11 Sep 2026 23:04:56 +0000

TypeScript 6.0 shipped on March 23, 2026, and it's the last version of the compiler written in JavaScript before the team's full-speed move to the Go-based TypeScript 7 (tsgo). Because of that, 6.0 is a genuine "spring cleaning" release: several long-deprecated options are gone, strict mode is on by default, and legacy targets are removed outright rather than just discouraged.

Most of the writeups floating around right now are abstract changelogs. This is what those changes actually do to a real Next.js App Router + Supabase project — the errors you'll see, and the order that minimizes wasted work.

What actually changed

Strict mode is on by default. If your tsconfig.json never explicitly set "strict": false, you're now opted into strictNullChecks, noImplicitAny, and the rest of the bundle, even if you never asked for it.
target: "es5" is deprecated (ES2015 is now the effective floor), and moduleResolution: "classic" is removed entirely. You must use "node16", "nodenext", or "bundler" (the one Next.js projects almost always want). Per the official TypeScript 6.0 release notes, deprecated options still compile in 6.0 (silence the warning with "ignoreDeprecations": "6.0" if you need breathing room) but are slated for hard removal in TypeScript 7.0 — treat the deprecation warning as a deadline, not background noise.
module: "amd" | "umd" | "systemjs" | "none" are deprecated, not yet hard errors. These predate the ESM ecosystem and have no place in an App Router project, but you may have inherited one from a dependency's shared tsconfig — fix it now rather than waiting for TypeScript 7.0 to force the issue.
All code is now assumed to be in strict-mode JavaScript syntax. If legacy or generated code uses reserved words (await, static, private, public, etc.) as plain identifiers, that now fails to parse. This mostly affects legacy scripts or generated code, not typical Next.js source.

Fix order for a Next.js + Supabase project

Trying to fix everything at once produces a wall of hundreds of errors with no sense of progress. This order clears the noisy, mechanical errors first so what's left is the genuine type-safety issues worth your attention.

1. Fix config-level errors first. Run tsc --noEmit and look only at errors that reference tsconfig.json itself — moduleResolution, target, module values. These are one-line fixes and they unblock everything downstream. For a standard Next.js App Router project:

{
  "compilerOptions": {
    "target": "es2022",
    "moduleResolution": "bundler",
    "module": "esnext"
  }
}

2. Fix strictNullChecks errors in your data layer next, specifically anywhere you touch a Supabase client response. Supabase's generated types already model nullability accurately (a .single() query can return null), but code written under lenient mode often accessed .data.someField without a null check because it "worked" at runtime. This is where strict mode earns its keep — and where you'll find the highest-value real bugs, not just noise.

3. Fix noImplicitAny in Server Actions and API route handlers last. These tend to be the highest volume of trivial errors (untyped formData.get() results, untyped request bodies) and the lowest risk — mechanical typing, not logic changes. Doing this last means your context budget goes to the data-layer bugs that matter, not to typing 200 form handlers.

4. Re-run your test suite, not just the type checker. Strict null checks catching a real bug means a code path changes behavior, not just its types — a .single() result that was silently null and got treated as an object might now throw where it used to fail silently downstream. That's the fix working as intended, but it needs a test pass to confirm.

The error you'll hit that isn't really about TypeScript 6.0

If you see Cannot find module 'X' or its corresponding type declarations appearing for packages that worked fine before, check whether it's actually the moduleResolution change surfacing a package that never shipped proper ESM exports — not a new TypeScript 6.0 bug. See TypeScript: could not find declaration file for module — fix for the general diagnostic steps, which still apply.

Fix An index signature parameter type cannot be a union

Mahdi BEN RHOUMA — Fri, 11 Sep 2026 23:04:49 +0000

TL;DR

If you're seeing An index signature parameter type cannot be a union type. Consider using a mapped object type instead, the cause is that TypeScript index signatures only accept string, number, or symbol as the key type. Fix it by replacing the index signature with a mapped object type using the in operator, or the Record utility type.

If that doesn't work, scroll to verify the fix — there are two common variants this guide also covers.

Symptom: TypeScript compiler error "An index signature parameter type cannot be a union type. Consider using a mapped object type instead."
Root cause: Index signatures describe all possible string/number keys; a union type restricts keys to a specific set, which is a contradiction.
Fix: Replace [key: UnionType]: ValueType with [key in UnionType]: ValueType inside a type alias, or use Record<UnionType, ValueType>.
Verification: Run tsc --noEmit and confirm zero errors related to the index signature.

What you'll see

A developer on Stack Overflow reported this exact error when trying to use a TypeScript enum as the key type in an interface index signature. The compiler output is unambiguous:

An index signature parameter type cannot be a union type. Consider using a mapped object type instead.

It happens when you write something like this:

enum Option {
  ONE = 'one',
  TWO = 'two',
  THREE = 'three'
}

interface OptionRequirement {
  someBool: boolean;
  someString: string;
}

interface OptionRequirements {
  [key: Option]: OptionRequirement;
  //  ~~~~~~~~~
  //  An index signature parameter type cannot be a union type.
  //  Consider using a mapped object type instead.
}

The behavior is the same across all TypeScript versions that support mapped types. It fires whether you use an enum, a union of string literals, or any type that isn't exactly string, number, or symbol.

Root cause

An index signature in TypeScript describes an object that can have any number of properties, as long as every property's key matches the index signature parameter type and every property's value matches the value type. The language specification restricts the key type to string, number, or symbol — and for good reason.

When you write [key: string]: SomeType, you're telling the compiler "this object may have any string key, and every value under any string key must be SomeType." That's an open-ended contract. A union type like Option.ONE | Option.TWO | Option.THREE is a closed set — it says "only these three specific strings are allowed as keys." Those two ideas are fundamentally incompatible. An index signature cannot both be open-ended (any string) and closed (only these three strings) at the same time.

The compiler detects this contradiction and suggests the correct alternative: a mapped object type. A mapped type iterates over a specific set of keys and produces a type with exactly those keys, which is what you actually want when you use an enum or a union of string literals as the key set.

The relevant code path that triggers the error is any interface or type declaration containing an index signature whose parameter type is not string, number, or symbol:

// Both of these trigger the error:
interface Broken {
  [key: 'a' | 'b']: string; // union type
}

type AlsoBroken = {
  [key: MyEnum]: number; // enum (which is a union under the hood)
};

The fix: replace the index signature with a mapped type

The solution is to use the in operator inside a type alias. The in operator iterates over each member of a union type and creates a property for each one:

enum Option {
  ONE = 'one',
  TWO = 'two',
  THREE = 'three',
}

interface OptionRequirement {
  someBool: boolean;
  someString: string;
}

type OptionRequirements = {
  [key in Option]: OptionRequirement;
};

That single change addresses the cause because key in Option tells TypeScript "for each individual member of the Option union, create a property with that exact key and type OptionRequirement." The result is an object type with exactly three known keys — one, two, and three — each mapped to OptionRequirement. This is a closed, specific shape, not an open-ended index signature.

Step by step

Open the file containing the broken interface or type.
Locate the index signature that uses a union type or enum as the key — it will have the form [key: SomeUnion]: SomeType.
Change the interface to a type alias (mapped types cannot appear inside interface declarations).
Replace the colon (:) after key with the in operator.
Save and run tsc --noEmit to verify.

The fix: use the `Record` utility type as a shorthand

TypeScript ships with a built-in utility type called Record<K, V> that does exactly what the mapped type above does, but with less syntax:

enum Option {
  ONE = 'one',
  TWO = 'two',
  THREE = 'three',
}

interface OptionRequirement {
  someBool: boolean;
  someString: string;
}

type OptionRequirements = Record<Option, OptionRequirement>;

Record<Option, OptionRequirement> expands to the same mapped type { [key in Option]: OptionRequirement }. It's a direct, readable shortcut. Use it when you don't need to add additional properties or modifiers to the mapped type — Record gives you a plain object type with all keys required and all values of the same type.

If you need to make some keys optional or add readonly modifiers, fall back to the explicit mapped type syntax:

type OptionRequirements = {
  [key in Option]?: OptionRequirement; // all keys optional
};

type ReadonlyOptionRequirements = {
  readonly [key in Option]: OptionRequirement; // all keys readonly
};

Important: mapped types must be inside a `type` alias, not an `interface`

A common mistake after learning the fix is to try to use the in operator inside an interface:

// This does NOT compile:
interface OptionRequirements {
  [key in Option]: OptionRequirement;
  //     ~~
  //     'in' operator is not allowed in an interface.
}

TypeScript interfaces do not support mapped type syntax. The in operator, along with keyof, as (key remapping), and other mapped type features, are exclusive to type aliases. If your type needs to be extended by other interfaces or used with implements on a class, you can still use a type alias — classes can implement object types defined with type as long as the shape is a plain object type.

This distinction between interface and type comes up frequently in production TypeScript codebases. I cover the full decision framework in the Interfaces vs Types in TypeScript guide.

Verify the fix

Run the TypeScript compiler in check-only mode to confirm the error is gone:

npx tsc --noEmit

You should see no output (zero errors). If the error persists, check for these two common variants.

Variant A — you used `:` instead of `in`

The most frequent mistake after learning about mapped types is writing [key: Options] instead of [key in Options]. The colon tells TypeScript you're still trying to write an index signature, and the error fires again. The fix is to replace the colon with in:

// Wrong — still an index signature:
type ProviderProps = {
  items: {
    [key: PossibleKeysType]: Array<SectionItemsType>;
  };
};

// Correct — mapped type:
type ProviderProps = {
  items: {
    [key in PossibleKeysType]: Array<SectionItemsType>;
  };
};

Variant B — you defined the mapped type inside an `interface`

If you see an error about the in operator not being allowed, you've placed the mapped type inside an interface body. Convert the interface to a type alias:

// Wrong — interface doesn't support mapped types:
interface OptionRequirements {
  [key in Option]: OptionRequirement;
}

// Correct — type alias does:
type OptionRequirements = {
  [key in Option]: OptionRequirement;
};

Why this happens (and how to avoid it next time)

The invariant is simple: index signatures describe all possible keys of a given category (string, number, symbol). A union type describes a specific, finite set of keys. When you need an object type with a specific set of keys derived from a union or enum, you want a mapped type — not an index signature. The compiler's error message already tells you this, but the distinction between the two concepts is what trips people up.

To prevent this error from appearing in your codebase, enable the @typescript-eslint/consistent-indexed-object-style rule if you're using ESLint with TypeScript. It can enforce using Record or mapped type syntax consistently and will flag index signatures that could be expressed more precisely. For a broader approach to catching type-level mistakes before they reach production, the Type Safety Guide for Next.js + Supabase in TypeScript walks through setting up strict TypeScript configurations that catch these issues at compile time.

FAQ

Why can't I use a union type as an index signature parameter in TypeScript?

TypeScript index signatures require the key type to be string, number, or symbol because they describe all possible keys of an object. A union type restricts the keys to a specific set, which contradicts the open-ended nature of an index signature. Use a mapped object type with the in operator instead — it iterates over the union members and creates a type with exactly those keys.

How do I use an enum as keys in a TypeScript object type?

You cannot use an enum directly in an index signature. Instead, define a mapped type using [key in MyEnum]: ValueType inside a type alias, or use the Record<MyEnum, ValueType> utility type. Both approaches iterate over the enum members and create a type with those specific keys. Mapped types must be defined in a type alias, not an interface.

What is the difference between an index signature and a mapped type?

An index signature ([key: string]: T) says "this object can have any string key, and every value must be T." It's open-ended. A mapped type ([key in SomeUnion]: T) says "this object has exactly the keys in SomeUnion, and each value is T." It's closed and specific. Use index signatures when the set of keys is truly unbounded; use mapped types when you know the exact keys ahead of time.

Can I use a union of string literals as keys in an interface?

Not with an index signature. If you need an interface with a specific set of keys from a union, you have two options: either write the keys out explicitly in the interface, or use a type alias with a mapped type. Interfaces do not support the in operator or mapped type syntax. If your type doesn't need to be merged via declaration merging, a type alias is the more flexible choice.

Originally published at https://www.iloveblogs.blog

TypeError cookies() crash in Next.js route handler

Mahdi BEN RHOUMA — Fri, 11 Sep 2026 17:25:35 +0000

A route handler that reads or writes cookies starts returning 500s right after a deploy to Vercel, and the logs show this stack trace:

Error: TypeError: cookies() is not a function
    at async /app/api/auth/login/route.ts:12:25
    at processTicksAndRejections (node:internal/process/task_queues:96:5)

The short version: in Next.js 15+ the cookies() helper is asynchronous. Call it without await and the variable you think holds a cookie store actually holds a Promise — the next .get() or .set() blows up with this TypeError. Adding await in front of cookies() (and updating any downstream code that expects a cookie store) resolves it.

Symptom: TypeError: cookies() is not a function in a route handler
Root cause: cookies() is async in Next.js 15/16 and must be awaited
Fix: Add await to the call and update dependent code
Verification: Run the handler locally or with curl and see a 200 response instead of 500

The stack trace blames your file, not the framework

The error surfaces when a POST request hits a route handler that reads or writes cookies after a recent deployment to Vercel. The behavior is the same across staging, production, and local npm run dev environments, which makes it easy to reproduce with a single curl command.

I first noticed this after merging a feature branch that introduced a new authentication endpoint. The GitHub issue that sparked this investigation is vercel/next.js#51156, where multiple teams reported intermittent 500 errors caused by the same stack trace. The error only appears after the code is built for production because the serverless runtime enforces the async contract of cookies() more strictly than the dev server.

The relevant code path lives in the Next.js core, but the part that touches your code is the call site inside your route file. When you look at the stack trace, the topmost frame points to your file, not the framework, which is why the issue appears to be “your code”.

What changed: `cookies()` now returns a Promise

In Next.js 15 the cookies() helper was refactored to be asynchronous. The function now returns a Promise<CookieStore> instead of a plain object. When you call cookies() without await, the variable you think holds a cookie store actually holds a Promise. The next line usually tries to read a cookie like cookieStore.get('session'), but because cookieStore is a Promise, JavaScript throws TypeError: cookies() is not a function. The error propagates up to the route handler, causing the entire request to fail with a 500 status.

Two things make this bug especially sneaky:

The TypeScript compiler does not always flag the missing await because the return type of cookies() is any in older type definitions. That means the code compiles cleanly, but at runtime the mismatch surfaces.
In the Vercel edge runtime, the handler is executed in a separate isolate where the Promise is never automatically resolved, so the error is not swallowed as it sometimes is in a Node.js dev server.

Here is what the failing call site looks like:

// app/api/auth/login/route.ts
export async function POST(request: Request) {
  const cookieStore = cookies(); // ← missing await
  const body = await request.json();
  if (body.password === 'secret') {
    cookieStore.set('session', 'abc123', { httpOnly: true });
    return new Response('Logged in', { status: 200 });
  }
  return new Response('Unauthorized', { status: 401 });
}

Notice how cookies() is called synchronously. The framework expects an async call, so the returned Promise is never resolved, and the subsequent set call triggers the TypeError.

The one-line change: `await cookies()`

import { cookies } from 'next/headers';
// app/api/auth/login/route.ts
export async function POST(request: Request) {
  // Await the async cookies helper
  const cookieStore = await cookies();

  const body = await request.json();

  if (body.password === 'secret') {
    // Now cookieStore is a proper CookieStore instance
    cookieStore.set('session', 'abc123', { httpOnly: true });
    return new Response('Logged in', { status: 200 });
  }

  return new Response('Unauthorized', { status: 401 });
}

That single change addresses the cause because it respects the async contract introduced in Next.js 15. The await forces the Promise to resolve before we interact with the cookie store, eliminating the TypeError. If you have multiple route handlers that use cookies(), apply the same pattern to each:

Open the file that contains the failing route handler, e.g., app/api/auth/login/route.ts.
Locate the line that reads const cookieStore = cookies();.
Prefix the call with await so the line becomes const cookieStore = await cookies();.
Ensure the surrounding function is declared async (it already is in most cases). Save the file and run npm run dev or redeploy to Vercel.
If you use TypeScript, you may also want to update the import: import { cookies } from 'next/headers'; – this stays the same, but the type definitions will now correctly show a Promise<CookieStore>.

I wrote a companion guide that walks through the same pattern for the App Router in Next.js 15: "Fix \"cookies() should be awaited\" Error in Next.js 15 App Router (Complete Migration Fix 2026)". That article also explains why the lint rule next/no-unawaited-cookies is useful.

Prove it with a curl request

Run the following command against your local dev server:

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password":"secret"}' -i

You should see output similar to:

HTTP/1.1 200 OK
set-cookie: session=abc123; Path=/; HttpOnly
Content-Type: text/plain; charset=UTF-8
Content-Length: 9

Logged in

Notice the set-cookie header is present and the status code is 200 instead of 500. If you still receive a 500 response, double‑check that every cookies() call in the file (and any imported helper) is awaited.

Still crashing? Two look-alike causes

`cookies` imported from the wrong package

Some projects import cookies from next/headers while others mistakenly use next/cookies. The wrong import returns a stub that is not async, leading to a different error (cookies is not a function). Ensure your import looks exactly like this:

import { cookies } from 'next/headers';

If you see import { cookies } from 'next/cookies';, replace it with the correct path and re‑run the verification command.

`cookies()` called from middleware instead of a route handler

Middleware runs in a different runtime where cookies() is still synchronous. If you copy the same code into middleware.ts, the await will cause a compile error. In that case, keep the call synchronous and use request.cookies directly. The fix for route handlers does not apply to middleware.

Why Next.js made header helpers async

Next.js 15 introduced an async API surface for many header helpers to make them compatible with edge runtimes. The underlying invariant is that any helper that may need to read from a streaming request must be async. When the framework changed, the type definitions lagged, so developers kept using the old synchronous pattern. To avoid the regression:

Add the ESLint rule next/no-unawaited-cookies to your .eslintrc.json. It will flag any cookies() call that lacks await.
Write a unit test for each route handler that asserts the response contains the expected set-cookie header. A failing test will surface the missing await before you ship.
Pin your Next.js version to a minor release that you have verified, and read the migration guide for each major release. My guide on partial prerendering covers similar migration pitfalls: "Next.js 15 Partial Prerendering: The Complete Production Guide".

By treating the async nature of cookies() as a first‑class citizen, you prevent the TypeError from resurfacing after future upgrades.

Originally published at https://www.iloveblogs.blog

Supabase bucket RLS policy for table objects fix

Mahdi BEN RHOUMA — Fri, 11 Sep 2026 17:24:53 +0000

The exact error looks like this:

new row violates row-level security policy for table "objects"

The root cause is usually one of three things:

you have no INSERT policy on storage.objects
you are using upsert: true, which needs more than just INSERT
you passed the bucket and file path in the wrong places

That is why this error shows up even when the user is already signed in.

The first thing to fix: bucket name vs file path

This is the broken shape from the real Stack Overflow thread:

// Wrong
await supabase.storage
  .from('/public/avatars')
  .upload(`${email}.png`, file, { upsert: true })

Supabase's own upload docs show the correct split:

const { data, error } = await supabase.storage
  .from('avatars')
  .upload('public/avatar1.png', file, {
    cacheControl: '3600',
    upsert: false,
  })

if (error) throw error

from() takes the bucket. upload() takes the path inside that bucket.

The minimal policy for a plain upload

Supabase documents that the only policy required for uploading objects is an INSERT policy on storage.objects.

A minimal bucket-scoped policy looks like this:

create policy "Allow authenticated uploads to avatars"
on storage.objects
for insert
to authenticated
with check (
  bucket_id = 'avatars'
);

If your uploads should go only into a specific folder, add a folder constraint too:

create policy "Allow authenticated uploads to avatars/private"
on storage.objects
for insert
to authenticated
with check (
  bucket_id = 'avatars' and
  (storage.foldername(name))[1] = 'private'
);

The `upsert: true` trap

This is the part many articles miss. Supabase's Storage access-control docs explicitly say that overwriting files with upsert needs SELECT and UPDATE permissions in addition to the upload policy.

So this code:

await supabase.storage
  .from('avatars')
  .upload(`private/${userId}/avatar.png`, file, {
    upsert: true,
  })

needs more than just for insert.

If you do not actually need overwrite behavior, make the fix smaller:

await supabase.storage
  .from('avatars')
  .upload(`private/${userId}/avatar.png`, file, {
    upsert: false,
  })

That alone resolves a surprising number of production bugs.

If you really do need overwrite behavior

Keep the insert policy, then add read/update policies that match the same object scope.

create policy "Allow authenticated reads on avatars/private"
on storage.objects
for select
to authenticated
using (
  bucket_id = 'avatars' and
  (storage.foldername(name))[1] = 'private'
);

create policy "Allow authenticated updates on avatars/private"
on storage.objects
for update
to authenticated
using (
  bucket_id = 'avatars' and
  (storage.foldername(name))[1] = 'private'
)
with check (
  bucket_id = 'avatars' and
  (storage.foldername(name))[1] = 'private'
);

A safe client upload example

const filePath = `private/${userId}/avatar.png`

const { data, error } = await supabase.storage
  .from('avatars')
  .upload(filePath, file, {
    cacheControl: '3600',
    upsert: false,
  })

if (error) {
  throw error
}

This is the right place to start. Only add overwrite behavior once the basic insert path works.

When the service key changes everything

Supabase's Storage docs also note that service keys bypass Storage RLS entirely. That can be useful for trusted server-side jobs, but it is not a fix for a browser upload bug. If a client upload needs the service key to work, the policy is still wrong.

The better debugging order is:

fix the bucket/path split
test with upsert: false
add the exact INSERT policy
only then add SELECT and UPDATE if overwrite is required

Scoping uploads to the signed-in user

The folder constraint above used a literal ('private'). To restrict every user to their own folder, match the first path segment against the user id. This is the pattern Supabase's own docs recommend, and it survives multi-tenant scale:

create policy "Users upload to their own folder"
on storage.objects
for insert
to authenticated
with check (
  bucket_id = 'avatars' and
  (storage.foldername(name))[1] = (select auth.uid()::text)
);

Upload to a path whose first segment is the user id, and the check passes:

const filePath = `${user.id}/avatar.png`

await supabase.storage
  .from('avatars')
  .upload(filePath, file, { upsert: false })

auth.uid() returns a UUID; the cast to text matters because storage.foldername(name) returns text segments. Wrapping it in (select ...) lets Postgres evaluate it once per statement instead of once per row.

Which role and which `FOR` clause

Two details decide whether your policy ever fires:

Role (TO clause). A signed-in user's request runs as authenticated, not anon. A policy scoped to anon will never apply to a logged-in upload, and vice-versa. The service_role key bypasses RLS entirely — useful for trusted server jobs, never a fix for a browser upload.
Operation (FOR clause). for insert covers only the upload. If the same per-user predicate should also gate reads, updates, and deletes, use for all with both using (read/delete predicate) and with check (write predicate):

create policy "Full access to own files"
on storage.objects
for all
to authenticated
using ((storage.foldername(name))[1] = (select auth.uid()::text))
with check ((storage.foldername(name))[1] = (select auth.uid()::text));

`owner` vs `owner_id`: don't gate on the wrong column

A common dead end is writing the policy against an ownership column instead of the path. If you go that route, use the right column: modern Supabase stores the uploader in owner_id (text), and the older owner (uuid) column is deprecated. A policy like with check (owner_id = auth.uid()) also needs a cast (owner_id is text, auth.uid() is uuid) — with check (owner_id = (select auth.uid()::text)). In practice the folder-path pattern above is simpler and less error-prone than relying on the auto-set owner column, so prefer it unless you have a reason not to.

For the surrounding security pieces:

References

Originally published at https://www.iloveblogs.blog

DEV Community: Mahdi BEN RHOUMA

Prisma: Can't reach database server at database:5432 on M1

TL;DR

The error, decoded

Why M1 Macs break Docker networking for Prisma and PostgreSQL

The fix: Add a connection timeout to DATABASE_URL

Alternative fix: Upgrade Node.js

Verify the fix

Two patterns that still trip you up

Pattern 1: Using localhost instead of the service name

Pattern 2: Not waiting for PostgreSQL to be ready

FAQ

Why does Prisma fail with 'Can't reach database server at database:5432' on M1 Macs?

Does changing the Node.js version fix the Prisma connection error on M1?

Can I use host.docker.internal instead of the service name?

How do I test if my database is reachable from inside the container?

Related

Why useEffect runs twice in Next.js dev

The broken effect pattern

A safer effect

What React is actually telling you

The better fix in many Next.js apps: move the fetch to the server

What not to do first

When a useRef guard is acceptable

References

Related

Extract date (yyyy/mm/dd) from a timestamp in PostgreSQL

The cast returns the full date, not just the year

The accepted answer and the direct cast

Use the direct cast for a native DATE

Use to_char only for display

date_trunc is not a date extraction

Verify the extracted date

1. Confirm the column type

2. Check the actual value

3. Insert the value into a DATE column

Three common pitfalls during verification

FAQ

Why can’t I just do to_date(to_char(ts, 'YYYY/MM/DD'), 'YYYY/MM/DD')?

Does ::date work in all PostgreSQL versions?

How do I output the date exactly as yyyy/mm/dd without losing the DATE type?

Related

Zero-Downtime Supabase Migrations: Expand/Contract (2026)

The Mental Model

Supabase Migration Workflow

Set Lock and Statement Timeouts

Safe Change 1: Add a New Nullable Column

Safe Change 2: Rename a Column

Release 1: Expand

Release 2: Bridge in App Code

Release 3: Backfill

Release 4: Validate

Release 5: Contract

Safe Change 3: Add a Required Foreign Key

Safe Change 4: Change a Column Type

Safe Change 5: Create Large Indexes

RLS Changes Are Schema Changes

Expand

Bridge

Contract

Type Generation Timing

GitHub Actions CI

Downloadable Assets

Add a Migration Safety Linter

Rollback Strategy

Migration Safety Checklist

Example Rollout: Add Team Billing

Migration 1: Expand

Deploy 1: Bridge

Backfill

Migration 2: Validate

Deploy 2: Switch

Migration 3: Contract

What Not to Do

Reference Docs

The Durable Pattern

Related Incidents

Adjacent Guides

Window is not defined in Next.js – 2026 Fix for React Apps

The crash happens at import time, not render time

Pattern 1: Using `localhost` instead of the service name

Can I use `host.docker.internal` instead of the service name?

When a `useRef` guard is acceptable

Use `to_char` only for display

`date_trunc` is not a date extraction

3. Insert the value into a `DATE` column

Why can’t I just do `to_date(to_char(ts, 'YYYY/MM/DD'), 'YYYY/MM/DD')`?

Does `::date` work in all PostgreSQL versions?

How do I output the date exactly as `yyyy/mm/dd` without losing the DATE type?

Three ways to keep `window` out of the server bundle

Dynamic import with `ssr: false` (the approach I'd pick)

The `typeof window` guard inside `useEffect`

Libraries that read `window` the moment they load

Who injects `data-new-gr-c-s-check-loaded`

Fix 1 — load external scripts with `next/script`

Fix 2 — strip `data-gr-*` attributes in a custom `_document`

Fix 3 — defer your own DOM writes to `useEffect`

The fix: use the `Record` utility type as a shorthand

Important: mapped types must be inside a `type` alias, not an `interface`

Variant A — you used `:` instead of `in`