chore: improve onboarding experience

2025-07-24 15:27:00 +08:00 · 2023-12-17 20:50:11 +08:00
parent af03b3c922
commit 42bad976a4
12 changed files with 79 additions and 45 deletions
--- a/.env.example
+++ b/.env.example
@ -1,3 +0,0 @@
-# see process.d.ts 
-DATABASE_URL=postgresql://postgres:YOUR_PASSWORD@localhost:5432/sqlchat?schema=sqlchat
-OPENAI_API_KEY=YOUR_OPENAI_API_KEY
--- a/.env.no-db
+++ b/.env.no-db
@ -0,0 +1,3 @@
+# see process.d.ts 
+OPENAI_API_KEY=xxx
+NEXT_PUBLIC_USE_DATABASE=false
--- a/.env.use-db
+++ b/.env.use-db
@ -0,0 +1,5 @@
+# see process.d.ts 
+OPENAI_API_KEY=xxx
+NEXT_PUBLIC_USE_DATABASE=true
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/sqlchat?schema=sqlchat&application_name=sqlchat"
+DATABASE_DIRECT_URL="postgresql://postgres:postgres@localhost:5432/sqlchat?schema=sqlchat&application_name=sqlchat"
--- a/Dockerfile.sqlchat-ai
+++ b/Dockerfile.sqlchat-ai
@ -23,7 +23,7 @@ ENV NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_1_MONTH_SUBSCRIPTION price_1O2clpAeLQYhEB73F
 ENV NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_3_MONTH_SUBSCRIPTION price_1NAE2hAeLQYhEB73FoF8WJPS
 ENV NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_1_YEAR_SUBSCRIPTION price_1N96riAeLQYhEB73YPSL8GuV
 ENV NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY pk_live_JoPlkGsFcm2iHvy5a4JR5tia00vVXVJM8d
-ENV NEXT_PUBLIC_DATABASE_LESS false
+ENV NEXT_PUBLIC_USE_DATABASE true

 RUN yarn run build

--- a/README.es-ES.md
+++ b/README.es-ES.md
@ -59,13 +59,13 @@ docker run --name sqlchat --platform linux/amd64 -env NEXTAUTH_SECRET=xxx -p 300

 ### Variables relacionadas con la base de datos:

- `NEXT_PUBLIC_DATABASE_LESS`: Establézcalo en `true` para iniciar SQL Chat en modo sin base de datos. Esto
+- `NEXT_PUBLIC_USE_DATABASE`: Establézcalo en `false` para iniciar SQL Chat en modo sin base de datos. Esto
  desactivara las siguientes funciones:
  1. Sistema de cuentas.
  2. Ejecución de Cuota por Usuario.
  3. Pago.
  4. Recopilación de datos de uso.
- `DATABASE_URL`: Aplicable si `NEXT_PUBLIC_DATABASE_LESS` es `false`. Cadena de conexión de Postgres para almacenar datos. ej. `postgresql://postgres:YOUR_PASSWORD@localhost:5432/sqlchat?schema=sqlchat`.
+- `DATABASE_URL`: Aplicable si `NEXT_PUBLIC_USE_DATABASE` es `true`. Cadena de conexión de Postgres para almacenar datos. ej. `postgresql://postgres:YOUR_PASSWORD@localhost:5432/sqlchat?schema=sqlchat`.

 ```bash
 docker run --name sqlchat --platform linux/amd64 --env NEXTAUTH_SECRET=xxx --env OPENAI_API_KEY=yyy --env OPENAI_API_ENDPOINT=zzz -p 3000:3000 sqlchat/sqlchat
@ -82,7 +82,7 @@ docker run --name sqlchat --platform linux/amd64 --env NEXTAUTH_SECRET=xxx --env
 1. Haga una copia del archivo de variables de entorno de ejemplo:

   ```bash
-   cp .env.example .env
+   cp .env.use-db .env
   ```

 1. Generar el cliente prisma a partir del modelo.
@ -95,7 +95,7 @@ docker run --name sqlchat --platform linux/amd64 --env NEXTAUTH_SECRET=xxx --env

 ### Configura la base de datos

-**Puede omitir esta sección con `NEXT_PUBLIC_DATABASE_LESS=true` si no crea funciones que requieren una base de datos**
+**Puede omitir esta sección con `NEXT_PUBLIC_USE_DATABASE=false` si no crea funciones que requieren una base de datos**

 1. Inicie una instancia de Postgres. Para mac, puedes usar [StackbBricks](https://stackbricks.app/), [DBngin](https://dbngin.com/) o [Postgres.app](https://postgresapp.com/).

--- a/README.md
+++ b/README.md
@ -34,41 +34,49 @@ SQL Chat is built by [Next.js](https://nextjs.org/), it supports the following d
 - MSSQL
 - TiDB Cloud

-## Data Privacy
+## [sqlchat.ai](https://sqlchat.ai) 

-See [SQL Chat Privacy Policy](https://sqlchat.ai/privacy).
-
-## IP Whitelisting
+### IP Whitelisting

 If you use [sqlchat.ai](https://sqlchat.ai) to connect to your database, you need to add 0.0.0.0 (allow all connections)
 to the database whitelist IP. Because sqlchat.AI is hosted on [Vercel](https://vercel.com/) which [uses dynamic IP](https://vercel.com/guides/how-to-allowlist-deployment-ip-address). If this is a concern, please consider the self-host option below.

-## Self-host with Docker
+### Data Privacy
+
+See [SQL Chat Privacy Policy](https://sqlchat.ai/privacy).
+
+## Self-host
+
+### Docker

 ```bash
 docker run --name sqlchat --platform linux/amd64 -env NEXTAUTH_SECRET=xxx -p 3000:3000 sqlchat/sqlchat
 ```

-### OpenAI related variables:
+### Startup options
+
+* Run without database, check [.env.no-db](https://github.com/sqlchat/sqlchat/blob/main/.env.no-db).
+This is suitable if you just want to use for yourself.
+* Run with database, check [.env.use-db](https://github.com/sqlchat/sqlchat/blob/main/.env.use-db).
+This is suitable if you want to run a similar multi-tenant service as [sqlchat.ai](https://sqlchat.ai) where you need manage account, usage and etc.
+
+#### OpenAI related

- `NEXT_PUBLIC_ALLOW_SELF_OPENAI_KEY`: Set to `true` to allow users to bring their own OpenAI API key.
 - `OPENAI_API_KEY`: OpenAI API key. You can get one from [here](https://beta.openai.com/docs/developer-quickstart/api-keys).

 - `OPENAI_API_ENDPOINT`: OpenAI API endpoint. Defaults to `https://api.openai.com`.

-### Database related variables:
+- `NEXT_PUBLIC_ALLOW_SELF_OPENAI_KEY`: Set to `true` to allow users to bring their own OpenAI API key.

- `NEXT_PUBLIC_DATABASE_LESS`: Set to `true` to start SQL Chat in database-less mode. This will
-  disable following features:
+#### Database related
+
+- `NEXT_PUBLIC_USE_DATABASE`: Set to `true` to start SQL Chat with database. This will
+  enable following features:
  1. Account system.
  1. Per-user quota enforcement.
  1. Payment.
  1. Usage data collection.
- `DATABASE_URL`: Applicable if `NEXT_PUBLIC_DATABASE_LESS` is `false`. Postgres connection string to store data. e.g. `postgresql://postgres:YOUR_PASSWORD@localhost:5432/sqlchat?schema=sqlchat`.
-
-```bash
-docker run --name sqlchat --platform linux/amd64 --env NEXTAUTH_SECRET=xxx --env OPENAI_API_KEY=yyy --env OPENAI_API_ENDPOINT=zzz -p 3000:3000 sqlchat/sqlchat
-```
+- `DATABASE_URL`: Applicable if `NEXT_PUBLIC_USE_DATABASE` is `true`. Postgres connection string to store data. e.g. `postgresql://postgres:YOUR_PASSWORD@localhost:5432/sqlchat?schema=sqlchat`.

 ## Local Development

@ -87,14 +95,14 @@ docker run --name sqlchat --platform linux/amd64 --env NEXTAUTH_SECRET=xxx --env
 1. Make a copy of the example environment variables file:

   ```bash
-   cp .env.example .env
+   cp .env.use-db .env
   ```

 1. Add your [API key](https://platform.openai.com/account/api-keys) and OpenAI API Endpoint(optional) to the newly created `.env` file.

 ### Setup database

-**You can skip this section with `NEXT_PUBLIC_DATABASE_LESS=true` if you don't build features requiring database**
+**You can skip this section with `NEXT_PUBLIC_USE_DATABASE=false` if you don't build features requiring database**

 1. Start a Postgres instance. For mac, you can use [StackbBricks](https://stackbricks.app/), [DBngin](https://dbngin.com/) or [Postgres.app](https://postgresapp.com/).

--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@ -57,12 +57,12 @@ docker run --name sqlchat --platform linux/amd64 -env NEXTAUTH_SECRET=xxx -p 300

 ### 数据库相关变量:

- `NEXT_PUBLIC_DATABASE_LESS`: 设置为 `true` 如果你想让 SQL Chat 运行时不需要数据库。这个会关闭如下功能:
+- `NEXT_PUBLIC_USE_DATABASE`: 设置为 `true` 如果你启动 SQL Chat 时使用了数据库。这会开启如下功能:
  1. 账户系统。
  1. 用户额度控制。
  1. 支付。
  1. 使用数据收集。
- `DATABASE_URL`: 只有在 NEXT_PUBLIC_DATABASE_LESS 为 true 时有效。Postgres 数据库连接串 e.g. `postgresql://postgres:YOUR_PASSWORD@localhost:5432/sqlchat?schema=sqlchat`.
+- `DATABASE_URL`: 只有在 `NEXT_PUBLIC_USE_DATABASE` 为 `true` 时有效。Postgres 数据库连接串 e.g. `postgresql://postgres:YOUR_PASSWORD@localhost:5432/sqlchat?schema=sqlchat`.

 ```bash
 docker run --name sqlchat --platform linux/amd64 --env NEXTAUTH_SECRET=xxx --env OPENAI_API_KEY=yyy --env OPENAI_API_ENDPOINT=zzz -p 3000:3000 sqlchat/sqlchat
@ -79,7 +79,7 @@ docker run --name sqlchat --platform linux/amd64 --env NEXTAUTH_SECRET=xxx --env
 1. 复制示例环境变量文件;

   ```bash
-   cp .env.example .env
+   cp .env.use-db .env
   ```

 1. 生成 `prisma` 客户端
--- a/package.json
+++ b/package.json
@ -3,6 +3,8 @@
  "private": false,
  "scripts": {
    "dev": "next dev",
+    "no-db": "env-cmd -f .env.no-db pnpm dev",
+    "use-db": "env-cmd -f .env.use-db pnpm dev",
    "build": "prisma generate && next build",
    "build-prisma-deploy": "prisma generate && next build && prisma migrate deploy",
    "export": "next export",
@ -76,6 +78,7 @@
    "@types/react-syntax-highlighter": "^15.5.6",
    "@types/uuid": "^9.0.1",
    "autoprefixer": "^10.4.13",
+    "env-cmd": "^10.1.0",
    "eslint": "8.20.0",
    "eslint-config-next": "12.2.3",
    "eslint-config-prettier": "^8.8.0",
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@ -196,6 +196,9 @@ devDependencies:
  autoprefixer:
    specifier: ^10.4.13
    version: 10.4.14(postcss@8.4.21)
+  env-cmd:
+    specifier: ^10.1.0
+    version: 10.1.0
  eslint:
    specifier: 8.20.0
    version: 8.20.0
@ -2272,6 +2275,11 @@ packages:
    resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==}
    dev: false

+  /commander@4.1.1:
+    resolution: {integrity: sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==}
+    engines: {node: '>= 6'}
+    dev: true
+
  /commander@9.5.0:
    resolution: {integrity: sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==}
    engines: {node: ^12.20.0 || >=14}
@ -2544,6 +2552,15 @@ packages:
    resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
    dev: true

+  /env-cmd@10.1.0:
+    resolution: {integrity: sha512-mMdWTT9XKN7yNth/6N6g2GuKuJTsKMDHlQFUDacb/heQRRWOTIZ42t1rMHnQu4jYxU1ajdTeJM+9eEETlqToMA==}
+    engines: {node: '>=8.0.0'}
+    hasBin: true
+    dependencies:
+      commander: 4.1.1
+      cross-spawn: 7.0.3
+    dev: true
+
  /error-ex@1.3.2:
    resolution: {integrity: sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==}
    dependencies:
--- a/process.d.ts
+++ b/process.d.ts
@ -2,15 +2,15 @@ declare namespace NodeJS {
  export interface ProcessEnv {
    // Required. Node environment.
    NODE_ENV: string;
-    // Optional. Set to "true" to disable the database. Need to use string as env is always string.
+    // Optional. Set to "true" to use the database. Need to use string as env is always string.
    // We can't prefix DATABASE_URL with NEXT_PUBLIC_ because it contains sensitive information that
    // should not be exposed to the client.
-    NEXT_PUBLIC_DATABASE_LESS: string;
-    // Optional. Set to "true" to allow users to bring their own OpenAI API key.
-    NEXT_PUBLIC_ALLOW_SELF_OPENAI_KEY: string;
-    // Required if NEXT_PUBLIC_DATABASE_LESS is false. Postgres database connection string to store
+    NEXT_PUBLIC_USE_DATABASE: string;
+    // Required if NEXT_PUBLIC_USE_DATABASE is true. Postgres database connection string to store
    // the data. e.g. postgresql://postgres:YOUR_PASSWORD@localhost:5432/sqlchat?schema=sqlchat
    DATABASE_URL: string;
+    // Optional. Set to "true" to allow users to bring their own OpenAI API key.
+    NEXT_PUBLIC_ALLOW_SELF_OPENAI_KEY: string;
    // Required. Do not share your OpenAI API key with anyone! It should remain a secret.
    OPENAI_API_KEY: string;
    // Optional. OpenAI API endpoint. Defaults to https://api.openai.com.
--- a/src/pages/_app.tsx
+++ b/src/pages/_app.tsx
@ -7,6 +7,7 @@ import React, { useEffect } from "react";
 import { Toaster } from "react-hot-toast";
 import { useTranslation } from "react-i18next";
 import { useSettingStore } from "@/store";
+import { hasDatabase } from "@/utils";

 dayjs.extend(localizedFormat);
 import "dayjs/locale/zh";
@ -25,7 +26,7 @@ function MyApp({ Component, pageProps: { session, ...pageProps } }: AppProps<{ s

  // Check whether those NEXT_PUBLIC_ envs are properly exposed in frontend.
  // See https://github.com/vercel/next.js/discussions/17641
-  console.log("Use database:", !process.env.NEXT_PUBLIC_DATABASE_LESS);
+  console.log("Has database:", hasDatabase());

  useEffect(() => {
    const darkMediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
--- a/src/utils/feature.ts
+++ b/src/utils/feature.ts
@ -1,23 +1,23 @@
 type FeatureType = "debug" | "account" | "payment" | "quota" | "collect";

-function databaseLess() {
-  return process.env.NEXT_PUBLIC_DATABASE_LESS == "true";
-}
+export const hasDatabase = () => {
+  return process.env.NEXT_PUBLIC_USE_DATABASE == "true";
+};

 const matrix: { [key: string]: { [feature: string]: boolean } } = {
  development: {
    debug: true,
-    account: !databaseLess(),
-    payment: !databaseLess(),
-    quota: !databaseLess(),
-    collect: !databaseLess(),
+    account: hasDatabase(),
+    payment: hasDatabase(),
+    quota: hasDatabase(),
+    collect: hasDatabase(),
  },
  production: {
    debug: false,
-    account: !databaseLess(),
-    payment: !databaseLess(),
-    quota: !databaseLess(),
-    collect: !databaseLess(),
+    account: hasDatabase(),
+    payment: hasDatabase(),
+    quota: hasDatabase(),
+    collect: hasDatabase(),
  },
 };