Supabase Postgres 관계형 데이터 모델링: 외래키와 TaskFlow 스키마 설계

auth.users와 public.profiles 분리

Supabase Auth는 auth schema 안에서 사용자 인증 정보를 관리합니다.

이 테이블은 앱의 일반적인 public 데이터 테이블과 역할이 다릅니다.

닉네임, 표시 이름, 앱 설정 같은 값을 저장하고 싶다고 auth.users에 앱 컬럼을 직접 추가하는 방식으로 시작하지 않습니다.

대신 public.profiles를 만들고 사용자 ID를 참조합니다.

auth.users
인증 계정

public.profiles
앱에서 사용하는 프로필

이렇게 나누면 인증 시스템과 앱 도메인 데이터를 분리할 수 있습니다.

profiles 설계

최소 프로필은 다음과 같습니다.

create table public.profiles (
  id uuid primary key
    references auth.users(id)
    on delete cascade,
  display_name text,
  created_at timestamptz not null default now()
);

id는 새로운 임의 UUID를 만드는 대신 Auth 사용자 ID와 동일한 값을 사용합니다.

한 사용자와 한 프로필을 1:1로 연결하기 쉽습니다.

on delete cascade는 Auth 사용자가 삭제될 때 연결된 프로필도 제거하는 정책입니다.

무조건 좋은 옵션은 아닙니다.

서비스가 탈퇴 후 데이터를 별도로 보관해야 한다면 다른 정책이 필요합니다.

제공된 예제 스키마는 Auth 사용자 삭제 시 연결된 프로필과 작업을 함께 정리하도록 선택했습니다. 서비스의 보관 요구가 다르다면 이 삭제 정책도 별도로 설계해야 합니다.

tasks 설계

create table public.tasks (
  id uuid primary key default gen_random_uuid(),
  owner_id uuid not null
    references public.profiles(id)
    on delete cascade,
  title text not null,
  status text not null default 'todo',
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

owner_id가 profiles.id를 참조합니다.

profiles.id 자체가 auth.users.id와 동일한 UUID이므로 이후 RLS에서 다음 비교를 사용할 수 있습니다.

(select auth.uid()) = owner_id

status 값 제한

이 예제의 작업은 다음 두 상태만 사용한다고 가정합니다.

todo
done

CHECK를 추가합니다.

constraint tasks_status_check
check (status in ('todo', 'done'))

이 제약 조건은 잘못된 문자열이 데이터베이스에 저장되는 것을 막습니다.

TypeScript union만으로 DB를 보호할 수 없다는 점이 중요합니다.

type TaskStatus = 'todo' | 'done';

프론트엔드 타입은 개발 편의와 정적 검사를 담당하고, 데이터베이스 CHECK는 실제 저장 규칙을 담당합니다.

둘 다 필요할 수 있습니다.

제목 길이도 DB에서 제한하기

constraint tasks_title_check
check (
  char_length(btrim(title))
  between 1 and 120
)

앞뒤 공백을 제거한 기준으로 1~120자여야 합니다.

UI의 maxLength와 DB의 CHECK는 같은 목적을 다른 계층에서 보완합니다.

외래키가 있다고 권한이 생기는 것은 아닙니다

외래키는 관계의 무결성을 확인합니다.

tasks.owner_id가
실제로 존재하는 profiles.id인가?

RLS는 접근 권한을 확인합니다.

현재 사용자가
이 tasks 행을 읽거나 수정할 수 있는가?

둘은 완전히 다른 역할입니다.

외래키를 만들었다고 다른 사용자 데이터 접근이 자동으로 차단되지는 않습니다.

테이블을 만든 직후 RLS부터 활성화

public schema는 Data API를 통해 노출될 수 있는 영역입니다.

따라서 테이블을 만든 뒤 다음 회차까지 열린 상태로 두지 않습니다.

alter table public.profiles
enable row level security;

alter table public.tasks
enable row level security;

그리고 현재 사용하지 않을 기본 권한을 닫습니다.

revoke all
on table public.profiles
from public, anon, authenticated;

revoke all
on table public.tasks
from public, anon, authenticated;

이번 회차에서는 사용자용 policy를 아직 만들지 않습니다.

따라서 publishable key로 profiles나 tasks를 읽거나 쓰려고 하면 차단되는 것이 정상입니다.

이것이 5회차의 완료 상태입니다.

테이블 생성
↓
관계 생성
↓
RLS ON
↓
기본 권한 닫기
↓
아직 사용자 접근 불가

6회차에서 필요한 GRANT와 RLS policy를 명시적으로 추가합니다.

기본 인덱스

tasks.owner_id는 사용자별 작업 목록의 핵심 조건이 됩니다.

create index tasks_owner_id_idx
on public.tasks(owner_id);

이번 회차에서는 이 정도만 둡니다.

status, created_at까지 조합한 복합 인덱스는 실제 쿼리를 만든 뒤 9회차에서 판단합니다.

인덱스를 많이 만드는 것이 목표가 아닙니다.

TypeScript Task 타입

lib/types/task.ts:

export type TaskStatus =
  | 'todo'
  | 'done';

export type Task = {
  id: string;
  owner_id: string;
  title: string;
  status: TaskStatus;
  created_at: string;
  updated_at: string;
};

export type CreateTaskInput = {
  title: string;
};

CreateTaskInput에 owner_id를 넣지 않습니다.

사용자가 폼에서 임의의 owner_id를 전달하는 구조를 만들지 않기 위해서입니다.

소유자는 현재 로그인 사용자로 결정합니다.

자주 발생하는 오류

auth.users에 display_name을 직접 추가하려 한다

앱 프로필을 public.profiles로 분리합니다.

tasks.owner_id에 외래키가 없다

존재하지 않는 사용자 UUID를 저장할 수 있는 구조가 됩니다.

외래키가 있으니 RLS가 없어도 된다고 생각한다

외래키는 데이터 관계, RLS는 접근 권한입니다.

RLS policy를 다음 회차에서 만들 예정이라 RLS 자체도 나중에 켠다

테이블 생성 직후 RLS를 활성화해 닫힌 상태부터 시작합니다.

학습 완료 체크리스트

• auth.users와 public.profiles의 역할 차이를 설명할 수 있습니다.
• profiles.id가 auth.users.id를 참조하는 이유를 알고 있습니다.
• tasks.owner_id가 profiles.id를 참조하는 이유를 알고 있습니다.
• FK와 RLS의 차이를 설명할 수 있습니다.
• CHECK와 TypeScript union의 역할 차이를 설명할 수 있습니다.
• 테이블 생성 직후 RLS를 활성화하는 이유를 알고 있습니다.
• 이번 회차 완료 시 사용자 API 접근이 차단되는 것이 정상임을 이해했습니다.

supabase-step-04-email-confirmation

supabase-step-03-auth-basics

Auth 사용자 존재
공개 lab 테이블 존재
실제 TaskFlow 관계형 모델 없음

supabase/
└─ migrations/
   └─ 05_taskflow_schema.sql

lib/
└─ types/
   └─ task.ts

docs/
└─ data-model.md

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=

node_modules/
.next/
.env.local
*.tsbuildinfo

export default function AuthConfirmedPage() {
  return (
    <main>
      <h1>이메일 확인 안내</h1>
      <p>메일의 확인 링크를 완료했다면 로그인 화면에서 이메일과 비밀번호로 로그인해 주세요.</p>
      <p>이 페이지를 열었다는 사실만으로 인증 상태를 판정하지 않습니다.</p>
    </main>
  );
}

import type { ReactNode } from "react";
export default function RootLayout({ children }: { children: ReactNode }) { return <html lang="ko"><body>{children}</body></html>; }

import { AuthForm } from '@/components/auth/auth-form';


export default function LoginPage() {
  return (
    <main>
      <h1>TaskFlow 로그인</h1>
      <AuthForm />
    </main>
  );
}

import Link from "next/link";
export default function Home() { return <main><h1>TaskFlow Supabase</h1><Link href="/tasks">작업 목록</Link> <Link href="/login">로그인</Link></main>; }

import { createPublicSupabaseClient } from '@/lib/supabase/public-server';


type PublicTask = {
  id: number;
  title: string;
  created_at: string;
};


export const dynamic = 'force-dynamic';


export default async function TasksPage() {
  const supabase = createPublicSupabaseClient();


  const { data, error } = await supabase
    .from('public_tasks_lab')
    .select('id, title, created_at')
    .order('id');


  if (error) {
    return (
      <main>
        <h1>TaskFlow</h1>
        <p>Supabase 데이터를 불러오지 못했습니다.</p>
        <pre>{error.message}</pre>
      </main>
    );
  }


  const tasks = (data ?? []) as PublicTask[];


  return (
    <main>
      <h1>TaskFlow</h1>


      {tasks.length === 0 ? (
        <p>공개 작업이 없습니다.</p>
      ) : (
        <ul>
          {tasks.map((task) => (
            <li key={task.id}>{task.title}</li>
          ))}
        </ul>
      )}
    </main>
  );
}

'use client';


import { FormEvent, useEffect, useState } from 'react';
import type { Session } from '@supabase/supabase-js';


import { createClient } from '@/lib/supabase/client';


export function AuthForm() {
  const supabase = createClient();


  const [session, setSession] = useState<Session | null>(null);
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [message, setMessage] = useState('');
  const [pending, setPending] = useState(false);


  useEffect(() => {
    void supabase.auth.getSession().then(({ data }) => {
      setSession(data.session);
    });


    const {
      data: { subscription },
    } = supabase.auth.onAuthStateChange((_event, nextSession) => {
      setSession(nextSession);
    });


    return () => subscription.unsubscribe();
  }, [supabase]);


  async function signUp(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setPending(true);
    setMessage('');


    const { data, error } = await supabase.auth.signUp({
      email,
      password,
    });


    setPending(false);


    if (error) {
      setMessage(error.message);
      return;
    }


    setMessage(
      data.session
        ? '가입과 로그인이 완료되었습니다.'
        : '가입 요청이 완료되었습니다. 이메일을 확인해 주세요.',
    );
  }


  async function signIn() {
    setPending(true);
    setMessage('');


    const { error } = await supabase.auth.signInWithPassword({
      email,
      password,
    });


    setPending(false);
    setMessage(error ? error.message : '로그인했습니다.');
  }


  async function signOut() {
    setPending(true);
    setMessage('');


    const { error } = await supabase.auth.signOut();


    setPending(false);
    setMessage(error ? error.message : '로그아웃했습니다.');
  }


  if (session) {
    return (
      <section>
        <p>로그인 상태입니다.</p>
        <p>{session.user.email}</p>
        <button type="button" onClick={signOut} disabled={pending}>
          로그아웃
        </button>
        {message && <p>{message}</p>}
      </section>
    );
  }


  return (
    <form onSubmit={signUp}>
      <label>
        이메일
        <input
          type="email"
          value={email}
          onChange={(event) => setEmail(event.target.value)}
          required
        />
      </label>


      <label>
        비밀번호
        <input
          type="password"
          value={password}
          onChange={(event) => setPassword(event.target.value)}
          minLength={8}
          required
        />
      </label>


      <button type="submit" disabled={pending}>
        회원가입
      </button>


      <button type="button" onClick={signIn} disabled={pending}>
        로그인
      </button>


      {message && <p>{message}</p>}
    </form>
  );
}

# Auth Email Template


## 대상


Confirm signup


## 제목


TaskFlow 회원가입을 확인해 주세요


## 버튼


이메일 확인하기


## 반드시 유지할 값


ConfirmationURL


## 검증


- 제목 확인
- 본문 확인
- 링크 존재 확인
- 클릭 후 이메일 확인 상태 확인
- redirect 확인


## 주의


2026-06-03 이후 무료 플랜 기본 이메일 발송 인프라의 템플릿 커스터마이징 제한을 발행/적용 시점에 다시 확인한다.

# Auth Redirect Checklist


- 로컬 Redirect URL 등록
- 운영 Redirect URL 등록
- Site URL 확인
- emailRedirectTo와 허용 URL 일치
- 링크 클릭 후 최종 이동 확인
- 실제 토큰/개인정보를 문서에 기록하지 않음

# TaskFlow Backend Choice


## 시작점


next-step-38-cache-update


## 선택


Supabase


## 이유


- PostgreSQL 관계형 데이터 모델을 직접 학습한다.
- Supabase Auth와 Postgres 사용자를 연결한다.
- GRANT와 RLS를 이용해 사용자별 데이터 격리를 학습한다.
- Next.js App Router에서 쿠키 기반 SSR 인증을 연결한다.
- 관계 조회와 인덱스까지 하나의 데이터 계층에서 학습한다.


## 이번 과정에서 사용하는 기능


- PostgreSQL
- Auth
- Data API
- Row Level Security
- @supabase/supabase-js
- @supabase/ssr


## 이번 과정에서 필수로 다루지 않는 기능


- Realtime
- Storage
- Edge Functions


필요 기능이 아니므로 과정 범위를 무리하게 늘리지 않는다.


## 보안 원칙


- 브라우저에는 publishable key만 사용한다.
- secret key는 클라이언트에 포함하지 않는다.
- 사용자 데이터는 RLS를 활성화한다.
- 화면에서 숨기는 것으로 권한 검증을 대신하지 않는다.
- 실제 인증 토큰과 개인정보를 학습 자료에 저장하지 않는다.


## 백엔드 트랙


Firebase 완료본을 이어서 수정하지 않는다.


Next.js TaskFlow 최종 체크포인트에서 별도 Supabase 브랜치를 시작한다.


## 다음 단계


Supabase 프로젝트를 만들고 공개 학습 데이터를 한 번 조회한다.

# TaskFlow Supabase Data Model


## Auth


auth.users
- Supabase Auth 계정
- 앱 프로필 데이터를 직접 추가하지 않음


## profiles


public.profiles
- id → auth.users.id
- display_name
- created_at


## tasks


public.tasks
- id
- owner_id → public.profiles.id
- title
- status
- created_at
- updated_at


## 관계


auth.users
→ public.profiles
→ public.tasks


## 보안 상태


profiles RLS enabled
tasks RLS enabled


anon 권한 없음
authenticated 권한 없음


6회차에서 필요한 GRANT와 RLS policy를 추가한다.

<h2>TaskFlow 회원가입을 확인해 주세요</h2>


<p>
  TaskFlow 회원가입이 요청되었습니다.
</p>


<p>
  아래 버튼을 눌러 이메일 확인을 완료해 주세요.
</p>


<p>
  <a href="{{ .ConfirmationURL }}">
    이메일 확인하기
  </a>
</p>


<p>
  회원가입을 요청하지 않았다면 이 메일을 무시해 주세요.
</p>

<h2>Confirm your signup</h2>


<p>Follow this link to confirm your user:</p>


<p>
  <a href="{{ .ConfirmationURL }}">
    Confirm your mail
  </a>
</p>

'use client';


import { createClient as createSupabaseClient, type SupabaseClient } from '@supabase/supabase-js';


let client: SupabaseClient | undefined;


export function createClient() {
  if (client) {
    return client;
  }


  const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
  const key = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY;


  if (!url || !key) {
    throw new Error('Supabase 공개 설정이 필요합니다.');
  }


  client = createSupabaseClient(url, key);


  return client;
}

import 'server-only';


import { createClient } from '@supabase/supabase-js';


export function createPublicSupabaseClient() {
  const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
  const key = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY;


  if (!url || !key) {
    throw new Error('Supabase 공개 설정이 필요합니다.');
  }


  return createClient(url, key, {
    auth: {
      persistSession: false,
      autoRefreshToken: false,
      detectSessionInUrl: false,
    },
  });
}

export type TaskStatus =
  | 'todo'
  | 'done';


export type Task = {
  id: string;
  owner_id: string;
  title: string;
  status: TaskStatus;
  created_at: string;
  updated_at: string;
};


export type CreateTaskInput = {
  title: string;
};

/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts";
import "./.next/types/root-params.d.ts";

// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

{
  "name": "taskflow-supabase-checkpoint",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "next": "16.3.5",
    "react": "19.3.0",
    "react-dom": "19.3.0",
    "@supabase/supabase-js": "2.116.0",
    "server-only": "0.0.1"
  },
  "devDependencies": {
    "typescript": "5.9.3",
    "@types/node": "24.10.1",
    "@types/react": "19.2.7",
    "@types/react-dom": "19.2.3"
  }
}

# Supabase 05 완료 체크포인트 — relational-schema

원문 회차 코드를 누적한 독립 실행용 최소 Next.js App Router 학습 앱입니다. 이전 Next.js 38편 앱 전체나 추가 CRUD 화면을 복제한 프로젝트가 아닙니다.

Node.js 24.18.0, npm 11.16.0 기준입니다.

1. `npm ci`
2. `.env.example`을 `.env.local`로 복사하고 개발 전용 Supabase URL/publishable key를 입력합니다.
3. 아래 순서대로 개발 DB에 해당 SQL을 한 번씩 적용합니다. 같은 객체가 있으면 덮어쓰지 않습니다.
4. `npm run dev` 후 `/tasks`를 확인합니다.
5. `npm run typecheck` 및 `npm run build`를 실행합니다.

SQL: `supabase/learning/02_public_tasks_lab.sql` → `supabase/migrations/05_taskflow_schema.sql`.

`/login`은 이메일/비밀번호 인증 화면입니다. 실제 가입/확인 메일은 본인 개발 프로젝트에서 직접 검증하세요.

실제 secret/service_role 키, 비밀번호, 원격 DB 계정은 포함하지 않습니다. node_modules/.next/.env.local은 제외했습니다. ZIP의 package-lock.json으로 정확한 의존성을 재현하세요.

begin;


create table public.public_tasks_lab (
  id bigint generated always as identity primary key,
  title text not null,
  created_at timestamptz not null default now()
);


insert into public.public_tasks_lab (title)
values
  ('Supabase 연결 확인'),
  ('RLS 공개 읽기 확인');


alter table public.public_tasks_lab
enable row level security;


revoke all
on table public.public_tasks_lab
from public, anon, authenticated;


grant select
on table public.public_tasks_lab
to anon, authenticated;


create policy "public_tasks_lab_read"
on public.public_tasks_lab
for select
to anon, authenticated
using (true);


commit;

begin;


create table public.profiles (
  id uuid primary key
    references auth.users(id)
    on delete cascade,
  display_name text,
  created_at timestamptz not null default now()
);


create table public.tasks (
  id uuid primary key default gen_random_uuid(),
  owner_id uuid not null
    references public.profiles(id)
    on delete cascade,
  title text not null,
  status text not null default 'todo',
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now(),


  constraint tasks_status_check
    check (status in ('todo', 'done')),


  constraint tasks_title_check
    check (
      char_length(btrim(title))
      between 1 and 120
    )
);


create index tasks_owner_id_idx
on public.tasks(owner_id);


alter table public.profiles
enable row level security;


alter table public.tasks
enable row level security;


revoke all
on table public.profiles
from public, anon, authenticated;


revoke all
on table public.tasks
from public, anon, authenticated;


commit;

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": [
        "./*"
      ]
    },
    "allowJs": true
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts",
    ".next/dev/types/**/*.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}

select
  table_name
from information_schema.tables
where table_schema = 'public'
  and table_name in ('profiles', 'tasks');

supabase-step-05-relational-schema

다음 학습

다음 글에서는 닫아 둔 profiles와 tasks에 필요한 권한만 엽니다.

로그인한 사용자는 자신의 profile과 tasks만 다룰 수 있게 만들고, 두 계정 A/B로 데이터 격리를 검증합니다.

다음 글:

Supabase 사용자별 CRUD와 RLS: 두 계정으로 데이터 격리 검증하기

공식 문서

확인일: 2026-09-21

• Supabase Auth: https://supabase.com/docs/guides/auth
• Row Level Security: https://supabase.com/docs/guides/database/postgres/row-level-security
• Managing User Data: https://supabase.com/docs/guides/auth/managing-user-data