diff --git a/README.md b/README.md index 83cb92a4..791e90b7 100644 --- a/README.md +++ b/README.md @@ -33,8 +33,9 @@ Below, you'll find a matrix of all supported features for the SQL Server connect | Table Relationships | ✅ | | | Views | ✅ | | | Remote Relationships | ✅ | | +| Stored Procedures | ✅ | | | Custom Fields | ❌ | | -| Mutations | ✅ | Only native mutations are suppported | +| Mutations | ❌ | Only native mutations are suppported | | Distinct | ✅ | | | Enums | ❌ | | | Naming Conventions | ❌ | | @@ -61,7 +62,7 @@ ddn auth login ### Step 2: Configure the connector -Once you have an initialized supergraph and subgraph, run the initialization command in interactive mode while +Once you have an initialized supergraph and subgraph, run the initialization command in interactive mode while providing a name for the connector in the prompt: ```bash @@ -72,7 +73,7 @@ ddn connector init -i #### Step 2.2: Choose a port for the connector -The CLI will ask for a specific port to run the connector on. Choose a port that is not already in use or use the +The CLI will ask for a specific port to run the connector on. Choose a port that is not already in use or use the default suggested port. #### Step 2.3: Provide the env vars for the connector @@ -80,7 +81,7 @@ default suggested port. | Name | Description | Required | Default | |----------------|--------------------------------------------------|----------|---------| | CONNECTION_URI | The connection string of the SQL Server database | Yes | N/A | - + ## Step 3: Introspect the connector ```bash diff --git a/docs/readme.md b/docs/readme.md index 0a8fb26a..9a051420 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -4,5 +4,6 @@ - [Usage](./usage/index.md) - [Native mutations](./usage/native_mutations.md) + - [Stored procedures](./usage/stored_procedures.md) - [Code of Conduct](./code-of-conduct.md) - [Debugging](./debugging.md) diff --git a/docs/usage/index.md b/docs/usage/index.md index ba9af7d7..49d27e8e 100644 --- a/docs/usage/index.md +++ b/docs/usage/index.md @@ -3,3 +3,4 @@ Information on how to use the ndc-sqlserver connector. - [Native Mutations](./native_mutations.md) +- [Stored Procedures](./stored_procedures.md) diff --git a/docs/usage/stored_procedures.md b/docs/usage/stored_procedures.md new file mode 100644 index 00000000..dc1e9ffa --- /dev/null +++ b/docs/usage/stored_procedures.md @@ -0,0 +1,140 @@ +# Stored Procedures with ndc-sqlserver + +## Introduction + +Stored procedures are a powerful feature of SQL Server that allow you to encapsulate logic in the +database. This can be useful for a number of reasons, such as: + +- **Performance**: Stored procedures can be precompiled and cached, which can improve performance. +- **Security**: Stored procedures can be used to control access to data. +- **Consistency**: Stored procedures can be used to enforce business rules. +- **Code Reuse**: Stored procedures can be reused across multiple applications. + +In this guide, we'll look at how to use stored procedures with the ndc-sqlserver connector. + +## Tracking Stored Procedures + +The ndc-sqlserver connector can track stored procedures in a SQL Server database. The stored +procedures present in the database are automatically added while introspecting the database +via the `update` operation. The stored procedures will appear in the `$.metadata.storedProcedures` +key of the configuration that is generated by the `update` operation. + + +Example of a stored procedure configuration that's generated by the introspection: + +```json +{ + "storedProcedures": { + "GetArtistsByName": { + "name": "GetArtistsByName", + "schema": "dbo", + "arguments": { + "Name": { + "name": "Name", + "type": "varchar", + "nullable": "nullable", + "isOutput": false, + "description": null + } + }, + "returns": null, + "description": null + } + } +} +``` + +### Return type of Stored Procedures + +The stored procedure generated by the introspection contains `returns` as `null` because a stored +procedure can return multiple result sets or output parameters, so it is not possible for the connector +to automatically determine the return type of the stored procedure. You should manually update the +stored procedure's configuration to include the return type of the stored procedure, as shown below. + +The return type of a stored procedure should include the fields that are going to be returned by the +stored procedure. The fields should be defined in the `returns` key of the stored procedure +configuration. + +For example, if the stored procedure returns `CustomerId`, `Phone` and `TotalPurchases`, +we can add a return type for it, as following: + +```json +{ + "storedProcedures": { + "GetArtistsByName": { + "name": "GetArtistsByName", + "schema": "dbo", + "arguments": { + "Name": { + "name": "Name", + "type": "varchar", + "nullable": "nullable", + "isOutput": false, + "description": null + } + }, + "returns": { + "CustomerId": { + "name": "CustomerId", + "type": "int", + "nullable": "nonNullable", + "description": null + }, + "Phone": { + "name": "Phone", + "type": "varchar", + "nullable": "nonNullable", + "description": null + }, + "TotalPurchases": { + "name": "TotalPurchases", + "type": "int", + "nullable": "nonNullable", + "description": null + } + }, + "description": null + } + } +} +``` + +## Schema of Stored Procedures + +## Schema + +A stored procedure can be defined using the following fields: + + +### Native Mutation Object + +| Field name | Type | Required | Notes | +|---------------|----------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | Name of the stored procedure | Yes | | +| `schema` | Name of the schema of the stored procedure | Yes | | +| `arguments` | JSON Object | Yes | Schema of the arguments that will be passed to the stored procedure `sql` query. | +| `returns` | JSON Object | No | Schema of the columns that will be returned by the stored procedure. Note that if this key is not present, the stored procedure won't be added to the schema of the connector | +| `description` | String | No | Description of the stored procedure. | + + + +### Column Object + +| Field name | Type | Required | Notes | +|---------------|--------|----------|----------------------------------------------------------------------| +| `name` | String | Yes | Name of the column that will be returned in the SQL query's response | +| `type` | String | Yes | Type of the column. | +| `description` | String | No | Description of the column. | +| `nullable` | String | Yes | Nullability of the column. | +| `description` | String | No | Description of the column. | + + +### Argument Object + +| Field name | Type | Required | Notes | +|---------------|--------|----------|--------------------------------------------------------------------| +| `name` | String | Yes | Name of the argument. | +| `type` | String | Yes | Type of the argument. | +| `nullable` | String | Yes | Nullability of the argument. | +| `isOutput` | String | Yes | Boolean value to indicate if the argument can contain output value | +| `description` | String | No | Description of the argument. |