SQL Connect 스키마 설계

Firebase SQL Connect를 사용하면 애플리케이션에 필요한 데이터 모델을 나타내는 GraphQL 스키마를 설계할 수 있습니다. SQL Connect는 이 스키마를 앱을 지원하는 PostgreSQL용 Cloud SQL 인스턴스로 변환합니다. 그런 다음 쿼리 및 변형을 작성하여 백엔드와 상호작용하고 이러한 작업을 클라이언트 코드에서 데이터를 사용하는 커넥터로 번들링합니다.

SQL Connect는 스키마를 설계하고 구현하는 데 도움이 되는 AI 도구를 제공합니다. 이 가이드에서는 앱 개발을 시작할 때 표준 및 AI 지원 워크플로를 지원하고 보완하는 스키마 설계의 중요한 개념을 소개합니다. 앱 개발을 시작할 때뿐만 아니라 그 이후에도 말이죠.

시작하기 가이드에서는 PostgreSQL용 영화 리뷰 앱 스키마를 소개했습니다.

이 가이드에서는 해당 스키마를 추가로 개발하고 최종 영화 리뷰 앱 스키마와 동일한 SQL 목록 을 제공합니다.

영화 리뷰 앱의 스키마

사용자가 영화 리뷰를 제출하고 볼 수 있는 서비스를 빌드한다고 가정해 보겠습니다.

기본 쿼리를 지원하려면 이러한 앱의 초기 스키마가 필요합니다. 나중에 이 스키마를 확장하여 복잡한 관계형 쿼리를 만듭니다.

SQL Connect에서 클라이언트가 쿼리하고 조작할 수 있는 데이터의 형태를 정의하기 위해 GraphQL 유형을 정의합니다. 스키마를 작성할 때 유형은 PostgreSQL용 Cloud SQL 테이블로 변환됩니다. GraphQL 유형과 데이터베이스 테이블 간의 직접적인 관계가 가장 일반적이지만 다른 매핑도 가능합니다. 이 가이드에서는 기본부터 고급까지 몇 가지 예를 보여줍니다.

기본 Movie 유형 정의

Movie 유형으로 시작할 수 있습니다.

Movie의 스키마에는 다음과 같은 핵심 지시어가 포함되어 있습니다.

• SQL 테이블 및 열 이름을 맞춤설정하는 @table(name) 및 @col(name). SQL Connect는 지정되지 않은 경우 snake_case 이름을 생성합니다.
• SQL 열 유형을 맞춤설정하는 @col(dataType).
• 삽입 중에 SQL 열 기본값을 구성하는 @default.

자세한 내용은 @table, @col, @default의 참조 문서를 확인하세요.

# Movies
type Movie @table(name: "movie", key: "id") {
  id: UUID! @col(name: "movie_id") @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int
  genre: String @col(dataType: "varchar(20)")
  rating: Int
  description: String
}

User 유형에 중요한 사용자 데이터 자동 저장

앱에서 사용자를 추적하므로 User 유형이 필요합니다.

@default 지시어는 이 경우에 특히 유용합니다. 여기서 id 필드는 인증에서 사용자 ID를 자동으로 가져올 수 있습니다. 다음 샘플에서 @default(expr: "auth.uid")의 사용에 유의하세요.

# Users
# Suppose a user can leave reviews for movies
type User @table {
  id: String! @default(expr: "auth.uid")
  username: String! @col(dataType: "varchar(50)")
}

주요 스칼라 및 서버 값

영화 리뷰 앱을 자세히 살펴보기 전에 SQL Connect 주요 스칼라 및 서버 값을 소개하는 것이 중요합니다.

주요 스칼라 는 SQL Connect가 스키마의 키 필드에서 SQL Connect 자동으로 어셈블하는 간결한 객체 식별자입니다. 주요 스칼라는 효율성에 관한 것으로, 단일 호출에서 데이터의 ID 및 구조에 관한 정보를 찾을 수 있습니다. 새 레코드에서 순차적 작업을 실행하고 향후 작업에 전달할 고유 식별자가 필요한 경우, 또한 관계형 키에 액세스하여 더 복잡한 작업을 실행하려는 경우에 특히 유용합니다.

서버 값을 사용하면 서버에서 저장되거나 쉽게 계산할 수 있는 값을 사용하여 테이블의 필드를 동적으로 채울 수 있습니다. expr 인수의 특정 서버 측 CEL 표현식에 따라 예를 들어 작업 요청에 저장된 시간을 사용하여 필드에 액세스할 때 타임스탬프가 적용된 필드를 정의할 수 있습니다(updatedAt: Timestamp! @default(expr: "request.time")).

Actor 및 MovieActor 유형에서 다대다 관계 처리

사용자가 처리되면 영화 데이터 모델링으로 돌아갈 수 있습니다.

다음으로 배우가 영화에 출연하도록 하려고 합니다.

Actor 테이블은 매우 간단합니다.

# Actors
# Suppose an actor can participate in multiple movies and movies can have multiple actors
# Movie - Actors (or vice versa) is a many to many relationship
type Actor @table {
  id: UUID! @default(expr: "uuidV4()")
  name: String! @col(dataType: "varchar(30)")
}

배우가 여러 영화에 출연하고 영화에 여러 배우가 출연하도록 하려면 '조인 테이블'이 필요합니다.

MovieActor 테이블은 다대다 관계를 처리하며 기본 키는 [movie, actor] (movie 및 actor의 외래 키 필드)의 조합입니다.

# Join table for many-to-many relationship for movies and actors
# The 'key' param signifies the primary keys of this table
# In this case, the keys are [movieId, actorId], the foreign key fields of the reference fields [movie, actor]
type MovieActor @table(key: ["movie", "actor"]) {
  movie: Movie!
  # movieId: UUID! <- implicitly added foreign key field
  actor: Actor!
  # actorId: UUID! <- implicitly added foreign key field
  role: String! # "main" or "supporting"
  # optional other fields
}

외래 키 제약조건이 있는 테이블에서 SQL 관계를 정의하면 SQL Connect 다른 쪽에 해당하는 필드를 자동으로 생성합니다. 역방향 매핑 필드 (예: Actor에서 MovieActor로 다시)를 정의할 필요가 없습니다.

MovieMetadata 유형에서 일대일 관계 처리

이제 영화 감독을 추적하고 Movie와의 일대일 관계를 설정합니다.

@ref 지시어를 사용하여 외래 키 제약조건을 맞춤설정할 수 있습니다.

• @ref(fields)는 사용할 외래 키 필드를 지정합니다.
• @ref(references) 는 타겟 테이블에서 참조되는 필드를 지정합니다(기본값은 기본 키이지만 @unique 필드도 작동함). 이는 고급 옵션입니다. SQL Connect는 종종 이를 추론할 수 있습니다.

자세한 내용은 @ref의 참조 문서를 확인하세요.

# Movie Metadata
# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
  # @unique ensures that each Movie only has one MovieMetadata.
  movie: Movie! @unique
  # Since it references to another table type, it adds a foreign key constraint.
  #  movie: Movie! @unique @ref(fields: "movieId", references: "id")
  #  movieId: UUID! <- implicitly added foreign key field
  director: String
}

스키마에서 생성된 필드를 사용하여 작업 빌드

SQL Connect 작업은 스키마의 유형 및 유형 관계를 기반으로 SQL Connect에서 자동으로 생성하는 필드 집합 을 확장합니다. 이러한 필드는 스키마를 수정할 때마다 로컬 도구에서 생성됩니다.

스키마에 Movie 유형과 연결된 Actor 유형이 포함되어 있다고 가정해 보겠습니다. SQL Connect는 movie, movies, actors_on_movies 필드 등을 생성합니다.

query GetMovie($myKey: Movie_Key!) {
  movie(key: $myKey) { title }
}

query GetMovies($myYear: Int!) {
  movies(where: { year: { eq: $myYear } }) { title }
}

  query GetActorsOnMovie($myKey: Movie_Key!) {
    actors_on_movies(where: { movie: { key: { eq: $myKey } } }) {
      actor { name }
    }
  }

이를 염두에 두고 이러한 필드를 사용하여 작업을 구현하는 방법을 쿼리 구현 가이드 및 변형 구현 가이드에서 읽어보세요.

고급 스키마 개념

열거형 필드

SQL Connect는 PostgreSQL 열거형 유형에 매핑되는 열거형 필드를 지원합니다. 열거형을 사용하면 특정 순서로 정적이고 미리 정의된 값 목록을 빠르게 정의할 수 있습니다.

스키마에 열거형을 추가하려면 열거형과 미리 정의된 값을 선언한 후 유형에서 참조합니다.

enum AspectRatio {
   ACADEMY
   WIDESCREEN
   ANAMORPHIC
   IMAX
   "No information available on aspect ratio"
   UNAVAILABLE
}

type Movie
  @table {
  title: String! 
  genre: String
  description: String
  originalAspectRatio: AspectRatio! @default(value: WIDESCREEN)
  otherAspectRatios: [AspectRatio!]
  tags: [String]
  rating: Float
  imageUrl: String!
  releaseYear: Int
}

Movie 유형에서 영화가 촬영된 화면 비율의 열거형 필드 originalAspectRatio와 사용 가능한 다른 화면 비율 목록의 다른 필드 otherAspectRatios를 추가했습니다.

열거형 필드 변경사항 관리

열거형에 새 값을 추가할 수 있지만 열거형 목록의 순서는 매우 중요하므로 새 값을 신중하게 삽입하세요. 열거형에 완전히 하위 호환되는 변경사항은 값 목록의 끝에 새 값을 추가하는 것뿐입니다. 특히 이전에 게시된 열거형 사이에 새 값을 삽입하거나 기존 값의 순서를 변경하면 쿼리에서 '보다 작음'과 같은 상대 연산자를 사용할 때 상대적 순서가 변경됩니다. 값을 삭제하거나 이름을 바꾸는 것은 항상 하위 호환되지 않는 변경사항입니다.

열거형 값 목록에서 값의 순서를 변경해서는 안 됩니다. 순서는 필터링이 적용되는 방식을 변경하므로 중요합니다.

열거형 값 조정은 이전 버전의 작업 또는 클라이언트 코드를 손상시키지 않도록 신중하게 실행해야 합니다. 열거형 값을 삭제하거나 이름을 바꿀 때는 현재 데이터베이스에 남아 있는 인스턴스가 없는지 확인하세요.

작업 및 클라이언트 코드에서 열거형 필드 사용

이제 스키마에 열거형 필드를 추가했으므로 쿼리 및 클라이언트 코드에서 이 필드를 사용할 수 있습니다.

열거형을 사용하여 쿼리를 작성하는 방법과 쿼리 가이드에서 시작하여 열거형을 조정할 수 있도록 클라이언트를 작성하는 방법을 자세히 알아보세요.

기타 고급 개념

기본적이지만 유용한 유형과 관계를 넘어선 고급 개념을 알아보려면 참고 문서의 예를 참고하세요.

지원되는 데이터 유형

SQL Connect는 @col(dataType:)을 사용하여 PostgreSQL 유형에 할당되는 다음 스칼라 데이터 유형을 지원합니다.

• GraphQL List는 1차원 배열에 매핑됩니다.
  • 예를 들어 [Int]는 int5[]에 매핑되고 [Any]는 jsonb[]에 매핑됩니다.
  • SQL Connect는 중첩된 배열을 지원하지 않습니다.

동등한 SQL 스키마

-- Movies Table
CREATE TABLE Movies (
    movie_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    release_year INT,
    genre VARCHAR(30),
    rating INT,
    description TEXT,
    tags TEXT[]
);
-- Movie Metadata Table
CREATE TABLE MovieMetadata (
    movie_id UUID REFERENCES Movies(movie_id) UNIQUE,
    director VARCHAR(255) NOT NULL,
    PRIMARY KEY (movie_id)
);
-- Actors Table
CREATE TABLE Actors (
    actor_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    name VARCHAR(30) NOT NULL
);
-- MovieActor Join Table for Many-to-Many Relationship
CREATE TABLE MovieActor (
    movie_id UUID REFERENCES Movies(movie_id),
    actor_id UUID REFERENCES Actors(actor_id),
    role VARCHAR(50) NOT NULL, # "main" or "supporting"
    PRIMARY KEY (movie_id, actor_id),
    FOREIGN KEY (movie_id) REFERENCES Movies(movie_id),
    FOREIGN KEY (actor_id) REFERENCES Actors(actor_id)
);
-- Users Table
CREATE TABLE Users (
    user_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    user_auth VARCHAR(255) NOT NULL
    username VARCHAR(30) NOT NULL
);
-- Reviews Table
CREATE TABLE Reviews (
    review_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    user_id UUID REFERENCES Users(user_id),
    movie_id UUID REFERENCES Movies(movie_id),
    rating INT,
    review_text TEXT,
    review_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (movie_id, user_id)
    FOREIGN KEY (user_id) REFERENCES Users(user_id),
    FOREIGN KEY (movie_id) REFERENCES Movies(movie_id)
);
-- Self Join Example for Movie Sequel Relationship
ALTER TABLE Movies
ADD COLUMN sequel_to UUID REFERENCES Movies(movie_id);

다음 단계

다음 항목에 관심이 있을 수 있습니다.

• AI 지원 도구를 사용하여 앱의 스키마 생성
• 문법 참고 문서 검토