Many dApps need more than just decentralized tools to build an end-to-end solution. The SettleMint Hasura SDK provides a seamless way to interact with Hasura GraphQL APIs for managing application data.

Need for a on-chain and off-chain data architecture

In blockchain-based applications, not all data needs to, or should, reside on-chain. While critical state changes, token ownerships, or verifiable proofs are best kept immutable and transparent on a blockchain, a large portion of application data such as user profiles, analytics, logs, metadata, and UI-driven state is better suited to an off-chain data store. Storing everything on-chain is neither cost-effective nor performance-friendly. On-chain data is expensive to store and slow to query for complex front-end or dashboard use cases.

This is where a hybrid architecture becomes essential. In such an approach, data is partitioned based on its importance and usage:

• On-chain layer serves as the source of truth for verifiable, consensus-driven actions like token transfers, proofs, and governance.
• Off-chain layer handles high-volume, user-generated, or fast-changing data that benefits from relational structure, rich queries, and low latency.

This model provides the best of both worlds: immutability and trust from blockchain, and speed, flexibility, and developer-friendliness from traditional databases.

How hasura on SettleMint supports this architecture

SettleMint offers Hasura as a Backend-as-a-Service (BaaS), tightly integrated into its low-code blockchain development stack. Hasura provides a high-performance, real-time GraphQL API layer on top of a PostgreSQL database, and allows developers to instantly query, filter, and subscribe to changes in the data without writing custom backend logic.

Key capabilities of hasura on settlemint

• A fully managed PostgreSQL database is provisioned automatically with each Hasura instance.
• Hasura auto-generates a powerful and expressive GraphQL API for all the tables and relationships defined in the database.
• It allows integration with external databases or REST/GraphQL services, making it possible to unify multiple data sources behind one GraphQL endpoint.
• Role-based access control ensures secure data access aligned with business logic and user permissions.

Benefits of using hasura in a blockchain project

Hasura is especially useful for building interfaces, dashboards, and off-chain tools in blockchain applications. Developers can use it to:

• Store non-critical or frequently updated data like user preferences, audit logs, or API call metadata.
• Power admin panels or reporting dashboards with complex filtering, sorting, and aggregation capabilities.
• Perform fast and reliable queries without the overhead of smart contract reads or event processing.
• Sync or mirror blockchain data into Postgres via indexing services (like The Graph or custom workers), and build additional logic around it.

For example, while the verification of a credential or the execution of a transaction happens on-chain, the user's profile details, usage history, or interactions with the platform can be managed off-chain using Hasura. This results in a responsive and scalable user experience, without compromising on the core security and trust guarantees of blockchain.

Off-chain database use cases in blockchain applications

Add hasura

Some basic features

• Under the data subtab you can create an arbitrary number of schemas. A schema is a collection of tables.
• In a schema you can create tables, choose which columns you want and define relations and indexes.
• You can add, edit and delete data in these columns as well. Learn more here

Any table you make is instantly visible in the API subtab. Note that by using the REST and derive action buttons you can convert queries into REST endpoints if that fits your application better. Using the code exporter button you can get the actual code snippets you can use in your application or the integration studio.

A bit more advanced are actions. Actions are custom queries or mutations that are resolved via HTTP handlers. Actions can be used to carry out complex data validations, data enrichment from external sources or execute just about any custom business logic. Actions can be kickstarted by using the derive action button in the API subtab. Learn more here.

If you need to execute tasks based on changes to your database you can leverage events. An event trigger atomically captures events (insert, update, delete) on a specified table and then reliably calls a HTTP webhook to run some custom business logic. Learn more here.

Cron triggers can be used to reliably trigger HTTP endpoints to run some custom business logic periodically based on a cron schedule.

One-off scheduled events are individual events that can be scheduled to reliably trigger a HTTP webhook to run some custom business logic at a particular timestamp.

Access to your database can be handled all the way to the row level by using the authentication and authorisation options available in Hasura. Learn more here.

This is of course on top of the application access tokens and personal access tokens in the platform you can use to close off access to the entire API.

Usage examples

You can interact with your Hasura database in two ways: through the GraphQL API (recommended) or directly via PostgreSQL connection.

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();

Hasura postgress database access and connection

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

For PostgreSQL:

1. PostgreSQL Connection String: Found in the "connect" tab of Hasura console under "Database URL"

Understanding postgress connection string

postgresql://hasura-f1cd9:[email protected]:30787/hasura-f1cd9

Here's how it's broken down:

• Protocol: postgresql://
  Indicates the connection type , PostgreSQL database over TCP.

• Username: hasura-f1cd9
  The database username used for authentication.

• Password: 0c510604a378d348e7ed
  The corresponding password for the above username.

• Host: p2p.gke-europe.settlemint.com
  The server address (domain or IP) where the PostgreSQL database is hosted.

• Port: 30787
  The network port on which the PostgreSQL service is listening.

• Database Name: hasura-f1cd9
  The specific PostgreSQL database to connect to on that server.

Hasura backup

Via CLI pgdump command

PGPASSWORD=0c510604a378d348e7ed pg_dump \
  -h p2p.gke-europe.settlemint.com \
  -p 30787 \
  -U hasura-f1cd9 \
  -d hasura-f1cd9 \
  -F p \
  -f ~/Desktop/hasura_backup.sql

Taking backup via hasura CLI

1. Hasura Database
2. Hasura Metadata

Steps for taking a backup of hasura database

1. Install Hasura CLI (https://hasura.io/docs/latest/hasura-cli/install-hasura-cli/)
2. Run hasura init command to initiate a new Hasura project in the working directory.
3. Edit config.yaml file to configure remote Hasura instance. We need to generate an API Key in BPaaS and pass it with the endpoint.

Syntax of config.yaml:

version: 3
endpoint: <hasura-db-endpoint-here/API-key>
admin_secret: <admin-secret-here>
metadata_directory: metadata
actions:
 kind: synchronous
 handler_webhook_baseurl: http://localhost:3000

Example

endpoint: https://hasuradb-15ce.gke-japan.settlemint.com/sm_aat_86530f5bf93d82a9
admin_secret: dc5eb1b93f43fd28c53e
metadata_directory: metadata
actions:
 kind: synchronous
 handler_webhook_baseurl: http://localhost:3000

4. Run hasura console command. (this command will sync everything to your local hasura instance.)
5. Run this curl command to generate DB export:

Curl Format

curl -d '{"opts": [ "-O", "-x", "--schema=public", "--inserts"], "clean_output": true, "source": "default"}' -H "x-hasura-admin-secret: <SecretKey>" <Endpoint URL/APIKey>/v1alpha1/pg_dump > db.sql

Example Curl

curl -d '{"opts": [ "-O", "-x", "--schema=public", "--inserts"], "clean_output": true, "source": "default"}' -H "x-hasura-admin-secret:78b0e4618125322de0eb" https://fuchsiacapybara-7f70.gke-europe.settlemint.com/bpaas-1d79Acd6A2f112EA450F1C07a372a7D582E6121F/v1alpha1/pg_dump > db.sql

Importing data into a new instance

Please copy the content of the exported db.sql file, paste it and execute as a SQL statement.

Steps for taking a backup of hasura metadata

Hasura Metadata Export is a collection of yaml files which captures all the metadata required by the GraphQL Engine. This includes info about tables that are tracked, permission rules, relationships, and event triggers that are defined on those tables.

If you have already initialized your project via the Hasura CLI you should see the metadata directory structure in your project directory.

To export your entire metadata using the Hasura CLI execute the following command in your terminal:

# In hasura CLI
hasura metadata export

This will export the metadata as YAML files in the /metadata directory

Steps for importing or applying hasura metadata

You can apply metadata from one Hasura Server instance to another. You can also apply an older or modified version of an instance's metadata onto itself to replace the existing metadata. Applying or importing completely replaces the metadata on that instance, i.e. you lose any metadata that existed before applying.

# In hasura CLI
hasura metadata apply

Reload hasura metadata

In some cases, the metadata can be out of sync with the database schema. For example, when a new column has been added to a table via an external tool.

# In hasura CLI
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/