@sap/cds 1.15.1 → 1.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +19 -0
- package/{developer-license-3.1.txt → LICENSE} +37 -35
- package/_hdbext/README.md +373 -0
- package/_hdbext/index.js +4 -0
- package/_hdbext/lib/client-factory.js +62 -0
- package/_hdbext/lib/client-session.js +96 -0
- package/_hdbext/lib/conn-options.js +84 -0
- package/_hdbext/lib/constants.js +79 -0
- package/_hdbext/lib/internal-constants.js +7 -0
- package/_hdbext/lib/middleware.js +46 -0
- package/_hdbext/lib/pool.js +236 -0
- package/_hdbext/lib/safe-sql.js +17 -0
- package/_hdbext/lib/sql-injection-utils.js +149 -0
- package/cds-queries-geo.js +347 -371
- package/cds-queries.js +2692 -2229
- package/cds.js +111 -104
- package/exprs.js +118 -107
- package/manager.js +696 -614
- package/metadata.js +604 -542
- package/npm-shrinkwrap.json +175 -0
- package/package.json +40 -1
- package/transaction.js +45 -51
- package/util/Queue.js +32 -30
- package/utils.js +182 -159
- package/xsjs-cds.js +231 -221
- package/.project +0 -11
- package/SIGNATURE.SMF +0 -1747
- package/TUTORIAL.md +0 -1236
- package/dependencies +0 -56
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# ChangeLog for node-cds
|
|
2
|
+
|
|
3
|
+
## Version 1.17.0 - 2022-18-08
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- Node 16 support.
|
|
8
|
+
|
|
9
|
+
## Version 1.16.8 - 2022-06-08
|
|
10
|
+
|
|
11
|
+
### Fixed
|
|
12
|
+
|
|
13
|
+
- Use `async@2.6.4^` to get rid of security vulnerability.
|
|
14
|
+
|
|
15
|
+
## Version 1.16.3 - 2021-07-07
|
|
16
|
+
|
|
17
|
+
### Fixed
|
|
18
|
+
|
|
19
|
+
- Use `lodash@4^` to get rid of security vulnerability.
|
|
@@ -1,35 +1,37 @@
|
|
|
1
|
-
SAP DEVELOPER LICENSE AGREEMENT
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
1
|
+
SAP DEVELOPER LICENSE AGREEMENT
|
|
2
|
+
|
|
3
|
+
Version 3.1
|
|
4
|
+
|
|
5
|
+
Please scroll down and read the following Developer License Agreement carefully ("Developer Agreement"). By clicking "I Accept" or by attempting to download, or install, or use the SAP software and other materials that accompany this Developer Agreement ("SAP Materials"), You agree that this Developer Agreement forms a legally binding agreement between You ("You" or "Your") and SAP SE, for and on behalf of itself and its subsidiaries and affiliates (as defined in Section 15 of the German Stock Corporation Act) and You agree to be bound by all of the terms and conditions stated in this Developer Agreement. If You are trying to access or download the SAP Materials on behalf of Your employer or as a consultant or agent of a third party (either "Your Company"), You represent and warrant that You have the authority to act on behalf of and bind Your Company to the terms of this Developer Agreement and everywhere in this Developer Agreement that refers to 'You' or 'Your' shall also include Your Company. If You do not agree to these terms, do not click "I Accept", and do not attempt to access or use the SAP Materials.
|
|
6
|
+
|
|
7
|
+
1. LICENSE: SAP grants You a non-exclusive, non-transferable, non-sublicensable, revocable, limited use license to copy, reproduce and distribute the application programming interfaces ("API"), documentation, plug-ins, templates, scripts and sample code ("Tools") on a desktop, laptop, tablet, smart phone, or other appropriate computer device that You own or control (any, a "Computer") to create new applications ("Customer Applications"). You agree that the Customer Applications will not: (a) unreasonably impair, degrade or reduce the performance or security of any SAP software applications, services or related technology ("Software"); (b) enable the bypassing or circumventing of SAP's license restrictions and/or provide users with access to the Software to which such users are not licensed; (c) render or provide, without prior written consent from SAP, any information concerning SAP software license terms, Software, or any other information related to SAP products; or (d) permit mass data extraction from an SAP product to a non-SAP product, including use, modification, saving or other processing of such data in the non-SAP product. In exchange for the right to develop Customer Applications under this Agreement, You covenant not to assert any Intellectual Property Rights in Customer Applications created by You against any SAP product, service, or future SAP development.
|
|
8
|
+
|
|
9
|
+
2. INTELLECTUAL PROPERTY: (a) SAP or its licensors retain all ownership and intellectual property rights in the APIs, Tools and Software. You may not: a) remove or modify any marks or proprietary notices of SAP, b) provide or make the APIs, Tools or Software available to any third party, c) assign this Developer Agreement or give or transfer the APIs, Tools or Software or an interest in them to another individual or entity, d) decompile, disassemble or reverse engineer (except to the extent permitted by applicable law) the APIs Tools or Software, (e) create derivative works of or based on the APIs, Tools or Software, (f) use any SAP name, trademark or logo, or (g) use the APIs or Tools to modify existing Software or other SAP product functionality or to access the Software or other SAP products' source code or metadata.
|
|
10
|
+
(b) Subject to SAP's underlying rights in any part of the APIs, Tools or Software, You retain all ownership and intellectual property rights in Your Customer Applications.
|
|
11
|
+
|
|
12
|
+
3. FREE AND OPEN SOURCE COMPONENTS: The SAP Materials may include certain third party free or open source components ("FOSS Components"). You may have additional rights in such FOSS Components that are provided by the third party licensors of those components.
|
|
13
|
+
|
|
14
|
+
4. THIRD PARTY DEPENDENCIES: The SAP Materials may require certain third party software dependencies ("Dependencies") for the use or operation of such SAP Materials. These dependencies may be identified by SAP in Maven POM files, product documentation or by other means. SAP does not grant You any rights in or to such Dependencies under this Developer Agreement. You are solely responsible for the acquisition, installation and use of Dependencies. SAP DOES NOT MAKE ANY REPRESENTATIONS OR WARRANTIES IN RESPECT OF DEPENDENCIES, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND OF FITNESS FOR A PARTICULAR PURPOSE. IN PARTICULAR, SAP DOES NOT WARRANT THAT DEPENDENCIES WILL BE AVAILABLE, ERROR FREE, INTEROPERABLE WITH THE SAP MATERIALS, SUITABLE FOR ANY PARTICULAR PURPOSE OR NON-INFRINGING. YOU ASSUME ALL RISKS ASSOCIATED WITH THE USE OF DEPENDENCIES, INCLUDING WITHOUT LIMITATION RISKS RELATING TO QUALITY, AVAILABILITY, PERFORMANCE, DATA LOSS, UTILITY IN A PRODUCTION ENVIRONMENT, AND NON-INFRINGEMENT. IN NO EVENT WILL SAP BE LIABLE DIRECTLY OR INDIRECTLY IN RESPECT OF ANY USE OF DEPENDENCIES BY YOU.
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
5. WARRANTY:
|
|
18
|
+
a) If You are located outside the US or Canada: AS THE API AND TOOLS ARE PROVIDED TO YOU FREE OF CHARGE, SAP DOES NOT GUARANTEE OR WARRANT ANY FEATURES OR QUALITIES OF THE TOOLS OR API OR GIVE ANY UNDERTAKING WITH REGARD TO ANY OTHER QUALITY. NO SUCH WARRANTY OR UNDERTAKING SHALL BE IMPLIED BY YOU FROM ANY DESCRIPTION IN THE API OR TOOLS OR ANY AVAILABLE DOCUMENTATION OR ANY OTHER COMMUNICATION OR ADVERTISEMENT. IN PARTICULAR, SAP DOES NOT WARRANT THAT THE SOFTWARE WILL BE AVAILABLE UNINTERRUPTED, ERROR FREE, OR PERMANENTLY AVAILABLE. FOR THE TOOLS AND API ALL WARRANTY CLAIMS ARE SUBJECT TO THE LIMITATION OF LIABILITY STIPULATED IN SECTION 4 BELOW.
|
|
19
|
+
b) If You are located in the US or Canada: THE API AND TOOLS ARE LICENSED TO YOU "AS IS", WITHOUT ANY WARRANTY, ESCROW, TRAINING, MAINTENANCE, OR SERVICE OBLIGATIONS WHATSOEVER ON THE PART OF SAP. SAP MAKES NO EXPRESS OR IMPLIED WARRANTIES OR CONDITIONS OF SALE OF ANY TYPE WHATSOEVER, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND OF FITNESS FOR A PARTICULAR PURPOSE. IN PARTICULAR, SAP DOES NOT WARRANT THAT THE SOFTWARE WILL BE AVAILABLE UNINTERRUPTED, ERROR FREE, OR PERMANENTLY AVAILABLE. YOU ASSUME ALL RISKS ASSOCIATED WITH THE USE OF THE API AND TOOLS, INCLUDING WITHOUT LIMITATION RISKS RELATING TO QUALITY, AVAILABILITY, PERFORMANCE, DATA LOSS, AND UTILITY IN A PRODUCTION ENVIRONMENT.
|
|
20
|
+
|
|
21
|
+
6. LIMITATION OF LIABILITY:
|
|
22
|
+
a) If You are located outside the US or Canada: IRRESPECTIVE OF THE LEGAL REASONS, SAP SHALL ONLY BE LIABLE FOR DAMAGES UNDER THIS AGREEMENT IF SUCH DAMAGE (I) CAN BE CLAIMED UNDER THE GERMAN PRODUCT LIABILITY ACT OR (II) IS CAUSED BY INTENTIONAL MISCONDUCT OF SAP OR (III) CONSISTS OF PERSONAL INJURY. IN ALL OTHER CASES, NEITHER SAP NOR ITS EMPLOYEES, AGENTS AND SUBCONTRACTORS SHALL BE LIABLE FOR ANY KIND OF DAMAGE OR CLAIMS HEREUNDER.
|
|
23
|
+
b) If You are located in the US or Canada: IN NO EVENT SHALL SAP BE LIABLE TO YOU, YOUR COMPANY OR TO ANY THIRD PARTY FOR ANY DAMAGES IN AN AMOUNT IN EXCESS OF $100 ARISING IN CONNECTION WITH YOUR USE OF OR INABILITY TO USE THE TOOLS OR API OR IN CONNECTION WITH SAP'S PROVISION OF OR FAILURE TO PROVIDE SERVICES PERTAINING TO THE TOOLS OR API, OR AS A RESULT OF ANY DEFECT IN THE API OR TOOLS. THIS DISCLAIMER OF LIABILITY SHALL APPLY REGARDLESS OF THE FORM OF ACTION THAT MAY BE BROUGHT AGAINST SAP, WHETHER IN CONTRACT OR TORT, INCLUDING WITHOUT LIMITATION ANY ACTION FOR NEGLIGENCE. YOUR SOLE REMEDY IN THE EVENT OF BREACH OF THIS DEVELOPER AGREEMENT BY SAP OR FOR ANY OTHER CLAIM RELATED TO THE API OR TOOLS SHALL BE TERMINATION OF THIS AGREEMENT. NOTWITHSTANDING ANYTHING TO THE CONTRARY HEREIN, UNDER NO CIRCUMSTANCES SHALL SAP AND ITS LICENSORS BE LIABLE TO YOU OR ANY OTHER PERSON OR ENTITY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR INDIRECT DAMAGES, LOSS OF GOOD WILL OR BUSINESS PROFITS, WORK STOPPAGE, DATA LOSS, COMPUTER FAILURE OR MALFUNCTION, ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSS, OR EXEMPLARY OR PUNITIVE DAMAGES.
|
|
24
|
+
|
|
25
|
+
7. INDEMNITY: You will fully indemnify, hold harmless and defend SAP against law suits based on any claim: (a) that any Customer Application created by You infringes or misappropriates any patent, copyright, trademark, trade secrets, or other proprietary rights of a third party, or (b) related to Your alleged violation of the terms of this Developer Agreement.
|
|
26
|
+
|
|
27
|
+
8. EXPORT: The Tools and API are subject to German, EU and US export control regulations. You confirm that: a) You will not use the Tools or API for, and will not allow the Tools or API to be used for, any purposes prohibited by German, EU and US law, including, without limitation, for the development, design, manufacture or production of nuclear, chemical or biological weapons of mass destruction; b) You are not located in Cuba, Iran, Sudan, Iraq, North Korea, Syria, nor any other country to which the United States has prohibited export or that has been designated by the U.S. Government as a "terrorist supporting" country (any, an "US Embargoed Country"); c) You are not a citizen, national or resident of, and are not under the control of, a US Embargoed Country; d) You will not download or otherwise export or re-export the API or Tools, directly or indirectly, to a US Embargoed Country nor to citizens, nationals or residents of a US Embargoed Country; e) You are not listed on the United States Department of Treasury lists of Specially Designated Nationals, Specially Designated Terrorists, and Specially Designated Narcotic Traffickers, nor listed on the United States Department of Commerce Table of Denial Orders or any other U.S. government list of prohibited or restricted parties and f) You will not download or otherwise export or re-export the API or Tools , directly or indirectly, to persons on the above-mentioned lists.
|
|
28
|
+
|
|
29
|
+
9. SUPPORT: Other than what is made available on the SAP Community Website (SCN) by SAP at its sole discretion and by SCN members, SAP does not offer support for the API or Tools which are the subject of this Developer Agreement.
|
|
30
|
+
|
|
31
|
+
10. TERM AND TERMINATION: You may terminate this Developer Agreement by destroying all copies of the API and Tools on Your Computer(s). SAP may terminate Your license to use the API and Tools immediately if You fail to comply with any of the terms of this Developer Agreement, or, for SAP's convenience by providing you with ten (10) day's written notice of termination (including email). In case of termination or expiration of this Developer Agreement, You must destroy all copies of the API and Tools immediately. In the event Your Company or any of the intellectual property you create using the API, Tools or Software are acquired (by merger, purchase of stock, assets or intellectual property or exclusive license), or You become employed, by a direct competitor of SAP, then this Development Agreement and all licenses granted in this Developer Agreement shall immediately terminate upon the date of such acquisition.
|
|
32
|
+
|
|
33
|
+
11. LAW/VENUE:
|
|
34
|
+
a) If You are located outside the US or Canada: This Developer Agreement is governed by and construed in accordance with the laws of the Germany. You and SAP agree to submit to the exclusive jurisdiction of, and venue in, the courts of Karlsruhe in Germany in any dispute arising out of or relating to this Developer Agreement.
|
|
35
|
+
b) If You are located in the US or Canada: This Developer Agreement shall be governed by and construed under the Commonwealth of Pennsylvania law without reference to its conflicts of law principles. In the event of any conflicts between foreign law, rules, and regulations, and United States of America law, rules, and regulations, United States of America law, rules, and regulations shall prevail and govern. The United Nations Convention on Contracts for the International Sale of Goods shall not apply to this Developer Agreement. The Uniform Computer Information Transactions Act as enacted shall not apply.
|
|
36
|
+
|
|
37
|
+
12. MISCELLANEOUS: This Developer Agreement is the complete agreement for the API and Tools licensed (including reference to information/documentation contained in a URL). This Developer Agreement supersedes all prior or contemporaneous agreements or representations with regards to the subject matter of this Developer Agreement. If any term of this Developer Agreement is found to be invalid or unenforceable, the surviving provisions shall remain effective. SAP's failure to enforce any right or provisions stipulated in this Developer Agreement will not constitute a waiver of such provision, or any other provision of this Developer Agreement.
|
|
@@ -0,0 +1,373 @@
|
|
|
1
|
+
# DISCLAIMER: This module is a modified version of @sap/hdbext@4.7.5
|
|
2
|
+
|
|
3
|
+
Due to a security vulnerability in lodash@4.7.11 which is a dependency of @sap/hdbext@4.7.5 we had to upgrade to @sap/hdbext@^7.0.0
|
|
4
|
+
as the issue with lodash is only patched in major version 7 upwards. The @sap/hdbext@^5.0.0 is incompatible to the @sap/node-cds package.
|
|
5
|
+
This is because @sap/node-cds was built on top of the @sap/hdb client, while in @sap/hdbext^5.0.0 the client got replaced with @sap/hana-client.
|
|
6
|
+
Instead of changing the code base to use the @sap/hana-client we re-use the relevant parts of the @sap/hdbext package, bump the lodash dependency
|
|
7
|
+
and bundle the module with @sap/node-cds.
|
|
8
|
+
|
|
9
|
+
@sap/hdbext
|
|
10
|
+
============
|
|
11
|
+
|
|
12
|
+
This module provides convenient functions on top of the [hdb][4] module.
|
|
13
|
+
|
|
14
|
+
The [change log](CHANGELOG.md) describes notable changes in this package.
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
```js
|
|
19
|
+
var hdbext = require('@sap/hdbext');
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## API
|
|
23
|
+
|
|
24
|
+
### createConnection(hanaConfig, callback)
|
|
25
|
+
|
|
26
|
+
Creates a connection to a HANA database:
|
|
27
|
+
|
|
28
|
+
```js
|
|
29
|
+
var hanaConfig = {
|
|
30
|
+
host : 'hostname',
|
|
31
|
+
port : 30015,
|
|
32
|
+
user : 'user',
|
|
33
|
+
password : 'secret'
|
|
34
|
+
};
|
|
35
|
+
hdbext.createConnection(hanaConfig, function(error, client) {
|
|
36
|
+
if (error) {
|
|
37
|
+
return console.error(error);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
client.exec(...);
|
|
41
|
+
});
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The `hanaConfig` argument contains [database connection options](#database-connection-options) and [additional options](#additional-options).
|
|
45
|
+
The callback provides a connected `client` object (see [hdb][4]).
|
|
46
|
+
|
|
47
|
+
If the application will be deployed in Cloud Foundry or XSA, you can use _@sap/xsenv_ package to
|
|
48
|
+
lookup the bound HANA service, like this:
|
|
49
|
+
```js
|
|
50
|
+
var xsenv = require('@sap/xsenv');
|
|
51
|
+
|
|
52
|
+
var hanaConfig = xsenv.cfServiceCredentials({ tag: 'hdb' });
|
|
53
|
+
hdbext.createConnection(hanaConfig, function(error, client) {
|
|
54
|
+
//...
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
#### Database connection options
|
|
59
|
+
|
|
60
|
+
The HANA options provided to *@sap/hdbext* should be in the same format as expected by the [hdb][5] package.
|
|
61
|
+
|
|
62
|
+
For convenience these properties set by the HANA service broker in the SAP HANA XS Advanced platform are also accepted:
|
|
63
|
+
* `db_hosts` - can be used instead of the `hosts` property of the [hdb driver][5].
|
|
64
|
+
* `certificate` - can be used instead of `ca` property of the [hdb driver][6].
|
|
65
|
+
__Note:__ `certificate` is a string containing one certificate, while `ca` is an array of certificates.
|
|
66
|
+
|
|
67
|
+
#### Additional options
|
|
68
|
+
|
|
69
|
+
A connection created with *@sap/hdbext* can be further configured with the following options:
|
|
70
|
+
|
|
71
|
+
Option | Type | Description
|
|
72
|
+
-------- | ---- | -----------
|
|
73
|
+
`schema` | string | Used to set current schema.
|
|
74
|
+
`autoCommit` | boolean | Sets the autoCommit flag. If no option is specified it defaults to `true`
|
|
75
|
+
`isolationLevel` | enum | One of `hdbext.constants.isolation` values. Used to set transaction isolation level.
|
|
76
|
+
`locale` | string | Used to set connection locale.
|
|
77
|
+
`session` | object | Object with key/value pairs that will be set as session variables.
|
|
78
|
+
|
|
79
|
+
##### Special session variables
|
|
80
|
+
|
|
81
|
+
Some session variables are handled in a special way.
|
|
82
|
+
|
|
83
|
+
* `XS_APPLICATIONUSER` - can be set to a user token (SAML/JWT) to associate the aplication user with the database connection
|
|
84
|
+
* `SAP_PASSPORT` - used to propagate SAP passport to SAP HANA, used for end-to-end tracing
|
|
85
|
+
* `APPLICATION` - the name of the application initiating the database connection
|
|
86
|
+
|
|
87
|
+
**Note**: If providing an SAP Passport in the `session` object of the [additional options](#additional-options),
|
|
88
|
+
it should have already been updated with data, specific to the component that consumes *@sap/hdbext*.
|
|
89
|
+
For more information, see the documentation of the *@sap/e2e-trace* package.
|
|
90
|
+
|
|
91
|
+
The [Express middleware](#express-middleware) provided by this package sets automatically
|
|
92
|
+
`XS_APPLICATIONUSER` and `SAP_PASSPORT` by extracting relevant data from the HTTP request (for requests that use client credentials token only the latter is set).
|
|
93
|
+
|
|
94
|
+
#### Example
|
|
95
|
+
|
|
96
|
+
Sample configuration with both [database connection options](#database-connection-options) and [additional options](#additional-options):
|
|
97
|
+
|
|
98
|
+
```js
|
|
99
|
+
{
|
|
100
|
+
host: 'my.host',
|
|
101
|
+
port: 30015,
|
|
102
|
+
user: 'my_user',
|
|
103
|
+
password: 'secret',
|
|
104
|
+
schema: 'name_of_the_schema',
|
|
105
|
+
isolationLevel: hdbext.constants.isolation.SERIALIZABLE,
|
|
106
|
+
locale: 'en_US',
|
|
107
|
+
session: {
|
|
108
|
+
APPLICATION: 'myapp',
|
|
109
|
+
SAP_PASSPORT: 'passport'
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### connectionOptions.getGlobalOptions()
|
|
115
|
+
|
|
116
|
+
Provides default values for these connection options:
|
|
117
|
+
* session.APPLICATION - extracted from VCAP_APPLICATION
|
|
118
|
+
* session.APPLICATIONVERSION - extracted from package.json in current directory
|
|
119
|
+
|
|
120
|
+
The application can override these defaults by setting these options explicitly.
|
|
121
|
+
|
|
122
|
+
### connectionOptions.getRequestOptions(req)
|
|
123
|
+
|
|
124
|
+
Provides these connection options based on the given HTTP request (_req_):
|
|
125
|
+
* session.SAP_PASSPORT (Updated with default component data)
|
|
126
|
+
* session.XS_APPLICATIONUSER (Only for requests that do not use client credentials token)
|
|
127
|
+
* locale
|
|
128
|
+
|
|
129
|
+
### updateConnectionOptions(client, options, callback)
|
|
130
|
+
|
|
131
|
+
It is also possible to change options on existing connection by using the `updateConnectionOptions` function:
|
|
132
|
+
|
|
133
|
+
```js
|
|
134
|
+
hdbext.updateConnectionOptions(client, options, function(error) {
|
|
135
|
+
if (error) {
|
|
136
|
+
return console.error(error);
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
// ...
|
|
140
|
+
});
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
`options` is an object having properties same as the [additional options](#additional-options).
|
|
144
|
+
|
|
145
|
+
### loadProcedure(client, schemaName, procedureName, callback)
|
|
146
|
+
|
|
147
|
+
Calling stored procedures could become complex using plain [hdb][4] driver, so there are functionalities provided to simplify these calls.
|
|
148
|
+
|
|
149
|
+
For example, if you have the following stored procedure:
|
|
150
|
+
|
|
151
|
+
```sql
|
|
152
|
+
create procedure PROC_DUMMY (in a int, in b int, out c int, out d DUMMY, out e TABLES)
|
|
153
|
+
language sqlscript
|
|
154
|
+
reads sql data as
|
|
155
|
+
begin
|
|
156
|
+
c := :a + :b;
|
|
157
|
+
d = select * from DUMMY;
|
|
158
|
+
e = select * from TABLES;
|
|
159
|
+
end
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
you can call it via the [hdb](https://www.npmjs.com/package/hdb) driver in the following way:
|
|
163
|
+
|
|
164
|
+
```js
|
|
165
|
+
client.prepare('call PROC_DUMMY (?, ?, ?, ?, ?)', function(err, statement) {
|
|
166
|
+
if (err) {
|
|
167
|
+
return console.error(err);
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
statement.exec({ A: 3, B: 4 }, function(err, parameters, dummyRows, tableRows) {
|
|
171
|
+
if (err) {
|
|
172
|
+
return console.error(err);
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
console.log('C:', parameters.C);
|
|
176
|
+
console.log('Dummies:', dummyRows);
|
|
177
|
+
console.log('Tables:', tableRows);
|
|
178
|
+
});
|
|
179
|
+
});
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
**Note**: Non-quoted names are automatically converted to uppercase by HANA.
|
|
183
|
+
|
|
184
|
+
With *@sap/hdbext* you don't need to construct a `CALL` statement. The procedure can be loaded by its name.
|
|
185
|
+
The code can look like this:
|
|
186
|
+
|
|
187
|
+
```js
|
|
188
|
+
hdbext.loadProcedure(client, 'MY_SCHEMA', 'PROC_DUMMY', function(err, sp) {
|
|
189
|
+
sp({ A: 3, B: 4 }, function(err, parameters, dummyRows, tableRows) {
|
|
190
|
+
if (err) {
|
|
191
|
+
return console.error(err);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
console.log('C:', parameters.C);
|
|
195
|
+
console.log('Dummies:', dummyRows);
|
|
196
|
+
console.log('Tables:', tableRows);
|
|
197
|
+
});
|
|
198
|
+
});
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
To use the current schema, pass an empty string `''`, `null` or `undefined` for schema.
|
|
202
|
+
|
|
203
|
+
`loadProcedure(client, schemaName, procedureName, callback)` retruns a JavaScript function which you can call directly.
|
|
204
|
+
The function has the `paramsMetadata` property containing metadata for all parameters of the stored procedure.
|
|
205
|
+
This could be useful if you need to implement generic stored procedures calling.
|
|
206
|
+
|
|
207
|
+
You can also pass the input parameters directly in the proper order:
|
|
208
|
+
|
|
209
|
+
```js
|
|
210
|
+
sp(3, 4, function(err, parameters, dummyRows, tableRows) {
|
|
211
|
+
// ...
|
|
212
|
+
});
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
or as an array:
|
|
216
|
+
|
|
217
|
+
```js
|
|
218
|
+
sp([3, 4], function(err, parameters, dummyRows, tableRows) {
|
|
219
|
+
// ...
|
|
220
|
+
});
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Where the big advantage comes in, is with table parameters.
|
|
224
|
+
You can pass an array of objects and *@sap/hdbext* will auto convert it into a table parameter.
|
|
225
|
+
Say we have a `customer` table with `ID` and `NAME` columns and the following procedure:
|
|
226
|
+
|
|
227
|
+
```sql
|
|
228
|
+
create procedure "getCustomers" (in in_table_1 "customer")
|
|
229
|
+
language sqlscript reads sql data as begin
|
|
230
|
+
select * from :in_table_1;
|
|
231
|
+
end;
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
You can call it like this:
|
|
235
|
+
|
|
236
|
+
```js
|
|
237
|
+
client.loadProcedure('MY_SCHEMA', 'getCustomers', function(err, sp) {
|
|
238
|
+
if (err) {
|
|
239
|
+
return console.error(err);
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
sp([
|
|
243
|
+
{ ID: 1, NAME: 'alex' },
|
|
244
|
+
{ ID: 2, NAME: 'peter' }
|
|
245
|
+
], function(err, parameters, dummyRows, tableRows) {
|
|
246
|
+
// ...
|
|
247
|
+
});
|
|
248
|
+
});
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
In this example each array element represents a table row. Property names should case-sensitively match the corresponding column names.
|
|
252
|
+
|
|
253
|
+
Internally *@sap/hdbext* creates a local temporary table in the current schema for each table parameter.
|
|
254
|
+
Thus, the current user needs the respective permissions.
|
|
255
|
+
|
|
256
|
+
Input arguments for parameters that have default values can be skipped in order to use the defined defaults.
|
|
257
|
+
It is recommended to pass the input as an object in those cases. In this way the application code would be independent
|
|
258
|
+
from the order in which parameters with default values are defined in the procedure.
|
|
259
|
+
When the parameters are passed in a sequence (i.e. as an array or are passed directly in the proper order),
|
|
260
|
+
input arguments can be skipped only for the parameters which are after the last mandatory parameter in the procedure's list.
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
### Connection Pooling
|
|
264
|
+
|
|
265
|
+
*@sap/hdbext* implements a simple [generic-pool][1] for pooling connections.
|
|
266
|
+
|
|
267
|
+
To use it you first synchronously create the pool:
|
|
268
|
+
|
|
269
|
+
```js
|
|
270
|
+
var pool = hdbext.getPool(hanaConfig, poolConfig);
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
The `hanaConfig` argument contains both [database connection options](#database-connection-options) and [additional options](#additional-options).
|
|
274
|
+
|
|
275
|
+
The `poolConfig` argument is optional. It may contain configurations for the pool itself.
|
|
276
|
+
|
|
277
|
+
You can acquire a client from the pool. It is delivered via a callback:
|
|
278
|
+
|
|
279
|
+
```js
|
|
280
|
+
pool.acquire(function(err, client) {
|
|
281
|
+
// ...
|
|
282
|
+
});
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
If settings of the pooled connection need to be changed, an optional `options` object can be used.
|
|
286
|
+
```js
|
|
287
|
+
pool.acquire(options, function(err, client) {
|
|
288
|
+
// ...
|
|
289
|
+
});
|
|
290
|
+
```
|
|
291
|
+
Refer to the [additional options](#additional-options) section for more details.
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
When the client is no longer needed you should release it to the pool with `pool.release(client);`, `client.close();` or `client.disconnect();`.
|
|
295
|
+
|
|
296
|
+
When the pool is no longer needed you can dispose of the idle connections by draining the pool with `pool.drain()`.
|
|
297
|
+
|
|
298
|
+
The following property can be used to access the actual pool (refer to the generic-pool module):
|
|
299
|
+
```js
|
|
300
|
+
pool.pool
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
For managing your own pools, you can use:
|
|
304
|
+
```js
|
|
305
|
+
var pool = hdbext.createPool(hanaConfig, poolConfig);
|
|
306
|
+
```
|
|
307
|
+
The options hanaConfig and poolConfig are same as above.
|
|
308
|
+
|
|
309
|
+
### Express Middleware
|
|
310
|
+
|
|
311
|
+
*@sap/hdbext* provides an [Express][3] [middleware][2] which allows easy access to a connection pool in an Express based application.
|
|
312
|
+
In the background a connection pool is created. The connection is automatically returned to the pool when the express request is closed or finished.
|
|
313
|
+
|
|
314
|
+
```js
|
|
315
|
+
var hdbext = require('@sap/hdbext');
|
|
316
|
+
var express = require('express');
|
|
317
|
+
|
|
318
|
+
var app = express();
|
|
319
|
+
app.use(hdbext.middleware(hanaConfig, poolConfig));
|
|
320
|
+
|
|
321
|
+
app.get('/execute-query', function (req, res) {
|
|
322
|
+
var client = req.db;
|
|
323
|
+
|
|
324
|
+
client.exec('SELECT * FROM DUMMY', function (err, rs) {
|
|
325
|
+
if (err) {
|
|
326
|
+
return res.end('Error: ' + err.message);
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
res.end(JSON.stringify(rs));
|
|
330
|
+
});
|
|
331
|
+
});
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
The argument `hanaConfig` may contain both [database connection options](#database-connection-options) and [additional options](#additional-options).
|
|
335
|
+
|
|
336
|
+
The argument `poolConfig` is optional. It may contain configurations for the created pool.
|
|
337
|
+
|
|
338
|
+
The middleware sets the `XS_APPLICATIONUSER` and the `SAP_PASSPORT` session variables automatically,
|
|
339
|
+
if the corresponding data is available in the HTTP request. For requests that use client credentials token only the latter is set.
|
|
340
|
+
It also sets `APPLICATION` and `APPLICATIONVERSION` session variables automatically to some
|
|
341
|
+
default values extracted from the environment.
|
|
342
|
+
|
|
343
|
+
### SQL Parameter Utilities
|
|
344
|
+
|
|
345
|
+
The `hdbext.sqlInjectionUtils` object contains several synchronous utility functions that can be used to prevent SQL injections.
|
|
346
|
+
|
|
347
|
+
#### isAcceptableParameter(value, maxToken)
|
|
348
|
+
|
|
349
|
+
Returns true if `value` can be used to construct SQL statements.
|
|
350
|
+
The number of tokens a value is allowed to contain is set via the optional `maxToken` argument. Defaults to 1.
|
|
351
|
+
|
|
352
|
+
#### isAcceptableQuotedParameter(value)
|
|
353
|
+
|
|
354
|
+
Returns true if the provided `value` is quoted correctly and can be used in an SQL statement.
|
|
355
|
+
|
|
356
|
+
#### escapeDoubleQuotes(value)
|
|
357
|
+
|
|
358
|
+
Returns the `value` parameter with all double quotation marks escaped (i. e. doubled).
|
|
359
|
+
|
|
360
|
+
#### escapeSingleQuotes(value)
|
|
361
|
+
|
|
362
|
+
Returns the `value` parameter with all single quotation marks escaped (i. e. doubled).
|
|
363
|
+
|
|
364
|
+
## Troubleshooting
|
|
365
|
+
|
|
366
|
+
To enable tracing, you should set the environment variable `DEBUG` to `hdbext:*`.
|
|
367
|
+
|
|
368
|
+
[1]: https://github.com/coopernurse/node-pool
|
|
369
|
+
[2]: http://expressjs.com/guide/using-middleware.html
|
|
370
|
+
[3]: http://expressjs.com/
|
|
371
|
+
[4]: https://www.npmjs.com/package/hdb
|
|
372
|
+
[5]: https://www.npmjs.com/package/hdb#establish-a-database-connection
|
|
373
|
+
[6]: https://www.npmjs.com/package/hdb#encrypted-network-communication
|
package/_hdbext/index.js
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
var assert = require('assert');
|
|
4
|
+
var _ = require('lodash');
|
|
5
|
+
var hdb = require('hdb');
|
|
6
|
+
var clientSession = require('./client-session');
|
|
7
|
+
|
|
8
|
+
module.exports.createConnection = createConnection;
|
|
9
|
+
module.exports.openBaseConnection = openBaseConnection;
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
function createConnection(options, callback) {
|
|
13
|
+
openBaseConnection(options, function (err, client) {
|
|
14
|
+
if (err) {
|
|
15
|
+
client.close();
|
|
16
|
+
return callback(err);
|
|
17
|
+
}
|
|
18
|
+
clientSession.updateConnectionOptions(client, options, function (err) {
|
|
19
|
+
if (err) {
|
|
20
|
+
client.close();
|
|
21
|
+
client = null;
|
|
22
|
+
}
|
|
23
|
+
callback(err, client);
|
|
24
|
+
});
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function openBaseConnection(options, callback) {
|
|
29
|
+
options = normalizeOptions(options);
|
|
30
|
+
|
|
31
|
+
var client = hdb.createClient(options);
|
|
32
|
+
client.on('error', function (err) {
|
|
33
|
+
console.error('Network connection error: ', err); // eslint-disable-line no-console
|
|
34
|
+
});
|
|
35
|
+
client.connect(function (err) {
|
|
36
|
+
callback(err, client);
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function normalizeOptions(options) {
|
|
41
|
+
options = _.clone(options);
|
|
42
|
+
|
|
43
|
+
if (!options.hosts && options.db_hosts) {
|
|
44
|
+
assert(Array.isArray(options.db_hosts), 'options.db_hosts should be an array');
|
|
45
|
+
options.hosts = options.db_hosts;
|
|
46
|
+
delete options.db_hosts;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
if (!options.ca && options.certificate) {
|
|
50
|
+
options.ca = [options.certificate];
|
|
51
|
+
delete options.certificate;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
// hdb driver does not filter the properties passed to it
|
|
55
|
+
// and 'session' property is interpreted by the 'tls' module in hdb.
|
|
56
|
+
// Its value is rejected if it is not a Buffer.
|
|
57
|
+
if (options.session && !Buffer.isBuffer(options.session)) {
|
|
58
|
+
delete options.session;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
return options;
|
|
62
|
+
}
|