diff --git a/CHANGES.md b/CHANGES.md index 205a99c..cfcf1a6 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -8,3 +8,8 @@ ========================= * First release! + +17-11-2017, Version 1.1.0 +========================= + + * Official Release to github & npm \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index e91797f..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,151 +0,0 @@ -### Contributing ### - -Thank you for your interest in `loopback-connector-oracle`, an open source project -administered by StrongLoop. - -Contributing to `loopback-connector-oracle` is easy. In a few simple steps: - - * Ensure that your effort is aligned with the project's roadmap by - talking to the maintainers, especially if you are going to spend a - lot of time on it. - - * Make something better or fix a bug. - - * Adhere to code style outlined in the [Google C++ Style Guide][] and - [Google Javascript Style Guide][]. - - * Sign the [Contributor License Agreement](https://cla.strongloop.com/agreements/strongloop/loopback-connector-oracle) - - * Submit a pull request through Github. - - -### Contributor License Agreement ### - -``` - Individual Contributor License Agreement - - By signing this Individual Contributor License Agreement - ("Agreement"), and making a Contribution (as defined below) to - StrongLoop, Inc. ("StrongLoop"), You (as defined below) accept and - agree to the following terms and conditions for Your present and - future Contributions submitted to StrongLoop. Except for the license - granted in this Agreement to StrongLoop and recipients of software - distributed by StrongLoop, You reserve all right, title, and interest - in and to Your Contributions. - - 1. Definitions - - "You" or "Your" shall mean the copyright owner or the individual - authorized by the copyright owner that is entering into this - Agreement with StrongLoop. - - "Contribution" shall mean any original work of authorship, - including any modifications or additions to an existing work, that - is intentionally submitted by You to StrongLoop for inclusion in, - or documentation of, any of the products owned or managed by - StrongLoop ("Work"). For purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication - sent to StrongLoop or its representatives, including but not - limited to communication or electronic mailing lists, source code - control systems, and issue tracking systems that are managed by, - or on behalf of, StrongLoop for the purpose of discussing and - improving the Work, but excluding communication that is - conspicuously marked or otherwise designated in writing by You as - "Not a Contribution." - - 2. You Grant a Copyright License to StrongLoop - - Subject to the terms and conditions of this Agreement, You hereby - grant to StrongLoop and recipients of software distributed by - StrongLoop, a perpetual, worldwide, non-exclusive, no-charge, - royalty-free, irrevocable copyright license to reproduce, prepare - derivative works of, publicly display, publicly perform, - sublicense, and distribute Your Contributions and such derivative - works under any license and without any restrictions. - - 3. You Grant a Patent License to StrongLoop - - Subject to the terms and conditions of this Agreement, You hereby - grant to StrongLoop and to recipients of software distributed by - StrongLoop a perpetual, worldwide, non-exclusive, no-charge, - royalty-free, irrevocable (except as stated in this Section) - patent license to make, have made, use, offer to sell, sell, - import, and otherwise transfer the Work under any license and - without any restrictions. The patent license You grant to - StrongLoop under this Section applies only to those patent claims - licensable by You that are necessarily infringed by Your - Contributions(s) alone or by combination of Your Contributions(s) - with the Work to which such Contribution(s) was submitted. If any - entity institutes a patent litigation against You or any other - entity (including a cross-claim or counterclaim in a lawsuit) - alleging that Your Contribution, or the Work to which You have - contributed, constitutes direct or contributory patent - infringement, any patent licenses granted to that entity under - this Agreement for that Contribution or Work shall terminate as - of the date such litigation is filed. - - 4. You Have the Right to Grant Licenses to StrongLoop - - You represent that You are legally entitled to grant the licenses - in this Agreement. - - If Your employer(s) has rights to intellectual property that You - create, You represent that You have received permission to make - the Contributions on behalf of that employer, that Your employer - has waived such rights for Your Contributions, or that Your - employer has executed a separate Corporate Contributor License - Agreement with StrongLoop. - - 5. The Contributions Are Your Original Work - - You represent that each of Your Contributions are Your original - works of authorship (see Section 8 (Submissions on Behalf of - Others) for submission on behalf of others). You represent that to - Your knowledge, no other person claims, or has the right to claim, - any right in any intellectual property right related to Your - Contributions. - - You also represent that You are not legally obligated, whether by - entering into an agreement or otherwise, in any way that conflicts - with the terms of this Agreement. - - You represent that Your Contribution submissions include complete - details of any third-party license or other restriction (including, - but not limited to, related patents and trademarks) of which You - are personally aware and which are associated with any part of - Your Contributions. - - 6. You Don't Have an Obligation to Provide Support for Your Contributions - - You are not expected to provide support for Your Contributions, - except to the extent You desire to provide support. You may provide - support for free, for a fee, or not at all. - - 6. No Warranties or Conditions - - StrongLoop acknowledges that unless required by applicable law or - agreed to in writing, You provide Your Contributions on an "AS IS" - BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER - EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES - OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR - FITNESS FOR A PARTICULAR PURPOSE. - - 7. Submission on Behalf of Others - - If You wish to submit work that is not Your original creation, You - may submit it to StrongLoop separately from any Contribution, - identifying the complete details of its source and of any license - or other restriction (including, but not limited to, related - patents, trademarks, and license agreements) of which You are - personally aware, and conspicuously marking the work as - "Submitted on Behalf of a Third-Party: [named here]". - - 8. Agree to Notify of Change of Circumstances - - You agree to notify StrongLoop of any facts or circumstances of - which You become aware that would make these representations - inaccurate in any respect. Email us at callback@strongloop.com. -``` - -[Google C++ Style Guide]: https://google.github.io/styleguide/cppguide.html -[Google Javascript Style Guide]: https://google.github.io/styleguide/javascriptguide.xml diff --git a/README.md b/README.md index ee26f73..31ae779 100644 --- a/README.md +++ b/README.md @@ -1,479 +1,3 @@ # oe-connector-oracle This is a oracle connector for oeCloud framework developed based on loopback-connector-postgresql with the same license of postgres connector. - -[Oracle](https://www.oracle.com/database/index.html) is an object-relational database management system produced by Oracle Corporation. The `oe-connector-oracle` module is the Oracle connector for the oeCloud framework based on the [node-oracledb](https://github.com/oracle/node-oracledb) module. - -
-For more information, see the LoopBack documentation. -
- -## Prerequisites - -**Node.js**: The Oracle connector requires Node.js version 4.x or 6.x. - -**Windows**: On 32-bit Windows systems, you must use the 32-bit version of Node.js. On 64-bit Windows systems, you must use the 64-bit version of Node.js. For more information, see [Node-oracledb Installation on Windows](https://github.com/oracle/node-oracledb/blob/master/INSTALL.md#-7-node-oracledb-installation-on-windows). - -**Oracle**: The Oracle connector requires Oracle client libraries 11.2+ and can connect to Oracle Database Server 9.2+. - -## Installation - -In your application root directory, enter this command to install the connector: - -```shell -$ npm install oe-connector-oracle --save -``` - -If you create a Oracle data source using the data source generator as described below, you don’t have to do this, since the generator will run npm install for you. - -See [Installing the Oracle connector](http://loopback.io/doc/en/lb3/Installing-the-Oracle-connector.html) for further installation instructions. - -To simplify the installation of [node-oracledb](https://github.com/oracle/node-oracledb) module and Oracle instant clients, use [loopback-oracle-installer](https://github.com/strongloop/loopback-oracle-installer) as a dependency to install and configure `node-oracledb` (oracledb) upon `npm install`. - -Use the `config.oracleUrl` property to define the base URL to download the corresponding node-oracle (oracledb) bundle for the local environment. - -The bundle file name is `loopback-oracle---.tar.gz`. The `version` is the same as the `version` in package.json. - -```javascript - "dependencies": { - "loopback-oracle-installer": "git+ssh://git@github.com:strongloop/loopback-oracle-installer.git", - ... - }, - "config": { - "oracleUrl": "http://7e9918db41dd01dbf98e-ec15952f71452bc0809d79c86f5751b6.r22.cf1.rackcdn.com" - }, - ... -``` - -You can override the `oracleUrl` setting with the LOOPBACK_ORACLE_URL environment variable. - -For example, the full URL for v1.5.0 for MacOSX is: - -http://7e9918db41dd01dbf98e-ec15952f71452bc0809d79c86f5751b6.r22.cf1.rackcdn.com/loopback-oracle-MacOSX-x64-1.5.0.tar.gz - -The `libaio` library is required on Linux systems: - -On Ubuntu/Debian, get it with this command: - -``` -sudo apt-get install libaio1 -``` - -On Fedora/CentOS/RHEL, get it with this command: - -``` -sudo yum install libaio -``` - -## Creating an Oracle data source - -Use the [Data source generator](http://loopback.io/doc/en/lb3/Data-source-generator.html) to add a Oracle data source to your application. -The generator will prompt for the database server hostname, port, and other settings -required to connect to a Oracle database. It will also run the `npm install` command above for you. - -The entry in the application's `/server/datasources.json` will look like this: - -{% include code-caption.html content="/server/datasources.json" %} -```javascript -"mydb": { - "name": "mydb", - "connector": "oracle", - "tns": "demo", - "host": "myserver", - "port": 3306, - "database": "mydb", - "password": "mypassword", - "user": "admin" - } -``` - -Edit `datasources.json` to add any other additional properties that you require. - -## Connector properties - -The connector properties depend on [naming methods](http://docs.oracle.com/cd/E11882_01/network.112/e10836/naming.htm#NETAG008) you use for the Oracle database. -LoopBack supports three naming methods: - -* Easy connect: host/port/database. -* Local naming (TNS): alias to a full connection string that can specify all the attributes that Oracle supports. -* Directory naming (LDAP): directory for looking up the full connection string that can specify all the attributes that Oracle supports. - -### Easy Connect - -Easy Connect is the simplest form that provides out-of-the-box TCP/IP connectivity to databases. -The data source then has the following settings. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PropertyTypeDefaultDescription
host or hostnameStringlocalhostHost name or IP address of the Oracle database server
portNumber1521Port number of the Oracle database server
username or userString User name to connect to the Oracle database server
passwordString Password to connect to the Oracle database server
databaseStringXEOracle database listener name
- -For example: - -{% include code-caption.html content="/server/datasources.json" %} -```javascript -{ - "demoDB": { - "connector": "oracle", - "host": "oracle-demo.strongloop.com", - "port": 1521, - "database": "XE", - "username": "demo", - "password": "L00pBack" - } -} -``` - -### Local and directory naming - -Both local and directory naming require that you place configuration files in a TNS admin directory, such as `/oracle/admin`. - -**sqlnet.ora** - -This specifies the supported naming methods; for example: - -``` -NAMES.DIRECTORY_PATH=(LDAP,TNSNAMES,EZCONNECT) -``` - -**nsnames.ora** - -This maps aliases to connection stringsl for example: - -``` -demo1=(DESCRIPTION=(CONNECT_DATA=(SERVICE_NAME=))(ADDRESS=(PROTOCOL=TCP)(HOST=demo.strongloop.com)(PORT=1521))) -``` - -**ldap.ora** - -This configures the LDAP server. - -``` -DIRECTORY_SERVERS=(localhost:1389) -DEFAULT_ADMIN_CONTEXT="dc=strongloop,dc=com" -DIRECTORY_SERVER_TYPE=OID -``` - -#### Set up TNS_ADMIN environment variable - -For the Oracle connector to pick up the configurations, you must set the environment variable 'TNS_ADMIN' to the directory containing the `.ora` files. - -``` -export TNS_ADMIN= -``` - -Now you can use either the TNS alias or LDAP service name to configure a data source: - -```javascript -var ds = loopback.createDataSource({ - "tns": "demo", // The tns property can be a tns name or LDAP service name - "username": "demo", - "password": "L00pBack" -}); -``` - -### Connection pooling options - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Property nameDescriptionDefault value
minConnMaximum number of connections in the connection pool1
maxConnMinimum number of connections in the connection pool10
incrConn -

Incremental number of connections for the connection pool.

-
1
timeout - Time-out period in seconds for a connection in the connection pool. - The Oracle connector - will terminate connections in this - connection pool that are idle longer than the time-out period. - 10
- -For example, - -{% include code-caption.html content="/server/datasources.json" %} -```javascript -{ - "demoDB": { - "connector": "oracle", - "minConn":1, - "maxConn":5, - "incrConn":1, - "timeout": 10, - ... - } -} -``` - -### Connection troubleshooting - -If you encounter this error: - -``` -Error: ORA-24408: could not generate unique server group name -``` - -Then the Oracle 11g client requires an entry with your hostname pointing to -`127.0.0.1`. - -To resolve: - -Get your hostname. Check your hostname by running this command (for example, if your machine's name is "earth"): - -``` -$ hostname -earth -``` - -Update `/etc/hosts` and map `127.0.0.1` to your hostname "earth": - -``` -... -127.0.0.1 localhost earth -... -``` - -Verify the fix. Run the example in `examples/app.js`: - -``` -$ node examples/app.js -``` - -For more information, see [StackOverflow question](http://stackoverflow.com/questions/10484231/ora-24408-could-not-generate-unique-server-group-name). - -## Model properties - -An Oracle model definition consists of the following properties: - -* `name`: Name of the model, by default, it's the camel case of the table. -* `options`: Model-level operations and mapping to Oracle schema/table. -* `properties`: Property definitions, including mapping to Oracle column. - -{% include code-caption.html content="/common/models/model.json" %} -```javascript -{ - "name":"Inventory", - "options":{ - "idInjection":false, - "oracle":{ - "schema":"STRONGLOOP", - "table":"INVENTORY" - } - }, - "properties":{ - "productId":{ - "type":"String", - "required":true, - "length":20, - "id":1, - "oracle":{ - "columnName":"PRODUCT_ID", - "dataType":"VARCHAR2", - "dataLength":20, - "nullable":"N" - } - }, - "locationId":{ - "type":"String", - "required":true, - "length":20, - "id":2, - "oracle":{ - "columnName":"LOCATION_ID", - "dataType":"VARCHAR2", - "dataLength":20, - "nullable":"N" - } - }, - "available":{ - "type":"Number", - "required":false, - "length":22, - "oracle":{ - "columnName":"AVAILABLE", - "dataType":"NUMBER", - "dataLength":22, - "nullable":"Y" - } - }, - "total":{ - "type":"Number", - "required":false, - "length":22, - "oracle":{ - "columnName":"TOTAL", - "dataType":"NUMBER", - "dataLength":22, - "nullable":"Y" - } - } - } - } -``` - -## Type mapping - -See [LoopBack types](http://loopback.io/doc/en/lb3/LoopBack-types.html) for details on LoopBack's data types. - -### JSON to Oracle Types - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LoopBack TypeOracle Type
String
JSON
Text
default
VARCHAR2 -
Default length is 1024 -
NumberNUMBER
DateDATE
TimestampTIMESTAMP(3)
BooleanCHAR(1)
- -### Oracle Types to JSON - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Oracle TypeLoopBack Type
CHAR(1)Boolean
CHAR(n)
VARCHAR
VARCHAR2,
LONG VARCHAR
NCHAR
NVARCHAR2
String
LONG, BLOB, CLOB, NCLOBNode.js Buffer object
NUMBER
INTEGER
DECIMAL
DOUBLE
FLOAT
BIGINT
SMALLINT
REAL
NUMERIC
BINARY_FLOAT
BINARY_DOUBLE
UROWID
ROWID
Number
DATE
TIMESTAMP
Date
- -## Discovery and auto-migration - -### Model discovery - -The Oracle connector supports _model discovery_ that enables you to create LoopBack models -based on an existing database schema using the unified [database discovery API](http://apidocs.strongloop.com/loopback-datasource-juggler/#datasource-prototype-discoverandbuildmodels). For more information on discovery, see [Discovering models from relational databases](https://loopback.io/doc/en/lb3/Discovering-models-from-relational-databases.html). - -For an example of model discover, see [`example/app.js`](https://github.com/strongloop/loopback-connector-oracle/blob/master/example/app.js). - -### Auto-migratiion - -The Oracle connector also supports _auto-migration_ that enables you to create a database schema -from LoopBack models using the [LoopBack automigrate method](http://apidocs.strongloop.com/loopback-datasource-juggler/#datasource-prototype-automigrate). - -For more information on auto-migration, see [Creating a database schema from models](https://loopback.io/doc/en/lb3/Creating-a-database-schema-from-models.html) for more information. - -LoopBack Oracle connector creates the following schema objects for a given model: - -* A table, for example, PRODUCT -* A sequence for the primary key, for example, PRODUCT_ID_SEQUENCE -* A trigger to generate the primary key from the sequnce, for example, PRODUCT_ID_TRIGGER - -Destroying models may result in errors due to foreign key integrity. First delete any related models by calling delete on models with relationships. - -## Running tests - -The tests in this repository are mainly integration tests, meaning you will need -to run them using our preconfigured test server. - -1. Ask a core developer for instructions on how to set up test server - credentials on your machine -2. `npm test` diff --git a/package.json b/package.json index 3e10dfb..5ea4d98 100644 --- a/package.json +++ b/package.json @@ -20,7 +20,6 @@ "bluebird": "^3.3.3", "eslint": "^3.17.0", "eslint-config-loopback": "^8.0.0", - "loopback-datasource-juggler": "^3.0.0", "mocha": "^3.2.0", "rc": "^1.0.0", "should": "^8.0.2" @@ -35,6 +34,6 @@ "license": "SEE LICENSE IN LICENSE.md", "repository": { "type": "git", - "url": "git+http://evgit/oecloud.io/loopback-connector-oracle.git" + "url": "git+https://github.com/edgeverve/oe-connector-oracle.git" } } \ No newline at end of file diff --git a/run-tests b/run-tests deleted file mode 100644 index b091be4..0000000 --- a/run-tests +++ /dev/null @@ -1,4 +0,0 @@ -#!/bin/bash -ROOT=`dirname $0` -$ROOT/node_modules/.bin/mocha --timeout 10000 --require $ROOT/test/init.js $ROOT/test/*.test.js -