supalite 0.6.1 → 0.7.2

package/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: ci
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U postgres"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=5
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - run: npm ci
+      - name: Initialize test database
+        env:
+          PGPASSWORD: postgres
+        run: psql -h localhost -U postgres -f setup-postgres-test.sql
+
+      - run: npm run build
+      - run: npm test
+        env:
+          DB_CONNECTION: postgresql://testuser:testpassword@localhost:5432/testdb
+      - run: npm run lint

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.7.2] - 2026-01-17
+
+### ✨ Added
+- `--no-bigint` 옵션을 추가해 BIGINT를 `number`로 출력할 수 있습니다.
+
+### 🐞 Fixed
+- `js-yaml` 의존성을 보안 패치 버전으로 업데이트했습니다. (prototype pollution 대응)
+
+## [0.7.1] - 2026-01-17
+
+### ✨ Added
+- `supalite gen types` 기본 출력이 Supabase CLI 포맷과 최대한 동일하도록 정렬/포맷/헬퍼 타입/Constants를 추가했습니다.
+- `--format supabase|supalite`, `--bigint-type`, `--json-bigint` 옵션을 추가했습니다.
+- Supabase 포맷에서 insertable view에 `Insert`/`Update`를 포함하고, 함수 오버로드 출력 형태를 Supabase와 맞췄습니다.
+
+### 🔧 Changed
+- Supabase 포맷 기본값 기준으로 관계/복합 타입/함수 시그니처가 기본 포함됩니다. (legacy 출력은 `--format supalite`)
+
+## [0.7.0] - 2026-01-17
+
+### ✨ Added
+- `supalite gen types` CLI to generate TypeScript Database types from PostgreSQL schemas.
+- BIGINT columns are emitted as `bigint` in the generated types.
+- `--date-as-date` option to map `date`/`timestamp` columns to `Date` in generated types.
+- `--include-relationships`, `--include-constraints`, `--include-indexes` options to emit schema metadata.
+- `--include-composite-types` and `--include-function-signatures` options for composite types and typed function signatures.
+- `--type-case` and `--function-case` options to control enum/composite and function key casing.
+- `--dump-functions-sql` option to export `CREATE FUNCTION/PROCEDURE` definitions to a local file.
+- Added gen-types seed/cleanup scripts and limitations docs.
+
 ## [0.6.1] - 2026-01-16
 
 ### ✨ Added

package/README.ko.md

@@ -1,8 +1,31 @@
 # SupaLite
+Supabase가 서버리스 지연으로 느리게 느껴진다면, DB 쿼리에는 SupaLite가 더 빠른 대안이 될 수 있습니다.
 
 [![npm version](https://img.shields.io/npm/v/supalite.svg)](https://www.npmjs.com/package/supalite)
+[![npm downloads](https://img.shields.io/npm/dm/supalite.svg)](https://www.npmjs.com/package/supalite)
+[![license](https://img.shields.io/npm/l/supalite.svg)](LICENSE)
+[![types](https://img.shields.io/npm/types/supalite.svg)](https://www.npmjs.com/package/supalite)
+[![node](https://img.shields.io/node/v/supalite.svg)](https://www.npmjs.com/package/supalite)
+[![ci](https://img.shields.io/github/actions/workflow/status/genideas-labs/supalite/ci.yml?branch=main)](https://github.com/genideas-labs/supalite/actions/workflows/ci.yml)
 
-가볍고 효율적인 PostgreSQL 클라이언트 라이브러리입니다. Supabase와 동일한 API를 제공하면서도 더 가볍고 빠른 구현을 제공합니다.
+Supabase 쿼리 빌더에 집중한 가벼운 PostgreSQL 클라이언트입니다. 익숙한 API를 유지하면서도 표면적을 줄여 더 작은 풋프린트와 낮은 오버헤드를 목표로 합니다.
+
+한 줄 요약: **SupaLite는 쿼리 빌더 + RPC + 트랜잭션에 집중한 슬림 Supabase 클라이언트입니다.** Auth/Storage/Realtime까지 필요하면 `supabase-js`를 사용하세요.
+
+실서비스 사용: [oqoq.ai](https://oqoq.ai)
+
+호환 범위 요약:
+- ✅ 조회/필터/정렬/페이지네이션
+- ✅ PostgREST 임베드 (`related_table(*)`, `!inner`)
+- ✅ Insert/Update/Delete/Upsert (`ignoreDuplicates` 포함)
+- ✅ RPC (`single`/`maybeSingle` 포함)
+- ❌ Auth/Storage/Realtime
+
+클라우드 마이그레이션 안내 (GCP/AWS):
+Supabase에서 완전히 분리하려면 SupaLite는 **DB 쿼리 계층만** 대체합니다. Auth/Storage/Realtime은 별도 대안이 필요합니다.
+- Auth: 관리형 인증(AWS Cognito / Google Identity Platform) 또는 자체 호스팅(GoTrue/Keycloak)
+- Storage: 오브젝트 스토리지(S3 / GCS)
+- Realtime: 관리형 pub/sub, WebSocket 서비스, 또는 PostgreSQL LISTEN/NOTIFY + 자체 게이트웨이
 
 ## 주요 기능
 
@@ -17,6 +40,127 @@
 - 🔍 고급 필터링: OR 조건, ILIKE 검색 등 지원
 - 📚 배열 작업: 다중 레코드 삽입 및 배열 데이터 처리 (JSON/JSONB 필드 포함)
 - 🔄 Views, Functions, Enums 지원: Supabase 스타일의 완벽한 타입 지원
+- 🧮 BigInt 대응: JSON 안전 변환 옵션 제공
+
+## 프로젝트 범위
+
+SupaLite는 Supabase 클라이언트의 **일부 기능(쿼리 빌더, RPC, 트랜잭션)**에 집중합니다. Auth/Storage/Realtime 같은 기능까지 포함하는 전체 호환을 목표로 하지는 않습니다. 지원되는 쿼리 패턴은 아래에 정리되어 있으며, 빠진 패턴이 있으면 이슈로 알려주세요.
+
+## 마이그레이션 및 스키마 관리
+
+SupaLite는 ORM을 최소화합니다. 마이그레이션/스키마 관리는 전용 도구를 사용하는 것이 현실적입니다.
+- 마이그레이션/스키마 동기화: [pg-schema-sync](https://github.com/genideas-labs/pg-schema-sync)
+- 대안: Atlas, dbmate, Sqitch, Goose, Flyway
+- 타입 생성: `supabase gen types typescript --db-url <postgres_url>` (DB URL만 있어도 가능)
+
+ORM 기능(관계 모델링/중첩 쓰기 등)이 꼭 필요하면 Prisma/Drizzle/Kysely를 별도 서비스로 병행하는 방식을 권장합니다. SupaLite를 가볍게 유지하는 것이 핵심 가치입니다.
+
+`supabase db pull`에 대해서: 이는 ORM 기능이 아니라 마이그레이션/스키마 동기화 단계입니다. SupaLite 내부에 구현하기보다 “권장 워크플로우”로 문서화하고, 필요하다면 `pg-schema-sync` + 타입 생성기를 묶는 간단한 CLI 래퍼가 현실적입니다.
+
+SupaLite는 `supalite gen types`를 포함하며, 기본 출력은 SupaLite 포맷(Supabase CLI 출력의 상위 집합)입니다. Supabase CLI와 1:1로 맞추려면 `--format supabase`를 사용하세요.
+
+## SupaLite vs Prisma / Drizzle
+
+SupaLite는 SQL에 가까운 가벼운 쿼리 클라이언트입니다. Prisma/Drizzle은 스키마 중심의 ORM과 마이그레이션을 제공합니다.
+
+SupaLite가 적합한 경우:
+- 최소한의 추상화로 쿼리 레이어만 얇게 두고 싶을 때
+- Supabase에서 이동하면서 유사한 쿼리 문법을 유지하고 싶을 때
+- 마이그레이션과 스키마 관리는 별도로 하고 있을 때
+
+Prisma/Drizzle이 적합한 경우:
+- 스키마 중심 모델링과 내장 마이그레이션이 필요할 때
+- 관계/중첩 쓰기 등 ORM 기능을 적극 활용할 때
+- 스키마 파일 기반의 강한 타입 보장을 원할 때
+
+트레이드오프:
+- SupaLite는 간단하고 SQL에 가깝지만 ORM 모델링/마이그레이션 도구는 없습니다.
+- Prisma/Drizzle은 기능이 풍부한 대신 추상화 레이어가 추가됩니다.
+- SupaLite는 BIGINT를 JSON 안전하게 변환하는 옵션을 기본 제공한다는 점이 장점입니다.
+- Prisma/Drizzle은 BIGINT의 JSON 직렬화/정밀도 선택을 호출부에서 처리해야 하는 경우가 많지만, SupaLite는 `bigintTransform`으로 일관되게 설정할 수 있습니다.
+
+## 예제 비교 (SupaLite vs Prisma vs Drizzle)
+
+SupaLite는 Supabase 스타일 네이밍을 유지해 SQL과 유사하게 읽히도록 설계했습니다. 아래는 동일 쿼리의 비교입니다.
+
+작업: `status = 'active'` 사용자 조회, `created_at` 내림차순, 2페이지(페이지당 10건).
+
+SupaLite:
+```typescript
+const page = 2;
+const pageSize = 10;
+const { data } = await client
+  .from('users')
+  .select('id, name, email, created_at')
+  .eq('status', 'active')
+  .order('created_at', { ascending: false })
+  .limit(pageSize)
+  .offset((page - 1) * pageSize);
+```
+
+Prisma:
+```typescript
+const page = 2;
+const pageSize = 10;
+const data = await prisma.user.findMany({
+  select: { id: true, name: true, email: true, created_at: true },
+  where: { status: 'active' },
+  orderBy: { created_at: 'desc' },
+  take: pageSize,
+  skip: (page - 1) * pageSize,
+});
+```
+
+Drizzle:
+```typescript
+const page = 2;
+const pageSize = 10;
+const data = await db
+  .select({ id: users.id, name: users.name, email: users.email, created_at: users.createdAt })
+  .from(users)
+  .where(eq(users.status, 'active'))
+  .orderBy(desc(users.createdAt))
+  .limit(pageSize)
+  .offset((page - 1) * pageSize);
+```
+
+## 로드맵 (단기)
+
+- Node/pg 버전별 CI 매트릭스와 통합 테스트
+- 벤치마크 및 성능 가이드
+- Auth/Storage/Realtime 마이그레이션 가이드 (Cognito/GIP, S3/GCS, Realtime 대안)
+- `supalite gen types` (SupaLite 중심 타입 생성기, Supabase 포맷 옵션 제공)
+- 기여 가이드/이슈 템플릿
+
+## 성능 노트 (서버리스 Supabase vs 클라우드 Postgres)
+
+서버리스 Supabase에서 GCP/AWS의 관리형 Postgres로 이동할 때 일반적으로 기대할 수 있는 차이:
+- 네트워크 hop: Supabase는 edge/API/REST 계층이 추가될 수 있고, 동일 VPC 내 직접 접속은 hop이 줄어듭니다.
+- 콜드스타트/풀링: 서버리스는 cold start나 aggressive pooling이 있을 수 있어, 전용 풀러(pgBouncer/RDS Proxy)가 tail latency를 낮춥니다.
+- 네트워크 경로: 공용망 vs VPC/피어링에 따라 jitter와 p95/p99가 달라집니다.
+- 오버헤드: HTTP/PostgREST 계층 직렬화 비용이 추가되며, 직접 SQL 클라이언트는 이를 줄입니다.
+
+벤치마크 수치: **TBD (출처 필요)**. 공개된 벤치마크 링크가 있으면 PR로 공유해 주세요.
+필요한 출처:
+- 서버리스 Postgres vs 관리형 Postgres 지연/풀링 비교에 대한 공개 자료 링크
+
+## 벤치마크 방법론 (초안)
+
+- 워크로드: 단순 `select`, 필터+정렬 `select`, `insert`, `rpc`
+- warm/cold 구분, p50/p95/p99 측정
+- 동일 리전/인스턴스 크기, DB 버전/풀 설정 기록
+- 가능하면 네트워크/쿼리 시간 분리 측정
+- 스크립트/원본 결과 공개
+
+## SupaLite를 선택해야 하는 이유
+
+- PostgREST hop 없이 PostgreSQL에 직접 연결해 더 낮은 레이턴시
+- Supabase 스타일의 SQL 유사 API로 마이그레이션이 쉬움
+- native `bigint` 지원 및 변환 옵션 제공
+- Supabase 클라이언트에서 불가능한 트랜잭션/멀티 스텝 플로우 지원
+- 관계/제약/인덱스/함수 시그니처까지 포함 가능한 타입 생성기
+
+알려진 트레이드오프는 `docs/limitations.ko.md`를 참고하세요.
 
 ## 설치 방법
 
@@ -24,13 +168,25 @@
 npm install supalite
 ```
 
+### CLI
+
+```bash
+npm install -g supalite
+```
+
+```bash
+supalite gen types --help
+```
+
+전역 설치 없이 `npx supalite ...`로도 사용 가능합니다.
+
 ## 타입 시스템
 
 ### 데이터베이스 스키마 정의
 
 ```typescript
-// Supabase CLI의 타입 생성기로 생성된 데이터베이스 타입 정의
-// 예: supabase gen types typescript --local > database.types.ts
+// SupaLite CLI의 타입 생성기로 생성된 데이터베이스 타입 정의
+// 예: npx supalite gen types --db-url "postgresql://user:pass@localhost:5432/db" --out database.types.ts
 import { Database } from './types/database';
 
 // 타입이 적용된 클라이언트 생성
@@ -91,6 +247,35 @@ interface Database {
 }
 ```
 
+### supalite gen types로 타입 생성
+
+```bash
+npx supalite gen types --db-url "postgresql://user:pass@localhost:5432/db" --schema public,analytics --out database.types.ts --date-as-date
+```
+
+- `--out -`는 stdout으로 출력합니다.
+- 기본 출력은 SupaLite 포맷(= Supabase CLI의 상위 집합)입니다. Supabase CLI와 1:1로 맞추려면 `--format supabase`를 사용하세요.
+- SupaLite 포맷은 `Constraints`/`Indexes`, `Relationships`의 `referencedSchema`, `bigint` + `Json` bigint 지원, setof RPC용 `SetofOptions`를 추가로 포함합니다.
+- BIGINT 컬럼 타입은 `--bigint-type bigint|number|string`로 제어합니다. (기본: supabase=number, supalite=bigint)
+- `--no-bigint`는 `--bigint-type number`의 간편 옵션입니다.
+- `--json-bigint`는 `Json` 타입에 `bigint`를 포함합니다. (기본: supabase=false, supalite=true)
+- `--no-json-bigint`는 `Json` 타입에서 `bigint`를 제외합니다.
+- `--date-as-date`는 `date`/`timestamp` 컬럼을 `Date`로 생성합니다.
+- `--include-relationships`는 FK 메타데이터를 `Relationships`에 포함합니다. (기본: true)
+- `--include-constraints`는 PK/UNIQUE/CHECK/FK 메타데이터를 포함합니다. (기본: supabase=false, supalite=true)
+- `--include-indexes`는 인덱스 메타데이터(이름/유니크/정의)를 포함합니다. (기본: supabase=false, supalite=true)
+- `--include-composite-types`는 `CompositeTypes` 정의를 포함합니다. (기본: true)
+- `--include-function-signatures`는 `Functions.Args/Returns`를 스키마 메타데이터로 매핑합니다. (기본: true)
+- `Functions`에는 감지된 함수명이 기본 포함되며, 시그니처도 기본 포함됩니다.
+- `--type-case`는 enum/composite 타입 키의 케이스를 제어합니다 (`preserve` | `snake` | `camel` | `pascal`)
+- `--function-case`는 함수 키의 케이스를 제어합니다 (`preserve` | `snake` | `camel` | `pascal`)
+- `--dump-functions-sql [path]`는 `pg_get_functiondef` 기반의 `CREATE FUNCTION/PROCEDURE` 정의를 로컬 파일로 저장합니다.
+- 테스트/개발용 스키마를 제외하려면 `--schema public`을 사용하세요.
+- `--db-url`을 생략하면 `DB_CONNECTION`을 사용합니다.
+
+로드맵
+- TODO (AI): 스키마 메타데이터 기반 RPC/함수용 트랜잭션 TypeScript 래퍼 자동 생성
+
 ## 사용 예시
 
 ### 데이터베이스 연결
@@ -933,6 +1118,10 @@ npm test
 npm run build
 ```
 
+## 기여하기
+
+이슈와 PR을 환영합니다. 큰 변경은 먼저 이슈로 방향을 맞춰 주세요. 테스트는 로컬 Postgres(또는 `DB_CONNECTION`)가 필요하며, 배포 전 `npm run build`, `npm test`, `npm run lint`를 실행합니다.
+
 ## 라이선스
 
 MIT 라이선스로 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

package/README.md

@@ -1,9 +1,32 @@
 # SupaLite
+If Supabase feels slow due to serverless latency, SupaLite can be a faster alternative for database queries.
 [한국어 README](README.ko.md)
 
 [![npm version](https://img.shields.io/npm/v/supalite.svg)](https://www.npmjs.com/package/supalite)
+[![npm downloads](https://img.shields.io/npm/dm/supalite.svg)](https://www.npmjs.com/package/supalite)
+[![license](https://img.shields.io/npm/l/supalite.svg)](LICENSE)
+[![types](https://img.shields.io/npm/types/supalite.svg)](https://www.npmjs.com/package/supalite)
+[![node](https://img.shields.io/node/v/supalite.svg)](https://www.npmjs.com/package/supalite)
+[![ci](https://img.shields.io/github/actions/workflow/status/genideas-labs/supalite/ci.yml?branch=main)](https://github.com/genideas-labs/supalite/actions/workflows/ci.yml)
 
-A lightweight and efficient PostgreSQL client library. It mirrors the Supabase API while providing a smaller and faster implementation.
+A lightweight PostgreSQL client focused on the Supabase query builder. It keeps the familiar API but trims the surface area so you get a smaller footprint and less overhead in production.
+
+In one line: **SupaLite is a slim Supabase client for query builder + RPC + transactions.** If you need full Supabase features (auth/storage/realtime), use `supabase-js`.
+
+Used in production by [oqoq.ai](https://oqoq.ai).
+
+Compatibility at a glance:
+- ✅ Select/filters/order/pagination
+- ✅ PostgREST-style embeds (`related_table(*)`, `!inner`)
+- ✅ Insert/update/delete/upsert (including `ignoreDuplicates`)
+- ✅ RPC (including `single`/`maybeSingle`)
+- ❌ Auth/Storage/Realtime
+
+Cloud migration note (GCP/AWS):
+If you are moving off Supabase, SupaLite replaces only the **DB query layer**. You still need alternatives for Auth/Storage/Realtime. Typical choices are:
+- Auth: managed identity (AWS Cognito / Google Identity Platform) or self-hosted (GoTrue/Keycloak)
+- Storage: object storage (S3 / GCS)
+- Realtime: managed pub/sub, WebSocket services, or PostgreSQL LISTEN/NOTIFY + your own gateway
 
 ## Key Features
 
@@ -18,6 +41,127 @@ A lightweight and efficient PostgreSQL client library. It mirrors the Supabase A
 - Advanced filtering: OR conditions, ILIKE, and more
 - Array support: multi-row inserts and array fields (JSON/JSONB included)
 - Views, Functions, Enums: full Supabase-style typing
+- BigInt handling: configurable transforms for JSON-safe values
+
+## Project Scope
+
+SupaLite targets a focused subset of the Supabase client: query builder, RPC, and transactions. It does not aim for full Supabase feature parity (auth/storage/realtime). The supported query patterns are documented below; if a pattern is missing, please open an issue so we can prioritize it.
+
+## Migrations and schema management
+
+SupaLite is intentionally ORM-light. For schema management and migrations, use dedicated tools:
+- Migrations/schema sync: [pg-schema-sync](https://github.com/genideas-labs/pg-schema-sync)
+- Alternatives: Atlas, dbmate, Sqitch, Goose, Flyway
+- Type generation: `supabase gen types typescript --db-url <postgres_url>` (works with just a DB URL)
+
+ORM features (relations, nested writes, etc.) are best handled by Prisma/Drizzle/Kysely in a separate service when needed. Keeping SupaLite light is part of the value.
+
+About `supabase db pull`: it is a schema/migration sync step, not an ORM feature. Rather than implementing it inside SupaLite, we recommend documenting the workflow and optionally providing a lightweight CLI wrapper that combines `pg-schema-sync` + type generation.
+
+SupaLite now includes `supalite gen types`, which defaults to the SupaLite format (a superset of Supabase CLI output). Use `--format supabase` for byte-for-byte Supabase CLI output.
+
+## SupaLite vs Prisma / Drizzle
+
+SupaLite is a lightweight SQL-first client with a Supabase-style query builder. Prisma and Drizzle are ORMs with schema-first workflows and migrations.
+
+When SupaLite fits best:
+- You want a thin query layer with minimal abstraction.
+- You are migrating from Supabase and want similar query ergonomics.
+- You handle migrations and schema management separately.
+
+When Prisma or Drizzle fits best:
+- You want schema-first modeling and built-in migrations.
+- You want richer ORM features (relations, nested writes, generated client APIs).
+- You want stronger compile-time guarantees tied to a schema file.
+
+Trade-offs:
+- SupaLite is simpler and closer to SQL, but does not provide ORM-level modeling or migration tooling.
+- Prisma/Drizzle add features and structure, with some abstraction overhead.
+- SupaLite includes built-in BIGINT transform options for JSON-safe output.
+- Prisma/Drizzle still require manual decisions for BIGINT (JSON serialization vs precision), while SupaLite centralizes it with `bigintTransform`.
+
+## Example comparison (SupaLite vs Prisma vs Drizzle)
+
+SupaLite keeps Supabase-style naming so the query reads close to SQL. Below is the same query in each tool:
+
+Task: fetch active users, ordered by `created_at` desc, page 2 (10 per page).
+
+SupaLite:
+```typescript
+const page = 2;
+const pageSize = 10;
+const { data } = await client
+  .from('users')
+  .select('id, name, email, created_at')
+  .eq('status', 'active')
+  .order('created_at', { ascending: false })
+  .limit(pageSize)
+  .offset((page - 1) * pageSize);
+```
+
+Prisma:
+```typescript
+const page = 2;
+const pageSize = 10;
+const data = await prisma.user.findMany({
+  select: { id: true, name: true, email: true, created_at: true },
+  where: { status: 'active' },
+  orderBy: { created_at: 'desc' },
+  take: pageSize,
+  skip: (page - 1) * pageSize,
+});
+```
+
+Drizzle:
+```typescript
+const page = 2;
+const pageSize = 10;
+const data = await db
+  .select({ id: users.id, name: users.name, email: users.email, created_at: users.createdAt })
+  .from(users)
+  .where(eq(users.status, 'active'))
+  .orderBy(desc(users.createdAt))
+  .limit(pageSize)
+  .offset((page - 1) * pageSize);
+```
+
+## Roadmap (near-term)
+
+- CI matrix for Node/pg versions with integration tests
+- Benchmarks and performance guidance
+- Auth/Storage/Realtime migration guidance (Cognito/GIP, S3/GCS, Realtime options)
+- `supalite gen types` (SupaLite-first generator with Supabase-compatible output)
+- Contribution guide and issue templates
+
+## Performance notes (serverless Supabase vs cloud Postgres)
+
+General differences you can expect when moving off serverless Supabase to a managed Postgres on GCP/AWS:
+- Network hops: Supabase often adds extra hops (edge/API/REST layer) vs direct Postgres access, especially within the same VPC.
+- Cold starts and pooling: serverless tiers can cold-start or aggressively pool; dedicated poolers (pgBouncer/RDS Proxy) reduce tail latency.
+- Network path: public Internet vs private VPC/peering changes jitter and p95/p99 latency.
+- Overhead: HTTP/PostgREST layers add serialization cost; direct SQL clients minimize that overhead.
+
+Benchmarks and numbers: **TBD (source needed)**. If you have public benchmarks, please open a PR with sources.
+Sources needed:
+- Links to public benchmarks/blogs/docs comparing serverless Postgres vs managed Postgres latency and pooling.
+
+## Benchmark methodology (draft)
+
+- Workloads: simple `select`, filtered `select + order`, `insert`, `rpc`.
+- Measure p50/p95/p99 with warm and cold runs.
+- Keep region and instance size identical; record DB version and pool settings.
+- Separate client latency vs query time when possible.
+- Publish scripts and raw results.
+
+## Why SupaLite
+
+- Direct PostgreSQL connection (no PostgREST hop) for lower latency and fewer moving parts
+- Supabase-style, SQL-like method names for easy migration
+- Native `bigint` support with configurable transforms
+- Transactions and multi-step flows that Supabase client does not support
+- Type generator that can include relationships/constraints/indexes and function signatures
+
+See `docs/limitations.md` for known trade-offs.
 
 ## Installation
 
@@ -25,13 +169,25 @@ A lightweight and efficient PostgreSQL client library. It mirrors the Supabase A
 npm install supalite
 ```
 
+### CLI
+
+```bash
+npm install -g supalite
+```
+
+```bash
+supalite gen types --help
+```
+
+You can also use `npx supalite ...` without a global install.
+
 ## Type System
 
 ### Database schema definition
 
 ```typescript
-// Database types generated by Supabase CLI
-// Example: supabase gen types typescript --local > database.types.ts
+// Database types generated by SupaLite CLI
+// Example: npx supalite gen types --db-url "postgresql://user:pass@localhost:5432/db" --out database.types.ts
 import { Database } from './types/database';
 
 // Typed client
@@ -92,6 +248,35 @@ interface Database {
 }
 ```
 
+### Generate types with supalite gen types
+
+```bash
+npx supalite gen types --db-url "postgresql://user:pass@localhost:5432/db" --schema public,analytics --out database.types.ts --date-as-date
+```
+
+- `--out -` prints to stdout
+- Default output is SupaLite format (superset of Supabase CLI). Use `--format supabase` for byte-for-byte Supabase CLI output.
+- SupaLite format also includes `Constraints`/`Indexes`, `referencedSchema` in `Relationships`, `bigint` + `Json` bigint support, and `SetofOptions` for setof RPCs.
+- BIGINT type mapping is controlled by `--bigint-type bigint|number|string` (default: supabase=number, supalite=bigint)
+- `--no-bigint` is a shortcut for `--bigint-type number`
+- `--json-bigint` includes `bigint` in the `Json` union (default: supabase=false, supalite=true)
+- `--no-json-bigint` disables bigint in the `Json` union
+- `--date-as-date` maps `date`/`timestamp` columns to `Date`
+- `--include-relationships` emits foreign-key metadata into `Relationships` (default: true)
+- `--include-constraints` emits primary/unique/check/foreign key metadata (default: supabase=false, supalite=true)
+- `--include-indexes` emits index metadata (name, uniqueness, definition) (default: supabase=false, supalite=true)
+- `--include-composite-types` emits `CompositeTypes` definitions (default: true)
+- `--include-function-signatures` maps `Functions.Args/Returns` from schema metadata (default: true)
+- `Functions` always lists detected function names; signatures are included by default
+- `--type-case` controls enum/composite type key casing (`preserve` | `snake` | `camel` | `pascal`)
+- `--function-case` controls function key casing (`preserve` | `snake` | `camel` | `pascal`)
+- `--dump-functions-sql [path]` writes `CREATE FUNCTION/PROCEDURE` definitions (from `pg_get_functiondef`) to a local file
+- Use `--schema public` to exclude test/dev schemas from generated types
+- Uses `DB_CONNECTION` if `--db-url` is omitted
+
+Roadmap
+- TODO (AI): generate transactional TypeScript wrappers for RPC/functions from schema metadata
+
 ## Usage Examples
 
 ### Database connection
@@ -926,6 +1111,10 @@ npm test
 npm run build
 ```
 
+## Contributing
+
+Issues and PRs are welcome. For larger changes, please open an issue first to align on scope. Tests expect a local Postgres (or `DB_CONNECTION`), and we run `npm run build`, `npm test`, and `npm run lint` before publishing.
+
 ## License
 
 Released under the MIT License. See [LICENSE](LICENSE).

package/SPEC.md

@@ -151,7 +151,28 @@ Notes:
 - Some tests require a running PostgreSQL with the right schema and `DB_CONNECTION` env var.
 - Raw SQL tests validate exact SQL generation via the private `buildQuery()`.
 
-## 11. Non-goals
+## 11. Type generation CLI
+- `supalite gen types --db-url <postgres_url> [--schema public,analytics] [--out supalite.types.ts]`
+- Reads schema metadata from `information_schema` and `pg_catalog`.
+- Emits `Json` and a `Database` type with `Tables`, `Views`, `Functions`, `Enums`, and `CompositeTypes`.
+- `--format supalite|supabase` (default: supalite).
+- `--format supabase` matches Supabase CLI output (including formatting).
+- SupaLite format is a superset of Supabase: `Constraints`/`Indexes`, `referencedSchema` in `Relationships`, `bigint` defaults, `Json` bigint, and `SetofOptions` for setof RPCs.
+- `BIGINT` maps to `bigint` by default (`--format supabase` defaults to `number`); `--no-bigint` is a shorthand for `--bigint-type number`.
+- `json/jsonb` map to `Json` with optional `bigint` (`--json-bigint` default: supalite=true, supabase=false; disable via `--no-json-bigint`).
+- `--date-as-date` maps `date`/`timestamp` columns to `Date`.
+- `--include-relationships` emits FK metadata in `Relationships`.
+- `--include-constraints` emits PK/UNIQUE/CHECK/FK metadata per table.
+- `--include-indexes` emits index metadata per table.
+- `--include-composite-types` emits `CompositeTypes` definitions.
+- `--include-function-signatures` maps `Functions.Args/Returns` from schema metadata.
+- `--type-case` controls enum/composite type key casing (`preserve` | `snake` | `camel` | `pascal`).
+- `--function-case` controls function key casing (`preserve` | `snake` | `camel` | `pascal`).
+- `--dump-functions-sql [path]` writes `CREATE FUNCTION/PROCEDURE` definitions from `pg_get_functiondef`.
+- Arrays are mapped to `baseType[]` using the underlying element type.
+- Insert types mark nullable/default/identity/generated columns as optional; Update types are always optional.
+
+## 12. Non-goals
 - Full Supabase feature parity (auth, storage, realtime).
 - SQL injection-safe raw SQL DSL beyond the query builder.
 - Advanced query planner hints or server-side caching.

package/bin/supalite

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli');

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};