Lifecycle

Enumerate / inspect / empty / remove existing tables. See the Tables hub for the full RPC list.

ListTables, GetTable and DeleteTable are not RPCs. The Tables service has exactly one lifecycle RPC — DropTable — and it accepts either a typed DropSpec or a DROP TABLE SQL string. Everything else is SQL. dodil data table list sends SHOW TABLES; dodil data table get is an alias of describe and sends DESCRIBE (cli-shell/cli-k3/cmd/table.go:76-120).

SHOW TABLES

SHOW TABLES;

dodil data table list -b kb-prod

psql "host=pg.uk-lon-1.dodil.io port=5432 dbname=acme--kb-prod user=$DODIL_KEY password=$DODIL_SECRET sslmode=require" \
  -c '\dt'

curl -sS -X POST "https://table.uk-lon-1.dodil.io/v1/databases/acme--kb-prod/sql/execute" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SHOW TABLES"}'

{
  "kind": "query",
  "columns": [
    { "name": "table",      "type": "STRING", "vectorDimension": 0 },
    { "name": "pk_columns", "type": "STRING", "vectorDimension": 0 }
  ],
  "rows": [
    { "table": "events", "pk_columns": "id,user_id" },
    { "table": "users",  "pk_columns": "id" }
  ],
  "rowCount": 2,
  "warnings": []
}

DESCRIBE

Schema rows only — five columns: column, type, nullable, pk, default. It is not a stats call. The reported type is the effective one, so a column that has been logically retyped shows its new type, and logically dropped columns are absent.

DESCRIBE "events";

dodil data table describe events -b kb-prod
# `dodil data table get events -b kb-prod` is the same command

psql "$DODIL_PG_DSN" -c '\d events'

For size, residency, WAL backlog and reject counts, use GetDatabaseStats — see Schema → Database stats.

TRUNCATE TABLE

Removes all rows but keeps the schema, primary key, secondary indexes (emptied), graph bindings and reservations. A single empty Delta commit plus a WAL/overlay purge, all-or-nothing on the log. This is the sanctioned “delete everything” — a bare DELETE with no WHERE is refused.

TRUNCATE TABLE events;

RESTART IDENTITY / CONTINUE IDENTITY and CASCADE / RESTRICT are accepted as no-ops (the plane has no sequences and enforces no foreign keys). TRUNCATE … PARTITION and multi-table TRUNCATE are refused.

DropTable

Permanently deletes the table — the Delta directory, the HTAP sidecar and any un-drained WAL objects.

For a pipeline-backed table, the drop does not cascade to the bound pipeline or its ingest rule. Clean those up separately via Pipelines → DeleteRule.

Request

DROP TABLE IF EXISTS events;

dodil data table delete events -b kb-prod

rpc DropTable(DropTableRequest) returns (DropTableResponse);
 
message DropTableRequest {
  string db_id = 1;
  oneof ddl {
    DropSpec spec = 2;
    string sql = 3;                    // "DROP TABLE …"
  }
}
 
message DropSpec {
  string table_name = 1;
  bool if_exists = 2;
}

{
  "db_id": "acme--kb-prod",
  "spec": { "table_name": "events", "if_exists": true }
}

curl -sS -X POST "https://table.uk-lon-1.dodil.io/v1/databases/acme--kb-prod/sql/execute" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql":"DROP TABLE IF EXISTS events"}'

Response

message DropTableResponse {
  string table_name = 1;
  bool existed = 2;
  uint64 objects_deleted = 3;
  int64 bytes_deleted = 4;
  bool sidecar_deleted = 5;
  uint64 wal_objects_deleted = 6;
}

{
  "table_name": "events",
  "existed": true,
  "objects_deleted": 37,
  "bytes_deleted": 184729302,
  "sidecar_deleted": true,
  "wal_objects_deleted": 3
}

Through Execute the same drop returns an ExecuteResponse.ddl (DdlResult) carrying table_name and objects_deleted.

See also

• Create — CreateTable · CreateTablePipeline
• Schema — AlterTable and database stats
• Maintenance → RESTORE — roll a table back to an earlier version
• Core Concepts → Table — type signature + both creation modes
• CLI Guide — dodil data table list / describe / delete