-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
add stored procedures documentation (#145)
<!-- The PR description should answer 2 (maybe 3) important questions: --> ### What <!-- What is this PR trying to accomplish (and why, if it's not obvious)? --> ### How <!-- How is it trying to accomplish it (what are the implementation steps)? -->
- Loading branch information
1 parent
0a341b5
commit 05d7071
Showing
4 changed files
with
147 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <K: Identifier of the column, V: [ArgumentObject](#argument-object)> | Yes | Schema of the arguments that will be passed to the stored procedure `sql` query. | | ||
| | `returns` | JSON Object <K: Identifier of the column, V: [ColumnObject](#column-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. | |