mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-22 15:01:39 +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
1.6 KiB
1.6 KiB
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,
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,
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;
```