Skip to content

feat: support for explicit column names for references #1458

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adrenalin wants to merge 10 commits into
base: main
Choose a base branch
from
Open

feat: support for explicit column names for references #1458

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
5dff71f
Added References type to extend Name
adrenalin Jul 9, 2025
2df9f18
Allow Literal to ingest References type
adrenalin Jul 9, 2025
e8fd9bb
Allow using optional columns for references to define the target colu…
adrenalin Jul 9, 2025
f3e21cf
Updated documentation for foreign key references
adrenalin Jul 9, 2025
ccc72bb
Refined new test descriptions and removed related unnecessary comment…
adrenalin Jul 9, 2025
090d547
Added Reference to the Type section and renamed Type to Types
adrenalin Jul 9, 2025
7c21d5c
Create a shallow copy of the reference columns
adrenalin Jul 9, 2025
2e89fd4
Readability refactoring, type safety has already been established
adrenalin Jul 13, 2025
3e4f08c
Merge branch 'main' into feat-explicit-column-names-for-references
adrenalin Jul 16, 2025
3f9b820
Merge branch 'main' into feat-explicit-column-names-for-references
adrenalin Jul 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 37 additions & 37 deletions docs/src/migrations/columns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,27 +6,27 @@ The `createTable` and `addColumns` methods both take a `columns` argument that s
It is an object (key/value) where each key is the name of the column,
and the value is another object that defines the options for the column.

| Option | Type | Description |
| ----------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------- |
| `type` | `string` | Data type (use normal postgres types) |
| `collation` | `string` | Collation of data type |
| `unique` | `boolean` | Set to true to add a unique constraint on this column |
| `primaryKey` | `boolean` | Set to true to make this column the primary key |
| `notNull` | `boolean` | Set to true to make this column not null |
| `default` | `string` | Adds DEFAULT clause for column. Accepts null, a literal value, or a `pgm.func()` expression. |
| `check` | `string` | SQL for a check constraint for this column |
| `references` | [Name](/migrations/#type) or `string` | A table name that this column is a foreign key to |
| `referencesConstraintName` | `string` | Name of the created constraint |
| `referencesConstraintComment` | `string` | Comment on the created constraint |
| `onDelete` | `string` | Adds ON DELETE constraint for a reference column |
| `onUpdate` | `string` | Adds ON UPDATE constraint for a reference column |
| `match` | `string` | `FULL` or `SIMPLE` |
| `deferrable` | `boolean` | Flag for deferrable column constraint |
| `deferred` | `boolean` | Flag for initially deferred deferrable column constraint |
| `comment` | `string` | Adds comment on column |
| `expressionGenerated` | `string` | Expression to compute column value |
| `sequenceGenerated` | `object` | Creates identity column see [sequence options section](sequences.md#sequence-options) |
| `precedence` | `string` | `ALWAYS` or `BY DEFAULT` |
| Option | Type | Description |
| ----------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------- |
| `type` | `string` | Data type (use normal postgres types) |
| `collation` | `string` | Collation of data type |
| `unique` | `boolean` | Set to true to add a unique constraint on this column |
| `primaryKey` | `boolean` | Set to true to make this column the primary key |
| `notNull` | `boolean` | Set to true to make this column not null |
| `default` | `string` | Adds DEFAULT clause for column. Accepts null, a literal value, or a `pgm.func()` expression. |
| `check` | `string` | SQL for a check constraint for this column |
| `references` | [Name](/migrations/#types) or `string` | A table name that this column is a foreign key to |
| `referencesConstraintName` | `string` | Name of the created constraint |
| `referencesConstraintComment` | `string` | Comment on the created constraint |
| `onDelete` | `string` | Adds ON DELETE constraint for a reference column |
| `onUpdate` | `string` | Adds ON UPDATE constraint for a reference column |
| `match` | `string` | `FULL` or `SIMPLE` |
| `deferrable` | `boolean` | Flag for deferrable column constraint |
| `deferred` | `boolean` | Flag for initially deferred deferrable column constraint |
| `comment` | `string` | Adds comment on column |
| `expressionGenerated` | `string` | Expression to compute column value |
| `sequenceGenerated` | `object` | Creates identity column see [sequence options section](sequences.md#sequence-options) |
| `precedence` | `string` | `ALWAYS` or `BY DEFAULT` |

## Data types & Convenience Shorthand

Expand Down Expand Up @@ -72,11 +72,11 @@ pgm.addColumns('myTable', { id: { type: 'serial', primaryKey: true } });

#### Arguments

| Name | Type | Description |
| ------------- | ------------------------- | ------------------------------------------------------------------------------- |
| `tablename` | [Name](/migrations/#type) | Name of the table to alter |
| `new_columns` | `object` | Column names / options -- see [column definitions section](#column-definitions) |
| `options` | `object` | Check below for available options |
| Name | Type | Description |
| ------------- | -------------------------- | ------------------------------------------------------------------------------- |
| `tablename` | [Name](/migrations/#types) | Name of the table to alter |
| `new_columns` | `object` | Column names / options -- see [column definitions section](#column-definitions) |
| `options` | `object` | Check below for available options |

##### Options

Expand All @@ -97,7 +97,7 @@ pgm.addColumns('myTable', { id: { type: 'serial', primaryKey: true } });

| Name | Type | Description |
| ----------- | ------------------------------ | ---------------------------------------- |
| `tablename` | [Name](/migrations/#type) | Name of the table to alter |
| `tablename` | [Name](/migrations/#types) | Name of the table to alter |
| `columns` | `array of strings` or `object` | Columns to drop (if objected, uses keys) |
| `options` | `object` | Check below for available options |

Expand All @@ -119,11 +119,11 @@ pgm.addColumns('myTable', { id: { type: 'serial', primaryKey: true } });

#### Arguments

| Name | Type | Description |
| ----------------- | ------------------------- | ------------------- |
| `tablename` | [Name](/migrations/#type) | Name of the table |
| `old_column_name` | `string` | Current column name |
| `new_column_name` | `string` | New column name |
| Name | Type | Description |
| ----------------- | -------------------------- | ------------------- |
| `tablename` | [Name](/migrations/#types) | Name of the table |
| `old_column_name` | `string` | Current column name |
| `new_column_name` | `string` | New column name |

### Operation: `alterColumn`

Expand All @@ -135,11 +135,11 @@ pgm.addColumns('myTable', { id: { type: 'serial', primaryKey: true } });

#### Arguments

| Name | Type | Description |
| ---------------- | ------------------------- | --------------------------- |
| `tablename` | [Name](/migrations/#type) | Name of the table |
| `column_name` | `string` | Column to alter |
| `column_options` | `object` | Optional new column options |
| Name | Type | Description |
| ---------------- | -------------------------- | --------------------------- |
| `tablename` | [Name](/migrations/#types) | Name of the table |
| `column_name` | `string` | Column to alter |
| `column_options` | `object` | Optional new column options |

##### Column Options

Expand Down
48 changes: 24 additions & 24 deletions docs/src/migrations/constraints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@

### Arguments

| Name | Type | Description |
| ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `tablename` | [Name](/migrations/#type) | Name of the table to alter |
| `constraint_name` | `string` | Name for the constraint |
| `expression` | `string` or `object` | Constraint expression (raw sql) or definition -- see [constraint definition section](#constraint-definition) |
| Name | Type | Description |
| ----------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `tablename` | [Name](/migrations/#types) | Name of the table to alter |
| `constraint_name` | `string` | Name for the constraint |
| `expression` | `string` or `object` | Constraint expression (raw sql) or definition -- see [constraint definition section](#constraint-definition) |

#### Constraint Definition

Expand All @@ -32,15 +32,15 @@

#### Foreign Keys

| Option | Type | Description |
| ----------------------------- | -------------------------- | ---------------------------------------------------------------------------------- |
| `columns` | `Name` or `array of Names` | Names of columns |
| `references` | `Name` | Names of foreign table and column names |
| `referencesConstraintName` | `string` | Name of the created constraint (only necessary when creating multiple constraints) |
| `referencesConstraintComment` | `string` | Comment on the individual foreign key constraint |
| `onDelete` | `string` | Action to perform on delete |
| `onUpdate` | `string` | Action to perform on update |
| `match` | `string` | `FULL` or `SIMPLE` |
| Option | Type | Description |
| ----------------------------- | --------------------------------- | ---------------------------------------------------------------------------------- |
| `columns` | `Name` or `array of Names` | Names of columns |
| `references` | [`Reference`](/migrations/#types) | Names of foreign table and column names |
| `referencesConstraintName` | `string` | Name of the created constraint (only necessary when creating multiple constraints) |
| `referencesConstraintComment` | `string` | Comment on the individual foreign key constraint |
| `onDelete` | `string` | Action to perform on delete |
| `onUpdate` | `string` | Action to perform on update |
| `match` | `string` | `FULL` or `SIMPLE` |

## Reverse Operation: `dropConstraint`

Expand All @@ -51,11 +51,11 @@

### Arguments

| Name | Type | Description |
| ----------------- | ------------------------- | --------------------------------- |
| `tablename` | [Name](/migrations/#type) | Name of the table to alter |
| `constraint_name` | `string` | Name of the constraint |
| `options` | `object` | Check below for available options |
| Name | Type | Description |
| ----------------- | -------------------------- | --------------------------------- |
| `tablename` | [Name](/migrations/#types) | Name of the table to alter |
| `constraint_name` | `string` | Name of the constraint |
| `options` | `object` | Check below for available options |

#### Options

Expand All @@ -75,8 +75,8 @@

### Arguments

| Name | Type | Description |
| --------------------- | ------------------------- | -------------------------- |
| `tablename` | [Name](/migrations/#type) | Name of the table to alter |
| `old_constraint_name` | `string` | Current constraint name |
| `new_constraint_name` | `string` | New constraint name |
| Name | Type | Description |
| --------------------- | -------------------------- | -------------------------- |
| `tablename` | [Name](/migrations/#types) | Name of the table to alter |
| `old_constraint_name` | `string` | Current constraint name |
| `new_constraint_name` | `string` | New constraint name |
Loading
Loading