docs: update hasura with examples of graphQL useage and postgres, and… (#148)

… missing dns config details from custom deployments

## Summary by Sourcery

Document Hasura usage with GraphQL and PostgreSQL, and add missing DNS
configuration details for custom deployments.

Enhancements:
- Add missing DNS configuration details for custom deployments,
including obtaining the application's hostname, accessing DNS settings,
configuring DNS records, setting TTL, verifying DNS propagation, and
SSL/TLS configuration.

Documentation:
- Document Hasura database interaction through GraphQL API and direct
PostgreSQL connection.
- Add usage examples for GraphQL and PostgreSQL.
- Document authentication setup for both GraphQL and PostgreSQL.

Co-authored-by: saeeddawod <saeed.dawod@gmail.com>

Author: SaeeDawod

docs/using-platform/14_custom-deployment.md

@@ -25,7 +25,7 @@ A Custom Deployment allows you to deploy your own Docker images, such as fronten
    - Environment variables (if required)
    - Custom domain information (if applicable)
 5. Configure any additional settings as needed.
-6. Click on 'Confirm' and wait for the Custom Deployment to be in the Running status.
+6. Click on 'Confirm' and wait for the Custom Deployment to be in the Running status. [View the list of statuses](../reference/14_statuses.md).
 
 </TabItem>
 <TabItem value="sdk-cli" label="SDK CLI">
@@ -92,9 +92,15 @@ When using custom domains with your Custom Deployment, you'll need to configure
    - Enter your desired custom domain (e.g., example.com for top-level domain or app.example.com for subdomain).
    - Save the changes to update your Custom Deployment settings.
 
-2. **Configure DNS Records**:
+2. **Obtain Your Application's Hostname**: After adding your custom domain, the SettleMint platform will provide you with an ALIAS (for top-level domains) or CNAME (for subdomains) record. This can be found in the "Connect" tab of your Custom Deployment.
+
+3. **Access Your Domain's DNS Settings**: Log in to your domain registrar or DNS provider's control panel.
+
+4. **Configure DNS Records**:
 
    For Top-Level Domains (e.g., example.com):
+   - Remove any existing A and AAAA records for the domain you're configuring.
+   - Remove any existing A and AAAA records for the www domain (e.g., www.example.com) if you're using it.
    ```
    ALIAS example.com gke-europe.settlemint.com
    ALIAS www.example.com gke-europe.settlemint.com
@@ -105,6 +111,20 @@ When using custom domains with your Custom Deployment, you'll need to configure
    CNAME app.example.com gke-europe.settlemint.com
    ```
 
+5. **Set TTL (Time to Live)**:
+   - Set a lower TTL (e.g., 300 seconds) initially to allow for quicker propagation.
+   - You can increase it later for better caching (e.g., 3600 seconds).
+
+6. **Verify DNS Propagation**:
+   - Use online DNS lookup tools to check if your DNS changes have propagated.
+   - Note that DNS propagation can take up to 48 hours, although it's often much quicker.
+
+7. **SSL/TLS Configuration**:
+   - The SettleMint platform typically handles SSL/TLS certificates automatically for both top-level domains and subdomains.
+   - If you need to use your own certificates, please contact us for assistance and further instructions.
+
+Note: The configuration process is similar for both top-level domains and subdomains. The main difference lies in the type of DNS record you create (ALIAS for top-level domains, CNAME for subdomains) and whether you need to remove existing records.
+
 ## Manage Custom Deployments
 
 <Tabs>
@@ -173,7 +193,7 @@ When using Custom Deployment, keep the following limitations in mind:
 1. **No Root User Privileges**: Your application will run without root user privileges for security reasons.
 
 2. **Read-Only Filesystem**: The filesystem is read-only. For data persistence, consider using:
-   - Hasura: A GraphQL engine that provides a scalable database solution
+   - Hasura: A GraphQL engine that provides a scalable database solution. See [Hasura](./9_hasura-backend-as-a-service.md).
    - Other External Services: Depending on your specific needs, you may use other cloud-based storage or database services
 
 3. **Stateless Applications**: Your applications should be designed to be stateless. This ensures better scalability and reliability in a cloud environment.
@@ -187,6 +207,8 @@ When using Custom Deployment, keep the following limitations in mind:
 - Implement proper logging to facilitate debugging and monitoring
 - Regularly update your container images to include the latest security patches
 
+Custom Deployment offers a powerful way to extend the capabilities of your blockchain solutions on the SettleMint platform. By following these guidelines and best practices, you can seamlessly integrate your custom applications into your blockchain ecosystem.
+
 :::info Note
 Custom Deployments support automatic SSL/TLS certificate management for custom domains.
 :::

docs/using-platform/9_hasura-backend-as-a-service.md

@@ -160,3 +160,200 @@ hasura metadata reload
 
 For more on Hasura Metadata, refer: https://hasura.io/docs/latest/migrations-metadata-seeds/manage-metadata/
 For more on Hasura Migrations, refer: https://hasura.io/docs/latest/migrations-metadata-seeds/manage-migrations/
+
+## Usage Examples
+
+You can interact with your Hasura database in two ways: through the GraphQL API (recommended) or directly via PostgreSQL connection.
+
+<Tabs>
+<TabItem value="graphql" label="GraphQL API (Recommended)">
+
+```javascript
+import fetch from 'node-fetch';
+
+// Configure your authentication details
+const HASURA_ENDPOINT = "YOUR_HASURA_ENDPOINT";
+const HASURA_ADMIN_SECRET = "YOUR_HASURA_ADMIN_SECRET"; // Found in the "Connect" tab of Hasura console
+const APP_ACCESS_TOKEN = "YOUR_APP_ACCESS_TOKEN"; // Generated following the Application Access Tokens guide
+
+// Reusable function to make GraphQL requests
+async function fetchGraphQL(operationsDoc, operationName, variables) {
+  try {
+    const result = await fetch(
+      HASURA_ENDPOINT,
+      {
+        method: "POST",
+        headers: {
+          'Content-Type': 'application/json',
+          'x-hasura-admin-secret': HASURA_ADMIN_SECRET,
+          'x-auth-token': APP_ACCESS_TOKEN
+        },
+        body: JSON.stringify({
+          query: operationsDoc,
+          variables: variables,
+          operationName: operationName
+        })
+      }
+    );
+
+    if (!result.ok) {
+      const text = await result.text();
+      throw new Error(`HTTP error! status: ${result.status}, body: ${text}`);
+    }
+
+    return await result.json();
+  } catch (error) {
+    console.error('Request failed:', error);
+    throw error;
+  }
+}
+
+// Query to fetch verification records
+const operationsDoc = `
+  query MyQuery {
+    verification {
+      id
+    }
+  }
+`;
+
+// Mutation to insert a new verification record
+const insertOperationDoc = `
+  mutation InsertVerification($name: String!, $status: String!) {
+    insert_verification_one(object: {name: $name, status: $status}) {
+      id
+      name
+      status
+    }
+  }
+`;
+
+// Function to fetch verification records
+async function main() {
+  try {
+    const { errors, data } = await fetchGraphQL(operationsDoc, "MyQuery", {});
+    
+    if (errors) {
+      console.error('GraphQL Errors:', errors);
+      return;
+    }
+
+    console.log('Data:', data);
+  } catch (error) {
+    console.error('Failed:', error);
+  }
+}
+
+// Function to insert a new verification record
+async function insertWithGraphQL() {
+  try {
+    const { errors, data } = await fetchGraphQL(
+      insertOperationDoc,
+      "InsertVerification",
+      {
+        name: "Test User",
+        status: "pending"
+      }
+    );
+    
+    if (errors) {
+      console.error('GraphQL Errors:', errors);
+      return;
+    }
+
+    console.log('Inserted Data:', data);
+  } catch (error) {
+    console.error('Failed:', error);
+  }
+}
+
+// Execute both query and mutation
+main();
+insertWithGraphQL();
+```
+
+</TabItem>
+<TabItem value="postgresql" label="Direct PostgreSQL Connection">
+
+```javascript 
+import pkg from 'pg';
+const { Pool } = pkg;
+
+// Initialize PostgreSQL connection (get connection string from Hasura console -> "Connect" tab)
+const pool = new Pool({
+  connectionString: 'YOUR_POSTGRES_CONNECTION_STRING'
+});
+
+// Simple query to read all records from verification table
+const readData = async () => {
+  const query = 'SELECT * FROM verification';
+  const result = await pool.query(query);
+  console.log('Current Data:', result.rows);
+};
+
+// Insert a new verification record with sample data
+const insertData = async () => {
+  const query = `
+    INSERT INTO verification (id, identifier, value, created_at, expires_at) 
+    VALUES ($1, $2, $3, $4, $5) 
+    RETURNING *`;
+  
+  // Sample values - modify according to your needs
+  const values = [
+    'test-id-123',
+    'test-identifier',
+    'test-value',
+    new Date(),
+    new Date(Date.now() + 24 * 60 * 60 * 1000) // Sets expiry to 24h from now
+  ];
+  
+  const result = await pool.query(query, values);
+  console.log('Inserted:', result.rows[0]);
+};
+
+// Update an existing record by ID
+const updateData = async () => {
+  const query = `
+    UPDATE verification 
+    SET value = $1, updated_at = $2 
+    WHERE id = $3 
+    RETURNING *`;
+  
+  const values = ['updated-value', new Date(), 'test-id-123'];
+  const result = await pool.query(query, values);
+  console.log('Updated:', result.rows[0]);
+};
+
+// Execute all operations in sequence
+async function main() {
+  try {
+    await readData();
+    await insertData();
+    await updateData();
+    await readData();
+  } finally {
+    await pool.end(); // Close database connection
+  }
+}
+
+main();
+```
+
+</TabItem>
+</Tabs>
+
+### Authentication Setup
+
+To run these examples, you'll need the following:
+
+For GraphQL API:
+1. **Hasura Admin Secret**: Found in the "Connect" tab of Hasura console
+2. **Application Access Token**: Generate this by following our [Application Access Tokens guide](16_application-access-tokens.md)
+
+For PostgreSQL:
+1. **PostgreSQL Connection String**: Found in the "Connect" tab of Hasura console under "Database URL"
+
+
+:::warning
+Always keep your credentials secure and never expose them in client-side code. Use environment variables or a secure configuration management system in production environments.
+:::