relman CLI: Schema Change Actions

← Back to the relman CLI command overview

Schema change actions (change bundles)

Schema changes are never applied directly. They are proposed into a change bundle, exactly like the web UI’s schema editor – nothing runs against the database until the bundle is sealed there. Every action below is one line inside such a bundle.

add changebundle <org-token> <pg-token> <project-token> <task-token> (aliases: changebundles, cb, cbs)

Creates a new, empty database change bundle for the task identified by <task-token> and prints its id and state – the same way the web UI’s “add change bundle” button does (unsealed, with audition-table updates enabled). Individual schema changes are not part of this command; this only creates the empty container they get added to.

list actions <org-token> <pg-token> <project-token> <task-token> <changebundle-token> (alias: action)

Fetches every proposed schema change (“action”) in the change bundle, across all sixteen action types below. This is the only way to find an existing action’s id to feed into the matching edit/cancel command, since add only ever hands back the id of the one it just created.

The sixteen action types

Every action type supports add, edit and cancel. cancel <action-type> <org> <pg> <project> <task> <changebundle> <action> is the same six-argument shape for every one of the sixteen types, so it is not repeated below – only what makes each add/edit distinct is.

table / renametable / removetable

• add table <org> <pg> <project> <db> <catalog> <schema> <task> <changebundle> <table-name> <pk-column-name> <pk-column-type> [table-comment] [pk-column-comment] – proposes a new table in the schema identified by <schema>. <pk-column-type> is a type name as shown by list column (e.g. int8), resolved server-side – no raw JDBC type constant needed.
• add renametable/add removetable follow the same argument shape, targeting the table to rename/remove instead of proposing a new one.

column / removecolumn

add column <org> <pg> <project> <db> <catalog> <schema> <table> <task> <changebundle> <column-name> <native-type> <nullable> <primary-key> <unique> <auto-increment> [character-length] [default-value] [column-comment] – proposes a new column on the table identified by <table>. <native-type> is a type name as shown by list column (e.g. varchar), resolved server-side. <nullable>/<primary-key>/<unique>/<auto-increment> are true/false.

foreignkey / removeforeignkey / removeforeignkeyonetoone

add foreignkey <org> <pg> <project> <db> <catalog> <schema> <from-table> <from-column-token> <to-table> <to-column-token> <task> <changebundle> <fk-name> <delete-cascade> [fk-comment] – proposes a new foreign key from <from-column-token> (on <from-table>) to <to-column-token> (on <to-table>, both assumed within the same catalog/schema). <delete-cascade> is true/false.

Two gotchas worth knowing: <from-column-token>/<to-column-token> must be column tokens – the id field printed by list column – not the plain column name; unlike table arguments, there is no name-based fallback, so a name here silently resolves to nothing and the server answers HTTP 400. And [fk-comment], if given, becomes the literal text of a generated SQL COMMENT ON ... IS '...' statement; a single quote in it is not escaped server-side and breaks that statement (and with it the whole change bundle’s execution) – avoid apostrophes.

Column property edits: columnname, columndefault, columnnullability, columndimension, columncomment, columnuniqueness, columnprimarykey, columnautoincrement

These eight action types each change one property of an existing column without touching its type – a rename, a new default, nullability, dimension (length/precision), comment, uniqueness, primary-key membership, or auto-increment flag. Every add/edit takes the same shape: <org> <pg> <project> <db> <catalog> <schema> <table> <column> <task> <changebundle> [<action>] <new-value-field(s)...> – the action id is inserted only for edit (find one via list actions). Every add/edit prints the action’s id.

Examples

1. Opening a change bundle

Global flags omitted below – see Utility & global flags.

$ relman add changebundle o-4kNc8Q pg-8mZ2Lx p-Qv73Tn t-Nc2Xp8
id: cb-Vt62Fq
sealed: false

Edge case: nothing runs against the database yet – sealed: false means this is still an editable proposal. Sealing it (running the actual DDL) is only available from the web UI, not from relman.

2. Proposing a new column

$ relman add column o-4kNc8Q pg-8mZ2Lx p-Qv73Tn db-9Zx4Kp cat-3Hs7Bn sch-6Yp2Nx tab-Lm83Vq t-Nc2Xp8 cb-Vt62Fq newsletter_opt_in bool true false false false
id: cbat-Hn84Ws

Edge case: bool must be exactly one of the type names list column shows for existing columns – a close-but-wrong name like boolean fails server-side with no autocorrect. The four trailing true/false arguments are nullable/primary-key/unique/auto-increment, in that fixed order – swapping two of them silently proposes the wrong constraint instead of raising an error, since they’re all the same type.

3. Proposing a foreign key – and the column-token gotcha

$ relman add foreignkey o-4kNc8Q pg-8mZ2Lx p-Qv73Tn db-9Zx4Kp cat-3Hs7Bn sch-6Yp2Nx tab-Qf29Rz col-Jm3Bxz tab-Lm83Vq col-Qs81Nc t-Nc2Xp8 cb-Vt62Fq fk_orders_customer false
id: cbat-Rk29Lm

Edge case: col-Jm3Bxz/col-Qs81Nc here are the column tokens from list column‘s id field – not the plain names like customer_id. Running the same command with a column name instead of its token doesn’t raise a helpful error: it silently resolves to nothing and the server answers a bare HTTP 400, which is easy to misread as a permissions problem instead of a wrong-argument-type problem.