SQL

Query and manage SQLite databases from the TinyCloud CLI

The tc sql commands let you query, update, export, and copy SQLite databases in your TinyCloud space. Each space can use the default database or named databases with --db. Use --space when you need to target a non-primary space such as an application manifest space.

Commands

tc sql query

Run a read-only SELECT query.

tc sql query <sql>

Option	Description	Default
--db <name>	SQLite database name within the current space	default
--space <name|uri>	Target a non-primary space by short name or full URI	Current primary space
--params <json>	JSON array of bind parameters for ? placeholders	None

List rows

$ tc sql query "SELECT id, body FROM notes ORDER BY id"
  id  body
  1   ship docs
  2   test help

  2 rows returned

Bind params

$ tc sql query "SELECT * FROM notes WHERE id = ?" --params '[1]'
  id  body
  1   ship docs

  1 row returned

Named database

$ tc sql query "SELECT type, count(*) AS total FROM events GROUP BY type" --db analytics
  type    total
  signup  42
  view    319

JSON output

$ tc sql query "SELECT id, body FROM notes" --json
{
  "columns": ["id", "body"],
  "rows": [[1, "ship docs"]],
  "rowCount": 1
}

tc sql execute

Run a write or schema statement such as CREATE TABLE, INSERT, UPDATE, DELETE, or DROP TABLE.

tc sql execute <sql>

Option	Description	Default
--db <name>	SQLite database name within the current space	default
--space <name|uri>	Target a non-primary space by short name or full URI	Current primary space
--params <json>	JSON array of bind parameters for ? placeholders	None

Create table

$ tc sql execute "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)"
{
  "changes": 0,
  "lastInsertRowId": null
}

Insert row

$ tc sql execute "INSERT INTO notes (body) VALUES (?)" --params '["ship docs"]'
{
  "changes": 1,
  "lastInsertRowId": 1
}

Update row

$ tc sql execute "UPDATE notes SET body = ? WHERE id = ?" --params '["test help", 1]'
{
  "changes": 1,
  "lastInsertRowId": null
}

tc sql export

Download the raw SQLite database file.

tc sql export

Option	Description	Default
--db <name>	SQLite database name within the current space	default
--space <name|uri>	Target a non-primary space by short name or full URI	Current primary space
-o, --output <file>	Output file path	export.db

Default database

$ tc sql export
{
  "file": "/Users/alice/project/export.db",
  "size": 16384,
  "sizeHuman": "16 KB"
}

Named database

$ tc sql export --db analytics --output analytics.db
{
  "file": "/Users/alice/project/analytics.db",
  "size": 32768,
  "sizeHuman": "32 KB"
}

tc sql copy

Copy rows between SQLite databases, optionally across spaces.

tc sql copy --from-db <name> --to-db <name>

Option	Description	Default
--from-db <name>	Source database name	Required
--to-db <name>	Destination database name	Required
--from-space <name|uri>	Source space by short name or full URI	Current primary space
--to-space <name|uri>	Destination space by short name or full URI	Current primary space
--table <name...>	Restrict copy to one or more tables. Repeat or pass comma-separated names.	All user tables
--dry-run	Plan the copy without writing destination rows	false

tc sql copy \
  --from-space applications \
  --from-db xyz.tinycloud.listen/conversations \
  --to-db listen-export \
  --table conversation \
  --dry-run

Parameter Binding

Use --params for dynamic values instead of string interpolation. The value must be a JSON array, and values bind to ? placeholders in order.

tc sql execute \
  "INSERT INTO notes (body, priority) VALUES (?, ?)" \
  --params '["ship docs", 2]'

tc sql query \
  "SELECT * FROM notes WHERE priority >= ?" \
  --params '[2]'

Quote SQL strings so your shell passes the statement as one argument. Quote JSON params with single quotes when possible so double quotes inside the JSON are preserved.

Named Databases

Use --db when an app needs separate SQLite databases within the same space. Use --space when the database lives in another space that the active profile can access.

Default app database

tc sql execute "CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)"

Scripting

Add --json for stable machine-readable output, or pipe output to another command.

tc sql query "SELECT id, body FROM notes" --json | jq '.rows[]'

tc sql execute "DELETE FROM notes WHERE id = ?" --params '[1]' --json | jq '.changes'