feat(snippet): add example for @dbquery with SQL queries

dbquery/custom-query/README.md

@@ -0,0 +1,65 @@
+
+# SQL Queries with `@dbquery`
+
+This snippet demonstrates how to configure the `@dbquery` directive for custom SQL queries.
+
+## Getting Started
+
+[Install](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=setting-up-your-environment) the StepZen command line interface.
+
+To run these examples,
+
+- `git clone` this repo
+- Change to the right working directory.
+- run `stepzen deploy`
+
+This example uses a demo database filled with mock data, you can inspect the `config.yaml` file to find the credentials for this database. Also you can configure the connection in the `config.yaml` file by providing your database credentials.
+
+Here’s a more generalized and specific description of the `@dbquery` directive functionality without referring to any particular data:
+
+---
+
+## The `@dbquery` Directive with SQL Query
+
+The `@dbquery` directive in StepZen is used to connect your GraphQL API to databases and allows you to execute custom SQL queries within your schema. It supports various database types, such as MySQL, PostgreSQL, MSSQL, and Snowflake.
+
+In this snippet, the `query` argument is used to define custom SQL queries for more control over the data being fetched. The functionality of the `query` argument allows for:
+
+- Running complex SQL queries directly from GraphQL fields.
+- Retrieving data from specific columns or joining multiple tables based on your query requirements.
+- Filtering and querying data using SQL syntax when database field names or structures differ from the GraphQL schema.
+
+The `query` argument provides the flexibility to write any SQL statement, while the **configuration** argument references the connection settings defined in the `config.yaml` file.
+
+For example, a query may look like this:
+
+```graphql
+@dbquery(
+  query: "SELECT column1, column2 FROM your_table WHERE condition = $1",
+  type: "postgresql",
+  configuration: "your_config"
+)
+```
+
+This allows you to fetch exactly the data you need, based on the custom SQL query provided. You can adjust the queries to match your database schema and use case.
+
+## Try it Out!
+
+Deploy the schema from `dbquery/pagination` relative to the repository's root directory:
+
+```
+stepzen deploy
+```
+
+Run the [sample operations](operations.graphql):
+
+- **Fetch all customers**:
+  ```
+  stepzen request -f operations.graphql --operation-name=Customers
+  ```
+
+- **Fetch a customer by ID**:
+  ```
+  stepzen request -f operations.graphql --operation-name=Customer --var id=1
+  ```
+

dbquery/custom-query/api.graphql

@@ -0,0 +1,42 @@
+# This example shows how @dbquery is configured for custom SQL queries with Customer data.
+
+"""
+Sample Customer type.
+"""
+type Customer {
+  id: ID!
+  name: String
+  email: String
+}
+
+"""
+`Customer` queries a mock `Customer` object from a demo PostgreSQL database.
+The data is fetched using custom SQL queries.
+
+Table structure for 'customer':
+
+  CREATE TABLE customer (
+    id SERIAL PRIMARY KEY,          -- Unique identifier with sequence
+    name CHARACTER(50) NOT NULL,    -- Customer's name, max 50 characters
+    email CHARACTER(50) NOT NULL,   -- Customer's email, max 50 characters, must be unique
+    CONSTRAINT customer_email_key UNIQUE (email)  -- Unique constraint on email
+  );
+
+"""
+type Query {
+  # Fetches all customers.
+  customers: [Customer]
+    @dbquery(
+      query: "SELECT id, name, email FROM customer",
+      type: "postgresql",
+      configuration: "postgresql_config"
+    )
+
+  # Fetches a customer by their ID.
+  customer(id: Int!): Customer
+    @dbquery(
+      query: "SELECT id, name, email FROM customer WHERE id = $1",
+      type: "postgresql",
+      configuration: "postgresql_config"
+    )
+}

dbquery/custom-query/config.yaml

@@ -0,0 +1,5 @@
+configurationset:
+  - configuration:
+      name: postgresql_config
+      uri: postgresql://postgresql.introspection.stepzen.net/introspection?user=testUserIntrospection&password=HurricaneStartingSample1934
+

dbquery/custom-query/index.graphql

@@ -0,0 +1,3 @@
+schema @sdl(files: ["api.graphql"]) {
+  query: Query
+}

dbquery/custom-query/operations.graphql

@@ -0,0 +1,17 @@
+# Retrieve a specific customer by ID
+query Customer {
+  customer(id: 1) {
+    id
+    name
+    email
+  }
+}
+
+# Retrieve all customers in the system
+query Customers {
+  customers {
+    id
+    name
+    email
+  }
+}

dbquery/custom-query/stepzen.config.json

@@ -0,0 +1,4 @@
+{
+    "endpoint": "api/miscellaneous"
+  }
+

dbquery/custom-query/tests/Test.js

@@ -0,0 +1,57 @@
+const fs = require("fs");
+const path = require("node:path");
+const {
+  deployAndRun,
+  stepzen,
+  getTestDescription,
+} = require("../../../tests/gqltest.js");
+
+testDescription = getTestDescription("snippets", __dirname);
+
+// Read the GraphQL operations from the operations file
+const requestsFile = path.join(path.dirname(__dirname), "operations.graphql");
+const requests = fs.readFileSync(requestsFile, "utf8").toString();
+
+describe(testDescription, function () {
+
+  const tests = [
+    {
+      label: "fetch all customers",
+      query: requests,
+      operationName: "Customers",
+      variables: {},
+      expected: {
+        customers: [
+          { id: "1", name: "Lucas Bill                                        ", email: "[email protected]                            " },
+          { id: "2", name: "Mandy Jones                                       ", email: "[email protected]                           " },
+          { id: "3", name: "Salim Ali                                         ", email: "[email protected]                             " },
+          { id: "4", name: "Jane Xiu                                          ", email: "[email protected]                              " },
+          { id: "5", name: "John Doe                                          ", email: "[email protected]                              " },
+          { id: "6", name: "Jane Smith                                        ", email: "[email protected]                            " },
+          { id: "7", name: "Sandeep Bhushan                                   ", email: "[email protected]                       " },
+          { id: "8", name: "George Han                                        ", email: "[email protected]                            " },
+          { id: "9", name: "Asha Kumari                                       ", email: "[email protected]                           " },
+          { id: "10", name: "Salma Khan                                        ", email: "[email protected]                            " }
+        ]
+      },
+    },
+    {
+      label: "fetch customer by ID",
+      query: requests,
+      operationName: "Customer",
+      variables: { 
+        id: 1  
+      },
+      expected: {
+        customer: {
+          id: "1",
+          name: "Lucas Bill                                        ",
+          email: "[email protected]                            "
+        }
+      },
+    },
+  ];
+
+  // Run the tests against the deployed schema
+  return deployAndRun(__dirname, tests, stepzen.admin);
+});