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` 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
|
||||
|
||||
````sh
|
||||
In your application root directory, enter this command to install the connector:
|
||||
|
||||
```sh
|
||||
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":
|
||||
{
|
||||
...
|
||||
"dependencies": {
|
||||
"loopback-datasource-juggler": "latest",
|
||||
"loopback-connector-mysql": "latest"
|
||||
},
|
||||
...
|
||||
"columnName":"LOCATION_ID",
|
||||
"dataType":"VARCHAR2",
|
||||
"dataLength":20,
|
||||
"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
|
||||
var DataSource = require('loopback-datasource-juggler').DataSource;
|
||||
var dataSource = new DataSource('mysql', {
|
||||
host: 'localhost',
|
||||
port: 3306,
|
||||
database: 'mydb',
|
||||
username: 'myuser',
|
||||
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.
|
||||
* Number
|
||||
* integer
|
||||
* tinyint
|
||||
* smallint
|
||||
* mediumint
|
||||
* int
|
||||
* bigint
|
||||
|
||||
## 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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue