mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-19 05:21:47 +03:00
8a999bd44d
### Description This PR does several things: - it cleans up some structural issues with the engineering documentation: - it harmonizes the table of contents structure across different files - adds a link to the bigquery documentation - moves some files to a new `deep-dives` subfolder - puts a title at the top of each page to avoid github assuming their title is "table of contents" - it pre-fills the glossary with a long list of words that could use an entry (all empty for now) - it adds the only remaining relevant server file from [hasura-internal's wiki](https://github.com/hasura/graphql-engine-internal/wiki): the old "multiple backends architecture" file ### Discussion A few things worth discussing in the scope of this PR: - is it worth migrating old documentation such as the multiple backends architecture, that document a decision process rather instead of being up-to-date reflections of the code? are we planning to delete hasura-internal? - should we focus instead on _new_ documentation, aimed to be kept up to date? - are there other old documents we want to move in here, or is that it? - is this glossary structure ok, or would a purely alphabetical structure make sense? - does it make sense to have the glossary only in the engineering section? more generally, _what's our broader plan for documentation_? PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4537 GitOrigin-RevId: c2b674657b19af7a75f66a2a304c80c30f5b0afb
57 lines
1.6 KiB
Markdown
57 lines
1.6 KiB
Markdown
# Guidelines for adding migrations
|
|
|
|
## 1. Additive changes should be preferred over transformational changes.
|
|
|
|
For example,
|
|
|
|
We have to change a type of the column `locked` from `bool` to `timestamp with time zone`
|
|
where when the value of the column is `true` then the new value should be the
|
|
current timestamp and when the value of the column is `false` it should be `null`.
|
|
|
|
Instead of doing,
|
|
|
|
```sql
|
|
ALTER TABLE hdb_catalog.event_log ALTER COLUMN locked TYPE TIMESTAMPTZ USING CASE WHEN locked THEN NOW() ELSE NULL END;
|
|
```
|
|
|
|
It's preferred to do,
|
|
|
|
```sql
|
|
ALTER TABLE hdb_catalog.event_log RENAME COLUMN locked TO locked_boolean;
|
|
|
|
ALTER TABLE hdb_catalog.event_log ADD COLUMN locked TIMESTAMPTZ;
|
|
|
|
UPDATE hdb_catalog.event_log
|
|
SET locked = NOW()
|
|
WHERE locked_boolean = 't';
|
|
|
|
ALTER TABLE hdb_catalog.event_log DROP COLUMN locked_boolean;
|
|
```
|
|
|
|
This is because in the former way, the `ALTER TABLE` will acquire an lock on the `hdb_catalog.event_log` table
|
|
and will keep the lock until all the rows are transformed to the new data type. The latter method is preffered although
|
|
it does 4 queries, because all the DDL statements do not depend on the data contained in the rows.
|
|
|
|
## 2. Avoid adding a default value while adding a new column to an existing table
|
|
|
|
Instead of doing,
|
|
|
|
```sql
|
|
ALTER TABLE <table>
|
|
ADD COLUMN col1 INT SET DEFAULT 1 NOT NULL;
|
|
```
|
|
|
|
Do,
|
|
|
|
```sql
|
|
ALTER TABLE <table>
|
|
ADD COLUMN col1 INT;
|
|
|
|
UPDATE <table>
|
|
SET col1 = 1;
|
|
|
|
ALTER TABLE <table>
|
|
ALTER COLUMN col1 SET DEFAULT 1
|
|
ALTER COLUMN col1 SET NOT NULL;
|
|
```
|