Update readme w info from docs (#229)
* Update readme w info from docs * Update README.md * Update README.md Fix problems, clarify.
This commit is contained in:
Rand McKinney
GitHub
parent
529eebbc60
commit
9fab8ba795
373
README.md
373
README.md
|
|
@ -1,50 +1,361 @@
|
||||||
# loopback-connector-mysql
|
# loopback-connector-mysql
|
||||||
|
|
||||||
`loopback-connector-mysql` is the MySQL connector module for [loopback-datasource-juggler](https://github.com/strongloop/loopback-datasource-juggler/).
|
[MySQL](https://www.mysql.com/) is a popular open-source relational database management system (RDBMS). The `loopback-connector-mysql` module provides the MySQL connector module for the LoopBack framework.
|
||||||
|
|
||||||
For complete documentation, see [StrongLoop Documentation | MySQL Connector](http://loopback.io/doc/en/lb2/MySQL-connector.html).
|
<div class="gh-only">See also [LoopBack MySQL Connector](http://loopback.io/doc/en/lb3/MySQL-connector.html) in LoopBack documentation.
|
||||||
|
|
||||||
|
**NOTE**: The MySQL connector requires MySQL 5.0+.
|
||||||
|
</div>
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
````sh
|
In your application root directory, enter this command to install the connector:
|
||||||
|
|
||||||
|
```sh
|
||||||
npm install loopback-connector-mysql --save
|
npm install loopback-connector-mysql --save
|
||||||
````
|
```
|
||||||
|
|
||||||
## Basic use
|
This installs the module from npm and adds it as a dependency to the application's `package.json` file.
|
||||||
|
|
||||||
To use it you need `loopback-datasource-juggler`.
|
If you create a MySQL 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.
|
||||||
|
|
||||||
1. Setup dependencies in `package.json`:
|
## Creating a MySQL data source
|
||||||
|
|
||||||
```json
|
Use the [Data source generator](http://loopback.io/doc/en/lb3/Data-source-generator.html) to add a MySQL data source to your application.
|
||||||
|
The generator will prompt for the database server hostname, port, and other settings
|
||||||
|
required to connect to a MySQL 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": "mysql",
|
||||||
|
"host": "myserver",
|
||||||
|
"port": 3306,
|
||||||
|
"database": "mydb",
|
||||||
|
"password": "mypassword",
|
||||||
|
"user": "admin"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Edit `datasources.json` to add any other additional properties that you require.
|
||||||
|
|
||||||
|
### Properties
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th width="150">Property</th>
|
||||||
|
<th width="80">Type</th>
|
||||||
|
<th>Description</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td>collation</td>
|
||||||
|
<td>String</td>
|
||||||
|
<td>Determines the charset for the connection. Default is utf8_general_ci.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>connector</td>
|
||||||
|
<td>String</td>
|
||||||
|
<td>Connector name, either “loopback-connector-mysql” or “mysql”.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>connectionLimit</td>
|
||||||
|
<td>Number</td>
|
||||||
|
<td>The maximum number of connections to create at once. Default is 10.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>database</td>
|
||||||
|
<td>String</td>
|
||||||
|
<td>Database name</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>debug</td>
|
||||||
|
<td>Boolean</td>
|
||||||
|
<td>If true, turn on verbose mode to debug database queries and lifecycle.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>host</td>
|
||||||
|
<td>String</td>
|
||||||
|
<td>Database host name</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>password</td>
|
||||||
|
<td>String</td>
|
||||||
|
<td>Password to connect to database</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>port</td>
|
||||||
|
<td>Number</td>
|
||||||
|
<td>Database TCP port</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>socketPath</td>
|
||||||
|
<td>String</td>
|
||||||
|
<td>The path to a unix domain socket to connect to. When used host and port are ignored.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>supportBigNumbers</td>
|
||||||
|
<td>Boolean</td>
|
||||||
|
<td>Enable this option to deal with big numbers (BIGINT and DECIMAL columns) in the database. Default is false.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>timeZone</td>
|
||||||
|
<td>String</td>
|
||||||
|
<td>The timezone used to store local dates. Default is ‘local’.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>url</td>
|
||||||
|
<td>String</td>
|
||||||
|
<td>Connection URL of form <code>mysql://user:password@host/db</code>. Overrides other connection settings.</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>username</td>
|
||||||
|
<td>String</td>
|
||||||
|
<td>Username to connect to database</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
**NOTE**: In addition to these properties, you can use additional parameters supported by [`node-mysql`](https://github.com/felixge/node-mysql).
|
||||||
|
|
||||||
|
## Type mappings
|
||||||
|
|
||||||
|
See [LoopBack types](http://loopback.io/doc/en/lb3/LoopBack-types.html) for details on LoopBack's data types.
|
||||||
|
|
||||||
|
### LoopBack to MySQL types
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>LoopBack Type</th>
|
||||||
|
<th>MySQL Type</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<td>String/JSON</td>
|
||||||
|
<td>VARCHAR</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Text</td>
|
||||||
|
<td>TEXT</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Number</td>
|
||||||
|
<td>INT</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Date</td>
|
||||||
|
<td>DATETIME</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Boolean</td>
|
||||||
|
<td>TINYINT(1)</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td><a href="http://apidocs.strongloop.com/loopback-datasource-juggler/#geopoint" class="external-link">GeoPoint</a> object</td>
|
||||||
|
<td>POINT</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Custom Enum type<br>(See <a href="#enum">Enum</a> below)</td>
|
||||||
|
<td>ENUM</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
### MySQL to LoopBack types
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<th>MySQL Type</th>
|
||||||
|
<th>LoopBack Type</th>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>CHAR</td>
|
||||||
|
<td>String</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>CHAR(1)</td>
|
||||||
|
<td>Boolean</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>VARCHAR<br>TINYTEXT<br>MEDIUMTEXT<br>LONGTEXT<br>TEXT<br>ENUM<br>SET</td>
|
||||||
|
<td>String</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>TINYBLOB<br>MEDIUMBLOB<br>LONGBLOB<br>BLOB<br>BINARY<br>VARBINARY<br>BIT</td>
|
||||||
|
<td>Node.js <a href="http://nodejs.org/api/buffer.html">Buffer object</a></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>TINYINT<br>SMALLINT<br>INT<br>MEDIUMINT<br>YEAR<br>FLOAT<br>DOUBLE<br>NUMERIC<br>DECIMAL</td>
|
||||||
|
<td>
|
||||||
|
<p>Number<br>For FLOAT and DOUBLE, see <a href="#floating-point-types">Floating-point types</a>. </p>
|
||||||
|
<p>For NUMERIC and DECIMAL, see <a href="MySQL-connector.html">Fixed-point exact value types</a></p>
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>DATE<br>TIMESTAMP<br>DATETIME</td>
|
||||||
|
<td>Date</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
## Using the datatype field/column option with MySQL
|
||||||
|
|
||||||
|
Use the `mysql` model property to specify additional MySQL-specific properties for a LoopBack model.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
{% include code-caption.html content="/common/models/model.json" %}
|
||||||
|
```javascript
|
||||||
|
"locationId":{
|
||||||
|
"type":"String",
|
||||||
|
"required":true,
|
||||||
|
"length":20,
|
||||||
|
"mysql":
|
||||||
{
|
{
|
||||||
...
|
"columnName":"LOCATION_ID",
|
||||||
"dependencies": {
|
"dataType":"VARCHAR2",
|
||||||
"loopback-datasource-juggler": "latest",
|
"dataLength":20,
|
||||||
"loopback-connector-mysql": "latest"
|
"nullable":"N"
|
||||||
},
|
|
||||||
...
|
|
||||||
}
|
}
|
||||||
```
|
}
|
||||||
|
```
|
||||||
|
|
||||||
2. Use:
|
You can also use the dataType column/property attribute to specify what MySQL column type to use for many loopback-datasource-juggler types.
|
||||||
|
The following type-dataType combinations are supported:
|
||||||
|
|
||||||
```javascript
|
* Number
|
||||||
var DataSource = require('loopback-datasource-juggler').DataSource;
|
* integer
|
||||||
var dataSource = new DataSource('mysql', {
|
* tinyint
|
||||||
host: 'localhost',
|
* smallint
|
||||||
port: 3306,
|
* mediumint
|
||||||
database: 'mydb',
|
* int
|
||||||
username: 'myuser',
|
* bigint
|
||||||
password: 'mypass'
|
|
||||||
});
|
|
||||||
```
|
|
||||||
You can optionally pass a few additional parameters supported by [`node-mysql`](https://github.com/felixge/node-mysql),
|
|
||||||
most particularly `password` and `collation`. `Collation` currently defaults
|
|
||||||
to `utf8_general_ci`. The `collation` value will also be used to derive the
|
|
||||||
connection charset.
|
|
||||||
|
|
||||||
## Running Tests
|
Use the `limit` option to alter the display width. Example:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
{ userName : {
|
||||||
|
type: String,
|
||||||
|
dataType: 'char',
|
||||||
|
limit: 24
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Floating-point types
|
||||||
|
|
||||||
|
For Float and Double data types, use the `precision` and `scale` options to specify custom precision. Default is (16,8). For example:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
{ average :
|
||||||
|
{ type: Number,
|
||||||
|
dataType: 'float',
|
||||||
|
precision: 20,
|
||||||
|
scale: 4
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fixed-point exact value types
|
||||||
|
|
||||||
|
For Decimal and Numeric types, use the `precision` and `scale` options to specify custom precision. Default is (9,2).
|
||||||
|
These aren't likely to function as true fixed-point.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
{ stdDev :
|
||||||
|
{ type: Number,
|
||||||
|
dataType: 'decimal',
|
||||||
|
precision: 12,
|
||||||
|
scale: 8
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Other types
|
||||||
|
|
||||||
|
Convert String / DataSource.Text / DataSource.JSON to the following MySQL types:
|
||||||
|
|
||||||
|
* varchar
|
||||||
|
* char
|
||||||
|
* text
|
||||||
|
* mediumtext
|
||||||
|
* tinytext
|
||||||
|
* longtext
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
{ userName :
|
||||||
|
{ type: String,
|
||||||
|
dataType: 'char',
|
||||||
|
limit: 24
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
{ biography :
|
||||||
|
{ type: String,
|
||||||
|
dataType: 'longtext'
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Convert JSON Date types to datetime or timestamp
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
{ startTime :
|
||||||
|
{ type: Date,
|
||||||
|
dataType: 'timestamp'
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Enum
|
||||||
|
|
||||||
|
Enums are special. Create an Enum using Enum factory:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
var MOOD = dataSource.EnumFactory('glad', 'sad', 'mad');
|
||||||
|
MOOD.SAD; // 'sad'
|
||||||
|
MOOD(2); // 'sad'
|
||||||
|
MOOD('SAD'); // 'sad'
|
||||||
|
MOOD('sad'); // 'sad'
|
||||||
|
{ mood: { type: MOOD }}
|
||||||
|
{ choice: { type: dataSource.EnumFactory('yes', 'no', 'maybe'), null: false }}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Discovery and auto-migration
|
||||||
|
|
||||||
|
### Model discovery
|
||||||
|
|
||||||
|
The MySQL 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).
|
||||||
|
|
||||||
|
### Auto-migratiion
|
||||||
|
|
||||||
|
The MySQL 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.
|
||||||
|
|
||||||
|
Destroying models may result in errors due to foreign key integrity. First delete any related models first 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.
|
The tests in this repository are mainly integration tests, meaning you will need to run them using our preconfigured test server.
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue