Merge branch 'master' into data-environment

CHANGELOG.md

@@ -10,6 +10,7 @@
 - server: adjustments to idle GC to try to free memory more eagerly (related to #3388)
 - server: process events generated by the event triggers asynchronously (close #5189) (#5352)
 - console: display line number that error originated from in GraphQL editor (close #4849) (#4942)
+- docs: add page on created_at / updated_at timestamps (close #2880) (#5223)
 
 ## `v1.3.0-beta.4`
 

docs/_static/utils.js

@@ -0,0 +1,25 @@
+const hasuraUtils = {
+  formatNumber: function(number) {
+    if (typeof number !== "number") return number;
+
+    const SIsymbol = ["", "k", "M", "G", "T", "P", "E"];
+    const absNumber = Math.abs(number);
+    const sign = Math.sign(number);
+
+    // what tier? (determines SI symbol)
+    const tier = Math.log10(absNumber) / 3 | 0;
+
+    // if zero, we don't need a suffix
+    if (tier === 0) return sign * absNumber;
+
+    // get suffix and determine scale
+    const suffix = SIsymbol[tier];
+    const scale = Math.pow(10, tier * 3);
+
+    // scale the number
+    const scaled = absNumber / scale;
+
+    // format number and add suffix
+    return sign * scaled.toFixed(1) + suffix;
+  }
+}

docs/_theme/djangodocs/layout.html

@@ -6,6 +6,8 @@
 
 {% set css_files = css_files + ['_static/djangosite.css', '_static/hasura-custom.css'] %}
 
+{% set script_files = script_files + ['_static/utils.js'] %}
+
 {%- if is_landing_page %}
   {% set css_files = css_files + ['_static/landing.css'] %}
 {%- endif %}
@@ -751,7 +753,7 @@
           })
           .then(data => {
             const githubStar = data[0].star_count
-            $(".gitHubCount").html(githubStar);
+            $(".gitHubCount").html(hasuraUtils.formatNumber(githubStar));
             $(".gitHubBtn").removeClass("hide");
           })
           .catch(e => {

docs/graphql/manual/scheduled-triggers/index.rst

@@ -16,11 +16,7 @@ Scheduled triggers are used to execute custom business logic at a specific point
 
 .. admonition:: Supported from
 
-  Scheduled triggers are supported from versions ``v1.3.0-beta.1`` and above.
-
-.. .. admonition:: Supported from
-  
-..   Scheduled triggers are supported from versions ``v.1.3.0`` and above.
+  Scheduled triggers are supported from versions ``v.1.3.0`` and above.
 
 **See:**
 

docs/graphql/manual/schema/default-values/created-updated-timestamps.rst

@@ -0,0 +1,170 @@
+.. meta::
+   :description: Add created at / updated at timestamps
+   :keywords: hasura, docs, schema, default value, timestamps
+
+.. _created_updated_timestamps:
+
+Adding created_at / updated_at timestamps
+=========================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+We often need ``created_at`` and ``updated_at`` timestamp fields in our tables in order to indicate when an object was created or last updated.
+This page explains how to add these. 
+
+Add a created_at timestamp
+--------------------------
+
+.. rst-class:: api_tabs
+.. tabs::
+
+  .. tab:: Console
+
+    On the Hasura console, click on the ``Modify`` tab of a table. When clicking on the ``+Frequently used columns`` button, 
+    choose ``created_at``:
+
+    .. thumbnail:: /img/graphql/manual/schema/created-at.png
+        :alt: Add a created_at time on the Hasura console
+
+    Click the ``Add column`` button.
+
+  .. tab:: CLI
+
+    :ref:`Create a migration manually <manual_migrations>` and add the following SQL statement to the ``up.sql`` file:
+
+    .. code-block:: plpgsql
+
+      ALTER TABLE ONLY "public"."article" ADD COLUMN "created_at" TIMESTAMP DEFAULT NOW();
+
+    Add the following statement to the ``down.sql`` file in case you need to :ref:`roll back <roll_back_migrations>` the above statement:
+
+    .. code-block:: plpgsql
+
+      ALTER TABLE article DROP COLUMN created_at;
+
+    Apply the migration and reload the metadata:
+
+    .. code-block:: bash
+
+        hasura migrate apply
+        hasura metadata reload
+
+  .. tab:: API
+
+    You can add a ``created_at`` timestamp by using the :ref:`run_sql metadata API <run_sql>`:
+
+    .. code-block:: http
+
+      POST /v1/query HTTP/1.1
+      Content-Type: application/json
+      X-Hasura-Role: admin
+
+      {
+        "type": "run_sql",
+        "args": {
+            "sql": "ALTER TABLE ONLY \"article\" ADD COLUMN \"created_at\" TIMESTAMP DEFAULT NOW();"
+        }
+      }
+
+Add an updated_at timestamp
+---------------------------
+
+.. rst-class:: api_tabs
+.. tabs::
+
+  .. tab:: Console
+
+    On the Hasura console, click on the ``Modify`` tab of a table. When clicking on the ``+Frequently used columns`` button, 
+    choose ``updated_at``:
+
+    .. thumbnail:: /img/graphql/manual/schema/updated-at.png
+        :alt: Add an updated_at time on the Hasura console
+
+    Click the ``Add column`` button.
+
+  .. tab:: CLI
+
+    :ref:`Create a migration manually <manual_migrations>` and add the below SQL statement to the ``up.sql`` file:
+
+    1. Add an ``updated_at`` timestamp field to the ``article`` table.
+    2. Define a `Postgres function <https://www.postgresql.org/docs/current/sql-createfunction.html>`__ to set the ``updated_at`` field to ``NOW()``.
+    3. Create a `Postgres trigger <https://www.postgresql.org/docs/current/sql-createtrigger.html>`__ to call the defined function whenever an article is updated.
+
+    .. code-block:: plpgsql
+
+      ALTER TABLE ONLY "public"."article"
+      ADD COLUMN "updated_at" TIMESTAMP DEFAULT NOW();
+
+      CREATE FUNCTION trigger_set_timestamp()
+      RETURNS TRIGGER AS $$
+      BEGIN
+        NEW.updated_at = NOW();
+      RETURN NEW;
+      END;
+      $$ LANGUAGE plpgsql;
+
+      CREATE TRIGGER set_timestamp
+      BEFORE
+      UPDATE ON article
+      FOR EACH ROW
+      EXECUTE PROCEDURE trigger_set_timestamp();
+
+    Add the following statement to the ``down.sql`` file in case you need to :ref:`roll back <roll_back_migrations>` the above statement:
+
+    .. code-block:: plpgsql
+
+      DROP trigger set_timestamp on article;
+      DROP function trigger_set_timestamp();
+      ALTER TABLE article DROP COLUMN updated_at;
+
+    Apply the migration and reload the metadata:
+
+    .. code-block:: bash
+
+        hasura migrate apply
+        hasura metadata reload
+
+  .. tab:: API
+
+    You can add an ``updated_at`` timestamp by using the :ref:`run_sql metadata API <run_sql>`.
+
+    The below SQL statement will achieve the following:
+
+    1. Add an ``updated_at`` timestamp field to the ``article`` table.
+    2. Define a `Postgres function <https://www.postgresql.org/docs/current/sql-createfunction.html>`__ to set the ``updated_at`` field to ``NOW()``.
+    3. Create a `Postgres trigger <https://www.postgresql.org/docs/current/sql-createtrigger.html>`__ to call the defined function whenever an article is updated.
+
+    .. code-block:: http
+
+      POST /v1/query HTTP/1.1
+      Content-Type: application/json
+      X-Hasura-Role: admin
+
+      {
+        "type": "run_sql",
+        "args": {
+            "sql": 
+              "ALTER TABLE ONLY \"public\".\"article\"
+              ADD COLUMN \"updated_at\" TIMESTAMP DEFAULT NOW();
+
+              CREATE FUNCTION trigger_set_timestamp()
+              RETURNS TRIGGER AS $$
+              BEGIN
+                NEW.updated_at = NOW();
+              RETURN NEW;
+              END;
+              $$ LANGUAGE plpgsql;
+
+              CREATE TRIGGER set_timestamp
+              BEFORE
+              UPDATE ON article
+              FOR EACH ROW
+              EXECUTE PROCEDURE trigger_set_timestamp();"
+        }
+      }

docs/graphql/manual/schema/default-values/index.rst

@@ -24,6 +24,7 @@ the following ways:
 - :ref:`Role based column presets <column_presets>`: set up presets, using session variables or fixed values, that are
   applied when a new row is created with a particular :ref:`user role <roles_variables>`.
   E.g. set a ``user_id`` field automatically from a session variable/authorization header.
+- :ref:`Created_at / updated_at timestamps <created_updated_timestamps>`: set up ``created_at`` and ``updated_at`` timestamp values.
 
 .. toctree::
   :maxdepth: 1
@@ -32,4 +33,5 @@ the following ways:
   Postgres defaults <postgres-defaults>
   Custom SQL functions/stored procedures <sql-functions>
   Role based column presets <column-presets>
+  Created_at / updated_at timestamps <created-updated-timestamps>
 

docs/graphql/manual/schema/relay-schema.rst

@@ -22,11 +22,7 @@ The Hasura GraphQL engine serves a `Relay <https://relay.dev/>`__ schema for Pos
 
 .. admonition:: Supported from
 
-  Relay is supported from versions ``v1.3.0-beta.1`` and above.
-
-.. .. admonition:: Supported from
-
-..   Relay is supported from versions ``v.1.3.0`` and above.
+  Relay is supported from versions ``v.1.3.0`` and above.
 
 What is Relay?
 --------------