yaklang-database

スキル：Yaklang データベース操作（db ライブラリ）

AI LOAD INSTRUCTION：db ライブラリは Yaklang のデータベース中核モジュールであり、SQLite／MySQL 接続、SQL クエリ、キーと値のストレージ、Payload 辞書の管理などの機能を提供します。このページでは、そのまま実行できる例と、実際の API の形式に関するいくつかの規約を紹介します（第 4 節「落とし穴」を参照）。どちらの例も yak <file> で実行してテストできます。データベース関連の Yaklang を記述する際は、まずここを参照してください。

0. 関連ルート

• 総合エントリーポイント：yak
• 基本構文（エラー処理 ~、map、for）：yaklang-syntax

1. 一時 SQLite：テーブルの作成／追加・削除・更新・検索／集計

スクリプト内で構造化データ（スキャン結果、アセット、中間テーブル）を一時的に保存し、SQL でクエリや集計を行う場合に適しています。

tempDB = db.OpenTempSqliteDatabase()~          // 返回 (gormDB, err), 用 ~ 处理

// 写操作: tempDB.Exec(sql, args...).Error 是字段(不是函数, 不能用 ~)
err = tempDB.Exec("CREATE TABLE products (id INTEGER PRIMARY KEY, name TEXT, price INTEGER)").Error
assert err == nil, "create failed"
tempDB.Exec("INSERT INTO products (name, price) VALUES (?, ?)", "laptop", 8000)  // ? 参数化防注入

// 读操作: db.ScanResult 返回 []map, 每行是一个 map
rows = db.ScanResult(tempDB, "SELECT * FROM products WHERE price > ? ORDER BY price DESC", 100)~
for row in rows {
    log.info("%v -> %v", row["name"], row["price"])
}

完全な例：examples/sqlite-crud.yak

2. キーと値のストレージ（KV）：スクリプト間で状態を共有

Yakit プロファイルデータベースに書き込まれます（永続化）。プラグインやスクリプト間で設定や中間状態を共有する場合に適しています。

db.SetKey("my-key", "my-value")          // 写 (重复调用即覆盖)
v = db.GetKey("my-key")                   // 读, 不存在返回 ""
db.SetKeyWithTTL("tmp", "v", 60)          // 带过期 (秒)
db.DelKey("my-key")                        // 删

// 项目级配置 (随项目切换), 与全局 KV 区分
db.SetProjectKey("conf", json.dumps({"a":1}))
cfg = db.GetProjectKey("conf")

3. Payload 辞書の管理：ブルートフォース用辞書を Yakit に一元管理させる

db.SavePayload("my-users", ["admin", "root", "guest"])~   // 存入字典组

for content in db.YieldPayload("my-users") {              // 迭代器, 逐条产出内容字符串
    log.info("payload: %s", content)
}

groups = db.GetAllPayloadGroupsName()                     // 列出所有字典组名
db.DeletePayloadByGroup("my-users")                       // 删除整组

完全な例（KV + Payload、クリーンアップ付き）：examples/kv-and-payload.yak

4. 実際の API 形式に関する規約（記述前に必ずお読みください）

規約	誤った書き方	正しい書き方
.Exec(...).Error は関数ではなくフィールドです	tempDB.Exec(sql).Error~	err = tempDB.Exec(sql).Error; assert err == nil
db.OpenTempSqliteDatabase() は (db, err) を返します	tempDB = db.OpenTempSqliteDatabase()	tempDB = db.OpenTempSqliteDatabase()~
db.YieldPayload はオブジェクトではなく、内容の文字列を生成します	for p in db.YieldPayload(g) { p.Content }	for content in db.YieldPayload(g) { ... }
db.GetKey は存在しない場合、nil ではなく空文字列を返します	if db.GetKey(k) == nil	if db.GetKey(k) == ""
KV／Payload への書き込みは永続化されます	自己テストで固定の汚れたデータを使う	一意のプレフィックスを付けた key／group を使い、最後にクリーンアップする

メソッドが不明な場合は、スクリプト内で desc(db) または desc(tempDB) を使い、利用可能なメソッドを確認してください。API を注意深く調べることを誇りとし、推測でインターフェースを決めつけることを恥としましょう。

5. よく使う API のクイックリファレンス

用途	API
一時 SQLite を開く	db.OpenTempSqliteDatabase()~
SQL を実行する（書き込み）	tempDB.Exec(sql, args...).Error
[]map を返すクエリ	db.ScanResult(tempDB, sql, args...)~
キーと値の読み取り・書き込み・削除	db.SetKey / db.GetKey / db.DelKey / db.SetKeyWithTTL
プロジェクトレベルの設定	db.SetProjectKey / db.GetProjectKey
Payload 辞書	db.SavePayload / db.YieldPayload / db.GetAllPayloadGroupsName / db.DeletePayloadByGroup

6. 検証

cd /Users/v1ll4n/Projects/yaklang
go run common/yak/cmd/yak.go skills/yaklang-database/examples/sqlite-crud.yak
go run common/yak/cmd/yak.go skills/yaklang-database/examples/kv-and-payload.yak

各例では、assert がすべて成功し、log がすべて英語で、... self test passed が表示されることを確認してください。

参考資料

• yaklang-ai-training-materials library-usage/db/db-practice.yak
• yaklang-ai-training-materials library-usage/yakit-db/yakit-db-practice.yak
• ライブラリのエクスポート：common/yak/script_engine.go