빠른 시작 가이드

5분 안에 Connect Base를 프로젝트에 연동하는 방법입니다.

0. 사전 준비 (콘솔 작업, 약 1분)

⚠️ 코드 작성 전에 콘솔에서 앱과 Public Key를 먼저 발급해야 합니다.

https://connectbase.world 에 접속해서 로그인합니다.
좌측 사이드바에서 앱 (Apps) → 새 앱 만들기를 클릭합니다.
앱 이름을 입력하고 생성합니다.
생성된 앱의 설정 (Settings) → Public Keys 메뉴로 이동합니다.
새 Public Key 생성 버튼을 클릭하고 cb_pk_... 로 시작하는 키를 복사합니다.

⚠️ 주의: Public Key (cb_pk_*)는 한 번만 표시됩니다. 안전한 곳에 저장하세요.

1. SDK 설치

bash

# npm
npm install connectbase-client

# yarn
yarn add connectbase-client

# pnpm
pnpm add connectbase-client

2. 환경 변수 설정

프로젝트 루트에 .env 파일을 생성합니다.

bash

# Vite (React/Vue/Svelte)
VITE_CONNECT_BASE_PUBLIC_KEY=cb_pk_your_public_key_here

# Next.js (브라우저 노출 가능)
NEXT_PUBLIC_CONNECT_BASE_PUBLIC_KEY=cb_pk_your_public_key_here

# Node.js / Express
CONNECT_BASE_PUBLIC_KEY=cb_pk_your_public_key_here

💡 클라이언트(브라우저)에서는 반드시 cb_pk_* (Public Key)를 사용하세요. 서버 전용 키 cb_sk_* (Secret Key)를 노출하면 권한이 탈취됩니다.

3. SDK 초기화

typescript

import ConnectBase from 'connectbase-client'

const cb = new ConnectBase({
  publicKey: import.meta.env.VITE_CONNECT_BASE_PUBLIC_KEY
})

4. 데이터 저장하기

📌 데이터를 저장하려면 콘솔의 데이터베이스 → 테이블 만들기에서 먼저 테이블을 생성하고 생성된 테이블의 ID(tbl_xxx 형식)를 복사해 두세요.

typescript

// cb.database.createData(tableId, { data })
const created = await cb.database.createData('tbl_your_table_id', {
  data: {
    name: '홍길동',
    email: '[email protected]',
    age: 30
  }
})
// 응답: { id, data, created_at, updated_at }
console.log(created.id) // 생성된 row 의 UUID

📌 createData 는 201 Created 와 함께 생성된 row 전체(DataItem)를 반환합니다. 직후 업데이트/삭제/캐시 반영에 created.id 를 바로 쓸 수 있습니다.

5. 데이터 조회하기

typescript

// 전체 조회 (페이지네이션)
const all = await cb.database.getData('tbl_your_table_id', {
  limit: 20,
  offset: 0
})
console.log(all.data)      // DataItem[]
console.log(all.total_count) // 전체 row 개수

// 조건 조회 (where + orderBy + limit)
const adults = await cb.database.queryData('tbl_your_table_id', {
  where: { age: { $gte: 18 } },
  orderBy: 'created_at',
  orderDirection: 'desc',
  limit: 10
})
console.log(adults.data)

6. 파일 업로드 (옵션)

📌 콘솔에서 스토리지 (Storage) → 파일 스토리지 만들기로 스토리지를 먼저 생성하고 스토리지 ID(stg_xxx)를 복사해 두세요.

html

<input type="file" id="avatar" />

typescript

const input = document.getElementById('avatar') as HTMLInputElement
const file = input.files?.[0]
if (!file) throw new Error('파일을 선택해주세요')

// cb.storage.uploadFile(storageId, file, parentId?)
const result = await cb.storage.uploadFile('stg_your_storage_id', file)
console.log('업로드된 파일 URL:', result.url)

완료!

축하합니다 🎉 Connect Base에 성공적으로 첫 데이터를 저장했습니다.

다음 30분 로드맵

5분 quickstart 직후 추천 학습 순서:

순서	문서	소요
1	실시간 통신 — WebSocket으로 채팅·알림 만들기	10분
2	사용자 인증 — 회원가입 / 로그인 / 세션 관리	10분
3	파일 스토리지 — 업로드 진행률 / 폴더 관리	10분

막히면 흔한 에러 & 해결책 페이지를 확인하세요.

Connect Base 소개

SDK 설치