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,72 @@
+# This example shows how @dbquery is configured for custom SQL queries with Customer data.
+
+"""
+Represents a customer in the system, stored in the 'customer' table of a PostgreSQL database.
+Each customer has an ID, name, and email. The 'Customer' type maps directly to the
+corresponding table fields.
+"""
+type Customer {
+    id: ID!
+    name: String
+    email: String
+}
+
+"""
+Defines the root-level queries for fetching customer data.
+These queries use the `@dbquery` directive to execute custom SQL queries.
+The SQL queries include parameter markers, which correspond to the GraphQL field arguments.
+
+The 'customer' table in PostgreSQL has the following structure:
+
+  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
+  );
+These queries demonstrate basic SQL interactions with this table.
+"""
+type Query {
+    """
+    Fetches a list of all customers from the database.
+
+    The custom SQL query retrieves the `id`, `name`, and `email` fields from the 'customer' table.
+
+    **@dbquery Directive Usage**:
+    - `query`: This is the SQL query that will be executed. Here, it fetches all records from the 'customer' table.
+    - `type`: Specifies the type of database being queried. In this case, it’s a PostgreSQL database.
+    - `configuration`: References the database configuration (connection details) in StepZen.
+
+    This query does not take any arguments, and hence there are no parameter markers in the SQL query.
+    The SQL query is static, always returning all customers from the database.
+    """
+    customers: [Customer]
+        @dbquery(
+            query: "SELECT id, name, email FROM customer"
+            type: "postgresql"
+            configuration: "postgresql_config"
+        )
+
+    """
+    Fetches a single customer by their ID from the database.
+
+    **Field Argument to Parameter Marker Mapping**:
+    - The `id` argument provided in the GraphQL query maps to the `$1` marker in the SQL query.
+    - SQL queries typically use numbered markers (e.g., `$1`, `$2`, etc.) for parameterized inputs. The number refers to the position of the argument in the query.
+    - When a query is executed, the value passed to the `id` argument in GraphQL (via variables) will replace the `$1` marker in the SQL query.
+
+    **@dbquery Directive Usage**:
+    - `query`: This is the SQL query that will be executed. Here, the customer data is fetched based on the provided `id` value.
+      - The `$1` marker is a placeholder for the value of the `id` argument, which is passed as a variable when executing the query.
+    - `type`: Specifies the type of database being queried (PostgreSQL).
+    - `configuration`: References the database configuration (connection details) in StepZen.
+
+    This query requires an `id` argument as input, which is passed as a variable from the GraphQL query. The variable's value is used to fetch the corresponding customer from the database.
+    """
+    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,4 @@
+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 using a variable
+query Customer($id: Int!) {
+  customer(id: $id) {
+    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);
+});