Tables — Management

Create and drop custom tables and columns from your server with the client.tables module

The tables module manages the schema of your custom tables — creating and dropping tables, and adding and dropping columns. For reading and writing rows, see Tables — Rows. For the feature overview, see Custom Tables.

Table management is service-key only, so it lives in the server-side @sublay/node SDK only — the browser @sublay/js SDK and the React useTable hook are row-only. The same operations are also available in the dashboard data editor.

All names you pass are logical — Sublay applies the custom_ prefix for you.

---

createTable

Creates a custom table with the given columns and managed-column flags.

await sublay.tables.createTable({
  tableName: "Events",
  timestamps: true,
  paranoid: true,
  columns: [
    { columnName: "name", dataType: "text", nullable: false },
    { columnName: "capacity", dataType: "integer", nullable: true, defaultValue: "0" },
    { columnName: "startsAt", dataType: "timestamp", nullable: true },
    { columnName: "metadata", dataType: "json", nullable: true },
  ],
});

tableName · string · required

The logical table name (max 56 characters — 63 minus the custom_ prefix). Sublay stores it as custom_<tableName>.

columns · CustomColumnDefinition[] · required

The developer columns to create. Each is { columnName, dataType, nullable, defaultValue? }. dataType is one of text, integer, float, decimal, boolean, date, timestamp, uuid, json. A column may not be named id, createdAt, updatedAt, or deletedAt (reserved managed columns).

timestamps · boolean

Emit createdAt / updatedAt. Defaults to true.

paranoid · boolean

Emit deletedAt and enable soft delete. Requires timestamps. Defaults to false.

Returns — Promise<{ table: string }> — the physical (custom_*) table name.

Errors are returned with a database/* code: database/reserved-column (a column shadows a managed name), database/name-too-long (over 56 chars), database/table-limit-reached (100 tables), database/column-limit-reached (100 columns).

---

addColumn

Adds a column to an existing custom table.

await sublay.tables.addColumn({
  tableName: "Events",
  columnName: "venue",
  dataType: "text",
  nullable: true,
});

tableName · string · required

The logical table name.

columnName · string · required

The new column’s name (may not be a reserved managed name).

dataType · CustomColumnType · required

One of text, integer, float, decimal, boolean, date, timestamp, uuid, json.

nullable · boolean · required

Whether the column accepts null.

defaultValue · string | null

Optional default literal, validated against dataType.

Returns — Promise<{ added: string }>

---

dropColumn

Drops a column from a custom table. Managed columns (id, createdAt, updatedAt, deletedAt) cannot be dropped.

await sublay.tables.dropColumn({ tableName: "Events", columnName: "venue" });

tableName · string · required

The logical table name.

columnName · string · required

The column to drop.

Returns — Promise<{ dropped: string }>

---

dropTable

Drops a custom table and all of its rows. This is irreversible.

await sublay.tables.dropTable({ tableName: "Events" });

tableName · string · required

The logical table name.

Returns — Promise<{ dropped: string }>