Merge pull request #960 from go-admin-team/fix/quick-start-first-run

docs📝: make the first run work from a fresh clone

README.Zh-cn.md

@@ -136,6 +136,21 @@ git clone https://github.com/go-admin-team/go-admin-ui.git
 
 ### 启动说明
 
+#### SQLite 快速体验（无需安装数据库）
+
+这是看到 go-admin 跑起来的最短路径。需要 C 编译器（cgo），并且要带 `sqlite3` 构建标签，普通的 `go build` 不包含它。
+
+```bash
+cd ./go-admin
+go build -tags sqlite3
+./go-admin migrate -c config/settings.sqlite.yml
+./go-admin server -c config/settings.sqlite.yml
+```
+
+Windows 下把 `./go-admin` 换成 `go-admin.exe`。启动后接口地址是 `http://localhost:8000`。要打开界面，在 `go-admin-ui` 里执行 `pnpm install` 和 `pnpm dev`，然后用 `admin` / `123456` 登录。
+
+使用 MySQL、PostgreSQL 或 SQL Server 时，请按下面的步骤操作。
+
 #### 服务端启动说明
 
 ```bash
@@ -181,10 +196,10 @@ cgo: exec gcc: exec: "gcc": executable file not found in %PATH%
 ``` bash
 # 首次配置需要初始化数据库资源信息
 # macOS or linux 下使用
-$ ./go-admin migrate -c config/settings.dev.yml
+$ ./go-admin migrate -c config/settings.yml
 
 # ⚠️注意:windows 下使用
-$ go-admin.exe migrate -c config/settings.dev.yml
+$ go-admin.exe migrate -c config/settings.yml
 
 
 # 启动项目，也可以用IDE进行调试

README.ja-JP.md

@@ -136,6 +136,21 @@ git clone https://github.com/go-admin-team/go-admin-ui.git
 
 ### 起動方法
 
+#### SQLite でとりあえず動かす（データベースのインストール不要）
+
+go-admin が動くところまでの最短手順です。C コンパイラ（cgo）と `sqlite3` ビルドタグが必要で、通常の `go build` にはタグが含まれません。
+
+```bash
+cd ./go-admin
+go build -tags sqlite3
+./go-admin migrate -c config/settings.sqlite.yml
+./go-admin server -c config/settings.sqlite.yml
+```
+
+Windows では `./go-admin` を `go-admin.exe` に置き換えてください。起動後の API は `http://localhost:8000` です。画面を開くには `go-admin-ui` で `pnpm install` と `pnpm dev` を実行し、`admin` / `123456` でログインします。
+
+MySQL、PostgreSQL、SQL Server を使う場合は、以下の手順に従ってください。
+
 #### サーバーの起動
 
 ```bash
@@ -181,10 +196,10 @@ cgo: exec gcc: exec: "gcc": executable file not found in %PATH%
 ``` bash
 # 初回はデータベースのリソース情報を初期化する必要があります
 # macOS または linux の場合
-$ ./go-admin migrate -c config/settings.dev.yml
+$ ./go-admin migrate -c config/settings.yml
 
 # ⚠️注意: windows の場合
-$ go-admin.exe migrate -c config/settings.dev.yml
+$ go-admin.exe migrate -c config/settings.yml
 
 
 # プロジェクトを起動します。IDE からデバッグ実行することもできます

README.md

@@ -134,6 +134,21 @@ git clone https://github.com/go-admin-team/go-admin-ui.git
 
 ### Startup instructions
 
+#### Quick start with SQLite (nothing to install)
+
+This is the shortest way to see go-admin running. It needs a C compiler (cgo) and the `sqlite3` build tag, which a plain `go build` does not include.
+
+```bash
+cd ./go-admin
+go build -tags sqlite3
+./go-admin migrate -c config/settings.sqlite.yml
+./go-admin server -c config/settings.sqlite.yml
+```
+
+On Windows, use `go-admin.exe` instead of `./go-admin`. The API is then at `http://localhost:8000`. To open the UI, run `pnpm install` and `pnpm dev` in `go-admin-ui`, then sign in with `admin` / `123456`.
+
+For MySQL, PostgreSQL or SQL Server, follow the steps below instead.
+
 #### Server startup instructions
 
 ```bash
@@ -178,10 +193,10 @@ cgo: exec gcc: exec: "gcc": executable file not found in %PATH%
 ``` bash
 # The first configuration needs to initialize the database resource information
 # Use under macOS or linux
-$ ./go-admin migrate -c config/settings.dev.yml
+$ ./go-admin migrate -c config/settings.yml
 
 # ⚠️Note: Use under windows
-$ go-admin.exe migrate -c config/settings.dev.yml
+$ go-admin.exe migrate -c config/settings.yml
 
 # Start the project, you can also use the IDE for debugging
 # Use under macOS or linux

README.zh-TW.md

@@ -136,6 +136,21 @@ git clone https://github.com/go-admin-team/go-admin-ui.git
 
 ### 啟動說明
 
+#### SQLite 快速體驗（無需安裝資料庫）
+
+這是看到 go-admin 跑起來的最短路徑。需要 C 編譯器（cgo），並且要帶 `sqlite3` 建置標籤，一般的 `go build` 不包含它。
+
+```bash
+cd ./go-admin
+go build -tags sqlite3
+./go-admin migrate -c config/settings.sqlite.yml
+./go-admin server -c config/settings.sqlite.yml
+```
+
+Windows 下把 `./go-admin` 換成 `go-admin.exe`。啟動後 API 位址是 `http://localhost:8000`。要開啟介面，在 `go-admin-ui` 中執行 `pnpm install` 與 `pnpm dev`，然後用 `admin` / `123456` 登入。
+
+使用 MySQL、PostgreSQL 或 SQL Server 時，請依下面的步驟操作。
+
 #### 伺服器端啟動說明
 
 ```bash
@@ -181,10 +196,10 @@ cgo: exec gcc: exec: "gcc": executable file not found in %PATH%
 ``` bash
 # 首次設定需要初始化資料庫資源資訊
 # macOS or linux 下使用
-$ ./go-admin migrate -c config/settings.dev.yml
+$ ./go-admin migrate -c config/settings.yml
 
 # ⚠️注意:windows 下使用
-$ go-admin.exe migrate -c config/settings.dev.yml
+$ go-admin.exe migrate -c config/settings.yml
 
 
 # 啟動專案，也可以用 IDE 進行除錯

common/database/driver.go

@@ -17,6 +17,12 @@ import (
 func openerFor(driver string) (func(string) gorm.Dialector, error) {
 	open, ok := opens[driver]
 	if !ok {
+		// sqlite3 is the driver people reach for first, and the one a default
+		// build leaves out. Say how to get it rather than only what is missing.
+		if driver == "sqlite3" {
+			return nil, fmt.Errorf("database driver %q is not in this build, rebuild with -tags sqlite3 (this build supports %s)",
+				driver, strings.Join(supportedDrivers(), ", "))
+		}
 		return nil, fmt.Errorf("unsupported database driver %q, this build supports %s",
 			driver, strings.Join(supportedDrivers(), ", "))
 	}

common/database/driver_nosqlite_test.go

@@ -0,0 +1,20 @@
+//go:build !sqlite3
+
+package database
+
+import (
+	"strings"
+	"testing"
+)
+
+// A default build has no sqlite3, and a config naming it is the usual first
+// run. The error has to say how to get the driver, not only that it is missing.
+func TestOpenerForTellsHowToGetSqliteInADefaultBuild(t *testing.T) {
+	_, err := openerFor("sqlite3")
+	if err == nil {
+		t.Fatal("sqlite3 was accepted by a build without the sqlite3 tag")
+	}
+	if !strings.Contains(err.Error(), "-tags sqlite3") {
+		t.Errorf("error does not say how to enable sqlite3: %s", err)
+	}
+}