From 9d079f7936373d22b417f278187186d939cf4054 Mon Sep 17 00:00:00 2001 From: Yiran Date: Thu, 12 Sep 2024 15:03:26 +0800 Subject: [PATCH] programming languages in SQL tools --- docs/reference/sql-tools.md | 294 ++++++++++++++++++ .../ingest-data/for-iot/grpc-sdks/go.md | 115 +------ .../ingest-data/for-iot/grpc-sdks/java.md | 123 -------- .../ingest-data/for-iot/grpc-sdks/template.md | 33 -- .../current/reference/sql-tools.md | 3 + sidebars.ts | 1 + 6 files changed, 299 insertions(+), 270 deletions(-) create mode 100644 docs/reference/sql-tools.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/reference/sql-tools.md diff --git a/docs/reference/sql-tools.md b/docs/reference/sql-tools.md new file mode 100644 index 000000000..8626e1ef2 --- /dev/null +++ b/docs/reference/sql-tools.md @@ -0,0 +1,294 @@ +# SQL Tools + +GreptimeDB uses SQL as main query language, so it supports most famous SQL tools. +This document guides you on how to use SQL tools with GreptimeDB. + +## Programming languages + +It is recommend to use mature SQL drivers to query data. + +### Recommended libraries + + + + Java database connectivity (JDBC) is the JavaSoft specification of a standard application programming interface (API) that allows Java programs to access database management systems. + + Many databases, such as MySQL or PostgreSQL, have implemented their own drivers based on the JDBC API. + Since GreptimeDB supports [multiple protocols](/user-guide/protocols/overview.md), we use MySQL as an example to demonstrate how to use JDBC. + If you want to use other protocols, just replace the MySQL driver with the corresponding driver. + + + It is recommend to using the [GORM](https://gorm.io/) library, which is popular and developer-friendly. + + + + +### Installation + + + + If you are using [Maven](https://maven.apache.org/), add the following to your pom.xml + dependencies list: + + ```xml + + mysql + mysql-connector-java + 8.0.33 + + ``` + + + + Use the following command to install the GORM library: + + ```shell + go get -u gorm.io/gorm + ``` + + and install the MySQL driver as the example: + + ```shell + go get -u gorm.io/driver/mysql + ``` + + Then import the libraries in your code: + + ```go + import ( + "gorm.io/gorm" + "gorm.io/driver/mysql" + ) + ``` + + + +### Connect to database + +The following example shows how to connect to GreptimeDB: + + + + + Here we will use MySQL as an example to demonstrate how to connect to GreptimeDB. + + ```java + public static Connection getConnection() throws IOException, ClassNotFoundException, SQLException { + Properties prop = new Properties(); + prop.load(QueryJDBC.class.getResourceAsStream("/db-connection.properties")); + + String dbName = (String) prop.get("db.database-driver"); + + String dbConnUrl = (String) prop.get("db.url"); + String dbUserName = (String) prop.get("db.username"); + String dbPassword = (String) prop.get("db.password"); + + Class.forName(dbName); + Connection dbConn = DriverManager.getConnection(dbConnUrl, dbUserName, dbPassword); + + return Objects.requireNonNull(dbConn, "Failed to make connection!"); + } + + ``` + + You need a properties file to store the DB connection information. Place it in the Resources directory and name it `db-connection.properties`. The file content is as follows: + + ```txt + # DataSource + db.database-driver=com.mysql.cj.jdbc.Driver + db.url=jdbc:mysql://localhost:4002/public + db.username= + db.password= + ``` + + Or you can just get the file from [here](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/ingester-example/src/main/resources/db-connection.properties). + + + + + ```go + type Mysql struct { + Host string + Port string + User string + Password string + Database string + + DB *gorm.DB + } + + m := &Mysql{ + Host: "127.0.0.1", + Port: "4002", // default port for MySQL + User: "username", + Password: "password", + Database: "public", + } + + dsn := fmt.Sprintf("tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local", + m.Host, m.Port, m.Database) + dsn = fmt.Sprintf("%s:%s@%s", m.User, m.Password, dsn) + db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{}) + if err != nil { + //error handling + } + m.DB = db + ``` + + + + +#### Time zone + + + + Set the JDBC time zone by setting URL parameters: + + ```txt + jdbc:mysql://127.0.0.1:4002?connectionTimeZone=Asia/Shanghai&forceConnectionTimeZoneToSession=true + ``` + + * `connectionTimeZone={LOCAL|SERVER|user-defined-time-zone}` specifies the connection time zone. + * `forceConnectionTimeZoneToSession=true` makes the session `time_zone` variable to be set to the value specified in `connectionTimeZone`. + + + Set the time zone to the DSN. For example, set the time zone to `Asia/Shanghai`: + + ```go + dsn := fmt.Sprintf("tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local&time_zone=%27Asia%2FShanghai%27", + m.Host, m.Port, m.Database) + ``` + + For more information, see the [MySQL Driver Documentation](https://github.com/go-sql-driver/mysql?tab=readme-ov-file#system-variables). + + + + +### Raw SQL + +It is recommend using raw SQL to experience the full features of GreptimeDB. +The following example shows how to use raw SQL to query data. + + + + + ```java + try (Connection conn = getConnection()) { + Statement statement = conn.createStatement(); + + // DESC table; + ResultSet rs = statement.executeQuery("DESC cpu_metric"); + LOG.info("Column | Type | Key | Null | Default | Semantic Type "); + while (rs.next()) { + LOG.info("{} | {} | {} | {} | {} | {}", + rs.getString(1), + rs.getString(2), + rs.getString(3), + rs.getString(4), + rs.getString(5), + rs.getString(6)); + } + + // SELECT COUNT(*) FROM cpu_metric; + rs = statement.executeQuery("SELECT COUNT(*) FROM cpu_metric"); + while (rs.next()) { + LOG.info("Count: {}", rs.getInt(1)); + } + + // SELECT * FROM cpu_metric ORDER BY ts DESC LIMIT 5; + rs = statement.executeQuery("SELECT * FROM cpu_metric ORDER BY ts DESC LIMIT 5"); + LOG.info("host | ts | cpu_user | cpu_sys"); + while (rs.next()) { + LOG.info("{} | {} | {} | {}", + rs.getString("host"), + rs.getTimestamp("ts"), + rs.getDouble("cpu_user"), + rs.getDouble("cpu_sys")); + } + } + + ``` + + For the complete code of the demo, please refer to [here](https://github.com/GreptimeTeam/greptimedb-ingester-java/blob/main/ingester-example/src/main/java/io/greptime/QueryJDBC.java). + + + + + + The following code declares a GORM object model: + + ```go + type CpuMetric struct { + Host string `gorm:"column:host;primaryKey"` + Ts time.Time `gorm:"column:ts;primaryKey"` + CpuUser float64 `gorm:"column:cpu_user"` + CpuSys float64 `gorm:"column:cpu_sys"` + } + ``` + + If you are using the [ORM API](#orm-api) to insert data, you can declare the model with both GORM and Greptime tags. + + ```go + type CpuMetric struct { + Host string `gorm:"column:host;primaryKey" greptime:"tag;column:host;type:string"` + Ts time.Time `gorm:"column:ts;primaryKey" greptime:"timestamp;column:ts;type:timestamp;precision:millisecond"` + CpuUser float64 `gorm:"column:cpu_user" greptime:"field;column:cpu_user;type:float64"` + CpuSys float64 `gorm:"column:cpu_sys" greptime:"field;column:cpu_sys;type:float64"` + } + ``` + + Declare the table name as follows: + + ```go + func (CpuMetric) TableName() string { + return "cpu_metric" + } + ``` + + Use raw SQL to query data: + + ```go + var cpuMetric CpuMetric + db.Raw("SELECT * FROM cpu_metric LIMIT 10").Scan(&result) + + ``` + + + + +### Query library reference + +For more information about how to use the query library, please see the documentation of the corresponding library: + + + + - [JDBC Online Tutorials](https://docs.oracle.com/javase/tutorial/jdbc/basics/index.html) + + + - [GORM](https://gorm.io/docs/index.html) + + + +## Command line tools + +### MySQL + +You can use `mysql` command line tool to connect to GreptimeDB MySQL server. +Please refer to the [MySQL protocol](/user-guide/protocols/mysql.md) document for the connection information. + +After you connect to the MySQL server, you can use all [GreptimeDB SQL commands](/reference/sql/overview.md) to interact with the database. + +### PostgreSQL + +You can use `psql` command line tool to connect to GreptimeDB PostgreSQL server. +Please refer to the [PostgreSQL protocol](/user-guide/protocols/postgresql.md) document for the connection information. + +After you connect to the PostgreSQL server, you can use all [GreptimeDB SQL commands](/reference/sql/overview.md) to interact with the database. + +## Greptime dashboard + +## GUI tools + +### Navicat + +### DBeaver diff --git a/docs/user-guide/ingest-data/for-iot/grpc-sdks/go.md b/docs/user-guide/ingest-data/for-iot/grpc-sdks/go.md index 0828fe889..b3b2010ca 100644 --- a/docs/user-guide/ingest-data/for-iot/grpc-sdks/go.md +++ b/docs/user-guide/ingest-data/for-iot/grpc-sdks/go.md @@ -223,117 +223,4 @@ affected, err := cli.CloseStream(ctx) - - - -
- -Use the following command to install the GORM library: - -```shell -go get -u gorm.io/gorm -``` - -and install the MySQL driver as the example: - -```shell -go get -u gorm.io/driver/mysql -``` - -Then import the libraries in your code: - -```go -import ( - "gorm.io/gorm" - "gorm.io/driver/mysql" -) -``` - -
- -
- -```go -type Mysql struct { - Host string - Port string - User string - Password string - Database string - - DB *gorm.DB -} - -m := &Mysql{ - Host: "127.0.0.1", - Port: "4002", // default port for MySQL - User: "username", - Password: "password", - Database: "public", -} - -dsn := fmt.Sprintf("tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local", - m.Host, m.Port, m.Database) -dsn = fmt.Sprintf("%s:%s@%s", m.User, m.Password, dsn) -db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{}) -if err != nil { - //error handling -} -m.DB = db -``` -
- -
- -The following code declares a GORM object model: - -```go -type CpuMetric struct { - Host string `gorm:"column:host;primaryKey"` - Ts time.Time `gorm:"column:ts;primaryKey"` - CpuUser float64 `gorm:"column:cpu_user"` - CpuSys float64 `gorm:"column:cpu_sys"` -} -``` - -If you are using the [ORM API](#orm-api) to insert data, you can declare the model with both GORM and Greptime tags. - -```go -type CpuMetric struct { - Host string `gorm:"column:host;primaryKey" greptime:"tag;column:host;type:string"` - Ts time.Time `gorm:"column:ts;primaryKey" greptime:"timestamp;column:ts;type:timestamp;precision:millisecond"` - CpuUser float64 `gorm:"column:cpu_user" greptime:"field;column:cpu_user;type:float64"` - CpuSys float64 `gorm:"column:cpu_sys" greptime:"field;column:cpu_sys;type:float64"` -} -``` - -Declare the table name as follows: - -```go -func (CpuMetric) TableName() string { - return "cpu_metric" -} -``` - -Use raw SQL to query data: - -```go -var cpuMetric CpuMetric -db.Raw("SELECT * FROM cpu_metric LIMIT 10").Scan(&result) - -``` - -
- - - - - \ No newline at end of file + diff --git a/docs/user-guide/ingest-data/for-iot/grpc-sdks/java.md b/docs/user-guide/ingest-data/for-iot/grpc-sdks/java.md index a479b2c68..c3ba011e4 100644 --- a/docs/user-guide/ingest-data/for-iot/grpc-sdks/java.md +++ b/docs/user-guide/ingest-data/for-iot/grpc-sdks/java.md @@ -319,127 +319,4 @@ Please refer to [Metrics & Display](https://github.com/GreptimeTeam/greptimedb-i - - - - - - - - diff --git a/docs/user-guide/ingest-data/for-iot/grpc-sdks/template.md b/docs/user-guide/ingest-data/for-iot/grpc-sdks/template.md index 01e020ab6..7f53dd4c7 100644 --- a/docs/user-guide/ingest-data/for-iot/grpc-sdks/template.md +++ b/docs/user-guide/ingest-data/for-iot/grpc-sdks/template.md @@ -93,36 +93,3 @@ Streaming insert is useful when you want to insert a large amount of data such a ## Ingester library reference - - - diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql-tools.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql-tools.md new file mode 100644 index 000000000..aba94fa48 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql-tools.md @@ -0,0 +1,3 @@ +# SQL 工具 + + diff --git a/sidebars.ts b/sidebars.ts index ee78b5c5c..a268160dd 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -281,6 +281,7 @@ const sidebars: SidebarsConfig = { label: 'Reference', items: [ 'reference/command-lines', + 'reference/sql-tools', { type: 'category', label: 'SQL',