Tools

These are the tools pebblebase offers your AI, with the descriptions the server sends. This page is generated from the server.

list_databases · Reads only

List the authenticated account’s database IDs and names. Before using one, read its pebblebase_notes.

create_database · Changes data

Create an empty SQLite database (a pebble). Returns its ID for later SQL calls and pebblebase’s build guide: these instructions plus the views, forms and app reference.

execute_sql · Changes data

Change a pebble with SQLite SQL (https://sqlite.org/lang.html), using positional ? parameters. All statements run in one transaction; no BEGIN/COMMIT needed. For reads alone, use query_sql.

Returns columns, rows and change counts for each statement. The last result may list notices: what this pebble still lacks. At most 1,000 rows per statement, 200,000 characters of results, and about two seconds for the statements. Exceeding a limit rolls back the call. If the call changes the schema of a database with stored tests, they rerun before it commits (up to about 10 more seconds), and the call rolls back if a test fails that didn’t fail before. Update a test in the same call as the change it describes, and keep large data changes out of schema-change calls. ‘localtime’ means the time_zone row in pebblebase_settings, else the account’s zone, else UTC. That row is set with INSERT INTO pebblebase_settings (name, value) VALUES (‘time_zone’, ‘America/Chicago’). pebblebase_settings accepts only pebblebase’s own settings. BLOB results are base64 objects.

query_sql · Reads only

Read a pebble with SQLite SELECT statements (https://sqlite.org/lang_select.html), using positional ? parameters, all in one read-only snapshot. Nothing is saved: writes, schema changes, transactions, ATTACH and pragmas that set values are refused.

Returns columns and rows for each statement. At most 1,000 rows per statement, 200,000 characters of results, and about two seconds. ‘localtime’ and BLOB results work as in execute_sql.

run_tests · Reads only

Run the database’s stored tests on a private in-memory copy. Nothing is saved.

Tests are rows in pebblebase_tests(name, given, expect, expect_error). Each runs the SQL in given, then expect: a query whose rows are failures (no rows = pass). Set expect_error instead of expect when given must fail with an error containing that text. The clock reads 2026-01-15 12:00:00 UTC; SELECT pebblebase_set_clock(’…’) in given moves it. ‘localtime’ uses the database’s time zone, as in execute_sql. About 2 seconds per test and 10 seconds per run. Results also list warnings about triggers (reaching into another model, two on one event, cycles) and about how forms and views will draw.

export_database · Changes data

Get a link that downloads the database as one SQLite file, for the user to save.

Show the link to the user; don’t fetch it. Anyone with the link can download the file for 15 minutes without signing in. The file is the database as saved when downloaded, pebblebase_ tables included, and opens in any SQLite tool. Databases over 50 MB are refused.

show_view · Reads only

Show a view declared in pebblebase_views(name, kind, query). Its query runs read-only in the database’s time zone. Returns kind, columns and rows (truncated when large), and problem when the rows don’t fit the kind.

show_form · Reads only

Show the user a form that adds one row to a table: a field per column, CHECK (x IN (…)) as choices. prefill is {column: value}, shown and editable. Submit saves the row. Pass key instead to edit that row, where the table allows it. Where the host can’t draw forms, execute_sql can INSERT the row instead.

create_sign_in_link · Changes data

Get a link that signs the person in to pebblebase on a new device, once, within 20 minutes, then offers to save a passkey there. Use only when they ask to sign in on a new device or lost their passkey. Show it only to them; never open, fetch or store it. It signs in this chat’s account only.

submit_form, update_row and delete_row are called only by the form and record views pebblebase draws in chat; AIs don’t call them.

I have a question about pebblebase. First read https://pebblebase.dev/docs/reference/tools.md, then help me with this: