スキルOfficialdeployment

🗄️sqlite-storage

プラグイン: valtown
ソース: GitHub で見る ↗

説明

次のような場合に使用: val が構造化データまたはリレーショナルデータを保存する必要がある場合。 `std/sqlite` API、パラメータ化クエリ、トランザクション、および val スコープと organization スコープのデータベースの違いについて説明します。

原文を表示

Use when a val needs to store structured or relational data. Covers the std/sqlite API, parameterized queries, transactions, and the val-scoped vs organization-scoped database distinction.

ユースケース

✓構造化データを保存する必要があるとき
✓リレーショナルデータを保存する必要があるとき

本文（日本語訳）

SQLite ストレージ

Val Town は std/sqlite モジュールを通じて SQLite をビルトインで提供しています。 val でリレーショナルまたは構造化された永続データが必要な場合はこちらを使用してください。単純なキー/バリューデータには、代わりに std/blob を推奨します。

基本的な使い方

import { sqlite } from "https://esm.town/v/std/sqlite/main.ts";

await sqlite.execute(`CREATE TABLE IF NOT EXISTS users (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE
)`);

await sqlite.execute({
  sql: "INSERT INTO users (name, email) VALUES (?, ?)",
  args: ["Alice", "alice@example.com"],
});

const result = await sqlite.execute("SELECT * FROM users");
// result.rows = [{ id: 1, name: "Alice", email: "alice@example.com" }]

トランザクション

アトミックなマルチステートメントトランザクションには sqlite.batch を使用してください。すべて成功するか、すべてロールバックされます:

await sqlite.batch([
  { sql: "INSERT INTO users (name, email) VALUES (?, ?)", args: ["Bob", "bob@example.com"] },
  { sql: "UPDATE users SET name = ? WHERE id = ?", args: ["Robert", 2] },
]);

val スコープ vs. 組織データベース

どのデータベースを使用するかはインポートパスで決まります。どちらも同じ @libsql/client API（execute、batch）を公開しており、行はキー付きオブジェクト（Record<string, unknown>[]）として返されます:

std/sqlite/main.ts — val スコープのデータベース。この val にのみ隔離されます。新しい val のデフォルトであり、ほぼ常にこちらを使用します。
std/sqlite/global.ts — 組織スコープのデータベース。同じアカウントが所有するすべての val で共有されます。（個人アカウントもここでは独自の組織として扱われるため、このデータベースはあなたのすべての val で共有されます。）

既存の val でこれらのインポートパスを切り替えないでください。切り替えると、その val が読み書きするデータベースが変わってしまいます。

ツールを使った組織所有 val へのクエリ

sqlite_execute または sqlite_batch ツールを使って、組織（個人アカウントではない）が所有する val にクエリを実行する場合は、 org パラメータに組織ハンドルを渡すことで、正しいデータベースへのアクセスが保証されます。例: { sql: "SELECT * FROM users", org: "some-org" } これはツール呼び出し時のみ必要です。val 内部のコードは自動的に自身のデータベースを参照します。

ルール

ユーザー入力に由来するすべての値には、必ずパラメータ化クエリ（args フィールド）を使用してください。 SQL に文字列を直接埋め込まないでください。
val の再起動をまたいでスキーマのセットアップが冪等になるよう、CREATE TABLE IF NOT EXISTS を使用してください。
スキーマのマイグレーションには ALTER TABLE ... ADD COLUMN で新しいカラムを追加してください。すでに更新済みのテーブルに対してマイグレーションが実行される可能性がある場合は、try/catch でラップしてください。

リファレンス

完全な API ドキュメント: https://docs.val.town/reference/std/sqlite/usage/

原文（English）を表示

SQLite Storage

Val Town provides built-in SQLite via the std/sqlite module. Reach for it whenever a val needs relational or structured persistent data. For simple key/value data, prefer std/blob instead.

Basic usage

import { sqlite } from "https://esm.town/v/std/sqlite/main.ts";

await sqlite.execute(`CREATE TABLE IF NOT EXISTS users (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE
)`);

await sqlite.execute({
  sql: "INSERT INTO users (name, email) VALUES (?, ?)",
  args: ["Alice", "alice@example.com"],
});

const result = await sqlite.execute("SELECT * FROM users");
// result.rows = [{ id: 1, name: "Alice", email: "alice@example.com" }]

Transactions

Use sqlite.batch for atomic multi-statement transactions — all succeed or all roll back:

await sqlite.batch([
  { sql: "INSERT INTO users (name, email) VALUES (?, ?)", args: ["Bob", "bob@example.com"] },
  { sql: "UPDATE users SET name = ? WHERE id = ?", args: ["Robert", 2] },
]);

Per-val vs organization databases

The import path determines which database you get. Both expose the same @libsql/client API (execute, batch) and return rows as keyed objects (Record<string, unknown>[]):

std/sqlite/main.ts — val-scoped database, isolated to this val. The default for new vals, and what you almost always want.
std/sqlite/global.ts — organization-scoped database, shared across every val owned by the same account. (Your personal account counts as its own organization here, so this database is shared across all of your vals.)

Do not switch an existing val between these import paths — it changes which database the val reads and writes.

Querying org-owned vals via tools

When using the sqlite_execute or sqlite_batch tools to query a val owned by an organization (not your personal account), pass the org handle as the org parameter so the call hits the right database. Example: { sql: "SELECT * FROM users", org: "some-org" }. This only matters for the tool calls — code inside the val itself reads from its own database automatically.

Rules

Always use parameterized queries (the args field) for any value derived from user input. Never interpolate strings into SQL.
Use CREATE TABLE IF NOT EXISTS so schema setup is idempotent across val restarts.
Schema migrations: add new columns with ALTER TABLE ... ADD COLUMN. Wrap in try/catch if the migration may run against an already-updated table.

Reference

Full API docs: https://docs.val.town/reference/std/sqlite/usage/

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。