dclient/docs/writing.md

Writing data

In addition to insert (documented in {doc}inserting), dclient provides several commands for modifying data in a Datasette instance via the Write API.

All write commands require authentication. See {doc}authentication for how to set up tokens.

Creating tables

Use dclient create-table to create a new empty table with an explicit schema:

dclient create-table https://example.com/db mytable \
  --column id integer \
  --column name text \
  --column age integer \
  --pk id

Output:

{
  "ok": true,
  "database": "db",
  "table": "mytable",
  "schema": "CREATE TABLE [mytable] (\n   [id] INTEGER PRIMARY KEY,\n   [name] TEXT,\n   [age] INTEGER\n)"
}

Use --pk one or more times to set compound primary keys:

dclient create-table https://example.com/db events \
  --column date text --column venue text --column title text \
  --pk date --pk venue

Upserting data

Use dclient upsert to insert rows or update existing ones based on primary key. This works like insert but uses the upsert API endpoint:

dclient upsert https://example.com/db mytable data.csv

The same file format options as insert are supported: --csv, --tsv, --json, --nl, --encoding, --no-detect-types.

Upsert from standard input:

echo '[{"id": 1, "name": "Updated"}]' | \
  dclient upsert https://example.com/db mytable - --json

Use --alter to add any missing columns automatically.

Updating a single row

Use dclient update to update specific columns of a row by its primary key:

dclient update https://example.com/db/mytable 42 name=Alice age=30

Values are automatically parsed — numbers become integers/floats, true/false become booleans, null becomes null. Everything else is treated as a string.

Use --alter to allow adding new columns that don't exist yet.

Deleting a row

Use dclient delete to delete a single row by primary key:

dclient delete https://example.com/db/mytable 42

You'll be prompted for confirmation. Use --yes to skip the prompt:

dclient delete https://example.com/db/mytable 42 --yes

Dropping a table

Use dclient drop to drop an entire table:

dclient drop https://example.com/db/mytable

Without --yes, dclient will first query the table and show you the row count before asking for confirmation:

Drop table mytable (150 rows)? [y/N]:

Use --yes to skip confirmation:

dclient drop https://example.com/db/mytable --yes

dclient create-table --help

Usage: dclient create-table [OPTIONS] URL_OR_ALIAS TABLE_NAME

  Create a new empty table with explicit schema

  Example usage:

      dclient create-table https://example.com/db mytable \
        --column id integer --column name text --pk id

Options:
  --column TEXT...  Column definition: name type (e.g. --column id integer
                    --column name text)
  --pk TEXT         Column(s) to use as primary key
  --token TEXT      API token
  -v, --verbose     Verbose output
  --help            Show this message and exit.

dclient upsert --help

Usage: dclient upsert [OPTIONS] URL_OR_ALIAS TABLE FILEPATH

  Upsert data into a remote Datasette table

  Rows with matching primary keys will be updated; others will be inserted. Each
  row must include the primary key column(s).

  Example usage:

      dclient upsert \
        https://private.datasette.cloud/data \
        mytable data.csv

Options:
  --csv                 Input is CSV
  --tsv                 Input is TSV
  --json                Input is JSON
  --nl                  Input is newline-delimited JSON
  --encoding TEXT       Character encoding for CSV/TSV
  --no-detect-types     Don't detect column types for CSV/TSV
  --alter               Alter table to add any missing columns
  --batch-size INTEGER  Send rows in batches of this size
  --interval FLOAT      Send batch at least every X seconds
  -t, --token TEXT      API token
  --silent              Don't output progress
  -v, --verbose         Verbose output: show HTTP request and response
  --help                Show this message and exit.

dclient update --help

Usage: dclient update [OPTIONS] URL_OR_ALIAS PK_VALUES [UPDATES]...

  Update a row by primary key

  Pass key=value pairs to set column values.

  Example usage:

      dclient update https://example.com/db/table 42 name=Alice age=30

Options:
  --token TEXT   API token
  --alter        Alter table to add any missing columns
  -v, --verbose  Verbose output
  --help         Show this message and exit.

dclient delete --help

Usage: dclient delete [OPTIONS] URL_OR_ALIAS PK_VALUES

  Delete a row by primary key

  Example usage:

      dclient delete https://example.com/db/table 42
      dclient delete https://example.com/db/table 42 --yes

Options:
  --token TEXT   API token
  --yes          Skip confirmation
  -v, --verbose  Verbose output
  --help         Show this message and exit.

dclient drop --help

Usage: dclient drop [OPTIONS] URL_OR_ALIAS

  Drop a table

  Example usage:

      dclient drop https://example.com/db/table
      dclient drop https://example.com/db/table --yes

Options:
  --token TEXT   API token
  --yes          Skip confirmation
  -v, --verbose  Verbose output
  --help         Show this message and exit.