docs: logging and sequelzie adapter (zh)

also changed the language switching button in layout a bit. It will switch to the target language of current page first.

docs/_layouts/en.html

@@ -19,22 +19,22 @@
             <li><a href="{{ '/associations' | relative_url }}">Associations</a></li>
             <li><a href="{{ '/querying' | relative_url }}">Query Interface</a></li>
             <li><a href="{{ '/hooks' | relative_url }}">Hooks</a></li>
-            <li><a href="{{ '/logging' | relative_url }}">[wip] Logging</a></li>
+            <li><a href="{{ '/logging' | relative_url }}">Logging</a></li>
             <li><a href="{{ '/sequelize' | relative_url }}">Sequelize Adapter</a></li>
           </ul>
         </li>
         <li class="nav-item dropdown-trigger">
           <a href="{{ '/setup' | relative_url }}">Setup</a>
           <ul class="dropdown-list">
-            <li><a href="{{ '/setup/egg' | relative_url }}">Setup Egg Applications</a></li>
-            <li><a href="{{ '/setup/express' | relative_url }}">[wip] Setup Express Applications</a></li>
+            <li><a href="{{ '/setup/egg' | relative_url }}">Setup with Egg / Chair</a></li>
+            <li><a href="{{ '/setup/express' | relative_url }}">[wip] Setup with Express</a></li>
           </ul>
         </li>
         <li class="nav-item">
           <a href="{{ '/api' | relative_url }}">API</a>
         </li>
         <li class="nav-item dropdown-trigger">
-          <a href="{{ '/zh' | relative_url }}">中文</a>
+          <a href="{{ page.url | prepend: '/zh' | relative_url }}">中文</a>
         </li>
       </ul>
     </nav>

docs/_layouts/zh.html

@@ -19,7 +19,7 @@
             <li><a href="{{ '/zh/associations' | relative_url }}">关联关系</a></li>
             <li><a href="{{ '/zh/querying' | relative_url }}">查询接口</a></li>
             <li><a href="{{ '/zh/hooks' | relative_url }}">钩子</a></li>
-            <li><a href="{{ '/zh/logging' | relative_url }}">[wip] 日志</a></li>
+            <li><a href="{{ '/zh/logging' | relative_url }}">日志</a></li>
             <li><a href="{{ '/zh/sequelize' | relative_url }}">Sequelize 适配器</a></li>
           </ul>
         </li>
@@ -34,7 +34,7 @@
           <a href="{{ '/api' | relative_url }}">API</a>
         </li>
         <li class="nav-item dropdown-trigger">
-          <a href="{{ '/' | relative_url }}">English</a>
+          <a href="{{ page.url | replace: '/zh', '' | relative_url }}">English</a>
         </li>
       </ul>
     </nav>

docs/associations.md

@@ -47,7 +47,7 @@ A `belongsTo()` association sets up a one-to-one or many-to-one relationship. Fo
 
 ```js
 class Item extends Bone {
-  static describe() {
+  static initialize() {
     this.belongsTo('shop')
   }
 }
@@ -57,7 +57,7 @@ Leoric locates the model class `Shop` automatically by capitalizing `shop` as th
 
 ```js
 class Item extends Bone {
-  static describe() {
+  static initialize() {
     this.belongsTo('shop', { className: 'Seller' })
   }
 }
@@ -73,7 +73,7 @@ To override foreign key, we can specify it explicitly:
 
 ```js
 class Item extends Bone {
-  static describe() {
+  static initialize() {
     this.belongsTo('shop', { foreignKey: 'sellerId' })
   }
 }
@@ -89,7 +89,7 @@ If you look this ER diagram from the shops point of view, you may notice that th
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('items')
   }
 }
@@ -103,7 +103,7 @@ To override the model name, we can specify it explicitly:
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('items', { className: 'Commodity' })
   }
 }
@@ -113,7 +113,7 @@ As you can tell from the ER diagram, the foreign key used to join two tables is
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('items', { foreignKey: 'sellerId' })
   }
 }
@@ -137,7 +137,7 @@ A shop can have as many tags as it see fit. And a tag can be related to as many
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static initialize() {
     // the extra where is needed if you fancy this generic tag system
     this.hasMany('tagMaps', { foreignKey: 'targetId', where: { targetType: 0 } })
     this.hasMany('tags', { through: 'tagMaps' })
@@ -149,7 +149,7 @@ On `Tag`'s side:
 
 ```js
 class Tag extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('shopTagMaps', { className: 'TagMap', where: { targetType: 0 } })
     this.hasMany('shops', { through: 'shopTagMaps' })
   }
@@ -160,7 +160,7 @@ If suddenly our business requires us to apply the tag system to items too, the c
 
 ```diff
 class Tag extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('shopTagMaps', { className: 'TagMap', where: { targetType: 0 } })
     this.hasMany('shops', { through: 'shopTagMaps' })
 +   this.hasMany('itemTagMaps', { className: 'TagMap', where: { targetType: 1 } })
@@ -185,7 +185,7 @@ In this example, a user has one shop:
 
 ```js
 class User extends Bone {
-  static describe() {
+  static initialize() {
     this.hasOne('shop', { foreignKey: 'ownerId' })
   }
 }
@@ -195,7 +195,7 @@ And the shop belongs to the user:
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static initialize() {
     this.belongsTo('owner', { className: 'User' })
   }
 }

docs/logging.md

@@ -2,4 +2,92 @@
 layout: en
 title: Logging
 ---
+## Table of Contents
+{:.no_toc}
 
+1. Table of Contents
+{:toc}
+
+We can customzie logging methods with the `logger` option like below:
+
+```js
+const realm = new Realm({
+  dialect: 'mysql',
+  host: 'localhost',
+  logger: {
+    logQuery(sql, duration, opts) {},            // queries
+    logQueryError(err, sql, duration, opts) {},  // failed queries
+    logMigration(name) {},                       // migrations
+  },
+});
+```
+
+## `logQuery`
+
+`logQuery(sql, duration, opts)` gets called when query completes, which receives arguments as explained in following table:
+
+| name | type | description |
+|-----|------|------|
+| `sql` | `string` | SQL of the query |
+| `duration` | `number` | response time of the query |
+| `opts.command` | `string` | command of the query |
+| `opts.connection` | `Connection` | related connection |
+| `opts.Model` | `Model` | the model that initiates the query |
+
+### SQL
+
+By default, we log the SQL as is. If there are sensible data to ignore, please consider the  `hideKeys` option to hide certain columns from the logger.
+
+### Response Time
+
+When performing model queries, such as `await User.findOne()`, the most time consuming steps are as below:
+
+1. obtaining a connection from the connection pool,
+2. sending query through obtained connection,
+3. getting and formatting the result.
+
+The duration in `logQuery`is about the time elapsed between step 2 and 3, which should be close to the response time from the database perspective.
+
+### Related Model
+
+The model related to the query is accessible through `opts.Model`. If there are multiple models participated in the query, `opts.Model` is only bound to the initiator.
+
+### Extra Info
+
+When performing queries through model methods, `opts` might contain extra info including but not limited to below:
+
+| name | type | description |
+|-----|------|-----|
+| `opts.hints` | `Hint[]` | optimizer hints |
+| `opts.columns` | `string[]` | columns to select |
+| `opts.whereConditions` | `object[]` | where conditions |
+
+## `logQueryError`
+
+`logQueryError(err, sql, duration, opts)` receives almost the same arguments like `logQuery()` with an extra first arugment `err`. This method only gets called when the query fails to be carried out in database, mostly due to syntax error, validation error, or other constraints.
+
+| name | type | description |
+|-----|-----|------|
+| `err` | `Error` | related error |
+
+## `logMigration`
+
+When performing migration tasks, besides the default `logQuery()` or `logQueryError()`, there is also `logMigration(name)` to log the related migration task.
+
+## `hideKeys`
+
+We can use the `hideKeys` option to refrain the values of certain columns from being printed.
+
+```js
+const realm = new Realm({
+  logging: {
+    hideKeys: [ 'users.password', 'docs.content' ],
+  },
+});
+```
+
+The SQL with corresponding column values hidden is like below:
+
+```sql
+INSERT INTO users (name, password) VALUES ('John', '***');
+```

docs/setup/egg.md

@@ -1,9 +1,9 @@
 ---
 layout: en
-title: Setup Leoric in Egg Applications
+title: Setup with Egg / Chair / Midway
 ---
 
-To reduce the effort to setup Leoric in Egg applications, a specific Egg plugin called [egg-orm](https://github.com/eggjs/egg-orm) is provided.
+To reduce the effort to setup Leoric in Egg applications, a specific Egg plugin called [egg-orm](https://github.com/eggjs/egg-orm) is provided. Those frameworks that are built on top of Egg, such as Chair and [Midway](https://midwayjs.org/), can all be supported with [egg-orm](https://github.com/eggjs/egg-orm) as well.
 
 ## Table of Contents
 {:.no_toc}
@@ -41,6 +41,25 @@ module.exports = function(app) {
 }
 ```
 
+Or even better, define models in `app/model` with `class` syntax like below:
+
+```js
+// app/model/user.js
+module.exports = function(app) {
+  const { Bone } = app.model;
+  const { STRING } = app.model.DataTypes;
+
+  return class User extends Bone {
+    static table = 'users'
+    static attributes = {
+      name: STRING,
+      password: STRING,
+      avatar: STRING(2048),
+    }
+  };
+}
+```
+
 then consume them in controllers (or services) in following fashion:
 
 ```js

docs/setup/express.md

@@ -1,6 +1,6 @@
 ---
 layout: en
-title: Setup Leoric in Express
+title: Setup with Express
 ---
 
 ## Table of Contents

docs/setup/index.md

@@ -0,0 +1,7 @@
+---
+layout: en
+title: Setup
+---
+
+- [Setup with Egg]({{ '/setup/egg' | relative_url }})
+- [Setup with Express]({{ '/setup/express' | relative_url }})