ch1-1 new connections

zh/java language support.md

@@ -0,0 +1,339 @@
+因为和 MySQL 保持良好的兼容，TiDB 不需要使用专用的语言驱动。在本节中，主要介绍常见的开发语言和框架如何连接 TiDB 数据库。
+
+## 使用 JDBC 连接 TiDB 数据库
+利用 JDBC 连接 TiDB 时，连接方式与 MySQL 相同，以下是一个简单示例。
+
+```command
+package com.pingcap.test;
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.util.Properties;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.atomic.AtomicLong;
+public class SingleMixEngine {
+  public static void main(String[] args) throws Exception {
+    Class.forName("com.mysql.jdbc.Driver");
+    Properties props = new Properties();
+    props.setProperty("user", "pingcap");
+    props.setProperty("password", "pingcap");
+    SingleMixEngine eng = new SingleMixEngine();
+    eng.execute(props,"jdbc:mysql://192.168.58.51:8066/testdb");
+  }
+  final AtomicLong tmAl = new AtomicLong();
+  final String table="news_table";
+  public void execute(Properties props,String url) {
+    CountDownLatch cdl = new CountDownLatch(1);
+    long start = System.currentTimeMillis();
+    for (int i = 0; i < 1; i++) {
+      TestThread insertThread = new TestThread(props,cdl, url);
+      Thread t = new Thread(insertThread);
+      t.start();
+      System.out.println("Test start");
+    }
+    try {
+      cdl.await();
+      long end = System.currentTimeMillis();
+      System.out.println("Total cost:" + (end-start) + "ms");
+    } catch (Exception e) {
+      e.printStackTrace();
+    }
+  }
+
+  class TestThread implements Runnable {
+    Properties props;
+    private CountDownLatch countDownLatch;
+    String url;
+    public TestThread(Properties props,CountDownLatch cdl,String url) {
+      this.props = props;
+      this.countDownLatch = cdl;
+      this.url = url;
+    }
+    public void run() {
+      Connection connection = null;
+      PreparedStatement ps = null;
+      Statement st = null;
+      try {
+        connection = DriverManager.getConnection(url,props);
+        connection.setAutoCommit(true);
+        st = connection.createStatement();
+        String sql = "drop table if exists " + table;
+        System.out.println("SQL:\n\t"+sql);
+        st.execute(sql);
+
+        sql = "create table " + table + "(id int,title varchar(20))";
+        System.out.println("SQL:\n\t" + sql);
+        st.execute(sql);
+
+        sql = "insert into " + table + " (id,title) values(?,?)";
+        System.out.println("SQL:\n\t"+ sql);
+        ps = connection.prepareStatement(sql);
+        for (int i = 1; i <= 3; i++) {
+          ps.setInt(1,i);
+          ps.setString(2, "测试"+i);
+          ps.execute();
+          System.out.println("Insert data:\t"+i+","+"测试"+i);
+        }
+
+        sql = "select * from " + table + " order by id";
+        System.out.println("SQL:\n\t"+ sql);
+        ResultSet rs = st.executeQuery(sql);
+        int colcount = rs.getMetaData().getColumnCount();
+        System.out.println("Current Data:");
+        while(rs.next()){
+        for(int i=1;i<=colcount;i++){
+          System.out.print("\t"+rs.getString(i));
+        }
+        System.out.println();
+      }
+
+        sql = "update " + table + " set title='test1' where id=1";
+        System.out.println("SQL:\n\t"+ sql);
+        st.execute(sql);
+        sql = "select * from " + table + " order by id";
+        rs = st.executeQuery(sql);
+        System.out.println("Current Data:");
+        while(rs.next()){
+          for(int i=1;i<=colcount;i++){
+            System.out.print("\t"+rs.getString(i));
+          }
+          System.out.println();
+        }
+
+        sql = "delete from " + table + " where id=2";
+        System.out.println("SQL:\n\t"+ sql);
+        st.execute(sql);
+        sql = "select * from " + table + " order by id";
+        rs = st.executeQuery(sql);
+        System.out.println("Current Data:");
+        while(rs.next()){
+          for(int i=1;i<=colcount;i++){
+            System.out.print("\t"+rs.getString(i));
+          }
+          System.out.println();
+        }
+
+        sql = "create index idx_1 on " + table + "(title)";
+        System.out.println("SQL:\n\t"+ sql);
+        st.execute(sql);
+
+        sql = "drop index idx_1 on " + table;
+        System.out.println("SQL:\n\t"+ sql);
+        st.execute(sql);
+      } catch (Exception e) {
+        e.printStackTrace();
+      } finally {
+        if (ps != null)
+          try {
+            ps.close();
+          } catch (SQLException e1) {
+            e1.printStackTrace();
+          }
+        if (connection != null)
+          try {
+            connection.close();
+          } catch (SQLException e1) {
+                    e1.printStackTrace();
+          }
+        this.countDownLatch.countDown();
+      }}}}
+```
+
+下文以 BenchmarkSQL 压测工具添加连接 TiDB 功能为例，介绍 Java 程序添加连接 TiDB 数据库的大致步骤。
+
+### 添加 MySQL JDBC 驱动
+添加 mysql-connector-java-8.0.13.jar 驱动文件到 lib/mysql/ 目录下。
+建议使用  5.1.36 版本或以上的驱动程序文件。
+
+### 程序中添加 MySQL 的驱动支持
+在 run/funcs.sh 文件中的 function setCP() 中，添加如下的驱动描述
+
+```command
+	mysql)
+	    cp="../lib/mysql/*:../lib/*"
+	    ;;
+```
+
+### 配置连接属性
+在 run/props.mysql 或类似的连接参数文件中，添加如下的连接信息。
+
+```command
+db=mysql
+driver=com.mysql.jdbc.Driver
+conn=jdbc:mysql://localhost:3306/tpcc?useSSL=false&useServerPrepStmts=true&useConfigs=maxPerformance
+user=root
+password=
+```
+
+### 程序中添加其他的压测业务支持内容
+其他的修改属于添加对 MySQL 的压测功能的支持，如语法适配、功能特性适配等，以与添加连接的例子无关。
+关于 BenchmarkSQL 压测工具添加对 TiDB 的完整支持内容请参阅：
+https://github.com/pingcap/benchmarksql/compare/5.0...5.0-mysql-support?expand=1
+https://github.com/pingcap/benchmarksql/compare/5.0...5.0-mysql-support-opt-2.1?expand=1
+
+## 使用 Java 开发框架连接 TiDB 数据库
+TiDB 兼容各种开发工具，开发框架和应用接口等，利用软件生态中大量的成熟工具降低了业务开发和运维团队的学习和使用成本，部分框架适配如下:
+### 与 ibatis 适配
+利用 ibatis 连接 TiDB 时，连接方式与 MySQL 相同，以下是一个简单示例。
+#### jdbc配置：
+
+```command
+jdbc.driverClass=com.mysql.jdbc.Driver
+jdbc.jdbcUrl=jdbc:mysql://192.168.58.51:8066/TESTDB?useUnicode=true&characterEncoding=utf-8
+jdbc.user=root
+jdbc.password=123456
+```
+
+#### 映射文件配置：
+
+```command
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
+"http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="com.mapper.UserMapper">
+    <insert id="saveUser" parameterType="com.bean.User">
+    insert into user(id,name,phone,birthday)
+    values (0,#{name},#{phone},#{birthday})
+    <selectKey keyProperty="id" order="after" resultType="int">
+         select last_insert_id() as id
+    </selectKey>
+    </insert>
+    <delete id="deleteUserById" parameterType="java.lang.String">
+    delete from user where id=#{id}
+    </delete>
+    <update id="updateUser" parameterType="com.bean.User">
+    update user set name=#{name}, phone=#{phone}, 
+    birthday=#{birthday} where id=#{id}
+    </update>
+    <update id="updateUsers">
+    /*!mycat: sql=select * from user;*/update users set usercount=(select count(*) from user),ts=now()
+    </update>
+    <select id="getUserById" parameterType="java.lang.String" resultType="com.bean.User">
+    select * from user where id=#{id}
+    </select>
+    <select id="getUsers" resultType="com.bean.User">
+    select * from user
+    </select>
+</mapper>
+```
+语句select last_insert_id() as id可用来获取新写入记录的ID。
+updateUsers方法用到了 TiDB的注解，由于ibatis中的符号#具有特殊含义，因此注解中不能含有#。
+
+### 与 hibernate 适配
+利用hibernate连接TiDB时，连接方式与MySQL相同，以下是一个简单示例。
+hibernate.cfg.xml：
+
+```command
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE hibernate-configuration PUBLIC
+  "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
+  "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
+<hibernate-configuration>
+  <session-factory>
+    <property name="hibernate.connection.driver_class">
+      com.mysql.jdbc.Driver
+    </property>
+    <property name="hibernate.connection.url">
+jdbc:mysql://192.168.58.51:8066/testdb?useUnicode=true&amp;characterEncoding=utf-8
+    </property>
+    <property name="hibernate.connection.username">
+      root
+    </property>
+    <property name="hibernate.connection.password">
+      123456
+    </property>
+    <property name="hibernate.dialect">
+      org.hibernate.dialect.MySQLInnoDBDialect
+    </property>
+    <property name="hibernate.format_sql">
+      true
+    </property>
+    <property name="hibernate.hbm2ddl.auto">
+      update
+    </property>
+    <mapping resource="com/pingcap/test/News.hbm.xml"/>
+  </session-factory>
+</hibernate-configuration>
+```
+
+News.hbm.xml：
+
+```command
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE hibernate-mapping PUBLIC 
+  "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
+  "http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">
+<hibernate-mapping>
+  <class name="com.pingcap.test.News" table="news_table">
+    <id name="id" type="java.lang.Integer">
+      <column name="id" />
+    </id>
+    <property name="title" type="java.lang.String">
+      <column name="title" />
+    </property>
+    <property name="content" type="java.lang.String">
+      <column name="content" />
+    </property>
+  </class>
+</hibernate-mapping>
+```
+
+News.java:
+
+```command
+package com.pingcap.test;
+public class News {
+  private Integer id;
+  private String title;
+  private String content;
+  public Integer getId() {
+    return id;
+    }
+  public void setId(Integer id) {
+    this.id = id;
+  }
+  public String getTitle() {
+    return title;
+  }
+  public void setTitle(String title) {
+    this.title = title;
+  }
+  public String getContent() {
+    return content;
+  }
+  public void setContent(String content) {
+    this.content = content;
+  }
+}
+```
+
+NewsManager.java：
+
+```command
+package com.pingcap.test;
+import org.hibernate.Session;
+import org.hibernate.SessionFactory;
+import org.hibernate.Transaction;
+import org.hibernate.cfg.Configuration;
+public class NewsManager {
+  public static void main(String[] args) throws Exception {
+    Configuration config = new Configuration().configure();
+    SessionFactory factory = config.buildSessionFactory();
+    Session session = factory.openSession();
+    Transaction transaction = session.beginTransaction();
+    News news = new News();
+    news.setId(10);
+    news.setTitle("UShard示例");
+    news.setContent("Hibernate 连接UShard的第一个例子");
+    session.save(news);
+    transaction.commit();
+    session.close();
+    factory.close();
+    }
+}
+```
+
+因为 Hibernate 无法控制 SQL 的生成，无法实现对查询 SQL 的优化，大数量下可能会出现性能问题，不建议使用 Hibernate。

zh/new_connections.md

@@ -0,0 +1,122 @@
+
+TiDB 兼容MySQL 协议、常用的功能及语法，可以使用支持 MySQL 的命令行和图形客户端程序连接 TiDB 数据库。
+
+## 安装 MariaDB 分支的 MySQL 客户端
+在 Redhat Enterprise Linux 7 操作系统或其兼容发行版中，默认包含由社区维护的 MariaDB 分支的 MySQL。以 RHEL 7.6 版本为例，内含 MariaDB 5.5。在操作系统 REPO 源配置正确的情况下，通过 yum 命令快速安装 mariadb 客户端，再通过 mysql 客户端连接 TiDB。
+
+{{< copyable "command" >}}
+
+```command
+yum install -y mysql
+mysql -uroot -h172.16.4.66 -P4000 -prootpassword --comments
+```
+
+注意：
+MySQL 命令行客户端在 5.7.7 版本之前默认清除 Optimizer Hints。如果需要在这些早期版本的客户端中使用 Hint 语法，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments。 
+
+通过 --help 子命令也可以看到具体的版本信息。
+
+{{< copyable "command" >}}
+
+```command
+mysql --help
+```
+
+```
+mysql  Ver 15.1 Distrib 5.5.65-MariaDB, for Linux (x86_64) using readline 5.1
+Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
+```
+
+## 安装 Oracle 的 MySQL 5.7 客户端
+通过配置 Oracle 官方的 REPO 源，在 Redhat Enterprise Linux 7 操作系统或兼容发行版中可以通过 yum 命令快速安装 mariadb 客户端，再通过 mysql 客户端连接 TiDB。
+
+注意：
+从 MySQL 8.0.4开始，MySQL 8.0 的默认身份验证方式改用 caching_sha2_password 验证，与 TiDB 不兼容，需要使用 5.7 版本的客户端。
+
+{{< copyable "command" >}}
+
+```command
+vi /etc/yum.repos.d/mysql-community.repo
+```
+
+```
+[mysql57-community]
+name=MySQL 5.7 Community Server
+baseurl=http://repo.mysql.com/yum/mysql-5.7-community/el/6/$basearch/
+enabled=1
+gpgcheck=0
+```
+
+{{< copyable "command" >}}
+
+```command
+yum repolist all | grep mysql
+```
+
+```
+mysql57-community/x86_64      MySQL 5.7 Community Server            启用:    414
+```
+
+{{< copyable "command" >}}
+
+```command
+yum install mysql
+```
+
+通过 --help 子命令也可以看到具体的版本信息。
+
+{{< copyable "command" >}}
+
+```command
+mysql --help
+```
+
+```
+mysql  Ver 14.14 Distrib 5.7.31, for Linux (x86_64) using  EditLine wrapper
+Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
+
+Oracle is a registered trademark of Oracle Corporation and/or its
+affiliates. Other names may be trademarks of their respective
+```
+
+## 安装 Navicat 图形化工具
+Navicat 是一款强大的图形化管理数据库工具，在 MySQL DBA 群体中较为流行，产品发展较快，最新的 15 版本支持 MySQL 8.0。Navicat 是一款商业产品，官方提供 14 天下载试用，并支持订阅销售方式。
+
+- Navicat 程序主界面连接菜单
+
+![连接菜单](/media/ch1-1-navicat1.png)
+
+- Navicat 新建连接对话框
+
+![连接对话框](/media/ch1-1-navicat2.png)
+
+- Navicat 连接成功操作界面
+
+![成功操作界面](/media/ch1-1-navicat3.png)
+
+- Navicat 活动数据库下拉菜单
+
+![下拉菜单](/media/ch1-1-navicat4.png)
+
+- Navicat 命令语句输入框
+
+![语句对话框](/media/ch1-1-navicat5.png)
+
+## 安装 DBeaver 图形化工具
+DBeaver 是一款为开发人员和数据库管理员准备的通用数据库工具，支持多种主流的数据库，属于开源产品，在金融等行业中流行较广。
+
+- DBeaver 程序主界面连接菜单
+
+![连接菜单](/media/ch1-1-dbeaver1.png)
+
+- DBeaver 新建连接对话框
+
+![连接对话框](/media/ch1-1-dbeaver2.png)
+
+- DBeaver 连接成功操作界面
+
+![成功操作界面](/media/ch1-1-dbeaver3.png)
+
+- DBeaver 命令语句输入框
+
+![下拉菜单](/media/ch1-1-dbeaver4.png)