docs: separate usage.md and remove duplicates (#10899)

.esdoc.json

@@ -38,7 +38,7 @@
           "asset": "./docs/images",
           "files": [
             "./docs/getting-started.md",
-            "./docs/usage.md",
+            "./docs/dialects.md",
             "./docs/data-types.md",
             "./docs/models-definition.md",
             "./docs/models-usage.md",
@@ -49,6 +49,7 @@
             "./docs/transactions.md",
             "./docs/scopes.md",
             "./docs/raw-queries.md",
+            "./docs/read-replication.md",
             "./docs/migrations.md",
             "./docs/resources.md",
             "./docs/typescript.md",

docs/dialects.md

+# Dialects
+
+Sequelize is independent from specific dialects. This means that you'll have to install the respective connector library to your project yourself.
+
+## MySQL
+
+In order to get Sequelize working nicely together with MySQL, you'll need to install`mysql2@^1.5.2`or higher. Once that's done you can use it like this:
+
+```js
+const sequelize = new Sequelize('database', 'username', 'password', {
+  dialect: 'mysql'
+})
+```
+
+**Note:** You can pass options directly to dialect library by setting the
+`dialectOptions` parameter. See [Options](/manual/usage.html#options).
+
+## MariaDB
+
+Library for MariaDB is `mariadb`.
+
+```js
+const sequelize = new Sequelize('database', 'username', 'password', {
+  dialect: 'mariadb',
+  dialectOptions: {connectTimeout: 1000} // mariadb connector option
+})
+```
+
+or using connection String:
+
+```js
+const sequelize = new Sequelize('mariadb://user:password@example.com:9821/database')
+```
+
+## SQLite
+
+For SQLite compatibility you'll need`sqlite3@^4.0.0`. Configure Sequelize like this:
+
+```js
+const sequelize = new Sequelize('database', 'username', 'password', {
+  // sqlite! now!
+  dialect: 'sqlite',
+
+  // the storage engine for sqlite
+  // - default ':memory:'
+  storage: 'path/to/database.sqlite'
+})
+```
+
+Or you can use a connection string as well with a path:
+
+```js
+const sequelize = new Sequelize('sqlite:/home/abs/path/dbname.db')
+const sequelize = new Sequelize('sqlite:relativePath/dbname.db')
+```
+
+## PostgreSQL
+
+For PostgreSQL, two libraries are needed, `pg@^7.0.0` and `pg-hstore`. You'll just need to define the dialect:
+
+```js
+const sequelize = new Sequelize('database', 'username', 'password', {
+  // gimme postgres, please!
+  dialect: 'postgres'
+})
+```
+
+To connect over a unix domain socket, specify the path to the socket directory
+in the `host` option.
+
+The socket path must start with `/`.
+
+```js
+const sequelize = new Sequelize('database', 'username', 'password', {
+  // gimme postgres, please!
+  dialect: 'postgres',
+  host: '/path/to/socket_directory'
+})
+```
+
+## MSSQL
+
+The library for MSSQL is`tedious@^6.0.0` You'll just need to define the dialect:
+
+```js
+const sequelize = new Sequelize('database', 'username', 'password', {
+  dialect: 'mssql'
+})
+```

docs/raw-queries.md

 # Raw queries
 
-As there are often use cases in which it is just easier to execute raw / already prepared SQL queries, you can utilize the function `sequelize.query`.
+As there are often use cases in which it is just easier to execute raw / already prepared SQL queries, you can use the function `sequelize.query`.
 
 By default the function will return two arguments - a results array, and an object containing metadata (affected rows etc.). Note that since this is a raw query, the metadata (property names etc.) is dialect specific. Some dialects return the metadata "within" the results object (as properties on an array). However, two arguments will always be returned, but for MSSQL and MySQL it will be two references to the same object.
 
@@ -35,6 +35,56 @@ sequelize
   })
 ```
 
+See more options in the [query API reference](class/lib/sequelize.js~Sequelize.html#instance-method-query). Some examples below:
+
+```js
+sequelize.query('SELECT 1', {
+  // A function (or false) for logging your queries
+  // Will get called for every SQL query that gets sent
+  // to the server.
+  logging: console.log,
+
+  // If plain is true, then sequelize will only return the first
+  // record of the result set. In case of false it will return all records.
+  plain: false,
+
+  // Set this to true if you don't have a model definition for your query.
+  raw: false,
+
+  // The type of query you are executing. The query type affects how results are formatted before they are passed back.
+  type: Sequelize.QueryTypes.SELECT
+})
+
+// Note the second argument being null!
+// Even if we declared a callee here, the raw: true would
+// supersede and return a raw object.
+sequelize
+  .query('SELECT * FROM projects', { raw: true })
+  .then(projects => {
+    console.log(projects)
+  })
+```
+
+## "Dotted" attributes
+
+If an attribute name of the table contains dots, the resulting objects will be nested. This is due to the usage of [dottie.js](https://github.com/mickhansen/dottie.js/) under the hood. See below:
+
+```js
+sequelize.query('select 1 as `foo.bar.baz`').then(rows => {
+  console.log(JSON.stringify(rows))
+})
+```
+
+```json
+[{
+  "foo": {
+    "bar": {
+      "baz": 1
+    }
+  }
+}]
+```
+
 ## Replacements
 
 Replacements in a query can be done in two different ways, either using named parameters (starting with `:`), or unnamed, represented by a `?`. Replacements are passed in the options object.

docs/read-replication.md

+# Read replication
+
+Sequelize supports read replication, i.e. having multiple servers that you can connect to when you want to do a SELECT query. When you do read replication, you specify one or more servers to act as read replicas, and one server to act as the write master, which handles all writes and updates and propagates them to the replicas (note that the actual replication process is **not** handled by Sequelize, but should be set up by database backend).
+
+```js
+const sequelize = new Sequelize('database', null, null, {
+  dialect: 'mysql',
+  port: 3306
+  replication: {
+    read: [
+      { host: '8.8.8.8', username: 'read-username', password: 'some-password' },
+      { host: '9.9.9.9', username: 'another-username', password: null }
+    ],
+    write: { host: '1.1.1.1', username: 'write-username', password: 'any-password' }
+  },
+  pool: { // If you want to override the options used for the read/write pool you can do so here
+    max: 20,
+    idle: 30000
+  },
+})
+```
+
+If you have any general settings that apply to all replicas you do not need to provide them for each instance. In the code above, database name and port is propagated to all replicas. The same will happen for user and password, if you leave them out for any of the replicas. Each replica has the following options:`host`,`port`,`username`,`password`,`database`.
+
+Sequelize uses a pool to manage connections to your replicas. Internally Sequelize will maintain two pools created using `pool` configuration.
+
+If you want to modify these, you can pass pool as an options when instantiating Sequelize, as shown above.
+
+Each `write` or `useMaster: true` query will use write pool. For `SELECT` read pool will be used. Read replica are switched using a basic round robin scheduling.
\ No newline at end of file

lib/sequelize.js

@@ -48,6 +48,82 @@ class Sequelize {
    * // with uri
    * const sequelize = new Sequelize('mysql://localhost:3306/database', {})
    *
+   * // option examples
+   * const sequelize = new Sequelize('database', 'username', 'password', {
+   *   // the sql dialect of the database
+   *   // currently supported: 'mysql', 'sqlite', 'postgres', 'mssql'
+   *   dialect: 'mysql',
+   * 
+   *   // custom host; default: localhost
+   *   host: 'my.server.tld',
+   *   // for postgres, you can also specify an absolute path to a directory
+   *   // containing a UNIX socket to connect over
+   *   // host: '/sockets/psql_sockets'.
+   * 
+   *   // custom port; default: dialect default
+   *   port: 12345,
+   * 
+   *   // custom protocol; default: 'tcp'
+   *   // postgres only, useful for Heroku
+   *   protocol: null,
+   * 
+   *   // disable logging or provide a custom logging function; default: console.log
+   *   logging: false,
+   * 
+   *   // you can also pass any dialect options to the underlying dialect library
+   *   // - default is empty
+   *   // - currently supported: 'mysql', 'postgres', 'mssql'
+   *   dialectOptions: {
+   *     socketPath: '/Applications/MAMP/tmp/mysql/mysql.sock',
+   *     supportBigNumbers: true,
+   *     bigNumberStrings: true
+   *   },
+   * 
+   *   // the storage engine for sqlite
+   *   // - default ':memory:'
+   *   storage: 'path/to/database.sqlite',
+   * 
+   *   // disable inserting undefined values as NULL
+   *   // - default: false
+   *   omitNull: true,
+   * 
+   *   // a flag for using a native library or not.
+   *   // in the case of 'pg' -- set this to true will allow SSL support
+   *   // - default: false
+   *   native: true,
+   * 
+   *   // Specify options, which are used when sequelize.define is called.
+   *   // The following example:
+   *   //   define: { timestamps: false }
+   *   // is basically the same as:
+   *   //   Model.init(attributes, { timestamps: false });
+   *   //   sequelize.define(name, attributes, { timestamps: false });
+   *   // so defining the timestamps for each model will be not necessary
+   *   define: {
+   *     underscored: false,
+   *     freezeTableName: false,
+   *     charset: 'utf8',
+   *     dialectOptions: {
+   *       collate: 'utf8_general_ci'
+   *     },
+   *     timestamps: true
+   *   },
+   * 
+   *   // similar for sync: you can define this to always force sync for models
+   *   sync: { force: true },
+   * 
+   *   // pool configuration used to pool database connections
+   *   pool: {
+   *     max: 5,
+   *     idle: 30000,
+   *     acquire: 60000,
+   *   },
+   * 
+   *   // isolation level of each transaction
+   *   // defaults to dialect default
+   *   isolationLevel: Transaction.ISOLATION_LEVELS.REPEATABLE_READ
+   * })
+   * 
    * @param {string}   [database] The name of the database
    * @param {string}   [username=null] The username which is used to authenticate against the database.
    * @param {string}   [password=null] The password which is used to authenticate against the database. Supports SQLCipher encryption for SQLite.