Database

A tool ref to some of its operations, for tools=: "query" (a read-only statement), "execute" (a statement that writes) and "schema" (its tables and columns). The database itself in tools= gives all three. "upsert" writes one row of one table, inserting it or updating the row with its primary key; its parameters are that table's columns, so the model fills a form rather than writing SQL. Bind its table with .bind(table=...).

Create a database called name, unique to its user (a taken name raises noclick.Conflict with existing_id). region (noclick.regions()) is where its data is kept, for good; without one, your account's default region, else us-east. A SQLite database outside eu is placed in its region as capacity allows (us-east and us-west keep it in the United States). An agent or app in the same region reaches it fastest.

A lazy reference to the database called name in the current (or given) user. With create_if_missing=True it's created on first use with engine in region (as create); one that exists is used as it is, whatever its engine and region.

Inside a deployed app (signed in by its deployment) the name is looked up in the app's own namespace for the environment the code runs in, and one made there is the app's: a name bound to the app by hand wins, and in a preview of an app whose preview_resources is branch the branch gets its own copy at its first write, reading production's as it is until then, so a preview never changes production's data. A Postgres copy is a copy-on-write branch of production's data. A SQLite copy holds the schema and migrations only (migrate's seed fills it), unless branch_data="copy" asks for production's rows too: they're read at one moment while production keeps serving, from a database of up to 200,000 rows and 16 MB. Asked after the branch's copy was made without them, that copy goes to the trash and the next write makes one with them. branch_data changes nothing outside a preview.

A lazy reference to a database by id.

Load a database by id now; an unknown id raises noclick.NotFound.

The current user's databases (the account's own outside as_user, or those user_filter covers), branches included.

One page of databases; pass next_cursor back as cursor.

Run a read: one select (or with ... select) that changes nothing. It runs read-only, so a statement that writes raises noclick.InvalidRequest; use execute for those. A result is at most 10 MB and a statement stops after 30 seconds. On Postgres, noclick.embed(:q, model) turns a parameter or a quoted text into a halfvec before the statement runs (up to 100 distinct texts a request; not over connection_url), so a read, an agent's query tool among them, can search by meaning without your code embedding first (billed as AI to the database's user).

Run one statement that writes: insert, update, delete or DDL (several go in a batch). A SQLite database that would pass 10 GB raises noclick.QuotaExceeded, whose next step is branching into Postgres. SQLite refuses virtual tables, so every database exports as plain SQL.

Run up to 100 statements in one transaction: all of them apply or none do. Each is the SQL alone or a (sql, params) pair.

Apply the migrations the database hasn't run yet, in name order: migrations is a local directory (its *.sql files, read here) or a {name: sql} dict. They run in one transaction, so a failing migration applies none of them and raises noclick.InvalidRequest naming it. A name that already ran with different SQL raises noclick.Conflict. dry_run=True reports what would run and changes nothing.

seed is a SQL file that runs once, after the migrations and in their transaction, on a preview branch's database that holds none of production's data (a SQLite copy made without its rows, or one only the branch has), so the preview has something to show; it shows in applied and the ledger as (seed). Production never runs it. Without seed, a seed.sql beside the migrations directory is the seed (supabase/seed.sql beside supabase/migrations/ is).

The migrations this database has applied.

The database's tables, their columns and row counts.

Put the database back as it was at at (a timezone-aware datetime), in place: anything written since is gone. at must be within its history: 30 days on SQLite, 7 on Postgres. While it runs, status is restoring and queries raise noclick.Conflict. To look at the past without losing the present, branch at that time instead.

Copy the database into a new one called name: as it is now, or as it was at at (within its history: 30 days on SQLite, 7 on Postgres). engine="postgres" branches a SQLite database into Postgres, the way past SQLite's 10 GB. The branch is a database of its own (parent_id names this one) for the same user. While a SQLite database is copied, its status is branching and queries raise noclick.Conflict.

The databases branched from this one.

A Postgres connection string for tools that speak the wire protocol (psql, an ORM, a BI tool), with a password that stops working after ttl_s seconds (60 to 86,400), when any session still open on it ends. read_only=True connects as a role that can only read. A SQLite database has no wire protocol and raises noclick.NotAvailable.

Export the database as SQL that recreates its schema and rows in any database of its engine: sqlite3 booking.db < databases/booking-db.sql, or a pg_dump script for psql (NoClick's own noclick schema, owners and grants left out). Exporting a Postgres database wakes it, and its compute is billed as any use is.

Delete the database and its data: it goes to the trash, restorable for 30 days (its storage billed until it's purged), and its connection URLs stop working. One with branches raises noclick.Conflict naming them until you delete them, as does one an app still binds or an agent has in its tools.