diff --git a/website/translated_docs/en-US/api.md b/website/translated_docs/en-US/api.md new file mode 100644 index 0000000..0a111da --- /dev/null +++ b/website/translated_docs/en-US/api.md @@ -0,0 +1,5 @@ +--- +id: api +title: '👩🏻‍💻 CovenantSQL API' +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/en-US/cql.md b/website/translated_docs/en-US/cql.md new file mode 100644 index 0000000..be990f0 --- /dev/null +++ b/website/translated_docs/en-US/cql.md @@ -0,0 +1,210 @@ +--- +id: cql +title: '🖥️ CQL 命令行工具' +--- +## 简介 + +本文将介绍如何使用 `cql` 进行查询、转账和数据库权限管理。在使用 `cql` 前请先确认已接入 [CovenantSQL TestNet](quickstart) 或者在本地使用 [Docker 一键部署](development)的网络, 并将 `cql` 可执行文件保存在 `PATH` 目录。 + +### 配置文件 + +`cql`命令依赖配置文件`config.yaml`和私钥文件`private.key`。这两个文件如果使用`cql generate config`命令生成，会默认放在`~/.cql/`目录下。在此目录下时，`cql`所有子命令的`-config`参数均可以省略不填写。 + +### Master key + +`private.key`文件在生成时需要输入密码，`cql`命令会自动请求输入master key (密码)。 如果想在脚本中使用，可以在子命令后面增加`-password your_master_key`，空密码时用`-no-password`参数。 + +## 查询余额 + +查询余额的命令是：`cql wallet -balance `。其中`token_type`设置为`all`时将返回用户账户中 `Particle` 与 `Wave` 的数量，其他关键词将返回用户账户中特定 `token_type` 的 token 数量。目前系统支持的 `token_type` 有： + +- `Particle` +- `Wave` +- `Bitcoin` +- `Ether` +- `EOS` + +查看默认余额： + +```bash +cql wallet -balance all -config conf/config.yaml +``` + +输出： + + INFO[0000] Particle balance is: 10000000000000000000 + INFO[0000] Wave balance is: 10000000000000000000 + + +查看 Particle 余额： + +```bash +cql wallet -balance Particle -config conf/config.yaml +``` + +输出： + + INFO[0000] Particle balance is: 10000000000000000000 + + +查看 Bitcoin 余额： + +```bash +cql wallet -balance Bitcoin -config conf/config.yaml +``` + +输出： + + INFO[0000] Bitcoin balance is: 0 + + +## 转账 + +转账操作使用 `cql transfer` 并以 `json` 格式的转账信息为参数。 + +```json +{ + "addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // 收款地址 + "amount":"1000000 Particle" // 转账金额并带上单位 +} +``` + +其中收款地址可以是一个个人钱包地址也可以是一个数据库子链地址。转账至数据库地址时将在该数据库账户上补充付款人的押金与预付款。 + +转账 Particle： + +```bash +cql transfer -config conf/config.yaml '{"addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount":"1000000 Particle"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +转账 Wave： + +```bash +cql transfer -config conf/config.yaml '{"addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount":"1000000 Wave"}' +``` + + INFO[0000] succeed in sending transaction to CovenantSQL + + +查看余额： + +```bash +cql wallet -balance all -config conf/config.yaml +``` + +输出： + + INFO[0000] Particle balance is: 9999999999999000000 + INFO[0000] Wave balance is: 9999999999999000000 + + +注意，`succeed in sending transaction to CovenantSQL` 只说明交易已成功发送至主网，交易能否成功、何时成功需要通过 `cql wallet -balance ` 确定。 + +## 数据库权限管理 + +#### 访问权限 + +CovenantSQL 数据库有三类库级别权限： + +- `Admin` +- `Write` +- `Read` +- `Void` + +其中，`Admin` 可以赋予其他钱包地址数据库的权限（`Admin`、`Write` 或 `Read`）；`Admin` 和 `Write` 可以对数据库进行写操作（`CREATE`, `INSERT` 等）；`Admin` 和 `Read` 可以对数据库进行读操作（`SHOW`, `SELECT` 等）；如果需要设置用户有读写权限但是不能修改其他用户或自己的权限，可以将权限设置为 `Read,Write`；`Void` 是一个特殊的权限，当 `Admin` 想取消某个地址的权限时可以将该地址的权限设置为 `Void`，这样该地址将无法继续读写数据库。创建数据库的地址的权限默认为 `Admin`。若 `Admin` 需要赋予他人权限请使用 `cql grant` 并以 `json` 格式的权限信息为参数： + +```json +{ + "chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", // 需要进行权限变更的数据库地址 + "user":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // 需要赋予权限的钱包地址 + "perm":"Write" // 权限内容 +} +``` + +增加写权限： + +```bash +cql grant -config conf/config.yaml '{"chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","user":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","perm":"Write"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +吊销权限： + +```bash +cql grant -config conf/config.yaml '{"chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","perm":"Void"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +注意，`succeed in sending transaction to CovenantSQL` 只说明交易已成功发送至主网，交易成功与否请通过查询数据库确认。 + +为数据库添加新的账户权限后账户需补充押金与预付款才能进行正常查询。押金与预付款最小值的计算公式：`gas_price*number_of_miner*120000`。 + +使用新账户给数据库充值： + +```bash +cql transfer -config new_user_config/config.yaml '{"addr":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","amount":"90000000 Particle"}' +``` + +#### SQL 白名单 + +CovenantSQL 还支持给用户设置可执行的 SQL 白名单，可以限定用户以指定的 SQL Pattern 和可配的 Query 参数来访问数据库。在指定语句白名单的功能支持下，可以提高数据库的安全性，避免被单语句拖库或执行不正确的删除货更新操作。 + +增加白名单： + +```shell +cql -config conf/config.yaml -update-perm ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": { + "patterns": [ + "SELECT COUNT(1) FROM a", + "SELECT * FROM a WHERE id = ? LIMIT 1" + ], + "role": "Read" + } +} +' +``` + +*白名单功能是基于数据库权限的一个扩展，且当前不支持增量的白名单更新，在设置白名单时需要写明所有授权该用户使用的语句，以及该用户对数据库的访问权限* + +设置完成后，用户将只能执行 `SELECT COUNT(1) FROM a` 或 `SELECT * FROM a WHERE id = ? LIMIT 1` 的语句（语句内容严格匹配，使用 `select COUNT(1) FROM a` 或 `SELECT COUNT(1) FROM a` 也不可以）；其中 第二条语句支持用户提供一个参数，以支持查询不同记录的目的。最终可以实现限定用户访问 `表 a`，并一次只能查询 `表 a` 中的一条数据或查询 `表 a`的 总数据量。 + +去掉白名单限制： + +```shell +cql -config conf/config.yaml -update-perm ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": { + "patterns": nil, + "role": "Read" + } +} +' +# or +cql -config conf/config.yaml -update-perm ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": "Read" +} +' +``` + +将 `pattern` 设置为 `nil` 或直接设置用户权限，都可以将用户的白名单限制去掉，设置回可以查询所有内容的读权限。 \ No newline at end of file diff --git a/website/translated_docs/en-US/deployment.md b/website/translated_docs/en-US/deployment.md new file mode 100644 index 0000000..3ef403b --- /dev/null +++ b/website/translated_docs/en-US/deployment.md @@ -0,0 +1,161 @@ +--- +id: deployment +title: '🐳 Docker 一键部署' +--- +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 下载项目 + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行 + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +存为环境变量 + +### 启动 Docker 容器 + +现在有两种方式启动 CovenantSQL 容器： + +1. 使用 Docker Hub 上的公共镜像 +2. 构建 CovenantSQL Docker 镜像 + +> 我们推荐普通用户使用第一种方式测试 CovenantSQL，第二种仅用于体验最新的开发中的特性。 + +#### 1. 使用 Docker Hub 上的公共镜像 + +然后直接启动： + +```bash +make start +``` + +#### 2. 构建 CovenantSQL Docker 镜像 + +执行以下的命令在本地运行 CovenantSQL + +```bash +make docker # 从头编译新的镜像 +make start +``` + +### 检查运行状态 + +检查容器状态： + +```bash +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp +covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp +covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp +covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp +covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp +``` + +## 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +docker exec -it covenantsql_adapter /app/cql console -config /app/config.yaml -no-password -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +### SQLChain Observer + +镜像中的 Observer 角色使用了和 mysql-adapter 镜像中相同的 private.key ，故可以免去新账户授权和转账的过程制。 + +（关于权限管理的详细说明请参考[数据库权限管理](cql.md#数据库权限管理)） + +#### 在浏览器使用 SQLChain Observer + +我们在 `127.0.0.1:11108` 端口提供了一个 SQLChain 的 Observer 可以看到 SQL 语句在链上的情况。 \ No newline at end of file diff --git a/website/translated_docs/en-US/intro.md b/website/translated_docs/en-US/intro.md new file mode 100644 index 0000000..e5f0b33 --- /dev/null +++ b/website/translated_docs/en-US/intro.md @@ -0,0 +1,72 @@ +--- +id: intro +title: CovenantSQL 介绍 +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL is a GDPR-compliant SQL database running on Open Internet without central coordination. + +Combining the advantages of the blockchain, sharing economy and distributed database, the user's privacy and ownership of data are guaranteed. + +CovenantSQL has the following features： + +* **SQL Interface**: Supports SQL-92 standard, traditional App almost no modifications can be linked to data. +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是人们的私人钱包，那么 CovenantSQL 就是是人们的去中心化的私密数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密来保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/en-US/native.md b/website/translated_docs/en-US/native.md new file mode 100644 index 0000000..b76bcc8 --- /dev/null +++ b/website/translated_docs/en-US/native.md @@ -0,0 +1,172 @@ +--- +id: native +title: '📦 CovenantSQL Native SDK' +--- +## 用 Golang 使用 CovenantSQL + +### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/en-US/nav.md b/website/translated_docs/en-US/nav.md new file mode 100644 index 0000000..caac5e7 --- /dev/null +++ b/website/translated_docs/en-US/nav.md @@ -0,0 +1,21 @@ +--- +id: nav +title: '📖 使用导航' +--- +## 直接使用测试网 + +[🌏 TestNet 快速开始](./quickstart) + +## 部署私有 CovenantSQL 数据库（搭建私有链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +[🐳 Docker 一键部署](./deployment) + +## 使用 CovenantSQL 开发应用 + +[📦 CovenantSQL SDK](./development) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/en-US/proxy.md b/website/translated_docs/en-US/proxy.md new file mode 100644 index 0000000..3a39291 --- /dev/null +++ b/website/translated_docs/en-US/proxy.md @@ -0,0 +1,110 @@ +--- +id: adapter +title: '📦 CovenantSQL Adapter SDK' +--- +# 通过 Adapter 使用 CovenantSQL + +## 简介 + +`CovenantSQL` 提供了 HTTP/HTTPS Adapter，类似于云数据库， 开发者可以直接用 HTTP 的形式使用 CovenantSQL。 + +## 安装和使用 + +首先，需要确认我们有一个可用的配置和公私钥对，通常我们默认的配置和公私钥对的存储位置为 `~/.cql/` 目录。生成或获取请参考 [QuickStart#创建账号](./quickstart#创建账号) + +### Docker 运行 Adapter + +下面的命令将使用`~/.cql/config.yaml` 和 `~/.cql/private.key` 启动 Adapter，并把端口映射在 `0.0.0.0:11105` + +```bash +export adapter_addr=0.0.0.0:11105 +docker rm -f cql-adapter +docker run -itd \ + --env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --name cql-adapter -p $adapter_addr:4661 \ + covenantsql/covenantsql:testnet -listen 0.0.0.0:4661 +``` + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +docker run -it --rm \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --entrypoint /app/cql covenantsql/covenantsql:testnet \ + -config /app/config.yaml -create 1 +``` + +命令会返回创建的数据库实例的连接串（DSN） + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +## 主流语言 Driver 的使用 + +### NodeJS + +NodeJS 开发者可以通过 [node-covenantsql](https://github.com/CovenantSQL/node-covenantsql) 来与 CovenantSQL Adapter 进行交互。 + +#### 下载安装 + +可以直接通过 `npm` 或者 `yarn` 来安装 `node-covenantsql` + +```bash +npm install --save node-covenantsql +``` + +or + +```bash +yarn add node-covenantsql +``` + +#### 使用 + +在运行本地 Adapter 之后，将 Adapter 的 endpoint 填入 `node-covenantsql` 的 config 之中： + +```javascript +const config = { + endpoint: 'localhost:11105', // local testnet endpoint without https + database: `${DSN}`, // your DB id created by `cql` tools + bypassPem: true // bypass https config +} +``` + +这里 `bypassPem` 为 `true` 表示应用中所有对链上数据库的操作都会经过本地的 Adapter 进行代理，我们默认本地环境是可控，安全的，无需用 HTTPS 来保证这段连接的信道安全，少了证书的繁琐认证，所以成为 `bypassPem`。 + +接着连通之后则可进行链上数据库的增删改查： + +```typescript +const cql from 'node-covenantsql' + +const config = {...} // see above + +cql.createConnection(config).then(async (connection: any) => { + // read + const data1 = await connection.query("select ? + ?", [2.1, 3.2]); + console.log(data1); + + // write + const createTableSQL = ` + CREATE TABLE IF NOT EXISTS contacts (\ + contact_id INTEGER PRIMARY KEY, + first_name TEXT NOT NULL, + last_name TEXT NOT NULL, + email text NOT NULL UNIQUE, + phone text NOT NULL UNIQUE + ); + ` + const status1 = await connection.exec(createTableSQL) + console.log(`exec1 status:`, status1); + + const data2 = await connection.query("show tables;"); + console.log(data2); +}).catch((e: any) => console.log(e)) +``` \ No newline at end of file diff --git a/website/translated_docs/en-US/qna.md b/website/translated_docs/en-US/qna.md new file mode 100644 index 0000000..c910445 --- /dev/null +++ b/website/translated_docs/en-US/qna.md @@ -0,0 +1,5 @@ +--- +id: qna +title: '🙋 常见问题解答' +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/en-US/quandl.md b/website/translated_docs/en-US/quandl.md new file mode 100644 index 0000000..886d950 --- /dev/null +++ b/website/translated_docs/en-US/quandl.md @@ -0,0 +1,297 @@ +--- +id: quandl +title: 基于 Quandl 的金融数据分析 +--- +## 关于 Quandl + +Quandl 是一个针对金融投资行业的大数据平台，其数据来源包括联合国、世界银行、中央银行等公开数据，核心财务数据来自 CLS 集团，Zacks 和 ICE 等，所有的数据源自 500 多家发布商， 是为投资专业人士提供金融，经济和替代数据的首选平台，拥有海量的经济和金融数据。 + +## Quandl 数据索引 + +### CovenantSQL 使用简介 + +首先，我们已基于 Quandl 的开放 API 将数据存放在 CovenantSQL 中，首先应该浏览一下 CovenantSQL 的使用介绍来熟悉一下如何连接并且使用 CovenantSQL。 + +现在由于客户端兼容问题， 请直接使用我们的 HTTP 服务来对 Quandl 数据库进行 query，未来兼容现在的 `cql` 客户端后会第一时间更新此文档。 + +具体通过 HTTP 服务来使用 CovenantSQL 请参考 [Python 驱动文档](https://github.com/CovenantSQL/python-driver/blob/master/README.rst) 和 [NodeJS 驱动文档](https://github.com/CovenantSQL/node-covenantsql/blob/master/README.md) + +所需参数: + + host: 'e.morenodes.com' + port: 11108 + database: '057e55460f501ad071383c95f691293f2f0a7895988e22593669ceeb52a6452a' + + +### 数据使用方法 + +Quandl 数据分为表以及子表两层索引 + +数据库中，表名为`quandl_` + `database_code`为完整表名 + +通过查询表名来查看表的内容 + +具体使用时，需要结合`quandl_updateindex` 这张索引表来使用，（查询索引表时，请务必 limit 小于 10 万，因为全表数据量过大） + +使用时，请使用 where 语句限定`quandlcode`字段来查询表中的子表数据。 + +### 查询示例 + +1. 我们想要查询 欧盟委员会年度宏观经济数据库 的数据，我们找到其第一层索引的 `databasecode` 为`quandl_ameco`，于是，我们可以查询其第二层索引，用以下 SQL 命令行： + + `select * from quandl_updateindex where databasecode like 'ameco' group by quandlcode limit 10000` + +2. 然后通过第三列，我们可以查看`quandlcode`对应的描述 + + 比如 AMECO/ALB_1_0_0_0_AAGE 对应的就是阿尔巴尼亚的进出口相关信息，时间从 1960 到 1988。 + + Average share of imports and exports of goods in world trade excluding intra EU trade; Foreign trade statistics (1960-1998 Former EU-15) - Albania + + 于是，我们可以用以下方式把这个子表给查询出来 + + `select * from quandl_ameco where quandlcode like 'AMECO/ALB_1_0_0_0_AAGE' limit 10000` + +3. 注意：如果内容整列为 null 的，属于表结构本身不存在的字段，可以自行去除。 + +## Quandl 数据 Excel 插件使用说明 + +您可以下载 Quandl 数据 Excel 插件，无须安装，请解压到任意文件夹中。此插件目前仅支持 Office 2010 以及以上版本，office 2007 以及以下版本目前暂不支持。 + +### 配置 Excel 插件 + +解压下载后压缩包，在文件夹中有两个.xll 文件，`ClassLibrary7-AddIn.xll` 以及 `ClassLibrary7-AddIn64.xll` 文件，这两个文件分别对应 32 位的 Excel 与 64 位的 Excel，请根据您的电脑配置使用对应插件。 + +#### 修改 xml 配置 + +每个 `.xll` 文件对应一个 `.config` 的配置文件，也就是 `ClassLibrary7-AddIn.xll.config` 和`ClassLibrary7-AddIn64.xll.config`，为如下 xml 配置： + +```xml + + + + + + + + + +``` + +其中有如下配置需要修改，并保存： + +- certpath: 请填写 `read.data.thunderdb.io.pfx` 证书的绝对路径 + +#### 安装插件 + +有两种办法使用此 Excel 插件 + +1. 直接双击对应的 32 位或 64 位 Excel 的 xll 文件打开 + +![quandl_ext_1](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_1.png) + +如果弹出如上对话框，选择第一个： `仅为本回话启用此加载项`。然后新建一个 Excel 表格，如果在 Excel 的上方选项卡中看到 CovenantSQL，说明插件加载成功。 + +2. 打开 Excel，然后依次选择 `文件 — 选项 — 加载项`，管理选择 Excel 加载项，点击转到然后浏览选择解压后的对应版本的 `.xll` 文件，然后点击 `确定`，在选项卡中如果成功加载出 CovenantSQL 即为成功加载，如下图： + +![quandl_ext_2](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_2.png) + +#### 使用插件 + +选择 CovenantSQL 的选项卡可以看到 Quandl 数据查询，点击 Quandl 数据查询，会弹出一个窗体如下图所示： + +![quandl_ext_3](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_3.png) + +- 其中红色框住的列表部分是一级目录，下方则是所选项的具体描述 + +- 绿色按钮是通过选择的一级目录来查询二级目录。这里查询时间会随着所查询二级目录的大小以及用户自身的网络速度等因素而不同，可能查询时间会超过 1 分钟，请耐心等待。 + +- 黄色部分左边的列表是二级目录，右边的窗体则为列表项所选择的表的描述。 + +- 蓝色部分是导出数据的可选项 + + - Limit Number 是一次导出的最多数据条数，默认为 10000 条，最大值可填写 100000 + - Offset Number 是从数据库的第几条开始导出，因为之前会限定条数，例如我们之前导出了 10000 条数据，但是明显数据还没有导出全部，我们可以使用此功能选择 offset 10000 来从第 10000 条开始导出（注：数据库的计数从 0 开始，所以前 10000 条为 0-9999） + +现在，您即可在 Excel 中方便的调用存在 CovenantSQL 上的 Quandl 数据。 + +## 附件表 + +| DataBase | 名称 | 描述 | +| ------------ | ------------------------ | ------------------------------------------------------------------------------------------- | +| BUNDESBANK | 德意志联邦银行数据仓库 | 有关德国经济，货币和资本市场，公共财政，银行，家庭，欧元区总量，贸易和外债的数据。 | +| URC | 独角兽研究公司数据 | 纽约证券交易所，美国证券交易所和纳斯达克证券交易所的预付和下跌数据。从各种公开来源和报告中值。 | +| DCE | 大连商品交易所数据 | 来自DCE的农业和商品期货，历史跨越了近十年的特定期货。 | +| WFC | 富国银行住房抵押贷款数据 | 该数据库提供富国银行（Wells Fargo Bank）分部Wells Fargo Home Mortgage的抵押贷款购买和再融资利率。 | +| USDAFNS | 美国农业部食品与营养服务项目数据 | 食品和营养服务局为低收入家庭和儿童管理联邦营养援助计划。成本和参与率数据。 | +| LJUBSE | 卢布尔雅那证券交易所数据 | 该数据库包含卢布尔雅那股票交易所指数，总部位于斯洛文尼亚的卢布尔雅那。 | +| TOCOM | 东京商品交易所数据 | 来自东京商品交易所（TOCOM）的农业和商品期货，历史跨越了近十年的特定期货。 | +| WCSC | 世界银行企业积分卡数据 | 该数据库旨在提供世界银行集团在消除极端贫困和促进共同繁荣方面的表现的战略概述。 | +| CMHC | 加拿大住房抵押贷款公司 | CMHC是一家政府所有的公司，为加拿大公民提供经济适用房，并收集价格，建筑和供应等数据。 | +| WGEC | 世界银行全球经济监测商品数据（GEM） | 包含1960年至今的商品价格和指数的数据。 | +| FED | 美联储数据公布 | 美国官方关于货币供应量，利率，抵押贷款，政府财政，银行资产和债务，汇率，工业生产的数据。 | +| WPSD | 世界银行公共部分支出数据 | 由世界银行和国际货币基金组织共同开发的数据，汇集了详细的公共部门政府债务数据。 | +| UGID | 联合国全球指标 | 该数据库提供广泛的全球指标，涵盖人口，公共卫生，就业，贸易，教育，通货膨胀和外债。 | +| RBA | 澳大利亚储备银行数据 | 中央银行和货币当局，监管银行业，设定利率，并为政府债务提供服务。关键经济指标数据。 | +| UCOM | 联合国商品贸易数据 | 该数据库提供有关食品，活体动物，药品，金属，燃料和机械等商品进出口的全面综合数据。 | +| SIDC | 太阳影响数据分析中心数据 | SIDC主持从1700年开始的太阳活动数据，特别是太阳黑子活动。 | +| ZCE | 郑州商品交易所数据 | 来自ZCE的农业和商品期货，历史跨越了近十年的特定期货。 | +| USDAFAS | 美国农业部外国农业服务数据（FAS） | 美国农业部外国农业服务局将美国农业与世界市场联系起来。它提供了国外生产和出口的统计数据。 | +| OECD | 世界经济合作与发展组织数据 | 促进经济福利的发达国家国际组织。从成员和其他人收集数据以提出政策建议。 | +| OPEC | 欧佩克数据 | 国际组织和经济卡特尔监督伊拉克，伊朗，沙特阿拉伯和委内瑞拉等石油生产国的政策、油价数据。 | +| MCX | 印度多种商品交易所数据 | 印度最大的商品交易所，为金属，能源和农业期货交易提供服务。世界第三大合约和交易量交易所。 | +| ECONOMIST | 经济学人 - 巨无霸指数 | 巨无霸指数是由经济学家于1986年发明的，是一个轻松的指南，指出货币是否处于“正确”水平。它基于购买力平价理论（PPP）。 | +| NSDL | 国家证券存管有限公司（印度）数据 | 在印度存放负责该国经济发展的国家，该国家建立了国际标准的国家基础设施，处理在印度资本市场以非物质形式持有和结算的大部分证券。 | +| GDT | 全球乳品贸易数据 | nan | +| CFFEX | 中国金融期货交易所数据 | 来自CFFEX的指数和债券期货，对于特定期货的历史跨越近十年。 | +| CITYPOP | Thomas Brinkhoff的城市人口数据 | Thomas Brinkhoff提供了大多数国家城市和行政区域的人口数据。 | +| BCHARTS | 比特币图表汇率数据 | 来自所有主要比特币交易所的比特币兑换大量货币的汇率，包括当前和历史汇率。 | +| LOCALBTC | Local Bitcoins数据 | nan | +| JODI | JODI石油世界数据库 | JODI石油和天然气数据来自100多个国家，包括多种能源产品和各种计量方法。 | +| UENG | 联合国能源统计数据 | 该数据库提供有关新能源和可再生能源的生产，贸易，转换和最终消费的全面统计数据。 | +| ULMI | 联合国劳工市场指标 | 该数据库为世界上所有国家提供了按性别划分的全面青年失业数字。 | +| MAURITIUSSE | 毛里求斯证券交易所数据 | 毛里求斯证券交易所指数数据。 | +| UKRSE | 乌克兰交易所数据 | UKRSE提供与乌克兰最大证券交易所相关的最新数据。该交易所位于基辅，约占乌克兰总股本交易量的四分之三 | +| BITSTAMP | Bitstamp数据 | Bitstamp是一个比特币的交易平台。 | +| UNAE | 联合国国民账户估算数据 | 该数据库提供了全球所有国家不同部门的国内生产总值，国民总收入和总增加值的全球数据。 | +| UNAC | 联合国国民账户官方国家数据 | 该数据库提供有关国民账户的全球数据，例如家庭，公司和政府的资产和负债。 | +| UTOR | 联合国世界旅游业数据 | 该数据库提供有关国际旅游的综合数据。数据包括所有国家的旅游人数和旅游支出。 | +| WFE | 世界交易所联合会数据 | 该数据库提供有关国际旅游的综合数据。数据包括所有国家的旅游人数和旅游支出。 | +| FRBC | 克利夫兰联邦储备银行数据 | 克利夫兰联邦储备银行从数百家金融机构收集数据，包括存款机构，银行控股公司和其他用于评估金融机构状况的实体，以及收集经济和金融体系运作方式的见解。 | +| UGEN | 联合国性别信息 | 该数据库提供关于各种与性别有关的指标的全面综合数据，涵盖人口，卫生，教育和就业。 | +| BITFINEX | Bitfinex数据 | Bitfinex是比特币，莱特币和Darkcoin的交易平台，具有许多先进功能，包括保证金交易，交易所和点对点保证金融资。 | +| UGHG | 联合国温室气体清单 | 该数据库提供有关六种主要温室气体人为排放的全面综合数据。数据可以追溯到1990年。 | +| UIST | 联合国工业发展组织数据 | 该数据库提供有关工业发展指标的全球数据，包括产量，员工，工资，各种行业的增加值。 | +| PRAGUESE | 布拉格证券交易所数据 | 布拉格证券交易所的价格指数数据。 | +| PFTS | PFTS证券交易所（乌克兰）数据 | 来自PFTS证券交易所的指数数据，这是乌克兰最大的市场。 | +| WARSAWSE | 华沙证券交易所数据 | WIG20指数自1994年4月16日起根据WSE主要清单中20家最主要和最具流动性公司的股票价值计算。 | +| TUNISSE | 突尼斯证券交易所数据 | 突尼斯证券交易所的主要参考指数。 | +| FRKC | 堪萨斯城联邦储备银行数据 | FRKC是美联储第10区的区域中央银行，主要发布农业交易中的银行业务数据。 | +| UENV | 联合国环境统计数据 | 该数据库提供有关水和废物相关指标的全球数据，包括淡水供应和降水，以及废物的产生和收集。 | +| UFAO | 联合国粮食和农业数据 | 该数据库提供全球粮食和农业数据，包括作物生产，化肥消费，农业用地和牲畜用途。 | +| TAIFEX | 台湾期货交易所数据 | 来自TAIFEX的指数和债券期货，其历史跨越了十多年的特定期货。 | +| GDAX | GDAX（全球数字资产交易所）数据 | GDAX是世界上最受欢迎的买卖比特币的地方。 | +| ARES | 房地产证券化协会数据 | ARES保护投资者，有助于房地产证券化产品市场的发展，并促进房地产投资市场的扩张。 | +| SHADOWS | 影子联邦基金利率模型数据 | 该数据集包含 吴-侠 论文中关于影子联邦基金的三个主要指标，用于识别所有三大银行的影子利率。 | +| NAAIM | 全国积极投资管理者协会头寸指数 | NAAIM暴露指数代表NAAIM成员报告的美国股票市场的平均风险敞口。 | +| CBRT | 土耳其共和国中央银行数据 | CBRT负责采取措施维持土耳其金融体系的稳定。 | +| CEGH | 中欧天然气中心数据 | nan | +| FINRA | 美国金融业监管局数据 | 金融业监管局提供证券公司和交易所市场的短期利息数据。 | +| NASDAQOMX | 纳斯达克OMX全球指数数据 | 纳斯达克OMX发布的全球指数超过35,000种，包括全球股票，固定收益，股息，绿色，北欧，伊斯兰教等。每日数据。 | +| EURONEXT | 泛欧证券交易所数据 | 欧洲最大的交易所Euronext的历史股票数据。 | +| UICT | 联合国信息和通信技术数据 | 该数据库提供有关信息和通信技术的全面全球数据，包括所有国家的电话，蜂窝和互联网使用情况。 | +| USAID | 美国国际开发署数据 | 美国国际开发署提供了美国向世界其他地方提供的所有外国援助的完整历史记录。 | +| ZAGREBSE | 萨格勒布证券交易所数据 | 克罗地亚唯一的证券交易所。它发布有关其股票和债券指数表现的数据。 | +| QUITOSE | 基多证券交易所（厄瓜多尔）数据 | 厄瓜多尔国家证券交易所的指数。 | +| ECBCS | 欧盟委员会商业和消费者调查 | 该数据库中的数据来自欧盟（EU）和欧盟申请国的不同经济部门的统一调查。 | +| PSE | 巴黎经济学院数据 | 该数据库描述了越来越多国家的最高收入分配。数字是使用税收数据得出的。 | +| MALTASE | 马耳他证券交易所数据 | 马耳他证券交易所发挥作用，为其认可的名单提供金融工具的结构，随后可在受监管，透明和有序的市场（二级市场）进行交易。市场的主要参与者是发行人，股票交易所会员（股票经纪人）和投资者一般。 | +| GPP | 全球石油价格 | nan | +| PPE | 波兰电力交易所（TGE）数据 | nan | +| UKONS | 英国国家统计局数据 | 关于英国就业，投资，住房，家庭支出，国民账户和许多其他社会经济指标的数据。 | +| NCDEX | 国家商品及衍生品交易所（印度）数据 | 印度专业管理的在线多商品交易所 | +| WSE | 华沙证券交易所（GPW）数据 | nan | +| TFX | 东京金融交易所数据 | 东京金融交易所是一个期货交易所，主要交易金融工具市场，处理证券和市场衍生品。 | +| WGFD | 世界银行全球金融发展数据 | 有关金融系统特征的数据，包括金融机构和市场的规模，使用，获取，效率和稳定性的衡量标准。 | +| CEPEA | 应用经济学应用研究中心（巴西）数据 | CEPEA是圣保罗大学的一个经济研究中心，专注于农业企业问题，发布巴西商品价格指数。 | +| SBJ | 日本统计局数据 | 日本政府统计机构，提供有关就业和劳动力的统计数据。 | +| WGEM | 世界银行全球经济监测 | 关于全球经济发展的数据，涵盖高收入国家和发展中国家。 | +| WGDF | 世界银行全球发展金融 | 关于金融系统特征的数据，包括金融机构和市场的规模，使用，获取，效率和稳定性的衡量标准。 | +| WWDI | 世界银行世界发展指标 | 最新和最准确的发展指标，由官方认可的国际来源汇编而成。 | +| WESV | 世界银行企业调查 | 公司级私营部门数据，涵盖金融，腐败，基础设施，犯罪，竞争和绩效衡量等业务主题。 | +| WDBU | 世界银行存续商业数据 | 关于成员国和地方和区域一级选定城市的商业法规及其执法的数据。 | +| OSE | 大阪证券交易所数据 | 日本第二大证券交易所。与东京证券交易所不同，OSE在衍生品交易方面表现最为强劲，是日本的大多数期货和期权。 | +| RFSS | 俄罗斯联邦统计局数据 | 俄罗斯政府统计机构，负责在国家和地方层面发布俄罗斯的社会，经济和人口统计数据。 | +| SHFE | 上海期货交易所数据 | 大宗商品交换能源，金属和化学相关的工业产品。许多商品期货的衍生品市场。 | +| WGEP | 世界银行全球环境规划经济前景数据 | 关于全球经济的短期，中期和长期前景以及对发展中国家和减贫的影响的数据。 | +| USMISERY | 美国痛苦指数 | 由经济学家亚瑟·奥肯（Arthur Okun）开发的苦难指数是失业率加上通胀率。 | +| WJKP | 世界银行知识平台工作数据 | 与劳工有关的主题指标。 | +| WMDG | 世界银行千年发展目标数据 | 根据千年发展目标（MDGs）的目标和指标重新组织的世界发展指标数据。 | +| WPOV | 世界银行贫困统计 | 贫困人口比率，贫困差距以及国际和国家贫困线贫困人口数量的指标。 | +| EUREKA | Eurekahedge数据 | 一家研究公司专注于对冲基金和其他另类投资基金。它公布了对冲基金业绩的数据。 | +| MOFJ | 日本财务省数据 | 日本政府债券利率数据，由财政部每日公布。 | +| PIKETTY | Thomas Piketty数据 | “21世纪资本”中的收入和财富数据，哈佛大学出版社，2014。 | +| PSX | 巴基斯坦证交所数据 | 巴基斯坦证券交易所的股票收盘价格。 | +| SGX | 新加坡交易所数据 | 亚洲证券和衍生品交易所为许多大型新加坡和其他亚洲公司进行股票交易。在自己的交易所上市。 | +| UIFS | 联合国国际金融统计 | 该数据库提供有关国际财务指标的综合数据，如平均收入，债券收益率，政府收入和支出。 | +| UINC | 联合国工业商品数据 | 该数据库提供有关工业商品生产的全球数据，如矿石和矿物，食品，可运输货物和金属产品。 | +| INSEE | 国家统计和经济研究所（法国）数据 | INSEE是法国的国家统计机构。它收集有关法国经济和社会的数据，如社会经济指标和国民账户。 | +| SNB | 瑞士国家银行数据 | 中央银行负责货币政策和货币。有关国际账户，利率，货币供应和其他宏观经济指标的数据。 | +| ODE | 大阪道岛商品交易所数据 | 日本关西地区的一个非营利性商品交易所，交易七种主要农产品。 | +| WGEN | 世界银行性别统计 | 描述收入，工作类型，工作部门，农民生产率以及企业家公司规模和利润的性别差异的数据。 | +| WHNP | 世界银行健康营养与人口统计 | 关键的健康，营养和人口统计数据。 | +| WIDA | 世界银行国际发展协会 | 关于选定指标的IDA（国际开发协会）国家总体成果进展情况的数据。 | +| ECMCI | 欧盟委员会货币状况指数 | 每月更新，此数据库提供欧元区的货币状况指数值。历史可以追溯到1999年。 | +| NBSC | 中国国家统计局数据 | 中国有关金融，工业，贸易，农业，房地产和交通运输的统计数据。 | +| MAS | 新加坡金融管理局数据 | nan | +| MGEX | 明尼阿波利斯谷物交易所数据 | 促进农业指数贸易的区域商品期货和期权合约市场。 | +| WWGI | 世界银行全球治理指标 | 六个治理层面的总体和个别治理指标数据。 | +| ISM | 供应管理研究所 | ISM促进供应链管理实践，并发布有关生产和供应链，新订单，库存和资本支出的数据。 | +| UKR | 乌克兰交易所数据 | nan | +| FRBNY | 纽约联邦储备银行数据 | FRBNY是美国最大的区域中央银行。为纽约，康涅狄格州和新泽西州的大部分地区以及一些地区设定货币政策。 | +| FRBP | 费城联邦储备银行数据 | FRBP是美联储的区域中央银行。它发布有关商业信心指数，GDP，消费和其他经济指标的数据。 | +| FMSTREAS | 美国财政部 - 财务管理处数据 | 美利坚合众国的月收入/支出和赤字/盈余。 | +| EIA | 美国能源信息管理局数据 | 美国国家和州有关所有主要能源产品（如电力，煤炭，天然气和石油）的生产，消费和其他指标的数据。 | +| SOCSEC | 美国社会保障局数据 | 提供有关美国社会保障计划的数据，特别是受益人的人口统计数据;残疾人，老人和幸存者。 | +| TFGRAIN | 顶级飞行谷物合作社数据 | 玉米和大豆的现货价格，包括前月期货合约的基础。 | +| IRPR | 波多黎各统计研究所数据 | 波多黎各统计研究所制造业统计数据。 | +| BCHAIN | blockchain.com数据 | Blockchain是一个发布与比特币相关的数据的网站，每日更新。 | +| BITCOINWATCH | Bitcoin Watch数据 | 比特币采矿统计。 | +| ODA | 国际货币基金组织跨国宏观经济统计 | 国际货币基金组织的初级商品价格和世界经济展望数据，由非洲开放数据公布。优秀的跨国宏观经济数据。 | +| WADI | 世界银行非洲发展指标 | 关于非洲的一系列发展指标，包括国家，区域和全球估计数。 | +| WEDU | 世界银行教育统计 | 关于教育机会，进展，完成，扫盲，教师，人口和支出的国际可比指标。 | +| WGLF | 世界银行全球Findex（全球金融包容性数据库） | 关于人们如何储蓄，借贷，支付和管理风险的金融包容性指标。 | +| WWID | 世界财富和收入数据库 | 世界财富和收入数据库旨在提供开放和便捷的途径，以获取有关国家内部和国家之间世界收入和财富分配历史演变的最广泛的现有数据库。 | +| BTER | 比特儿数据 | 加密货币的历史汇率数据。 | +| CFTC | 商品期货交易委员会报告 | 交易员和集中比率的每周承诺。期货头寸以及期货加期权头寸的报告。新旧格式。 | +| BOE | 英格兰银行官方统计 | 当前和历史汇率，担保贷款和定期存款利率，欧元商业票据利率和政府证券收益率。 | +| EXMPL | Quandl时间序列数据示例 | 一个时间序列数据库示例。 | +| WORLDAL | 铝价格 | 世界铝产能和产量（千公吨）。 | +| WGC | 黄金价格 | 世界黄金协会是黄金行业的市场开发组织。它以不同货币发布黄金价格数据。 | +| MX | 加拿大期货数据 | 蒙特利尔交易所是一家衍生品交易所，交易期货合约以及股票，指数，货币，ETF，能源和利率的期权。 | +| UMICH | 消费者情绪 | 密歇根大学的消费者调查 - 最近6个月的数据点是非官方的;它们来自华尔街日报的文章。 | +| JOHNMATT | 稀有金属价格数据 | 关于铂族金属的当前和历史数据，如价格，供应和需求。 | +| NAHB | 美国住房指数 | 美国的住房和经济指数。 | +| RATEINF | 通货膨胀率 | 阿根廷，澳大利亚，加拿大，德国，欧元区，法国，意大利，日本，新西兰等国的通货膨胀率和消费物价指数CPI。 | +| RENCAP | IPO数据 | 有关美国IPO市场的数据。 | +| ML | 公司债券收益率数据 | 美林（Merrill Lynch）是美国一家大型银行，它发布了不同地区公司债券收益率的数据。 | +| MULTPL | S&P 500 | nan | +| RICI | 商品指数 | 综合，以美元为基础的总回报指数，代表全球经济中消费的一篮子商品的价值。 | +| AAII | 投资者情绪 | 美国个人投资者协会的情绪数据。 | +| BIS | 国际清算银行数据 | 国际清算银行为中央银行提供货币和金融稳定管理，促进国际合作，并作为中央银行的银行。 | +| BCB | 巴西中央银行统计数据库 | 巴西宏观经济数据，涵盖公共财政，国民账户，支付系统，通货膨胀，汇率，贸易和国际储备。 | +| BCRA | 阿根廷中央银行数据 | 阿根廷中央银行负责货币政策，提供外汇市场数据和主要宏观经济指标。 | +| FSE | 法兰克福证券交易所 | 法兰克福证券交易所的每日股票价格 | +| BLSN | 劳工统计局国际数据 | 各国的进出口价格统计，由劳工统计局公布。 | +| BLSP | 劳工统计局生产力数据 | 美国制造业，劳务和商业统计，由劳工统计局公布。 | +| FDIC | 联邦存款保险公司数据 | FDIC是一家银行存款高达25万美元的联邦保险公司，负责收集商业银行和储蓄机构的财务数据。 | +| BLSI | 美国劳工统计局通货膨胀和价格统计 | 美国国家和州一级的通胀数据，由劳工统计局公布。 | +| BLSE | 美国劳工统计局就业与失业统计 | 美国国家和州一级的就业和失业统计数据，由劳工统计局公布。 | +| BLSB | 美国劳工统计局薪酬福利统计 | 由劳工统计局公布的美国停工统计数据。 | +| BP | BP能源生产和消费数据 | BP是一家大型能源生产商和分销商。它提供了各个国家和较大次区域的能源生产和消费数据。 | +| LPPM | 白金和钯价格数据 | 全球钯金和铂金市场清算价格数据。 | +| CASS | 运费指数 | 自1990年以来，CASS每月提供与其他经济和供应链指标相关的货运趋势的CASS运费指数报告。 | +| MORTGAGEX | 可调利率抵押贷款指数 | ARM索引的历史住房数据。 | +| BUCHARESTSE | 布加勒斯特证券交易所数据 | 布加勒斯特证券交易所发布股票，权利，债券，基金单位，结构性产品和期货合约活动数据。 | +| AMECO | 欧盟委员会年度宏观经济数据库 | 欧洲委员会经济和财政事务总局（DG ECFIN）年度宏观经济数据库。 | +| ACC | 美国化学理事会数据 | 化学活性晴雨表（CAB）由美国化学理事会（ACC）出版。 CAB是一个经济指标，有助于预测整个美国经济的高峰和低谷，并突出了美国其他行业的潜在趋势。 | +| ABMI | 亚洲债券市场计划 | 中国和日本债券市场的指标，如规模和构成，市场流动性，收益率收益率和波动率。 | +| BITAL | 意大利证交所数据 | 该数据库提供了Borsa Italiana（现为伦敦证券交易所集团的一部分）的股票期货合约数据。 | +| BANKRUSSIA | 俄罗斯银行数据 | 俄罗斯银行的主要指标，包括银行业，货币供应量，金融市场和宏观经济统计数据。 | +| BOC | 加拿大银行统计数据库 | 加拿大的经济，金融和银行数据。包括利率，通货膨胀，国民账户等。每日更新。 | +| HKEX | 香港交易所数据 | 香港交易所股票价格，历史分割期货等每日更新。 | +| AMFI | 印度共同基金协会数据 | 该数据库代表印度共同基金协会的基金信息。 | +| BDM | 墨西哥银行数据 | 墨西哥银行负责货币政策和本国货币（比索），并提供账户和所有宏观经济变量的数据。 | +| BATS | BATS美国证券交易所数据 | Bats是美国的股票市场运营商，经营四个股票交易所--BZX Exchange，BYX Exchange，EDGA Exchange和EDGX Exchange | +| BSE | 孟买证券交易所数据 | 在印度孟买证券交易所交易的公司的日终价格，指数和其他信息。 | +| FRED | 美联储经济数据 | 来自圣路易斯联邦储备银行研究部门的增长，就业，通货膨胀，劳工，制造业和其他美国经济统计数据。 | +| FMAC | 房地美数据 | Freddie Mac的主要抵押贷款市场调查和其他地区特定历史抵押贷款利率的数据。 | +| EUREX | 欧洲期货交易所数据 | 欧洲最大的期货交易所EUREX的指数，利率，农业和能源期货，历史跨越了特定期货的十年。 | +| ECB | 欧洲中央银行数据 | 欧盟中央银行监督货币政策和欧元，并提供相关宏观经济变量的数据。 | +| BOF | 法国银行数据 | 法兰西银行通过欧洲中央银行体系的政策负责货币政策，并提供关键经济指标的数据。 | +| BELGRADESE | 贝尔格莱德证券交易所数据 | 贝尔格莱德证券交易所数据，每日更新。 | +| CHRIS | 维基连续期货 | Quandl所有600个期货的连续合约。建立在CME，ICE，LIFFE等原始数据之上。由Quandl社区策划。 50年的历史。 | +| BOJ | 日本银行数据 | nan | +| USTREASURY | 美国财政部数据 | 美国财政部确保国家的金融安全，管理国家债务，收取税收，发行货币，提供收益率数据。 | +| LBMA | 伦敦金银市场协会数据 | 伦敦黄金和白银市场的国际贸易协会，由中央银行，私人投资者，生产商，炼油商和其他代理商组成。 | +| PERTH | 珀斯铸币厂数据 | 珀斯造币厂的利率和商品价格的高点，低点和平均值每月更新一次。 | +| ZILLOW2 | Zillow房地产研究 | 房屋价格和租金按大小，类型和等级划分;住房供应，需求和销售。按邮政编码，街区，城市，都市区，县和州切片。 | \ No newline at end of file diff --git a/website/translated_docs/en-US/quickstart.md b/website/translated_docs/en-US/quickstart.md new file mode 100644 index 0000000..c2cd203 --- /dev/null +++ b/website/translated_docs/en-US/quickstart.md @@ -0,0 +1,146 @@ +--- +id: quickstart +title: '🌏 TestNet 快速开始' +--- +## CovenantSQL 工具包 + +### 工具包简介 + +请根据您使用的操作系统平台选择 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。 + +例如，您使用的是： + +- MacOS 平台请下载：[**CovenantSQL-v0.5.0.osx-amd64.tar.gz**](https://github.com/CovenantSQL/CovenantSQL/releases/download/v0.5.0/CovenantSQL-v0.5.0.osx-amd64.tar.gz) +- Linux 平台请下载：[**CovenantSQL-v0.5.0.linux-amd64.tar.gz**](https://github.com/CovenantSQL/CovenantSQL/releases/download/v0.5.0/CovenantSQL-v0.5.0.linux-amd64.tar.gz) +- Windows 平台我们稍后发布，有需求请戳这里：[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/CovenantSQL/CovenantSQL) + +解压之后，你将得到以下命令行工具，包括：`cql`、`cql-minerd` 等, 请将此文件移动到 `PATH` 目录。 + +| 工具名 | 介绍 | +| ---------- | ---------------------------------------------------------------- | +| cql | CovenantSQL 的客户端，`cql console` 命令类似 mysql 命令，用于执行 SQL。还有其他丰富的工具链 | +| cql-minerd | CovenantSQL 矿工客户端，用于运行数据库赚取奖励，以后会开放加入 | +| cqld | CovenantSQL 主链节点，主要由 CovenantLabs 以及合作伙伴以 DPoS 模式运行 | + +### 测试网快速接入 + +目前，我们已经发布了测试网 v0.5.0，供大家进行原理性验证和体验。你可以选在使用公共的测试账号快速进行接入测试。 + +测试账号的配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) (密码为空)，或者使用以下命令： + +```bash +mkdir conf +wget https://git.io/fhFZe -O conf/config.yaml +wget https://git.io/fhFZv -O conf/private.key +chmod 600 conf/private.key +``` + +**测试网注**： + +> 该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放你的应用信息，我们会不定期清理数据库数据。 +> +> 测试网暂时由 3 个 Miner 组成，所以暂时最大只支持`create 3`创建 3 个节点组成的数据库。 + +## 创建并访问 CovenantSQL 数据库 + +### 创建数据库 + +```shell +cql create -config conf/config.yaml '{"node":1}' +``` + +在命令行提示中输入master key的密码，之后控制台会输出： + + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + + +这里表示你提交了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库的创建请求到主链。 + +> 我们需要等待大概 30s 的时间，等待数据库创建，大致过程为： +> +> 1. 收到请求的 出块节点（Block Producer）进行 Miner 和数据库创建请求的撮合 +> 2. 数据库创建请求在 其它出块节点 进行验证和确认 +> 3. SQLChain 的符合条件的 Miner 收到数据库任务 +> 4. SQLChian 组建 Kayak 数据库集群 +> 5. 所有 Miner 准备就绪等待请求 + +### 访问数据库 + +```shell +cql console -config conf/config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +在控制台中根据提示输入master key的密码。连接上数据库后，你可以按你操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 数据库 SDK + +- [Golang 开发指引](./development) + +## SQLChain 区块浏览器 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，你可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。 + +> 测试网的`区块浏览器`目前是开放权限的，所以任何知道数据库 ID 的人都能看到您的数据 + +查询时，请在其页面右上角填入你的数据库 ID。例如：`0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` + +## 创建账号 + +我们的测试网支持你创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（会询问设置主密码，测试期间建议直接回车留空）： + +```shell +cql generate config +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你在~目录下创建一个 `.cql` 目录： + +- `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +cql wallet +``` + +输出： + +```toml +wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 +``` + +你可以在这里回复上面得到的钱包地址 [GitHub Issue](https://github.com/CovenantSQL/CovenantSQL/issues/283)，我们会为你的钱包充值。 + +使用 cql 命令行工具查询余额(可以添加 -config 参数，指定其他的 config.yaml 所在目录)： + +```shell +cql wallet -balance all +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +恭喜，你已收到我们发出的 PTC 稳定币，现在即可开始使用 CovenantSQL， 你可以参考 [Golang 使用 CovenantSQL 文档](./development) 进行开发。 \ No newline at end of file diff --git a/website/translated_docs/en-US/usecase.md b/website/translated_docs/en-US/usecase.md new file mode 100644 index 0000000..0ca5313 --- /dev/null +++ b/website/translated_docs/en-US/usecase.md @@ -0,0 +1,5 @@ +--- +id: usecase +title: 使用案例 +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/adapter.md b/website/translated_docs/zh-CN/adapter.md new file mode 100644 index 0000000..32c7fa9 --- /dev/null +++ b/website/translated_docs/zh-CN/adapter.md @@ -0,0 +1,59 @@ +--- +id: adapter +title: Adapter +--- + +# Use Adapter to access CovenantSQL + +`CovenantSQL` provides an HTTP/HTTPS adapter service. Developers could access CovenantSQL like a cloud database by using HTTP RESTful requests. + +## How to use + +First, [Install docker](https://docs.docker.com/install/). + +Secondly, before using CovenantSQL, a proper configuration file and an asymmetric key-pair is required. If no configuration file is specified, CovenantSQL tries to load configuration from `~/.cql/config.yaml`. For configuration file and key-pair generation, please refer to [QuickStart#CreateAccount](./quickstart#CreateAccount) + +### Start adapter using docker + +Following command will use config file `~/.cql/config.yaml` and key-pair `~/.cql/private.key` to start adapter service and serving at `0.0.0.0:11105`. + +```bash +export adapter_addr=0.0.0.0:11105 +docker rm -f cql-adapter +docker run -itd \ + --env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \ + --env COVENANTSQL_ADAPTER_ADDR=0.0.0.0:4661 \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --name cql-adapter -p $adapter_addr:4661 \ + covenantsql/covenantsql:testnet +``` + +### Create database + +Create new database using `cql create` command and provide database instance requirements. + +For example, create a single node database instance: + +```bash +docker run -it --rm \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --entrypoint /app/cql covenantsql/covenantsql:testnet \ + create -config /app/config.yaml -wait-tx-confirm -db-node 1 +``` + +This command would produce a database connection string (DSN) similar to following example. + +```bash +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +Use DSN to access CovenantSQL using various drivers. + +## Drivers + +1. [Golang](./driver_golang) +2. [Java](./driver_java) +3. [Python](./driver_python) +4. [NodeJS](./driver_js) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/adpater.md b/website/translated_docs/zh-CN/adpater.md new file mode 100644 index 0000000..18bb37e --- /dev/null +++ b/website/translated_docs/zh-CN/adpater.md @@ -0,0 +1,58 @@ +--- +id: adapter +title: Adapter +--- + +# Use Adapter to access CovenantSQL + +`CovenantSQL` provides an HTTP/HTTPS adapter service. Developers could access CovenantSQL like a cloud database by using HTTP RESTful requests. + +## How to use + +First, [Install docker](https://docs.docker.com/install/). + +Secondly, before using CovenantSQL, a proper configuration file and an asymmetric key-pair is required. If no configuration file is specified, CovenantSQL tries to load configuration from `~/.cql/config.yaml`. For configuration file and key-pair generation, please refer to [QuickStart#CreateAccount](./quickstart#CreateAccount) + +### Start adapter using docker + +Following command will use config file `~/.cql/config.yaml` and key-pair `~/.cql/private.key` to start adapter service and serving at `0.0.0.0:11105`. + +```bash +export adapter_addr=0.0.0.0:11105 +docker rm -f cql-adapter +docker run -itd \ + --env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --name cql-adapter -p $adapter_addr:4661 \ + covenantsql/covenantsql:testnet 0.0.0.0:4661 +``` + +### Create database + +Create new database using `cql create` command and provide database instance requirements. + +For example, create a single node database instance: + +```bash +docker run -it --rm \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --entrypoint /app/cql covenantsql/covenantsql:testnet \ + create -config /app/config.yaml -wait-tx-confirm '{"node": 1}' +``` + +This command would produce a database connection string (DSN) similar to following example. + +```bash +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +Use DSN to access CovenantSQL using various drivers. + +## Drivers + +1. [Golang](./driver_golang) +2. [Java](./driver_java) +3. [Python](./driver_python) +4. [NodeJS](./driver_js) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/advanced_deployment.md b/website/translated_docs/zh-CN/advanced_deployment.md new file mode 100644 index 0000000..7bbc350 --- /dev/null +++ b/website/translated_docs/zh-CN/advanced_deployment.md @@ -0,0 +1,159 @@ +--- +id: advanced_deployment +title: Private Deploy +--- + +## Deploy with CovenantSQL Docker + +### Install Docker + +You need to install docker and docker-compose on your machine to deploy CovenantSQL. + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### Download project + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +For all subsequent commands, the working directory is by default in the cloned CovenantSQL root directory, which can be saved as an environment variable: + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +### Start Docker container + +There are now two ways to start the CovenantSQL container: + +1. Use a public image on Docker Hub +2. Build a CovenantSQL Docker image + +> We recommend that regular users test CovenantSQL in the first way, and the second is only used to experience the latest development features. + +#### 1. Use a public image on Docker Hub + +Then start directly: + +```bash +make start +``` + +#### 2. Build a CovenantSQL Docker image + +Run CovenantSQL locally by executing the following command + +```bash +make docker # compile a new image from source files +make start +``` + +### Check running status + +Check the container status: + +```bash +docker-compose ps +``` + +Confirm that all components are in the `Up` state + + Name Command State Ports + ------------------------------------------------------------------------------------------------------ + covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp + covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp + covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp + covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp + covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp + covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp + covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp + covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp + covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp + covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp + + +## Operate CovenantSQL + +### Create a database + +Create a DB instance by using the `cql` command and using the `create` parameter to provide the required number of database nodes. + +e.g.: creating a single-node database instance + +```bash +cql create -config ${COVENANTSQL_ROOT}/test/service/node_c/config.yaml -db-node 1 +``` + +> Modify the value of the `create` parameter to create an instance running on multiple nodes +> e.g.: create an instance of two nodes + +```bash +cql create -config ${COVENANTSQL_ROOT}/test/service/node_c/config.yaml -db-node 2 +``` + +The command will return the connection string of the created database instance + + covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + + +### Accessing the database + +Use the `cql` command and use the `dsn` parameter to provide a connection string for the database instance access: + +```bash +cql console -config ${COVENANTSQL_ROOT}/test/service/node_c/config.yaml covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +After that, it will get the following output, and enter the `cql` interactive command line mode + +``` + +Connected with driver covenantsql (develop) Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> + +
The `cql` interactive command line mode is similar to the `mysql` command. For example, create a table named test, view the tables in the database, insert records, and query results etc. + + ```sql + CREATE TABLE test (test TEXT); + SHOW TABLES; + INSERT INTO test VALUES("happy"); + SELECT * FROM test; + + +After that, it will get the following output: + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); + CREATE TABLE + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name + ------ + test + (1 row) + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); + INSERT + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test + ------- + happy + (1 row) + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> + + +Use the `Ctrl + D` shortcut or type `\q` to exit the `cql` interactive command line + +### SQLChain Observer + +The Observer role in the image uses the same private.key as in the mysql-adapter image, so the new account authorization and transfer process can be eliminated. + +（For details on rights management, please refer to [Database Permission Managemen](cql_db_manage#granting-permission)） + +#### Use SQLChain Observer in your browser + +We provide a SQLChain Observer at port `127.0.0.1:11108` to see the SQL statement on the chain. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/advanced_secure_gateway.md b/website/translated_docs/zh-CN/advanced_secure_gateway.md new file mode 100644 index 0000000..04a120f --- /dev/null +++ b/website/translated_docs/zh-CN/advanced_secure_gateway.md @@ -0,0 +1,79 @@ +--- +id: advanced_secure_gateway +title: Secure Gateway +--- + +## SecureGateway + +CQL SecureGateway (CGS) is currently only available to enterprise users. If you have in-depth understanding or trial requirements, please [contact us](mailto:info@covenantsql.io). + +### Architecture + +![CovenantSQL.SecureGateway](https://github.com/CovenantSQL/docs/raw/master/website/static/img/CovenantSQL.SecureGateway.png) + +### API + +CGS uses the binary protocol of MySQL 5.x, and all language drivers compatible with MySQL 5.x can be used directly. + +### ACL Config + +Support for **User/User Group** and **Column/Column Group** combination authorization (columns are represented as **database.table.column** triples) + +#### ACL Example + +The settings are divided into two parts, `Group` and `Strategy`, as follows: + +User Group + +| User | Group | +| ----- | --------------- | +| user1 | admin,userGroup | +| user2 | admin,userGroup | +| user3 | userGroup | + +Column Group + +| Column | Group | +| ------------- | -------- | +| db1.tbl1.col2 | someCols | +| db1.tbl1.col3 | someCols | +| db1.tbl1.col4 | someCols | + +Strategy + +| User/Group | Column/Group | Permission（Write/Read） | +| ---------- | ------------- | ---------------------- | +| user1 | db1.tbl1.col1 | write | +| user2 | db1.tbl1.col1 | read | +| admin | someCols | read | +| userGroup | db1.tbl2.col1 | read | +| userGroup | db2.tbl1.* | read | + +### Encryption Config + +Support for configuring encryption settings in the form of fields & encryption keys (fields are represented as **database.table.field** triples) Encryption/decryption is valid only if the user has permission to the field. + +#### Example + +Keys + +| Column | Key | +| ------------- | ---- | +| db1.tbl1.col1 | key1 | +| db1.tbl1.col2 | key2 | +| db1.tbl1.col3 | key3 | +| db1.tbl2.col1 | key1 | +| db2.tbl1.col1 | key1 | + +In conjunction with the configuration of `ACL` & `Keys` above, the access restrictions that are in effect are as follows: + +Result + +| database | table | column | key | user permissions | +| -------- | ----- | ------ | ---- | ----------------------- | +| db1 | tbl1 | col1 | key1 | user1 write; user2 read | +| db1 | tbl1 | col2 | key2 | user1 read; user2 read | +| db1 | tbl1 | col3 | key3 | user1 read; user2 read | +| db1 | tbl1 | col4 | | user1 read; user2 read | +| db1 | tbl2 | col1 | key1 | userGroup read | +| db2 | tbl1 | * | key1 | userGroup read | \ No newline at end of file diff --git a/website/translated_docs/zh-CN/api.md b/website/translated_docs/zh-CN/api.md new file mode 100644 index 0000000..0a111da --- /dev/null +++ b/website/translated_docs/zh-CN/api.md @@ -0,0 +1,5 @@ +--- +id: api +title: '👩🏻‍💻 CovenantSQL API' +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/arch.md b/website/translated_docs/zh-CN/arch.md new file mode 100644 index 0000000..e1540fa --- /dev/null +++ b/website/translated_docs/zh-CN/arch.md @@ -0,0 +1,59 @@ +--- +id: arch +title: Architecture +--- + +## 3 Layers Arch + +![CovenantSQL 3 Layer design](https://github.com/CovenantSQL/CovenantSQL/raw/ed2878359345cd86e4221f14cd59e4654361b64e/logo/arch.png) + +- Layer 1: **Global Consensus Layer** (the main chain, the middle ring in the architecture diagram): + - There will only be one main chain throughout the network. + - Mainly responsible for database Miner and the user’s contract matching, transaction settlement, anti-cheating, shard chain lock hash and other global consensus matters. +- Layer 2: **SQL Consensus Layer** (shard chain, rings on both sides): + - Each database will have its own separate shard chain. + - Mainly responsible for: the signature, delivery and consistency of the various Transactions of the database. The data history of the permanent traceability is mainly implemented here, and the hash lock is performed in the main chain. +- Layer 3: **Datastore Layer** (database engine with SQL-92 support): + - Each Database has its own independent distributed engine. + - Mainly responsible for: database storage & encryption, query processing & signature, efficient indexing. + +## Consensus Algorithm + +CQL supports 2 kinds of consensus algorithm: + +1. DPoS (Delegated Proof-of-Stake) is applied in `Eventually consistency mode` database and also `Layer 1 (Global Consensus Layer)` in BlockProducer. CQL miners pack all SQL queries and its signatures by the client into blocks thus form a blockchain. We named the algorithm [`Xenomint`](https://github.com/CovenantSQL/CovenantSQL/tree/develop/xenomint). +2. BFT-Raft (Byzantine Fault-Toleranted Raft)bft-raft is applied in `Strong consistency mode` database. We named our implementation [`Kayak`](https://github.com/CovenantSQL/CovenantSQL/tree/develop/kayak). The CQL miner leader does a `Two-Phase Commit` with `Kayak` to support `Transaction`.transaction + +CQL database consistency mode and node count can be selected in database creation with command `cql create -db-eventual-consistency -db-node 3` + +## Comparison + +| | Ethereum | Hyperledger Fabric | Amazon QLDB | CovenantSQL | +| ---------------------------- | ----------------- | ---------------------- | ----------- | -------------------------------------------------------------------- | +| **Dev language** | Solidity, ewasm | Chaincode (Go, NodeJS) | ? | Python, Golang, Java, PHP, NodeJS, MatLab | +| **Dev Pattern** | Smart Contract | Chaincode | SQL | SQL | +| **Open Source** | Y | Y | N | Y | +| **Nodes for HA** | 3 | 15 | ? | 3 | +| **Column Level ACL** | N | Y | ? | Y | +| **Data Format** | File | Key-value | Document | Filefuse, Key-value, Structured | +| **Storage Encryption** | N | API | Y | Y | +| **Data Desensitization** | N | N | N | Y | +| **Multi-tenant** | DIY | DIY | N | Y | +| **Throughput (1s delay)** | 15~10 tx/s | 3500 tx/s | ? | 11065 tx/s (Eventually Consistency) +1866 tx/s (Strong Consistency) | +| **Consistency Delay** | 2~6 min | < 1 s | ? | < 10 ms | +| **Secure for Open Internet** | Y | N | Only in AWS | Y | +| **Consensus** | PoW + PoS(Casper) | CFT | ? | DPoS (Eventually Consistency) +BFT-Raft (Strong Consistency) | + +### FootNotes + +- BFT-Raft: A CQL leader offline needs CQL Block Producer to decide whether to wait for leader online for data integrity or promote a follower node for availability. This part is still under construction and any advice is welcome. + +- Transaction: Talking about `ACID`, CQL has full "Consistency, Isolation, Durability" and a limited `Atomicity` support. That is even under strong consistency mode, CQL transaction is only supported on the leader node. If you want to do "read `v`, `v++`, write `v` back" parallelly and atomically, then the only way is "read `v` from the leader, `v++`, write `v` back to leader" + +- FUSE: CQL has a [simple FUSE](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql-fuse) support adopted from CockroachDB. The performance is not very ideal and still has some issues. But it can pass fio test like: + + ```bash + fio --debug=io --loops=1 --size=8m --filename=../mnt/fiotest.tmp --stonewall --direct=1 --name=Seqread --bs=128k --rw=read --name=Seqwrite --bs=128k --rw=write --name=4krandread --bs=4k --rw=randread --name=4krandwrite --bs=4k --rw=randwrite + ``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/arch_layers.md b/website/translated_docs/zh-CN/arch_layers.md new file mode 100644 index 0000000..4bc3fc3 --- /dev/null +++ b/website/translated_docs/zh-CN/arch_layers.md @@ -0,0 +1,29 @@ +--- +id: arch_layers +title: Blockchains +--- + + +## MainChain & SQLChain + +CQL uses a layered architecture for database creation and operation. A typical data creation process can be roughly as follows: + +1. Miner will automatically register with the MainChain after startup. The registration information includes: "Minimum acceptable Gas price", "System metrics", "External IP and port", etc. +2. Miner subscribes to and pays attention to information related to themselves through ChainBus; +3. The client runs `cql create -db-node 2` to send a signed database creation request to any BP (Block Producer) in the MainChain; +4. The BP that received the request performs a match of Miner and database creation request in the process of producing the block (see: \[MainChain Produce Block\] (#mainchain-produce-block)); +5. Database creation requests and matching results are verified and confirmed at other BP nodes; +6. The Miner subscription receives the database task; +7. Miners discover and connect with each other through Kayak to form a SQLChain database cluster; +8. All miners are ready to wait for a request; +9. Users can connect to the database and execute SQL through the `cql console` command. + +See the image below to view [large picture](https://cdn.jsdelivr.net/gh/CovenantSQL/docs@b7143254adb804dff0e3bc1f2f6ab11ad9cd44f5/website/static/img/2layers.svg)： + +![2layers](https://cdn.jsdelivr.net/gh/CovenantSQL/docs@b7143254adb804dff0e3bc1f2f6ab11ad9cd44f5/website/static/img/2layers.svg) + +## MainChain Produce Block + +The complete main chain export process is complicated. Please refer to the numbers in the figure below for understanding. For the big picture, please click [here](https://cdn.jsdelivr.net/gh/CovenantSQL/docs/website/static/img/produce-block.svg) + +![MainChain Produce Block](https://cdn.jsdelivr.net/gh/CovenantSQL/docs/website/static/img/produce-block.svg) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/arch_network.md b/website/translated_docs/zh-CN/arch_network.md new file mode 100644 index 0000000..171e2d7 --- /dev/null +++ b/website/translated_docs/zh-CN/arch_network.md @@ -0,0 +1,280 @@ +--- +id: arch_network +title: RPC Framework +--- + +The traditional key exchange like TLS or SSL needs a CA to ensure key exchange run safely. But in DH-RPC I use a DHT to do that. The main idea is removing CA Cert from the whole system by using a DHT for Naming and Key Exchange. + +DH-RPC is a secp256k1-ECDH-AES encrypted P2P RPC framework for decentralized applications written in golang. + +CovenantSQL is built on DH-RPC, including: + +- Byzantine Fault Tolerance consensus protocol [Kayak](https://godoc.org/github.com/CovenantSQL/CovenantSQL/kayak) +- Consistent Secure DHT +- DB API +- Metric Collect +- Blocks sync + +## Usage + +![](https://cdn.jsdelivr.net/gh/CovenantSQL/CovenantSQL@cc4aa933d80a5d31738081d13c7b1587ad47cffb/logo/dh-rpc.svg) + +Alice Client: + +```go +// Init Key Management System +route.InitKMS(PubKeyStoreFile) + +// Register Node public key, addr to Tracker +reqA := &proto.PingReq{ + Node: AliceNode, +} +respA := new(proto.PingResp) +rpc.NewCaller().CallNode(Tracker.NodeID, "DHT.Ping", reqA, respA) + +pc := rpc.NewPersistentCaller(BobNodeID) +respSimple := new(string) +pc.Call("Test.Talk", "Hi there", respSimple) +fmt.Printf("Response msg: %s", *respSimple) +``` + +Bob Server: + +```go +// RPC logic +// TestService to be register to RPC server +type TestService struct {} + +func (s *TestService) Talk(msg string, ret *string) error { + fmt.Println(msg) + resp := fmt.Sprintf("got msg %s", msg) + *ret = resp + return nil +} + +// Init Key Management System +route.InitKMS(PubKeyStoreFile) + +// Register DHT service +server, err := rpc.NewServerWithService(rpc.ServiceMap{ + "Test": &TestService{}, +}) + +// Init RPC server with an empty master key, which is not recommend +server.InitRPCServer("0.0.0.0:2120", PrivateKeyFile, "") + +// Start Node RPC server +server.Serve() +``` + +Tracker stuff can refer to the Example section below + +## Features + +- 100% compatible with Go [net/rpc](https://golang.org/pkg/net/rpc/) standard. +- ID based routing and Key exchange built on Secure Enhanced DHT. +- use MessagePack for serialization which support most types without writing `Marshal` and `Unmarshal`. +- Crypto Schema + - Use Elliptic Curve Secp256k1 for Asymmetric Encryption + - ECDH for Key Exchange + - PKCS#7 for padding + - AES-256-CFB for Symmetric Encryption + - Private key protected by master key + - Anonymous connection is also supported +- DHT persistence layer has 2 implementations: + - SQLite3 based simple traditional DHT + - [Kayak](https://godoc.org/github.com/CovenantSQL/CovenantSQL/kayak) based 2PC strong consistent DHT +- Connection pool based on [smux](https://github.com/xtaci/smux), make thousands of connections multiplexed over **One TCP connection**. + +## Stack + +[DH-RPC](rpc/) := TLS - Cert + DHT + +| Layer | Implementation | +|:------------------ |:------------------------------------------------------------------------------------------------------------:| +| RPC | `net/rpc` | +| Naming | [**C**onsistent **S**ecure **DHT**](https://godoc.org/github.com/CovenantSQL/CovenantSQL/consistent) | +| Pooling | Session Pool | +| Multiplex | [smux](https://github.com/xtaci/smux) | +| Transport Security | [**E**nhanced **TLS**](https://github.com/CovenantSQL/research/wiki/ETLS(Enhanced-Transport-Layer-Security)) | +| Network | TCP or KCP for optional later | + +## How it works + +As we all know, Elliptic Curve Public Key is computed form Private Key + +```go +ECPubKey := ECPrivKey.Pub() +``` + +DH-RPC node is generated by hash of NodePublicKey and an [Uint256 Nonce](../pow/cpuminer/uint256.go): + +```go +NodeID := sha256(blake2b-512(NodePublicKey + Uint256Nonce)) +``` + +DHT is used to hold the `NodeID`:`PublicKey` `NodeID`:`Addr` map. A RPC connection will do ECDH to get shared secret after TCP connection established. + +```go +GenECDHSharedSecret(APub, BPriv) == GenECDHSharedSecret(BPub, APriv) +``` + +The main procedure is described as sequence chart below: + + + +So anyone tries to fake NodeB by overwriting the address or public key on DHT without the private key of NodeB will be failed to get the correct shared secret. + +## Example + +The example below is 1 tracker and 2 nodes. + +Complete code can be found [here](_example/) + +#### Tracker Code + +```go +package main + +import ( + "os" + + "github.com/CovenantSQL/CovenantSQL/conf" + "github.com/CovenantSQL/CovenantSQL/consistent" + "github.com/CovenantSQL/CovenantSQL/route" + "github.com/CovenantSQL/CovenantSQL/rpc" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + //log.SetLevel(log.DebugLevel) + conf.GConf, _ = conf.LoadConfig(os.Args[1]) + log.Debugf("GConf: %#v", conf.GConf) + + // Init Key Management System + route.InitKMS(conf.GConf.PubKeyStoreFile) + + // Creating DHT RPC with simple persistence layer + dht, err := route.NewDHTService(conf.GConf.DHTFileName, new(consistent.KMSStorage), true) + if err != nil { + log.Fatalf("init dht failed: %v", err) + } + + // Register DHT service + server, err := rpc.NewServerWithService(rpc.ServiceMap{route.DHTRPCName: dht}) + if err != nil { + log.Fatal(err) + } + + // Init RPC server with an empty master key, which is not recommend + addr := conf.GConf.ListenAddr + masterKey := []byte("") + server.InitRPCServer(addr, conf.GConf.PrivateKeyFile, masterKey) + server.Serve() +} +``` + +#### Node Code + +```go +package main + +import ( + "bufio" + "fmt" + "os" + "strings" + + "github.com/CovenantSQL/CovenantSQL/conf" + "github.com/CovenantSQL/CovenantSQL/proto" + "github.com/CovenantSQL/CovenantSQL/route" + "github.com/CovenantSQL/CovenantSQL/rpc" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +// TestService to be register to RPC server +type TestService struct { +} + +func NewTestService() *TestService { + return &TestService{} +} + +func (s *TestService) Talk(msg string, ret *string) error { + fmt.Println(msg) + resp := fmt.Sprintf("got %s", msg) + *ret = resp + return nil +} + +func main() { + //log.SetLevel(log.DebugLevel) + conf.GConf, _ = conf.LoadConfig(os.Args[1]) + log.Debugf("GConf: %#v", conf.GConf) + + // Init Key Management System + route.InitKMS(conf.GConf.PubKeyStoreFile) + + // Register DHT service + server, err := rpc.NewServerWithService(rpc.ServiceMap{ + "Test": NewTestService(), + }) + if err != nil { + log.Fatal(err) + } + + // Init RPC server with an empty master key, which is not recommend + addr := conf.GConf.ListenAddr + masterKey := []byte("") + server.InitRPCServer(addr, conf.GConf.PrivateKeyFile, masterKey) + + // Start Node RPC server + go server.Serve() + + // Register Node public key, addr to Tracker(BP) + for _, n := range conf.GConf.KnownNodes { + client := rpc.NewCaller() + reqA := &proto.PingReq{ + Node: n, + } + respA := new(proto.PingResp) + err = client.CallNode(conf.GConf.BP.NodeID, "DHT.Ping", reqA, respA) + if err != nil { + log.Fatal(err) + } + log.Debugf("respA: %v", respA) + } + + // Read target node and connect to it + scanner := bufio.NewScanner(os.Stdin) + fmt.Print("Input target node ID: ") + scanner.Scan() + if scanner.Err() == nil { + target := proto.NodeID(strings.TrimSpace(scanner.Text())) + pc := rpc.NewPersistentCaller(target) + log.Debugf("connecting to %s", scanner.Text()) + + fmt.Print("Input msg: ") + for scanner.Scan() { + input := scanner.Text() + log.Debugf("get input %s", input) + repSimple := new(string) + err = pc.Call("Test.Talk", input, repSimple) + if err != nil { + log.Fatal(err) + } + log.Infof("resp msg: %s", *repSimple) + } + } +} +``` + +Start tracker and node1, node2 + +```bash +$ ./runTracker.sh & +$ ./runNode2.sh & +$ ./runNode1.sh +$ Input target node ID: 000005aa62048f85da4ae9698ed59c14ec0d48a88a07c15a32265634e7e64ade #node2 +$ Input msg: abcdefg +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/cql.md b/website/translated_docs/zh-CN/cql.md new file mode 100644 index 0000000..c47f8e7 --- /dev/null +++ b/website/translated_docs/zh-CN/cql.md @@ -0,0 +1,623 @@ +--- +id: cql +title: Client +--- +## Intro + +CovenantSQL provides a `cql` command line toolset for terminal users to access and manage user accounts, wallet balances, and databases. Check the complete toolset installation tutorial at \[CovenantSQL Toolset installation\](quickstart#工具包安装). + +### Private Key and Config File + +The `cql` command needs to rely on a private key file `private.key` and a config file `config.yaml`: + +- `private.key`：a private key file which is generated while creating an account, be sure to keep it safe +- `config.yaml`：mainly used to config the CovenantSQL network for `cql` command to connect (e.g., the [TestNet](quickstart) or the [Docker Environment by One Click](deployment)) + +For security, the private key file is usually encrypted with a master key. A master key is individually chosen by the user while creating an account and is memorized or kept somewhere by the user -- note that the config file will not keep the master key. When the private key is required by the `cql` command, it will ask the user to input the master key to decrypt the private key file. + +### Common Parameters for Sub-commands + +The following parameters are commonly used by `cql` sub-commands: + + -bypass-signature + Disable signature signing and verifying, for testing only + -config string + Config file for covenantsql (Usually no need to set, default is enough.) (default "~/.cql/config.yaml") + -no-password + Use an empty master key + -password string + Master key for covenantsql (NOT SAFE, for debugging or script mode only) + + +Note that the private key file path is specified in the config file, and its default value is `./private.key`, indicating that it's located in the same directory of the config. So usually we put the private key file together with config, instead of using an individual parameter to specify the private key file. + +## Account Management + +For the TestNet environment, we provide a public account for quick testing. Check the [CovenantSQL TestNet](quickstart) tutorial to find out the private key and config file of the public account. And you can also follow the next section to create an individual account with `cql` command. + +### Creating New Account + +The sub-command `generate` generates a private key file and a config file connecting to the TestNet in the specified directory, e.g.: + +```bash +cql generate config +``` + +> Currently, the generated config file is pointed to the TestNet, we will provide options to generated config for Docker Environment later. + +For a complete help message, check [Complete Parameters](#sub-command-generate-complete-parameters). + +Output: + + Generating key pair... + Enter master key(press Enter for default: ""): + + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +### Acquiring the Public Key + +The sub-command `generate` is also used to acquire the public key (in hex string format) of the private key file, e.g.: + +```bash +cql generate public +``` + +Output： + + Enter master key(press Enter for default: ""): + + INFO[0011] init config success path=/home/levente/.cql/private.key + INFO[0011] use public key in config file: /home/levente/.cql/config.yaml + Public key's hex: 02fd4089e7f4ca224f576d4baa573b3e9662153c952fce3f87f9586ffdd11baef6 + + +> This functionality is usually not used in common scene + +### Sub-command `generate` Complete Parameters + +Also see [Common Parameters for Sub-commands](#common-parameters-for-sub-commands). We will not mention this in the further sub-command introductions. + + usage: cql generate [parameters]... config | public + + Generate command can generate private.key and config.yaml for CovenantSQL. + e.g. + cql generate config + + Params: + + + +### Mine a Node ID + +The sub-command `idminer` is used to mine another Node ID of a private key (specified by a config file), (also check [Node ID](terms#Node-ID) for details). e.g.: + +```bash +cql idminer +``` + +Output: + + INFO[0000] cql build: cql develop-34ae741a-20190415161544 linux amd64 go1.11.5 + Enter master key(press Enter for default: ""): + + INFO[0008] init config success path=/home/levente/.cql/config.yaml + INFO[0008] use public key in config file: /home/levente/.cql/config.yaml + INFO[0008] cpu: 8 + INFO[0008] position: 3, shift: 0x20, i: 7 + INFO[0008] position: 0, shift: 0x0, i: 0 + INFO[0008] position: 3, shift: 0x0, i: 6 + INFO[0008] position: 1, shift: 0x0, i: 2 + INFO[0008] position: 2, shift: 0x0, i: 4 + INFO[0008] position: 1, shift: 0x20, i: 3 + INFO[0008] position: 2, shift: 0x20, i: 5 + INFO[0008] position: 0, shift: 0x20, i: 1 + nonce: {{1251426 4506240821 0 0} 25 00000041bc2b3de3bcb96328d0004c684628a908f0233eb31fe9998ef0c6288e} + node id: 00000041bc2b3de3bcb96328d0004c684628a908f0233eb31fe9998ef0c6288e + + +> This functionality is usually not used in common scene + +### Sub-command `idminer` Complete Parameters + + usage: cql idminer [parameter]... + + IDMiner command can calculate legal node id and it's nonce. Default 24 difficulty and no endless loop. + e.g. + cql idminer -difficulty 24 + + If you want to mine a good id, use: + cql idminer -config ~/.cql/config.yaml -loop -difficulty 24 + + Params: + -difficulty int + the difficulty for a miner to mine nodes and generating a nonce (default 24) + -loop + mining endless loop + + +## Wallet Management + +### Wallet Address + +Once the private key and config file is set, we can use sub-command `wallet` to check the wallet address of the account: + +```bash +cql wallet +``` + +Output: + + Enter master key(press Enter for default: ""): + + wallet address: 43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 + + +The wallet address of the test account here is `43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40`. + +### Wallet Balances + +We can also use sub-command `wallet` to check the balances in the wallet. CovenantSQL currently supports 5 types of tokens: + +- `Particle` +- `Wave` +- `Bitcoin` +- `Ether` +- `EOS` + +Among them, `Particle` and `Wave` are the token types used by CovenantSQL. To check the token balances, use: + +```bash +cql wallet -balance all +``` + +Output: + + INFO[0000] Particle balance is: 10000000000000000000 + INFO[0000] Wave balance is: 10000000000000000000 + + +You can also check the balance of a specified type of token, e.g., checking the balance of `Bitcoin`: + +```bash +cql wallet -balance Bitcoin +``` + +Output: + + INFO[0000] Bitcoin balance is: 0 + + +### Transferring Tokens to Another Account + +Once you get tokens from [TestNet](quickstart) or [Docker Environment by One-Click](deployment), you can use the `transfer` sub-command to transfer tokens to another account. The command takes a `json` format meta info as its main parameter, e.g.: + +```json +{ + "addr": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // Receiver wallet address + "amount": "1000000 Particle" // Transfer amount with token type +} +``` + +Note that the receiver wallet address could be a user account address or a database address -- we treat the database as a special kind of account. While transferring to a database, the tokens will be used as the deposit and advance payment of that database for the sender. + +> Check more detailed knowledge about [Deposit and Advance Payment](terms#deposit-and-advance-payment). + +Pass the parameter to `transfer`: + +```bash +cql transfer '{"addr": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount": "1000000 Particle"}' +``` + +Output: + + INFO[0000] succeed in sending transaction to CovenantSQL + + +Note that the above output message indicates that the transfer request is successfully sent to CovenantSQL network, but it will take a while before the block producers actually execute and confirm the transaction to take effect. You can use the `cql wallet -balance ` command again to check if the request takes effect, or add `-wait-tx-confirm` parameter to make `cql` wait for transaction confirmation before exit. + +### Sub-command `wallet` Complete Parameters + + usage: cql wallet [-config file] [-balance token_name] + + Wallet command can get CovenantSQL wallet address and the token balance of the current account + e.g. + cql wallet + + cql wallet -balance Particle + cql wallet -balance all + + Params: + -balance string + Get a specific token's balance of the current account, e.g. Particle, Wave, and etc. + + +### Sub-command `transfer` Complete Parameters + + usage: cql transfer [-config file] [-wait-tx-confirm] meta_json + + Transfer command can transfer your token to the target account. + The command argument is JSON meta info of a token transaction. + e.g. + cql transfer '{"addr":"your_account_addr","amount":"100 Particle"}' + + Since CovenantSQL is based on blockchain, you may want to wait for the transaction confirmation. + e.g. + cql transfer -wait-tx-confirm '{"addr":"your_account_addr","amount":"100 Particle"}' + + Params: + -wait-tx-confirm + Wait for transaction confirmation + + +## Database Management + +### Creating Database + +Like `transfer`, `create` takes a `json` format main parameter. Create a database with one miner node with: + +```bash +cql create '{"node": 1}' +``` + +Output: + + Enter master key(press Enter for default: ""): + + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + + +Here `covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` is the database source name (DSN) of the created database. And the `covenantsql` part is the scheme, which can be `cql` in abbreviation. The hex string after `://` is the database address, which can be used as a receiver address in `transfer` command. + +The sub-command `create` sends transactions to block producers to create databases, so it has a `wait-tx-confirm` parameter too. + +For a complete help message, check [Complete Parameters](#sub-command-create-complete-parameters). + +### ~~Deleting Database~~ + +~~Not yet implemented.~~ + +### Granting Permission + +#### Access Permission + +CovenantSQL database has 3 kinds of access permission: + +- `Admin` +- `Write` +- `Read` +- `Void` (for none) + +Among them, `Admin` is the permission that can assign permissions (`Admin`, `Write`, or `Read`) to the other accounts. `Admin` and `Write` allows the write queries (such as `CREATE`, `INSERT`, and etc.). `Admin` and `Read` allows the read queries (such as `SHOW`, `SELECT`, and etc.). If you want to allow a user to read/write the database but not allow to modify the permissions of itself or other accounts, you can assign the user permission as `Read,Write`. `Void` is a special kind of permission which means 'no permission'. Once the `Admin` sets the permission of an account as `Void`, it will no longer able to read or write the database. The account who creates the database will be granted the initial `Admin` permission by default. + +Assume that you have created a database `covenantsql:\\4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5` with default account, and have generated another account under directory `account2` which has the address `011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6`. Now you can grant permissions to `accounts` to access the database, with the `json` format main parameter as following: + +```json +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", // Target database adderss to give permission + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // Target wallet address to get permission + "perm": "Read,Write" // Permission, separated by commas +} +``` + +Pass the parameter to `grant`: + +```bash +cql grant '{"chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", "perm": "Read,Write"}' +``` + +Output: + + INFO[0000] succeed in sending transaction to CovenantSQL + + +Or revoke the permission: + +```bash +cql grant '{"chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", "perm": "Void"}' +``` + +Output: + + INFO[0000] succeed in sending transaction to CovenantSQL + + +The sub-command `grant` sends transactions to block producers to request permission granting, so it has a `wait-tx-confirm` parameter too. + +Since the database separately keeps billing for each user, you need to transfer tokens to the database (as user deposit and advance payment) from the new account before it can actually get access to the database. The minimum amount of deposit and advance payment can be calculated by: `gas_price*number_of_miner*120000`. + +Transferring from `account2` to the database: + +```bash +cql -config "account2/config.yaml" transfer '{"addr": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","amount": "90000000 Particle"}' +``` + +#### SQL White List + +CovenantSQL supports white list setting for each of its users. By setting up SQL white list, you can further limit the access permission of a user to a given list of SQL Patterns with assignable parameters. With this feature, your database can be further secured because it avoids important data breach and accidentally updating/deleting. + +Adding a white list: + +```bash +cql grant ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": { + "patterns": [ + "SELECT COUNT(1) FROM a", + "SELECT * FROM a WHERE id = ? LIMIT 1" + ], + "role": "Read,Write" + } +} +' +``` + +*SQL White List is an extension of the database permission system. It currently doesn't support incrementally updating, so you need to provide the complete permission information each time you use the `grant` sub-command* + +Cleaning the white list: + +```bash +cql grant ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": { + "patterns": nil, + "role": "Read,Write" + } +} +' +# or +cql grant ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": "Read,Write" +} +' +``` + +Either setting the `pattern` field to `nil` or just resetting the user permission directly, will eliminate the white list and give back the access permission to the user. + +### Sub-command `create` Complete Parameters + + usage: cql create [parameters]... db_meta_json + + Create CovenantSQL database by database meta info JSON string, meta info must include node count. + e.g. + cql create '{"node":2}' + + A complete introduction of db_meta_json fields： + targetminers []string // List of target miner addresses + node int // Target node number + space int // Minimum disk space requirement, 0 for none + memory int // Minimum memory requirement, 0 for none + loadavgpercpu float // Minimum idle CPU requirement, 0 for none + encryptionkey string // Encryption key for persistence data + useeventualconsistency bool // Use eventual consistency to sync among miner nodes + consistencylevel float // Consistency level, node*consistencylevel is the node number to perform strong consistency + isolationlevel int // Isolation level in a single node + + Since CovenantSQL is blockchain database, you may want get confirm of creation. + e.g. + cql create -wait-tx-confirm '{"node": 2}' + + Params: + -wait-tx-confirm + Wait for transaction confirmation + + +### Sub-command `drop` Complete Parameters + + usage: cql drop [parameter]... dsn/dbid + + Drop command can drop a database by DSN or database id + e.g. + cql drop covenantsql://the_dsn_of_your_database + + Since CovenantSQL is blockchain database, you may want get confirm of drop operation. + e.g. + cql drop -wait-tx-confirm covenantsql://the_dsn_of_your_database + + Params: + -wait-tx-confirm + Wait for transaction confirmation + + +### Sub-command `grant` Complete Parameters + + usage: cql grant [parameter]... permission_meta_json + + Grant command can give a user some specific permissions on your database + e.g. + cql grant '{"chain": "your_chain_addr", "user": "user_addr", "perm": "perm_struct"}' + + Since CovenantSQL is blockchain database, you may want get confirm of permission update. + e.g. + cql grant -wait-tx-confirm '{"chain":"your_chain_addr","user":"user_addr","perm":"perm_struct"}' + + Params: + -wait-tx-confirm + Wait for transaction confirmation + + +## Accessing Database + +Once your database is successfully created, you can use the `console` sub-command to access it in an interactive console: + +```bash +cql console -dsn 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + Enter master key(press Enter for default: ""): + + INFO[0010] init config success path=/home/levente/.cql/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-34ae741a-20190416184528) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Or access as `account2` if it has successfully been granted access permission: + +```bash +cql console -config "account2/config.yaml" -dsn 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + Enter master key(press Enter for default: ""): + + INFO[0010] init config success path=/home/levente/.config/cql/account2/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-34ae741a-20190416184528) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Here is an example of using the interactive console: + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> create table t1 (c1 int); + CREATE TABLE + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> insert into t1 values (1), (2), (3); + INSERT + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> select * from t1; + c1 + ---- + 1 + 2 + 3 + (3 rows) + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +### Sub-command `console` Complete Parameters + +The sub-command `console` also supports running `adapter` or `explorer` servers in the background. Check [Local Servers](#local-servers) for details. + + usage: cql console [parameter]... + + Console command can run a interactive SQL console for CovenantSQL + e.g. + cql console -dsn covenantsql://the_dsn_of_your_database + + There is also a -command param for SQL script, and a -file param for reading SQL in a file. + If those params are set, it will run SQL script and exit without staying console mode. + e.g. + cql console -dsn covenantsql://the_dsn_of_your_database -command "create table test1(test2 int);" + + Params: + -adapter string + Address to serve a database chain adapter, e.g.:7784 + -command string + Run only single command (SQL or usql internal command) and exit + -dsn string + Database url + -explorer string + Address to serve a database chain explorer, e.g.:8546 + -file string + Execute commands from file and exit + -no-rc + Do not read startup file + -out string + Record stdout to file + -single-transaction + Execute as a single transaction (if non-interactive) + -variable value + Set variable + + +## Local Servers + +### Sub-command `explorer` Complete Parameter + + usage: cql explorer [parameter]... address + + Explorer command serves a SQLChain web explorer. + e.g. + cql explorer 127.0.0.1:8546 + + Params: + -bg-log-level string + Background service log level + -tmp-path string + Background service temp file path, use os.TempDir for default + + +### Sub-command `mirror` Complete Parameter + + usage: cql mirror [parameter]... dsn/dbid address + + Mirror command subscribes database updates and serves a read-only database mirror. + e.g. + cql mirror database_id 127.0.0.1:9389 + + Params: + -bg-log-level string + Background service log level + -tmp-path string + Background service temp file path, use os.TempDir for default + + +### Sub-command `adapter` Complete Parameter + +See for details of adapter server. + + usage: cql adapter [parameter]... address + + Adapter command serves a SQLChain adapter + e.g. + cql adapter 127.0.0.1:7784 + + Params: + -bg-log-level string + Background service log level + -mirror string + mirror server for the target adapter to query + -tmp-path string + Background service temp file path, use os.TempDir for default + + +## Advance Usage + +Sub-command `rpc` calls the remote process directly in the CovenantSQL network. + +### Sub-command `rpc` Complete Parameter + + usage: cql rpc [parameter]... + + Rpc command make a RPC request to the target server + e.g. + cql rpc -name 'MCC.QuerySQLChainProfile' \ + -endpoint 000000fd2c8f68d54d55d97d0ad06c6c0d91104e4e51a7247f3629cc2a0127cf \ + -req '{"DBID": "c8328272ba9377acdf1ee8e73b17f2b0f7430c798141080d0282195507eb94e7"}' + + Params: + -endpoint string + RPC endpoint to do a test call + -name string + RPC name to do a test call + -req string + RPC request to do a test call, in json format + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/cql_account.md b/website/translated_docs/zh-CN/cql_account.md new file mode 100644 index 0000000..a9fcc19 --- /dev/null +++ b/website/translated_docs/zh-CN/cql_account.md @@ -0,0 +1,143 @@ +--- +id: cql_account +title: Account Management +--- + +For the TestNet environment, we provide a public account for quick testing. Check the [CovenantSQL TestNet](quickstart) tutorial to find out the private key and config file of the public account. And you can also follow the next section to create an individual account with `cql` command. + +## Creating New Account + +The sub-command `generate` generates a private key file and a config file connecting to the TestNet in the specified directory, e.g.: + +```bash +cql generate +``` + +> Currently, the generated config file is pointed to the TestNet, we will provide options to generated config for Docker Environment later. + +For a complete help message, check [Complete Parameters](#sub-command-generate-complete-parameters). + +Output: + + Generating private key... + Please enter password for new private key + Generated private key. + Generating nonce... + INFO cpu: 4 + INFO position: 2, shift: 0x0, i: 2 + INFO position: 0, shift: 0x0, i: 0 + INFO position: 3, shift: 0x0, i: 3 + INFO position: 1, shift: 0x0, i: 1 + nonce: {{973366 0 586194564 0} 26 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b} + node id: 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b + Generated nonce. + Generating config file... + Generated config. + + Config file: ~/.cql/config.yaml + Private key file: ~/.cql/private.key + Public key's hex: 03f195dfe6237691e724bcf54359d76ef388b0996a3de94a7e782dac69192c96f0 + + Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + Any further command could costs PTC. + You can get some free PTC from: + https://testnet.covenantsql.io/wallet/dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + +### Public Key + +Generate command also print public key (in hex string format) of the private key file, e.g.: + +Output： + + Public key's hex: 03f195dfe6237691e724bcf54359d76ef388b0996a3de94a7e782dac69192c96f0 + + +> This info is usually not used in common scene. + +### Wallet address + +Generate command shows wallet address (in hex string format) and will store in `config.yaml` file, e.g.: + +Output： + + Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + Any further command could costs PTC. + You can get some free PTC from: + https://testnet.covenantsql.io/wallet/dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + +After get a wallet address, you may need to request PTC as above. + +## Sub-command `generate` Complete Parameters + +Also see [Common Parameters for Sub-commands](cql_intro#common-parameters-for-sub-commands). We will not mention this again in the later sub-command introductions. + + usage: cql generate [common params] [-source template_file] [-miner] [-private existing_private_key] [dest_path] + + Generate generates private.key and config.yaml for CovenantSQL. + You can input a passphrase for local encrypt your private key file by set -with-password + e.g. + cql generate + + or input a passphrase by + + cql generate -with-password + + Generate params: + -miner string + Generate miner config with specified miner address + -private string + Generate config using an existing private key + -source string + Generate config using the specified config template + + +## Mine a Node ID + +The sub-command `idminer` is used to mine another Node ID of a private key (specified by a config file), (also check [Node ID](terms#node-id) for details). e.g.: + +```bash +cql idminer +``` + +Output: + + INFO[0000] cql build: cql develop-34ae741a-20190415161544 linux amd64 go1.11.5 + Enter master key(press Enter for default: ""): + + INFO[0008] init config success path=/home/levente/.cql/config.yaml + INFO[0008] use public key in config file: /home/levente/.cql/config.yaml + INFO[0008] cpu: 8 + INFO[0008] position: 3, shift: 0x20, i: 7 + INFO[0008] position: 0, shift: 0x0, i: 0 + INFO[0008] position: 3, shift: 0x0, i: 6 + INFO[0008] position: 1, shift: 0x0, i: 2 + INFO[0008] position: 2, shift: 0x0, i: 4 + INFO[0008] position: 1, shift: 0x20, i: 3 + INFO[0008] position: 2, shift: 0x20, i: 5 + INFO[0008] position: 0, shift: 0x20, i: 1 + nonce: {{1251426 4506240821 0 0} 25 00000041bc2b3de3bcb96328d0004c684628a908f0233eb31fe9998ef0c6288e} + node id: 00000041bc2b3de3bcb96328d0004c684628a908f0233eb31fe9998ef0c6288e + + +> This functionality is usually not used in common scene. + +## Sub-command `idminer` Complete Parameters + + usage: cql idminer [common params] [-difficulty number] [-loop [true]] + + IDMiner calculates legal node id and it's nonce. Default parameters are difficulty of 24 and no endless loop. + e.g. + cql idminer -difficulty 24 + + If you want to mine a good id, use: + cql idminer -config ~/.cql/config.yaml -loop -difficulty 24 + + Params: + -difficulty int + the difficulty for a miner to mine nodes and generating a nonce (default 24) + -loop + mining endless loop \ No newline at end of file diff --git a/website/translated_docs/zh-CN/cql_advance.md b/website/translated_docs/zh-CN/cql_advance.md new file mode 100644 index 0000000..2ee6744 --- /dev/null +++ b/website/translated_docs/zh-CN/cql_advance.md @@ -0,0 +1,28 @@ +--- +id: cql_advance +title: Advanced Usage +--- + +Sub-command `rpc` calls the remote process directly in the CovenantSQL network. + +## Sub-command `rpc` Complete Parameter + + usage: cql rpc [common params] [-wait-tx-confirm] [-endpoint rpc_endpoint | -bp] -name rpc_name -req rpc_request + + RPC makes a RPC request to the target endpoint. + e.g. + cql rpc -name 'MCC.QuerySQLChainProfile' \ + -endpoint 000000fd2c8f68d54d55d97d0ad06c6c0d91104e4e51a7247f3629cc2a0127cf \ + -req '{"DBID": "c8328272ba9377acdf1ee8e73b17f2b0f7430c798141080d0282195507eb94e7"}' + + RPC params: + -bp + Call block producer node + -endpoint string + RPC endpoint Node ID to do test call + -name string + RPC name to do test call + -req string + RPC request to do test call, in json format + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/cql_db_access.md b/website/translated_docs/zh-CN/cql_db_access.md new file mode 100644 index 0000000..7ef0d9d --- /dev/null +++ b/website/translated_docs/zh-CN/cql_db_access.md @@ -0,0 +1,84 @@ +--- +id: cql_db_access +title: Accessing Database +--- + +Once your database is successfully created, you can use the `console` sub-command to access it in an interactive console: + +```bash +cql console 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io + INFO[0010] init config success path=~/.cql/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-da3af8f6-20190515152207) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Or access as `account2` (Should been granted access permission and transfered deposit token to the database successfully in last section): + +```bash +cql console -config "account2/config.yaml" 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io + INFO[0010] init config success path=~/.config/cql/account2/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-da3af8f6-20190515152207) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Here is an example of using the interactive console: + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> create table t1 (c1 int); + CREATE TABLE + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> insert into t1 values (1), (2), (3); + INSERT + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> select * from t1; + c1 + ---- + 1 + 2 + 3 + (3 rows) + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +## Sub-command `console` Complete Parameters + +The sub-command `console` also supports running `adapter` or `explorer` servers in the background. Check [Local Servers](#local-servers) for details. + + usage: cql console [common params] [Console params] dsn + + Console runs an interactive SQL console for CovenantSQL. + e.g. + cql console covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + There is also a -command param for SQL script, and you can add "< file.sql" at end of command for executing a SQL file. + If those params are set, it will run SQL script and exit without staying console mode. + e.g. + cql console -command "create table test1(test2 int);" covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + Console params: + -adapter string + Address to serve a database chain adapter, e.g. :7784 + -command string + Run only single command (SQL or usql internal command) and exit + -explorer string + Address serve a database chain explorer, e.g. :8546 + -out string + Record stdout to file + -single-transaction + Execute as a single transaction (if non-interactive) + -variable value + Set variable \ No newline at end of file diff --git a/website/translated_docs/zh-CN/cql_db_manage.md b/website/translated_docs/zh-CN/cql_db_manage.md new file mode 100644 index 0000000..7a06d00 --- /dev/null +++ b/website/translated_docs/zh-CN/cql_db_manage.md @@ -0,0 +1,243 @@ +--- +id: cql_db_manage +title: Database Management +--- + +## Creating Database + +Like `transfer`, `create` takes several parameters. e.g. Create a database with one miner node: + +```bash +cql create -db-node 1 +``` + +Output: + + INFO[0000] Geting bp address from dns: bp00.testnet.gridb.io + INFO[0048] Register self to blockproducer: 00000000000589366268c274fdc11ec8bdb17e668d2f619555a2e9c1a29c91d8 + INFO init config success path=~/.cql/config.yaml + INFO create database requested + + The newly created database is: "covenantsql://962bbb3a8028a203e99121d23173a38fa24a670d52c8775a9d987d007a767ce4" + The connecting string beginning with 'covenantsql://' could be used as a dsn for `cql console` + or any command, or be used in website like https://web.covenantsql.io + + +Here `covenantsql://962bbb3a8028a203e99121d23173a38fa24a670d52c8775a9d987d007a767ce4` is the database source name (DSN) of the created database. And the `covenantsql` part is the scheme, which can be `cql` in abbreviation. The hex string after `://` is the database address, which can be used as a receiver address in `transfer` command. + +The sub-command `create` sends transactions to block producers to create databases, so it has a `wait-tx-confirm` parameter too. + +For a complete help message, check [Complete Parameters](#sub-command-create-complete-parameters). + +## Billing + +CovenantSQL uses Gas for billing just like the [Ethereum Gas](https://www.ethos.io/what-is-ethereum-gas/). The gas unit (a.k.a., the `Gas-Price`) in stable token `Particle` is specified while creating the database, and its corresponding field is `-db-gas-price`. If not specified in the parameter, it will be set as 1 by default. Another billing-related field is `-db-advance-payment`, which will be used as deposit and query expending. The default advance payment is 20,000,000. Creating a database with specified `Gas-Price` and `Advance-Payment`: + +```bash +cql create -db-node 2 -db-gas-price 5 -db-advance-payment 500000000 +``` + +Thus we created a new database with `Gas-Price` 5 and `Advance-Payment` 500,000,000. Note that when the CovenantSQL network is short of miner resources, setting a higher `Gas-Price` will help your creation request to be accepted earlier, but it will cost you more tokens of course. + +> At present, we only accept the CovenantSQL stable token Particle for database billing. More token types will be supported soon. + +And the billing is processed as following: + +- For a Read request, the result `rows_count` is counted as the `Gas` cost +- For a Write request, the result `affected_rows` is counted as the `Gas` cost +- The SQLChain miner does periodic billing, sums up, and reports the `Gas` cost to the main chain, and the main chain verifies and deducts `Gas` * `Gas Price` tokens from the user accounts + +## ~~Deleting Database~~ + +~~Not yet implemented.~~ + +## Granting Permission + +### Access Permission + +CovenantSQL database has 3 kinds of access permission: + +- `Admin` +- `Write` +- `Read` +- `Void` (for none) + +Among them, `Admin` is the permission that can assign permissions (`Admin`, `Write`, or `Read`) to the other accounts. `Admin` and `Write` allows the write queries (such as `CREATE`, `INSERT`, and etc.). `Admin` and `Read` allows the read queries (such as `SHOW`, `SELECT`, and etc.). If you want to allow a user to read/write the database but not allow to modify the permissions of itself or other accounts, you can assign the user permission as `Read,Write`. `Void` is a special kind of permission which means 'no permission'. Once the `Admin` sets the permission of an account as `Void`, it will no longer able to read or write the database. The account who creates the database will be granted the initial `Admin` permission by default. + +Assume that you have created a database `covenantsql:\\4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5` with default account, and have generated another account under directory `account2` which has the address `011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6`. Now you can grant permissions to `accounts` to access the database, with parameters as following: + +```bash +`-to-dsn` Target database adderss to give permission +`-to-user` Target wallet address to get permission +`-perm` Permission, separated by commas +``` + +Pass the parameter to `grant`: + +```bash +cql grant -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 \ + -perm "Read,Write" +``` + +Output: + + INFO[0000] Geting bp address from dns: bp04.testnet.gridb.io + INFO[0003] Self register to blockproducer: 00000000003b2bd120a7d07f248b181fc794ba8b278f07f9a780e61eb77f6abb + INFO init config success path=~/.cql/config.yaml + INFO succeed in grant permission on target database + + +Or revoke the permission: + +```bash +cql grant -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 \ + -perm "Void" +``` + +Output: + + INFO[0000] Geting bp address from dns: bp04.testnet.gridb.io + INFO[0003] Self register to blockproducer: 00000000003b2bd120a7d07f248b181fc794ba8b278f07f9a780e61eb77f6abb + INFO init config success path=~/.cql/config.yaml + INFO succeed in grant permission on target database + + +The sub-command `grant` sends transactions to block producers to request permission granting, so it has a `wait-tx-confirm` parameter too. + +Since the database separately keeps billing for each user, you need to transfer tokens to the database (as user deposit and advance payment) from the new account before it can actually get access to the database. The minimum amount of deposit and advance payment can be calculated by: `gas_price*number_of_miner*120000`. + +Transferring from `account2` to the database: + +```bash +cql transfer -config "account2/config.yaml" \ + -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -amount 90000000 \ + -token Particle +``` + +### SQL White List + +CovenantSQL supports white list setting for each of its users. By setting up SQL white list, you can further limit the access permission of a user to a given list of SQL Patterns with assignable parameters. With this feature, your database can be further secured because it avoids important data breach and accidentally updating/deleting. + +Adding a white list: + +```bash +cql grant -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 \ + -perm ' +{ + "patterns": [ + "SELECT COUNT(1) FROM a", + "SELECT * FROM a WHERE id = ? LIMIT 1" + ], + "role": "Read,Write" +} +' +``` + +*SQL White List is an extension of the database permission system. It currently doesn't support incrementally updating, so you need to provide the complete permission information each time you use the `grant` sub-command* + +Cleaning the white list: + +```bash +
cql grant -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 \ + -perm ' +{ + "patterns": null, + "role": "Read,Write" +} +' + + or + +cql grant -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 \ + -perm "Read,Write" +``` + +Either setting the `pattern` field to `null` or just resetting the user permission directly, will eliminate the white list and give back the access permission to the user. + +## Sub-command `create` Complete Parameters + + usage: cql create [common params] [-wait-tx-confirm] [db_meta_params] + + Create command creates a CovenantSQL database by database meta params. The meta info must include + node count. + e.g. + cql create -db-node 2 + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction + confirmation before the creation takes effect. + e.g. + cql create -wait-tx-confirm -db-node 2 + + DB meta params: + -db-advance-payment uint + Customized advance payment + -db-consistency-level float + Consistency level, node*consistency_level is the node count to perform strong consistency + -db-encrypt-key string + Encryption key for persistence data + -db-eventual-consistency + Use eventual consistency to sync among miner nodes + -db-gas-price uint + Customized gas price + -db-isolation-level int + Isolation level in a single node + -db-load-avg-per-cpu float + Minimum idle CPU requirement, 0 for none + -db-memory uint + Minimum memory requirement, 0 for none + -db-node uint + Target node count + -db-space uint + Minimum disk space requirement, 0 for none + -db-target-miners value + List of target miner addresses(separated by ',') + -wait-tx-confirm + Wait for transaction confirmation + + +## Sub-command `drop` Complete Parameters + + usage: cql drop [common params] [-wait-tx-confirm] dsn + + Drop drops a CovenantSQL database by DSN or database ID. + e.g. + cql drop covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction + confirmation before the drop operation takes effect. + e.g. + cql drop -wait-tx-confirm covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + Drop params: + -wait-tx-confirm + Wait for transaction confirmation + + +## Sub-command `grant` Complete Parameters + + usage: cql grant [common params] [-wait-tx-confirm] [-to-user wallet] [-to-dsn dsn] [-perm perm_struct] + + Grant grants specific permissions for the target user on target dsn. + e.g. + cql grant -to-user=43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 -to-dsn="covenantsql://xxxx" -perm perm_struct + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction + confirmation before the permission takes effect. + e.g. + cql grant -wait-tx-confirm -to-user=43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 -to-dsn="covenantsql://xxxx" -perm perm_struct + + Grant params: + -perm string + Permission type struct for grant. + -to-dsn string + Target database dsn to grant permission. + -to-user string + Target address of an user account to grant permission. + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/cql_intro.md b/website/translated_docs/zh-CN/cql_intro.md new file mode 100644 index 0000000..98eb6a6 --- /dev/null +++ b/website/translated_docs/zh-CN/cql_intro.md @@ -0,0 +1,40 @@ +--- +id: cql_intro +title: Overview +--- + +CovenantSQL provides a `cql` command line toolset for terminal users to access and manage user accounts, wallet balances, and databases. Check the complete toolset installation tutorial at \[CovenantSQL Toolset installation\](quickstart#工具包安装). + +## Private Key and Config File + +The `cql` command needs to rely on a private key file `private.key` and a config file `config.yaml`: + +- `private.key`：a private key file which is generated while creating an account, be sure to keep it safe +- `config.yaml`：mainly used to config the CovenantSQL network for `cql` command to connect (e.g., the [TestNet](quickstart) or the [Private Deploy](advanced_deployment)) + +For security, the private key file is usually encrypted with a master key. A master key is individually chosen by the user while creating an account and is memorized or kept somewhere by the user -- note that the config file will not keep the master key. When the private key is required by the `cql` command, it will ask the user to input the master key to decrypt the private key file. + +## Command Format + +The `cql` command has more than a dozen subcommands, each one follows the same command format. e.g: + + cql sub-command [common parameters] [subcommand parameters] arguments + + +The content of `arguments` may be empty, but it must be placed at the end of the command when it is not empty. + +## Common Parameters for Sub-commands + +The following parameters are commonly used by `cql` sub-commands: + + -config string + Config file for covenantsql (Usually no need to set, default is enough.) (default "~/.cql/config.yaml") + -with-password + Use passphrase for private.key + -password string + Master key for covenantsql (NOT SAFE, for debugging or script mode only) + -help + Show help message + + +Note that the private key file path is specified in the config file, and its default value is `./private.key`, indicating that it's located in the same directory of the config. So usually we put the private key file together with config, instead of using an individual parameter to specify the private key file. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/cql_server.md b/website/translated_docs/zh-CN/cql_server.md new file mode 100644 index 0000000..a7fe66c --- /dev/null +++ b/website/translated_docs/zh-CN/cql_server.md @@ -0,0 +1,52 @@ +--- +id: cql_server +title: Local Servers +--- + +## Sub-command `explorer` Complete Parameter + + usage: cql explorer [common params] [-tmp-path path] [-bg-log-level level] listen_address + + Explorer serves a SQLChain web explorer. + e.g. + cql explorer 127.0.0.1:8546 + + Explorer params: + -bg-log-level string + Background service log level: trace debug info warning error fatal panic (default "info") + -tmp-path string + Background service temp file path, use "dirname $(mktemp -u)" to check it out + + +## Sub-command `mirror` Complete Parameter + + usage: cql mirror [common params] [-tmp-path path] [-bg-log-level level] dsn listen_address + + Mirror subscribes database updates and serves a read-only database mirror. + e.g. + cql mirror dsn 127.0.0.1:9389 + + Mirror params: + -bg-log-level string + Background service log level: trace debug info warning error fatal panic (default "info") + -tmp-path string + Background service temp file path, use "dirname $(mktemp -u)" to check it out + + +## Sub-command `adapter` Complete Parameter + +See for details of adapter server. + + usage: cql adapter [common params] [-tmp-path path] [-bg-log-level level] [-mirror addr] listen_address + + Adapter serves a SQLChain adapter. + e.g. + cql adapter 127.0.0.1:7784 + + Adapter params: + -bg-log-level string + Background service log level: trace debug info warning error fatal panic (default "info") + -mirror string + Mirror server for adapter to query + -tmp-path string + Background service temp file path, use "dirname $(mktemp -u)" to check it out \ No newline at end of file diff --git a/website/translated_docs/zh-CN/cql_wallet.md b/website/translated_docs/zh-CN/cql_wallet.md new file mode 100644 index 0000000..5053648 --- /dev/null +++ b/website/translated_docs/zh-CN/cql_wallet.md @@ -0,0 +1,130 @@ +--- +id: cql_wallet +title: Wallet Management +--- + +## Wallet Address + +Once the private key and config file is set, you can use sub-command `wallet` to check the wallet address of the account: + +```bash +cql wallet +``` + +Output: + + INFO[0000] Geting bp address from dns: bp00.testnet.gridb.io + INFO[0003] Register self to blockproducer: 00000000000589366268c274fdc11ec8bdb17e668d2f619555a2e9c1a29c91d8 + INFO init config success path=~/.cql/config.yaml + + + wallet address: 290f7dbbff2aa0d5a5af65f4caa0bfd68663f97f9b08d0ee71e76a172349b613 + Particle balance is: 100000000 + Wave balance is: 0 + found no related database + + +The wallet address of the test account here is `290f7dbbff2aa0d5a5af65f4caa0bfd68663f97f9b08d0ee71e76a172349b613`. And balances are also shown. + +## Wallet Balances + +CovenantSQL currently supports 5 types of tokens: + +- `Particle` +- `Wave` +- `Bitcoin` +- `Ether` +- `EOS` + +Among them, `Particle` and `Wave` are the token types used by CovenantSQL. You can also check the balance of a specified type of token, e.g., checking the balance of `Bitcoin`: + +```bash +cql wallet -token Bitcoin +``` + +Output: + + INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io + INFO[0006] Register self to blockproducer: 0000000000293f7216362791b6b1c9772184d6976cb34310c42547735410186c + INFO init config success path=~/.cql/config.yaml + + wallet address: 290f7dbbff2aa0d5a5af65f4caa0bfd68663f97f9b08d0ee71e76a172349b613 + Bitcoin balance is: 0 + + +## Transferring Tokens to Another Account + +Once you get tokens from [TestNet](quickstart) or [Private Deploy](advanced_deployment), you can use the `transfer` sub-command to transfer tokens to another account. The command takes 3 main parameters, e.g.: + +```bash +cql transfer -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 -amount 1000000 -token Particle +``` + +`-to-user` is set for other user's wallet address, `-amount` param is for token count, and `-token` is for token type + +## Transferring Tokens to a database + +If you want to transfer token to a database address, replace `-to-user` to `-to-dsn`, and set a CovenantSQL dsn string. e.g. + +```bash +cql transfer -to-dsn covenantsql://0bfea233d20676bb848b66d072bb768945507bb8a3b8b22b13133cde0583e208 -amount 1000000 -token Particle +``` + +While transferring to a database, the tokens will be used as the deposit and advance payment of that database for the sender. + +> Check more detailed knowledge about [Deposit and Advance Payment](terms#deposit-and-advance-payment). + +Output: + + INFO[0000] Geting bp address from dns: bp04.testnet.gridb.io + INFO[0043] Register self to blockproducer: 00000000003b2bd120a7d07f248b181fc794ba8b278f07f9a780e61eb77f6abb + INFO init config success path=~/.cql/config.yaml + INFO succeed in sending transaction to CovenantSQL + + +Note that the above output message indicates that the transfer request is successfully sent to CovenantSQL network, but it will take a while before the block producers actually execute and confirm the transaction to take effect. You can use the `cql wallet -token ` command again to check if the request takes effect, or add `-wait-tx-confirm` parameter to make `cql` wait for transaction confirmation before exit. + +## Sub-command `wallet` Complete Parameters + + usage: cql wallet [common params] [-token type] [-dsn dsn] + + Wallet gets the CovenantSQL wallet address and the token balances of the current account. + e.g. + cql wallet + + cql wallet -token Particle + + cql wallet -dsn "covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c" + + Wallet params: + -dsn string + Show specified database deposit + -token string + Get specific token's balance of current account, e.g. Particle, Wave, All + + +## Sub-command `transfer` Complete Parameters + + usage: cql transfer [common params] [-wait-tx-confirm] [-to-user wallet | -to-dsn dsn] [-amount count] [-token token_type] + + Transfer transfers your token to the target account or database. + The command arguments are target wallet address(or dsn), amount of token, and token type. + e.g. + cql transfer -to-user=43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 -amount=100 -token=Particle + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction + confirmation before the transfer takes effect. + e.g. + cql transfer -wait-tx-confirm -to-dsn=43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 -amount=100 -token=Particle + + Transfer params: + -amount uint + Token account to transfer. + -to-dsn string + Target database dsn to transfer token. + -to-user string + Target address of an user account to transfer token. + -token string + Token type to transfer. + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/deploy_miner.md b/website/translated_docs/zh-CN/deploy_miner.md new file mode 100644 index 0000000..7ba546d --- /dev/null +++ b/website/translated_docs/zh-CN/deploy_miner.md @@ -0,0 +1,407 @@ +* * * + +id: deploy_miner title: Deploy custom miner + +* * * + +## 部署 CovenantSQL Miner 节点 + +文档对应版本： + + covenantsql/covenantsql e87bfd412293 + + +本教程可以为中国测试网(testnet cn)或者国外测试网(testnet w) 部署 miner 节点，注意区分网络环境。 + +本教程在当前目录(`$PWD`) 会产生三个目录，分别是： + + miner_config: 您自己的 miner 节点配置 + super_client_config: 测试网超级客户端配置 + client_config: 您 miner 的使用者客户端配置 + + +各个命令都会使用上述配置之一，代表了命令的执行角色。 + +### 环境依赖 + +#### 机器配置 + +推荐运行服务在 AWS 的 `c5.2xlarge` 型机器或其他同等配置的机器上 (8 核, 16 GB 内存)。 + +另外建议单独挂载数据盘用于 DB 存储。 + +#### Docker + +CovenantSQL 使用 docker 来简化部署，可通过 Docker 的 [官方文档](https://docs.docker.com/install/) 来进行安装。 + +#### Docker 镜像 + +使用 docker 获取 CovenantSQL 的服务镜像以提供数据存储节点服务 + +```shell +docker pull covenantsql/covenantsql:latest +``` + +### 配置服务 + +#### 生成 Miner 配置文件 + +执行以下命令在当前目录中创建一个 miner_config 目录，并生成 Miner 启动所需的配置文件 `config.yaml` 和 私钥 `private.key` + +> 请将命令中的 `miner_external_ip` 和 `miner_listen_port` 替换成实际 miner 运行时对外提供服务的 ip 或域名以及端口号；需要注意的是，之后使用者的命令行客户端或 Adapter 都将使用这个地址连接 Miner，请确保这个地址在使用者的机器上可以访问（没有被云平台或其他防火墙限制访问）。可以使用 telnet 或者 nc 的形式在 Miner 启动后检查服务的可用性 + +```shell +mkdir -v ./miner_config + +docker run -it --rm -v $(pwd)/miner_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + generate -miner ":" /app/config/ +``` + +> 如果需要生成国外区测试网配置，将上述命令的 `generate` 后面增加 `-testnet w` 参数。并且注意下述第一行输出会变成 `Generating testnet w config` + +命令将会生成一个 miner 的配置文件和私钥，并在命令行中输出 Miner 的节点 id、公钥 hex 和 钱包地址，例如： + +```shell +Generating testnet cn config +Generated private key. +Generating nonce... +INFO cpu: 8 +INFO position: 3, shift: 0x20, i: 7 +INFO position: 1, shift: 0x20, i: 3 +INFO position: 3, shift: 0x0, i: 6 +INFO position: 2, shift: 0x0, i: 4 +INFO position: 2, shift: 0x20, i: 5 +INFO position: 0, shift: 0x0, i: 0 +INFO position: 1, shift: 0x0, i: 2 +INFO position: 0, shift: 0x20, i: 1 +nonce: {{2677734 0 6632872946 0} 26 0000003e2c8d0b39711edf19ef266a44996b93f7f830149f5d01491a6b7da99d} +node id: 0000003e2c8d0b39711edf19ef266a44996b93f7f830149f5d01491a6b7da99d +Generated nonce. +Generating config file... +Generated config. + +Config file: /app/config/config.yaml +Private key file: /app/config/private.key +Public key's hex: 0338816967be3c24bd490f841de57f2c42daf024dd7f462305aab9a601c423ab8d +Wallet address: eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451 + +Any further command could costs PTC. +You can get some free PTC from: + https://testnet.covenantsql.io/wallet/eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451 +``` + +可以得到 miner 的钱包地址：`eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451` + +#### 给 Miner 帐户充值 + +为了大家使用方便，我们创建了一个公共使用的超级客户端节点，拥有大量测试余额，首先需要下载这个超级客户端节点的配置： + +国内测试网： + +```shell +mkdir -v ./super_client_config/ +curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql/develop/conf/testnet/config.yaml' -o ./super_client_config/config.yaml +curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql/develop/conf/testnet/private.key' -o ./super_client_config/private.key +``` + +国外测试网： + +```shell +mkdir -v ./super_client_config/ +curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql/develop/conf/testnet/w/config.yaml' -o ./super_client_config/config.yaml +curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql/develop/conf/testnet/w/private.key' -o ./super_client_config/private.key +``` + +执行以下命令将会给 miner 的钱包地址转入 `10000000000` 个 `Particle` + +> 请将命令中的 `miner_wallet_address` 替换成上一步中生成的 miner 的钱包地址，例如上例中的 `eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451` + +```shell +docker run -it --rm -v $(pwd)/super_client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + transfer -config /app/config/config.yaml \ + -wait-tx-confirm -to-user "" \ + -amount 10000000000 \ + -token Particle +``` + +命令将会从测试网帐户中划转金额给 miner 使用，miner 后续将会使用这笔费用作为押金来提供服务，将会得到类似以下的输出： + +```shell +INFO[0000] Geting bp address from dns: bp04.testnet.gridb.io +INFO[0002] Register self to blockproducer: 00000000000589366268c274fdc11ec8bdb17e668d2f619555a2e9c1a29c91d8 +INFO init config success path=/app/config/config.yaml + + +INFO wait transaction confirmation error="" tx_hash=09001b9904194400e85018984c5428616000669e5de0efac0dc65c72f11950a2 tx_state=Confirmed +INFO succeed in sending transaction to CovenantSQL +``` + +查询 miner 的账户余额以确定转账成功 + +```shell +docker run -it --rm -v $(pwd)/miner_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + wallet -config ./config/config.yaml +``` + +将会得到类似以下的输出： + +```shell +INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io +INFO[0002] Register self to blockproducer: 0000000000293f7216362791b6b1c9772184d6976cb34310c42547735410186c +INFO init config success path=/app/config/config.yaml + + +wallet address: eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451 +Particle balance is: 100000000 +Wave balance is: 0 +``` + +Particle balance 这行输出中可以看到转账的金额，这样 miner 就可以提供服务了。 + +#### 添加 Miner 可服务的用户限制 + +在默认启动的情况下，Miner 是面向全网用户提供服务的。如果只希望给指定的 Miner 提供服务，需要在 Miner 上设置 TargetUsers 配置，并指定需要服务的用户的钱包地址。 + +修改 `miner` 的配置文件 `./miner_config/config.yaml`，在 `Miner` 配置段下添加 `TargetUsers` 配置，指定一个需要服务的用户的 List，例如如下修改： + +```diff +--- old.yaml 2019-05-14 00:12:33.000000000 +0800 ++++ new.yaml 2019-05-14 00:12:19.000000000 +0800 +@@ -1,4 +1,5 @@ + Miner: + RootDir: './data' + MaxReqTimeGap: '5m' + ProvideServiceInterval: '10s' ++ TargetUsers: ['eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451'] +``` + +### 启动 Miner 服务 + +#### 创建 Container + +执行以下命令以创建 miner 的 + +> 请将下述命令中的 `miner_name` 替换成所需的 miner docker container 名用于管理；`data_disk_dir` 替换成用于存放 miner 数据的目录的绝对地址(推荐挂载一个盘用于提供服务)；`miner_listen_port` 替换成miner 对外提供服务的端口号 + +```shell +docker create --name "" \ + --restart always \ + -v $(pwd)/miner_config/:/app/config/ \ + -v ":/app/config/data/" \ + -e COVENANT_ROLE=miner \ + -e COVENANT_CONF=/app/config/config.yaml \ + -e METRIC_WEB_ADDR=0.0.0.0:4665 \ + --log-driver "json-file" \ + --log-opt "max-size=1g" \ + --log-opt "max-file=3" \ + -p ":" \ + covenantsql/covenantsql:latest +``` + +#### 启动 Miner + +> 同样，请将 `miner_name` 替换为实际使用的 miner container 名 + +```shell +docker start "" +``` + +#### 检查 Miner 状态 + +> 同样，请将 `miner_name` 替换为实际使用的 miner container 名 + +```shell +docker ps -a -f "name = " +docker logs --tail=10 -f "" +``` + +在单台或多台机器上重复上述步骤，启动多个实例，可以提供至多对应节点数量的 DB SideChain 服务。 + +#### 服务升级 + +执行以下命令更新镜像，然后重复 **创建 Container** 步骤 和 **启动 Miner** 步骤 + +```shell + docker pull covenantsql/covenantsql:latest +``` + +### 使用 + +#### 使用者账户和配置 + +使用 CovenantSQL 需要创建一个 DB 使用者的账户。这个账户必须与提供服务的 Miner 节点的账号不同，与此同时一个 Miner 账户也不能同时启动多个 Miner 服务，否则将会导致 Miner 或 DB 使用者的 Transaction 执行异常，用户不能正确创建 DB 或 Miner 不能正确上报使用者的费用信息等。 + +##### 生成使用者账户配置 + +执行如下命令将在 `./client_config` 目录下生成使用者账户的私钥和配置 + +> 如果需要生成国外区测试网配置，将上述命令的 `generate` 后面增加 `-testnet w` 参数。并且注意第一行输出会变成 `Generating testnet w config` + +```shell +mkdir -v client_config + +docker run -it --rm -v $(pwd)/client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + generate /app/config/ +``` + +命令最后一行会显示 wallet address，注意需要将此 wallet address 加入到 miner 的 `TargetUsers` 配置中，并重启 miner。 + +##### 向使用者账户中充值 + +类似向 Miner 账户充值，请执行如下命令： + +> 请将 `client_wallet_address` 替换为创建的使用者账号的钱包地址 + +```shell +docker run -it --rm -v $(pwd)/super_client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + transfer -config /app/config/config.yaml \ + -wait-tx-confirm -to-user "" \ + -amount 10000000000 \ + -token Particle +``` + +#### 创建 DB 和使用 + +由于需要在指定的 Miner 上创建 DB，需要在创建 DB 时指定提供服务的 Miner 列表 + +> `create` 命令接收一系列描述 DB 实例的参数，可以用 `cql help create` 查看详细参数；将 `node_count` 替换为所需的节点数量，例如 1 代表创建一个节点的 DB SideChain；`miner1_wallet_address, miner2_wallet_address` 等替换为指定 miner 的钱包地址列表；另外需要格外注意的时，所需创建的 DB SideChain 的节点数量需要小于或等于提供的指定 miner 数量，否则 CovenantSQL 会在指定 miner 之外的公用 miner 中随机分配节点以满足用户所需节点数量要求。 + +```shell +docker run -it --rm -v $(pwd)/client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + create -config /app/config/config.yaml -wait-tx-confirm \ + -db-node -db-target-miners ", , ..." +``` + +命令执行完成后将会有类似如下的输出： + +```shell +time="2019-05-07T03:41:03Z" level=info msg="Geting bp address from dns: bp04.testnet.gridb.io" +time="2019-05-07T03:41:05Z" level=info msg="Register self to blockproducer: 00000000003b2bd120a7d07f248b181fc794ba8b278f07f9a780e61eb77f6abb" +level=info msg="init config success" path=/root/.cql/config.yaml +level=info msg="create database requested" +The newly created database is: "covenantsql://163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df" +The connecting string beginning with 'covenantsql://' could be used as a dsn for `cql console` + or any command, or be used in website like https://web.covenantsql.io +``` + +其中 `covenantsql://163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df` 是数据库的连接串，可以在各类 SDK 或命令行工具中使用这个连接串访问数据库服务 + +#### 使用命令行工具连接数据库服务 + +可以是用 `cql` 工具提供的命令行功能访问数据库 + +> 将命令行中的 `dsn` 替换为上一步生成的数据库连接串 + +```shell +docker run -it --rm -v $(pwd)/client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + console -config /app/config/config.yaml "" +``` + +#### 启动 Adapter + +Java SDK 因为CovenantSQL 的 RPC 和网络连接协议的限制，不能直接访问 Miner 或 BlockProducer 节点，需要通过 Adapter 进行协议转换来访问。实际运行时，Java SDK/Adapter/Miner 是以如下图所示的形式交互的： + +```sequence +Java SDK ->Adapter: HTTP(s) Request +Adapter->Miner: ETLS RPC Request +Miner->Adapter: ETLS RPC Response +Adapter->Java SDK: HTTP(s) with JSON Response +``` + +可以通过如下命令启动 Adapter： + +> 请将命令中的 `adapter_name` 替换为所需的 adapter 的 docker container 名，将 `adapter_listen_port` 替换为所需暴露在物理机器上的端口号 + +```shell +docker run -d -v $(pwd)/client_config/:/app/config/ \ + -e COVENANT_ROLE=adapter \ + -e COVENANT_CONF=/app/config/config.yaml \ + -e COVENANTSQL_ADAPTER_ADDR=0.0.0.0:4661 \ + --name "" \ + --restart always \ + --log-driver "json-file" \ + --log-opt "max-size=1g" \ + --log-opt "max-file=3" \ + -p ":4661" \ + covenantsql/covenantsql:latest +``` + +启动后如果 adapter 的 docker container 运行正常，将可以通过 `http://localhost:/` 访问 adapter 并获取到 adapter 的版本信息 + +#### 使用 Java SDK + +参考 [CovenantSQL Java SDK Github](https://github.com/CovenantSQL/covenant-connector/tree/master/covenantsql-java-connector) 和 [CovenantSQL Java SDK 使用文档](https://developers.covenantsql.io/docs/en/driver_java) 通过 Adapter 访问 + +> 上一步启动的 Adapter 是运行在非 TLS 模式下的开发权限服务，任何访问 Adapter 的人都将以 Adapter 启动的账户（也就是 `./client_config` 中的私钥与配置）的权限访问数据库服务。 +> +> 在 Java SDK 中设置配置 `ssl=false`（因为 Adapter 运行在了非 TLS 模式下提供的 http 服务），并以 `jdbc:covenantsql://:/` 即可访问（请将 `adapter_host` 替换为实际的运行机器的域名或 IP，将 `adapter_listen_port` 替换为上一步中的监听端口号，`database_id` 替换为创建 DB 后返回的 `dsn` 中去除 `covenantsql://` scheme 的 hex 串部分，例如：`jdbc:covenantsql://127.0.0.1:11151/163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df`） + +#### 获取 Miner 节点的 metric 信息 + +Miner 提供了 metric 数据的导出接口，可以通过下述命令访问和导出： + +> 讲命令中的 `miner_name` 替换为 启动 miner 的 container 名 + +```shell +miner_internal_ip=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "" | head -1) +curl -s "http://${miner_internal_ip}:4665/debug/vars" +``` + +metric 信息对应表 + +| 字段名 | 含义 | +| ------------------------ | ----------------------------------------------------------------------- | +| service:miner:addr | 可访问的 Miner 的外部地址和端口（配置中的 ListenAddr） | +| service:miner:node | Miner 的 DHT 网络节点 ID | +| service:miner:wallet | Miner 的 钱包地址 | +| service:miner:disk:root | Miner 的 数据目录地址 | +| service:miner:disk:usage | Miner 使用的磁盘空间（KB） | +| service:miner:db:count | Miner 上正在提供服务的 ShardChain 数量 | +| service:miner:chain | Miner 上所有 ShardChain 统计信息，类型是一个 Map Map 的 key 是 ShardChain 的 DatabaseID | + + +针对每个 ShardChain 的统计信息，有如下字段 + +| 字段 | 含义 | +| -------------- | ------------------------------- | +| head:count | Chain 最新 Block 的编号（第几个块） | +| head:height | Chain 最新 Block 的 Epoch（第几个出块周期） | +| head:hash | Chain 最新 Block 的 Hash | +| head:timestamp | Chain 最新 Block 的产生时间（UTC） | +| requests:count | 最近 5 分钟统计范围内，1m 的请求数的平均值 | + + +#### 查看 Miner 节点上某个 DB Chain 的块信息 + +CovenantSQL 提供了一个方便的 Explorer 来展示数据库子链上的块信息，可以在通过如下命令启动 Explorer： + +> 其中替换 `explorer_name` 为想要运行 explorer 的 docker container 名，`explorer_listen_port` 替换为所需暴露在物理机器上的端口号 + +```shell +docker run -d -v $(pwd)/client_config/:/app/config/ \ + -e COVENANT_ROLE=explorer \ + -e COVENANT_CONF=/app/config/config.yaml \ + -e COVENANTSQL_OBSERVER_ADDR=0.0.0.0:4661 \ + --name "" \ + --restart always \ + --log-driver "json-file" \ + --log-opt "max-size=1g" \ + --log-opt "max-file=3" \ + -p ":4661" \ + covenantsql/covenantsql:latest +``` + +启动在浏览器里访问 `http://:/dbs/` + +> 其中 `explorer_external_address` 替换为物理机的外网 IP，`explorer_listen_port` 替换为上一步中指定的端口， `database_id` 替换为创建 DB 后返回的 `dsn` 中去除 `covenantsql://` scheme 的 hex 串部分，例如：`http://miner_machine:11106/dbs/163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df` + +稍后等待块同步，即可在页面中看到历史产生的 Block，点击 Block 可以看到 Block 上承载的历史查询过的 Query 情况（如果没有自动出现块的信息，可以尝试手动刷新） + +> CovenantSQL 有严格的权限控制，需要对数据库有读权限的人才能使用 Explorer 看到这些 Query 历史和 Block 信息 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/deployment-en.md b/website/translated_docs/zh-CN/deployment-en.md new file mode 100644 index 0000000..b94d5df --- /dev/null +++ b/website/translated_docs/zh-CN/deployment-en.md @@ -0,0 +1,162 @@ +--- +id: deployment +title: '🐳 Docker one-line deployment' +--- +## Deploy with CovenantSQL Docker + +### Install Docker + +You need to install docker and docker-compose on your machine to deploy CovenantSQL. + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### Download project + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +For all subsequent commands, the working directory is by default in the cloned CovenantSQL root directory, which can be saved as an environment variable: + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +### Start Docker container + +There are now two ways to start the CovenantSQL container: + +1. Use a public image on Docker Hub +2. Build a CovenantSQL Docker image + +> We recommend that regular users test CovenantSQL in the first way, and the second is only used to experience the latest development features. + +#### 1. Use a public image on Docker Hub + +Then start directly: + +```bash +make start +``` + +#### 2. Build a CovenantSQL Docker image + +Run CovenantSQL locally by executing the following command + +```bash +make docker # compile a new image from source files +make start +``` + +### Check running status + +Check the container status: + +```bash +docker-compose ps +``` + +Confirm that all components are in the `Up` state + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp +covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp +covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp +covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp +covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp +``` + +## Operate CovenantSQL + +### Create a database + +Create a DB instance by using the `cql` command and using the `create` parameter to provide the required number of database nodes. + +e.g.: creating a single-node database instance + +```shell +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +> Modify the value of the `create` parameter to create an instance running on multiple nodes +> e.g.: create an instance of two nodes + +```shell +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +The command will return the connection string of the created database instance + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### Accessing the database + +Use the `cql` command and use the `dsn` parameter to provide a connection string for the database instance access: + +```shell +docker exec -it covenantsql_adapter /app/cql console -config /app/config.yaml -no-password -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +After that, it will get the following output, and enter the `cql` interactive command line mode + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +The `cql` interactive command line mode is similar to the `mysql` command. For example, create a table named test, view the tables in the database, insert records, and query results etc. + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +After that, it will get the following output: + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +Use the `Ctrl + D` shortcut or type `\q` to exit the `cql` interactive command line + +### SQLChain Observer + +The Observer role in the image uses the same private.key as in the mysql-adapter image, so the new account authorization and transfer process can be eliminated. + +（For details on rights management, please refer to [Database Permission Managemen](cql.md#数据库权限管理)） + +#### Use SQLChain Observer in your browser + +We provide a SQLChain Observer at port `127.0.0.1:11108` to see the SQL statement on the chain. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/deployment.md b/website/translated_docs/zh-CN/deployment.md new file mode 100644 index 0000000..51ac83a --- /dev/null +++ b/website/translated_docs/zh-CN/deployment.md @@ -0,0 +1,158 @@ +--- +id: deployment +title: Docker Deploy +--- +## Deploy with CovenantSQL Docker + +### Install Docker + +You need to install docker and docker-compose on your machine to deploy CovenantSQL. + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### Download project + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +For all subsequent commands, the working directory is by default in the cloned CovenantSQL root directory, which can be saved as an environment variable: + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +### Start Docker container + +There are now two ways to start the CovenantSQL container: + +1. Use a public image on Docker Hub +2. Build a CovenantSQL Docker image + +> We recommend that regular users test CovenantSQL in the first way, and the second is only used to experience the latest development features. + +#### 1. Use a public image on Docker Hub + +Then start directly: + +```bash +make start +``` + +#### 2. Build a CovenantSQL Docker image + +Run CovenantSQL locally by executing the following command + +```bash +make docker # compile a new image from source files +make start +``` + +### Check running status + +Check the container status: + +```bash +docker-compose ps +``` + +Confirm that all components are in the `Up` state + + Name Command State Ports + ------------------------------------------------------------------------------------------------------ + covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp + covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp + covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp + covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp + covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp + covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp + covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp + covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp + covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp + covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp + + +## Operate CovenantSQL + +### Create a database + +Create a DB instance by using the `cql` command and using the `create` parameter to provide the required number of database nodes. + +e.g.: creating a single-node database instance + +```bash +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +> Modify the value of the `create` parameter to create an instance running on multiple nodes +> e.g.: create an instance of two nodes + +```bash +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +The command will return the connection string of the created database instance + + covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + + +### Accessing the database + +Use the `cql` command and use the `dsn` parameter to provide a connection string for the database instance access: + +```bash +docker exec -it covenantsql_adapter /app/cql console -config /app/config.yaml -no-password -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +After that, it will get the following output, and enter the `cql` interactive command line mode + +``` + +Connected with driver covenantsql (develop) Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> + +
The `cql` interactive command line mode is similar to the `mysql` command. For example, create a table named test, view the tables in the database, insert records, and query results etc. + + ```sql + CREATE TABLE test (test TEXT); + SHOW TABLES; + INSERT INTO test VALUES("happy"); + SELECT * FROM test; + + +After that, it will get the following output: + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); + CREATE TABLE + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name + ------ + test + (1 row) + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); + INSERT + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test + ------- + happy + (1 row) + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> + + +Use the `Ctrl + D` shortcut or type `\q` to exit the `cql` interactive command line + +### SQLChain Observer + +The Observer role in the image uses the same private.key as in the mysql-adapter image, so the new account authorization and transfer process can be eliminated. + +（For details on rights management, please refer to [Database Permission Managemen](cql.md#数据库权限管理)） + +#### Use SQLChain Observer in your browser + +We provide a SQLChain Observer at port `127.0.0.1:11108` to see the SQL statement on the chain. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/driver_golang.md b/website/translated_docs/zh-CN/driver_golang.md new file mode 100644 index 0000000..3bb7fca --- /dev/null +++ b/website/translated_docs/zh-CN/driver_golang.md @@ -0,0 +1,169 @@ +--- +id: driver_golang +title: Golang +--- + +## Use Golang to access CovenantSQL + +`CovenantSQL` provides `Golang SDK` to access database using native rpc protocol. The `cql` tool is developed based on `Golang SDK`. + +`Golang SDK` is compatible with Golang `database/sql` driver standard, and popular `Golang ORM` is supported for advanced uses. + +### Compatibility + +`Golang SDK` is compatible with Golang `1.10+`. + +### Installation and quick start + +Install it with: + +```bash +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API doc + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### Example + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // Use config file to initialize Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // Connect to database instance + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // Insert records + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // Query records + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/driver_java.md b/website/translated_docs/zh-CN/driver_java.md new file mode 100644 index 0000000..b96902d --- /dev/null +++ b/website/translated_docs/zh-CN/driver_java.md @@ -0,0 +1,52 @@ +--- +id: driver_java +title: Java +--- + +## Use Java to access CovenantSQL + +`CovenantSQL` provides `Java SDK` to access database instance through [`Adapter`](./adapter) service. + +`Java SDK` is compatible with `JDBC4` specifications，and popular `ORM` like `MyBatis` is supported through JDBC interface. + +### Compatibility + +`Java SDK` requires `Java 1.7+`. + +### Installation and quick start + +Before using `Java SDK`, an adapter tool deployment is required, please see [Deploy Adapter Service](./adapter). + +Now you can use `jdbc:covenantsql:///` uri，replacing `adapter_endpoint` with adapter listen address，`database_id` with database id。 + +#### Maven + +```xml + + + io.covenantsql + cql-java-connector + 1.0.1 + + +``` + +#### Gradle + +```gradle +repositories { + maven { + url 'https://raw.github.com/CovenantSQL/cql-java-driver/mvn-repo' + } +} + +dependencies { + compile 'io.covenantsql:covenantsql-java-connector:1.0-SNAPSHOT' +} +``` + +### Examples + +1. [JDBC Example](https://github.com/CovenantSQL/cql-java-driver/blob/master/example/src/main/java/io/covenantsql/connector/example/jdbc/Example.java) +2. [MyBatis Example](https://github.com/CovenantSQL/cql-java-driver/blob/master/example/src/main/java/io/covenantsql/connector/example/mybatis/Example.java) +3. [SpringBoot + MyBatis Project Example](https://github.com/CovenantSQL/covenantsql-mybatis-spring-boot-jpetstore) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/driver_js.md b/website/translated_docs/zh-CN/driver_js.md new file mode 100644 index 0000000..469aeb5 --- /dev/null +++ b/website/translated_docs/zh-CN/driver_js.md @@ -0,0 +1,65 @@ +--- +id: driver_js +title: JavaScript +--- + +## Use JavaScript to access CovenantSQL + +Front-end developers could use [covenantsql-proxy-js](https://github.com/CovenantSQL/covenantsql-proxy-js) to access CovenantSQL through CovenantSQL [Adapter](./adapter). + +#### Installation + +Install `node-covenantsql` using package manager `npm` or `yarn`: + +```bash +npm install --save node-covenantsql +``` + +or + +```bash +yarn add node-covenantsql +``` + +#### Quick start + +First, [Deploy Adapter Service](./adapter). + +Configure `node-covenantsql`, replace `adapter_listen_address` with adapter listen address, replace `database_id` with created database id: + +```javascript +const config = { + endpoint: '', // local testnet endpoint without https + database: 'database_id', // your DB id created by `cql` tools +} +``` + +After successfully connected to adapter, any CRUD operation is available using typical database operations: + +```typescript +const cql from 'node-covenantsql' + +const config = {...} // see above + +cql.createConnection(config).then(async (connection: any) => { + // read + const data1 = await connection.query("select ? + ?", [2.1, 3.2]); + console.log(data1); + + // write + const createTableSQL = ` + CREATE TABLE IF NOT EXISTS contacts (\ + contact_id INTEGER PRIMARY KEY, + first_name TEXT NOT NULL, + last_name TEXT NOT NULL, + email text NOT NULL UNIQUE, + phone text NOT NULL UNIQUE + ); + ` + const status1 = await connection.exec(createTableSQL) + console.log(`exec1 status:`, status1); + + const data2 = await connection.query("show tables;"); + console.log(data2); +}).catch((e: any) => console.log(e)) +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/driver_python.md b/website/translated_docs/zh-CN/driver_python.md new file mode 100644 index 0000000..e68f269 --- /dev/null +++ b/website/translated_docs/zh-CN/driver_python.md @@ -0,0 +1,54 @@ +--- +id: driver_python +title: Python +--- + +## Use Python to access CovenantSQL + +Developers could use [PyCovenantSQL](https://github.com/CovenantSQL/cql-python-driver) to access CovenantSQL through [Adapter](./adapter). + +### Compatibility + +`Python SDK` requires `Python 3.4+`. + +### Installation and quick start + +Before using `Python SDK`, an adapter deployment is required, please see [Deploy Adapter Service](./adapter). + +Install `PyCovenantSQL` using pip: + +```bash +$ python3 -m pip install PyCovenantSQL +``` + +### Example + +Replace `adapter_host` with adapter listen host, `adapter_port` with adapter listen port, `dsn` with database dsn. + +```python +import pycovenantsql + +# Connect to the database +connection = pycovenantsql.connect(host='', + port=, + database='' + ) + +try: + with connection.cursor() as cursor: + # Create a new record + sql = "INSERT INTO `users` (`email`, `password`) VALUES (%s, %s)" + cursor.execute(sql, ('webmaster@python.org', 'very-secret')) + + # connection is autocommit. No need to commit in any case. + # connection.commit() + + with connection.cursor() as cursor: + # Read a single record + sql = "SELECT `id`, `password` FROM `users` WHERE `email`=%s" + cursor.execute(sql, ('webmaster@python.org',)) + result = cursor.fetchone() + print(result) +finally: + connection.close() +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/intro.md b/website/translated_docs/zh-CN/intro.md new file mode 100644 index 0000000..fb1f732 --- /dev/null +++ b/website/translated_docs/zh-CN/intro.md @@ -0,0 +1,52 @@ +--- +id: intro +title: CovenantSQL Intro +--- + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + homebrew +

+ +CovenantSQL(CQL) is a decentralized, GDPR-compliant, trusted, SQL database with blockchain features: + +- **ServerLess**: Free, High Availabile, Auto Sync Database Service for Serverless App +- **GDPR-compliant**: Zero pain to be GDPR-compliant. +- **SQL**: Most SQL-92 support. +- **Decentralize**: Running on Open Internet without Central Coordination. +- **Privacy**: Access with Granted Permission and Encryption Pass. +- **Immutable**: Query History in CQL is Immutable and Trackable. +- **Permission**: Column Level ACL and SQL Pattern Whitelist. + +We believe [On the next Internet, everyone should have a complete **Data Rights**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +**One Line Makes Data on Blockchain** + +```go +sql.Open("cql", dbURI) +``` + +## What is CQL? + +- Open source alternative of [Amazon QLDB](https://aws.amazon.com/qldb/) +- Just like [filecoin](https://filecoin.io/) + [IPFS](https://ipfs.io/) is the decentralized file system, CQL is the decentralized database \ No newline at end of file diff --git a/website/translated_docs/zh-CN/native.md b/website/translated_docs/zh-CN/native.md new file mode 100644 index 0000000..b76bcc8 --- /dev/null +++ b/website/translated_docs/zh-CN/native.md @@ -0,0 +1,172 @@ +--- +id: native +title: '📦 CovenantSQL Native SDK' +--- +## 用 Golang 使用 CovenantSQL + +### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/nav.md b/website/translated_docs/zh-CN/nav.md new file mode 100644 index 0000000..caac5e7 --- /dev/null +++ b/website/translated_docs/zh-CN/nav.md @@ -0,0 +1,21 @@ +--- +id: nav +title: '📖 使用导航' +--- +## 直接使用测试网 + +[🌏 TestNet 快速开始](./quickstart) + +## 部署私有 CovenantSQL 数据库（搭建私有链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +[🐳 Docker 一键部署](./deployment) + +## 使用 CovenantSQL 开发应用 + +[📦 CovenantSQL SDK](./development) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/proxy.md b/website/translated_docs/zh-CN/proxy.md new file mode 100644 index 0000000..3a39291 --- /dev/null +++ b/website/translated_docs/zh-CN/proxy.md @@ -0,0 +1,110 @@ +--- +id: adapter +title: '📦 CovenantSQL Adapter SDK' +--- +# 通过 Adapter 使用 CovenantSQL + +## 简介 + +`CovenantSQL` 提供了 HTTP/HTTPS Adapter，类似于云数据库， 开发者可以直接用 HTTP 的形式使用 CovenantSQL。 + +## 安装和使用 + +首先，需要确认我们有一个可用的配置和公私钥对，通常我们默认的配置和公私钥对的存储位置为 `~/.cql/` 目录。生成或获取请参考 [QuickStart#创建账号](./quickstart#创建账号) + +### Docker 运行 Adapter + +下面的命令将使用`~/.cql/config.yaml` 和 `~/.cql/private.key` 启动 Adapter，并把端口映射在 `0.0.0.0:11105` + +```bash +export adapter_addr=0.0.0.0:11105 +docker rm -f cql-adapter +docker run -itd \ + --env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --name cql-adapter -p $adapter_addr:4661 \ + covenantsql/covenantsql:testnet -listen 0.0.0.0:4661 +``` + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +docker run -it --rm \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --entrypoint /app/cql covenantsql/covenantsql:testnet \ + -config /app/config.yaml -create 1 +``` + +命令会返回创建的数据库实例的连接串（DSN） + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +## 主流语言 Driver 的使用 + +### NodeJS + +NodeJS 开发者可以通过 [node-covenantsql](https://github.com/CovenantSQL/node-covenantsql) 来与 CovenantSQL Adapter 进行交互。 + +#### 下载安装 + +可以直接通过 `npm` 或者 `yarn` 来安装 `node-covenantsql` + +```bash +npm install --save node-covenantsql +``` + +or + +```bash +yarn add node-covenantsql +``` + +#### 使用 + +在运行本地 Adapter 之后，将 Adapter 的 endpoint 填入 `node-covenantsql` 的 config 之中： + +```javascript +const config = { + endpoint: 'localhost:11105', // local testnet endpoint without https + database: `${DSN}`, // your DB id created by `cql` tools + bypassPem: true // bypass https config +} +``` + +这里 `bypassPem` 为 `true` 表示应用中所有对链上数据库的操作都会经过本地的 Adapter 进行代理，我们默认本地环境是可控，安全的，无需用 HTTPS 来保证这段连接的信道安全，少了证书的繁琐认证，所以成为 `bypassPem`。 + +接着连通之后则可进行链上数据库的增删改查： + +```typescript +const cql from 'node-covenantsql' + +const config = {...} // see above + +cql.createConnection(config).then(async (connection: any) => { + // read + const data1 = await connection.query("select ? + ?", [2.1, 3.2]); + console.log(data1); + + // write + const createTableSQL = ` + CREATE TABLE IF NOT EXISTS contacts (\ + contact_id INTEGER PRIMARY KEY, + first_name TEXT NOT NULL, + last_name TEXT NOT NULL, + email text NOT NULL UNIQUE, + phone text NOT NULL UNIQUE + ); + ` + const status1 = await connection.exec(createTableSQL) + console.log(`exec1 status:`, status1); + + const data2 = await connection.query("show tables;"); + console.log(data2); +}).catch((e: any) => console.log(e)) +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/qna.md b/website/translated_docs/zh-CN/qna.md new file mode 100644 index 0000000..0e2b596 --- /dev/null +++ b/website/translated_docs/zh-CN/qna.md @@ -0,0 +1,58 @@ +--- +id: qna +title: Q&A +--- + +## Frequently Asked + +- **Q:** What level of consistency does the CQL database support and how is the CQL database created? + + **A:** See [Consensus Algorithm](./arch#consensus-algorithm) + +- **Q:** How is CQL database security done? + + **A:** Unlike traditional databases, CQL is a distributed database system that runs on the open Internet. In terms of security, CQL mainly does the following work: + + 1. Key Management: CQL uses public and private key pairs generated by Bitcoin's `scep256k1` asymmetric encryption curve. + + 2. Network communication: see [RPC Framework](./arch_network)。 + + 3. Database Permissions & Encryption: + + 1. [Secure Gateway](./advanced_secure_gateway) + + 2. Support of SQL encryption functions `encrypt`, `decrypt`, for example: + + ```sql + INSERT INTO "t1" ("k", "v") VALUES (1, encrypt("data", "pass", "salt")); + SELECT decrypt("v", "pass", "salt") FROM "t1" WHERE "k"=1; + ``` + +- **Q:** If CQL data is Immutable, how do CQL deal with the need for data deletion in GDPR? + + **A:** CQL supports two development modes, one is the traditional `DB per App`, and the other is the `DB per User` which is biased towards privacy. + + The development mode of `DB per User` is very suitable for the development of applications such as "Password Manager" and "Personal Information Management". Since users manage their personal data through a CQL private key which is quite like using Bitcoin a private key to manage their own property. App developed in this model naturally does not store any user data, and technically conforms to the following Stringent requirements of laws and regulations: + + - [EU GDPR（General Data Protection Regulation）](https://gdpr-info.eu/) + - [CCPA（California_Consumer_Privacy_Act）](https://en.wikipedia.org/wiki/California_Consumer_Privacy_Act) + - [HIPAA（Health Insurance Portability and Accountability Act of 1996）](https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act) + - [HongKong Personal Data (Privacy) Ordinance](https://www.elegislation.gov.hk/hk/cap486) + + The complete data of CQL is stored on Miner of SQLChain. The data related SQL history is completely saved on Miner. Compared to the traditional database `CRUD` (Create, Read, Update, Delete), CQL supports `CRAP` (Create, Read, Append, Privatize). + + > **Append** vs **Update** + > + > After the traditional database changes the data (Update), there is no history, in other words, the data can be tampered with. CQL supports the Append of data, and the result is that the history of the data is preserved. + > + > **Privatize** vs **Delete** + > + > The traditional database deletes the data (Delete), which is irreversible and irreversible. CQL supports Privatization of data, that is, transferring the permissions of the database to an impossible public key. This allows substantial deletion of sub-chain data. Deletion of all traces on the chain for a single piece of data is currently only supported in the Enterprise Edition. + +- **Q:** How does CQL store data for a database? + + **A:** Most of the operation of the user database is done on SQLChain. By default, the MainChain only saves the block hash of the SQLChain. For more details, please refer to [MainChain & SQLChain](./arch_layers#mainchain-sqlchain)。 + +- **Q:** What is the maximum amount of data supported by CQL? + + **A:** CQL's database data is stored on a separate SQLChain. The number of CQL databases depends on the number of Miners across the network. The upper limit of a single CQL database depends on the hardware performance. As of 2019-04-25, the largest table online of TestNet is a 2 Miner database running continuously on a AWS c5.2xlarge standard configuration with 433,211,000 rows of data and 3.2 TB of disk. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/quandl.md b/website/translated_docs/zh-CN/quandl.md new file mode 100644 index 0000000..886d950 --- /dev/null +++ b/website/translated_docs/zh-CN/quandl.md @@ -0,0 +1,297 @@ +--- +id: quandl +title: 基于 Quandl 的金融数据分析 +--- +## 关于 Quandl + +Quandl 是一个针对金融投资行业的大数据平台，其数据来源包括联合国、世界银行、中央银行等公开数据，核心财务数据来自 CLS 集团，Zacks 和 ICE 等，所有的数据源自 500 多家发布商， 是为投资专业人士提供金融，经济和替代数据的首选平台，拥有海量的经济和金融数据。 + +## Quandl 数据索引 + +### CovenantSQL 使用简介 + +首先，我们已基于 Quandl 的开放 API 将数据存放在 CovenantSQL 中，首先应该浏览一下 CovenantSQL 的使用介绍来熟悉一下如何连接并且使用 CovenantSQL。 + +现在由于客户端兼容问题， 请直接使用我们的 HTTP 服务来对 Quandl 数据库进行 query，未来兼容现在的 `cql` 客户端后会第一时间更新此文档。 + +具体通过 HTTP 服务来使用 CovenantSQL 请参考 [Python 驱动文档](https://github.com/CovenantSQL/python-driver/blob/master/README.rst) 和 [NodeJS 驱动文档](https://github.com/CovenantSQL/node-covenantsql/blob/master/README.md) + +所需参数: + + host: 'e.morenodes.com' + port: 11108 + database: '057e55460f501ad071383c95f691293f2f0a7895988e22593669ceeb52a6452a' + + +### 数据使用方法 + +Quandl 数据分为表以及子表两层索引 + +数据库中，表名为`quandl_` + `database_code`为完整表名 + +通过查询表名来查看表的内容 + +具体使用时，需要结合`quandl_updateindex` 这张索引表来使用，（查询索引表时，请务必 limit 小于 10 万，因为全表数据量过大） + +使用时，请使用 where 语句限定`quandlcode`字段来查询表中的子表数据。 + +### 查询示例 + +1. 我们想要查询 欧盟委员会年度宏观经济数据库 的数据，我们找到其第一层索引的 `databasecode` 为`quandl_ameco`，于是，我们可以查询其第二层索引，用以下 SQL 命令行： + + `select * from quandl_updateindex where databasecode like 'ameco' group by quandlcode limit 10000` + +2. 然后通过第三列，我们可以查看`quandlcode`对应的描述 + + 比如 AMECO/ALB_1_0_0_0_AAGE 对应的就是阿尔巴尼亚的进出口相关信息，时间从 1960 到 1988。 + + Average share of imports and exports of goods in world trade excluding intra EU trade; Foreign trade statistics (1960-1998 Former EU-15) - Albania + + 于是，我们可以用以下方式把这个子表给查询出来 + + `select * from quandl_ameco where quandlcode like 'AMECO/ALB_1_0_0_0_AAGE' limit 10000` + +3. 注意：如果内容整列为 null 的，属于表结构本身不存在的字段，可以自行去除。 + +## Quandl 数据 Excel 插件使用说明 + +您可以下载 Quandl 数据 Excel 插件，无须安装，请解压到任意文件夹中。此插件目前仅支持 Office 2010 以及以上版本，office 2007 以及以下版本目前暂不支持。 + +### 配置 Excel 插件 + +解压下载后压缩包，在文件夹中有两个.xll 文件，`ClassLibrary7-AddIn.xll` 以及 `ClassLibrary7-AddIn64.xll` 文件，这两个文件分别对应 32 位的 Excel 与 64 位的 Excel，请根据您的电脑配置使用对应插件。 + +#### 修改 xml 配置 + +每个 `.xll` 文件对应一个 `.config` 的配置文件，也就是 `ClassLibrary7-AddIn.xll.config` 和`ClassLibrary7-AddIn64.xll.config`，为如下 xml 配置： + +```xml + + + + + + + + + +``` + +其中有如下配置需要修改，并保存： + +- certpath: 请填写 `read.data.thunderdb.io.pfx` 证书的绝对路径 + +#### 安装插件 + +有两种办法使用此 Excel 插件 + +1. 直接双击对应的 32 位或 64 位 Excel 的 xll 文件打开 + +![quandl_ext_1](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_1.png) + +如果弹出如上对话框，选择第一个： `仅为本回话启用此加载项`。然后新建一个 Excel 表格，如果在 Excel 的上方选项卡中看到 CovenantSQL，说明插件加载成功。 + +2. 打开 Excel，然后依次选择 `文件 — 选项 — 加载项`，管理选择 Excel 加载项，点击转到然后浏览选择解压后的对应版本的 `.xll` 文件，然后点击 `确定`，在选项卡中如果成功加载出 CovenantSQL 即为成功加载，如下图： + +![quandl_ext_2](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_2.png) + +#### 使用插件 + +选择 CovenantSQL 的选项卡可以看到 Quandl 数据查询，点击 Quandl 数据查询，会弹出一个窗体如下图所示： + +![quandl_ext_3](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_3.png) + +- 其中红色框住的列表部分是一级目录，下方则是所选项的具体描述 + +- 绿色按钮是通过选择的一级目录来查询二级目录。这里查询时间会随着所查询二级目录的大小以及用户自身的网络速度等因素而不同，可能查询时间会超过 1 分钟，请耐心等待。 + +- 黄色部分左边的列表是二级目录，右边的窗体则为列表项所选择的表的描述。 + +- 蓝色部分是导出数据的可选项 + + - Limit Number 是一次导出的最多数据条数，默认为 10000 条，最大值可填写 100000 + - Offset Number 是从数据库的第几条开始导出，因为之前会限定条数，例如我们之前导出了 10000 条数据，但是明显数据还没有导出全部，我们可以使用此功能选择 offset 10000 来从第 10000 条开始导出（注：数据库的计数从 0 开始，所以前 10000 条为 0-9999） + +现在，您即可在 Excel 中方便的调用存在 CovenantSQL 上的 Quandl 数据。 + +## 附件表 + +| DataBase | 名称 | 描述 | +| ------------ | ------------------------ | ------------------------------------------------------------------------------------------- | +| BUNDESBANK | 德意志联邦银行数据仓库 | 有关德国经济，货币和资本市场，公共财政，银行，家庭，欧元区总量，贸易和外债的数据。 | +| URC | 独角兽研究公司数据 | 纽约证券交易所，美国证券交易所和纳斯达克证券交易所的预付和下跌数据。从各种公开来源和报告中值。 | +| DCE | 大连商品交易所数据 | 来自DCE的农业和商品期货，历史跨越了近十年的特定期货。 | +| WFC | 富国银行住房抵押贷款数据 | 该数据库提供富国银行（Wells Fargo Bank）分部Wells Fargo Home Mortgage的抵押贷款购买和再融资利率。 | +| USDAFNS | 美国农业部食品与营养服务项目数据 | 食品和营养服务局为低收入家庭和儿童管理联邦营养援助计划。成本和参与率数据。 | +| LJUBSE | 卢布尔雅那证券交易所数据 | 该数据库包含卢布尔雅那股票交易所指数，总部位于斯洛文尼亚的卢布尔雅那。 | +| TOCOM | 东京商品交易所数据 | 来自东京商品交易所（TOCOM）的农业和商品期货，历史跨越了近十年的特定期货。 | +| WCSC | 世界银行企业积分卡数据 | 该数据库旨在提供世界银行集团在消除极端贫困和促进共同繁荣方面的表现的战略概述。 | +| CMHC | 加拿大住房抵押贷款公司 | CMHC是一家政府所有的公司，为加拿大公民提供经济适用房，并收集价格，建筑和供应等数据。 | +| WGEC | 世界银行全球经济监测商品数据（GEM） | 包含1960年至今的商品价格和指数的数据。 | +| FED | 美联储数据公布 | 美国官方关于货币供应量，利率，抵押贷款，政府财政，银行资产和债务，汇率，工业生产的数据。 | +| WPSD | 世界银行公共部分支出数据 | 由世界银行和国际货币基金组织共同开发的数据，汇集了详细的公共部门政府债务数据。 | +| UGID | 联合国全球指标 | 该数据库提供广泛的全球指标，涵盖人口，公共卫生，就业，贸易，教育，通货膨胀和外债。 | +| RBA | 澳大利亚储备银行数据 | 中央银行和货币当局，监管银行业，设定利率，并为政府债务提供服务。关键经济指标数据。 | +| UCOM | 联合国商品贸易数据 | 该数据库提供有关食品，活体动物，药品，金属，燃料和机械等商品进出口的全面综合数据。 | +| SIDC | 太阳影响数据分析中心数据 | SIDC主持从1700年开始的太阳活动数据，特别是太阳黑子活动。 | +| ZCE | 郑州商品交易所数据 | 来自ZCE的农业和商品期货，历史跨越了近十年的特定期货。 | +| USDAFAS | 美国农业部外国农业服务数据（FAS） | 美国农业部外国农业服务局将美国农业与世界市场联系起来。它提供了国外生产和出口的统计数据。 | +| OECD | 世界经济合作与发展组织数据 | 促进经济福利的发达国家国际组织。从成员和其他人收集数据以提出政策建议。 | +| OPEC | 欧佩克数据 | 国际组织和经济卡特尔监督伊拉克，伊朗，沙特阿拉伯和委内瑞拉等石油生产国的政策、油价数据。 | +| MCX | 印度多种商品交易所数据 | 印度最大的商品交易所，为金属，能源和农业期货交易提供服务。世界第三大合约和交易量交易所。 | +| ECONOMIST | 经济学人 - 巨无霸指数 | 巨无霸指数是由经济学家于1986年发明的，是一个轻松的指南，指出货币是否处于“正确”水平。它基于购买力平价理论（PPP）。 | +| NSDL | 国家证券存管有限公司（印度）数据 | 在印度存放负责该国经济发展的国家，该国家建立了国际标准的国家基础设施，处理在印度资本市场以非物质形式持有和结算的大部分证券。 | +| GDT | 全球乳品贸易数据 | nan | +| CFFEX | 中国金融期货交易所数据 | 来自CFFEX的指数和债券期货，对于特定期货的历史跨越近十年。 | +| CITYPOP | Thomas Brinkhoff的城市人口数据 | Thomas Brinkhoff提供了大多数国家城市和行政区域的人口数据。 | +| BCHARTS | 比特币图表汇率数据 | 来自所有主要比特币交易所的比特币兑换大量货币的汇率，包括当前和历史汇率。 | +| LOCALBTC | Local Bitcoins数据 | nan | +| JODI | JODI石油世界数据库 | JODI石油和天然气数据来自100多个国家，包括多种能源产品和各种计量方法。 | +| UENG | 联合国能源统计数据 | 该数据库提供有关新能源和可再生能源的生产，贸易，转换和最终消费的全面统计数据。 | +| ULMI | 联合国劳工市场指标 | 该数据库为世界上所有国家提供了按性别划分的全面青年失业数字。 | +| MAURITIUSSE | 毛里求斯证券交易所数据 | 毛里求斯证券交易所指数数据。 | +| UKRSE | 乌克兰交易所数据 | UKRSE提供与乌克兰最大证券交易所相关的最新数据。该交易所位于基辅，约占乌克兰总股本交易量的四分之三 | +| BITSTAMP | Bitstamp数据 | Bitstamp是一个比特币的交易平台。 | +| UNAE | 联合国国民账户估算数据 | 该数据库提供了全球所有国家不同部门的国内生产总值，国民总收入和总增加值的全球数据。 | +| UNAC | 联合国国民账户官方国家数据 | 该数据库提供有关国民账户的全球数据，例如家庭，公司和政府的资产和负债。 | +| UTOR | 联合国世界旅游业数据 | 该数据库提供有关国际旅游的综合数据。数据包括所有国家的旅游人数和旅游支出。 | +| WFE | 世界交易所联合会数据 | 该数据库提供有关国际旅游的综合数据。数据包括所有国家的旅游人数和旅游支出。 | +| FRBC | 克利夫兰联邦储备银行数据 | 克利夫兰联邦储备银行从数百家金融机构收集数据，包括存款机构，银行控股公司和其他用于评估金融机构状况的实体，以及收集经济和金融体系运作方式的见解。 | +| UGEN | 联合国性别信息 | 该数据库提供关于各种与性别有关的指标的全面综合数据，涵盖人口，卫生，教育和就业。 | +| BITFINEX | Bitfinex数据 | Bitfinex是比特币，莱特币和Darkcoin的交易平台，具有许多先进功能，包括保证金交易，交易所和点对点保证金融资。 | +| UGHG | 联合国温室气体清单 | 该数据库提供有关六种主要温室气体人为排放的全面综合数据。数据可以追溯到1990年。 | +| UIST | 联合国工业发展组织数据 | 该数据库提供有关工业发展指标的全球数据，包括产量，员工，工资，各种行业的增加值。 | +| PRAGUESE | 布拉格证券交易所数据 | 布拉格证券交易所的价格指数数据。 | +| PFTS | PFTS证券交易所（乌克兰）数据 | 来自PFTS证券交易所的指数数据，这是乌克兰最大的市场。 | +| WARSAWSE | 华沙证券交易所数据 | WIG20指数自1994年4月16日起根据WSE主要清单中20家最主要和最具流动性公司的股票价值计算。 | +| TUNISSE | 突尼斯证券交易所数据 | 突尼斯证券交易所的主要参考指数。 | +| FRKC | 堪萨斯城联邦储备银行数据 | FRKC是美联储第10区的区域中央银行，主要发布农业交易中的银行业务数据。 | +| UENV | 联合国环境统计数据 | 该数据库提供有关水和废物相关指标的全球数据，包括淡水供应和降水，以及废物的产生和收集。 | +| UFAO | 联合国粮食和农业数据 | 该数据库提供全球粮食和农业数据，包括作物生产，化肥消费，农业用地和牲畜用途。 | +| TAIFEX | 台湾期货交易所数据 | 来自TAIFEX的指数和债券期货，其历史跨越了十多年的特定期货。 | +| GDAX | GDAX（全球数字资产交易所）数据 | GDAX是世界上最受欢迎的买卖比特币的地方。 | +| ARES | 房地产证券化协会数据 | ARES保护投资者，有助于房地产证券化产品市场的发展，并促进房地产投资市场的扩张。 | +| SHADOWS | 影子联邦基金利率模型数据 | 该数据集包含 吴-侠 论文中关于影子联邦基金的三个主要指标，用于识别所有三大银行的影子利率。 | +| NAAIM | 全国积极投资管理者协会头寸指数 | NAAIM暴露指数代表NAAIM成员报告的美国股票市场的平均风险敞口。 | +| CBRT | 土耳其共和国中央银行数据 | CBRT负责采取措施维持土耳其金融体系的稳定。 | +| CEGH | 中欧天然气中心数据 | nan | +| FINRA | 美国金融业监管局数据 | 金融业监管局提供证券公司和交易所市场的短期利息数据。 | +| NASDAQOMX | 纳斯达克OMX全球指数数据 | 纳斯达克OMX发布的全球指数超过35,000种，包括全球股票，固定收益，股息，绿色，北欧，伊斯兰教等。每日数据。 | +| EURONEXT | 泛欧证券交易所数据 | 欧洲最大的交易所Euronext的历史股票数据。 | +| UICT | 联合国信息和通信技术数据 | 该数据库提供有关信息和通信技术的全面全球数据，包括所有国家的电话，蜂窝和互联网使用情况。 | +| USAID | 美国国际开发署数据 | 美国国际开发署提供了美国向世界其他地方提供的所有外国援助的完整历史记录。 | +| ZAGREBSE | 萨格勒布证券交易所数据 | 克罗地亚唯一的证券交易所。它发布有关其股票和债券指数表现的数据。 | +| QUITOSE | 基多证券交易所（厄瓜多尔）数据 | 厄瓜多尔国家证券交易所的指数。 | +| ECBCS | 欧盟委员会商业和消费者调查 | 该数据库中的数据来自欧盟（EU）和欧盟申请国的不同经济部门的统一调查。 | +| PSE | 巴黎经济学院数据 | 该数据库描述了越来越多国家的最高收入分配。数字是使用税收数据得出的。 | +| MALTASE | 马耳他证券交易所数据 | 马耳他证券交易所发挥作用，为其认可的名单提供金融工具的结构，随后可在受监管，透明和有序的市场（二级市场）进行交易。市场的主要参与者是发行人，股票交易所会员（股票经纪人）和投资者一般。 | +| GPP | 全球石油价格 | nan | +| PPE | 波兰电力交易所（TGE）数据 | nan | +| UKONS | 英国国家统计局数据 | 关于英国就业，投资，住房，家庭支出，国民账户和许多其他社会经济指标的数据。 | +| NCDEX | 国家商品及衍生品交易所（印度）数据 | 印度专业管理的在线多商品交易所 | +| WSE | 华沙证券交易所（GPW）数据 | nan | +| TFX | 东京金融交易所数据 | 东京金融交易所是一个期货交易所，主要交易金融工具市场，处理证券和市场衍生品。 | +| WGFD | 世界银行全球金融发展数据 | 有关金融系统特征的数据，包括金融机构和市场的规模，使用，获取，效率和稳定性的衡量标准。 | +| CEPEA | 应用经济学应用研究中心（巴西）数据 | CEPEA是圣保罗大学的一个经济研究中心，专注于农业企业问题，发布巴西商品价格指数。 | +| SBJ | 日本统计局数据 | 日本政府统计机构，提供有关就业和劳动力的统计数据。 | +| WGEM | 世界银行全球经济监测 | 关于全球经济发展的数据，涵盖高收入国家和发展中国家。 | +| WGDF | 世界银行全球发展金融 | 关于金融系统特征的数据，包括金融机构和市场的规模，使用，获取，效率和稳定性的衡量标准。 | +| WWDI | 世界银行世界发展指标 | 最新和最准确的发展指标，由官方认可的国际来源汇编而成。 | +| WESV | 世界银行企业调查 | 公司级私营部门数据，涵盖金融，腐败，基础设施，犯罪，竞争和绩效衡量等业务主题。 | +| WDBU | 世界银行存续商业数据 | 关于成员国和地方和区域一级选定城市的商业法规及其执法的数据。 | +| OSE | 大阪证券交易所数据 | 日本第二大证券交易所。与东京证券交易所不同，OSE在衍生品交易方面表现最为强劲，是日本的大多数期货和期权。 | +| RFSS | 俄罗斯联邦统计局数据 | 俄罗斯政府统计机构，负责在国家和地方层面发布俄罗斯的社会，经济和人口统计数据。 | +| SHFE | 上海期货交易所数据 | 大宗商品交换能源，金属和化学相关的工业产品。许多商品期货的衍生品市场。 | +| WGEP | 世界银行全球环境规划经济前景数据 | 关于全球经济的短期，中期和长期前景以及对发展中国家和减贫的影响的数据。 | +| USMISERY | 美国痛苦指数 | 由经济学家亚瑟·奥肯（Arthur Okun）开发的苦难指数是失业率加上通胀率。 | +| WJKP | 世界银行知识平台工作数据 | 与劳工有关的主题指标。 | +| WMDG | 世界银行千年发展目标数据 | 根据千年发展目标（MDGs）的目标和指标重新组织的世界发展指标数据。 | +| WPOV | 世界银行贫困统计 | 贫困人口比率，贫困差距以及国际和国家贫困线贫困人口数量的指标。 | +| EUREKA | Eurekahedge数据 | 一家研究公司专注于对冲基金和其他另类投资基金。它公布了对冲基金业绩的数据。 | +| MOFJ | 日本财务省数据 | 日本政府债券利率数据，由财政部每日公布。 | +| PIKETTY | Thomas Piketty数据 | “21世纪资本”中的收入和财富数据，哈佛大学出版社，2014。 | +| PSX | 巴基斯坦证交所数据 | 巴基斯坦证券交易所的股票收盘价格。 | +| SGX | 新加坡交易所数据 | 亚洲证券和衍生品交易所为许多大型新加坡和其他亚洲公司进行股票交易。在自己的交易所上市。 | +| UIFS | 联合国国际金融统计 | 该数据库提供有关国际财务指标的综合数据，如平均收入，债券收益率，政府收入和支出。 | +| UINC | 联合国工业商品数据 | 该数据库提供有关工业商品生产的全球数据，如矿石和矿物，食品，可运输货物和金属产品。 | +| INSEE | 国家统计和经济研究所（法国）数据 | INSEE是法国的国家统计机构。它收集有关法国经济和社会的数据，如社会经济指标和国民账户。 | +| SNB | 瑞士国家银行数据 | 中央银行负责货币政策和货币。有关国际账户，利率，货币供应和其他宏观经济指标的数据。 | +| ODE | 大阪道岛商品交易所数据 | 日本关西地区的一个非营利性商品交易所，交易七种主要农产品。 | +| WGEN | 世界银行性别统计 | 描述收入，工作类型，工作部门，农民生产率以及企业家公司规模和利润的性别差异的数据。 | +| WHNP | 世界银行健康营养与人口统计 | 关键的健康，营养和人口统计数据。 | +| WIDA | 世界银行国际发展协会 | 关于选定指标的IDA（国际开发协会）国家总体成果进展情况的数据。 | +| ECMCI | 欧盟委员会货币状况指数 | 每月更新，此数据库提供欧元区的货币状况指数值。历史可以追溯到1999年。 | +| NBSC | 中国国家统计局数据 | 中国有关金融，工业，贸易，农业，房地产和交通运输的统计数据。 | +| MAS | 新加坡金融管理局数据 | nan | +| MGEX | 明尼阿波利斯谷物交易所数据 | 促进农业指数贸易的区域商品期货和期权合约市场。 | +| WWGI | 世界银行全球治理指标 | 六个治理层面的总体和个别治理指标数据。 | +| ISM | 供应管理研究所 | ISM促进供应链管理实践，并发布有关生产和供应链，新订单，库存和资本支出的数据。 | +| UKR | 乌克兰交易所数据 | nan | +| FRBNY | 纽约联邦储备银行数据 | FRBNY是美国最大的区域中央银行。为纽约，康涅狄格州和新泽西州的大部分地区以及一些地区设定货币政策。 | +| FRBP | 费城联邦储备银行数据 | FRBP是美联储的区域中央银行。它发布有关商业信心指数，GDP，消费和其他经济指标的数据。 | +| FMSTREAS | 美国财政部 - 财务管理处数据 | 美利坚合众国的月收入/支出和赤字/盈余。 | +| EIA | 美国能源信息管理局数据 | 美国国家和州有关所有主要能源产品（如电力，煤炭，天然气和石油）的生产，消费和其他指标的数据。 | +| SOCSEC | 美国社会保障局数据 | 提供有关美国社会保障计划的数据，特别是受益人的人口统计数据;残疾人，老人和幸存者。 | +| TFGRAIN | 顶级飞行谷物合作社数据 | 玉米和大豆的现货价格，包括前月期货合约的基础。 | +| IRPR | 波多黎各统计研究所数据 | 波多黎各统计研究所制造业统计数据。 | +| BCHAIN | blockchain.com数据 | Blockchain是一个发布与比特币相关的数据的网站，每日更新。 | +| BITCOINWATCH | Bitcoin Watch数据 | 比特币采矿统计。 | +| ODA | 国际货币基金组织跨国宏观经济统计 | 国际货币基金组织的初级商品价格和世界经济展望数据，由非洲开放数据公布。优秀的跨国宏观经济数据。 | +| WADI | 世界银行非洲发展指标 | 关于非洲的一系列发展指标，包括国家，区域和全球估计数。 | +| WEDU | 世界银行教育统计 | 关于教育机会，进展，完成，扫盲，教师，人口和支出的国际可比指标。 | +| WGLF | 世界银行全球Findex（全球金融包容性数据库） | 关于人们如何储蓄，借贷，支付和管理风险的金融包容性指标。 | +| WWID | 世界财富和收入数据库 | 世界财富和收入数据库旨在提供开放和便捷的途径，以获取有关国家内部和国家之间世界收入和财富分配历史演变的最广泛的现有数据库。 | +| BTER | 比特儿数据 | 加密货币的历史汇率数据。 | +| CFTC | 商品期货交易委员会报告 | 交易员和集中比率的每周承诺。期货头寸以及期货加期权头寸的报告。新旧格式。 | +| BOE | 英格兰银行官方统计 | 当前和历史汇率，担保贷款和定期存款利率，欧元商业票据利率和政府证券收益率。 | +| EXMPL | Quandl时间序列数据示例 | 一个时间序列数据库示例。 | +| WORLDAL | 铝价格 | 世界铝产能和产量（千公吨）。 | +| WGC | 黄金价格 | 世界黄金协会是黄金行业的市场开发组织。它以不同货币发布黄金价格数据。 | +| MX | 加拿大期货数据 | 蒙特利尔交易所是一家衍生品交易所，交易期货合约以及股票，指数，货币，ETF，能源和利率的期权。 | +| UMICH | 消费者情绪 | 密歇根大学的消费者调查 - 最近6个月的数据点是非官方的;它们来自华尔街日报的文章。 | +| JOHNMATT | 稀有金属价格数据 | 关于铂族金属的当前和历史数据，如价格，供应和需求。 | +| NAHB | 美国住房指数 | 美国的住房和经济指数。 | +| RATEINF | 通货膨胀率 | 阿根廷，澳大利亚，加拿大，德国，欧元区，法国，意大利，日本，新西兰等国的通货膨胀率和消费物价指数CPI。 | +| RENCAP | IPO数据 | 有关美国IPO市场的数据。 | +| ML | 公司债券收益率数据 | 美林（Merrill Lynch）是美国一家大型银行，它发布了不同地区公司债券收益率的数据。 | +| MULTPL | S&P 500 | nan | +| RICI | 商品指数 | 综合，以美元为基础的总回报指数，代表全球经济中消费的一篮子商品的价值。 | +| AAII | 投资者情绪 | 美国个人投资者协会的情绪数据。 | +| BIS | 国际清算银行数据 | 国际清算银行为中央银行提供货币和金融稳定管理，促进国际合作，并作为中央银行的银行。 | +| BCB | 巴西中央银行统计数据库 | 巴西宏观经济数据，涵盖公共财政，国民账户，支付系统，通货膨胀，汇率，贸易和国际储备。 | +| BCRA | 阿根廷中央银行数据 | 阿根廷中央银行负责货币政策，提供外汇市场数据和主要宏观经济指标。 | +| FSE | 法兰克福证券交易所 | 法兰克福证券交易所的每日股票价格 | +| BLSN | 劳工统计局国际数据 | 各国的进出口价格统计，由劳工统计局公布。 | +| BLSP | 劳工统计局生产力数据 | 美国制造业，劳务和商业统计，由劳工统计局公布。 | +| FDIC | 联邦存款保险公司数据 | FDIC是一家银行存款高达25万美元的联邦保险公司，负责收集商业银行和储蓄机构的财务数据。 | +| BLSI | 美国劳工统计局通货膨胀和价格统计 | 美国国家和州一级的通胀数据，由劳工统计局公布。 | +| BLSE | 美国劳工统计局就业与失业统计 | 美国国家和州一级的就业和失业统计数据，由劳工统计局公布。 | +| BLSB | 美国劳工统计局薪酬福利统计 | 由劳工统计局公布的美国停工统计数据。 | +| BP | BP能源生产和消费数据 | BP是一家大型能源生产商和分销商。它提供了各个国家和较大次区域的能源生产和消费数据。 | +| LPPM | 白金和钯价格数据 | 全球钯金和铂金市场清算价格数据。 | +| CASS | 运费指数 | 自1990年以来，CASS每月提供与其他经济和供应链指标相关的货运趋势的CASS运费指数报告。 | +| MORTGAGEX | 可调利率抵押贷款指数 | ARM索引的历史住房数据。 | +| BUCHARESTSE | 布加勒斯特证券交易所数据 | 布加勒斯特证券交易所发布股票，权利，债券，基金单位，结构性产品和期货合约活动数据。 | +| AMECO | 欧盟委员会年度宏观经济数据库 | 欧洲委员会经济和财政事务总局（DG ECFIN）年度宏观经济数据库。 | +| ACC | 美国化学理事会数据 | 化学活性晴雨表（CAB）由美国化学理事会（ACC）出版。 CAB是一个经济指标，有助于预测整个美国经济的高峰和低谷，并突出了美国其他行业的潜在趋势。 | +| ABMI | 亚洲债券市场计划 | 中国和日本债券市场的指标，如规模和构成，市场流动性，收益率收益率和波动率。 | +| BITAL | 意大利证交所数据 | 该数据库提供了Borsa Italiana（现为伦敦证券交易所集团的一部分）的股票期货合约数据。 | +| BANKRUSSIA | 俄罗斯银行数据 | 俄罗斯银行的主要指标，包括银行业，货币供应量，金融市场和宏观经济统计数据。 | +| BOC | 加拿大银行统计数据库 | 加拿大的经济，金融和银行数据。包括利率，通货膨胀，国民账户等。每日更新。 | +| HKEX | 香港交易所数据 | 香港交易所股票价格，历史分割期货等每日更新。 | +| AMFI | 印度共同基金协会数据 | 该数据库代表印度共同基金协会的基金信息。 | +| BDM | 墨西哥银行数据 | 墨西哥银行负责货币政策和本国货币（比索），并提供账户和所有宏观经济变量的数据。 | +| BATS | BATS美国证券交易所数据 | Bats是美国的股票市场运营商，经营四个股票交易所--BZX Exchange，BYX Exchange，EDGA Exchange和EDGX Exchange | +| BSE | 孟买证券交易所数据 | 在印度孟买证券交易所交易的公司的日终价格，指数和其他信息。 | +| FRED | 美联储经济数据 | 来自圣路易斯联邦储备银行研究部门的增长，就业，通货膨胀，劳工，制造业和其他美国经济统计数据。 | +| FMAC | 房地美数据 | Freddie Mac的主要抵押贷款市场调查和其他地区特定历史抵押贷款利率的数据。 | +| EUREX | 欧洲期货交易所数据 | 欧洲最大的期货交易所EUREX的指数，利率，农业和能源期货，历史跨越了特定期货的十年。 | +| ECB | 欧洲中央银行数据 | 欧盟中央银行监督货币政策和欧元，并提供相关宏观经济变量的数据。 | +| BOF | 法国银行数据 | 法兰西银行通过欧洲中央银行体系的政策负责货币政策，并提供关键经济指标的数据。 | +| BELGRADESE | 贝尔格莱德证券交易所数据 | 贝尔格莱德证券交易所数据，每日更新。 | +| CHRIS | 维基连续期货 | Quandl所有600个期货的连续合约。建立在CME，ICE，LIFFE等原始数据之上。由Quandl社区策划。 50年的历史。 | +| BOJ | 日本银行数据 | nan | +| USTREASURY | 美国财政部数据 | 美国财政部确保国家的金融安全，管理国家债务，收取税收，发行货币，提供收益率数据。 | +| LBMA | 伦敦金银市场协会数据 | 伦敦黄金和白银市场的国际贸易协会，由中央银行，私人投资者，生产商，炼油商和其他代理商组成。 | +| PERTH | 珀斯铸币厂数据 | 珀斯造币厂的利率和商品价格的高点，低点和平均值每月更新一次。 | +| ZILLOW2 | Zillow房地产研究 | 房屋价格和租金按大小，类型和等级划分;住房供应，需求和销售。按邮政编码，街区，城市，都市区，县和州切片。 | \ No newline at end of file diff --git a/website/translated_docs/zh-CN/quickstart.md b/website/translated_docs/zh-CN/quickstart.md new file mode 100644 index 0000000..5e1d997 --- /dev/null +++ b/website/translated_docs/zh-CN/quickstart.md @@ -0,0 +1,183 @@ +--- +id: quickstart +title: Quick Start +--- + + +## CovenantSQL Client + +### Install + +Please choose the installation method according to the operating system platform you use: + +#### MacOS + +- 🍺 Homebrew users can just run: + +```bash + brew install cql + ``` + +- non-Homebrew users can run: + + ```bash + sudo bash -c 'curl -L "https://mac.gridb.io/cql" | \ + tar xzv -C /usr/local/bin/ --strip-components=1' + ``` + +#### Linux + +- Just run： + + ```bash + sudo bash -c 'curl -L "https://linux.gridb.io/cql" | \ + tar xzv -C /usr/local/bin/ --strip-components=1' + ``` + +After the installation is complete, you can execute the following command to check whether the installation is successful. + +```bash +cql version +``` + +If you have any errors on the MacOS or Linux, you can try the following to fix it: + +```bash +sudo chmod a+x /usr/local/bin/cql* # Fix Permission +sudo ln -s /usr/local/bin/cql* /usr/bin/ # Fix if /usr/local/bin not in $PATH +``` + +If the problem persists please check out our GitHub page [submit issue](https://github.com/CovenantSQL/CovenantSQL/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D) + +### Utils + +| Tool | Introduction | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| cql | CovenantSQL client, `cql console` command is similar to the `mysql` command and is used to manage the CQL databases, [More](./cql_intro) | +| cql-fuse | CovenantSQL's FUSE client, which can mount a CovenantSQL database as a file system | +| cql-minerd | CovenantSQL miner client, used to run the database to earn rewards, will open later | +| cqld | CovenantSQL main chain node, mainly run by CovenantLabs and partners in DPoS mode | + +> Windows platform we will release later, if there is a need please [submit issue](https://github.com/CovenantSQL/CovenantSQL/issues/new?assignees=&labels=&template=feature_request.md&title=) + +### TestNet + +At present, we have released the test network v0.8.0 for everyone to verify and experience the principle. You can choose to quickly perform access testing using the "public account". + +The configuration file and private key of the "public account":[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) (empty password)，or just run： + +```bash +mkdir -p ~/.cql/testnet-conf +curl -L https://git.io/fhFZe --output ~/.cql/testnet-conf/config.yaml +curl -L https://git.io/fhFZv --output ~/.cql/testnet-conf/private.key +chmod 600 ~/.cql/testnet-conf/private.key +``` + +**TestNet Notes**： + +> The "public account" is public and only for testing. Please do not store your application information in the database created by the "public account". We will clean the database data from time to time. +> +> The test network is temporarily composed of 3 Miners, so temporarily only supports `create 3` to create a database of 3 nodes. + +## Create a testnet database + +```bash +cql create -config=~/.cql/testnet-conf/config.yaml \ + -db-node 1 -wait-tx-confirm +``` + +The command execution takes a little long time, and after about 30 seconds the console outputs something like below: + +> covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + +​ + +This means that you submitted the database(dsn) `covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` creation request to the main chain and created the database to complete. + +> Command execution takes some time, and the general process is: +> +> 1. The "Block Producer" that received the request performs a match of Miner and database creation requests. +> 2. Database creation request is verified and confirmed at other "Block Producer" nodes +> 3. Eligible Miner on SQLChain receives database task +> 4. SQLChain Miners builds a database cluster with Kayak +> 5. All Miners are ready to wait for a database request + +## Access the testnet database + +```bash +cql console -config=~/.cql/testnet-conf/config.yaml \ + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +After connecting to the database, you can manipulate the database on CovenantSQL according to your habit of operating the database. For example, execute `CREATE TABLE` to create a table, `SELECT` query data, and so on. + +## SQLChain Explorer + +One feature of CovenantSQL is that its query records are **immutable and traceable**, you can query the operation of a database through \[Test Web Block Browser\] (https://explorer.dbhub.org/) recording. + +> The TestNet's SQLChain Explorer is currently open-access, and anyone who knows the database ID can manipulate your data using TestNet's public key. + +Please fill in your database ID in the upper right corner of the page. For example: `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872`. You can see information about all the data created using TestNet's Key: + +![explorer](https://github.com/CovenantSQL/docs/raw/master/website/static/img/explorer.png) + +> **If you want to create your own private database, you need to create a new public-private key pair from scratch, please refer to the following section.** + +## Create your own account + +Our test network allows you to create your own account and create a database under your own account. Create an account with the following command (default empty passphrase for private.key, you can add `-with-password` to set passphrase)： + +```bash +cql generate +``` + +Output： + + Generating private key... + Please enter password for new private key + Generated private key. + Generating nonce... + INFO cpu: 4 + INFO position: 2, shift: 0x0, i: 2 + INFO position: 0, shift: 0x0, i: 0 + INFO position: 3, shift: 0x0, i: 3 + INFO position: 1, shift: 0x0, i: 1 + nonce: {{973366 0 586194564 0} 26 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b} + node id: 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b + Generated nonce. + Generating config file... + Generated config. + + Config file: ~/.cql/config.yaml + Private key file: ~/.cql/private.key + Public key's hex: 03f195dfe6237691e724bcf54359d76ef388b0996a3de94a7e782dac69192c96f0 + + Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + Any further command could costs PTC. + You can get some free PTC from: + https://testnet.covenantsql.io/wallet/dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + +This command will create a `.cql` directory for you in your `$HOME` directory: + +- `~/.cql/private.key`: The generated private key is stored in the file by the master password encryption, and your account address needs to be created using this file; +- `~/.cql/config.yaml`: The generated configuration, cql can access the CovenantSQL TestNet with it. + +It alse print your wallet address(also called the account address, CovenantSQL address): `Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95` + +You can get the test PTC here with the wallet address obtained above: \[Request for PTC\] (https://testnet.covenantsql.io/). + +After up to 2 minutes while requested PTC, you can use the cql command line tool to check the balance: + +```bash +cql wallet +``` + +output： + + Particle balance is: 10000000 + Wave balance is: 0 + + +Congratulations, you have received our PTC stable currency, and you can start using CovenantSQL now. You can refer to [Golang uses CovenantSQL documentation](./driver_golang) for development. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/usecase.md b/website/translated_docs/zh-CN/usecase.md new file mode 100644 index 0000000..0ca5313 --- /dev/null +++ b/website/translated_docs/zh-CN/usecase.md @@ -0,0 +1,5 @@ +--- +id: usecase +title: 使用案例 +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/usecase_dapp.md b/website/translated_docs/zh-CN/usecase_dapp.md new file mode 100644 index 0000000..777b2d0 --- /dev/null +++ b/website/translated_docs/zh-CN/usecase_dapp.md @@ -0,0 +1,6 @@ +--- +id: usecase_dapp +title: DApp +--- + +Storing data on Bitcoin or Ethereum is quite expensive ($4305 / MB on Ethereum 2018-05-15). Programming is very complicated due to the lack of support for structured data storage. CQL gives you a low-cost structured SQL database and also provides more room for ĐApp to exchange data with real-world. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/usecase_data_analysis.md b/website/translated_docs/zh-CN/usecase_data_analysis.md new file mode 100644 index 0000000..37b33f4 --- /dev/null +++ b/website/translated_docs/zh-CN/usecase_data_analysis.md @@ -0,0 +1,300 @@ +--- +id: usecase_data_analysis +title: Data Analysis +--- + +# Financial data analysis based on Quandl + +## About Quandl + +Quandl is a big data platform for the financial investment industry. Its data sources include public data such as the United Nations, the World Bank, and the Central Bank. The core financial data comes from CLS Group, Zacks and ICE. All data comes from more than 500 publishers. It is the preferred platform for investment professionals to provide financial, economic and alternative data with vast economic and financial data. + +## Quandl Data Index + +### Introduction to CovenantSQL + +First, we have stored the data in CovenantSQL based on Quandl's open API. Next, you should take a look at the introduction of CovenantSQL to know how to connect and use CovenantSQL. + +Now due to client compatibility issues, please use our HTTP service to query the Quandl database directly. This document will be updated as soon as possible after the current cql client is compatible. + +Use CovenantSQL specifically through the HTTP service. Please refer to the Python driver documentation and the NodeJS driver documentation. + +Required parameters: + + host: 'e.morenodes.com' + port: 11111 + database: '057e55460f501ad071383c95f691293f2f0a7895988e22593669ceeb52a6452a' + + +### How to use CQL-Quandl + +Quandl data is divided into tables and sub-tables + +In the database, the table name is `quandl_ + database_code` for the full table name + +View the contents of the table by querying the table name + +For specific use, you need to use the `quandl_updateindex` index table to use it. (When querying the index table, be sure to limit less than 100,000 because the full data is too large) + +Please using the `where` statement to qualify the `quandlcode` field to query the sub table data in the table. + +## Example + +1. We want to query the data of the European Commission's annual macroeconomic database. We find the database code of its first index is `quandl_ameco`, so we can query its second index, using the following SQL command line: + +```SQL + select * from quandl_updateindex where databasecode like 'ameco' group by quandlcode limit 10000; + ``` + +2. Then through the third column, we can see the description corresponding to the `quandlcode` + + For example, `AMECO/ALB_1_0_0_0_AAGE` corresponds to the import and export information of Albania from 1960 to 1988. + + Average share of imports and exports of goods in world trade excluding intra EU trade; Foreign trade statistics (1960-1998 Former EU-15) - Albania + + So, we can query this subtable in the following way. + + ```SQL + select * from quandl_ameco where quandlcode like 'AMECO/ALB_1_0_0_0_AAGE' limit 10000; + ``` + +3. Note: If the content of the content is null, it belongs to the field that does not exist in the table structure itself, you can remove it yourself. + +# Quandl Data Excel Plugin Instructions + +You can download the Quandl Data Excel plugin without having to install it, unzip it into any folder. This plugin currently only supports Office 2010 and above, and Office 2007 and below are currently not supported. + +## Configuring the Excel plugin + +Unzip the downloaded package. There are two .xll files in the folder, `ClassLibrary7-AddIn.xll` and `ClassLibrary7-AddIn64.xll` files. These two files correspond to 32-bit Excel and 64-bit Excel respectively. Please refer to your The computer configuration uses the corresponding plugin. + +### Modify the xml configuration + +Each .xll file corresponds to a .config configuration file, which is `ClassLibrary7-AddIn.xll.config` and `ClassLibrary7-AddIn64.xll.config`, configured for the following xml: + +```xml + + + + + + + + + +``` + +The following configuration needs to be modified and saved: + +`Certpath`: Please fill in the absolute path of the `read.data.covenantsql.io.pfx` certificate + +### Plugin installation + +There are two ways to use this Excel plugin + +1. Double-click the corresponding 32-bit or 64-bit Excel xll file to open it. + +![quandl_ext_1](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_1.png) + +If the above dialog box shows up, select the first one: Enable this add-on only for this callback. Then create a new Excel table. If you see CovenantSQL in the upper tab of Excel, the plugin is loaded successfully. + +2. Open Excel, then select File - Options - Add-ons, Manage Select Excel Add-Ins, click Go and browse to select the .xll file for the corresponding version after decompression, and then click OK. If you successfully load CovenantSQL in the tab, Successfully loaded, as shown below: + +![quandl_ext_2](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_2.png) + +### How to use plugin + +Select the CovenantSQL tab to see the Quandl data query. Click on the Quandl data query and a pop-up will appear as shown below: + +![quandl_ext_3](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_3_en.png) + +- The part of the list that is framed by red is the first-level directory, and the lower part is the specific description of the selected item. +- The green button queries the se condary directory by selecting the primary directory. The query time will vary depending on the size of the secondary directory being queried and the user's own network speed. The query time may exceed 1 minute. Please be patient. +- The list on the left of the yellow part is the secondary directory, and the form on the right is the description of the table selected by the list item. + +- The blue part is an option to export data + + - Limit Number is the maximum number of data exported at a time. The default is 10000, and the maximum value can be filled in 100000. + - Offset Number is derived from the first few columns of the database, because the number of bars is limited. For example, we exported 10000 data before, but the obvious data has not been exported yet. We can use this function to select offset 10000 to start from the 10000th. Export (Note: the database count starts from 0, so the first 10000 is 0-9999) + +## Attachment + +| Database | Name | description | +| ------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| PIKETTY | Thomas Piketty | Data on Income and Wealth from "Capital in the 21st Century", Harvard University Press 2014. | +| BUNDESBANK | Deutsche Bundesbank Data Repository | Data on the German economy, money and capital markets, public finances, banking, households, Euro-area aggregates, trade and external debt. | +| URC | Unicorn Research Corporation | Advance and decline data for the NYSE, AMEX, and NASDAQ stock exchanges. From various publicly-available sources and the median value is reported. | +| DCE | Dalian Commodities Exchange | Agriculture and commodities futures from DCE, with history spanning almost a decade for select futures. | +| WFC | Wells Fargo Home Mortgage Loans | This database offers mortgage purchase and refinance rates from Wells Fargo Home Mortgage, a division of Wells Fargo Bank. | +| USDAFNS | U.S. Department of Agriculture FNS | Food and Nutrition Service administrates federal nutrition assistance programs for low-income households and children. Data on costs and participation rates. | +| LJUBSE | Ljubljana Stock Exchange (Slovenia) | This database contains the Ljubljana Stock Exchange indexes and is based in Ljubljana, Slovenia. | +| TOCOM | Tokyo Commodities Exchange | Agriculture and commodities futures from Tokyo Commodities Exchange (TOCOM), with history spanning almost a decade for select futures. | +| WCSC | World Bank Corporate Scorecard | This database is designed to provide a strategic overview of the World Bank Group’s performance toward ending extreme poverty and promoting shared prosperity. | +| CMHC | Canadian Mortgage and Housing Corporation | The CMHC is a gov’t-owned corporation that provides affordable housing to Canadian citizens and collects data such as prices, construction, and supply. | +| WGEC | World Bank Global Economic Monitor (GEM) Commodities | Data containing commodity prices and indices from 1960 to present. | +| FED | US Federal Reserve Data Releases | Official US figures on money supply, interest rates, mortgages, government finances, bank assets and debt, exchange rates, industrial production. | +| WPSD | World Bank Public Sector Debt | Data jointly developed by the World Bank and the International Monetary Fund, which brings together detailed public sector government debt data. | +| UGID | United Nations Global Indicators | This database offers a wide range of global indicators, covering population, public health, employment, trade, education, inflation and external debt. | +| RBA | Reserve Bank of Australia | Central bank and monetary authority, regulates banking industry, sets interest rates, and services governments debt. Data on key economic indicators. | +| UCOM | United Nations Commodity Trade | This database offers comprehensive global data on imports and exports of commodities such as food, live animals, pharmaceuticals, metals, fuels and machinery. | +| SIDC | Solar Influences Data Analysis Center | The SIDC hosts data spanning from the 1700s on solar activity, specifically sunspot activity. | +| ZCE | Zhengzhou Commodities Exchange | Agriculture and commodities futures from ZCE, with history spanning almost a decade for select futures. | +| USDAFAS | U.S. Department of Agriculture FAS | The USDA Foreign Agricultural Service connects U.S. agriculture with the world markets. It provides statistics on production and exports in foreign countries. | +| OECD | Organisation for Economic Co-operation and Development | International organization of developed countries that promotes economic welfare. Collects data from members and others to make policy recommendations. | +| OPEC | Organization of the Petroleum Exporting Countries | International organization and economic cartel overseeing policies of oil-producers, such as Iraq, Iran, Saudi Arabia, and Venezuela. Data on oil prices. | +| MCX | Multi Commodity Exchange India | Indias largest commodity exchange servicing futures trading in metals, energy, and agriculture. Worlds 3rd largest exchange in contracts and trading volume. | +| ECONOMIST | The Economist - Big Mac Index | The Big Mac index was invented by The Economist in 1986 as a lighthearted guide to whether currencies are at their “correct” level. It is based on the theory of purchasing-power parity (PPP). | +| NSDL | National Securities Depository Limited (India) | Depository in India responsible for economic development of the country that has established a national infrastructure of international standards that handles most of the securities held and settled in dematerialised form in the Indian capital market. | +| GDT | Global Dairy Trade | nan | +| CFFEX | China Financial Futures Exchange | Index and bond futures from CFFEX, with history spanning almost a decade for select futures. | +| CITYPOP | Thomas Brinkhoff: City Populations | Thomas Brinkhoff provides population data for cities and administrative areas in most countries. | +| BCHARTS | Bitcoin Charts Exchange Rate Data | Exchange rates for bitcoin against a large number of currencies, from all major bitcoin exchanges, including current and historical exchange rates. | +| LOCALBTC | Local Bitcoins | nan | +| JODI | JODI Oil World Database | JODI oil and gas data comes from over 100 countries consisting of multiple energy products and flows in various methods of measurement. | +| UENG | United Nations Energy Statistics | This database offers comprehensive global statistics on production, trade, conversion, and final consumption of new and renewable energy sources. | +| ULMI | United Nations Labour Market Indicators | This database offers comprehensive youth unemployment figures broken up by gender for all countries in the world. | +| MAURITIUSSE | Stock Exchange of Mauritius | Stock Exchange of Mauritius indices data. | +| UKRSE | Ukrainian Exchange | UKRSE presents the most current available data related to the largest stock exchanges in Ukraine. The exchange is located in Kiev and accounts for roughly three-quarters of Ukraines total equity trading volume | +| BITSTAMP | Bitstamp | Bitstamp is a trading platform for Bitcoin. | +| UNAE | United Nations National Accounts Estimates | This database offers global data on gross domestic product, gross national income, and gross value added by different sectors for all countries in the world. | +| UNAC | United Nations National Accounts Official Country Data | This database offers global data on national accounts, such as assets and liabilities of households, corporations and governments. | +| UTOR | United Nations World Tourism | This database offers comprehensive data on international tourism. Data includes number of tourist arrivals and tourism expenditures for all countries. | +| WFE | World Federation of Exchanges | A trade association of sixty publicly regulated stock, futures, and options exchanges that publishes data for its exchanges, like market capitalization. | +| FRBC | Federal Reserve Bank of Cleveland | The Federal Reserve Bank of Cleveland collects data from hundreds of financial institutions, including depository institutions, bank holding companies, and other entities that is used to assess financial institution conditions and also to glean insights into how the economy and financial system are doing. | +| UGEN | United Nations Gender Information | This database offers comprehensive global data on a wide range of gender-related indicators, covering demography, health, education and employment. | +| BITFINEX | Bitfinex | Bitfinex is a trading platform for Bitcoin, Litecoin and Darkcoin with many advanced features including margin trading, exchange and peer to peer margin funding. | +| UGHG | United Nations Greenhouse Gas Inventory | This database offers comprehensive global data on anthropogenic emissions of the six principal greenhouse gases. Data goes back to 1990. | +| UIST | United Nations Industrial Development Organization | This database offers global data on industrial development indicators, including output, employees, wages, value added for a wide range of industries. | +| PRAGUESE | Prague Stock Exchange | Price index data from the Prague Stock Exchange. | +| PFTS | PFTS Stock Exchange (Ukraine) | Index data from the PFTS Stock Exchange, the largest marketplace in Ukraine. | +| WARSAWSE | Warsaw Stock Exchange | WIG20 index has been calculated since April 16, 1994 based on the value of portfolio with shares in 20 major and most liquid companies in the WSE Main List. | +| TUNISSE | Tunis Stock Exchange | The main reference index of Tunis Stock Exchange. | +| FRKC | Federal Reserve Bank of Kansas City | FRKC is the regional central bank for the 10th District of the Federal Reserve, publishing data on banking in mostly agricultural transactions. | +| UENV | United Nations Environment Statistics | This database offers global data on water and waste related indicators, including fresh water supply and precipitation, and generation and collection of waste. | +| UFAO | United Nations Food and Agriculture | This database offers global food and agricultural data, covering crop production, fertilizer consumption, use of land for agriculture, and livestock. | +| TAIFEX | Taiwan Futures Exchange | Index and bond futures from TAIFEX, with history spanning over a decade for select futures. | +| GDAX | GDAX (Global Digital Asset Exchange) | GDAX is the world’s most popular place to buy and sell bitcoin. | +| ARES | Association for Real Estate Securitization | ARES protects investors, contributes to development of the real estate securitization product market, and facilitates expansion of the real estate investment market. | +| SHADOWS | Wu-Xia Shadow Federal Funds Rate | This dataset contains the three major indicators from the Wu-Xia papers which serve to identify the shadow rates on all three major banks. | +| NAAIM | NAAIM Exposure Index | The NAAIM Exposure Index represents the average exposure to US Equity markets reported by NAAIM members. | +| CBRT | Central Bank of the Republic of Turkey | CBRT is responsible for taking measures to sustain the stability of the financial system in Turkey. | +| CEGH | Central European Gas Hub | No description for this database yet. | +| FINRA | Financial Industry Regulatory Authority | Financial Industry Regulatory Authority provides short interest data on securities firms and exchange markets. | +| NASDAQOMX | NASDAQ OMX Global Index Data | Over 35,000 global indexes published by NASDAQ OMX including Global Equity, Fixed Income, Dividend, Green, Nordic, Sharia and more. Daily data. | +| EURONEXT | Euronext Stock Exchange | Historical stock data from Euronext, the largest European exchange. | +| UICT | United Nations Information and Communication Technology | This database offers comprehensive global data on information and communication technology, including telephone, cellular and internet usage for all countries. | +| USAID | U.S. Agency for International Development | US Agency for International Development provides a complete historical record of all foreign assistance provided by the United States to the rest of the world. | +| ZAGREBSE | Zagreb Stock Exchange | Croatias only stock exchange. It publishes data on the performance of its stock and bond indexes. | +| QUITOSE | Quito Stock Exchange (Ecuador) | The indexes of the national Stock Exchange of Ecuador. | +| ECBCS | European Commission Business and Consumer Surveys | Data in this database is derived from harmonized surveys for different sectors of the economies in the European Union (EU) and in the EU applicant countries. | +| PSE | Paris School of Economics | This database describes the distribution of top incomes in a growing number of countries. Numbers are derived using tax data. | +| MALTASE | Malta Stock Exchange | The Malta Stock Exchange carries out the role of providing a structure for admission of financial instruments to its recognised lists which may subsequently be traded on a regulated, transparent and orderly market place (secondary market).The main participants in the market are Issuers, Stock Exchange Members (stockbrokers), and the investors in general. | +| GPP | Global Petroleum Prices | No description for this database yet. | +| PPE | Polish Power Exchange (TGE) | No description for this database yet. | +| UKONS | United Kingdom Office of National Statistics | Data on employment, investment, housing, household expenditure, national accounts, and many other socioeconomic indicators in the United Kingdom. | +| NCDEX | National Commodity & Derivatives Exchange Limited (India) | A professionally managed on-line multi-commodity exchange in India | +| WSE | Warsaw Stock Exchange (GPW) | No description for this database yet. | +| TFX | Tokyo Financial Exchange | The Tokyo Financial Exchange is a futures exchange that primary deals in financial instruments markets that handle securities and market derivatives. | +| WGFD | World Bank Global Financial Development | Data on financial system characteristics, including measures of size, use, access to, efficiency, and stability of financial institutions and markets. | +| CEPEA | Center for Applied Studies on Applied Economics (Brazil) | CEPEA is an economic research center at the University of Sao Paulo focusing on agribusiness issues, publishing price indices for commodities in Brazil. | +| SBJ | Statistics Bureau of Japan | A Japanese government statistical agency that provides statistics related to employment and the labour force. | +| WGEM | World Bank Global Economic Monitor | Data on global economic developments, with coverage of high-income, as well as developing countries. | +| WGDF | World Bank Global Development Finance | Data on financial system characteristics, including measures of size, use, access to, efficiency, and stability of financial institutions and markets. | +| WWDI | World Bank World Development Indicators | Most current and accurate development indicators, compiled from officially-recognized international sources. | +| WESV | World Bank Enterprise Surveys | Company-level private sector data, covering business topics including finance, corruption, infrastructure, crime, competition, and performance measures. | +| WDBU | World Bank Doing Business | Data on business regulations and their enforcement for member countries and selected cities at the subnational and regional level. | +| OSE | Osaka Securities Exchange | The second largest securities exchange in Japan. Unlike the TSE, OSE is strongest in derivatives trading, the majority of futures and options in Japan. | +| RFSS | Russian Federation Statistics Service | The Russian governmental statistical agency that publishes social, economic, and demographic statistics for Russia at the national and local levels. | +| SHFE | Shanghai Futures Exchange | Commodities exchange for energy, metal, and chemical-related industrial products. A derivatives marketplace for many commodities futures. | +| WGEP | World Bank GEP Economic Prospects | Data on the short-, medium, and long-term outlook for the global economy and the implications for developing countries and poverty reduction. | +| USMISERY | United States Misery Index | Developed by economist Arthur Okun, the Misery Index is the unemployment rate added to the inflation rate. | +| WJKP | World Bank Jobs for Knowledge Platform | Indicators on labor-related topics. | +| WMDG | World Bank Millennium Development Goals | Data drawn from the World Development Indicators, reorganized according to the goals and targets of the Millennium Development Goals (MDGs). | +| WPOV | World Bank Poverty Statistics | Indicators on poverty headcount ratio, poverty gap, and number of poor at both international and national poverty lines. | +| EUREKA | Eurekahedge | A research company focused on hedge funds and other alternative investment funds. It publishes data on the performances of hedge funds. | +| MOFJ | Ministry of Finance Japan | Japanese government bond interest rate data, published daily by the Ministry of Finance. | +| PSX | Pakistan Stock Exchange | Daily closing stock prices from the Pakistan Stock Exchange. | +| SGX | Singapore Exchange | Asian securities and derivatives exchange that trades in equities for many large Singaporean and other Asian companies. Listed on its own exchange. | +| UIFS | United Nations International Financial Statistics | This database offers comprehensive data on international financial indicators, such as average earnings, bond yields, government revenues and expenditures. | +| UINC | United Nations Industrial Commodities | This database offers global data on production of industrial commodities, such as ores and minerals, food products, transportable goods, and metal products. | +| INSEE | National Institute of Statistics and Economic Studies (France) | INSEE is the national statistical agency of France. It collects data on Frances economy and society, such as socioeconomic indicators and national accounts. | +| SNB | Swiss National Bank | Central bank responsible for monetary policy and currency. Data on international accounts, interest rates, money supply, and other macroeconomic indicators. | +| ODE | Osaka Dojima Commodity Exchange | A non-profit commodity exchange in the Kansai region of Japan that trades in seven key agricultural commodities. | +| WGEN | World Bank Gender Statistics | Data describing gender differences in earnings, types of jobs, sectors of work, farmer productivity, and entrepreneurs’ firm sizes and profits. | +| WHNP | World Bank Health Nutrition and Population Statistics | Key health, nutrition and population statistics. | +| WIDA | World Bank International Development Association | Data on progress on aggregate outcomes for IDA (International Development Association) countries for selected indicators. | +| ECMCI | European Commission Monetary Conditions Index | Updated monthly, this database provides monetary conditions index values in the Euro zone. History goes back to 1999. | +| NBSC | National Bureau of Statistics of China | Statistics of China relating to finance, industry, trade, agriculture, real estate, and transportation. | +| MAS | Monetary Authority of Singapore | No description for this database yet. | +| MGEX | Minneapolis Grain Exchange | A marketplace of futures and options contracts for regional commodities that facilitates trade of agricultural indexes. | +| WWGI | World Bank Worldwide Governance Indicators | Data on aggregate and individual governance indicators for six dimensions of governance. | +| ISM | Institute for Supply Management | ISM promotes supply-chain management practices and publishes data on production and supply chains, new orders, inventories, and capital expenditures. | +| UKR | Ukrainian Exchange | No description for this database yet. | +| FRBNY | Federal Reserve Bank of New York | The FRBNY is the largest regional central bank in the US. Sets monetary policy for New York, most of Connecticut and New Jersey, and some territories. | +| FRBP | Federal Reserve Bank of Philadelphia | The FRBP is a regional central bank for the Federal Reserve. It publishes data on business confidence indexes, GDP, consumption, and other economic indicators. | +| FMSTREAS | US Treasury - Financial Management Service | The monthly receipts/outlays and deficit/surplus of the United States of America. | +| EIA | U.S. Energy Information Administration Data | US national and state data on production, consumption and other indicators on all major energy products, such as electricity, coal, natural gas and petroleum. | +| SOCSEC | Social Security Administration | Provides data on the US social security program, particularly demographics of beneficiaries; disabled, elderly, and survivors. | +| TFGRAIN | Top Flight Grain Co-operative | Cash price of corn and soybeans including basis to front month futures contract. | +| IRPR | Puerto Rico Institute of Statistics | Puerto Rico Institute of Statistics statistics on manufacturing. | +| BCHAIN | Blockchain | Blockchain is a website that publishes data related to Bitcoin, updated daily. | +| BITCOINWATCH | Bitcoin Watch | Bitcoin mining statistics. | +| ODA | IMF Cross Country Macroeconomic Statistics | IMF primary commodity prices and world economic outlook data, published by Open Data for Africa. Excellent cross-country macroeconomic data. | +| WADI | World Bank Africa Development Indicators | A collection of development indicators on Africa, including national, regional and global estimates. | +| WEDU | World Bank Education Statistics | Internationally comparable indicators on education access, progression, completion, literacy, teachers, population, and expenditures. | +| WGLF | World Bank Global Findex (Global Financial Inclusion database) | Indicators of financial inclusion measures on how people save, borrow, make payments and manage risk. | +| WWID | World Wealth and Income Database | The World Wealth and Income Database aims to provide open and convenient access to the most extensive available database on the historical evolution of the world distribution of income and wealth, both within countries and between countries. | +| BTER | BTER | Historical exchange rate data for crypto currencies. | +| CFTC | Commodity Futures Trading Commission Reports | Weekly Commitment of Traders and Concentration Ratios. Reports for futures positions, as well as futures plus options positions. New and legacy formats. | +| BOE | Bank of England Official Statistics | Current and historical exchange rates, interest rates on secured loans and time deposits, Euro-commercial paper rates, and yields on government securities. | +| EXMPL | Quandl Example Time-Series Data | An example time series database. | +| WORLDAL | Aluminium Prices | World Aluminium capacity and production in thousand metric tonnes. | +| WGC | Gold Prices | The World Gold Council is a market development organization for the gold industry. It publishes data on gold prices in different currencies. | +| MX | Canadian Futures | Montreal Exchange is a derivatives exchange that trades in futures contracts and options for equities, indices, currencies, ETFs, energy, and interest rates. | +| UMICH | Consumer Sentiment | The University of Michigan’s consumer survey - data points for the most recent 6 months are unofficial; they are sourced from articles in the Wall Street Journal. | +| JOHNMATT | Rare Metals | Current and historical data on platinum group metals such as prices, supply, and demand. | +| NAHB | US Housing Indices | Housing and economic indices for the United States. | +| RATEINF | Inflation Rates | Inflation Rates and the Consumer Price Index CPI for Argentina, Australia, Canada, Germany, Euro area, France, Italy, Japan, New Zealand and more. | +| RENCAP | IPOs | Data on the IPO market in the United States. | +| ML | Corporate Bond Yield Rates | Merrill Lynch, a major U.S. bank, publishes data on yield rates for corporate bonds in different regions. | +| MULTPL | S&P 500 Ratios | No description for this database yet. | +| RICI | Commodity Indices | Composite, USD based, total return index, representing the value of a basket of commodities consumed in the global economy. | +| AAII | Investor Sentiment | American Association of Individual Investor’s sentiment data. | +| BIS | Bank for International Settlements | BIS serves central banks with administration of monetary and financial stability, fosters international cooperation, and acts as bank for central banks. | +| BCB | Central Bank of Brazil Statistical Database | Brazilian macroeconomic data, covering public finances, national accounts, payment systems, inflation, exchange rates, trade, and international reserves. | +| BCRA | Central Bank of Argentina | The Central Bank of Argentina is responsible monetary policy and provides data on foreign exchange markets and key macroeconomic indicators. | +| FSE | Frankfurt Stock Exchange | Daily stock prices from the Frankfurt Stock Exchange | +| BLSN | BLS International | Import and export price statistics for various countries, published by the Bureau of Labor Statistics. | +| BLSP | BLS Productivity | US manufacturing, labor and business statistics, published by the Bureau of Labor Statistics. | +| FDIC | Federal Deposit Insurance Corporation | The FDIC is a federal insurer of bank deposits up to $250k and collects finance data on commercial banking and savings institutions. | +| BLSI | BLS Inflation & Prices | US national and state-level inflation data, published by the Bureau of Labor Statistics. | +| BLSE | BLS Employment & Unemployment | US national and state-level employment and unemployment statistics, published by the Bureau of Labor Statistics. | +| BLSB | BLS Pay & Benefits | US work stoppage statistics, published by the Bureau of Labor Statistics. | +| BP | Energy Production and Consumption | BP is a large energy producer and distributor. It provides data on energy production and consumption in individual countries and larger subregions. | +| LPPM | Platinum & Palladium Prices | Price data on the market-clearing level for Palladium and Platinum around the world. | +| CASS | Freight Indices | Since 1990, CASS provides monthly Cass Freight Index Reports on freight trends as they relate to other economic and supply chain indicators. | +| MORTGAGEX | ARM Indices | Historical housing data on ARM indexes. | +| BUCHARESTSE | Bucharest Stock Exchange | The Bucharest Stock Exchange publishes data on it activity in equity, rights, bonds, fund units, structured products, and futures contracts. | +| AMECO | European Commission Annual Macro-Economic Database | Annual macro-economic database of the European Commissions Directorate General for Economic and Financial Affairs (DG ECFIN). | +| ACC | American Chemistry Council | Chemical Activity Barometer (CAB) published by the American Chemistry Council (ACC). The CAB is an economic indicator that helps anticipate peaks and troughs in the overall US economy and highlights potential trends in other industries in the US. | +| ABMI | Asia Bond Market Initiative | Indicators of Chinese and Japanese bond markets, such as size and composition, market liquidity, yield returns, and volatility. | +| BITAL | Borsa Italiana | This database provides data on stock future contracts from the Borsa Italiana, now part of London Stock Exchange Group. | +| BANKRUSSIA | Bank of Russia | Primary indicators from the Bank of Russia, including data on the banking sector, money supply, financial markets and macroeconomic statistical data. | +| BOC | Bank of Canada Statistical Database | Economic, financial and banking data for Canada. Includes interest rates, inflation, national accounts and more. Daily updates. | +| HKEX | Hong Kong Exchange | Hong Kong Exchange stock prices, historical divided futures, etc. updated daily. | +| AMFI | Association of Mutual Funds in India | This database represents fund information from The Association of Mutual Funds in India. | +| BDM | Bank of Mexico | The Bank of Mexico is responsible for monetary policy and the national currency (peso), and provides data on accounts and all macroeconomic variables. | +| BATS | BATS U.S. Stock Exchanges | Bats is an equities market operator in the U.S., operating four equities exchanges — BZX Exchange, BYX Exchange, EDGA Exchange, and EDGX Exchange | +| BSE | Bombay Stock Exchange | End of day prices, indices, and additional information for companies trading on the Bombay Stock Exchange in India. | +| FRED | Federal Reserve Economic Data | Growth, employment, inflation, labor, manufacturing and other US economic statistics from the research department of the Federal Reserve Bank of St. Louis. | +| FMAC | Freddie Mac | Data from Freddie Mac’s Primary Mortgage Market Survey and other region specific historical mortgage rates. | +| EUREX | EUREX Futures Data | Index, rate, agriculture and energy futures from EUREX, Europes largest futures exchange, with history spanning a decade for select futures. | +| ECB | European Central Bank | The central bank for the European Union oversees monetary policy and the Euro, and provides data on related macroeconomic variables. | +| BOF | Bank of France | The Banque de France is responsible for monetary policy through policies of the European System of Central Banks and providing data on key economic indictors. | +| BELGRADESE | Belgrade Stock Exchange | Belgrade Stock Exchange data, updated daily. | +| CHRIS | Wiki Continuous Futures | Continuous contracts for all 600 futures on Quandl. Built on top of raw data from CME, ICE, LIFFE etc. Curated by the Quandl community. 50 years history. | +| BOJ | Bank of Japan | nan | +| USTREASURY | US Treasury | The U.S. Treasury ensures the nations financial security, manages the nations debt, collects tax revenues, and issues currency, provides data on yield rates. | +| LBMA | London Bullion Market Association | An international trade association in the London gold and silver market, consisting of central banks, private investors, producers, refiners, and other agents. | +| PERTH | Perth Mint | The Perth Mint’s highs, lows and averages of interest rates and commodities prices, updated on a monthly basis. | +| ZILLOW2 | Zillow Real Estate Research | Home prices and rents by size, type and tier; housing supply, demand and sales. Sliced by zip code, neighbourhood, city, metro area, county and state. | \ No newline at end of file diff --git a/website/translated_docs/zh-CN/usecase_traditional_app.md b/website/translated_docs/zh-CN/usecase_traditional_app.md new file mode 100644 index 0000000..cbd0655 --- /dev/null +++ b/website/translated_docs/zh-CN/usecase_traditional_app.md @@ -0,0 +1,31 @@ +--- +id: usecase_traditional_app +title: Traditional App +--- + +## Privacy data + +If you are a developper of password management tools just like [1Password](https://1password.com/) or [LastPass](https://www.lastpass.com/). You can use CQL as the database to take benefits: + +1. Serverless: no need to deploy a server to store your user's password for sync which is the hot potato. +2. Security: CQL handles all the encryption work. Decentralized data storage gives more confidence to your users. +3. Regulation: CQL naturally comply with [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation). + +## IoT storage + +CQL miners are deployed globally, IoT node can write to nearest CQL miner directly. + +1. Cheaper: Without passing all the traffic through a gateway, you can save a large bandwidth fee. And, CQL is a shared economic database which makes storage cheaper. +2. Faster: CQL consensus protocol is designed for Internet where network latency is unavoidable. + +## Open data service + +For example, you are the most detailed Bitcoin OHLC data maintainer. You can directly expose an online SQL interface to your customers to meet a wide range of query needs. + +1. CQL can limit specific SQL query statements to meet the needs while also balancing data security; +2. CQL can record SQL query records on the blockchain, which is very convenient for customers to check their bills for long-tail customers and billing, like [this](https://explorer.dbhub.org/dbs/7a51191ae06afa22595b3904dc558d41057a279393b22650a95a3fc610e1e2df/requests/f466f7bf89d4dd1ece7849ef3cbe5c619c2e6e793c65b31966dbe4c7db0bb072) +3. For customers with high performance requirements, Slave nodes can be deployed at the customer to meet the needs of customers with low latency queries while enabling almost real-time data updates. + +## Secure storage + +Thanks to the CQL data history is immutable, CQL can be used as a storage for sensitive operational logs to prevent hacking and erasure access logs. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/api-json-rpc.md b/website/translated_docs/zh-CN/version-0.0.6/api-json-rpc.md new file mode 100644 index 0000000..7ec30aa --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/api-json-rpc.md @@ -0,0 +1,440 @@ +--- +id: version-0.0.6-api-json-rpc +title: JSON RPC +original_id: api-json-rpc +--- +> JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. + +CovenantSQL provides a suite of RPC methods in [JSON-RPC 2.0](https://www.jsonrpc.org/specification) for easily accessing to CovenantSQL networks. + +## Javascript API + +[cql.js](https://github.com/covenantsql/cql.js) is a Javascript SDK which has encapsulated the RPC methods in order to give a much more convenient way to talk to the CovenantSQL networks. See the [Javascript API](cql-js.md) for more. + +## JSON RPC Endpoint + +| Network | Provider | URL | +| ------------------------ | ------------- | -------------------------------------- | +| CovenantSQL Test Network | Covenant Labs | https://jsonrpc.testnet.covenantsql.io | +| CovenantSQL Main Network | Covenant Labs | Comming soon :) | + +## JSON RPC API Reference + +### bp_getProtocolVersion + +Returns the current CovenantSQL protocol version. + +#### Parameters + +None. + +#### Returns + +- string - the current CovenantSQL protocol version + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "method": "bp_getProtocolVersion", + "params": [], + "id": 1 +} +``` + +Response: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0.1.0" +} +``` + +### bp_getRunningStatus + +Returns some basic indicators describing the running status of the CovenantSQL network. + +#### Parameters + +None. + +#### Returns + +- object: an object describes the running status of the network. + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getRunningStatus", + "params": [] +} +``` + +Response: + +```js +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "block_height": 182414, // height of the latest block + "count_accounts": 103, // count of the accounts ever created + "count_databases": 912414, // count of the databases ever created + "qps": 10241 // estimated QPS of database operations of the whole net + } +} +``` + +### bp_getBlockList + +Returns a list of the blocks. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------- | ---------------------- | ------ | +| 0 | from | integer | start height, included | 1 | +| 1 | to | integer | end height, excluded | 11 | + +**Constraints:** `to - from ∈ [5, 100]` + +#### Returns + +- array: list of the blocks, the object in the list is a [Block](#s-block), but **without** transaction details + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockList", + "params": [1, 11] +} +``` + +Response: [Block](#s-block) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { TODO: block object } + ] +} +``` + +### bp_getBlockListByTimeRange + +TODO: as a new API in the next release + +### bp_getBlockByHeight + +Returns information about the block specified by its height. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | height of the block | 1024 | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHeight", + "params": [1, true] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getBlockByHash + +Returns information about the block specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------- | ------ | +| 0 | hash | string | hash of the block | "TODO" | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHash", + "params": ["TODO", true] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getTransactionList + +Returns a list of the transactions. Traverse page by page by using a transaction hash as the mark for paging. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | --------- | ------- | ------------------------------------------- | ---------- | +| 0 | since | string | hash as the start point of traverse | "TODO" | +| 1 | direction | string | traverse direction, "backward" or "forward" | "backward" | +| 2 | size | integer | page size, [5, 100] | 20 | + + QhcAe42Xf8cwGUf5NYGQDQ + XNZ9yipFBUV5ySBtreW1MA ↑ forward (in newer blocks) + 9fXd3s5HE5fC8lOYY6uAZA + KhytGjS0xjw5CJvcJYpsNg ← since (paging mark) + 2KOxrKMS4iVDKXnm6HuYiA + 71VwqOMOvAsBXJRMeBruWg ↓ backward (in older blocks) + 0P3k04RKHw8SEMKHxADC8A + + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionList", + "params": ["KhytGjS0xjw5CJvcJYpsNg", "forward", 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { TODO: transaction object } + ] +} +``` + +### bp_getTransactionListInBlock + +Returns a list of the transactions from a block by the specified height. + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | --------------------- | ------ | +| 0 | height | integer | block height | 1024 | +| 1 | from | integer | start index, included | 0 | +| 2 | to | integer | end index, excluded | 10 | + +**Constraints:** `to - from ∈ [5, 100]` + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionListInBlock", + "params": [1024, 0, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { TODO: transaction object } + ] +} +``` + +### bp_getTransactionByHash + +Returns information about the transaction specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------------- | ------ | +| 0 | hash | string | hash of the transaction | "TODO" | + +#### Returns + +- object: transaction information object, it's a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionByHash", + "params": ["TODO", true] +} +``` + +Response: [Transaction](#s-transaction) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: transaction object + } +} +``` + +## Structure Reference + +Here are some common structure definitions used in the API. + + + +### Block + +The block generated in the CovenantSQL blockchain network. + +| Field | Type | Description | +| ----------- | ------- | -------------------------------------------- | +| height | integer | Height of the block | +| hash | string | Hash of the block | +| version | integer | Version number of the block | +| producer | string | Address of the node who generated this block | +| merkle_root | string | Hash of the merkle tree | +| parent | string | Hash of its parent block | +| timestamp | string | Create time of the block | +| signee | string | Public key of the node who signed this block | +| signature | string | Signature for the this block | +| tx_count | integer | Count of the transactions in this block | + +Sample in JSON format: + +```json +{ + "height": 12, + "hash": "TODO", + "version": 1, + "producer": "4io8u9v9nydaQPXtmqibg8gJbkNFd7DdM47PLWuM7ubzBXZ4At7", + "merkle_root": "TODO", + "parent": "TODO", + "timestamp": "TODO", + "signee": "TODO", + "signature": "TODO", + "tx_count": 1 +} +``` + + + +### Transaction + +| Field | Type | Description | +| ------------ | ------- | ------------------------------------------------------------------------------------------- | +| block_height | integer | Height of the block this transaction belongs to | +| index | integer | Index of the transaction in the block | +| hash | string | Hash of the transaction data | +| block_hash | string | Hash of the block this transaction belongs to | +| type | integer | Type of the transaction | +| signee | string | Public key of the account who signed this transaction | +| address | string | Account address who signed this transaction | +| signature | string | Signature of this transaction | +| timestamp | string | Create time of the transaction | +| raw | string | Raw content of the transaction data, in JSON format | +| tx | object | Concrete transaction object, see supported [transaction types](#transaction-types) for more | + +Sample in JSON format: + +```json +{ + "block_height": 1, + "index": 0, + "hash": "TODO", + "block_hash": "TODO", + "timestamp": "TODO", + "type": 1, + "signee": "TODO", + "address": "TODO", + "signature": "TODO", + "raw": "TODO", + "tx": { + "field": "TODO" + } +} +``` + +**Supported Transaction Types:** + +- [CreateDatabase](#s-transaction-createdatabase) + +TODO: more types + + + +### Transaction: CreateDatabase + +TODO: more types \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/api.md b/website/translated_docs/zh-CN/version-0.0.6/api.md new file mode 100644 index 0000000..5e4a668 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/api.md @@ -0,0 +1,6 @@ +--- +id: version-0.0.6-api +title: CovenantSQL API +original_id: api +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/bck/api-json-rpc.md b/website/translated_docs/zh-CN/version-0.0.6/bck/api-json-rpc.md new file mode 100644 index 0000000..7ec30aa --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/bck/api-json-rpc.md @@ -0,0 +1,440 @@ +--- +id: version-0.0.6-api-json-rpc +title: JSON RPC +original_id: api-json-rpc +--- +> JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. + +CovenantSQL provides a suite of RPC methods in [JSON-RPC 2.0](https://www.jsonrpc.org/specification) for easily accessing to CovenantSQL networks. + +## Javascript API + +[cql.js](https://github.com/covenantsql/cql.js) is a Javascript SDK which has encapsulated the RPC methods in order to give a much more convenient way to talk to the CovenantSQL networks. See the [Javascript API](cql-js.md) for more. + +## JSON RPC Endpoint + +| Network | Provider | URL | +| ------------------------ | ------------- | -------------------------------------- | +| CovenantSQL Test Network | Covenant Labs | https://jsonrpc.testnet.covenantsql.io | +| CovenantSQL Main Network | Covenant Labs | Comming soon :) | + +## JSON RPC API Reference + +### bp_getProtocolVersion + +Returns the current CovenantSQL protocol version. + +#### Parameters + +None. + +#### Returns + +- string - the current CovenantSQL protocol version + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "method": "bp_getProtocolVersion", + "params": [], + "id": 1 +} +``` + +Response: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0.1.0" +} +``` + +### bp_getRunningStatus + +Returns some basic indicators describing the running status of the CovenantSQL network. + +#### Parameters + +None. + +#### Returns + +- object: an object describes the running status of the network. + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getRunningStatus", + "params": [] +} +``` + +Response: + +```js +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "block_height": 182414, // height of the latest block + "count_accounts": 103, // count of the accounts ever created + "count_databases": 912414, // count of the databases ever created + "qps": 10241 // estimated QPS of database operations of the whole net + } +} +``` + +### bp_getBlockList + +Returns a list of the blocks. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------- | ---------------------- | ------ | +| 0 | from | integer | start height, included | 1 | +| 1 | to | integer | end height, excluded | 11 | + +**Constraints:** `to - from ∈ [5, 100]` + +#### Returns + +- array: list of the blocks, the object in the list is a [Block](#s-block), but **without** transaction details + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockList", + "params": [1, 11] +} +``` + +Response: [Block](#s-block) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { TODO: block object } + ] +} +``` + +### bp_getBlockListByTimeRange + +TODO: as a new API in the next release + +### bp_getBlockByHeight + +Returns information about the block specified by its height. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | height of the block | 1024 | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHeight", + "params": [1, true] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getBlockByHash + +Returns information about the block specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------- | ------ | +| 0 | hash | string | hash of the block | "TODO" | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHash", + "params": ["TODO", true] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getTransactionList + +Returns a list of the transactions. Traverse page by page by using a transaction hash as the mark for paging. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | --------- | ------- | ------------------------------------------- | ---------- | +| 0 | since | string | hash as the start point of traverse | "TODO" | +| 1 | direction | string | traverse direction, "backward" or "forward" | "backward" | +| 2 | size | integer | page size, [5, 100] | 20 | + + QhcAe42Xf8cwGUf5NYGQDQ + XNZ9yipFBUV5ySBtreW1MA ↑ forward (in newer blocks) + 9fXd3s5HE5fC8lOYY6uAZA + KhytGjS0xjw5CJvcJYpsNg ← since (paging mark) + 2KOxrKMS4iVDKXnm6HuYiA + 71VwqOMOvAsBXJRMeBruWg ↓ backward (in older blocks) + 0P3k04RKHw8SEMKHxADC8A + + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionList", + "params": ["KhytGjS0xjw5CJvcJYpsNg", "forward", 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { TODO: transaction object } + ] +} +``` + +### bp_getTransactionListInBlock + +Returns a list of the transactions from a block by the specified height. + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | --------------------- | ------ | +| 0 | height | integer | block height | 1024 | +| 1 | from | integer | start index, included | 0 | +| 2 | to | integer | end index, excluded | 10 | + +**Constraints:** `to - from ∈ [5, 100]` + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionListInBlock", + "params": [1024, 0, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { TODO: transaction object } + ] +} +``` + +### bp_getTransactionByHash + +Returns information about the transaction specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------------- | ------ | +| 0 | hash | string | hash of the transaction | "TODO" | + +#### Returns + +- object: transaction information object, it's a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionByHash", + "params": ["TODO", true] +} +``` + +Response: [Transaction](#s-transaction) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: transaction object + } +} +``` + +## Structure Reference + +Here are some common structure definitions used in the API. + + + +### Block + +The block generated in the CovenantSQL blockchain network. + +| Field | Type | Description | +| ----------- | ------- | -------------------------------------------- | +| height | integer | Height of the block | +| hash | string | Hash of the block | +| version | integer | Version number of the block | +| producer | string | Address of the node who generated this block | +| merkle_root | string | Hash of the merkle tree | +| parent | string | Hash of its parent block | +| timestamp | string | Create time of the block | +| signee | string | Public key of the node who signed this block | +| signature | string | Signature for the this block | +| tx_count | integer | Count of the transactions in this block | + +Sample in JSON format: + +```json +{ + "height": 12, + "hash": "TODO", + "version": 1, + "producer": "4io8u9v9nydaQPXtmqibg8gJbkNFd7DdM47PLWuM7ubzBXZ4At7", + "merkle_root": "TODO", + "parent": "TODO", + "timestamp": "TODO", + "signee": "TODO", + "signature": "TODO", + "tx_count": 1 +} +``` + + + +### Transaction + +| Field | Type | Description | +| ------------ | ------- | ------------------------------------------------------------------------------------------- | +| block_height | integer | Height of the block this transaction belongs to | +| index | integer | Index of the transaction in the block | +| hash | string | Hash of the transaction data | +| block_hash | string | Hash of the block this transaction belongs to | +| type | integer | Type of the transaction | +| signee | string | Public key of the account who signed this transaction | +| address | string | Account address who signed this transaction | +| signature | string | Signature of this transaction | +| timestamp | string | Create time of the transaction | +| raw | string | Raw content of the transaction data, in JSON format | +| tx | object | Concrete transaction object, see supported [transaction types](#transaction-types) for more | + +Sample in JSON format: + +```json +{ + "block_height": 1, + "index": 0, + "hash": "TODO", + "block_hash": "TODO", + "timestamp": "TODO", + "type": 1, + "signee": "TODO", + "address": "TODO", + "signature": "TODO", + "raw": "TODO", + "tx": { + "field": "TODO" + } +} +``` + +**Supported Transaction Types:** + +- [CreateDatabase](#s-transaction-createdatabase) + +TODO: more types + + + +### Transaction: CreateDatabase + +TODO: more types \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/bck/development-cmd-cql-utils-zh.md b/website/translated_docs/zh-CN/version-0.0.6/bck/development-cmd-cql-utils-zh.md new file mode 100644 index 0000000..1bbea8e --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/bck/development-cmd-cql-utils-zh.md @@ -0,0 +1,41 @@ +--- +id: version-0.0.6-keygen +title: 使用 cql-utils 生成密钥与钱包 +original_id: keygen +--- +`cql-utils` 是 CovenantSQL 的一个命令行工具，具体用法如下。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 使用 + +### 生成公私钥对 + + $ cql-utils -tool keygen + Enter master key(press Enter for default: ""): + ⏎ + Private key file: private.key + Public key's hex: 03bc9e90e3301a2f5ae52bfa1f9e033cde81b6b6e7188b11831562bf5847bff4c0 + + +生成的 private.key 文件即是使用主密码加密过的私钥文件，而输出到屏幕上的字符串就是使用十六进制进行编码的公钥。 + +### 使用私钥文件或公钥生成钱包地址 + + $ cql-utils -tool addrgen -private private.key + Enter master key(default: ""): + ⏎ + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + $ cql-utils -tool addrgen -public 02f2707c1c6955a9019cd9d02ade37b931fbfa286a1163dfc1de965ec01a5c4ff8 + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + + +你可以通过指定私钥文件，或者把上述的公钥十六进制编码字符串作为命令行参数来直接生成钱包地址。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/bck/development-cmd-cql-zh.md b/website/translated_docs/zh-CN/version-0.0.6/bck/development-cmd-cql-zh.md new file mode 100644 index 0000000..3bde205 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/bck/development-cmd-cql-zh.md @@ -0,0 +1,77 @@ +--- +id: version-0.0.6-cql +title: 使用命令行客户端 cql 创建数据库 +original_id: cql +--- +本文档主要介绍 CovenantSQL 命令行客户端 `cql` 的使用。`cql` 是一个用于批量进行 SQLChain 上数据库的创建、查询、更新或删除操作的命令行工具。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 生成默认配置文件 + +首先需要一个 config 文件和由你输入的主密码（master key）来初始化，其中主密码用来加密解密本地密钥对。使用 `cql-utils` 工具进行配置文件生成后，你可以在生成的配置文件目录下找到密钥文件。 + +具体请参考: [cql-utils 使用文档](https://github.com/CovenantSQL/docs/tree/master/development-cmd-utils-zh.md#使用) 中配置文件及钱包地址生成相关章节。 + +## 检查钱包余额 + +使用 `cql` 命令来检查钱包余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] +### Public Key ### +0388954cf083bb6bb2b9c7248849b57c76326296fcc0d69764fc61eedb5b8d820c +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +这里我们得到结果 **"stable coin balance is: 100"**。 + +## 初始化一个 CovenantSQL 数据库 + +准备好配置文件和主密码后就可以使用 `cql` 命令来创建数据库了，你的数据库 ID 将会输出到屏幕上： + +```bash +# if a non-default password applied on master key, use `-password` to pass it +$ cql -config conf/config.yaml -create 1 +INFO[0000] +### Public Key ### +039bc931161383c994ab9b81e95ddc1494b0efeb1cb735bb91e1043a1d6b98ebfd +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] the newly created database is: covenantsql://0e9103318821b027f35b96c4fd5562683543276b72c488966d616bfe0fe4d213 caller="main.go:297 main.main" +``` + +这里 `-create 1` 表示创建一个单节点的 SQLChain。 + +```bash +$ cql -config conf/config.yaml -dsn covenantsql://address +``` + +`address` 就是你的数据库 ID。 + +`cql` 命令的详细使用帮助如下： + +```bash +$ cql -help +``` + +## 使用 `cql` + +现在可以使用 `cql` 进行数据库操作了: + +```bash +co:address=> show tables; +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/bck/development-golang-client-zh.md b/website/translated_docs/zh-CN/version-0.0.6/bck/development-golang-client-zh.md new file mode 100644 index 0000000..0089def --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/bck/development-golang-client-zh.md @@ -0,0 +1,108 @@ +--- +id: version-0.0.6-golang-client +title: 使用 Golang 驱动访问数据库 +original_id: golang-client +--- +本文档介绍 CovenantSQL 客户端的使用方式。客户端用来创建、查询、更新和删除 SQLChain 以及绑定的数据库。 + +## 开始之前 + +确保 `$GOPATH/bin` 目录在环境变量 `$PATH` 中，执行以下命令 + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +然后在你的 go 代码中 import 第一个 `client` 包。 + +## 初始化一个 CovenantSQL 客户端 + +首先需要一个 config 文件和 master key 来初始化。master key 用来加密解密本地密钥对。以下是如何用一个自定义 master key 来生成默认的 config 文件： + +### 生成默认的配置文件 + +运行以下 `cql-utils` 命令，输入 master key（类似密码）来生成本地密钥对。等待几十秒，会在 `conf` 文件夹中，生成一个私钥文件和一个名为 `config.yaml` 的配置文件。 + +```bash +$ cql-utils -tool confgen -root conf +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: conf/private.key +Public key's hex: 025abec9b0072615170f4acf4a2fa1162a13864bb66bc3f140b29f6bf50ceafc75 +Generated key pair. +Generating nonce... +INFO[0005] cpu: 1 +INFO[0005] position: 0, shift: 0x0, i: 0 +nonce: {{1450338416 0 0 0} 26 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514} +node id: 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514 +Generated nonce. +Generating config file... +Generated nonce. +``` + +有了配置文件之后，可以通过以下 go 代码来初始化 CovenantSQL 客户端： + +```go +client.Init(configFile, masterKey) +``` + +## 客户端使用方式 + +### 创建一个 SQLChain 数据库 + +创建 SQLChain 数据库需要指明需要几个节点（nodeCount变量）: + +```go +var ( + dsn string + meta client.ResourceMeta +) +meta.Node = uint16(nodeCount) +dsn, err = client.Create(meta) +// process err +``` + +创建完毕会返回一个 dsn 字符串，用来访问这个数据库。 + +### 查询和执行 + +拿到 dsn 字符串后，可以通过以下代码在 SQLChain 中执行 SQL 语句： + +```go +
db, err := sql.Open("covenantsql", dsn) + // process err + + _, err = db.Exec("CREATE TABLE testSimple ( column int );") + // process err + + _, err = db.Exec("INSERT INTO testSimple VALUES(?);", 42) + // process err + + row := db.QueryRow("SELECT column FROM testSimple LIMIT 1;") + + var result int + err = row.Scan(&result) + // process err + fmt.Printf("SELECT column FROM testSimple LIMIT 1; result %d\n", result) + + err = db.Close() + // process err + +``` + +用法和其他 go sql driver 一致。 + +### 删除数据库 + +使用 dsn 来删除数据库： + +```go + err = client.Drop(dsn) + // process err +``` + +### 完整示例 + +在以下目录中有一个简单示例和复杂示例可以参考 [示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/bck/getting-started-overview-zh.md b/website/translated_docs/zh-CN/version-0.0.6/bck/getting-started-overview-zh.md new file mode 100644 index 0000000..174cc0d --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/bck/getting-started-overview-zh.md @@ -0,0 +1,63 @@ +--- +id: version-0.0.6-intro +title: 简介 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +- **SQL**: 支持 SQL-92 标准 +- **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +- **隐私**: 通过加密和授权许可进行访问 +- **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信[在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +#### 一行代码接入区块链数据 + +```go +sql.Open("CovenantSQL", dbURI) +``` + +# # + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +- 第一层: **全局共识层**(主链，架构图中的中间环): + - 整个网络中只有一个主链。 + - 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +- 第二层: **SQL 共识层**(子链，架构图中的两边环): + - 每个数据库都有自己独立的子链。 + - 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +- 第三层: **数据储存层**(支持 SQL-92 的数据库引擎): + - 每个数据库都有自己独立的分布式引擎。 + - 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/bck/getting-started-testnet-zh.md b/website/translated_docs/zh-CN/version-0.0.6/bck/getting-started-testnet-zh.md new file mode 100644 index 0000000..c3a90f9 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/bck/getting-started-testnet-zh.md @@ -0,0 +1,93 @@ +--- +id: version-0.0.6-testnet +title: CovenantSQL 测试网快速入门 +original_id: testnet +--- +[CovenantSQL](https://github.com/CovenantSQL/CovenantSQL/blob/develop/README-zh.md) 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +1. **SQL**: 支持 SQL-92 标准 +2. **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +3. **隐私**: 通过加密和授权许可进行访问 +4. **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## 0. 下载 CovenantSQL 工具 + +在 [github](https://github.com/CovenantSQL/CovenantSQL/releases) 下载最新的发行版 + +## 1. 用 `cql-utils` 生成配置文件访问测试网 + +```bash +$ cql-utils -tool confgen +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: conf/private.key +Public key's hex: 02296ea73240dcd69d2b3f1fb754c8debdf68c62147488abb10165428667ec8cbd +Generated key pair. +Generating nonce... +nonce: {{731613648 0 0 0} 11 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9} +node id: 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9 +Generated nonce. +Generating config file... +Generated nonce. +``` + +运行完成后，`cql-utils`会在 `./conf` 目录生成一个配置文件。 + +## 2. 用私钥生成钱包地址 + +私钥可以再上一步的 `./conf` 目录中找到，文件名为 `private.key` + +```bash +$ cql-utils -tool addrgen -private ./conf/private.key +Enter master key(default: ""): +⏎ +wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 +``` + +上述 `4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9` 就是钱包地址 + +## 3. 在水龙头(Faucet)获取 Particle(PTC) + +水龙头(Faucet)的地址为: [CovenantSQL 测试网 Particle(PTC) 水龙头](https://testnet.covenantsql.io/)。 + +完成教程之后，用 `cql` 命令来检查钱包地址的余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +当看到 **"stable coin balance is: 100"** 时，表明余额已经为 100。 + +如果您需要更多的 PTC 作为长期测试使用，请联系 。 + +对于有合作的商业伙伴，我们将直接提供 PTC 以供使用。 + +## 4. 使用 `CLI` 创建数据库 + +```bash +$ cql -config conf/config.yaml -create 1 +INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" +``` + +第一行命令中的 `1` 表示申请几个矿工为你的数据库服务。`covenantsql://...` 开头的这个字符串就是创建的数据库访问地址，在 SDK 和 CLI 命令中都需要用此地址，在整个区块链中找到这个数据库。 + +## 5. CLI 和 SDK 的详细文档 + +创建好数据库后，您可以参考以下文档和示例，以便更快的使用CovenantSQL来开发应用。 + +- [CLI 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql/README-zh.md) +- [SDK 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/README-zh.md) +- [SDK 示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) + +## 6. SQLChain 浏览器 + +目前，测试网的数据库时不需要权限的。意味着您可以通过数据库的DSN(数据库访问地址)，在[SQLChain 浏览器](https://explorer.dbhub.org)中拿到所有的修改历史和区块信息。 + +更多的测试网技术支持，请访问: + +> [TestNet 发行日志](https://github.com/CovenantSQL/CovenantSQL/wiki/Release-Notes-zh) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/bck/getting-started-zh.md b/website/translated_docs/zh-CN/version-0.0.6/bck/getting-started-zh.md new file mode 100644 index 0000000..a7c7ce9 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/bck/getting-started-zh.md @@ -0,0 +1,486 @@ +--- +id: version-0.0.6-local-deployment +title: CovenantSQL 综述 +original_id: local-deployment +--- +# CovenantSQL 介绍 + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可变成 ĐApp +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是用户的钱包，那么 CovenantSQL 就是是用户的去中心化数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密 保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 + +# 安装 CovenantSQL 客户端 + +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +* [Go](./development-golang-client-zh.md) +* [Java](https://github.com/CovenantSQL/covenant-connector) +* [Python](https://github.com/CovenantSQL/python-driver) +* [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +* `conf/private.key`: 为您生成的私钥通过主密码加密保存在该文件中，您的账号地址需要使用该文件创建； +* `conf/config.yaml`: 为您生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +* [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 + +# 部署 CovenantSQL + +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 启动 Docker 容器 + +执行以下的命令在本地运行 CovenantSQL + +```shell +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +make docker +make start +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行`export COVENANTSQL_ROOT=$PWD`存为环境变量 + +### 检查运行状态 + +```shell +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_adapter ./docker-entry.sh Up 0.0.0.0:11105->4661/tcp +covenantsql_bp_0 ./docker-entry.sh Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 ./docker-entry.sh Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 ./docker-entry.sh Up 0.0.0.0:11101->4661/tcp +covenantsql_explorer /bin/sh -c MAGIC_DOLLAR='$ ... Up 0.0.0.0:11108->80/tcp +covenantsql_miner_0 ./docker-entry.sh Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 ./docker-entry.sh Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 ./docker-entry.sh Up 0.0.0.0:11104->4661/tcp +covenantsql_mysql_adapter ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11106->4663/tcp +``` + +### SQLChain Explorer + +我们在`:11108`端口提供了一个 SQLChain 的 Explorer 可以看到 SQL 语句在链上的情况 + +# 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +cql -config config/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +cql -config config/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +cql -config config/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +# 使用 CovenantSQL 开发 App + +## Golang 使用 CovenantSQL + +#### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +#### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +#### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +#### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +#### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` + +# CovenantSQL API + +# 常见问题解答 + +补充 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/bck/guide-zh.md b/website/translated_docs/zh-CN/version-0.0.6/bck/guide-zh.md new file mode 100644 index 0000000..6c441ac --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/bck/guide-zh.md @@ -0,0 +1,114 @@ +--- +id: version-0.0.6-guide-zh +title: 快速开始 +original_id: guide-zh +--- +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +- [Go](./development-golang-client-zh.md) +- [Java](https://github.com/CovenantSQL/covenant-connector) +- [Python](https://github.com/CovenantSQL/python-driver) +- [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +- `conf/private.key`: 为您生成的私钥通过主密码加密保存在该文件中，您的账号地址需要使用该文件创建； +- `conf/config.yaml`: 为您生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +- [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/deployment.md b/website/translated_docs/zh-CN/version-0.0.6/deployment.md new file mode 100644 index 0000000..ff3376a --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/deployment.md @@ -0,0 +1,126 @@ +--- +id: version-0.0.6-deployment +title: 部署 CovenantSQL 私有链 +original_id: deployment +--- +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 启动 Docker 容器 + +执行以下的命令在本地运行 CovenantSQL + +```shell +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +make docker +make start +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行`export COVENANTSQL_ROOT=$PWD`存为环境变量 + +### 检查运行状态 + +```shell +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_adapter ./docker-entry.sh Up 0.0.0.0:11105->4661/tcp +covenantsql_bp_0 ./docker-entry.sh Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 ./docker-entry.sh Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 ./docker-entry.sh Up 0.0.0.0:11101->4661/tcp +covenantsql_explorer /bin/sh -c MAGIC_DOLLAR='$ ... Up 0.0.0.0:11108->80/tcp +covenantsql_miner_0 ./docker-entry.sh Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 ./docker-entry.sh Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 ./docker-entry.sh Up 0.0.0.0:11104->4661/tcp +covenantsql_mysql_adapter ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11106->4663/tcp +``` + +### SQLChain Explorer + +我们在`:11108`端口提供了一个 SQLChain 的 Explorer 可以看到 SQL 语句在链上的情况 + +# 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +cql -config config/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +cql -config config/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +cql -config config/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/development-cmd-cql-utils-zh.md b/website/translated_docs/zh-CN/version-0.0.6/development-cmd-cql-utils-zh.md new file mode 100644 index 0000000..1bbea8e --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/development-cmd-cql-utils-zh.md @@ -0,0 +1,41 @@ +--- +id: version-0.0.6-keygen +title: 使用 cql-utils 生成密钥与钱包 +original_id: keygen +--- +`cql-utils` 是 CovenantSQL 的一个命令行工具，具体用法如下。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 使用 + +### 生成公私钥对 + + $ cql-utils -tool keygen + Enter master key(press Enter for default: ""): + ⏎ + Private key file: private.key + Public key's hex: 03bc9e90e3301a2f5ae52bfa1f9e033cde81b6b6e7188b11831562bf5847bff4c0 + + +生成的 private.key 文件即是使用主密码加密过的私钥文件，而输出到屏幕上的字符串就是使用十六进制进行编码的公钥。 + +### 使用私钥文件或公钥生成钱包地址 + + $ cql-utils -tool addrgen -private private.key + Enter master key(default: ""): + ⏎ + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + $ cql-utils -tool addrgen -public 02f2707c1c6955a9019cd9d02ade37b931fbfa286a1163dfc1de965ec01a5c4ff8 + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + + +你可以通过指定私钥文件，或者把上述的公钥十六进制编码字符串作为命令行参数来直接生成钱包地址。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/development-cmd-cql-zh.md b/website/translated_docs/zh-CN/version-0.0.6/development-cmd-cql-zh.md new file mode 100644 index 0000000..3bde205 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/development-cmd-cql-zh.md @@ -0,0 +1,77 @@ +--- +id: version-0.0.6-cql +title: 使用命令行客户端 cql 创建数据库 +original_id: cql +--- +本文档主要介绍 CovenantSQL 命令行客户端 `cql` 的使用。`cql` 是一个用于批量进行 SQLChain 上数据库的创建、查询、更新或删除操作的命令行工具。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 生成默认配置文件 + +首先需要一个 config 文件和由你输入的主密码（master key）来初始化，其中主密码用来加密解密本地密钥对。使用 `cql-utils` 工具进行配置文件生成后，你可以在生成的配置文件目录下找到密钥文件。 + +具体请参考: [cql-utils 使用文档](https://github.com/CovenantSQL/docs/tree/master/development-cmd-utils-zh.md#使用) 中配置文件及钱包地址生成相关章节。 + +## 检查钱包余额 + +使用 `cql` 命令来检查钱包余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] +### Public Key ### +0388954cf083bb6bb2b9c7248849b57c76326296fcc0d69764fc61eedb5b8d820c +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +这里我们得到结果 **"stable coin balance is: 100"**。 + +## 初始化一个 CovenantSQL 数据库 + +准备好配置文件和主密码后就可以使用 `cql` 命令来创建数据库了，你的数据库 ID 将会输出到屏幕上： + +```bash +# if a non-default password applied on master key, use `-password` to pass it +$ cql -config conf/config.yaml -create 1 +INFO[0000] +### Public Key ### +039bc931161383c994ab9b81e95ddc1494b0efeb1cb735bb91e1043a1d6b98ebfd +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] the newly created database is: covenantsql://0e9103318821b027f35b96c4fd5562683543276b72c488966d616bfe0fe4d213 caller="main.go:297 main.main" +``` + +这里 `-create 1` 表示创建一个单节点的 SQLChain。 + +```bash +$ cql -config conf/config.yaml -dsn covenantsql://address +``` + +`address` 就是你的数据库 ID。 + +`cql` 命令的详细使用帮助如下： + +```bash +$ cql -help +``` + +## 使用 `cql` + +现在可以使用 `cql` 进行数据库操作了: + +```bash +co:address=> show tables; +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/development-golang-client-zh.md b/website/translated_docs/zh-CN/version-0.0.6/development-golang-client-zh.md new file mode 100644 index 0000000..0089def --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/development-golang-client-zh.md @@ -0,0 +1,108 @@ +--- +id: version-0.0.6-golang-client +title: 使用 Golang 驱动访问数据库 +original_id: golang-client +--- +本文档介绍 CovenantSQL 客户端的使用方式。客户端用来创建、查询、更新和删除 SQLChain 以及绑定的数据库。 + +## 开始之前 + +确保 `$GOPATH/bin` 目录在环境变量 `$PATH` 中，执行以下命令 + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +然后在你的 go 代码中 import 第一个 `client` 包。 + +## 初始化一个 CovenantSQL 客户端 + +首先需要一个 config 文件和 master key 来初始化。master key 用来加密解密本地密钥对。以下是如何用一个自定义 master key 来生成默认的 config 文件： + +### 生成默认的配置文件 + +运行以下 `cql-utils` 命令，输入 master key（类似密码）来生成本地密钥对。等待几十秒，会在 `conf` 文件夹中，生成一个私钥文件和一个名为 `config.yaml` 的配置文件。 + +```bash +$ cql-utils -tool confgen -root conf +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: conf/private.key +Public key's hex: 025abec9b0072615170f4acf4a2fa1162a13864bb66bc3f140b29f6bf50ceafc75 +Generated key pair. +Generating nonce... +INFO[0005] cpu: 1 +INFO[0005] position: 0, shift: 0x0, i: 0 +nonce: {{1450338416 0 0 0} 26 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514} +node id: 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514 +Generated nonce. +Generating config file... +Generated nonce. +``` + +有了配置文件之后，可以通过以下 go 代码来初始化 CovenantSQL 客户端： + +```go +client.Init(configFile, masterKey) +``` + +## 客户端使用方式 + +### 创建一个 SQLChain 数据库 + +创建 SQLChain 数据库需要指明需要几个节点（nodeCount变量）: + +```go +var ( + dsn string + meta client.ResourceMeta +) +meta.Node = uint16(nodeCount) +dsn, err = client.Create(meta) +// process err +``` + +创建完毕会返回一个 dsn 字符串，用来访问这个数据库。 + +### 查询和执行 + +拿到 dsn 字符串后，可以通过以下代码在 SQLChain 中执行 SQL 语句： + +```go +
db, err := sql.Open("covenantsql", dsn) + // process err + + _, err = db.Exec("CREATE TABLE testSimple ( column int );") + // process err + + _, err = db.Exec("INSERT INTO testSimple VALUES(?);", 42) + // process err + + row := db.QueryRow("SELECT column FROM testSimple LIMIT 1;") + + var result int + err = row.Scan(&result) + // process err + fmt.Printf("SELECT column FROM testSimple LIMIT 1; result %d\n", result) + + err = db.Close() + // process err + +``` + +用法和其他 go sql driver 一致。 + +### 删除数据库 + +使用 dsn 来删除数据库： + +```go + err = client.Drop(dsn) + // process err +``` + +### 完整示例 + +在以下目录中有一个简单示例和复杂示例可以参考 [示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/development.md b/website/translated_docs/zh-CN/version-0.0.6/development.md new file mode 100644 index 0000000..4c162b3 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/development.md @@ -0,0 +1,173 @@ +--- +id: version-0.0.6-development +title: 使用 CovenantSQL 开发 App +original_id: development +--- +## Golang 使用 CovenantSQL + +### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/getting-started-overview-zh.md b/website/translated_docs/zh-CN/version-0.0.6/getting-started-overview-zh.md new file mode 100644 index 0000000..c170277 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/getting-started-overview-zh.md @@ -0,0 +1,122 @@ +--- +id: version-0.0.6-intro +title: 简介 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +- **SQL**: 支持 SQL-92 标准 +- **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +- **隐私**: 通过加密和授权许可进行访问 +- **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信[在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +#### 一行代码接入区块链数据 + +```go +sql.Open("CovenantSQL", dbURI) +``` + +# # + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +- 第一层: **全局共识层**(主链，架构图中的中间环): + - 整个网络中只有一个主链。 + - 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +- 第二层: **SQL 共识层**(子链，架构图中的两边环): + - 每个数据库都有自己独立的子链。 + - 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +- 第三层: **数据储存层**(支持 SQL-92 的数据库引擎): + - 每个数据库都有自己独立的分布式引擎。 + - 主要负责：数据库存储和加密；查询处理和签名；高效索引。 + +## 文章 + +团队成员发表过的论文 + +- [迅雷水晶：一种新颖的基于众筹的内容分发平台](https://dl.acm.org/citation.cfm?id=2736085) +- [基于众筹的视频服务系统性能分析](https://ieeexplore.ieee.org/abstract/document/7114727/) +- [迅雷水晶性能分析：基于众筹的视频分发平台](https://ieeexplore.ieee.org/abstract/document/7762143/) + +这些启发了我们： + +- [比特币：P2P电子现金系统](https://bitcoin.org/bitcoin.pdf) +- [S/Kademlia](https://github.com/thunderdb/research/wiki/Secure-Kademlia) + - [S/Kademlia: 一种针对密钥的实用方法](https://ieeexplore.ieee.org/document/4447808/) +- [vSQL: 验证动态外包数据库上的任意SQL查询](https://ieeexplore.ieee.org/abstract/document/7958614/) + +## Libs + +### 网络栈 + +[DH-RPC](rpc/) := TLS - Cert + DHT + +| 层 | 应用 | +|:------ |:------------------------------------------------------------------------------------------------------------:| +| 远程调用协议 | `net/rpc` | +| 寻址 | [**C**onsistent **S**ecure **DHT**](https://godoc.org/github.com/CovenantSQL/CovenantSQL/consistent) | +| 会话池 | Session Pool | +| 多路复用 | [smux](https://github.com/xtaci/smux) | +| 传输安全 | [**E**nhanced **TLS**](https://github.com/CovenantSQL/research/wiki/ETLS(Enhanced-Transport-Layer-Security)) | +| 网络 | TCP or KCP for optional later | + +#### 测试工具 + +- [全球网络拓扑模拟器(GNTE)](https://github.com/CovenantSQL/GNTE) 用于网络模拟 +- [线性一致性测试](https://github.com/anishathalye/porcupine) + +#### 接口 + +CovenantSQL仍在建设中，测试网已经发布，[尝试一下](https://testnet.covenantsql.io/). + +- [Golang](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) +- [Java](https://github.com/CovenantSQL/covenant-connector/) +- [NodeJS](https://github.com/CovenantSQL/node-covenantsql/) +- [Python](https://github.com/CovenantSQL/python-driver/) +- Coding for more…… + +关注我们或[![follow on Twitter](https://img.shields.io/twitter/url/https/twitter.com/fold_left.svg?style=social&label=Follow%20%40CovenantLabs)](https://twitter.com/intent/follow?screen_name=CovenantLabs) 保持更新 + +## 测试网 + +- [快捷入口](https://testnet.covenantsql.io/quickstart) +- [测试网水龙头](https://testnet.covenantsql.io/) + +## 联系我们 + +- [邮箱地址](mailto:webmaster@covenantsql.io) +- [ ![follow on Twitter](https://img.shields.io/twitter/url/https/twitter.com/fold_left.svg?style=social&label=Follow%20%40CovenantLabs)](https://twitter.com/intent/follow?screen_name=CovenantLabs) + +- [![Join the chat at https://gitter.im/CovenantSQL/CovenantSQL](https://badges.gitter.im/CovenantSQL/CovenantSQL.svg)](https://gitter.im/CovenantSQL/CovenantSQL?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/getting-started-testnet-zh.md b/website/translated_docs/zh-CN/version-0.0.6/getting-started-testnet-zh.md new file mode 100644 index 0000000..c3a90f9 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/getting-started-testnet-zh.md @@ -0,0 +1,93 @@ +--- +id: version-0.0.6-testnet +title: CovenantSQL 测试网快速入门 +original_id: testnet +--- +[CovenantSQL](https://github.com/CovenantSQL/CovenantSQL/blob/develop/README-zh.md) 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +1. **SQL**: 支持 SQL-92 标准 +2. **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +3. **隐私**: 通过加密和授权许可进行访问 +4. **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## 0. 下载 CovenantSQL 工具 + +在 [github](https://github.com/CovenantSQL/CovenantSQL/releases) 下载最新的发行版 + +## 1. 用 `cql-utils` 生成配置文件访问测试网 + +```bash +$ cql-utils -tool confgen +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: conf/private.key +Public key's hex: 02296ea73240dcd69d2b3f1fb754c8debdf68c62147488abb10165428667ec8cbd +Generated key pair. +Generating nonce... +nonce: {{731613648 0 0 0} 11 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9} +node id: 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9 +Generated nonce. +Generating config file... +Generated nonce. +``` + +运行完成后，`cql-utils`会在 `./conf` 目录生成一个配置文件。 + +## 2. 用私钥生成钱包地址 + +私钥可以再上一步的 `./conf` 目录中找到，文件名为 `private.key` + +```bash +$ cql-utils -tool addrgen -private ./conf/private.key +Enter master key(default: ""): +⏎ +wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 +``` + +上述 `4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9` 就是钱包地址 + +## 3. 在水龙头(Faucet)获取 Particle(PTC) + +水龙头(Faucet)的地址为: [CovenantSQL 测试网 Particle(PTC) 水龙头](https://testnet.covenantsql.io/)。 + +完成教程之后，用 `cql` 命令来检查钱包地址的余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +当看到 **"stable coin balance is: 100"** 时，表明余额已经为 100。 + +如果您需要更多的 PTC 作为长期测试使用，请联系 。 + +对于有合作的商业伙伴，我们将直接提供 PTC 以供使用。 + +## 4. 使用 `CLI` 创建数据库 + +```bash +$ cql -config conf/config.yaml -create 1 +INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" +``` + +第一行命令中的 `1` 表示申请几个矿工为你的数据库服务。`covenantsql://...` 开头的这个字符串就是创建的数据库访问地址，在 SDK 和 CLI 命令中都需要用此地址，在整个区块链中找到这个数据库。 + +## 5. CLI 和 SDK 的详细文档 + +创建好数据库后，您可以参考以下文档和示例，以便更快的使用CovenantSQL来开发应用。 + +- [CLI 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql/README-zh.md) +- [SDK 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/README-zh.md) +- [SDK 示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) + +## 6. SQLChain 浏览器 + +目前，测试网的数据库时不需要权限的。意味着您可以通过数据库的DSN(数据库访问地址)，在[SQLChain 浏览器](https://explorer.dbhub.org)中拿到所有的修改历史和区块信息。 + +更多的测试网技术支持，请访问: + +> [TestNet 发行日志](https://github.com/CovenantSQL/CovenantSQL/wiki/Release-Notes-zh) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/getting-started-zh.md b/website/translated_docs/zh-CN/version-0.0.6/getting-started-zh.md new file mode 100644 index 0000000..a7c7ce9 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/getting-started-zh.md @@ -0,0 +1,486 @@ +--- +id: version-0.0.6-local-deployment +title: CovenantSQL 综述 +original_id: local-deployment +--- +# CovenantSQL 介绍 + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可变成 ĐApp +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是用户的钱包，那么 CovenantSQL 就是是用户的去中心化数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密 保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 + +# 安装 CovenantSQL 客户端 + +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +* [Go](./development-golang-client-zh.md) +* [Java](https://github.com/CovenantSQL/covenant-connector) +* [Python](https://github.com/CovenantSQL/python-driver) +* [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +* `conf/private.key`: 为您生成的私钥通过主密码加密保存在该文件中，您的账号地址需要使用该文件创建； +* `conf/config.yaml`: 为您生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +* [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 + +# 部署 CovenantSQL + +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 启动 Docker 容器 + +执行以下的命令在本地运行 CovenantSQL + +```shell +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +make docker +make start +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行`export COVENANTSQL_ROOT=$PWD`存为环境变量 + +### 检查运行状态 + +```shell +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_adapter ./docker-entry.sh Up 0.0.0.0:11105->4661/tcp +covenantsql_bp_0 ./docker-entry.sh Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 ./docker-entry.sh Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 ./docker-entry.sh Up 0.0.0.0:11101->4661/tcp +covenantsql_explorer /bin/sh -c MAGIC_DOLLAR='$ ... Up 0.0.0.0:11108->80/tcp +covenantsql_miner_0 ./docker-entry.sh Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 ./docker-entry.sh Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 ./docker-entry.sh Up 0.0.0.0:11104->4661/tcp +covenantsql_mysql_adapter ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11106->4663/tcp +``` + +### SQLChain Explorer + +我们在`:11108`端口提供了一个 SQLChain 的 Explorer 可以看到 SQL 语句在链上的情况 + +# 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +cql -config config/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +cql -config config/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +cql -config config/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +# 使用 CovenantSQL 开发 App + +## Golang 使用 CovenantSQL + +#### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +#### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +#### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +#### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +#### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` + +# CovenantSQL API + +# 常见问题解答 + +补充 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/getting-started.md b/website/translated_docs/zh-CN/version-0.0.6/getting-started.md new file mode 100644 index 0000000..ff3aeb8 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/getting-started.md @@ -0,0 +1,229 @@ +--- +id: version-0.0.6-getting-started +title: CovenantSQL 一键开箱使用 +original_id: getting-started +--- +## 一键部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 部署 CovenantSQL + +执行以下的命令在本地运行 CovenantSQL + +```shell +$ git clone https://github.com/CovenantSQL/CovenantSQL +$ cd CovenantSQL +$ make start +``` + +后续的所有命令，wd 都是在 clone 的 CovenantSQL 源码目录中 + +### 检查运行状态 + +```shell +$ docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_adapter ./docker-entry.sh Up 0.0.0.0:11105->4661/tcp +covenantsql_bp_0 ./docker-entry.sh Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 ./docker-entry.sh Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 ./docker-entry.sh Up 0.0.0.0:11101->4661/tcp +covenantsql_explorer /bin/sh -c MAGIC_DOLLAR='$ ... Up 0.0.0.0:11108->80/tcp +covenantsql_miner_0 ./docker-entry.sh Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 ./docker-entry.sh Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 ./docker-entry.sh Up 0.0.0.0:11104->4661/tcp +covenantsql_mysql_adapter ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11106->4663/tcp +``` + +## 使用 CovenantSQL + +### 创建数据库 + +创建一个单节点的数据库实例，可以将 create 的参数调整为 2 或者最多至 3（当前一键部署只部署了 3 个miner 节点，只能支持最多 3 节点的实例） + +```shell +$ docker cp covenantsql_bp_1:/app/cql ./ +$ ./cql -config ./test/service/node_c/config.yaml -create 1 +``` + +将会得到数据库的 dsn 串，当前示例是 `covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4` + +```shell +INFO[0001] the newly created database is: "covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4" +``` + +### 使用 cql 命令行访问数据库 + +```shell +$ ./cql -config ./test/service/node_c/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +执行任何常见 SQL 命令（兼容 SQLite 语法 和 部分类似 MySQL 的 SHOW 语法） + +```shell +INFO[0000] connecting to "covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4" +Connected with driver covenantsql (feature/kayakPerformance-a6e183ed-20181107003651) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +示例 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> create table test (test string); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> show tables; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> \q + +$ +``` + +## 使用 Java/Python Driver 操作 CovenantSQL + +当前 Java/Python Driver 需要依赖 ```covenantsql_adapter``` 服务使用，使用前确保 `covenantsql_adapter` 服务运行正常 + +### Java JDBC Driver 使用 + +**需要使用 maven 编译 java-connector + +```shell +$ git clone https://github.com/CovenantSQL/covenant-connector +$ cd covenant-connector/covenantsql-java-connector +$ mvn package -Dmaven.test.skip=true +``` + +编译后将会得到 3 个编译 jar 结果 + +```shell +$ ls -l target/*.jar +target/covenantsql-java-connector-1.0-SNAPSHOT-jar-with-dependencies.jar +target/covenantsql-java-connector-1.0-SNAPSHOT-shaded.jar +target/covenantsql-java-connector-1.0-SNAPSHOT.jar +``` + +Driver 提供了一个简单的 Example 测试 + +Example 源码在 `./src/main/java/io/covenantsql/connector/example/Example.java` + +使用 dsn 串中的 host 部分 ```0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4``` 设置为 `COVENANTSQL_DATABASE` 这个 property 来测试 example + +```shell +$ java -DCOVENANTSQL_DATABASE=0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 -cp target/covenantsql-java-connector-1.0-SNAPSHOT-jar-with-dependencies.jar io.covenantsql.connector.example.Example +``` + +可以看到插入和查询的结果 + +```shell +[main] INFO io.covenantsql.connector.CovenantDriver - covenantsql driver registered +Build url: jdbc:covenantsql://127.0.0.1:11105/0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +Connecting to database... +Creating statement... +ID: 1, Email: Apple, Password: appleisdelicious, Time: 00:01:17 +``` + +### Python Driver 使用 + +**当前支持 `python3` 下使用 Python Driver，`python2` 将会在兼容性测试后提供 + +Demo 依赖 `python3` 和 `pipenv` + +Python3: https://www.python.org/download/releases/3.0/ + +Pipenv: https://github.com/pypa/pipenv + +安装依赖完成后，clone demo 并安装依赖到 pipenv + +```shell +$ git clone https://github.com/CovenantSQL/python-demos.git +$ cd python-demos +$ pipenv install +``` + +使用 dsn 串中的 host 部分 `0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4`设置为 `COVENANTSQL_DATABASE` env 变量来执行测试 + +`COVENANTSQL_ROOT` 环境变量为开始 clone 的 CovenantSQL 代码目录 + +```shell +$ pipenv shell +(python-demos-d0igWVYT) $ cd hello-covenantsql +(python-demos-d0igWVYT) $ chmod u+x main.py +(python-demos-d0igWVYT) $ COVENANTSQL_DATABASE=0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 \ +COVENANTSQL_PRIVATE_KEY=${COVENANTSQL_ROOT}/test/service/node_c/admin.test.covenantsql.io-key.pem \ +COVENANTSQL_PROXY_PEM=${COVENANTSQL_ROOT}/test/service/node_c/admin.test.covenantsql.io.pem ./main.py +``` + +执行结果如下（因为使用了 Java JDBC Driver插入了一行数据，这里可以看到两行数据） + +```shell +create table +insert sample data +affected rows: 1, lastrowid: 2 +select data from the table +(1, '2018-11-07T16:01:17Z', 'Apple', 'appleisdelicious') +(2, '2018-11-07T16:10:29Z', 'Apple', 'appleisdelicious') +``` + +退出 pipenv + +```shell +(python-demos-d0igWVYT) $ deactive +$ +``` + +## 使用 MySQL Client（version <=5.7）操作 CovenantSQL + +**当前只支持 version <=5.7 的 MySQL Client 访问，且依赖 `covenantsql_mysql_adapter` 服务使用，使用前确保 `covenantsql_mysql_adapter` 服务运行正常 + +```shell +$ mysql -h127.0.0.1 -P11107 -uroot -pcalvin -D0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +可以执行任何常见 SQL 命令进行测试 + +```shell +Reading table information for completion of table and column names +You can turn off this feature to get a quicker startup with -A + +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 10001 +Server version: 5.7.0 + +Copyright (c) 2000, 2018, 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 +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> show tables; ++-----------------+ +| name | ++-----------------+ +| test | +| users | +| sqlite_sequence | ++-----------------+ +3 rows in set (0.02 sec) + +mysql> +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/install.md b/website/translated_docs/zh-CN/version-0.0.6/install.md new file mode 100644 index 0000000..c81fb23 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/install.md @@ -0,0 +1,115 @@ +--- +id: version-0.0.6-install +title: 安装 CovenantSQL 客户端 +original_id: install +--- +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +- [Go](./development-golang-client-zh.md) +- [Java](https://github.com/CovenantSQL/covenant-connector) +- [Python](https://github.com/CovenantSQL/python-driver) +- [NodeJS](https://github.com/CovenantSQL/node-covenantsql) +- [Web (WIP)](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +- `conf/private.key`: 为您生成的私钥通过主密码加密保存在该文件中，您的账号地址需要使用该文件创建； +- `conf/config.yaml`: 为您生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +- [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/intro.md b/website/translated_docs/zh-CN/version-0.0.6/intro.md new file mode 100644 index 0000000..f71ecd6 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/intro.md @@ -0,0 +1,73 @@ +--- +id: version-0.0.6-intro +title: CovenantSQL 介绍 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可数据上链 +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是人们的私人钱包，那么 CovenantSQL 就是是人们的去中心化的私密数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密来保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/nav.md b/website/translated_docs/zh-CN/version-0.0.6/nav.md new file mode 100644 index 0000000..b2842cb --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/nav.md @@ -0,0 +1,18 @@ +--- +id: version-0.0.6-nav +title: 使用导航 +original_id: nav +--- +## 直接使用测试网 + +[🌏 TestNet 快速开始](./quickstart) + +## 部署私有 CovenantSQL 数据库（搭建私有链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +[🔗 Docker 一键部署 CovenantSQL 测试网](./deployment) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/qna.md b/website/translated_docs/zh-CN/version-0.0.6/qna.md new file mode 100644 index 0000000..519f07d --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/qna.md @@ -0,0 +1,6 @@ +--- +id: version-0.0.6-qna +title: 常见问题解答 +original_id: qna +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/quickstart.md b/website/translated_docs/zh-CN/version-0.0.6/quickstart.md new file mode 100644 index 0000000..2ea23d0 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/quickstart.md @@ -0,0 +1,107 @@ +--- +id: version-0.0.6-quickstart +title: 快速开始 +original_id: quickstart +--- +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。你将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为你准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放你的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示你创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，你可以按你操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +- [Go](./development) +- [Java](https://github.com/CovenantSQL/covenant-connector) +- [Python](https://github.com/CovenantSQL/python-driver) +- [NodeJS](https://github.com/CovenantSQL/node-covenantsql) +- [Web (WIP)](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看你的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，你可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入你的数据库地址。 + +## 创建账号 + +我们的测试网支持你创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +- `conf/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `conf/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +你可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入你生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为你的钱包充值。 + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +恭喜，你已收到我们发出的 PTC 稳定币，现在即可开始使用 CovenantSQL， 你可以参考 [Golang 使用 CovenantSQL 文档](./development) 进行开发。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.0.6/usecase.md b/website/translated_docs/zh-CN/version-0.0.6/usecase.md new file mode 100644 index 0000000..87f5b00 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.0.6/usecase.md @@ -0,0 +1,6 @@ +--- +id: version-0.0.6-usecase +title: 使用案例 +original_id: usecase +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/api.md b/website/translated_docs/zh-CN/version-0.1.0/api.md new file mode 100644 index 0000000..a67acb9 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/api.md @@ -0,0 +1,6 @@ +--- +id: version-0.1.0-api +title: '👩🏻‍💻 CovenantSQL API' +original_id: api +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/bck/api-json-rpc.md b/website/translated_docs/zh-CN/version-0.1.0/bck/api-json-rpc.md new file mode 100644 index 0000000..7dfc832 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/bck/api-json-rpc.md @@ -0,0 +1,440 @@ +--- +id: version-0.1.0-api-json-rpc +title: JSON RPC +original_id: api-json-rpc +--- +> JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. + +CovenantSQL provides a suite of RPC methods in [JSON-RPC 2.0](https://www.jsonrpc.org/specification) for easily accessing to CovenantSQL networks. + +## Javascript API + +[cql.js](https://github.com/covenantsql/cql.js) is a Javascript SDK which has encapsulated the RPC methods in order to give a much more convenient way to talk to the CovenantSQL networks. See the [Javascript API](cql-js.md) for more. + +## JSON RPC Endpoint + +| Network | Provider | URL | +| ------------------------ | ------------- | -------------------------------------- | +| CovenantSQL Test Network | Covenant Labs | https://jsonrpc.testnet.covenantsql.io | +| CovenantSQL Main Network | Covenant Labs | Comming soon :) | + +## JSON RPC API Reference + +### bp_getProtocolVersion + +Returns the current CovenantSQL protocol version. + +#### Parameters + +None. + +#### Returns + +- string - the current CovenantSQL protocol version + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "method": "bp_getProtocolVersion", + "params": [], + "id": 1 +} +``` + +Response: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0.1.0" +} +``` + +### bp_getRunningStatus + +Returns some basic indicators describing the running status of the CovenantSQL network. + +#### Parameters + +None. + +#### Returns + +- object: an object describes the running status of the network. + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getRunningStatus", + "params": [] +} +``` + +Response: + +```js +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "block_height": 182414, // height of the latest block + "count_accounts": 103, // count of the accounts ever created + "count_databases": 912414, // count of the databases ever created + "qps": 10241 // estimated QPS of database operations of the whole net + } +} +``` + +### bp_getBlockList + +Returns a list of the blocks. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------- | ---------------------- | ------ | +| 0 | from | integer | start height, included | 1 | +| 1 | to | integer | end height, excluded | 11 | + +**Constraints:** `to - from ∈ [5, 100]` + +#### Returns + +- array: list of the blocks, the object in the list is a [Block](#s-block), but **without** transaction details + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockList", + "params": [1, 11] +} +``` + +Response: [Block](#s-block) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { TODO: block object } + ] +} +``` + +### bp_getBlockListByTimeRange + +TODO: as a new API in the next release + +### bp_getBlockByHeight + +Returns information about the block specified by its height. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | height of the block | 1024 | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHeight", + "params": [1, true] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getBlockByHash + +Returns information about the block specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------- | ------ | +| 0 | hash | string | hash of the block | "TODO" | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHash", + "params": ["TODO", true] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getTransactionList + +Returns a list of the transactions. Traverse page by page by using a transaction hash as the mark for paging. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | --------- | ------- | ------------------------------------------- | ---------- | +| 0 | since | string | hash as the start point of traverse | "TODO" | +| 1 | direction | string | traverse direction, "backward" or "forward" | "backward" | +| 2 | size | integer | page size, [5, 100] | 20 | + + QhcAe42Xf8cwGUf5NYGQDQ + XNZ9yipFBUV5ySBtreW1MA ↑ forward (in newer blocks) + 9fXd3s5HE5fC8lOYY6uAZA + KhytGjS0xjw5CJvcJYpsNg ← since (paging mark) + 2KOxrKMS4iVDKXnm6HuYiA + 71VwqOMOvAsBXJRMeBruWg ↓ backward (in older blocks) + 0P3k04RKHw8SEMKHxADC8A + + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionList", + "params": ["KhytGjS0xjw5CJvcJYpsNg", "forward", 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { TODO: transaction object } + ] +} +``` + +### bp_getTransactionListInBlock + +Returns a list of the transactions from a block by the specified height. + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | --------------------- | ------ | +| 0 | height | integer | block height | 1024 | +| 1 | from | integer | start index, included | 0 | +| 2 | to | integer | end index, excluded | 10 | + +**Constraints:** `to - from ∈ [5, 100]` + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionListInBlock", + "params": [1024, 0, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { TODO: transaction object } + ] +} +``` + +### bp_getTransactionByHash + +Returns information about the transaction specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------------- | ------ | +| 0 | hash | string | hash of the transaction | "TODO" | + +#### Returns + +- object: transaction information object, it's a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionByHash", + "params": ["TODO", true] +} +``` + +Response: [Transaction](#s-transaction) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: transaction object + } +} +``` + +## Structure Reference + +Here are some common structure definitions used in the API. + + + +### Block + +The block generated in the CovenantSQL blockchain network. + +| Field | Type | Description | +| ----------- | ------- | -------------------------------------------- | +| height | integer | Height of the block | +| hash | string | Hash of the block | +| version | integer | Version number of the block | +| producer | string | Address of the node who generated this block | +| merkle_root | string | Hash of the merkle tree | +| parent | string | Hash of its parent block | +| timestamp | string | Create time of the block | +| signee | string | Public key of the node who signed this block | +| signature | string | Signature for the this block | +| tx_count | integer | Count of the transactions in this block | + +Sample in JSON format: + +```json +{ + "height": 12, + "hash": "TODO", + "version": 1, + "producer": "4io8u9v9nydaQPXtmqibg8gJbkNFd7DdM47PLWuM7ubzBXZ4At7", + "merkle_root": "TODO", + "parent": "TODO", + "timestamp": "TODO", + "signee": "TODO", + "signature": "TODO", + "tx_count": 1 +} +``` + + + +### Transaction + +| Field | Type | Description | +| ------------ | ------- | ------------------------------------------------------------------------------------------- | +| block_height | integer | Height of the block this transaction belongs to | +| index | integer | Index of the transaction in the block | +| hash | string | Hash of the transaction data | +| block_hash | string | Hash of the block this transaction belongs to | +| type | integer | Type of the transaction | +| signee | string | Public key of the account who signed this transaction | +| address | string | Account address who signed this transaction | +| signature | string | Signature of this transaction | +| timestamp | string | Create time of the transaction | +| raw | string | Raw content of the transaction data, in JSON format | +| tx | object | Concrete transaction object, see supported [transaction types](#transaction-types) for more | + +Sample in JSON format: + +```json +{ + "block_height": 1, + "index": 0, + "hash": "TODO", + "block_hash": "TODO", + "timestamp": "TODO", + "type": 1, + "signee": "TODO", + "address": "TODO", + "signature": "TODO", + "raw": "TODO", + "tx": { + "field": "TODO" + } +} +``` + +**Supported Transaction Types:** + +- [CreateDatabase](#s-transaction-createdatabase) + +TODO: more types + + + +### Transaction: CreateDatabase + +TODO: more types \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/bck/development-cmd-cql-utils-zh.md b/website/translated_docs/zh-CN/version-0.1.0/bck/development-cmd-cql-utils-zh.md new file mode 100644 index 0000000..767df8d --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/bck/development-cmd-cql-utils-zh.md @@ -0,0 +1,41 @@ +--- +id: version-0.1.0-keygen +title: 使用 cql-utils 生成密钥与钱包 +original_id: keygen +--- +`cql-utils` 是 CovenantSQL 的一个命令行工具，具体用法如下。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 使用 + +### 生成公私钥对 + + $ cql-utils -tool keygen + Enter master key(press Enter for default: ""): + ⏎ + Private key file: private.key + Public key's hex: 03bc9e90e3301a2f5ae52bfa1f9e033cde81b6b6e7188b11831562bf5847bff4c0 + + +生成的 private.key 文件即是使用主密码加密过的私钥文件，而输出到屏幕上的字符串就是使用十六进制进行编码的公钥。 + +### 使用私钥文件或公钥生成钱包地址 + + $ cql-utils -tool addrgen -private private.key + Enter master key(default: ""): + ⏎ + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + $ cql-utils -tool addrgen -public 02f2707c1c6955a9019cd9d02ade37b931fbfa286a1163dfc1de965ec01a5c4ff8 + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + + +你可以通过指定私钥文件，或者把上述的公钥十六进制编码字符串作为命令行参数来直接生成钱包地址。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/bck/development-cmd-cql-zh.md b/website/translated_docs/zh-CN/version-0.1.0/bck/development-cmd-cql-zh.md new file mode 100644 index 0000000..b46fae0 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/bck/development-cmd-cql-zh.md @@ -0,0 +1,77 @@ +--- +id: version-0.1.0-cql +title: 使用命令行客户端 cql 创建数据库 +original_id: cql +--- +本文档主要介绍 CovenantSQL 命令行客户端 `cql` 的使用。`cql` 是一个用于批量进行 SQLChain 上数据库的创建、查询、更新或删除操作的命令行工具。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 生成默认配置文件 + +首先需要一个 config 文件和由你输入的主密码（master key）来初始化，其中主密码用来加密解密本地密钥对。使用 `cql-utils` 工具进行配置文件生成后，你可以在生成的配置文件目录下找到密钥文件。 + +具体请参考: [cql-utils 使用文档](https://github.com/CovenantSQL/docs/tree/master/development-cmd-utils-zh.md#使用) 中配置文件及钱包地址生成相关章节。 + +## 检查钱包余额 + +使用 `cql` 命令来检查钱包余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] +### Public Key ### +0388954cf083bb6bb2b9c7248849b57c76326296fcc0d69764fc61eedb5b8d820c +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +这里我们得到结果 **"stable coin balance is: 100"**。 + +## 初始化一个 CovenantSQL 数据库 + +准备好配置文件和主密码后就可以使用 `cql` 命令来创建数据库了，你的数据库 ID 将会输出到屏幕上： + +```bash +# if a non-default password applied on master key, use `-password` to pass it +$ cql -config conf/config.yaml -create 1 +INFO[0000] +### Public Key ### +039bc931161383c994ab9b81e95ddc1494b0efeb1cb735bb91e1043a1d6b98ebfd +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] the newly created database is: covenantsql://0e9103318821b027f35b96c4fd5562683543276b72c488966d616bfe0fe4d213 caller="main.go:297 main.main" +``` + +这里 `-create 1` 表示创建一个单节点的 SQLChain。 + +```bash +$ cql -config conf/config.yaml -dsn covenantsql://address +``` + +`address` 就是你的数据库 ID。 + +`cql` 命令的详细使用帮助如下： + +```bash +$ cql -help +``` + +## 使用 `cql` + +现在可以使用 `cql` 进行数据库操作了: + +```bash +co:address=> show tables; +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/bck/development-golang-client-zh.md b/website/translated_docs/zh-CN/version-0.1.0/bck/development-golang-client-zh.md new file mode 100644 index 0000000..9bbb203 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/bck/development-golang-client-zh.md @@ -0,0 +1,108 @@ +--- +id: version-0.1.0-golang-client +title: 使用 Golang 驱动访问数据库 +original_id: golang-client +--- +本文档介绍 CovenantSQL 客户端的使用方式。客户端用来创建、查询、更新和删除 SQLChain 以及绑定的数据库。 + +## 开始之前 + +确保 `$GOPATH/bin` 目录在环境变量 `$PATH` 中，执行以下命令 + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +然后在你的 go 代码中 import 第一个 `client` 包。 + +## 初始化一个 CovenantSQL 客户端 + +首先需要一个 config 文件和 master key 来初始化。master key 用来加密解密本地密钥对。以下是如何用一个自定义 master key 来生成默认的 config 文件： + +### 生成默认的配置文件 + +运行以下 `cql-utils` 命令，输入 master key（类似密码）来生成本地密钥对。等待几十秒，会在 `conf` 文件夹中，生成一个私钥文件和一个名为 `config.yaml` 的配置文件。 + +```bash +$ cql-utils -tool confgen -root conf +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: conf/private.key +Public key's hex: 025abec9b0072615170f4acf4a2fa1162a13864bb66bc3f140b29f6bf50ceafc75 +Generated key pair. +Generating nonce... +INFO[0005] cpu: 1 +INFO[0005] position: 0, shift: 0x0, i: 0 +nonce: {{1450338416 0 0 0} 26 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514} +node id: 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514 +Generated nonce. +Generating config file... +Generated nonce. +``` + +有了配置文件之后，可以通过以下 go 代码来初始化 CovenantSQL 客户端： + +```go +client.Init(configFile, masterKey) +``` + +## 客户端使用方式 + +### 创建一个 SQLChain 数据库 + +创建 SQLChain 数据库需要指明需要几个节点（nodeCount变量）: + +```go +var ( + dsn string + meta client.ResourceMeta +) +meta.Node = uint16(nodeCount) +dsn, err = client.Create(meta) +// process err +``` + +创建完毕会返回一个 dsn 字符串，用来访问这个数据库。 + +### 查询和执行 + +拿到 dsn 字符串后，可以通过以下代码在 SQLChain 中执行 SQL 语句： + +```go +
db, err := sql.Open("covenantsql", dsn) + // process err + + _, err = db.Exec("CREATE TABLE testSimple ( column int );") + // process err + + _, err = db.Exec("INSERT INTO testSimple VALUES(?);", 42) + // process err + + row := db.QueryRow("SELECT column FROM testSimple LIMIT 1;") + + var result int + err = row.Scan(&result) + // process err + fmt.Printf("SELECT column FROM testSimple LIMIT 1; result %d\n", result) + + err = db.Close() + // process err + +``` + +用法和其他 go sql driver 一致。 + +### 删除数据库 + +使用 dsn 来删除数据库： + +```go + err = client.Drop(dsn) + // process err +``` + +### 完整示例 + +在以下目录中有一个简单示例和复杂示例可以参考 [示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/bck/getting-started-overview-zh.md b/website/translated_docs/zh-CN/version-0.1.0/bck/getting-started-overview-zh.md new file mode 100644 index 0000000..f240f32 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/bck/getting-started-overview-zh.md @@ -0,0 +1,63 @@ +--- +id: version-0.1.0-intro +title: 简介 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +- **SQL**: 支持 SQL-92 标准 +- **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +- **隐私**: 通过加密和授权许可进行访问 +- **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信[在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +#### 一行代码接入区块链数据 + +```go +sql.Open("CovenantSQL", dbURI) +``` + +# # + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +- 第一层: **全局共识层**(主链，架构图中的中间环): + - 整个网络中只有一个主链。 + - 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +- 第二层: **SQL 共识层**(子链，架构图中的两边环): + - 每个数据库都有自己独立的子链。 + - 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +- 第三层: **数据储存层**(支持 SQL-92 的数据库引擎): + - 每个数据库都有自己独立的分布式引擎。 + - 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/bck/getting-started-testnet-zh.md b/website/translated_docs/zh-CN/version-0.1.0/bck/getting-started-testnet-zh.md new file mode 100644 index 0000000..2877e82 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/bck/getting-started-testnet-zh.md @@ -0,0 +1,93 @@ +--- +id: version-0.1.0-testnet +title: CovenantSQL 测试网快速入门 +original_id: testnet +--- +[CovenantSQL](https://github.com/CovenantSQL/CovenantSQL/blob/develop/README-zh.md) 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +1. **SQL**: 支持 SQL-92 标准 +2. **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +3. **隐私**: 通过加密和授权许可进行访问 +4. **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## 0. 下载 CovenantSQL 工具 + +在 [github](https://github.com/CovenantSQL/CovenantSQL/releases) 下载最新的发行版 + +## 1. 用 `cql-utils` 生成配置文件访问测试网 + +```bash +$ cql-utils -tool confgen +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: conf/private.key +Public key's hex: 02296ea73240dcd69d2b3f1fb754c8debdf68c62147488abb10165428667ec8cbd +Generated key pair. +Generating nonce... +nonce: {{731613648 0 0 0} 11 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9} +node id: 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9 +Generated nonce. +Generating config file... +Generated nonce. +``` + +运行完成后，`cql-utils`会在 `./conf` 目录生成一个配置文件。 + +## 2. 用私钥生成钱包地址 + +私钥可以再上一步的 `./conf` 目录中找到，文件名为 `private.key` + +```bash +$ cql-utils -tool addrgen -private ./conf/private.key +Enter master key(default: ""): +⏎ +wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 +``` + +上述 `4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9` 就是钱包地址 + +## 3. 在水龙头(Faucet)获取 Particle(PTC) + +水龙头(Faucet)的地址为: [CovenantSQL 测试网 Particle(PTC) 水龙头](https://testnet.covenantsql.io/)。 + +完成教程之后，用 `cql` 命令来检查钱包地址的余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +当看到 **"stable coin balance is: 100"** 时，表明余额已经为 100。 + +如果您需要更多的 PTC 作为长期测试使用，请联系 。 + +对于有合作的商业伙伴，我们将直接提供 PTC 以供使用。 + +## 4. 使用 `CLI` 创建数据库 + +```bash +$ cql -config conf/config.yaml -create 1 +INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" +``` + +第一行命令中的 `1` 表示申请几个矿工为你的数据库服务。`covenantsql://...` 开头的这个字符串就是创建的数据库访问地址，在 SDK 和 CLI 命令中都需要用此地址，在整个区块链中找到这个数据库。 + +## 5. CLI 和 SDK 的详细文档 + +创建好数据库后，您可以参考以下文档和示例，以便更快的使用CovenantSQL来开发应用。 + +- [CLI 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql/README-zh.md) +- [SDK 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/README-zh.md) +- [SDK 示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) + +## 6. SQLChain 浏览器 + +目前，测试网的数据库时不需要权限的。意味着您可以通过数据库的DSN(数据库访问地址)，在[SQLChain 浏览器](https://explorer.dbhub.org)中拿到所有的修改历史和区块信息。 + +更多的测试网技术支持，请访问: + +> [TestNet 发行日志](https://github.com/CovenantSQL/CovenantSQL/wiki/Release-Notes-zh) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/bck/getting-started-zh.md b/website/translated_docs/zh-CN/version-0.1.0/bck/getting-started-zh.md new file mode 100644 index 0000000..8eebf58 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/bck/getting-started-zh.md @@ -0,0 +1,486 @@ +--- +id: version-0.1.0-local-deployment +title: CovenantSQL 综述 +original_id: local-deployment +--- +# CovenantSQL 介绍 + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可变成 ĐApp +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是用户的钱包，那么 CovenantSQL 就是是用户的去中心化数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密 保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 + +# 安装 CovenantSQL 客户端 + +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +* [Go](./development-golang-client-zh.md) +* [Java](https://github.com/CovenantSQL/covenant-connector) +* [Python](https://github.com/CovenantSQL/python-driver) +* [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +* `conf/private.key`: 为您生成的私钥通过主密码加密保存在该文件中，您的账号地址需要使用该文件创建； +* `conf/config.yaml`: 为您生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +* [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 + +# 部署 CovenantSQL + +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 启动 Docker 容器 + +执行以下的命令在本地运行 CovenantSQL + +```shell +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +make docker +make start +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行`export COVENANTSQL_ROOT=$PWD`存为环境变量 + +### 检查运行状态 + +```shell +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_adapter ./docker-entry.sh Up 0.0.0.0:11105->4661/tcp +covenantsql_bp_0 ./docker-entry.sh Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 ./docker-entry.sh Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 ./docker-entry.sh Up 0.0.0.0:11101->4661/tcp +covenantsql_explorer /bin/sh -c MAGIC_DOLLAR='$ ... Up 0.0.0.0:11108->80/tcp +covenantsql_miner_0 ./docker-entry.sh Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 ./docker-entry.sh Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 ./docker-entry.sh Up 0.0.0.0:11104->4661/tcp +covenantsql_mysql_adapter ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11106->4663/tcp +``` + +### SQLChain Explorer + +我们在`:11108`端口提供了一个 SQLChain 的 Explorer 可以看到 SQL 语句在链上的情况 + +# 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +cql -config config/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +cql -config config/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +cql -config config/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +# 使用 CovenantSQL 开发 App + +## Golang 使用 CovenantSQL + +#### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +#### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +#### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +#### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +#### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` + +# CovenantSQL API + +# 常见问题解答 + +补充 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/bck/guide-zh.md b/website/translated_docs/zh-CN/version-0.1.0/bck/guide-zh.md new file mode 100644 index 0000000..98858f8 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/bck/guide-zh.md @@ -0,0 +1,114 @@ +--- +id: version-0.1.0-guide-zh +title: 快速开始 +original_id: guide-zh +--- +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +- [Go](./development-golang-client-zh.md) +- [Java](https://github.com/CovenantSQL/covenant-connector) +- [Python](https://github.com/CovenantSQL/python-driver) +- [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +- `conf/private.key`: 为您生成的私钥通过主密码加密保存在该文件中，您的账号地址需要使用该文件创建； +- `conf/config.yaml`: 为您生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +- [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/cql.md b/website/translated_docs/zh-CN/version-0.1.0/cql.md new file mode 100644 index 0000000..49710cc --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/cql.md @@ -0,0 +1,144 @@ +--- +id: version-0.1.0-cql +title: '🖥️ CQL 命令行工具' +original_id: cql +--- +## 简介 + +本文将介绍如何使用 `cql` 进行查询、转账和数据库权限管理。在使用 `cql` 前请先确认已接入 [CovenantSQL TestNet](quickstart) 或者在本地使用 [Docker 一键部署](development)的网络。 + +## 查询余额 + +查询余额有两个命令：`cql -get-balance` 和 `cql -token-balance `。其中 `-get-balance` 将返回用户账户中 `Particle` 与 `Wave` 的数量，`-token-balance ` 将返回用户账户中特定 `token_type` 的 token 数量。目前系统支持的 `token_type` 有： + +- `Particle` +- `Wave` +- `Bitcoin` +- `Ether` +- `EOS` + +查看默认余额： + +```bash +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] Particle balance is: 10000000000000000000 + INFO[0000] Wave balance is: 10000000000000000000 + + +查看 Particle 余额： + +```bash +./cql -config conf/config.yaml -token-balance Particle +``` + +输出： + + INFO[0000] Particle balance is: 10000000000000000000 + + +查看 Bitcoin 余额： + +```bash +./cql -config conf/config.yaml -token-balance Bitcoin +``` + +输出： + + INFO[0000] Bitcoin balance is: 0 + + +## 转账 + +转账操作使用 `cql -transfer` 并以 `json` 格式的转账信息为参数。 + +```json +{ + "addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // 收款地址 + "amount":"1000000 Particle" // 转账金额并带上单位 +} +``` + +其中收款地址可以是一个个人钱包地址也可以是一个数据库子链地址。转账至数据库地址时将在该数据库账户上补充付款人的押金与预付款。 + +转账 Particle： + +```bash +./cql -config conf/config.yaml -transfer '{"addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount":"1000000 Particle"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +转账 Wave： + +```bash +./cql -config conf/config.yaml -transfer '{"addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount":"1000000 Wave"}' +``` + + INFO[0000] succeed in sending transaction to CovenantSQL + + +查看余额： + +```bash +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] Particle balance is: 9999999999999000000 + INFO[0000] Wave balance is: 9999999999999000000 + + +注意，`succeed in sending transaction to CovenantSQL` 只说明交易已成功发送至主网，交易能否成功、何时成功需要通过 `-get-balance` 或者 `-token-balance ` 确定。 + +## 数据库权限管理 + +CovenantSQL 数据库有三类库级别权限： + +- `Admin` +- `Write` +- `Read` +- `Void` + +其中，`Admin` 可以赋予其他钱包地址数据库的权限（`Admin`、`Write` 或 `Read`）；`Admin` 和 `Write` 可以对数据库进行写操作（`CREATE`, `INSERT` 等）；`Admin`, `Write` 和 `Read` 可以对数据库进行读操作（`SHOW`, `SELECT` 等）；`Void` 是一个特殊的权限，当 `Admin` 想取消某个地址的权限时可以将该地址的权限设置为 `Void`，这样该地址将无法继续读写数据库。创建数据库的地址的权限默认为 `Admin`。若 `Admin` 需要赋予他人权限请使用 `cql -update-perm` 并以 `json` 格式的权限信息为参数： + +```json +{ + "chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", // 需要进行权限变更的数据库地址 + "user":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // 需要赋予权限的钱包地址 + "perm":"Write" // 权限内容 +} +``` + +增加写权限： + +```bash +./cql -config conf/config.yaml -update-perm '{"chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","user":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","perm":"Write"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +吊销权限： + +```bash +./cql -config conf/config.yaml -update-perm '{"chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","perm":"Void"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +注意，`succeed in sending transaction to CovenantSQL` 只说明交易已成功发送至主网，交易成功与否请通过查询数据库确认。 + +为数据库添加新的账户权限后账户需补充押金与预付款才能进行正常查询。押金与预付款最小值的计算公式：`gas_price*number_of_miner*120000`。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/deployment.md b/website/translated_docs/zh-CN/version-0.1.0/deployment.md new file mode 100644 index 0000000..524f5aa --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/deployment.md @@ -0,0 +1,156 @@ +--- +id: version-0.1.0-deployment +title: '🐳 Docker 一键部署' +original_id: deployment +--- +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 下载项目 + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行 + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +存为环境变量 + +### 启动 Docker 容器 + +现在有两种方式启动 CovenantSQL 容器： + +1. 使用 Docker Hub 上的公共镜像 +2. 构建 CovenantSQL Docker 镜像 + +> 我们推荐普通用户使用第一种方式测试 CovenantSQL，第二种仅用于体验最新的开发中的特性。 + +#### 1. 使用 Docker Hub 上的公共镜像 + +然后直接启动： + +```bash +make start +``` + +#### 2. 构建 CovenantSQL Docker 镜像 + +执行以下的命令在本地运行 CovenantSQL + +```bash +make docker # 从头编译新的镜像 +make start +``` + +### 检查运行状态 + +检查容器状态： + +```bash +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_adapter ./docker-entry.sh Up 0.0.0.0:11105->4661/tcp +covenantsql_bp_0 ./docker-entry.sh Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 ./docker-entry.sh Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 ./docker-entry.sh Up 0.0.0.0:11101->4661/tcp +covenantsql_explorer /bin/sh -c MAGIC_DOLLAR='$ ... Up 0.0.0.0:11108->80/tcp +covenantsql_miner_0 ./docker-entry.sh Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 ./docker-entry.sh Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 ./docker-entry.sh Up 0.0.0.0:11104->4661/tcp +covenantsql_mysql_adapter ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11106->4663/tcp +``` + +### SQLChain Explorer + +我们在`127.0.0.1:11108`端口提供了一个 SQLChain 的 Explorer 可以看到 SQL 语句在链上的情况 + +# 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/development.md b/website/translated_docs/zh-CN/version-0.1.0/development.md new file mode 100644 index 0000000..1b4a728 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/development.md @@ -0,0 +1,173 @@ +--- +id: version-0.1.0-development +title: '📦 CovenantSQL SDK' +original_id: development +--- +## Golang 使用 CovenantSQL + +### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/intro.md b/website/translated_docs/zh-CN/version-0.1.0/intro.md new file mode 100644 index 0000000..02dc58b --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/intro.md @@ -0,0 +1,73 @@ +--- +id: version-0.1.0-intro +title: CovenantSQL 介绍 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可数据上链 +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是人们的私人钱包，那么 CovenantSQL 就是是人们的去中心化的私密数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密来保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/nav.md b/website/translated_docs/zh-CN/version-0.1.0/nav.md new file mode 100644 index 0000000..f3161b6 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/nav.md @@ -0,0 +1,22 @@ +--- +id: version-0.1.0-nav +title: '📖 使用导航' +original_id: nav +--- +## 直接使用测试网 + +[🌏 TestNet 快速开始](./quickstart) + +## 部署私有 CovenantSQL 数据库（搭建私有链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +[🐳 Docker 一键部署](./deployment) + +## 使用 CovenantSQL 开发应用 + +[📦 CovenantSQL SDK](./development) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/qna.md b/website/translated_docs/zh-CN/version-0.1.0/qna.md new file mode 100644 index 0000000..8c0e5d4 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/qna.md @@ -0,0 +1,6 @@ +--- +id: version-0.1.0-qna +title: '🙋 常见问题解答' +original_id: qna +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/quickstart.md b/website/translated_docs/zh-CN/version-0.1.0/quickstart.md new file mode 100644 index 0000000..8892816 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/quickstart.md @@ -0,0 +1,148 @@ +--- +id: version-0.1.0-quickstart +title: '🌏 TestNet 快速开始' +original_id: quickstart +--- +## CovenantSQL 工具包 + +### 工具包简介 + +请根据您使用的操作系统平台选择 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。 + +例如，您使用的是： + +- MacOS 平台请下载：[**CovenantSQL-v0.1.0.osx-amd64.tar.gz**](https://github.com/CovenantSQL/CovenantSQL/releases/download/v0.1.0/CovenantSQL-v0.1.0.osx-amd64.tar.gz) +- Linux 平台请下载：[**CovenantSQL-v0.1.0.linux-amd64.tar.gz**](https://github.com/CovenantSQL/CovenantSQL/releases/download/v0.1.0/CovenantSQL-v0.1.0.linux-amd64.tar.gz) +- Windows 平台我们稍后发布，有需求请戳这里：[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/CovenantSQL/CovenantSQL) + +解压之后，你将得到以下命令行工具，包括：`cql`、`cql-utils` 等。 + +| 工具名 | 介绍 | +| ---------- | --------------------------------------------------- | +| cql | CovenantSQL 的客户端，类似 mysql 命令，用于执行 SQL | +| cql-utils | CovenantSQL 工具箱，用于和主链交互 | +| cql-minerd | CovenantSQL 矿工客户端，用于运行数据库赚取奖励，以后会开放加入 | +| cqld | CovenantSQL 主链节点，主要由 CovenantLabs 以及合作伙伴以 DPoS 模式运行 | + +### 测试网快速接入 + +目前，我们已经发布了测试网 v0.1.0，供大家进行原理性验证和体验。你可以选在使用公共的测试账号快速进行接入测试。 + +测试账号的配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) ，或者使用以下命令： + +```bash +mkdir conf +wget https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml -O conf/config.yaml +wget https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key -O conf/private.key +chmod 600 conf/private.key +``` + +**测试网注**： + +> 该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放你的应用信息，我们会不定期清理数据库数据。 +> +> 测试网暂时由 3 个 Miner 组成，所以暂时最大只支持`create 3`创建 3 个节点组成的数据库。 + +## 创建并访问 CovenantSQL 数据库 + +### 创建数据库 + +```shell +./cql -config conf/config.yaml -create 1 +``` + +输出： + + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + + +这里表示你提交了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库的创建请求到主链。 + +> 我们需要等待大概 30s 的时间，等待数据库创建，大致过程为： +> +> 1. 收到请求的 出块节点（Block Producer）进行 Miner 和数据库创建请求的撮合 +> 2. 数据库创建请求在 其它出块节点 进行验证和确认 +> 3. SQLChain 的符合条件的 Miner 收到数据库任务 +> 4. SQLChian 组建 Kayak 数据库集群 +> 5. 所有 Miner 准备就绪等待请求 + +### 访问数据库 + +```shell +./cql -config conf/config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，你可以按你操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 数据库SDK + +- [Golang开发指引](./development) + +## SQLChain区块浏览器 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，你可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。 + +> 测试网的`区块浏览器`目前是开放权限的，所以任何知道数据库 ID 的人都能看到您的数据 + +查询时，请在其页面右上角填入你的数据库 ID。例如：`0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` + +## 创建账号 + +我们的测试网支持你创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（会询问设置主密码，测试期间建议直接回车留空）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +- `conf/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `conf/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + +```toml +wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 +``` + +你可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入你生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为你的钱包充值。有任何问题请来这里讨论：[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/CovenantSQL/CovenantSQL) + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +恭喜，你已收到我们发出的 PTC 稳定币，现在即可开始使用 CovenantSQL， 你可以参考 [Golang 使用 CovenantSQL 文档](./development) 进行开发。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.1.0/usecase.md b/website/translated_docs/zh-CN/version-0.1.0/usecase.md new file mode 100644 index 0000000..f455dcb --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.1.0/usecase.md @@ -0,0 +1,6 @@ +--- +id: version-0.1.0-usecase +title: 使用案例 +original_id: usecase +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/api.md b/website/translated_docs/zh-CN/version-0.2.0/api.md new file mode 100644 index 0000000..390b56c --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/api.md @@ -0,0 +1,6 @@ +--- +id: version-0.2.0-api +title: '👩🏻‍💻 CovenantSQL API' +original_id: api +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/bck/api-json-rpc.md b/website/translated_docs/zh-CN/version-0.2.0/bck/api-json-rpc.md new file mode 100644 index 0000000..68689c2 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/bck/api-json-rpc.md @@ -0,0 +1,441 @@ +--- +id: version-0.2.0-api-json-rpc +title: JSON RPC +original_id: api-json-rpc +--- +> JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. + +CovenantSQL provides a suite of RPC methods in [JSON-RPC 2.0](https://www.jsonrpc.org/specification) for easily accessing to CovenantSQL networks. + +## Javascript API + +[cql.js](https://github.com/covenantsql/cql.js) is a Javascript SDK which has encapsulated the RPC methods in order to give a much more convenient way to talk to the CovenantSQL networks. See the [Javascript API](cql-js.md) for more. + +## JSON RPC Endpoint + +| Network | Provider | URL | +| ------------------------ | ------------- | -------------------------------------- | +| CovenantSQL Test Network | Covenant Labs | https://jsonrpc.testnet.covenantsql.io | +| CovenantSQL Main Network | Covenant Labs | Comming soon :) | + +## JSON RPC API Reference + +### bp_getProtocolVersion + +Returns the current CovenantSQL protocol version. + +#### Parameters + +None. + +#### Returns + +- string - the current CovenantSQL protocol version + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "method": "bp_getProtocolVersion", + "params": [], + "id": 1 +} +``` + +Response: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0.1.0" +} +``` + +### bp_getRunningStatus + +Returns some basic indicators describing the running status of the CovenantSQL network. + +#### Parameters + +None. + +#### Returns + +- object: an object describes the running status of the network. + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getRunningStatus", + "params": [] +} +``` + +Response: + +```js +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "block_height": 182414, // height of the latest block + "count_accounts": 103, // count of the accounts ever created + "count_databases": 912414, // count of the databases ever created + "qps": 10241 // estimated QPS of database operations of the whole net + } +} +``` + +### bp_getBlockList + +Returns a list of the blocks. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ----- | ------- | ---------------------- | ------ | +| 0 | since | integer | since height, excluded | 1024 | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the blocks, the object in the list is a [Block](#s-block), but **without** transaction details + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockList", + "params": [1024, 1, 10] +} +``` + +Response: [Block](#s-block) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "blocks" [ { TODO: block object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 102, + "pages": 11 + } +} +``` + +### bp_getBlockListByTimeRange + +TODO: as a new API in the next release + +### bp_getBlockByHeight + +Returns information about the block specified by its height. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | height of the block | 1024 | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHeight", + "params": [1] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getBlockByHash + +Returns information about the block specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------- | ------ | +| 0 | hash | string | hash of the block | "TODO" | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHash", + "params": ["TODO"] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getTransactionList + +Returns a list of the transactions. Traverse page by page by using a transaction hash as the mark for paging. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ----- | ------- | -------------------- | ------ | +| 0 | since | string | since hash, excluded | "TODO" | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionList", + "params": ["KhytGjS0xjw5CJvcJYpsNg", 1, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "transactions": [ { TODO: transaction object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 8, + "pages": 1 + } + } +} +``` + +### bp_getTransactionListOfBlock + +Returns a list of the transactions from a block by the specified height. + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | of block height | 1024 | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionListOfBlock", + "params": [1024, 1, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "transactions": [ { TODO: transaction object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 8, + "pages": 1 + } + } +} +``` + +### bp_getTransactionByHash + +Returns information about the transaction specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------------- | ------ | +| 0 | hash | string | hash of the transaction | "TODO" | + +#### Returns + +- object: transaction information object, it's a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionByHash", + "params": ["TODO"] +} +``` + +Response: [Transaction](#s-transaction) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: transaction object + } +} +``` + +## Structure Reference + +Here are some common structure definitions used in the API. + + + +### Block + +The block generated in the CovenantSQL blockchain network. + +| Field | Type | Description | +| --------------- | ------- | ------------------------------------------------------- | +| height | integer | Height of the block | +| hash | string | Hash of the block | +| version | integer | Version number of the block | +| producer | string | Address of the node who generated this block | +| merkle_root | string | Hash of the merkle tree | +| parent | string | Hash of its parent block | +| timestamp | integer | Create time of the block, unix time in nanoseconds | +| timestamp_human | string | Create time of the block, human readable RFC3339 format | +| tx_count | integer | Count of the transactions in this block | + +Sample in JSON format: + +```json +{ + "height": 12, + "hash": "TODO", + "version": 1, + "producer": "4io8u9v9nydaQPXtmqibg8gJbkNFd7DdM47PLWuM7ubzBXZ4At7", + "merkle_root": "TODO", + "parent": "TODO", + "timestamp": "TODO", + "timestamp_human": "TODO", + "tx_count": 1 +} +``` + + + +### Transaction + +| Field | Type | Description | +| --------------- | ------- | ------------------------------------------------------------------------------------------- | +| block_height | integer | Height of the block this transaction belongs to | +| index | integer | Index of the transaction in the block | +| hash | string | Hash of the transaction data | +| block_hash | string | Hash of the block this transaction belongs to | +| type | integer | Type of the transaction | +| address | string | Account address who signed this transaction | +| timestamp | integer | Create time of the transaction, unix time in nanoseconds | +| timestamp_human | string | Create time of the transaction, human readable RFC3339 format | +| raw | string | Raw content of the transaction data, in JSON format | +| tx | object | Concrete transaction object, see supported [transaction types](#transaction-types) for more | + +Sample in JSON format: + +```json +{ + "block_height": 1, + "index": 0, + "hash": "TODO", + "block_hash": "TODO", + "timestamp": "TODO", + "timestamp_human": "TODO", + "type": 1, + "address": "TODO", + "raw": "TODO", + "tx": { + "field": "TODO" + } +} +``` + +**Supported Transaction Types:** + +- [CreateDatabase](#s-transaction-createdatabase) + +TODO: more types + + + +### Transaction: CreateDatabase + +TODO: more types \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/bck/development-cmd-cql-utils-zh.md b/website/translated_docs/zh-CN/version-0.2.0/bck/development-cmd-cql-utils-zh.md new file mode 100644 index 0000000..fa97a30 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/bck/development-cmd-cql-utils-zh.md @@ -0,0 +1,41 @@ +--- +id: version-0.2.0-keygen +title: 使用 cql-utils 生成密钥与钱包 +original_id: keygen +--- +`cql-utils` 是 CovenantSQL 的一个命令行工具，具体用法如下。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 使用 + +### 生成公私钥对 + + $ cql-utils -tool keygen + Enter master key(press Enter for default: ""): + ⏎ + Private key file: private.key + Public key's hex: 03bc9e90e3301a2f5ae52bfa1f9e033cde81b6b6e7188b11831562bf5847bff4c0 + + +生成的 private.key 文件即是使用主密码加密过的私钥文件，而输出到屏幕上的字符串就是使用十六进制进行编码的公钥。 + +### 使用私钥文件或公钥生成钱包地址 + + $ cql-utils -tool addrgen -private private.key + Enter master key(default: ""): + ⏎ + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + $ cql-utils -tool addrgen -public 02f2707c1c6955a9019cd9d02ade37b931fbfa286a1163dfc1de965ec01a5c4ff8 + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + + +你可以通过指定私钥文件，或者把上述的公钥十六进制编码字符串作为命令行参数来直接生成钱包地址。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/bck/development-cmd-cql-zh.md b/website/translated_docs/zh-CN/version-0.2.0/bck/development-cmd-cql-zh.md new file mode 100644 index 0000000..d06e552 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/bck/development-cmd-cql-zh.md @@ -0,0 +1,77 @@ +--- +id: version-0.2.0-cql +title: 使用命令行客户端 cql 创建数据库 +original_id: cql +--- +本文档主要介绍 CovenantSQL 命令行客户端 `cql` 的使用。`cql` 是一个用于批量进行 SQLChain 上数据库的创建、查询、更新或删除操作的命令行工具。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 生成默认配置文件 + +首先需要一个 config 文件和由你输入的主密码（master key）来初始化，其中主密码用来加密解密本地密钥对。使用 `cql-utils` 工具进行配置文件生成后，你可以在生成的配置文件目录下找到密钥文件。 + +具体请参考: [cql-utils 使用文档](https://github.com/CovenantSQL/docs/tree/master/development-cmd-utils-zh.md#使用) 中配置文件及钱包地址生成相关章节。 + +## 检查钱包余额 + +使用 `cql` 命令来检查钱包余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] +### Public Key ### +0388954cf083bb6bb2b9c7248849b57c76326296fcc0d69764fc61eedb5b8d820c +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +这里我们得到结果 **"stable coin balance is: 100"**。 + +## 初始化一个 CovenantSQL 数据库 + +准备好配置文件和主密码后就可以使用 `cql` 命令来创建数据库了，你的数据库 ID 将会输出到屏幕上： + +```bash +# if a non-default password applied on master key, use `-password` to pass it +$ cql -config conf/config.yaml -create 1 +INFO[0000] +### Public Key ### +039bc931161383c994ab9b81e95ddc1494b0efeb1cb735bb91e1043a1d6b98ebfd +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] the newly created database is: covenantsql://0e9103318821b027f35b96c4fd5562683543276b72c488966d616bfe0fe4d213 caller="main.go:297 main.main" +``` + +这里 `-create 1` 表示创建一个单节点的 SQLChain。 + +```bash +$ cql -config conf/config.yaml -dsn covenantsql://address +``` + +`address` 就是你的数据库 ID。 + +`cql` 命令的详细使用帮助如下： + +```bash +$ cql -help +``` + +## 使用 `cql` + +现在可以使用 `cql` 进行数据库操作了: + +```bash +co:address=> show tables; +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/bck/development-golang-client-zh.md b/website/translated_docs/zh-CN/version-0.2.0/bck/development-golang-client-zh.md new file mode 100644 index 0000000..0fd9b7a --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/bck/development-golang-client-zh.md @@ -0,0 +1,108 @@ +--- +id: version-0.2.0-golang-client +title: 使用 Golang 驱动访问数据库 +original_id: golang-client +--- +本文档介绍 CovenantSQL 客户端的使用方式。客户端用来创建、查询、更新和删除 SQLChain 以及绑定的数据库。 + +## 开始之前 + +确保 `$GOPATH/bin` 目录在环境变量 `$PATH` 中，执行以下命令 + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +然后在你的 go 代码中 import 第一个 `client` 包。 + +## 初始化一个 CovenantSQL 客户端 + +首先需要一个 config 文件和 master key 来初始化。master key 用来加密解密本地密钥对。以下是如何用一个自定义 master key 来生成默认的 config 文件： + +### 生成默认的配置文件 + +运行以下 `cql-utils` 命令，输入 master key（类似密码）来生成本地密钥对。等待几十秒，会在 `conf` 文件夹中，生成一个私钥文件和一个名为 `config.yaml` 的配置文件。 + +```bash +$ cql-utils -tool confgen -root conf +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: conf/private.key +Public key's hex: 025abec9b0072615170f4acf4a2fa1162a13864bb66bc3f140b29f6bf50ceafc75 +Generated key pair. +Generating nonce... +INFO[0005] cpu: 1 +INFO[0005] position: 0, shift: 0x0, i: 0 +nonce: {{1450338416 0 0 0} 26 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514} +node id: 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514 +Generated nonce. +Generating config file... +Generated nonce. +``` + +有了配置文件之后，可以通过以下 go 代码来初始化 CovenantSQL 客户端： + +```go +client.Init(configFile, masterKey) +``` + +## 客户端使用方式 + +### 创建一个 SQLChain 数据库 + +创建 SQLChain 数据库需要指明需要几个节点（nodeCount变量）: + +```go +var ( + dsn string + meta client.ResourceMeta +) +meta.Node = uint16(nodeCount) +dsn, err = client.Create(meta) +// process err +``` + +创建完毕会返回一个 dsn 字符串，用来访问这个数据库。 + +### 查询和执行 + +拿到 dsn 字符串后，可以通过以下代码在 SQLChain 中执行 SQL 语句： + +```go +
db, err := sql.Open("covenantsql", dsn) + // process err + + _, err = db.Exec("CREATE TABLE testSimple ( column int );") + // process err + + _, err = db.Exec("INSERT INTO testSimple VALUES(?);", 42) + // process err + + row := db.QueryRow("SELECT column FROM testSimple LIMIT 1;") + + var result int + err = row.Scan(&result) + // process err + fmt.Printf("SELECT column FROM testSimple LIMIT 1; result %d\n", result) + + err = db.Close() + // process err + +``` + +用法和其他 go sql driver 一致。 + +### 删除数据库 + +使用 dsn 来删除数据库： + +```go + err = client.Drop(dsn) + // process err +``` + +### 完整示例 + +在以下目录中有一个简单示例和复杂示例可以参考 [示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/bck/getting-started-overview-zh.md b/website/translated_docs/zh-CN/version-0.2.0/bck/getting-started-overview-zh.md new file mode 100644 index 0000000..eb66866 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/bck/getting-started-overview-zh.md @@ -0,0 +1,63 @@ +--- +id: version-0.2.0-intro +title: 简介 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +- **SQL**: 支持 SQL-92 标准 +- **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +- **隐私**: 通过加密和授权许可进行访问 +- **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信[在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +#### 一行代码接入区块链数据 + +```go +sql.Open("CovenantSQL", dbURI) +``` + +# # + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +- 第一层: **全局共识层**(主链，架构图中的中间环): + - 整个网络中只有一个主链。 + - 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +- 第二层: **SQL 共识层**(子链，架构图中的两边环): + - 每个数据库都有自己独立的子链。 + - 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +- 第三层: **数据储存层**(支持 SQL-92 的数据库引擎): + - 每个数据库都有自己独立的分布式引擎。 + - 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/bck/getting-started-testnet-zh.md b/website/translated_docs/zh-CN/version-0.2.0/bck/getting-started-testnet-zh.md new file mode 100644 index 0000000..f7c9caf --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/bck/getting-started-testnet-zh.md @@ -0,0 +1,93 @@ +--- +id: version-0.2.0-testnet +title: CovenantSQL 测试网快速入门 +original_id: testnet +--- +[CovenantSQL](https://github.com/CovenantSQL/CovenantSQL/blob/develop/README-zh.md) 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +1. **SQL**: 支持 SQL-92 标准 +2. **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +3. **隐私**: 通过加密和授权许可进行访问 +4. **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## 0. 下载 CovenantSQL 工具 + +在 [github](https://github.com/CovenantSQL/CovenantSQL/releases) 下载最新的发行版 + +## 1. 用 `cql-utils` 生成配置文件访问测试网 + +```bash +$ cql-utils -tool confgen +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: conf/private.key +Public key's hex: 02296ea73240dcd69d2b3f1fb754c8debdf68c62147488abb10165428667ec8cbd +Generated key pair. +Generating nonce... +nonce: {{731613648 0 0 0} 11 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9} +node id: 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9 +Generated nonce. +Generating config file... +Generated nonce. +``` + +运行完成后，`cql-utils`会在 `./conf` 目录生成一个配置文件。 + +## 2. 用私钥生成钱包地址 + +私钥可以再上一步的 `./conf` 目录中找到，文件名为 `private.key` + +```bash +$ cql-utils -tool addrgen -private ./conf/private.key +Enter master key(default: ""): +⏎ +wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 +``` + +上述 `4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9` 就是钱包地址 + +## 3. 在水龙头(Faucet)获取 Particle(PTC) + +水龙头(Faucet)的地址为: [CovenantSQL 测试网 Particle(PTC) 水龙头](https://testnet.covenantsql.io/)。 + +完成教程之后，用 `cql` 命令来检查钱包地址的余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +当看到 **"stable coin balance is: 100"** 时，表明余额已经为 100。 + +如果您需要更多的 PTC 作为长期测试使用，请联系 。 + +对于有合作的商业伙伴，我们将直接提供 PTC 以供使用。 + +## 4. 使用 `CLI` 创建数据库 + +```bash +$ cql -config conf/config.yaml -create 1 +INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" +``` + +第一行命令中的 `1` 表示申请几个矿工为你的数据库服务。`covenantsql://...` 开头的这个字符串就是创建的数据库访问地址，在 SDK 和 CLI 命令中都需要用此地址，在整个区块链中找到这个数据库。 + +## 5. CLI 和 SDK 的详细文档 + +创建好数据库后，您可以参考以下文档和示例，以便更快的使用CovenantSQL来开发应用。 + +- [CLI 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql/README-zh.md) +- [SDK 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/README-zh.md) +- [SDK 示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) + +## 6. SQLChain 浏览器 + +目前，测试网的数据库时不需要权限的。意味着您可以通过数据库的DSN(数据库访问地址)，在[SQLChain 浏览器](https://explorer.dbhub.org)中拿到所有的修改历史和区块信息。 + +更多的测试网技术支持，请访问: + +> [TestNet 发行日志](https://github.com/CovenantSQL/CovenantSQL/wiki/Release-Notes-zh) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/bck/getting-started-zh.md b/website/translated_docs/zh-CN/version-0.2.0/bck/getting-started-zh.md new file mode 100644 index 0000000..d6e2e01 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/bck/getting-started-zh.md @@ -0,0 +1,486 @@ +--- +id: version-0.2.0-local-deployment +title: CovenantSQL 综述 +original_id: local-deployment +--- +# CovenantSQL 介绍 + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可变成 ĐApp +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是用户的钱包，那么 CovenantSQL 就是是用户的去中心化数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密 保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 + +# 安装 CovenantSQL 客户端 + +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +* [Go](./development-golang-client-zh.md) +* [Java](https://github.com/CovenantSQL/covenant-connector) +* [Python](https://github.com/CovenantSQL/python-driver) +* [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +* `conf/private.key`: 为您生成的私钥通过主密码加密保存在该文件中，您的账号地址需要使用该文件创建； +* `conf/config.yaml`: 为您生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +* [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 + +# 部署 CovenantSQL + +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 启动 Docker 容器 + +执行以下的命令在本地运行 CovenantSQL + +```shell +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +make docker +make start +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行`export COVENANTSQL_ROOT=$PWD`存为环境变量 + +### 检查运行状态 + +```shell +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_adapter ./docker-entry.sh Up 0.0.0.0:11105->4661/tcp +covenantsql_bp_0 ./docker-entry.sh Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 ./docker-entry.sh Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 ./docker-entry.sh Up 0.0.0.0:11101->4661/tcp +covenantsql_explorer /bin/sh -c MAGIC_DOLLAR='$ ... Up 0.0.0.0:11108->80/tcp +covenantsql_miner_0 ./docker-entry.sh Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 ./docker-entry.sh Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 ./docker-entry.sh Up 0.0.0.0:11104->4661/tcp +covenantsql_mysql_adapter ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11106->4663/tcp +``` + +### SQLChain Explorer + +我们在`:11108`端口提供了一个 SQLChain 的 Explorer 可以看到 SQL 语句在链上的情况 + +# 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +cql -config config/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +cql -config config/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +cql -config config/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +# 使用 CovenantSQL 开发 App + +## Golang 使用 CovenantSQL + +#### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +#### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +#### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +#### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +#### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` + +# CovenantSQL API + +# 常见问题解答 + +补充 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/bck/guide-zh.md b/website/translated_docs/zh-CN/version-0.2.0/bck/guide-zh.md new file mode 100644 index 0000000..659ef89 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/bck/guide-zh.md @@ -0,0 +1,114 @@ +--- +id: version-0.2.0-guide-zh +title: 快速开始 +original_id: guide-zh +--- +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +- [Go](./development-golang-client-zh.md) +- [Java](https://github.com/CovenantSQL/covenant-connector) +- [Python](https://github.com/CovenantSQL/python-driver) +- [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +- `conf/private.key`: 为您生成的私钥通过主密码加密保存在该文件中，您的账号地址需要使用该文件创建； +- `conf/config.yaml`: 为您生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +- [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/cql.md b/website/translated_docs/zh-CN/version-0.2.0/cql.md new file mode 100644 index 0000000..b46e6d4 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/cql.md @@ -0,0 +1,144 @@ +--- +id: version-0.2.0-cql +title: '🖥️ CQL 命令行工具' +original_id: cql +--- +## 简介 + +本文将介绍如何使用 `cql` 进行查询、转账和数据库权限管理。在使用 `cql` 前请先确认已接入 [CovenantSQL TestNet](quickstart) 或者在本地使用 [Docker 一键部署](development)的网络。 + +## 查询余额 + +查询余额有两个命令：`cql -get-balance` 和 `cql -token-balance `。其中 `-get-balance` 将返回用户账户中 `Particle` 与 `Wave` 的数量，`-token-balance ` 将返回用户账户中特定 `token_type` 的 token 数量。目前系统支持的 `token_type` 有： + +- `Particle` +- `Wave` +- `Bitcoin` +- `Ether` +- `EOS` + +查看默认余额： + +```bash +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] Particle balance is: 10000000000000000000 + INFO[0000] Wave balance is: 10000000000000000000 + + +查看 Particle 余额： + +```bash +./cql -config conf/config.yaml -token-balance Particle +``` + +输出： + + INFO[0000] Particle balance is: 10000000000000000000 + + +查看 Bitcoin 余额： + +```bash +./cql -config conf/config.yaml -token-balance Bitcoin +``` + +输出： + + INFO[0000] Bitcoin balance is: 0 + + +## 转账 + +转账操作使用 `cql -transfer` 并以 `json` 格式的转账信息为参数。 + +```json +{ + "addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // 收款地址 + "amount":"1000000 Particle" // 转账金额并带上单位 +} +``` + +其中收款地址可以是一个个人钱包地址也可以是一个数据库子链地址。转账至数据库地址时将在该数据库账户上补充付款人的押金与预付款。 + +转账 Particle： + +```bash +./cql -config conf/config.yaml -transfer '{"addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount":"1000000 Particle"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +转账 Wave： + +```bash +./cql -config conf/config.yaml -transfer '{"addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount":"1000000 Wave"}' +``` + + INFO[0000] succeed in sending transaction to CovenantSQL + + +查看余额： + +```bash +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] Particle balance is: 9999999999999000000 + INFO[0000] Wave balance is: 9999999999999000000 + + +注意，`succeed in sending transaction to CovenantSQL` 只说明交易已成功发送至主网，交易能否成功、何时成功需要通过 `-get-balance` 或者 `-token-balance ` 确定。 + +## 数据库权限管理 + +CovenantSQL 数据库有三类库级别权限： + +- `Admin` +- `Write` +- `Read` +- `Void` + +其中，`Admin` 可以赋予其他钱包地址数据库的权限（`Admin`、`Write` 或 `Read`）；`Admin` 和 `Write` 可以对数据库进行写操作（`CREATE`, `INSERT` 等）；`Admin`, `Write` 和 `Read` 可以对数据库进行读操作（`SHOW`, `SELECT` 等）；`Void` 是一个特殊的权限，当 `Admin` 想取消某个地址的权限时可以将该地址的权限设置为 `Void`，这样该地址将无法继续读写数据库。创建数据库的地址的权限默认为 `Admin`。若 `Admin` 需要赋予他人权限请使用 `cql -update-perm` 并以 `json` 格式的权限信息为参数： + +```json +{ + "chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", // 需要进行权限变更的数据库地址 + "user":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // 需要赋予权限的钱包地址 + "perm":"Write" // 权限内容 +} +``` + +增加写权限： + +```bash +./cql -config conf/config.yaml -update-perm '{"chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","user":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","perm":"Write"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +吊销权限： + +```bash +./cql -config conf/config.yaml -update-perm '{"chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","perm":"Void"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +注意，`succeed in sending transaction to CovenantSQL` 只说明交易已成功发送至主网，交易成功与否请通过查询数据库确认。 + +为数据库添加新的账户权限后账户需补充押金与预付款才能进行正常查询。押金与预付款最小值的计算公式：`gas_price*number_of_miner*120000`。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/deployment.md b/website/translated_docs/zh-CN/version-0.2.0/deployment.md new file mode 100644 index 0000000..7cb985e --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/deployment.md @@ -0,0 +1,198 @@ +--- +id: version-0.2.0-deployment +title: '🐳 Docker 一键部署' +original_id: deployment +--- +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 下载项目 + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行 + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +存为环境变量 + +### 启动 Docker 容器 + +现在有两种方式启动 CovenantSQL 容器： + +1. 使用 Docker Hub 上的公共镜像 +2. 构建 CovenantSQL Docker 镜像 + +> 我们推荐普通用户使用第一种方式测试 CovenantSQL，第二种仅用于体验最新的开发中的特性。 + +#### 1. 使用 Docker Hub 上的公共镜像 + +然后直接启动： + +```bash +make start +``` + +#### 2. 构建 CovenantSQL Docker 镜像 + +执行以下的命令在本地运行 CovenantSQL + +```bash +make docker # 从头编译新的镜像 +make start +``` + +### 检查运行状态 + +检查容器状态： + +```bash +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_adapter ./docker-entry.sh Up 0.0.0.0:11105->4661/tcp +covenantsql_bp_0 ./docker-entry.sh Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 ./docker-entry.sh Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 ./docker-entry.sh Up 0.0.0.0:11101->4661/tcp +covenantsql_explorer /bin/sh -c MAGIC_DOLLAR='$ ... Up 0.0.0.0:11108->80/tcp +covenantsql_miner_0 ./docker-entry.sh Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 ./docker-entry.sh Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 ./docker-entry.sh Up 0.0.0.0:11104->4661/tcp +covenantsql_mysql_adapter ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11106->4663/tcp +``` + +## 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +### SQLChain Explorer + +由于读数据库需要计费，并且数据库有权限限制，在启动 Explorer 前需要确保 Explorer 使用的钱包地址内有充足的 token 并且已使用管理员账户为 Explorer 地址授权读权限。（关于权限管理的详细说明请参考[数据库权限管理](cql.md#数据库权限管理)） + +**注意：**在授权前不要在浏览器打开 Explorer 地址。 + +获得转账地址： + +```bash +docker exec -it covenantsql_observer /app/cql-utils -tool addrgen -private /app/node_observer/private.key +``` + +输出： + +```bash +Enter master key(press Enter for default: ""): + +wallet address: 6304a1bcc4a8903b1bc8675fd37a588040a55ade1f1df552ef7721a823ae1c25 +``` + +转账： + +```bash +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -transfer '{"addr":"6304a1bcc4a8903b1bc8675fd37a588040a55ade1f1df552ef7721a823ae1c25","amount":"100000000 Particle"}' +``` + +其中，`addr` 表示转账地址，这里为 Explorer 使用的钱包地址，Explorer 地址可以在上一步中获得。`amount` 为能使 Explorer 运行的最小金额 `gas_price*number_of_miner*240000`，建议多一转些方便后续操作。 + +授权： + +```bash +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -update-perm '{"chain":"139f71bb7b2775baafa42bd9ed2ade6755381d4eed1e02d4847eb1491847a0ce","user":"6304a1bcc4a8903b1bc8675fd37a588040a55ade1f1df552ef7721a823ae1c25","perm":"Read"}' +``` + +充值： + +```bash +docker exec -it covenantsql_observer /app/cql -config /app/node_observer/config.yaml -transfer '{"addr":"139f71bb7b2775baafa42bd9ed2ade6755381d4eed1e02d4847eb1491847a0ce","amount":"90000000 Particle"}' +``` + +关于转账充值与授权的详细说明请参考[文档](cql.md)。 + +### 在浏览器使用 SQLChain Explorer + +我们在 `127.0.0.1:11108` 端口提供了一个 SQLChain 的 Explorer 可以看到 SQL 语句在链上的情况。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/development.md b/website/translated_docs/zh-CN/version-0.2.0/development.md new file mode 100644 index 0000000..ecad5dd --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/development.md @@ -0,0 +1,173 @@ +--- +id: version-0.2.0-development +title: '📦 CovenantSQL SDK' +original_id: development +--- +## Golang 使用 CovenantSQL + +### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/intro.md b/website/translated_docs/zh-CN/version-0.2.0/intro.md new file mode 100644 index 0000000..7fd16c7 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/intro.md @@ -0,0 +1,73 @@ +--- +id: version-0.2.0-intro +title: CovenantSQL 介绍 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可数据上链 +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是人们的私人钱包，那么 CovenantSQL 就是是人们的去中心化的私密数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密来保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/nav.md b/website/translated_docs/zh-CN/version-0.2.0/nav.md new file mode 100644 index 0000000..f94a14a --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/nav.md @@ -0,0 +1,22 @@ +--- +id: version-0.2.0-nav +title: '📖 使用导航' +original_id: nav +--- +## 直接使用测试网 + +[🌏 TestNet 快速开始](./quickstart) + +## 部署私有 CovenantSQL 数据库（搭建私有链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +[🐳 Docker 一键部署](./deployment) + +## 使用 CovenantSQL 开发应用 + +[📦 CovenantSQL SDK](./development) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/qna.md b/website/translated_docs/zh-CN/version-0.2.0/qna.md new file mode 100644 index 0000000..f07b2ca --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/qna.md @@ -0,0 +1,6 @@ +--- +id: version-0.2.0-qna +title: '🙋 常见问题解答' +original_id: qna +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/quandl.md b/website/translated_docs/zh-CN/version-0.2.0/quandl.md new file mode 100644 index 0000000..5363f5f --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/quandl.md @@ -0,0 +1,228 @@ +--- +id: version-0.2.0-quandl +title: 基于 Quandl 的金融数据分析 +original_id: quandl +--- +## 关于Quandl + +Quandl 是一个针对金融投资行业的大数据平台，其数据来源包括联合国、世界银行、中央银行等公开数据，核心财务数据来自 CLS 集团，Zacks 和 ICE 等，所有的数据源自 500 多家发布商， 是为投资专业人士提供金融，经济和替代数据的首选平台，拥有海量的经济和金融数据。 + +## Quandl 数据索引 + +### CovenantSQL 使用简介 + +首先，我们已基于 Quandl 的开放 API 将数据存放在 CovenantSQL 中，首先应该浏览一下 CovenantSQL 的使用介绍来熟悉一下如何连接并且使用 CovenantSQL。 + +现在由于客户端兼容问题， 请直接使用我们的 HTTP 服务来对 Quandl 数据库进行 query，未来兼容现在的 `cql` 客户端后会第一时间更新此文档。 + +具体通过 HTTP 服务来使用 CovenantSQL 请参考 [Python 驱动文档](https://github.com/CovenantSQL/python-driver/blob/master/README.rst) 和 [NodeJS 驱动文档](https://github.com/CovenantSQL/node-covenantsql/blob/master/README.md) + +所需参数: + + host: 'e.morenodes.com' + port: 11108 + database: '057e55460f501ad071383c95f691293f2f0a7895988e22593669ceeb52a6452a' + + +### 数据使用方法 + +Quandl 数据分为表以及子表两层索引 + +数据库中，表名为`quandl_` + `database_code`为完整表名 + +通过查询表名来查看表的内容 + +具体使用时，需要结合`quandl_updateindex` 这张索引表来使用，（查询索引表时，请务必limit小于10万，因为全表数据量过大） + +使用时，请使用where语句限定`quandlcode`字段来查询表中的子表数据。 + +### 查询示例 + +1. 我们想要查询 欧盟委员会年度宏观经济数据库 的数据，我们找到其第一层索引的 `databasecode` 为`quandl_ameco`，于是，我们可以查询其第二层索引，用以下SQL命令行： + + select * from quandl_updateindex where databasecode like 'ameco' group by quandlcode limit 10000 + +2. 然后通过第三列，我们可以查看`quandlcode`对应的描述 + + 比如 AMECO/ALB_1_0_0_0_AAGE 对应的就是阿尔巴尼亚的进出口相关信息，时间从1960到1988。 + + Average share of imports and exports of goods in world trade excluding intra EU trade; Foreign trade statistics (1960-1998 Former EU-15) - Albania + + 于是，我们可以用以下方式把这个子表给查询出来 + + select * from quandl_ameco where quandlcode like 'AMECO/ALB_1_0_0_0_AAGE' limit 10000 + +3. 注意：如果内容整列为null的，属于表结构本身不存在的字段，可以自行去除。 + +## 附件表 + +| database_code | description | | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | +| BUNDESBANK | Data on the German economy, money and capital markets, public finances, banking, households, Euro-area aggregates, trade and external debt. | 德意志联邦银行数据仓库 | +| URC | Advance and decline data for the NYSE, AMEX, and NASDAQ stock exchanges. From various publicly-available sources and the median value is reported. | 独角兽研究公司数据 | +| DCE | Agriculture and commodities futures from DCE, with history spanning almost a decade for select futures. | 大连商品交易所数据 | +| WFC | This database offers mortgage purchase and refinance rates from Wells Fargo Home Mortgage, a division of Wells Fargo Bank. | 富国银行住房抵押贷款数据 | +| USDAFNS | Food and Nutrition Service administrates federal nutrition assistance programs for low-income households and children. Data on costs and participation rates. | 美国农业部食品与营养服务项目数据 | +| LJUBSE | This database contains the Ljubljana Stock Exchange indexes and is based in Ljubljana, Slovenia. | 卢布尔雅那证券交易所数据 | +| TOCOM | Agriculture and commodities futures from Tokyo Commodities Exchange (TOCOM), with history spanning almost a decade for select futures. | 东京商品交易所数据 | +| LBMA | An international trade association in the London gold and silver market, consisting of central banks, private investors, producers, refiners, and other agents. | 伦敦金银市场协会数据 | +| WCSC | This database is designed to provide a strategic overview of the World Bank Group’s performance toward ending extreme poverty and promoting shared prosperity. | 世界银行企业积分卡数据 | +| CMHC | The CMHC is a gov’t-owned corporation that provides affordable housing to Canadian citizens and collects data such as prices, construction, and supply. | 加拿大住房抵押贷款公司 | +| WGEC | Data containing commodity prices and indices from 1960 to present. | 世界银行全球经济监测商品数据（GEM） | +| FED | Official US figures on money supply, interest rates, mortgages, government finances, bank assets and debt, exchange rates, industrial production. | 美联储数据公布 | +| WPSD | Data jointly developed by the World Bank and the International Monetary Fund, which brings together detailed public sector government debt data. | 世界银行公共部分支出数据 | +| UGID | This database offers a wide range of global indicators, covering population, public health, employment, trade, education, inflation and external debt. | 联合国全球指标 | +| RBA | Central bank and monetary authority, regulates banking industry, sets interest rates, and services government's debt. Data on key economic indicators. | 澳大利亚储备银行数据 | +| UCOM | This database offers comprehensive global data on imports and exports of commodities such as food, live animals, pharmaceuticals, metals, fuels and machinery. | 联合国商品贸易数据 | +| SIDC | The SIDC hosts data spanning from the 1700's on solar activity, specifically sunspot activity. | 太阳影响数据分析中心数据 | +| ZCE | Agriculture and commodities futures from ZCE, with history spanning almost a decade for select futures. | 郑州商品交易所数据 | +| ZILLOW2 | Home prices and rents by size, type and tier; housing supply, demand and sales; sliced by zip code, neighbourhood, city, metro area, county and state. | Zillow房地产研究 | +| USTREASURY | The U.S. Treasury ensures the nation's financial security, manages the nation's debt, collects tax revenues, and issues currency, provides data on yield rates. | 美国财政部数据 | +| BTS | BTS provides information on transportation systems in the United States. Their non-multimodal department provides statistics on air travel. | 美国交通运输统计局数据 | +| USDAFAS | The USDA Foreign Agricultural Service connects U.S. agriculture with the world markets. It provides statistics on production and exports in foreign countries. | 美国农业部外国农业服务数据（FAS） | +| OECD | International organization of developed countries that promotes economic welfare. Collects data from members and others to make policy recommendations. | 世界经济合作与发展组织数据 | +| OPEC | International organization and economic cartel overseeing policies of oil-producers, such as Iraq, Iran, Saudi Arabia, and Venezuela. Data on oil prices. | 欧佩克数据 | +| MCX | India's largest commodity exchange servicing futures trading in metals, energy, and agriculture. World's 3rd largest exchange in contracts and trading volume. | 印度多种商品交易所数据 | +| ECONOMIST | The Big Mac index was invented by The Economist in 1986 as a lighthearted guide to whether currencies are at their “correct” level. It is based on the theory of purchasing-power parity (PPP). | 经济学人 - 巨无霸指数 | +| NSDL | Depository in India responsible for economic development of the country that has established a national infrastructure of international standards that handles most of the securities held and settled in dematerialised form in the Indian capital market. | 国家证券存管有限公司（印度）数据 | +| FRED | Growth, employment, inflation, labor, manufacturing and other US economic statistics from the research department of the Federal Reserve Bank of St. Louis. | 美联储经济数据 | +| GDT | | 全球乳品贸易数据 | +| CFFEX | Index and bond futures from CFFEX, with history spanning almost a decade for select futures. | 中国金融期货交易所数据 | +| CITYPOP | Thomas Brinkhoff provides population data for cities and administrative areas in most countries. | Thomas Brinkhoff的城市人口数据 | +| BCHARTS | Exchange rates for bitcoin against a large number of currencies, from all major bitcoin exchanges, including current and historical exchange rates. | 比特币图表汇率数据 | +| LOCALBTC | | Local Bitcoins数据 | +| JODI | JODI oil and gas data comes from over 100 countries consisting of multiple energy products and flows in various methods of measurement. | JODI石油世界数据库 | +| UENG | This database offers comprehensive global statistics on production, trade, conversion, and final consumption of new and renewable energy sources. | 联合国能源统计数据 | +| ULMI | This database offers comprehensive youth unemployment figures broken up by gender for all countries in the world. | 联合国劳工市场指标 | +| MAURITIUSSE | Stock Exchange of Mauritius indices data. | 毛里求斯证券交易所数据 | +| UKRSE | UKRSE presents the most current available data related to the largest stock exchanges in Ukraine. The exchange is located in Kiev and accounts for roughly three-quarters of Ukraine's total equity trading volume | 乌克兰交易所数据 | +| BITSTAMP | Bitstamp is a trading platform for Bitcoin. | Bitstamp数据 | +| UNAE | This database offers global data on gross domestic product, gross national income, and gross value added by different sectors for all countries in the world. | 联合国国民账户估算数据 | +| UNAC | This database offers global data on national accounts, such as assets and liabilities of households, corporations and governments. | 联合国国民账户官方国家数据 | +| UTOR | This database offers comprehensive data on international tourism. Data includes number of tourist arrivals and tourism expenditures for all countries. | 联合国世界旅游业数据 | +| WFE | A trade association of sixty publicly regulated stock, futures, and options exchanges that publishes data for its exchanges, like market capitalization. | 世界交易所联合会数据 | +| FRBC | The Federal Reserve Bank of Cleveland collects data from hundreds of financial institutions, including depository institutions, bank holding companies, and other entities that is used to assess financial institution conditions and also to glean insights into how the economy and financial system are doing. | 克利夫兰联邦储备银行数据 | +| UGEN | This database offers comprehensive global data on a wide range of gender-related indicators, covering demography, health, education and employment. | 联合国性别信息 | +| BITFINEX | Bitfinex is a trading platform for Bitcoin, Litecoin and Darkcoin with many advanced features including margin trading, exchange and peer to peer margin funding. | Bitfinex数据 | +| UGHG | This database offers comprehensive global data on anthropogenic emissions of the six principal greenhouse gases. Data goes back to 1990. | 联合国温室气体清单 | +| UIST | This database offers global data on industrial development indicators, including output, employees, wages, value added for a wide range of industries. | 联合国工业发展组织数据 | +| PRAGUESE | Price index data from the Prague Stock Exchange. | 布拉格证券交易所数据 | +| PFTS | Index data from the PFTS Stock Exchange, the largest marketplace in Ukraine. | PFTS证券交易所（乌克兰）数据 | +| WARSAWSE | WIG20 index has been calculated since April 16, 1994 based on the value of portfolio with shares in 20 major and most liquid companies in the WSE Main List. | 华沙证券交易所数据 | +| TUNISSE | The main reference index of Tunis Stock Exchange. | 突尼斯证券交易所数据 | +| FRKC | FRKC is the regional central bank for the 10th District of the Federal Reserve, publishing data on banking in mostly agricultural transactions. | 堪萨斯城联邦储备银行数据 | +| UENV | This database offers global data on water and waste related indicators, including fresh water supply and precipitation, and generation and collection of waste. | 联合国环境统计数据 | +| NSE | Stock and index data from the National Stock Exchange of India. | 印度国家证券交易所数据 | +| UFAO | This database offers global food and agricultural data, covering crop production, fertilizer consumption, use of land for agriculture, and livestock. | 联合国粮食和农业数据 | +| TAIFEX | Index and bond futures from TAIFEX, with history spanning over a decade for select futures. | 台湾期货交易所数据 | +| GDAX | GDAX is the world’s most popular place to buy and sell bitcoin. | GDAX（全球数字资产交易所）数据 | +| ARES | ARES protects investors, contributes to development of the real estate securitization product market, and facilitates expansion of the real estate investment market. | 房地产证券化协会数据 | +| SHADOWS | This dataset contains the three major indicators from the Wu-Xia papers which serve to identify the shadow rates on all three major banks. | 影子联邦基金利率模型数据 | +| NAAIM | The NAAIM Exposure Index represents the average exposure to US Equity markets reported by NAAIM members. | 全国积极投资管理者协会头寸指数 | +| CBRT | CBRT is responsible for taking measures to sustain the stability of the financial system in Turkey. | 土耳其共和国中央银行数据 | +| CEGH | No description for this database yet. | 中欧天然气中心数据 | +| FINRA | Financial Industry Regulatory Authority provides short interest data on securities firms and exchange markets. | 美国金融业监管局数据 | +| NASDAQOMX | Over 35,000 global indexes published by NASDAQ OMX including Global Equity, Fixed Income, Dividend, Green, Nordic, Sharia and more. Daily data. | 纳斯达克OMX全球指数数据 | +| EURONEXT | Historical stock data from Euronext, the largest European exchange. | 泛欧证券交易所数据 | +| UICT | This database offers comprehensive global data on information and communication technology, including telephone, cellular and internet usage for all countries. | 联合国信息和通信技术数据 | +| USAID | US Agency for International Development provides a complete historical record of all foreign assistance provided by the United States to the rest of the world. | 美国国际开发署数据 | +| ZAGREBSE | Croatia's only stock exchange. It publishes data on the performance of its stock and bond indexes. | 萨格勒布证券交易所数据 | +| QUITOSE | The indexes of the national Stock Exchange of Ecuador. | 基多证券交易所（厄瓜多尔）数据 | +| ECBCS | Data in this database is derived from harmonized surveys for different sectors of the economies in the European Union (EU) and in the EU applicant countries. | 欧盟委员会商业和消费者调查 | +| PSE | This database describes the distribution of top incomes in a growing number of countries. Numbers are derived using tax data. | 巴黎经济学院数据 | +| MALTASE | The Malta Stock Exchange carries out the role of providing a structure for admission of financial instruments to its recognised lists which may subsequently be traded on a regulated, transparent and orderly market place (secondary market).The main participants in the market are Issuers, Stock Exchange Members (stockbrokers), and the investors in general. | 马耳他证券交易所数据 | +| GPP | No description for this database yet. | 全球石油价格 | +| PPE | No description for this database yet. | 波兰电力交易所（TGE）数据 | +| UKONS | Data on employment, investment, housing, household expenditure, national accounts, and many other socioeconomic indicators in the United Kingdom. | 英国国家统计局数据 | +| NCDEX | A professionally managed on-line multi-commodity exchange in India | 国家商品及衍生品交易所（印度）数据 | +| WSE | No description for this database yet. | 华沙证券交易所（GPW）数据 | +| TFX | The Tokyo Financial Exchange is a futures exchange that primary deals in financial instruments markets that handle securities and market derivatives. | 东京金融交易所数据 | +| WGFD | Data on financial system characteristics, including measures of size, use, access to, efficiency, and stability of financial institutions and markets. | 世界银行全球金融发展数据 | +| CEPEA | CEPEA is an economic research center at the University of Sao Paulo focusing on agribusiness issues, publishing price indices for commodities in Brazil. | 应用经济学应用研究中心（巴西）数据 | +| SBJ | A Japanese government statistical agency that provides statistics related to employment and the labour force. | 日本统计局数据 | +| WGEM | Data on global economic developments, with coverage of high-income, as well as developing countries. | 世界银行全球经济监测 | +| WGDF | Data on financial system characteristics, including measures of size, use, access to, efficiency, and stability of financial institutions and markets. | 世界银行全球发展金融 | +| WWDI | Most current and accurate development indicators, compiled from officially-recognized international sources. | 世界银行世界发展指标 | +| WESV | Company-level private sector data, covering business topics including finance, corruption, infrastructure, crime, competition, and performance measures. | 世界银行企业调查 | +| CHRIS | Continuous contracts for all 600 futures on Quandl. Built on top of raw data from CME, ICE, LIFFE etc. Curated by the Quandl community. 50 years history. | 维基连续期货 | +| WDBU | Data on business regulations and their enforcement for member countries and selected cities at the subnational and regional level. | 世界银行存续商业数据 | +| OSE | The second largest securities exchange in Japan. Unlike the TSE, OSE is strongest in derivatives trading, the majority of futures and options in Japan. | 大阪证券交易所数据 | +| RFSS | The Russian governmental statistical agency that publishes social, economic, and demographic statistics for Russia at the national and local levels. | 俄罗斯联邦统计局数据 | +| EUREX | Index, rate, agriculture and energy futures from EUREX, Europe's largest futures exchange, with history spanning a decade for select futures. | 欧洲期货交易所数据 | +| WMDG | Data drawn from the World Development Indicators, reorganized according to the goals and targets of the Millennium Development Goals (MDGs). | 世界银行千年发展目标数据 | +| ZILLOW | Home prices and rents by size, type and tier; housing supply, demand and sales; sliced by zip code, neighbourhood, city, metro area, county and state. | Zillow房地产研究 | +| WPOV | Indicators on poverty headcount ratio, poverty gap, and number of poor at both international and national poverty lines. | 世界银行贫困统计 | +| EUREKA | A research company focused on hedge funds and other alternative investment funds. It publishes data on the performances of hedge funds. | Eurekahedge数据 | +| MOFJ | Japanese government bond interest rate data, published daily by the Ministry of Finance. | 日本财务省数据 | +| PIKETTY | Data on Income and Wealth from "Capital in the 21st Century", Harvard University Press 2014. | Thomas Piketty数据 | +| PSX | Daily closing stock prices from the Pakistan Stock Exchange. | 巴基斯坦证交所数据 | +| SGX | Asian securities and derivatives exchange that trades in equities for many large Singaporean and other Asian companies. Listed on its own exchange. | 新加坡交易所数据 | +| UIFS | This database offers comprehensive data on international financial indicators, such as average earnings, bond yields, government revenues and expenditures. | 联合国国际金融统计 | +| UINC | This database offers global data on production of industrial commodities, such as ores and minerals, food products, transportable goods, and metal products. | 联合国工业商品数据 | +| INSEE | INSEE is the national statistical agency of France. It collects data on France's economy and society, such as socioeconomic indicators and national accounts. | 国家统计和经济研究所（法国）数据 | +| SNB | Central bank responsible for monetary policy and currency. Data on international accounts, interest rates, money supply, and other macroeconomic indicators. | 瑞士国家银行数据 | +| ODE | A non-profit commodity exchange in the Kansai region of Japan that trades in seven key agricultural commodities. | 大阪道岛商品交易所数据 | +| WGEN | Data describing gender differences in earnings, types of jobs, sectors of work, farmer productivity, and entrepreneurs’ firm sizes and profits. | 世界银行性别统计 | +| WHNP | Key health, nutrition and population statistics. | 世界银行健康营养与人口统计 | +| WIDA | Data on progress on aggregate outcomes for IDA (International Development Association) countries for selected indicators. | 世界银行国际发展协会 | +| ECMCI | Updated monthly, this database provides monetary conditions index values in the Euro zone. History goes back to 1999. | 欧盟委员会货币状况指数 | +| NBSC | Statistics of China relating to finance, industry, trade, agriculture, real estate, and transportation. | 中国国家统计局数据 | +| MAS | No description for this database yet. | 新加坡金融管理局数据 | +| MGEX | A marketplace of futures and options contracts for regional commodities that facilitates trade of agricultural indexes. | 明尼阿波利斯谷物交易所数据 | +| WWGI | Data on aggregate and individual governance indicators for six dimensions of governance. | 世界银行全球治理指标 | +| ISM | ISM promotes supply-chain management practices and publishes data on production and supply chains, new orders, inventories, and capital expenditures. | 供应管理研究所 | +| PERTH | The Perth Mint’s highs, lows and averages of interest rates and commodities prices, updated on a monthly basis. | 珀斯铸币厂数据 | +| UKR | No description for this database yet. | 乌克兰交易所数据 | +| FRBNY | The FRBNY is the largest regional central bank in the US. Sets monetary policy for New York, most of Connecticut and New Jersey, and some territories. | 纽约联邦储备银行数据 | +| FRBP | The FRBP is a regional central bank for the Federal Reserve. It publishes data on business confidence indexes, GDP, consumption, and other economic indicators. | 费城联邦储备银行数据 | +| FMSTREAS | The monthly receipts/outlays and deficit/surplus of the United States of America. | 美国财政部 - 财务管理处数据 | +| EIA | US national and state data on production, consumption and other indicators on all major energy products, such as electricity, coal, natural gas and petroleum. | 美国能源信息管理局数据 | +| SOCSEC | Provides data on the US social security program, particularly demographics of beneficiaries; disabled, elderly, and survivors. | 美国社会保障局数据 | +| TFGRAIN | Cash price of corn and soybeans including basis to front month futures contract. | 顶级飞行谷物合作社数据 | +| IRPR | Puerto Rico Institute of Statistics statistics on manufacturing. | 波多黎各统计研究所数据 | +| BCHAIN | Blockchain is a website that publishes data related to Bitcoin, updated daily. | blockchain.com数据 | +| BITCOINWATCH | Bitcoin mining statistics. | Bitcoin Watch数据 | +| ODA | IMF primary commodity prices and world economic outlook data, published by Open Data for Africa. Excellent cross-country macroeconomic data. | 国际货币基金组织跨国宏观经济统计 | +| WADI | A collection of development indicators on Africa, including national, regional and global estimates. | 世界银行非洲发展指标 | +| WEDU | Internationally comparable indicators on education access, progression, completion, literacy, teachers, population, and expenditures. | 世界银行教育统计 | +| WGLF | Indicators of financial inclusion measures on how people save, borrow, make payments and manage risk. | 世界银行全球Findex（全球金融包容性数据库） | +| WWID | The World Wealth and Income Database aims to provide open and convenient access to the most extensive available database on the historical evolution of the world distribution of income and wealth, both within countries and between countries. | 世界财富和收入数据库 | +| BTER | Historical exchange rate data for crypto currencies. | 比特儿数据 | +| BP | BP is a large energy producer and distributor. It provides data on energy production and consumption in individual countries and larger subregions. | BP能源生产和消费数据 | +| AMFI | This database represents fund information from The Association of Mutual Funds in India. | 印度共同基金协会数据 | +| BOC | Economic, financial and banking data for Canada. Includes interest rates, inflation, national accounts and more. Daily updates. | 加拿大银行统计数据库 | +| BLSE | US national and state-level employment and unemployment statistics, published by the Bureau of Labor Statistics. | 美国劳工统计局就业与失业统计 | +| BLSI | US national and state-level inflation data, published by the Bureau of Labor Statistics. | 美国劳工统计局通货膨胀和价格统计 | +| BITAL | This database provides data on stock future contracts from the Borsa Italiana, now part of London Stock Exchange Group. | 意大利证交所数据 | +| BLSB | US work stoppage statistics, published by the Bureau of Labor Statistics. | 美国劳工统计局薪酬福利统计 | +| ECB | The central bank for the European Union oversees monetary policy and the Euro, and provides data on related macroeconomic variables. | 欧洲中央银行数据 | +| BOJ | | 日本银行数据 | +| BOF | The Banque de France is responsible for monetary policy through policies of the European System of Central Banks and providing data on key economic indictors. | 法国银行数据 | +| LPPM | Price data on the market-clearing level for Palladium and Platinum around the world. | 白金和钯价格数据 | +| JOHNMATT | Current and historical data on platinum group metals such as prices, supply, and demand. | 稀有金属价格数据 | +| NAHB | Housing and economic indices for the United States. | 美国住房指数 | +| RATEINF | Inflation Rates and the Consumer Price Index CPI for Argentina, Australia, Canada, Germany, Euro area, France, Italy, Japan, New Zealand and more. | 通货膨胀率 | +| RENCAP | Data on the IPO market in the United States. | IPO数据 | +| ML | Merrill Lynch, a major U.S. bank, publishes data on yield rates for corporate bonds in different regions. | 公司债券收益率数据 | +| MULTPL | No description for this database yet. | S&P 500 | +| RICI | Composite, USD based, total return index, representing the value of a basket of commodities consumed in the global economy. | 商品指数 | +| AAII | American Association of Individual Investor’s sentiment data. | 投资者情绪 | +| WORLDAL | World Aluminium capacity and production in thousand metric tonnes. | 铝价格 | +| WGC | The World Gold Council is a market development organization for the gold industry. It publishes data on gold prices in different currencies. | 黄金价格 | +| MX | Montreal Exchange is a derivatives exchange that trades in futures contracts and options for equities, indices, currencies, ETFs, energy, and interest rates. | 加拿大期货数据 | +| UMICH | The University of Michigan’s consumer survey - data points for the most recent 6 months are unofficial; they are sourced from articles in the Wall Street Journal. | 消费者情绪 | +| BUCHARESTSE | The Bucharest Stock Exchange publishes data on it activity in equity, rights, bonds, fund units, structured products, and futures contracts. | 布加勒斯特证券交易所数据 | +| BSE | End of day prices, indices, and additional information for companies trading on the Bombay Stock Exchange in India. | 孟买证券交易所数据 | +| CFTC | Weekly Commitment of Traders and Concentration Ratios. Reports for futures positions, as well as futures plus options positions. New and legacy formats. | 商品期货交易委员会报告 | +| ACC | Chemical Activity Barometer (CAB) published by the American Chemistry Council (ACC). The CAB is an economic indicator that helps anticipate peaks and troughs in the overall US economy and highlights potential trends in other industries in the US. | 美国化学理事会数据 | +| AMECO | Annual macro-economic database of the European Commission's Directorate General for Economic and Financial Affairs (DG ECFIN). | 欧盟委员会年度宏观经济数据库 | +| MORTGAGEX | Historical housing data on ARM indexes. | 可调利率抵押贷款指数 | +| BUCHARESTSE | The Bucharest Stock Exchange publishes data on it activity in equity, rights, bonds, fund units, structured products, and futures contracts. | 布加勒斯特证券交易所数据 | +| AMECO | Annual macro-economic database of the European Commission's Directorate General for Economic and Financial Affairs (DG ECFIN). | 欧盟委员会年度宏观经济数据库 | +| ACC | Chemical Activity Barometer (CAB) published by the American Chemistry Council (ACC). The CAB is an economic indicator that helps anticipate peaks and troughs in the overall US economy and highlights potential trends in other industries in the US. | 美国化学理事会数据 | +| ABMI | Indicators of Chinese and Japanese bond markets, such as size and composition, market liquidity, yield returns, and volatility. | 亚洲债券市场计划 | +| BITAL | This database provides data on stock future contracts from the Borsa Italiana, now part of London Stock Exchange Group. | | +| BANKRUSSIA | Primary indicators from the Bank of Russia, including data on the banking sector, money supply, financial markets and macroeconomic statistical data. | 俄罗斯银行数据 | +| FMAC | Data from Freddie Mac’s Primary Mortgage Market Survey and other region specific historical mortgage rates. | 房地美数据 | +| BOC | Economic, financial and banking data for Canada. Includes interest rates, inflation, national accounts and more. Daily updates. | 加拿大银行统计数据库 | +| BSE | End of day prices, indices, and additional information for companies trading on the Bombay Stock Exchange in India. | 孟买证券交易所数据 | \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/quickstart.md b/website/translated_docs/zh-CN/version-0.2.0/quickstart.md new file mode 100644 index 0000000..fffaf95 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/quickstart.md @@ -0,0 +1,148 @@ +--- +id: version-0.2.0-quickstart +title: '🌏 TestNet 快速开始' +original_id: quickstart +--- +## CovenantSQL 工具包 + +### 工具包简介 + +请根据您使用的操作系统平台选择 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。 + +例如，您使用的是： + +- MacOS 平台请下载：[**CovenantSQL-v0.2.0.osx-amd64.tar.gz**](https://github.com/CovenantSQL/CovenantSQL/releases/download/v0.2.0/CovenantSQL-v0.2.0.osx-amd64.tar.gz) +- Linux 平台请下载：[**CovenantSQL-v0.2.0.linux-amd64.tar.gz**](https://github.com/CovenantSQL/CovenantSQL/releases/download/v0.2.0/CovenantSQL-v0.2.0.linux-amd64.tar.gz) +- Windows 平台我们稍后发布，有需求请戳这里：[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/CovenantSQL/CovenantSQL) + +解压之后，你将得到以下命令行工具，包括：`cql`、`cql-utils` 等。 + +| 工具名 | 介绍 | +| ---------- | --------------------------------------------------- | +| cql | CovenantSQL 的客户端，类似 mysql 命令，用于执行 SQL | +| cql-utils | CovenantSQL 工具箱，用于和主链交互 | +| cql-minerd | CovenantSQL 矿工客户端，用于运行数据库赚取奖励，以后会开放加入 | +| cqld | CovenantSQL 主链节点，主要由 CovenantLabs 以及合作伙伴以 DPoS 模式运行 | + +### 测试网快速接入 + +目前，我们已经发布了测试网 v0.2.0，供大家进行原理性验证和体验。你可以选在使用公共的测试账号快速进行接入测试。 + +测试账号的配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) ，或者使用以下命令： + +```bash +mkdir conf +wget https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml -O conf/config.yaml +wget https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key -O conf/private.key +chmod 600 conf/private.key +``` + +**测试网注**： + +> 该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放你的应用信息，我们会不定期清理数据库数据。 +> +> 测试网暂时由 3 个 Miner 组成，所以暂时最大只支持`create 3`创建 3 个节点组成的数据库。 + +## 创建并访问 CovenantSQL 数据库 + +### 创建数据库 + +```shell +./cql -config conf/config.yaml -create 1 +``` + +输出： + + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + + +这里表示你提交了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库的创建请求到主链。 + +> 我们需要等待大概 30s 的时间，等待数据库创建，大致过程为： +> +> 1. 收到请求的 出块节点（Block Producer）进行 Miner 和数据库创建请求的撮合 +> 2. 数据库创建请求在 其它出块节点 进行验证和确认 +> 3. SQLChain 的符合条件的 Miner 收到数据库任务 +> 4. SQLChian 组建 Kayak 数据库集群 +> 5. 所有 Miner 准备就绪等待请求 + +### 访问数据库 + +```shell +./cql -config conf/config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，你可以按你操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 数据库SDK + +- [Golang开发指引](./development) + +## SQLChain区块浏览器 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，你可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。 + +> 测试网的`区块浏览器`目前是开放权限的，所以任何知道数据库 ID 的人都能看到您的数据 + +查询时，请在其页面右上角填入你的数据库 ID。例如：`0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` + +## 创建账号 + +我们的测试网支持你创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（会询问设置主密码，测试期间建议直接回车留空）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: conf/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你创建一个 `conf` 目录： + +- `conf/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `conf/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private conf/private.key +``` + +输出： + +```toml +wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 +``` + +你可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入你生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为你的钱包充值。有任何问题请来这里讨论：[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/CovenantSQL/CovenantSQL) + +使用 cql 命令行工具查询余额： + +```shell +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +恭喜，你已收到我们发出的 PTC 稳定币，现在即可开始使用 CovenantSQL， 你可以参考 [Golang 使用 CovenantSQL 文档](./development) 进行开发。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.2.0/usecase.md b/website/translated_docs/zh-CN/version-0.2.0/usecase.md new file mode 100644 index 0000000..690cf7e --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.2.0/usecase.md @@ -0,0 +1,6 @@ +--- +id: version-0.2.0-usecase +title: 使用案例 +original_id: usecase +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/api.md b/website/translated_docs/zh-CN/version-0.3.0/api.md new file mode 100644 index 0000000..05cbbd9 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/api.md @@ -0,0 +1,6 @@ +--- +id: version-0.3.0-api +title: '👩🏻‍💻 CovenantSQL API' +original_id: api +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/bck/api-json-rpc.md b/website/translated_docs/zh-CN/version-0.3.0/bck/api-json-rpc.md new file mode 100644 index 0000000..105a705 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/bck/api-json-rpc.md @@ -0,0 +1,442 @@ +--- +id: version-0.3.0-api-json-rpc +title: JSON RPC +original_id: api-json-rpc +--- +> JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. + +CovenantSQL provides a suite of RPC methods in [JSON-RPC 2.0](https://www.jsonrpc.org/specification) for easily accessing to CovenantSQL networks. + +## Javascript API + +[cql.js](https://github.com/covenantsql/cql.js) is a Javascript SDK which has encapsulated the RPC methods in order to give a much more convenient way to talk to the CovenantSQL networks. See the [Javascript API](cql-js.md) for more. + +## JSON RPC Endpoint + +| Network | Provider | URL | +| ------------------------ | ------------- | -------------------------------------- | +| CovenantSQL Test Network | Covenant Labs | https://jsonrpc.testnet.covenantsql.io | +| CovenantSQL Main Network | Covenant Labs | Comming soon :) | + +## JSON RPC API Reference + +### bp_getProtocolVersion + +Returns the current CovenantSQL protocol version. + +#### Parameters + +None. + +#### Returns + +- string - the current CovenantSQL protocol version + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "method": "bp_getProtocolVersion", + "params": [], + "id": 1 +} +``` + +Response: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0.1.0" +} +``` + +### bp_getRunningStatus + +Returns some basic indicators describing the running status of the CovenantSQL network. + +#### Parameters + +None. + +#### Returns + +- object: an object describes the running status of the network. + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getRunningStatus", + "params": [] +} +``` + +Response: + +```js +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "block_height": 182414, // height of the latest block + "count_accounts": 103, // count of the accounts ever created + "count_shardchains": 912414, // count of the databases ever created + "qps": 10241 // estimated QPS of database operations of the whole net + "storage_size": 109870095269 // storage size + } +} +``` + +### bp_getBlockList + +Returns a list of the blocks. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ----- | ------- | ---------------------- | ------ | +| 0 | since | integer | since height, excluded | 1024 | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the blocks, the object in the list is a [Block](#s-block), but **without** transaction details + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockList", + "params": [1024, 1, 10] +} +``` + +Response: [Block](#s-block) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "blocks" [ { TODO: block object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 102, + "pages": 11 + } +} +``` + +### bp_getBlockListByTimeRange + +TODO: as a new API in the next release + +### bp_getBlockByHeight + +Returns information about the block specified by its height. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | height of the block | 1024 | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHeight", + "params": [1] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getBlockByHash + +Returns information about the block specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------- | ------ | +| 0 | hash | string | hash of the block | "TODO" | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHash", + "params": ["TODO"] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getTransactionList + +Returns a list of the transactions. Traverse page by page by using a transaction hash as the mark for paging. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ----- | ------- | -------------------- | ------ | +| 0 | since | string | since hash, excluded | "TODO" | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionList", + "params": ["KhytGjS0xjw5CJvcJYpsNg", 1, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "transactions": [ { TODO: transaction object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 8, + "pages": 1 + } + } +} +``` + +### bp_getTransactionListOfBlock + +Returns a list of the transactions from a block by the specified height. + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | of block height | 1024 | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionListOfBlock", + "params": [1024, 1, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "transactions": [ { TODO: transaction object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 8, + "pages": 1 + } + } +} +``` + +### bp_getTransactionByHash + +Returns information about the transaction specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------------- | ------ | +| 0 | hash | string | hash of the transaction | "TODO" | + +#### Returns + +- object: transaction information object, it's a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionByHash", + "params": ["TODO"] +} +``` + +Response: [Transaction](#s-transaction) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: transaction object + } +} +``` + +## Structure Reference + +Here are some common structure definitions used in the API. + + + +### Block + +The block generated in the CovenantSQL blockchain network. + +| Field | Type | Description | +| --------------- | ------- | ------------------------------------------------------- | +| height | integer | Height of the block | +| hash | string | Hash of the block | +| version | integer | Version number of the block | +| producer | string | Address of the node who generated this block | +| merkle_root | string | Hash of the merkle tree | +| parent | string | Hash of its parent block | +| timestamp | integer | Create time of the block, unix time in nanoseconds | +| timestamp_human | string | Create time of the block, human readable RFC3339 format | +| tx_count | integer | Count of the transactions in this block | + +Sample in JSON format: + +```json +{ + "height": 12, + "hash": "TODO", + "version": 1, + "producer": "4io8u9v9nydaQPXtmqibg8gJbkNFd7DdM47PLWuM7ubzBXZ4At7", + "merkle_root": "TODO", + "parent": "TODO", + "timestamp": "TODO", + "timestamp_human": "TODO", + "tx_count": 1 +} +``` + + + +### Transaction + +| Field | Type | Description | +| --------------- | ------- | ------------------------------------------------------------------------------------------- | +| block_height | integer | Height of the block this transaction belongs to | +| index | integer | Index of the transaction in the block | +| hash | string | Hash of the transaction data | +| block_hash | string | Hash of the block this transaction belongs to | +| type | integer | Type of the transaction | +| address | string | Account address who signed this transaction | +| timestamp | integer | Create time of the transaction, unix time in nanoseconds | +| timestamp_human | string | Create time of the transaction, human readable RFC3339 format | +| raw | string | Raw content of the transaction data, in JSON format | +| tx | object | Concrete transaction object, see supported [transaction types](#transaction-types) for more | + +Sample in JSON format: + +```json +{ + "block_height": 1, + "index": 0, + "hash": "TODO", + "block_hash": "TODO", + "timestamp": "TODO", + "timestamp_human": "TODO", + "type": 1, + "address": "TODO", + "raw": "TODO", + "tx": { + "field": "TODO" + } +} +``` + +**Supported Transaction Types:** + +- [CreateDatabase](#s-transaction-createdatabase) + +TODO: more types + + + +### Transaction: CreateDatabase + +TODO: more types \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/bck/development-cmd-cql-utils-zh.md b/website/translated_docs/zh-CN/version-0.3.0/bck/development-cmd-cql-utils-zh.md new file mode 100644 index 0000000..17c0215 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/bck/development-cmd-cql-utils-zh.md @@ -0,0 +1,41 @@ +--- +id: version-0.3.0-keygen +title: 使用 cql-utils 生成密钥与钱包 +original_id: keygen +--- +`cql-utils` 是 CovenantSQL 的一个命令行工具，具体用法如下。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 使用 + +### 生成公私钥对 + + $ cql-utils -tool keygen + Enter master key(press Enter for default: ""): + ⏎ + Private key file: private.key + Public key's hex: 03bc9e90e3301a2f5ae52bfa1f9e033cde81b6b6e7188b11831562bf5847bff4c0 + + +生成的 private.key 文件即是使用主密码加密过的私钥文件，而输出到屏幕上的字符串就是使用十六进制进行编码的公钥。 + +### 使用私钥文件或公钥生成钱包地址 + + $ cql-utils -tool addrgen -private private.key + Enter master key(default: ""): + ⏎ + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + $ cql-utils -tool addrgen -public 02f2707c1c6955a9019cd9d02ade37b931fbfa286a1163dfc1de965ec01a5c4ff8 + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + + +你可以通过指定私钥文件，或者把上述的公钥十六进制编码字符串作为命令行参数来直接生成钱包地址。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/bck/development-cmd-cql-zh.md b/website/translated_docs/zh-CN/version-0.3.0/bck/development-cmd-cql-zh.md new file mode 100644 index 0000000..b4c5cb4 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/bck/development-cmd-cql-zh.md @@ -0,0 +1,77 @@ +--- +id: version-0.3.0-cql +title: 使用命令行客户端 cql 创建数据库 +original_id: cql +--- +本文档主要介绍 CovenantSQL 命令行客户端 `cql` 的使用。`cql` 是一个用于批量进行 SQLChain 上数据库的创建、查询、更新或删除操作的命令行工具。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 生成默认配置文件 + +首先需要一个 config 文件和由你输入的主密码（master key）来初始化，其中主密码用来加密解密本地密钥对。使用 `cql-utils` 工具进行配置文件生成后，你可以在生成的配置文件目录下找到密钥文件。 + +具体请参考: [cql-utils 使用文档](https://github.com/CovenantSQL/docs/tree/master/development-cmd-utils-zh.md#使用) 中配置文件及钱包地址生成相关章节。 + +## 检查钱包余额 + +使用 `cql` 命令来检查钱包余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] +### Public Key ### +0388954cf083bb6bb2b9c7248849b57c76326296fcc0d69764fc61eedb5b8d820c +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +这里我们得到结果 **"stable coin balance is: 100"**。 + +## 初始化一个 CovenantSQL 数据库 + +准备好配置文件和主密码后就可以使用 `cql` 命令来创建数据库了，你的数据库 ID 将会输出到屏幕上： + +```bash +# if a non-default password applied on master key, use `-password` to pass it +$ cql -config conf/config.yaml -create 1 +INFO[0000] +### Public Key ### +039bc931161383c994ab9b81e95ddc1494b0efeb1cb735bb91e1043a1d6b98ebfd +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] the newly created database is: covenantsql://0e9103318821b027f35b96c4fd5562683543276b72c488966d616bfe0fe4d213 caller="main.go:297 main.main" +``` + +这里 `-create 1` 表示创建一个单节点的 SQLChain。 + +```bash +$ cql -config conf/config.yaml -dsn covenantsql://address +``` + +`address` 就是你的数据库 ID。 + +`cql` 命令的详细使用帮助如下： + +```bash +$ cql -help +``` + +## 使用 `cql` + +现在可以使用 `cql` 进行数据库操作了: + +```bash +co:address=> show tables; +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/bck/development-golang-client-zh.md b/website/translated_docs/zh-CN/version-0.3.0/bck/development-golang-client-zh.md new file mode 100644 index 0000000..a7e99e0 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/bck/development-golang-client-zh.md @@ -0,0 +1,108 @@ +--- +id: version-0.3.0-golang-client +title: 使用 Golang 驱动访问数据库 +original_id: golang-client +--- +本文档介绍 CovenantSQL 客户端的使用方式。客户端用来创建、查询、更新和删除 SQLChain 以及绑定的数据库。 + +## 开始之前 + +确保 `$GOPATH/bin` 目录在环境变量 `$PATH` 中，执行以下命令 + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +然后在你的 go 代码中 import 第一个 `client` 包。 + +## 初始化一个 CovenantSQL 客户端 + +首先需要一个 config 文件和 master key 来初始化。master key 用来加密解密本地密钥对。以下是如何用一个自定义 master key 来生成默认的 config 文件： + +### 生成默认的配置文件 + +运行以下 `cql-utils` 命令，输入 master key（类似密码）来生成本地密钥对。等待几十秒，会在 `~/.cql` 文件夹中，生成一个私钥文件和一个名为 `config.yaml` 的配置文件。 + +```bash +./cql-utils -tool confgen +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: ~/.cql/private.key +Public key's hex: 025abec9b0072615170f4acf4a2fa1162a13864bb66bc3f140b29f6bf50ceafc75 +Generated key pair. +Generating nonce... +INFO[0005] cpu: 1 +INFO[0005] position: 0, shift: 0x0, i: 0 +nonce: {{1450338416 0 0 0} 26 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514} +node id: 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514 +Generated nonce. +Generating config file... +Generated nonce. +``` + +有了配置文件之后，可以通过以下 go 代码来初始化 CovenantSQL 客户端： + +```go +client.Init(configFile, masterKey) +``` + +## 客户端使用方式 + +### 创建一个 SQLChain 数据库 + +创建 SQLChain 数据库需要指明需要几个节点（nodeCount变量）: + +```go +var ( + dsn string + meta client.ResourceMeta +) +meta.Node = uint16(nodeCount) +dsn, err = client.Create(meta) +// process err +``` + +创建完毕会返回一个 dsn 字符串，用来访问这个数据库。 + +### 查询和执行 + +拿到 dsn 字符串后，可以通过以下代码在 SQLChain 中执行 SQL 语句： + +```go +
db, err := sql.Open("covenantsql", dsn) + // process err + + _, err = db.Exec("CREATE TABLE testSimple ( column int );") + // process err + + _, err = db.Exec("INSERT INTO testSimple VALUES(?);", 42) + // process err + + row := db.QueryRow("SELECT column FROM testSimple LIMIT 1;") + + var result int + err = row.Scan(&result) + // process err + fmt.Printf("SELECT column FROM testSimple LIMIT 1; result %d\n", result) + + err = db.Close() + // process err + +``` + +用法和其他 go sql driver 一致。 + +### 删除数据库 + +使用 dsn 来删除数据库： + +```go + err = client.Drop(dsn) + // process err +``` + +### 完整示例 + +在以下目录中有一个简单示例和复杂示例可以参考 [示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/bck/getting-started-overview-zh.md b/website/translated_docs/zh-CN/version-0.3.0/bck/getting-started-overview-zh.md new file mode 100644 index 0000000..8f38c66 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/bck/getting-started-overview-zh.md @@ -0,0 +1,63 @@ +--- +id: version-0.3.0-intro +title: 简介 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +- **SQL**: 支持 SQL-92 标准 +- **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +- **隐私**: 通过加密和授权许可进行访问 +- **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信[在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +#### 一行代码接入区块链数据 + +```go +sql.Open("CovenantSQL", dbURI) +``` + +# # + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +- 第一层: **全局共识层**(主链，架构图中的中间环): + - 整个网络中只有一个主链。 + - 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +- 第二层: **SQL 共识层**(子链，架构图中的两边环): + - 每个数据库都有自己独立的子链。 + - 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +- 第三层: **数据储存层**(支持 SQL-92 的数据库引擎): + - 每个数据库都有自己独立的分布式引擎。 + - 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/bck/getting-started-testnet-zh.md b/website/translated_docs/zh-CN/version-0.3.0/bck/getting-started-testnet-zh.md new file mode 100644 index 0000000..1f14ac4 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/bck/getting-started-testnet-zh.md @@ -0,0 +1,96 @@ +--- +id: version-0.3.0-testnet +title: CovenantSQL 测试网快速入门 +original_id: testnet +--- +[CovenantSQL](https://github.com/CovenantSQL/CovenantSQL/blob/develop/README-zh.md) 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +1. **SQL**: 支持 SQL-92 标准 +2. **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +3. **隐私**: 通过加密和授权许可进行访问 +4. **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## 0. 下载 CovenantSQL 工具 + +在 [github](https://github.com/CovenantSQL/CovenantSQL/releases) 下载最新的发行版 + +## 1. 用 `cql-utils` 生成配置文件访问测试网 + +```bash +$ cql-utils -tool confgen +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: ~/.cql/private.key +Public key's hex: 02296ea73240dcd69d2b3f1fb754c8debdf68c62147488abb10165428667ec8cbd +Generated key pair. +Generating nonce... +nonce: {{731613648 0 0 0} 11 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9} +node id: 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9 +Generated nonce. +Generating config file... +Generated nonce. +``` + +该命令会为你在~目录下创建一个 `.cql` 目录： + +- `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +## 2. 用私钥生成钱包地址 + +私钥可以再上一步的 `~/.cql` 目录中找到，文件名为 `private.key` + +```bash +$ cql-utils -tool addrgen -private ~/.cql/private.key +Enter master key(default: ""): +⏎ +wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 +``` + +上述 `4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9` 就是钱包地址 + +## 3. 在水龙头(Faucet)获取 Particle(PTC) + +水龙头(Faucet)的地址为: [CovenantSQL 测试网 Particle(PTC) 水龙头](https://testnet.covenantsql.io/)。 + +完成教程之后，用 `cql` 命令来检查钱包地址的余额(未加-config参数时，命令会自动找~/.cql目录的config.yaml文件)： + +```bash +$ cql -get-balance +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +当看到 **"stable coin balance is: 100"** 时，表明余额已经为 100。 + +如果您需要更多的 PTC 作为长期测试使用，请联系 。 + +对于有合作的商业伙伴，我们将直接提供 PTC 以供使用。 + +## 4. 使用 `CLI` 创建数据库 + +```bash +$ cql -create 1 +INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" +``` + +第一行命令中的 `1` 表示申请几个矿工为你的数据库服务。`covenantsql://...` 开头的这个字符串就是创建的数据库访问地址，在 SDK 和 CLI 命令中都需要用此地址，在整个区块链中找到这个数据库。 + +## 5. CLI 和 SDK 的详细文档 + +创建好数据库后，您可以参考以下文档和示例，以便更快的使用CovenantSQL来开发应用。 + +- [CLI 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql/README-zh.md) +- [SDK 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/README-zh.md) +- [SDK 示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) + +## 6. SQLChain 浏览器 + +目前，测试网的数据库时不需要权限的。意味着您可以通过数据库的DSN(数据库访问地址)，在[SQLChain 浏览器](https://explorer.dbhub.org)中拿到所有的修改历史和区块信息。 + +更多的测试网技术支持，请访问: + +> [TestNet 发行日志](https://github.com/CovenantSQL/CovenantSQL/wiki/Release-Notes-zh) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/bck/getting-started-zh.md b/website/translated_docs/zh-CN/version-0.3.0/bck/getting-started-zh.md new file mode 100644 index 0000000..4e25cd0 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/bck/getting-started-zh.md @@ -0,0 +1,486 @@ +--- +id: version-0.3.0-local-deployment +title: CovenantSQL 综述 +original_id: local-deployment +--- +# CovenantSQL 介绍 + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可变成 ĐApp +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是用户的钱包，那么 CovenantSQL 就是是用户的去中心化数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密 保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 + +# 安装 CovenantSQL 客户端 + +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +* [Go](./development-golang-client-zh.md) +* [Java](https://github.com/CovenantSQL/covenant-connector) +* [Python](https://github.com/CovenantSQL/python-driver) +* [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你在~目录下创建一个 `.cql` 目录： + +* `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +* `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private ~/.cql/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额(未加 -config 参数时，命令会自动找 ~/.cql 目录的 config.yaml 文件)： + +```shell +./cql -config ~/.cql/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +* [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 + +# 部署 CovenantSQL + +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 启动 Docker 容器 + +执行以下的命令在本地运行 CovenantSQL + +```shell +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +make docker +make start +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行`export COVENANTSQL_ROOT=$PWD`存为环境变量 + +### 检查运行状态 + +```shell +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp +covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp +covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp +covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp +covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp +``` + +### SQLChain Observer + +我们在`:11108`端口提供了一个 SQLChain 的 Observer 可以看到 SQL 语句在链上的情况 + +# 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +cql -config config/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +cql -config config/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +cql -config config/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +# 使用 CovenantSQL 开发 App + +## Golang 使用 CovenantSQL + +#### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +#### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +#### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +#### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +#### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` + +# CovenantSQL API + +# 常见问题解答 + +补充 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/bck/guide-zh.md b/website/translated_docs/zh-CN/version-0.3.0/bck/guide-zh.md new file mode 100644 index 0000000..324f6d7 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/bck/guide-zh.md @@ -0,0 +1,114 @@ +--- +id: version-0.3.0-guide-zh +title: 快速开始 +original_id: guide-zh +--- +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +- [Go](./development-golang-client-zh.md) +- [Java](https://github.com/CovenantSQL/covenant-connector) +- [Python](https://github.com/CovenantSQL/python-driver) +- [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你在~目录下创建一个 `.cql` 目录： + +- `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private ~/.cql/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额(未加 -config 参数时，命令会自动找 ~/.cql 目录的 config.yaml 文件)： + +```shell +./cql -config ~/.cql/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +- [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/cql.md b/website/translated_docs/zh-CN/version-0.3.0/cql.md new file mode 100644 index 0000000..974f5fd --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/cql.md @@ -0,0 +1,150 @@ +--- +id: version-0.3.0-cql +title: '🖥️ CQL 命令行工具' +original_id: cql +--- +## 简介 + +本文将介绍如何使用 `cql` 进行查询、转账和数据库权限管理。在使用 `cql` 前请先确认已接入 [CovenantSQL TestNet](quickstart) 或者在本地使用 [Docker 一键部署](development)的网络。 + +## 查询余额 + +查询余额有两个命令：`cql -get-balance` 和 `cql -token-balance `。其中 `-get-balance` 将返回用户账户中 `Particle` 与 `Wave` 的数量，`-token-balance ` 将返回用户账户中特定 `token_type` 的 token 数量。目前系统支持的 `token_type` 有： + +- `Particle` +- `Wave` +- `Bitcoin` +- `Ether` +- `EOS` + +查看默认余额： + +```bash +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] Particle balance is: 10000000000000000000 + INFO[0000] Wave balance is: 10000000000000000000 + + +查看 Particle 余额： + +```bash +./cql -config conf/config.yaml -token-balance Particle +``` + +输出： + + INFO[0000] Particle balance is: 10000000000000000000 + + +查看 Bitcoin 余额： + +```bash +./cql -config conf/config.yaml -token-balance Bitcoin +``` + +输出： + + INFO[0000] Bitcoin balance is: 0 + + +## 转账 + +转账操作使用 `cql -transfer` 并以 `json` 格式的转账信息为参数。 + +```json +{ + "addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // 收款地址 + "amount":"1000000 Particle" // 转账金额并带上单位 +} +``` + +其中收款地址可以是一个个人钱包地址也可以是一个数据库子链地址。转账至数据库地址时将在该数据库账户上补充付款人的押金与预付款。 + +转账 Particle： + +```bash +./cql -config conf/config.yaml -transfer '{"addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount":"1000000 Particle"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +转账 Wave： + +```bash +./cql -config conf/config.yaml -transfer '{"addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount":"1000000 Wave"}' +``` + + INFO[0000] succeed in sending transaction to CovenantSQL + + +查看余额： + +```bash +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] Particle balance is: 9999999999999000000 + INFO[0000] Wave balance is: 9999999999999000000 + + +注意，`succeed in sending transaction to CovenantSQL` 只说明交易已成功发送至主网，交易能否成功、何时成功需要通过 `-get-balance` 或者 `-token-balance ` 确定。 + +## 数据库权限管理 + +CovenantSQL 数据库有三类库级别权限： + +- `Admin` +- `Write` +- `Read` +- `Void` + +其中，`Admin` 可以赋予其他钱包地址数据库的权限（`Admin`、`Write` 或 `Read`）；`Admin` 和 `Write` 可以对数据库进行写操作（`CREATE`, `INSERT` 等）；`Admin`, `Write` 和 `Read` 可以对数据库进行读操作（`SHOW`, `SELECT` 等）；`Void` 是一个特殊的权限，当 `Admin` 想取消某个地址的权限时可以将该地址的权限设置为 `Void`，这样该地址将无法继续读写数据库。创建数据库的地址的权限默认为 `Admin`。若 `Admin` 需要赋予他人权限请使用 `cql -update-perm` 并以 `json` 格式的权限信息为参数： + +```json +{ + "chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", // 需要进行权限变更的数据库地址 + "user":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // 需要赋予权限的钱包地址 + "perm":"Write" // 权限内容 +} +``` + +增加写权限： + +```bash +./cql -config conf/config.yaml -update-perm '{"chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","user":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","perm":"Write"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +吊销权限： + +```bash +./cql -config conf/config.yaml -update-perm '{"chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","perm":"Void"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +注意，`succeed in sending transaction to CovenantSQL` 只说明交易已成功发送至主网，交易成功与否请通过查询数据库确认。 + +为数据库添加新的账户权限后账户需补充押金与预付款才能进行正常查询。押金与预付款最小值的计算公式：`gas_price*number_of_miner*120000`。 + +使用新账户给数据库充值： + +```bash +./cql -config new_user_config/config.yaml -transfer '{"addr":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","amount":"90000000 Particle"}' +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/deployment.md b/website/translated_docs/zh-CN/version-0.3.0/deployment.md new file mode 100644 index 0000000..d46cdd6 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/deployment.md @@ -0,0 +1,162 @@ +--- +id: version-0.3.0-deployment +title: '🐳 Docker 一键部署' +original_id: deployment +--- +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 下载项目 + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行 + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +存为环境变量 + +### 启动 Docker 容器 + +现在有两种方式启动 CovenantSQL 容器： + +1. 使用 Docker Hub 上的公共镜像 +2. 构建 CovenantSQL Docker 镜像 + +> 我们推荐普通用户使用第一种方式测试 CovenantSQL，第二种仅用于体验最新的开发中的特性。 + +#### 1. 使用 Docker Hub 上的公共镜像 + +然后直接启动： + +```bash +make start +``` + +#### 2. 构建 CovenantSQL Docker 镜像 + +执行以下的命令在本地运行 CovenantSQL + +```bash +make docker # 从头编译新的镜像 +make start +``` + +### 检查运行状态 + +检查容器状态： + +```bash +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp +covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp +covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp +covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp +covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp +``` + +## 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +### SQLChain Observer + +镜像中的 Observer 角色使用了和 mysql-adapter 镜像中相同的 private.key ，故可以免去新账户授权和转账的过程制。 + +（关于权限管理的详细说明请参考[数据库权限管理](cql.md#数据库权限管理)） + +#### 在浏览器使用 SQLChain Observer + +我们在 `127.0.0.1:11108` 端口提供了一个 SQLChain 的 Observer 可以看到 SQL 语句在链上的情况。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/development.md b/website/translated_docs/zh-CN/version-0.3.0/development.md new file mode 100644 index 0000000..0d2c60b --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/development.md @@ -0,0 +1,173 @@ +--- +id: version-0.3.0-development +title: '📦 CovenantSQL SDK' +original_id: development +--- +## Golang 使用 CovenantSQL + +### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/intro.md b/website/translated_docs/zh-CN/version-0.3.0/intro.md new file mode 100644 index 0000000..e698711 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/intro.md @@ -0,0 +1,73 @@ +--- +id: version-0.3.0-intro +title: CovenantSQL 介绍 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可数据上链 +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是人们的私人钱包，那么 CovenantSQL 就是是人们的去中心化的私密数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密来保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/native.md b/website/translated_docs/zh-CN/version-0.3.0/native.md new file mode 100644 index 0000000..dfb6829 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/native.md @@ -0,0 +1,173 @@ +--- +id: version-0.3.0-native +title: '📦 CovenantSQL Native SDK' +original_id: native +--- +## 用 Golang 使用 CovenantSQL + +### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/nav.md b/website/translated_docs/zh-CN/version-0.3.0/nav.md new file mode 100644 index 0000000..4062dc3 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/nav.md @@ -0,0 +1,22 @@ +--- +id: version-0.3.0-nav +title: '📖 使用导航' +original_id: nav +--- +## 直接使用测试网 + +[🌏 TestNet 快速开始](./quickstart) + +## 部署私有 CovenantSQL 数据库（搭建私有链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +[🐳 Docker 一键部署](./deployment) + +## 使用 CovenantSQL 开发应用 + +[📦 CovenantSQL SDK](./development) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/proxy.md b/website/translated_docs/zh-CN/version-0.3.0/proxy.md new file mode 100644 index 0000000..836102f --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/proxy.md @@ -0,0 +1,111 @@ +--- +id: version-0.3.0-adapter +title: '📦 CovenantSQL Adapter SDK' +original_id: adapter +--- +# 通过 Adapter 使用 CovenantSQL + +## 简介 + +`CovenantSQL` 提供了 HTTP/HTTPS Adapter，类似于云数据库， 开发者可以直接用 HTTP 的形式使用 CovenantSQL。 + +## 安装和使用 + +首先，需要确认我们有一个可用的配置和公私钥对，通常我们默认的配置和公私钥对的存储位置为 `~/.cql/` 目录。生成或获取请参考 [QuickStart#创建账号](./quickstart#创建账号) + +### Docker 运行 Adapter + +下面的命令将使用`~/.cql/config.yaml` 和 `~/.cql/private.key` 启动 Adapter，并把端口映射在 `0.0.0.0:11105` + +```bash +export adapter_addr=0.0.0.0:11105 +docker rm -f cql-adapter +docker run -itd \ + --env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --name cql-adapter -p $adapter_addr:4661 \ + covenantsql/covenantsql:testnet -listen 0.0.0.0:4661 +``` + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +docker run -it --rm \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --entrypoint /app/cql covenantsql/covenantsql:testnet \ + -config /app/config.yaml -create 1 +``` + +命令会返回创建的数据库实例的连接串（DSN） + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +## 主流语言 Driver 的使用 + +### NodeJS + +NodeJS 开发者可以通过 [node-covenantsql](https://github.com/CovenantSQL/node-covenantsql) 来与 CovenantSQL Adapter 进行交互。 + +#### 下载安装 + +可以直接通过 `npm` 或者 `yarn` 来安装 `node-covenantsql` + +```bash +npm install --save node-covenantsql +``` + +or + +```bash +yarn add node-covenantsql +``` + +#### 使用 + +在运行本地 Adapter 之后，将 Adapter 的 endpoint 填入 `node-covenantsql` 的 config 之中： + +```javascript +const config = { + endpoint: 'localhost:11105', // local testnet endpoint without https + database: `${DSN}`, // your DB id created by `cql` tools + bypassPem: true // bypass https config +} +``` + +这里 `bypassPem` 为 `true` 表示应用中所有对链上数据库的操作都会经过本地的 Adapter 进行代理，我们默认本地环境是可控，安全的，无需用 HTTPS 来保证这段连接的信道安全，少了证书的繁琐认证，所以成为 `bypassPem`。 + +接着连通之后则可进行链上数据库的增删改查： + +```typescript +const cql from 'node-covenantsql' + +const config = {...} // see above + +cql.createConnection(config).then(async (connection: any) => { + // read + const data1 = await connection.query("select ? + ?", [2.1, 3.2]); + console.log(data1); + + // write + const createTableSQL = ` + CREATE TABLE IF NOT EXISTS contacts (\ + contact_id INTEGER PRIMARY KEY, + first_name TEXT NOT NULL, + last_name TEXT NOT NULL, + email text NOT NULL UNIQUE, + phone text NOT NULL UNIQUE + ); + ` + const status1 = await connection.exec(createTableSQL) + console.log(`exec1 status:`, status1); + + const data2 = await connection.query("show tables;"); + console.log(data2); +}).catch((e: any) => console.log(e)) +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/qna.md b/website/translated_docs/zh-CN/version-0.3.0/qna.md new file mode 100644 index 0000000..797cb90 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/qna.md @@ -0,0 +1,6 @@ +--- +id: version-0.3.0-qna +title: '🙋 常见问题解答' +original_id: qna +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/quandl.md b/website/translated_docs/zh-CN/version-0.3.0/quandl.md new file mode 100644 index 0000000..db94e5f --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/quandl.md @@ -0,0 +1,298 @@ +--- +id: version-0.3.0-quandl +title: 基于 Quandl 的金融数据分析 +original_id: quandl +--- +## 关于 Quandl + +Quandl 是一个针对金融投资行业的大数据平台，其数据来源包括联合国、世界银行、中央银行等公开数据，核心财务数据来自 CLS 集团，Zacks 和 ICE 等，所有的数据源自 500 多家发布商， 是为投资专业人士提供金融，经济和替代数据的首选平台，拥有海量的经济和金融数据。 + +## Quandl 数据索引 + +### CovenantSQL 使用简介 + +首先，我们已基于 Quandl 的开放 API 将数据存放在 CovenantSQL 中，首先应该浏览一下 CovenantSQL 的使用介绍来熟悉一下如何连接并且使用 CovenantSQL。 + +现在由于客户端兼容问题， 请直接使用我们的 HTTP 服务来对 Quandl 数据库进行 query，未来兼容现在的 `cql` 客户端后会第一时间更新此文档。 + +具体通过 HTTP 服务来使用 CovenantSQL 请参考 [Python 驱动文档](https://github.com/CovenantSQL/python-driver/blob/master/README.rst) 和 [NodeJS 驱动文档](https://github.com/CovenantSQL/node-covenantsql/blob/master/README.md) + +所需参数: + + host: 'e.morenodes.com' + port: 11108 + database: '057e55460f501ad071383c95f691293f2f0a7895988e22593669ceeb52a6452a' + + +### 数据使用方法 + +Quandl 数据分为表以及子表两层索引 + +数据库中，表名为`quandl_` + `database_code`为完整表名 + +通过查询表名来查看表的内容 + +具体使用时，需要结合`quandl_updateindex` 这张索引表来使用，（查询索引表时，请务必 limit 小于 10 万，因为全表数据量过大） + +使用时，请使用 where 语句限定`quandlcode`字段来查询表中的子表数据。 + +### 查询示例 + +1. 我们想要查询 欧盟委员会年度宏观经济数据库 的数据，我们找到其第一层索引的 `databasecode` 为`quandl_ameco`，于是，我们可以查询其第二层索引，用以下 SQL 命令行： + + `select * from quandl_updateindex where databasecode like 'ameco' group by quandlcode limit 10000` + +2. 然后通过第三列，我们可以查看`quandlcode`对应的描述 + + 比如 AMECO/ALB_1_0_0_0_AAGE 对应的就是阿尔巴尼亚的进出口相关信息，时间从 1960 到 1988。 + + Average share of imports and exports of goods in world trade excluding intra EU trade; Foreign trade statistics (1960-1998 Former EU-15) - Albania + + 于是，我们可以用以下方式把这个子表给查询出来 + + `select * from quandl_ameco where quandlcode like 'AMECO/ALB_1_0_0_0_AAGE' limit 10000` + +3. 注意：如果内容整列为 null 的，属于表结构本身不存在的字段，可以自行去除。 + +## Quandl 数据 Excel 插件使用说明 + +您可以下载 Quandl 数据 Excel 插件，无须安装，请解压到任意文件夹中。此插件目前仅支持 Office 2010 以及以上版本，office 2007 以及以下版本目前暂不支持。 + +### 配置 Excel 插件 + +解压下载后压缩包，在文件夹中有两个.xll 文件，`ClassLibrary7-AddIn.xll` 以及 `ClassLibrary7-AddIn64.xll` 文件，这两个文件分别对应 32 位的 Excel 与 64 位的 Excel，请根据您的电脑配置使用对应插件。 + +#### 修改 xml 配置 + +每个 `.xll` 文件对应一个 `.config` 的配置文件，也就是 `ClassLibrary7-AddIn.xll.config` 和`ClassLibrary7-AddIn64.xll.config`，为如下 xml 配置： + +```xml + + + + + + + + + +``` + +其中有如下配置需要修改，并保存： + +- certpath: 请填写 `read.data.thunderdb.io.pfx` 证书的绝对路径 + +#### 安装插件 + +有两种办法使用此 Excel 插件 + +1. 直接双击对应的 32 位或 64 位 Excel 的 xll 文件打开 + +![quandl_ext_1](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_1.png) + +如果弹出如上对话框，选择第一个： `仅为本回话启用此加载项`。然后新建一个 Excel 表格，如果在 Excel 的上方选项卡中看到 CovenantSQL，说明插件加载成功。 + +2. 打开 Excel，然后依次选择 `文件 — 选项 — 加载项`，管理选择 Excel 加载项，点击转到然后浏览选择解压后的对应版本的 `.xll` 文件，然后点击 `确定`，在选项卡中如果成功加载出 CovenantSQL 即为成功加载，如下图： + +![quandl_ext_2](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_2.png) + +#### 使用插件 + +选择 CovenantSQL 的选项卡可以看到 Quandl 数据查询，点击 Quandl 数据查询，会弹出一个窗体如下图所示： + +![quandl_ext_3](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_3.png) + +- 其中红色框住的列表部分是一级目录，下方则是所选项的具体描述 + +- 绿色按钮是通过选择的一级目录来查询二级目录。这里查询时间会随着所查询二级目录的大小以及用户自身的网络速度等因素而不同，可能查询时间会超过 1 分钟，请耐心等待。 + +- 黄色部分左边的列表是二级目录，右边的窗体则为列表项所选择的表的描述。 + +- 蓝色部分是导出数据的可选项 + + - Limit Number 是一次导出的最多数据条数，默认为 10000 条，最大值可填写 100000 + - Offset Number 是从数据库的第几条开始导出，因为之前会限定条数，例如我们之前导出了 10000 条数据，但是明显数据还没有导出全部，我们可以使用此功能选择 offset 10000 来从第 10000 条开始导出（注：数据库的计数从 0 开始，所以前 10000 条为 0-9999） + +现在，您即可在 Excel 中方便的调用存在 CovenantSQL 上的 Quandl 数据。 + +## 附件表 + +| DataBase | 名称 | 描述 | +| ------------ | ------------------------ | ------------------------------------------------------------------------------------------- | +| BUNDESBANK | 德意志联邦银行数据仓库 | 有关德国经济，货币和资本市场，公共财政，银行，家庭，欧元区总量，贸易和外债的数据。 | +| URC | 独角兽研究公司数据 | 纽约证券交易所，美国证券交易所和纳斯达克证券交易所的预付和下跌数据。从各种公开来源和报告中值。 | +| DCE | 大连商品交易所数据 | 来自DCE的农业和商品期货，历史跨越了近十年的特定期货。 | +| WFC | 富国银行住房抵押贷款数据 | 该数据库提供富国银行（Wells Fargo Bank）分部Wells Fargo Home Mortgage的抵押贷款购买和再融资利率。 | +| USDAFNS | 美国农业部食品与营养服务项目数据 | 食品和营养服务局为低收入家庭和儿童管理联邦营养援助计划。成本和参与率数据。 | +| LJUBSE | 卢布尔雅那证券交易所数据 | 该数据库包含卢布尔雅那股票交易所指数，总部位于斯洛文尼亚的卢布尔雅那。 | +| TOCOM | 东京商品交易所数据 | 来自东京商品交易所（TOCOM）的农业和商品期货，历史跨越了近十年的特定期货。 | +| WCSC | 世界银行企业积分卡数据 | 该数据库旨在提供世界银行集团在消除极端贫困和促进共同繁荣方面的表现的战略概述。 | +| CMHC | 加拿大住房抵押贷款公司 | CMHC是一家政府所有的公司，为加拿大公民提供经济适用房，并收集价格，建筑和供应等数据。 | +| WGEC | 世界银行全球经济监测商品数据（GEM） | 包含1960年至今的商品价格和指数的数据。 | +| FED | 美联储数据公布 | 美国官方关于货币供应量，利率，抵押贷款，政府财政，银行资产和债务，汇率，工业生产的数据。 | +| WPSD | 世界银行公共部分支出数据 | 由世界银行和国际货币基金组织共同开发的数据，汇集了详细的公共部门政府债务数据。 | +| UGID | 联合国全球指标 | 该数据库提供广泛的全球指标，涵盖人口，公共卫生，就业，贸易，教育，通货膨胀和外债。 | +| RBA | 澳大利亚储备银行数据 | 中央银行和货币当局，监管银行业，设定利率，并为政府债务提供服务。关键经济指标数据。 | +| UCOM | 联合国商品贸易数据 | 该数据库提供有关食品，活体动物，药品，金属，燃料和机械等商品进出口的全面综合数据。 | +| SIDC | 太阳影响数据分析中心数据 | SIDC主持从1700年开始的太阳活动数据，特别是太阳黑子活动。 | +| ZCE | 郑州商品交易所数据 | 来自ZCE的农业和商品期货，历史跨越了近十年的特定期货。 | +| USDAFAS | 美国农业部外国农业服务数据（FAS） | 美国农业部外国农业服务局将美国农业与世界市场联系起来。它提供了国外生产和出口的统计数据。 | +| OECD | 世界经济合作与发展组织数据 | 促进经济福利的发达国家国际组织。从成员和其他人收集数据以提出政策建议。 | +| OPEC | 欧佩克数据 | 国际组织和经济卡特尔监督伊拉克，伊朗，沙特阿拉伯和委内瑞拉等石油生产国的政策、油价数据。 | +| MCX | 印度多种商品交易所数据 | 印度最大的商品交易所，为金属，能源和农业期货交易提供服务。世界第三大合约和交易量交易所。 | +| ECONOMIST | 经济学人 - 巨无霸指数 | 巨无霸指数是由经济学家于1986年发明的，是一个轻松的指南，指出货币是否处于“正确”水平。它基于购买力平价理论（PPP）。 | +| NSDL | 国家证券存管有限公司（印度）数据 | 在印度存放负责该国经济发展的国家，该国家建立了国际标准的国家基础设施，处理在印度资本市场以非物质形式持有和结算的大部分证券。 | +| GDT | 全球乳品贸易数据 | nan | +| CFFEX | 中国金融期货交易所数据 | 来自CFFEX的指数和债券期货，对于特定期货的历史跨越近十年。 | +| CITYPOP | Thomas Brinkhoff的城市人口数据 | Thomas Brinkhoff提供了大多数国家城市和行政区域的人口数据。 | +| BCHARTS | 比特币图表汇率数据 | 来自所有主要比特币交易所的比特币兑换大量货币的汇率，包括当前和历史汇率。 | +| LOCALBTC | Local Bitcoins数据 | nan | +| JODI | JODI石油世界数据库 | JODI石油和天然气数据来自100多个国家，包括多种能源产品和各种计量方法。 | +| UENG | 联合国能源统计数据 | 该数据库提供有关新能源和可再生能源的生产，贸易，转换和最终消费的全面统计数据。 | +| ULMI | 联合国劳工市场指标 | 该数据库为世界上所有国家提供了按性别划分的全面青年失业数字。 | +| MAURITIUSSE | 毛里求斯证券交易所数据 | 毛里求斯证券交易所指数数据。 | +| UKRSE | 乌克兰交易所数据 | UKRSE提供与乌克兰最大证券交易所相关的最新数据。该交易所位于基辅，约占乌克兰总股本交易量的四分之三 | +| BITSTAMP | Bitstamp数据 | Bitstamp是一个比特币的交易平台。 | +| UNAE | 联合国国民账户估算数据 | 该数据库提供了全球所有国家不同部门的国内生产总值，国民总收入和总增加值的全球数据。 | +| UNAC | 联合国国民账户官方国家数据 | 该数据库提供有关国民账户的全球数据，例如家庭，公司和政府的资产和负债。 | +| UTOR | 联合国世界旅游业数据 | 该数据库提供有关国际旅游的综合数据。数据包括所有国家的旅游人数和旅游支出。 | +| WFE | 世界交易所联合会数据 | 该数据库提供有关国际旅游的综合数据。数据包括所有国家的旅游人数和旅游支出。 | +| FRBC | 克利夫兰联邦储备银行数据 | 克利夫兰联邦储备银行从数百家金融机构收集数据，包括存款机构，银行控股公司和其他用于评估金融机构状况的实体，以及收集经济和金融体系运作方式的见解。 | +| UGEN | 联合国性别信息 | 该数据库提供关于各种与性别有关的指标的全面综合数据，涵盖人口，卫生，教育和就业。 | +| BITFINEX | Bitfinex数据 | Bitfinex是比特币，莱特币和Darkcoin的交易平台，具有许多先进功能，包括保证金交易，交易所和点对点保证金融资。 | +| UGHG | 联合国温室气体清单 | 该数据库提供有关六种主要温室气体人为排放的全面综合数据。数据可以追溯到1990年。 | +| UIST | 联合国工业发展组织数据 | 该数据库提供有关工业发展指标的全球数据，包括产量，员工，工资，各种行业的增加值。 | +| PRAGUESE | 布拉格证券交易所数据 | 布拉格证券交易所的价格指数数据。 | +| PFTS | PFTS证券交易所（乌克兰）数据 | 来自PFTS证券交易所的指数数据，这是乌克兰最大的市场。 | +| WARSAWSE | 华沙证券交易所数据 | WIG20指数自1994年4月16日起根据WSE主要清单中20家最主要和最具流动性公司的股票价值计算。 | +| TUNISSE | 突尼斯证券交易所数据 | 突尼斯证券交易所的主要参考指数。 | +| FRKC | 堪萨斯城联邦储备银行数据 | FRKC是美联储第10区的区域中央银行，主要发布农业交易中的银行业务数据。 | +| UENV | 联合国环境统计数据 | 该数据库提供有关水和废物相关指标的全球数据，包括淡水供应和降水，以及废物的产生和收集。 | +| UFAO | 联合国粮食和农业数据 | 该数据库提供全球粮食和农业数据，包括作物生产，化肥消费，农业用地和牲畜用途。 | +| TAIFEX | 台湾期货交易所数据 | 来自TAIFEX的指数和债券期货，其历史跨越了十多年的特定期货。 | +| GDAX | GDAX（全球数字资产交易所）数据 | GDAX是世界上最受欢迎的买卖比特币的地方。 | +| ARES | 房地产证券化协会数据 | ARES保护投资者，有助于房地产证券化产品市场的发展，并促进房地产投资市场的扩张。 | +| SHADOWS | 影子联邦基金利率模型数据 | 该数据集包含 吴-侠 论文中关于影子联邦基金的三个主要指标，用于识别所有三大银行的影子利率。 | +| NAAIM | 全国积极投资管理者协会头寸指数 | NAAIM暴露指数代表NAAIM成员报告的美国股票市场的平均风险敞口。 | +| CBRT | 土耳其共和国中央银行数据 | CBRT负责采取措施维持土耳其金融体系的稳定。 | +| CEGH | 中欧天然气中心数据 | nan | +| FINRA | 美国金融业监管局数据 | 金融业监管局提供证券公司和交易所市场的短期利息数据。 | +| NASDAQOMX | 纳斯达克OMX全球指数数据 | 纳斯达克OMX发布的全球指数超过35,000种，包括全球股票，固定收益，股息，绿色，北欧，伊斯兰教等。每日数据。 | +| EURONEXT | 泛欧证券交易所数据 | 欧洲最大的交易所Euronext的历史股票数据。 | +| UICT | 联合国信息和通信技术数据 | 该数据库提供有关信息和通信技术的全面全球数据，包括所有国家的电话，蜂窝和互联网使用情况。 | +| USAID | 美国国际开发署数据 | 美国国际开发署提供了美国向世界其他地方提供的所有外国援助的完整历史记录。 | +| ZAGREBSE | 萨格勒布证券交易所数据 | 克罗地亚唯一的证券交易所。它发布有关其股票和债券指数表现的数据。 | +| QUITOSE | 基多证券交易所（厄瓜多尔）数据 | 厄瓜多尔国家证券交易所的指数。 | +| ECBCS | 欧盟委员会商业和消费者调查 | 该数据库中的数据来自欧盟（EU）和欧盟申请国的不同经济部门的统一调查。 | +| PSE | 巴黎经济学院数据 | 该数据库描述了越来越多国家的最高收入分配。数字是使用税收数据得出的。 | +| MALTASE | 马耳他证券交易所数据 | 马耳他证券交易所发挥作用，为其认可的名单提供金融工具的结构，随后可在受监管，透明和有序的市场（二级市场）进行交易。市场的主要参与者是发行人，股票交易所会员（股票经纪人）和投资者一般。 | +| GPP | 全球石油价格 | nan | +| PPE | 波兰电力交易所（TGE）数据 | nan | +| UKONS | 英国国家统计局数据 | 关于英国就业，投资，住房，家庭支出，国民账户和许多其他社会经济指标的数据。 | +| NCDEX | 国家商品及衍生品交易所（印度）数据 | 印度专业管理的在线多商品交易所 | +| WSE | 华沙证券交易所（GPW）数据 | nan | +| TFX | 东京金融交易所数据 | 东京金融交易所是一个期货交易所，主要交易金融工具市场，处理证券和市场衍生品。 | +| WGFD | 世界银行全球金融发展数据 | 有关金融系统特征的数据，包括金融机构和市场的规模，使用，获取，效率和稳定性的衡量标准。 | +| CEPEA | 应用经济学应用研究中心（巴西）数据 | CEPEA是圣保罗大学的一个经济研究中心，专注于农业企业问题，发布巴西商品价格指数。 | +| SBJ | 日本统计局数据 | 日本政府统计机构，提供有关就业和劳动力的统计数据。 | +| WGEM | 世界银行全球经济监测 | 关于全球经济发展的数据，涵盖高收入国家和发展中国家。 | +| WGDF | 世界银行全球发展金融 | 关于金融系统特征的数据，包括金融机构和市场的规模，使用，获取，效率和稳定性的衡量标准。 | +| WWDI | 世界银行世界发展指标 | 最新和最准确的发展指标，由官方认可的国际来源汇编而成。 | +| WESV | 世界银行企业调查 | 公司级私营部门数据，涵盖金融，腐败，基础设施，犯罪，竞争和绩效衡量等业务主题。 | +| WDBU | 世界银行存续商业数据 | 关于成员国和地方和区域一级选定城市的商业法规及其执法的数据。 | +| OSE | 大阪证券交易所数据 | 日本第二大证券交易所。与东京证券交易所不同，OSE在衍生品交易方面表现最为强劲，是日本的大多数期货和期权。 | +| RFSS | 俄罗斯联邦统计局数据 | 俄罗斯政府统计机构，负责在国家和地方层面发布俄罗斯的社会，经济和人口统计数据。 | +| SHFE | 上海期货交易所数据 | 大宗商品交换能源，金属和化学相关的工业产品。许多商品期货的衍生品市场。 | +| WGEP | 世界银行全球环境规划经济前景数据 | 关于全球经济的短期，中期和长期前景以及对发展中国家和减贫的影响的数据。 | +| USMISERY | 美国痛苦指数 | 由经济学家亚瑟·奥肯（Arthur Okun）开发的苦难指数是失业率加上通胀率。 | +| WJKP | 世界银行知识平台工作数据 | 与劳工有关的主题指标。 | +| WMDG | 世界银行千年发展目标数据 | 根据千年发展目标（MDGs）的目标和指标重新组织的世界发展指标数据。 | +| WPOV | 世界银行贫困统计 | 贫困人口比率，贫困差距以及国际和国家贫困线贫困人口数量的指标。 | +| EUREKA | Eurekahedge数据 | 一家研究公司专注于对冲基金和其他另类投资基金。它公布了对冲基金业绩的数据。 | +| MOFJ | 日本财务省数据 | 日本政府债券利率数据，由财政部每日公布。 | +| PIKETTY | Thomas Piketty数据 | “21世纪资本”中的收入和财富数据，哈佛大学出版社，2014。 | +| PSX | 巴基斯坦证交所数据 | 巴基斯坦证券交易所的股票收盘价格。 | +| SGX | 新加坡交易所数据 | 亚洲证券和衍生品交易所为许多大型新加坡和其他亚洲公司进行股票交易。在自己的交易所上市。 | +| UIFS | 联合国国际金融统计 | 该数据库提供有关国际财务指标的综合数据，如平均收入，债券收益率，政府收入和支出。 | +| UINC | 联合国工业商品数据 | 该数据库提供有关工业商品生产的全球数据，如矿石和矿物，食品，可运输货物和金属产品。 | +| INSEE | 国家统计和经济研究所（法国）数据 | INSEE是法国的国家统计机构。它收集有关法国经济和社会的数据，如社会经济指标和国民账户。 | +| SNB | 瑞士国家银行数据 | 中央银行负责货币政策和货币。有关国际账户，利率，货币供应和其他宏观经济指标的数据。 | +| ODE | 大阪道岛商品交易所数据 | 日本关西地区的一个非营利性商品交易所，交易七种主要农产品。 | +| WGEN | 世界银行性别统计 | 描述收入，工作类型，工作部门，农民生产率以及企业家公司规模和利润的性别差异的数据。 | +| WHNP | 世界银行健康营养与人口统计 | 关键的健康，营养和人口统计数据。 | +| WIDA | 世界银行国际发展协会 | 关于选定指标的IDA（国际开发协会）国家总体成果进展情况的数据。 | +| ECMCI | 欧盟委员会货币状况指数 | 每月更新，此数据库提供欧元区的货币状况指数值。历史可以追溯到1999年。 | +| NBSC | 中国国家统计局数据 | 中国有关金融，工业，贸易，农业，房地产和交通运输的统计数据。 | +| MAS | 新加坡金融管理局数据 | nan | +| MGEX | 明尼阿波利斯谷物交易所数据 | 促进农业指数贸易的区域商品期货和期权合约市场。 | +| WWGI | 世界银行全球治理指标 | 六个治理层面的总体和个别治理指标数据。 | +| ISM | 供应管理研究所 | ISM促进供应链管理实践，并发布有关生产和供应链，新订单，库存和资本支出的数据。 | +| UKR | 乌克兰交易所数据 | nan | +| FRBNY | 纽约联邦储备银行数据 | FRBNY是美国最大的区域中央银行。为纽约，康涅狄格州和新泽西州的大部分地区以及一些地区设定货币政策。 | +| FRBP | 费城联邦储备银行数据 | FRBP是美联储的区域中央银行。它发布有关商业信心指数，GDP，消费和其他经济指标的数据。 | +| FMSTREAS | 美国财政部 - 财务管理处数据 | 美利坚合众国的月收入/支出和赤字/盈余。 | +| EIA | 美国能源信息管理局数据 | 美国国家和州有关所有主要能源产品（如电力，煤炭，天然气和石油）的生产，消费和其他指标的数据。 | +| SOCSEC | 美国社会保障局数据 | 提供有关美国社会保障计划的数据，特别是受益人的人口统计数据;残疾人，老人和幸存者。 | +| TFGRAIN | 顶级飞行谷物合作社数据 | 玉米和大豆的现货价格，包括前月期货合约的基础。 | +| IRPR | 波多黎各统计研究所数据 | 波多黎各统计研究所制造业统计数据。 | +| BCHAIN | blockchain.com数据 | Blockchain是一个发布与比特币相关的数据的网站，每日更新。 | +| BITCOINWATCH | Bitcoin Watch数据 | 比特币采矿统计。 | +| ODA | 国际货币基金组织跨国宏观经济统计 | 国际货币基金组织的初级商品价格和世界经济展望数据，由非洲开放数据公布。优秀的跨国宏观经济数据。 | +| WADI | 世界银行非洲发展指标 | 关于非洲的一系列发展指标，包括国家，区域和全球估计数。 | +| WEDU | 世界银行教育统计 | 关于教育机会，进展，完成，扫盲，教师，人口和支出的国际可比指标。 | +| WGLF | 世界银行全球Findex（全球金融包容性数据库） | 关于人们如何储蓄，借贷，支付和管理风险的金融包容性指标。 | +| WWID | 世界财富和收入数据库 | 世界财富和收入数据库旨在提供开放和便捷的途径，以获取有关国家内部和国家之间世界收入和财富分配历史演变的最广泛的现有数据库。 | +| BTER | 比特儿数据 | 加密货币的历史汇率数据。 | +| CFTC | 商品期货交易委员会报告 | 交易员和集中比率的每周承诺。期货头寸以及期货加期权头寸的报告。新旧格式。 | +| BOE | 英格兰银行官方统计 | 当前和历史汇率，担保贷款和定期存款利率，欧元商业票据利率和政府证券收益率。 | +| EXMPL | Quandl时间序列数据示例 | 一个时间序列数据库示例。 | +| WORLDAL | 铝价格 | 世界铝产能和产量（千公吨）。 | +| WGC | 黄金价格 | 世界黄金协会是黄金行业的市场开发组织。它以不同货币发布黄金价格数据。 | +| MX | 加拿大期货数据 | 蒙特利尔交易所是一家衍生品交易所，交易期货合约以及股票，指数，货币，ETF，能源和利率的期权。 | +| UMICH | 消费者情绪 | 密歇根大学的消费者调查 - 最近6个月的数据点是非官方的;它们来自华尔街日报的文章。 | +| JOHNMATT | 稀有金属价格数据 | 关于铂族金属的当前和历史数据，如价格，供应和需求。 | +| NAHB | 美国住房指数 | 美国的住房和经济指数。 | +| RATEINF | 通货膨胀率 | 阿根廷，澳大利亚，加拿大，德国，欧元区，法国，意大利，日本，新西兰等国的通货膨胀率和消费物价指数CPI。 | +| RENCAP | IPO数据 | 有关美国IPO市场的数据。 | +| ML | 公司债券收益率数据 | 美林（Merrill Lynch）是美国一家大型银行，它发布了不同地区公司债券收益率的数据。 | +| MULTPL | S&P 500 | nan | +| RICI | 商品指数 | 综合，以美元为基础的总回报指数，代表全球经济中消费的一篮子商品的价值。 | +| AAII | 投资者情绪 | 美国个人投资者协会的情绪数据。 | +| BIS | 国际清算银行数据 | 国际清算银行为中央银行提供货币和金融稳定管理，促进国际合作，并作为中央银行的银行。 | +| BCB | 巴西中央银行统计数据库 | 巴西宏观经济数据，涵盖公共财政，国民账户，支付系统，通货膨胀，汇率，贸易和国际储备。 | +| BCRA | 阿根廷中央银行数据 | 阿根廷中央银行负责货币政策，提供外汇市场数据和主要宏观经济指标。 | +| FSE | 法兰克福证券交易所 | 法兰克福证券交易所的每日股票价格 | +| BLSN | 劳工统计局国际数据 | 各国的进出口价格统计，由劳工统计局公布。 | +| BLSP | 劳工统计局生产力数据 | 美国制造业，劳务和商业统计，由劳工统计局公布。 | +| FDIC | 联邦存款保险公司数据 | FDIC是一家银行存款高达25万美元的联邦保险公司，负责收集商业银行和储蓄机构的财务数据。 | +| BLSI | 美国劳工统计局通货膨胀和价格统计 | 美国国家和州一级的通胀数据，由劳工统计局公布。 | +| BLSE | 美国劳工统计局就业与失业统计 | 美国国家和州一级的就业和失业统计数据，由劳工统计局公布。 | +| BLSB | 美国劳工统计局薪酬福利统计 | 由劳工统计局公布的美国停工统计数据。 | +| BP | BP能源生产和消费数据 | BP是一家大型能源生产商和分销商。它提供了各个国家和较大次区域的能源生产和消费数据。 | +| LPPM | 白金和钯价格数据 | 全球钯金和铂金市场清算价格数据。 | +| CASS | 运费指数 | 自1990年以来，CASS每月提供与其他经济和供应链指标相关的货运趋势的CASS运费指数报告。 | +| MORTGAGEX | 可调利率抵押贷款指数 | ARM索引的历史住房数据。 | +| BUCHARESTSE | 布加勒斯特证券交易所数据 | 布加勒斯特证券交易所发布股票，权利，债券，基金单位，结构性产品和期货合约活动数据。 | +| AMECO | 欧盟委员会年度宏观经济数据库 | 欧洲委员会经济和财政事务总局（DG ECFIN）年度宏观经济数据库。 | +| ACC | 美国化学理事会数据 | 化学活性晴雨表（CAB）由美国化学理事会（ACC）出版。 CAB是一个经济指标，有助于预测整个美国经济的高峰和低谷，并突出了美国其他行业的潜在趋势。 | +| ABMI | 亚洲债券市场计划 | 中国和日本债券市场的指标，如规模和构成，市场流动性，收益率收益率和波动率。 | +| BITAL | 意大利证交所数据 | 该数据库提供了Borsa Italiana（现为伦敦证券交易所集团的一部分）的股票期货合约数据。 | +| BANKRUSSIA | 俄罗斯银行数据 | 俄罗斯银行的主要指标，包括银行业，货币供应量，金融市场和宏观经济统计数据。 | +| BOC | 加拿大银行统计数据库 | 加拿大的经济，金融和银行数据。包括利率，通货膨胀，国民账户等。每日更新。 | +| HKEX | 香港交易所数据 | 香港交易所股票价格，历史分割期货等每日更新。 | +| AMFI | 印度共同基金协会数据 | 该数据库代表印度共同基金协会的基金信息。 | +| BDM | 墨西哥银行数据 | 墨西哥银行负责货币政策和本国货币（比索），并提供账户和所有宏观经济变量的数据。 | +| BATS | BATS美国证券交易所数据 | Bats是美国的股票市场运营商，经营四个股票交易所--BZX Exchange，BYX Exchange，EDGA Exchange和EDGX Exchange | +| BSE | 孟买证券交易所数据 | 在印度孟买证券交易所交易的公司的日终价格，指数和其他信息。 | +| FRED | 美联储经济数据 | 来自圣路易斯联邦储备银行研究部门的增长，就业，通货膨胀，劳工，制造业和其他美国经济统计数据。 | +| FMAC | 房地美数据 | Freddie Mac的主要抵押贷款市场调查和其他地区特定历史抵押贷款利率的数据。 | +| EUREX | 欧洲期货交易所数据 | 欧洲最大的期货交易所EUREX的指数，利率，农业和能源期货，历史跨越了特定期货的十年。 | +| ECB | 欧洲中央银行数据 | 欧盟中央银行监督货币政策和欧元，并提供相关宏观经济变量的数据。 | +| BOF | 法国银行数据 | 法兰西银行通过欧洲中央银行体系的政策负责货币政策，并提供关键经济指标的数据。 | +| BELGRADESE | 贝尔格莱德证券交易所数据 | 贝尔格莱德证券交易所数据，每日更新。 | +| CHRIS | 维基连续期货 | Quandl所有600个期货的连续合约。建立在CME，ICE，LIFFE等原始数据之上。由Quandl社区策划。 50年的历史。 | +| BOJ | 日本银行数据 | nan | +| USTREASURY | 美国财政部数据 | 美国财政部确保国家的金融安全，管理国家债务，收取税收，发行货币，提供收益率数据。 | +| LBMA | 伦敦金银市场协会数据 | 伦敦黄金和白银市场的国际贸易协会，由中央银行，私人投资者，生产商，炼油商和其他代理商组成。 | +| PERTH | 珀斯铸币厂数据 | 珀斯造币厂的利率和商品价格的高点，低点和平均值每月更新一次。 | +| ZILLOW2 | Zillow房地产研究 | 房屋价格和租金按大小，类型和等级划分;住房供应，需求和销售。按邮政编码，街区，城市，都市区，县和州切片。 | \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/quickstart.md b/website/translated_docs/zh-CN/version-0.3.0/quickstart.md new file mode 100644 index 0000000..6551a16 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/quickstart.md @@ -0,0 +1,148 @@ +--- +id: version-0.3.0-quickstart +title: '🌏 TestNet 快速开始' +original_id: quickstart +--- +## CovenantSQL 工具包 + +### 工具包简介 + +请根据您使用的操作系统平台选择 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。 + +例如，您使用的是： + +- MacOS 平台请下载：[**CovenantSQL-v0.3.0.osx-amd64.tar.gz**](https://github.com/CovenantSQL/CovenantSQL/releases/download/v0.3.0/CovenantSQL-v0.3.0.osx-amd64.tar.gz) +- Linux 平台请下载：[**CovenantSQL-v0.3.0.linux-amd64.tar.gz**](https://github.com/CovenantSQL/CovenantSQL/releases/download/v0.3.0/CovenantSQL-v0.3.0.linux-amd64.tar.gz) +- Windows 平台我们稍后发布，有需求请戳这里：[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/CovenantSQL/CovenantSQL) + +解压之后，你将得到以下命令行工具，包括：`cql`、`cql-utils` 等。 + +| 工具名 | 介绍 | +| ---------- | --------------------------------------------------- | +| cql | CovenantSQL 的客户端，类似 mysql 命令，用于执行 SQL | +| cql-utils | CovenantSQL 工具箱，用于和主链交互 | +| cql-minerd | CovenantSQL 矿工客户端，用于运行数据库赚取奖励，以后会开放加入 | +| cqld | CovenantSQL 主链节点，主要由 CovenantLabs 以及合作伙伴以 DPoS 模式运行 | + +### 测试网快速接入 + +目前，我们已经发布了测试网 v0.3.0，供大家进行原理性验证和体验。你可以选在使用公共的测试账号快速进行接入测试。 + +测试账号的配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) ，或者使用以下命令： + +```bash +mkdir conf +wget https://git.io/fhFZe -O conf/config.yaml +wget https://git.io/fhFZv -O conf/private.key +chmod 600 conf/private.key +``` + +**测试网注**： + +> 该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放你的应用信息，我们会不定期清理数据库数据。 +> +> 测试网暂时由 3 个 Miner 组成，所以暂时最大只支持`create 3`创建 3 个节点组成的数据库。 + +## 创建并访问 CovenantSQL 数据库 + +### 创建数据库 + +```shell +./cql -config conf/config.yaml -create 1 +``` + +输出： + + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + + +这里表示你提交了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库的创建请求到主链。 + +> 我们需要等待大概 30s 的时间，等待数据库创建，大致过程为： +> +> 1. 收到请求的 出块节点（Block Producer）进行 Miner 和数据库创建请求的撮合 +> 2. 数据库创建请求在 其它出块节点 进行验证和确认 +> 3. SQLChain 的符合条件的 Miner 收到数据库任务 +> 4. SQLChian 组建 Kayak 数据库集群 +> 5. 所有 Miner 准备就绪等待请求 + +### 访问数据库 + +```shell +./cql -config conf/config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，你可以按你操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 数据库 SDK + +- [Golang 开发指引](./development) + +## SQLChain 区块浏览器 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，你可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。 + +> 测试网的`区块浏览器`目前是开放权限的，所以任何知道数据库 ID 的人都能看到您的数据 + +查询时，请在其页面右上角填入你的数据库 ID。例如：`0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` + +## 创建账号 + +我们的测试网支持你创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（会询问设置主密码，测试期间建议直接回车留空）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你在~目录下创建一个 `.cql` 目录： + +- `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private ~/.cql/private.key +``` + +输出： + +```toml +wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 +``` + +你可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入你生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为你的钱包充值。有任何问题请来这里讨论：[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/CovenantSQL/CovenantSQL) + +使用 cql 命令行工具查询余额(未加 -config 参数时，命令会自动找 ~/.cql 目录的 config.yaml 文件)： + +```shell +./cql -config ~/.cql/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +恭喜，你已收到我们发出的 PTC 稳定币，现在即可开始使用 CovenantSQL， 你可以参考 [Golang 使用 CovenantSQL 文档](./development) 进行开发。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.3.0/usecase.md b/website/translated_docs/zh-CN/version-0.3.0/usecase.md new file mode 100644 index 0000000..6e7c4ed --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.3.0/usecase.md @@ -0,0 +1,6 @@ +--- +id: version-0.3.0-usecase +title: 使用案例 +original_id: usecase +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/api.md b/website/translated_docs/zh-CN/version-0.4.0/api.md new file mode 100644 index 0000000..f124f52 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/api.md @@ -0,0 +1,6 @@ +--- +id: version-0.4.0-api +title: '👩🏻‍💻 CovenantSQL API' +original_id: api +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/bck/api-json-rpc.md b/website/translated_docs/zh-CN/version-0.4.0/bck/api-json-rpc.md new file mode 100644 index 0000000..3491c49 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/bck/api-json-rpc.md @@ -0,0 +1,442 @@ +--- +id: version-0.4.0-api-json-rpc +title: JSON RPC +original_id: api-json-rpc +--- +> JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. + +CovenantSQL provides a suite of RPC methods in [JSON-RPC 2.0](https://www.jsonrpc.org/specification) for easily accessing to CovenantSQL networks. + +## Javascript API + +[cql.js](https://github.com/covenantsql/cql.js) is a Javascript SDK which has encapsulated the RPC methods in order to give a much more convenient way to talk to the CovenantSQL networks. See the [Javascript API](cql-js.md) for more. + +## JSON RPC Endpoint + +| Network | Provider | URL | +| ------------------------ | ------------- | -------------------------------------- | +| CovenantSQL Test Network | Covenant Labs | https://jsonrpc.testnet.covenantsql.io | +| CovenantSQL Main Network | Covenant Labs | Comming soon :) | + +## JSON RPC API Reference + +### bp_getProtocolVersion + +Returns the current CovenantSQL protocol version. + +#### Parameters + +None. + +#### Returns + +- string - the current CovenantSQL protocol version + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "method": "bp_getProtocolVersion", + "params": [], + "id": 1 +} +``` + +Response: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0.1.0" +} +``` + +### bp_getRunningStatus + +Returns some basic indicators describing the running status of the CovenantSQL network. + +#### Parameters + +None. + +#### Returns + +- object: an object describes the running status of the network. + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getRunningStatus", + "params": [] +} +``` + +Response: + +```js +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "block_height": 182414, // height of the latest block + "count_accounts": 103, // count of the accounts ever created + "count_shardchains": 912414, // count of the databases ever created + "qps": 10241 // estimated QPS of database operations of the whole net + "storage_size": 109870095269 // storage size + } +} +``` + +### bp_getBlockList + +Returns a list of the blocks. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ----- | ------- | ---------------------- | ------ | +| 0 | since | integer | since height, excluded | 1024 | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the blocks, the object in the list is a [Block](#s-block), but **without** transaction details + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockList", + "params": [1024, 1, 10] +} +``` + +Response: [Block](#s-block) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "blocks" [ { TODO: block object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 102, + "pages": 11 + } +} +``` + +### bp_getBlockListByTimeRange + +TODO: as a new API in the next release + +### bp_getBlockByHeight + +Returns information about the block specified by its height. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | height of the block | 1024 | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHeight", + "params": [1] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getBlockByHash + +Returns information about the block specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------- | ------ | +| 0 | hash | string | hash of the block | "TODO" | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHash", + "params": ["TODO"] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getTransactionList + +Returns a list of the transactions. Traverse page by page by using a transaction hash as the mark for paging. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ----- | ------- | -------------------- | ------ | +| 0 | since | string | since hash, excluded | "TODO" | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionList", + "params": ["KhytGjS0xjw5CJvcJYpsNg", 1, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "transactions": [ { TODO: transaction object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 8, + "pages": 1 + } + } +} +``` + +### bp_getTransactionListOfBlock + +Returns a list of the transactions from a block by the specified height. + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | of block height | 1024 | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionListOfBlock", + "params": [1024, 1, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "transactions": [ { TODO: transaction object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 8, + "pages": 1 + } + } +} +``` + +### bp_getTransactionByHash + +Returns information about the transaction specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------------- | ------ | +| 0 | hash | string | hash of the transaction | "TODO" | + +#### Returns + +- object: transaction information object, it's a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionByHash", + "params": ["TODO"] +} +``` + +Response: [Transaction](#s-transaction) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: transaction object + } +} +``` + +## Structure Reference + +Here are some common structure definitions used in the API. + + + +### Block + +The block generated in the CovenantSQL blockchain network. + +| Field | Type | Description | +| --------------- | ------- | ------------------------------------------------------- | +| height | integer | Height of the block | +| hash | string | Hash of the block | +| version | integer | Version number of the block | +| producer | string | Address of the node who generated this block | +| merkle_root | string | Hash of the merkle tree | +| parent | string | Hash of its parent block | +| timestamp | integer | Create time of the block, unix time in nanoseconds | +| timestamp_human | string | Create time of the block, human readable RFC3339 format | +| tx_count | integer | Count of the transactions in this block | + +Sample in JSON format: + +```json +{ + "height": 12, + "hash": "TODO", + "version": 1, + "producer": "4io8u9v9nydaQPXtmqibg8gJbkNFd7DdM47PLWuM7ubzBXZ4At7", + "merkle_root": "TODO", + "parent": "TODO", + "timestamp": "TODO", + "timestamp_human": "TODO", + "tx_count": 1 +} +``` + + + +### Transaction + +| Field | Type | Description | +| --------------- | ------- | ------------------------------------------------------------------------------------------- | +| block_height | integer | Height of the block this transaction belongs to | +| index | integer | Index of the transaction in the block | +| hash | string | Hash of the transaction data | +| block_hash | string | Hash of the block this transaction belongs to | +| type | integer | Type of the transaction | +| address | string | Account address who signed this transaction | +| timestamp | integer | Create time of the transaction, unix time in nanoseconds | +| timestamp_human | string | Create time of the transaction, human readable RFC3339 format | +| raw | string | Raw content of the transaction data, in JSON format | +| tx | object | Concrete transaction object, see supported [transaction types](#transaction-types) for more | + +Sample in JSON format: + +```json +{ + "block_height": 1, + "index": 0, + "hash": "TODO", + "block_hash": "TODO", + "timestamp": "TODO", + "timestamp_human": "TODO", + "type": 1, + "address": "TODO", + "raw": "TODO", + "tx": { + "field": "TODO" + } +} +``` + +**Supported Transaction Types:** + +- [CreateDatabase](#s-transaction-createdatabase) + +TODO: more types + + + +### Transaction: CreateDatabase + +TODO: more types \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/bck/development-cmd-cql-utils-zh.md b/website/translated_docs/zh-CN/version-0.4.0/bck/development-cmd-cql-utils-zh.md new file mode 100644 index 0000000..88329cb --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/bck/development-cmd-cql-utils-zh.md @@ -0,0 +1,41 @@ +--- +id: version-0.4.0-keygen +title: 使用 cql-utils 生成密钥与钱包 +original_id: keygen +--- +`cql-utils` 是 CovenantSQL 的一个命令行工具，具体用法如下。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 使用 + +### 生成公私钥对 + + $ cql-utils -tool keygen + Enter master key(press Enter for default: ""): + ⏎ + Private key file: private.key + Public key's hex: 03bc9e90e3301a2f5ae52bfa1f9e033cde81b6b6e7188b11831562bf5847bff4c0 + + +生成的 private.key 文件即是使用主密码加密过的私钥文件，而输出到屏幕上的字符串就是使用十六进制进行编码的公钥。 + +### 使用私钥文件或公钥生成钱包地址 + + $ cql-utils -tool addrgen -private private.key + Enter master key(default: ""): + ⏎ + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + $ cql-utils -tool addrgen -public 02f2707c1c6955a9019cd9d02ade37b931fbfa286a1163dfc1de965ec01a5c4ff8 + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + + +你可以通过指定私钥文件，或者把上述的公钥十六进制编码字符串作为命令行参数来直接生成钱包地址。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/bck/development-cmd-cql-zh.md b/website/translated_docs/zh-CN/version-0.4.0/bck/development-cmd-cql-zh.md new file mode 100644 index 0000000..d2fe9ab --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/bck/development-cmd-cql-zh.md @@ -0,0 +1,77 @@ +--- +id: version-0.4.0-cql +title: 使用命令行客户端 cql 创建数据库 +original_id: cql +--- +本文档主要介绍 CovenantSQL 命令行客户端 `cql` 的使用。`cql` 是一个用于批量进行 SQLChain 上数据库的创建、查询、更新或删除操作的命令行工具。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 生成默认配置文件 + +首先需要一个 config 文件和由你输入的主密码（master key）来初始化，其中主密码用来加密解密本地密钥对。使用 `cql-utils` 工具进行配置文件生成后，你可以在生成的配置文件目录下找到密钥文件。 + +具体请参考: [cql-utils 使用文档](https://github.com/CovenantSQL/docs/tree/master/development-cmd-utils-zh.md#使用) 中配置文件及钱包地址生成相关章节。 + +## 检查钱包余额 + +使用 `cql` 命令来检查钱包余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] +### Public Key ### +0388954cf083bb6bb2b9c7248849b57c76326296fcc0d69764fc61eedb5b8d820c +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +这里我们得到结果 **"stable coin balance is: 100"**。 + +## 初始化一个 CovenantSQL 数据库 + +准备好配置文件和主密码后就可以使用 `cql` 命令来创建数据库了，你的数据库 ID 将会输出到屏幕上： + +```bash +# if a non-default password applied on master key, use `-password` to pass it +$ cql -config conf/config.yaml -create 1 +INFO[0000] +### Public Key ### +039bc931161383c994ab9b81e95ddc1494b0efeb1cb735bb91e1043a1d6b98ebfd +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] the newly created database is: covenantsql://0e9103318821b027f35b96c4fd5562683543276b72c488966d616bfe0fe4d213 caller="main.go:297 main.main" +``` + +这里 `-create 1` 表示创建一个单节点的 SQLChain。 + +```bash +$ cql -config conf/config.yaml -dsn covenantsql://address +``` + +`address` 就是你的数据库 ID。 + +`cql` 命令的详细使用帮助如下： + +```bash +$ cql -help +``` + +## 使用 `cql` + +现在可以使用 `cql` 进行数据库操作了: + +```bash +co:address=> show tables; +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/bck/development-golang-client-zh.md b/website/translated_docs/zh-CN/version-0.4.0/bck/development-golang-client-zh.md new file mode 100644 index 0000000..68d800f --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/bck/development-golang-client-zh.md @@ -0,0 +1,108 @@ +--- +id: version-0.4.0-golang-client +title: 使用 Golang 驱动访问数据库 +original_id: golang-client +--- +本文档介绍 CovenantSQL 客户端的使用方式。客户端用来创建、查询、更新和删除 SQLChain 以及绑定的数据库。 + +## 开始之前 + +确保 `$GOPATH/bin` 目录在环境变量 `$PATH` 中，执行以下命令 + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +然后在你的 go 代码中 import 第一个 `client` 包。 + +## 初始化一个 CovenantSQL 客户端 + +首先需要一个 config 文件和 master key 来初始化。master key 用来加密解密本地密钥对。以下是如何用一个自定义 master key 来生成默认的 config 文件： + +### 生成默认的配置文件 + +运行以下 `cql-utils` 命令，输入 master key（类似密码）来生成本地密钥对。等待几十秒，会在 `~/.cql` 文件夹中，生成一个私钥文件和一个名为 `config.yaml` 的配置文件。 + +```bash +./cql-utils -tool confgen +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: ~/.cql/private.key +Public key's hex: 025abec9b0072615170f4acf4a2fa1162a13864bb66bc3f140b29f6bf50ceafc75 +Generated key pair. +Generating nonce... +INFO[0005] cpu: 1 +INFO[0005] position: 0, shift: 0x0, i: 0 +nonce: {{1450338416 0 0 0} 26 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514} +node id: 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514 +Generated nonce. +Generating config file... +Generated nonce. +``` + +有了配置文件之后，可以通过以下 go 代码来初始化 CovenantSQL 客户端： + +```go +client.Init(configFile, masterKey) +``` + +## 客户端使用方式 + +### 创建一个 SQLChain 数据库 + +创建 SQLChain 数据库需要指明需要几个节点（nodeCount变量）: + +```go +var ( + dsn string + meta client.ResourceMeta +) +meta.Node = uint16(nodeCount) +dsn, err = client.Create(meta) +// process err +``` + +创建完毕会返回一个 dsn 字符串，用来访问这个数据库。 + +### 查询和执行 + +拿到 dsn 字符串后，可以通过以下代码在 SQLChain 中执行 SQL 语句： + +```go +
db, err := sql.Open("covenantsql", dsn) + // process err + + _, err = db.Exec("CREATE TABLE testSimple ( column int );") + // process err + + _, err = db.Exec("INSERT INTO testSimple VALUES(?);", 42) + // process err + + row := db.QueryRow("SELECT column FROM testSimple LIMIT 1;") + + var result int + err = row.Scan(&result) + // process err + fmt.Printf("SELECT column FROM testSimple LIMIT 1; result %d\n", result) + + err = db.Close() + // process err + +``` + +用法和其他 go sql driver 一致。 + +### 删除数据库 + +使用 dsn 来删除数据库： + +```go + err = client.Drop(dsn) + // process err +``` + +### 完整示例 + +在以下目录中有一个简单示例和复杂示例可以参考 [示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/bck/getting-started-overview-zh.md b/website/translated_docs/zh-CN/version-0.4.0/bck/getting-started-overview-zh.md new file mode 100644 index 0000000..5573dce --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/bck/getting-started-overview-zh.md @@ -0,0 +1,63 @@ +--- +id: version-0.4.0-intro +title: 简介 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +- **SQL**: 支持 SQL-92 标准 +- **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +- **隐私**: 通过加密和授权许可进行访问 +- **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信[在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +#### 一行代码接入区块链数据 + +```go +sql.Open("CovenantSQL", dbURI) +``` + +# # + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +- 第一层: **全局共识层**(主链，架构图中的中间环): + - 整个网络中只有一个主链。 + - 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +- 第二层: **SQL 共识层**(子链，架构图中的两边环): + - 每个数据库都有自己独立的子链。 + - 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +- 第三层: **数据储存层**(支持 SQL-92 的数据库引擎): + - 每个数据库都有自己独立的分布式引擎。 + - 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/bck/getting-started-testnet-zh.md b/website/translated_docs/zh-CN/version-0.4.0/bck/getting-started-testnet-zh.md new file mode 100644 index 0000000..e4c0d49 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/bck/getting-started-testnet-zh.md @@ -0,0 +1,96 @@ +--- +id: version-0.4.0-testnet +title: CovenantSQL 测试网快速入门 +original_id: testnet +--- +[CovenantSQL](https://github.com/CovenantSQL/CovenantSQL/blob/develop/README-zh.md) 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +1. **SQL**: 支持 SQL-92 标准 +2. **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +3. **隐私**: 通过加密和授权许可进行访问 +4. **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## 0. 下载 CovenantSQL 工具 + +在 [github](https://github.com/CovenantSQL/CovenantSQL/releases) 下载最新的发行版 + +## 1. 用 `cql-utils` 生成配置文件访问测试网 + +```bash +$ cql-utils -tool confgen +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: ~/.cql/private.key +Public key's hex: 02296ea73240dcd69d2b3f1fb754c8debdf68c62147488abb10165428667ec8cbd +Generated key pair. +Generating nonce... +nonce: {{731613648 0 0 0} 11 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9} +node id: 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9 +Generated nonce. +Generating config file... +Generated nonce. +``` + +该命令会为你在~目录下创建一个 `.cql` 目录： + +- `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +## 2. 用私钥生成钱包地址 + +私钥可以再上一步的 `~/.cql` 目录中找到，文件名为 `private.key` + +```bash +$ cql-utils -tool addrgen -private ~/.cql/private.key +Enter master key(default: ""): +⏎ +wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 +``` + +上述 `4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9` 就是钱包地址 + +## 3. 在水龙头(Faucet)获取 Particle(PTC) + +水龙头(Faucet)的地址为: [CovenantSQL 测试网 Particle(PTC) 水龙头](https://testnet.covenantsql.io/)。 + +完成教程之后，用 `cql` 命令来检查钱包地址的余额(未加-config参数时，命令会自动找~/.cql目录的config.yaml文件)： + +```bash +$ cql -get-balance +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +当看到 **"stable coin balance is: 100"** 时，表明余额已经为 100。 + +如果您需要更多的 PTC 作为长期测试使用，请联系 。 + +对于有合作的商业伙伴，我们将直接提供 PTC 以供使用。 + +## 4. 使用 `CLI` 创建数据库 + +```bash +$ cql -create 1 +INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" +``` + +第一行命令中的 `1` 表示申请几个矿工为你的数据库服务。`covenantsql://...` 开头的这个字符串就是创建的数据库访问地址，在 SDK 和 CLI 命令中都需要用此地址，在整个区块链中找到这个数据库。 + +## 5. CLI 和 SDK 的详细文档 + +创建好数据库后，您可以参考以下文档和示例，以便更快的使用CovenantSQL来开发应用。 + +- [CLI 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql/README-zh.md) +- [SDK 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/README-zh.md) +- [SDK 示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) + +## 6. SQLChain 浏览器 + +目前，测试网的数据库时不需要权限的。意味着您可以通过数据库的DSN(数据库访问地址)，在[SQLChain 浏览器](https://explorer.dbhub.org)中拿到所有的修改历史和区块信息。 + +更多的测试网技术支持，请访问: + +> [TestNet 发行日志](https://github.com/CovenantSQL/CovenantSQL/wiki/Release-Notes-zh) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/bck/getting-started-zh.md b/website/translated_docs/zh-CN/version-0.4.0/bck/getting-started-zh.md new file mode 100644 index 0000000..0a86826 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/bck/getting-started-zh.md @@ -0,0 +1,486 @@ +--- +id: version-0.4.0-local-deployment +title: CovenantSQL 综述 +original_id: local-deployment +--- +# CovenantSQL 介绍 + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可变成 ĐApp +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是用户的钱包，那么 CovenantSQL 就是是用户的去中心化数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密 保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 + +# 安装 CovenantSQL 客户端 + +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +* [Go](./development-golang-client-zh.md) +* [Java](https://github.com/CovenantSQL/covenant-connector) +* [Python](https://github.com/CovenantSQL/python-driver) +* [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你在~目录下创建一个 `.cql` 目录： + +* `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +* `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private ~/.cql/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额(未加 -config 参数时，命令会自动找 ~/.cql 目录的 config.yaml 文件)： + +```shell +./cql -config ~/.cql/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +* [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 + +# 部署 CovenantSQL + +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 启动 Docker 容器 + +执行以下的命令在本地运行 CovenantSQL + +```shell +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +make docker +make start +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行`export COVENANTSQL_ROOT=$PWD`存为环境变量 + +### 检查运行状态 + +```shell +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp +covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp +covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp +covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp +covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp +``` + +### SQLChain Observer + +我们在`:11108`端口提供了一个 SQLChain 的 Observer 可以看到 SQL 语句在链上的情况 + +# 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +cql -config config/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +cql -config config/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +cql -config config/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +# 使用 CovenantSQL 开发 App + +## Golang 使用 CovenantSQL + +#### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +#### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +#### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +#### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +#### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` + +# CovenantSQL API + +# 常见问题解答 + +补充 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/bck/guide-zh.md b/website/translated_docs/zh-CN/version-0.4.0/bck/guide-zh.md new file mode 100644 index 0000000..5b25df1 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/bck/guide-zh.md @@ -0,0 +1,114 @@ +--- +id: version-0.4.0-guide-zh +title: 快速开始 +original_id: guide-zh +--- +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```shell +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```shell +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +- [Go](./development-golang-client-zh.md) +- [Java](https://github.com/CovenantSQL/covenant-connector) +- [Python](https://github.com/CovenantSQL/python-driver) +- [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你在~目录下创建一个 `.cql` 目录： + +- `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private ~/.cql/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额(未加 -config 参数时，命令会自动找 ~/.cql 目录的 config.yaml 文件)： + +```shell +./cql -config ~/.cql/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +- [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/cql.md b/website/translated_docs/zh-CN/version-0.4.0/cql.md new file mode 100644 index 0000000..a934859 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/cql.md @@ -0,0 +1,203 @@ +--- +id: version-0.4.0-cql +title: '🖥️ CQL 命令行工具' +original_id: cql +--- +## 简介 + +本文将介绍如何使用 `cql` 进行查询、转账和数据库权限管理。在使用 `cql` 前请先确认已接入 [CovenantSQL TestNet](quickstart) 或者在本地使用 [Docker 一键部署](development)的网络。 + +## 查询余额 + +查询余额有两个命令：`cql -get-balance` 和 `cql -token-balance `。其中 `-get-balance` 将返回用户账户中 `Particle` 与 `Wave` 的数量，`-token-balance ` 将返回用户账户中特定 `token_type` 的 token 数量。目前系统支持的 `token_type` 有： + +- `Particle` +- `Wave` +- `Bitcoin` +- `Ether` +- `EOS` + +查看默认余额： + +```bash +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] Particle balance is: 10000000000000000000 + INFO[0000] Wave balance is: 10000000000000000000 + + +查看 Particle 余额： + +```bash +./cql -config conf/config.yaml -token-balance Particle +``` + +输出： + + INFO[0000] Particle balance is: 10000000000000000000 + + +查看 Bitcoin 余额： + +```bash +./cql -config conf/config.yaml -token-balance Bitcoin +``` + +输出： + + INFO[0000] Bitcoin balance is: 0 + + +## 转账 + +转账操作使用 `cql -transfer` 并以 `json` 格式的转账信息为参数。 + +```json +{ + "addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // 收款地址 + "amount":"1000000 Particle" // 转账金额并带上单位 +} +``` + +其中收款地址可以是一个个人钱包地址也可以是一个数据库子链地址。转账至数据库地址时将在该数据库账户上补充付款人的押金与预付款。 + +转账 Particle： + +```bash +./cql -config conf/config.yaml -transfer '{"addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount":"1000000 Particle"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +转账 Wave： + +```bash +./cql -config conf/config.yaml -transfer '{"addr":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount":"1000000 Wave"}' +``` + + INFO[0000] succeed in sending transaction to CovenantSQL + + +查看余额： + +```bash +./cql -config conf/config.yaml -get-balance +``` + +输出： + + INFO[0000] Particle balance is: 9999999999999000000 + INFO[0000] Wave balance is: 9999999999999000000 + + +注意，`succeed in sending transaction to CovenantSQL` 只说明交易已成功发送至主网，交易能否成功、何时成功需要通过 `-get-balance` 或者 `-token-balance ` 确定。 + +## 数据库权限管理 + +#### 访问权限 + +CovenantSQL 数据库有三类库级别权限： + +- `Admin` +- `Write` +- `Read` +- `Void` + +其中，`Admin` 可以赋予其他钱包地址数据库的权限（`Admin`、`Write` 或 `Read`）；`Admin` 和 `Write` 可以对数据库进行写操作（`CREATE`, `INSERT` 等）；`Admin` 和 `Read` 可以对数据库进行读操作（`SHOW`, `SELECT` 等）；如果需要设置用户有读写权限但是不能修改其他用户或自己的权限，可以将权限设置为 `Read,Write`；`Void` 是一个特殊的权限，当 `Admin` 想取消某个地址的权限时可以将该地址的权限设置为 `Void`，这样该地址将无法继续读写数据库。创建数据库的地址的权限默认为 `Admin`。若 `Admin` 需要赋予他人权限请使用 `cql -update-perm` 并以 `json` 格式的权限信息为参数： + +```json +{ + "chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", // 需要进行权限变更的数据库地址 + "user":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // 需要赋予权限的钱包地址 + "perm":"Write" // 权限内容 +} +``` + +增加写权限： + +```bash +./cql -config conf/config.yaml -update-perm '{"chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","user":"011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","perm":"Write"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +吊销权限： + +```bash +./cql -config conf/config.yaml -update-perm '{"chain":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","perm":"Void"}' +``` + +输出： + + INFO[0000] succeed in sending transaction to CovenantSQL + + +注意，`succeed in sending transaction to CovenantSQL` 只说明交易已成功发送至主网，交易成功与否请通过查询数据库确认。 + +为数据库添加新的账户权限后账户需补充押金与预付款才能进行正常查询。押金与预付款最小值的计算公式：`gas_price*number_of_miner*120000`。 + +使用新账户给数据库充值： + +```bash +./cql -config new_user_config/config.yaml -transfer '{"addr":"4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","amount":"90000000 Particle"}' +``` + +#### SQL 白名单 + +CovenantSQL 还支持给用户设置可执行的 SQL 白名单，可以限定用户以指定的 SQL Pattern 和可配的 Query 参数来访问数据库。在指定语句白名单的功能支持下，可以提高数据库的安全性，避免被单语句拖库或执行不正确的删除货更新操作。 + +增加白名单： + +```shell +./cql -config conf/config.yaml -update-perm ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": { + "patterns": [ + "SELECT COUNT(1) FROM a", + "SELECT * FROM a WHERE id = ? LIMIT 1" + ], + "role": "Read" + } +} +' +``` + +*白名单功能是基于数据库权限的一个扩展，且当前不支持增量的白名单更新，在设置白名单时需要写明所有授权该用户使用的语句，以及该用户对数据库的访问权限* + +设置完成后，用户将只能执行 `SELECT COUNT(1) FROM a` 或 `SELECT * FROM a WHERE id = ? LIMIT 1` 的语句（语句内容严格匹配，使用 `select COUNT(1) FROM a` 或 `SELECT COUNT(1) FROM a` 也不可以）；其中 第二条语句支持用户提供一个参数，以支持查询不同记录的目的。最终可以实现限定用户访问 `表 a`，并一次只能查询 `表 a` 中的一条数据或查询 `表 a`的 总数据量。 + +去掉白名单限制： + +```shell +./cql -config conf/config.yaml -update-perm ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": { + "patterns": nil, + "role": "Read" + } +} +' +# or +./cql -config conf/config.yaml -update-perm ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": "Read" +} +' +``` + +将 `pattern` 设置为 `nil` 或直接设置用户权限，都可以将用户的白名单限制去掉，设置回可以查询所有内容的读权限。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/deployment.md b/website/translated_docs/zh-CN/version-0.4.0/deployment.md new file mode 100644 index 0000000..85f8abb --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/deployment.md @@ -0,0 +1,162 @@ +--- +id: version-0.4.0-deployment +title: '🐳 Docker 一键部署' +original_id: deployment +--- +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 下载项目 + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行 + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +存为环境变量 + +### 启动 Docker 容器 + +现在有两种方式启动 CovenantSQL 容器： + +1. 使用 Docker Hub 上的公共镜像 +2. 构建 CovenantSQL Docker 镜像 + +> 我们推荐普通用户使用第一种方式测试 CovenantSQL，第二种仅用于体验最新的开发中的特性。 + +#### 1. 使用 Docker Hub 上的公共镜像 + +然后直接启动： + +```bash +make start +``` + +#### 2. 构建 CovenantSQL Docker 镜像 + +执行以下的命令在本地运行 CovenantSQL + +```bash +make docker # 从头编译新的镜像 +make start +``` + +### 检查运行状态 + +检查容器状态： + +```bash +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```shell + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp +covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp +covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp +covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp +covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp +``` + +## 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```shell +docker exec -it covenantsql_adapter /app/cql -config /app/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```shell +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```shell +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +### SQLChain Observer + +镜像中的 Observer 角色使用了和 mysql-adapter 镜像中相同的 private.key ，故可以免去新账户授权和转账的过程制。 + +（关于权限管理的详细说明请参考[数据库权限管理](cql.md#数据库权限管理)） + +#### 在浏览器使用 SQLChain Observer + +我们在 `127.0.0.1:11108` 端口提供了一个 SQLChain 的 Observer 可以看到 SQL 语句在链上的情况。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/intro.md b/website/translated_docs/zh-CN/version-0.4.0/intro.md new file mode 100644 index 0000000..dea44aa --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/intro.md @@ -0,0 +1,73 @@ +--- +id: version-0.4.0-intro +title: CovenantSQL 介绍 +original_id: intro +--- + + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可数据上链 +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是人们的私人钱包，那么 CovenantSQL 就是是人们的去中心化的私密数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密来保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/native.md b/website/translated_docs/zh-CN/version-0.4.0/native.md new file mode 100644 index 0000000..f2b845e --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/native.md @@ -0,0 +1,173 @@ +--- +id: version-0.4.0-native +title: '📦 CovenantSQL Native SDK' +original_id: native +--- +## 用 Golang 使用 CovenantSQL + +### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/nav.md b/website/translated_docs/zh-CN/version-0.4.0/nav.md new file mode 100644 index 0000000..403ba6e --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/nav.md @@ -0,0 +1,22 @@ +--- +id: version-0.4.0-nav +title: '📖 使用导航' +original_id: nav +--- +## 直接使用测试网 + +[🌏 TestNet 快速开始](./quickstart) + +## 部署私有 CovenantSQL 数据库（搭建私有链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +[🐳 Docker 一键部署](./deployment) + +## 使用 CovenantSQL 开发应用 + +[📦 CovenantSQL SDK](./development) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/proxy.md b/website/translated_docs/zh-CN/version-0.4.0/proxy.md new file mode 100644 index 0000000..7ea1ffa --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/proxy.md @@ -0,0 +1,111 @@ +--- +id: version-0.4.0-adapter +title: '📦 CovenantSQL Adapter SDK' +original_id: adapter +--- +# 通过 Adapter 使用 CovenantSQL + +## 简介 + +`CovenantSQL` 提供了 HTTP/HTTPS Adapter，类似于云数据库， 开发者可以直接用 HTTP 的形式使用 CovenantSQL。 + +## 安装和使用 + +首先，需要确认我们有一个可用的配置和公私钥对，通常我们默认的配置和公私钥对的存储位置为 `~/.cql/` 目录。生成或获取请参考 [QuickStart#创建账号](./quickstart#创建账号) + +### Docker 运行 Adapter + +下面的命令将使用`~/.cql/config.yaml` 和 `~/.cql/private.key` 启动 Adapter，并把端口映射在 `0.0.0.0:11105` + +```bash +export adapter_addr=0.0.0.0:11105 +docker rm -f cql-adapter +docker run -itd \ + --env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --name cql-adapter -p $adapter_addr:4661 \ + covenantsql/covenantsql:testnet -listen 0.0.0.0:4661 +``` + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +docker run -it --rm \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --entrypoint /app/cql covenantsql/covenantsql:testnet \ + -config /app/config.yaml -create 1 +``` + +命令会返回创建的数据库实例的连接串（DSN） + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +## 主流语言 Driver 的使用 + +### NodeJS + +NodeJS 开发者可以通过 [node-covenantsql](https://github.com/CovenantSQL/node-covenantsql) 来与 CovenantSQL Adapter 进行交互。 + +#### 下载安装 + +可以直接通过 `npm` 或者 `yarn` 来安装 `node-covenantsql` + +```bash +npm install --save node-covenantsql +``` + +or + +```bash +yarn add node-covenantsql +``` + +#### 使用 + +在运行本地 Adapter 之后，将 Adapter 的 endpoint 填入 `node-covenantsql` 的 config 之中： + +```javascript +const config = { + endpoint: 'localhost:11105', // local testnet endpoint without https + database: `${DSN}`, // your DB id created by `cql` tools + bypassPem: true // bypass https config +} +``` + +这里 `bypassPem` 为 `true` 表示应用中所有对链上数据库的操作都会经过本地的 Adapter 进行代理，我们默认本地环境是可控，安全的，无需用 HTTPS 来保证这段连接的信道安全，少了证书的繁琐认证，所以成为 `bypassPem`。 + +接着连通之后则可进行链上数据库的增删改查： + +```typescript +const cql from 'node-covenantsql' + +const config = {...} // see above + +cql.createConnection(config).then(async (connection: any) => { + // read + const data1 = await connection.query("select ? + ?", [2.1, 3.2]); + console.log(data1); + + // write + const createTableSQL = ` + CREATE TABLE IF NOT EXISTS contacts (\ + contact_id INTEGER PRIMARY KEY, + first_name TEXT NOT NULL, + last_name TEXT NOT NULL, + email text NOT NULL UNIQUE, + phone text NOT NULL UNIQUE + ); + ` + const status1 = await connection.exec(createTableSQL) + console.log(`exec1 status:`, status1); + + const data2 = await connection.query("show tables;"); + console.log(data2); +}).catch((e: any) => console.log(e)) +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/qna.md b/website/translated_docs/zh-CN/version-0.4.0/qna.md new file mode 100644 index 0000000..ff7276d --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/qna.md @@ -0,0 +1,6 @@ +--- +id: version-0.4.0-qna +title: '🙋 常见问题解答' +original_id: qna +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/quandl.md b/website/translated_docs/zh-CN/version-0.4.0/quandl.md new file mode 100644 index 0000000..d41d0b6 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/quandl.md @@ -0,0 +1,298 @@ +--- +id: version-0.4.0-quandl +title: 基于 Quandl 的金融数据分析 +original_id: quandl +--- +## 关于 Quandl + +Quandl 是一个针对金融投资行业的大数据平台，其数据来源包括联合国、世界银行、中央银行等公开数据，核心财务数据来自 CLS 集团，Zacks 和 ICE 等，所有的数据源自 500 多家发布商， 是为投资专业人士提供金融，经济和替代数据的首选平台，拥有海量的经济和金融数据。 + +## Quandl 数据索引 + +### CovenantSQL 使用简介 + +首先，我们已基于 Quandl 的开放 API 将数据存放在 CovenantSQL 中，首先应该浏览一下 CovenantSQL 的使用介绍来熟悉一下如何连接并且使用 CovenantSQL。 + +现在由于客户端兼容问题， 请直接使用我们的 HTTP 服务来对 Quandl 数据库进行 query，未来兼容现在的 `cql` 客户端后会第一时间更新此文档。 + +具体通过 HTTP 服务来使用 CovenantSQL 请参考 [Python 驱动文档](https://github.com/CovenantSQL/python-driver/blob/master/README.rst) 和 [NodeJS 驱动文档](https://github.com/CovenantSQL/node-covenantsql/blob/master/README.md) + +所需参数: + + host: 'e.morenodes.com' + port: 11108 + database: '057e55460f501ad071383c95f691293f2f0a7895988e22593669ceeb52a6452a' + + +### 数据使用方法 + +Quandl 数据分为表以及子表两层索引 + +数据库中，表名为`quandl_` + `database_code`为完整表名 + +通过查询表名来查看表的内容 + +具体使用时，需要结合`quandl_updateindex` 这张索引表来使用，（查询索引表时，请务必 limit 小于 10 万，因为全表数据量过大） + +使用时，请使用 where 语句限定`quandlcode`字段来查询表中的子表数据。 + +### 查询示例 + +1. 我们想要查询 欧盟委员会年度宏观经济数据库 的数据，我们找到其第一层索引的 `databasecode` 为`quandl_ameco`，于是，我们可以查询其第二层索引，用以下 SQL 命令行： + + `select * from quandl_updateindex where databasecode like 'ameco' group by quandlcode limit 10000` + +2. 然后通过第三列，我们可以查看`quandlcode`对应的描述 + + 比如 AMECO/ALB_1_0_0_0_AAGE 对应的就是阿尔巴尼亚的进出口相关信息，时间从 1960 到 1988。 + + Average share of imports and exports of goods in world trade excluding intra EU trade; Foreign trade statistics (1960-1998 Former EU-15) - Albania + + 于是，我们可以用以下方式把这个子表给查询出来 + + `select * from quandl_ameco where quandlcode like 'AMECO/ALB_1_0_0_0_AAGE' limit 10000` + +3. 注意：如果内容整列为 null 的，属于表结构本身不存在的字段，可以自行去除。 + +## Quandl 数据 Excel 插件使用说明 + +您可以下载 Quandl 数据 Excel 插件，无须安装，请解压到任意文件夹中。此插件目前仅支持 Office 2010 以及以上版本，office 2007 以及以下版本目前暂不支持。 + +### 配置 Excel 插件 + +解压下载后压缩包，在文件夹中有两个.xll 文件，`ClassLibrary7-AddIn.xll` 以及 `ClassLibrary7-AddIn64.xll` 文件，这两个文件分别对应 32 位的 Excel 与 64 位的 Excel，请根据您的电脑配置使用对应插件。 + +#### 修改 xml 配置 + +每个 `.xll` 文件对应一个 `.config` 的配置文件，也就是 `ClassLibrary7-AddIn.xll.config` 和`ClassLibrary7-AddIn64.xll.config`，为如下 xml 配置： + +```xml + + + + + + + + + +``` + +其中有如下配置需要修改，并保存： + +- certpath: 请填写 `read.data.thunderdb.io.pfx` 证书的绝对路径 + +#### 安装插件 + +有两种办法使用此 Excel 插件 + +1. 直接双击对应的 32 位或 64 位 Excel 的 xll 文件打开 + +![quandl_ext_1](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_1.png) + +如果弹出如上对话框，选择第一个： `仅为本回话启用此加载项`。然后新建一个 Excel 表格，如果在 Excel 的上方选项卡中看到 CovenantSQL，说明插件加载成功。 + +2. 打开 Excel，然后依次选择 `文件 — 选项 — 加载项`，管理选择 Excel 加载项，点击转到然后浏览选择解压后的对应版本的 `.xll` 文件，然后点击 `确定`，在选项卡中如果成功加载出 CovenantSQL 即为成功加载，如下图： + +![quandl_ext_2](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_2.png) + +#### 使用插件 + +选择 CovenantSQL 的选项卡可以看到 Quandl 数据查询，点击 Quandl 数据查询，会弹出一个窗体如下图所示： + +![quandl_ext_3](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_3.png) + +- 其中红色框住的列表部分是一级目录，下方则是所选项的具体描述 + +- 绿色按钮是通过选择的一级目录来查询二级目录。这里查询时间会随着所查询二级目录的大小以及用户自身的网络速度等因素而不同，可能查询时间会超过 1 分钟，请耐心等待。 + +- 黄色部分左边的列表是二级目录，右边的窗体则为列表项所选择的表的描述。 + +- 蓝色部分是导出数据的可选项 + + - Limit Number 是一次导出的最多数据条数，默认为 10000 条，最大值可填写 100000 + - Offset Number 是从数据库的第几条开始导出，因为之前会限定条数，例如我们之前导出了 10000 条数据，但是明显数据还没有导出全部，我们可以使用此功能选择 offset 10000 来从第 10000 条开始导出（注：数据库的计数从 0 开始，所以前 10000 条为 0-9999） + +现在，您即可在 Excel 中方便的调用存在 CovenantSQL 上的 Quandl 数据。 + +## 附件表 + +| DataBase | 名称 | 描述 | +| ------------ | ------------------------ | ------------------------------------------------------------------------------------------- | +| BUNDESBANK | 德意志联邦银行数据仓库 | 有关德国经济，货币和资本市场，公共财政，银行，家庭，欧元区总量，贸易和外债的数据。 | +| URC | 独角兽研究公司数据 | 纽约证券交易所，美国证券交易所和纳斯达克证券交易所的预付和下跌数据。从各种公开来源和报告中值。 | +| DCE | 大连商品交易所数据 | 来自DCE的农业和商品期货，历史跨越了近十年的特定期货。 | +| WFC | 富国银行住房抵押贷款数据 | 该数据库提供富国银行（Wells Fargo Bank）分部Wells Fargo Home Mortgage的抵押贷款购买和再融资利率。 | +| USDAFNS | 美国农业部食品与营养服务项目数据 | 食品和营养服务局为低收入家庭和儿童管理联邦营养援助计划。成本和参与率数据。 | +| LJUBSE | 卢布尔雅那证券交易所数据 | 该数据库包含卢布尔雅那股票交易所指数，总部位于斯洛文尼亚的卢布尔雅那。 | +| TOCOM | 东京商品交易所数据 | 来自东京商品交易所（TOCOM）的农业和商品期货，历史跨越了近十年的特定期货。 | +| WCSC | 世界银行企业积分卡数据 | 该数据库旨在提供世界银行集团在消除极端贫困和促进共同繁荣方面的表现的战略概述。 | +| CMHC | 加拿大住房抵押贷款公司 | CMHC是一家政府所有的公司，为加拿大公民提供经济适用房，并收集价格，建筑和供应等数据。 | +| WGEC | 世界银行全球经济监测商品数据（GEM） | 包含1960年至今的商品价格和指数的数据。 | +| FED | 美联储数据公布 | 美国官方关于货币供应量，利率，抵押贷款，政府财政，银行资产和债务，汇率，工业生产的数据。 | +| WPSD | 世界银行公共部分支出数据 | 由世界银行和国际货币基金组织共同开发的数据，汇集了详细的公共部门政府债务数据。 | +| UGID | 联合国全球指标 | 该数据库提供广泛的全球指标，涵盖人口，公共卫生，就业，贸易，教育，通货膨胀和外债。 | +| RBA | 澳大利亚储备银行数据 | 中央银行和货币当局，监管银行业，设定利率，并为政府债务提供服务。关键经济指标数据。 | +| UCOM | 联合国商品贸易数据 | 该数据库提供有关食品，活体动物，药品，金属，燃料和机械等商品进出口的全面综合数据。 | +| SIDC | 太阳影响数据分析中心数据 | SIDC主持从1700年开始的太阳活动数据，特别是太阳黑子活动。 | +| ZCE | 郑州商品交易所数据 | 来自ZCE的农业和商品期货，历史跨越了近十年的特定期货。 | +| USDAFAS | 美国农业部外国农业服务数据（FAS） | 美国农业部外国农业服务局将美国农业与世界市场联系起来。它提供了国外生产和出口的统计数据。 | +| OECD | 世界经济合作与发展组织数据 | 促进经济福利的发达国家国际组织。从成员和其他人收集数据以提出政策建议。 | +| OPEC | 欧佩克数据 | 国际组织和经济卡特尔监督伊拉克，伊朗，沙特阿拉伯和委内瑞拉等石油生产国的政策、油价数据。 | +| MCX | 印度多种商品交易所数据 | 印度最大的商品交易所，为金属，能源和农业期货交易提供服务。世界第三大合约和交易量交易所。 | +| ECONOMIST | 经济学人 - 巨无霸指数 | 巨无霸指数是由经济学家于1986年发明的，是一个轻松的指南，指出货币是否处于“正确”水平。它基于购买力平价理论（PPP）。 | +| NSDL | 国家证券存管有限公司（印度）数据 | 在印度存放负责该国经济发展的国家，该国家建立了国际标准的国家基础设施，处理在印度资本市场以非物质形式持有和结算的大部分证券。 | +| GDT | 全球乳品贸易数据 | nan | +| CFFEX | 中国金融期货交易所数据 | 来自CFFEX的指数和债券期货，对于特定期货的历史跨越近十年。 | +| CITYPOP | Thomas Brinkhoff的城市人口数据 | Thomas Brinkhoff提供了大多数国家城市和行政区域的人口数据。 | +| BCHARTS | 比特币图表汇率数据 | 来自所有主要比特币交易所的比特币兑换大量货币的汇率，包括当前和历史汇率。 | +| LOCALBTC | Local Bitcoins数据 | nan | +| JODI | JODI石油世界数据库 | JODI石油和天然气数据来自100多个国家，包括多种能源产品和各种计量方法。 | +| UENG | 联合国能源统计数据 | 该数据库提供有关新能源和可再生能源的生产，贸易，转换和最终消费的全面统计数据。 | +| ULMI | 联合国劳工市场指标 | 该数据库为世界上所有国家提供了按性别划分的全面青年失业数字。 | +| MAURITIUSSE | 毛里求斯证券交易所数据 | 毛里求斯证券交易所指数数据。 | +| UKRSE | 乌克兰交易所数据 | UKRSE提供与乌克兰最大证券交易所相关的最新数据。该交易所位于基辅，约占乌克兰总股本交易量的四分之三 | +| BITSTAMP | Bitstamp数据 | Bitstamp是一个比特币的交易平台。 | +| UNAE | 联合国国民账户估算数据 | 该数据库提供了全球所有国家不同部门的国内生产总值，国民总收入和总增加值的全球数据。 | +| UNAC | 联合国国民账户官方国家数据 | 该数据库提供有关国民账户的全球数据，例如家庭，公司和政府的资产和负债。 | +| UTOR | 联合国世界旅游业数据 | 该数据库提供有关国际旅游的综合数据。数据包括所有国家的旅游人数和旅游支出。 | +| WFE | 世界交易所联合会数据 | 该数据库提供有关国际旅游的综合数据。数据包括所有国家的旅游人数和旅游支出。 | +| FRBC | 克利夫兰联邦储备银行数据 | 克利夫兰联邦储备银行从数百家金融机构收集数据，包括存款机构，银行控股公司和其他用于评估金融机构状况的实体，以及收集经济和金融体系运作方式的见解。 | +| UGEN | 联合国性别信息 | 该数据库提供关于各种与性别有关的指标的全面综合数据，涵盖人口，卫生，教育和就业。 | +| BITFINEX | Bitfinex数据 | Bitfinex是比特币，莱特币和Darkcoin的交易平台，具有许多先进功能，包括保证金交易，交易所和点对点保证金融资。 | +| UGHG | 联合国温室气体清单 | 该数据库提供有关六种主要温室气体人为排放的全面综合数据。数据可以追溯到1990年。 | +| UIST | 联合国工业发展组织数据 | 该数据库提供有关工业发展指标的全球数据，包括产量，员工，工资，各种行业的增加值。 | +| PRAGUESE | 布拉格证券交易所数据 | 布拉格证券交易所的价格指数数据。 | +| PFTS | PFTS证券交易所（乌克兰）数据 | 来自PFTS证券交易所的指数数据，这是乌克兰最大的市场。 | +| WARSAWSE | 华沙证券交易所数据 | WIG20指数自1994年4月16日起根据WSE主要清单中20家最主要和最具流动性公司的股票价值计算。 | +| TUNISSE | 突尼斯证券交易所数据 | 突尼斯证券交易所的主要参考指数。 | +| FRKC | 堪萨斯城联邦储备银行数据 | FRKC是美联储第10区的区域中央银行，主要发布农业交易中的银行业务数据。 | +| UENV | 联合国环境统计数据 | 该数据库提供有关水和废物相关指标的全球数据，包括淡水供应和降水，以及废物的产生和收集。 | +| UFAO | 联合国粮食和农业数据 | 该数据库提供全球粮食和农业数据，包括作物生产，化肥消费，农业用地和牲畜用途。 | +| TAIFEX | 台湾期货交易所数据 | 来自TAIFEX的指数和债券期货，其历史跨越了十多年的特定期货。 | +| GDAX | GDAX（全球数字资产交易所）数据 | GDAX是世界上最受欢迎的买卖比特币的地方。 | +| ARES | 房地产证券化协会数据 | ARES保护投资者，有助于房地产证券化产品市场的发展，并促进房地产投资市场的扩张。 | +| SHADOWS | 影子联邦基金利率模型数据 | 该数据集包含 吴-侠 论文中关于影子联邦基金的三个主要指标，用于识别所有三大银行的影子利率。 | +| NAAIM | 全国积极投资管理者协会头寸指数 | NAAIM暴露指数代表NAAIM成员报告的美国股票市场的平均风险敞口。 | +| CBRT | 土耳其共和国中央银行数据 | CBRT负责采取措施维持土耳其金融体系的稳定。 | +| CEGH | 中欧天然气中心数据 | nan | +| FINRA | 美国金融业监管局数据 | 金融业监管局提供证券公司和交易所市场的短期利息数据。 | +| NASDAQOMX | 纳斯达克OMX全球指数数据 | 纳斯达克OMX发布的全球指数超过35,000种，包括全球股票，固定收益，股息，绿色，北欧，伊斯兰教等。每日数据。 | +| EURONEXT | 泛欧证券交易所数据 | 欧洲最大的交易所Euronext的历史股票数据。 | +| UICT | 联合国信息和通信技术数据 | 该数据库提供有关信息和通信技术的全面全球数据，包括所有国家的电话，蜂窝和互联网使用情况。 | +| USAID | 美国国际开发署数据 | 美国国际开发署提供了美国向世界其他地方提供的所有外国援助的完整历史记录。 | +| ZAGREBSE | 萨格勒布证券交易所数据 | 克罗地亚唯一的证券交易所。它发布有关其股票和债券指数表现的数据。 | +| QUITOSE | 基多证券交易所（厄瓜多尔）数据 | 厄瓜多尔国家证券交易所的指数。 | +| ECBCS | 欧盟委员会商业和消费者调查 | 该数据库中的数据来自欧盟（EU）和欧盟申请国的不同经济部门的统一调查。 | +| PSE | 巴黎经济学院数据 | 该数据库描述了越来越多国家的最高收入分配。数字是使用税收数据得出的。 | +| MALTASE | 马耳他证券交易所数据 | 马耳他证券交易所发挥作用，为其认可的名单提供金融工具的结构，随后可在受监管，透明和有序的市场（二级市场）进行交易。市场的主要参与者是发行人，股票交易所会员（股票经纪人）和投资者一般。 | +| GPP | 全球石油价格 | nan | +| PPE | 波兰电力交易所（TGE）数据 | nan | +| UKONS | 英国国家统计局数据 | 关于英国就业，投资，住房，家庭支出，国民账户和许多其他社会经济指标的数据。 | +| NCDEX | 国家商品及衍生品交易所（印度）数据 | 印度专业管理的在线多商品交易所 | +| WSE | 华沙证券交易所（GPW）数据 | nan | +| TFX | 东京金融交易所数据 | 东京金融交易所是一个期货交易所，主要交易金融工具市场，处理证券和市场衍生品。 | +| WGFD | 世界银行全球金融发展数据 | 有关金融系统特征的数据，包括金融机构和市场的规模，使用，获取，效率和稳定性的衡量标准。 | +| CEPEA | 应用经济学应用研究中心（巴西）数据 | CEPEA是圣保罗大学的一个经济研究中心，专注于农业企业问题，发布巴西商品价格指数。 | +| SBJ | 日本统计局数据 | 日本政府统计机构，提供有关就业和劳动力的统计数据。 | +| WGEM | 世界银行全球经济监测 | 关于全球经济发展的数据，涵盖高收入国家和发展中国家。 | +| WGDF | 世界银行全球发展金融 | 关于金融系统特征的数据，包括金融机构和市场的规模，使用，获取，效率和稳定性的衡量标准。 | +| WWDI | 世界银行世界发展指标 | 最新和最准确的发展指标，由官方认可的国际来源汇编而成。 | +| WESV | 世界银行企业调查 | 公司级私营部门数据，涵盖金融，腐败，基础设施，犯罪，竞争和绩效衡量等业务主题。 | +| WDBU | 世界银行存续商业数据 | 关于成员国和地方和区域一级选定城市的商业法规及其执法的数据。 | +| OSE | 大阪证券交易所数据 | 日本第二大证券交易所。与东京证券交易所不同，OSE在衍生品交易方面表现最为强劲，是日本的大多数期货和期权。 | +| RFSS | 俄罗斯联邦统计局数据 | 俄罗斯政府统计机构，负责在国家和地方层面发布俄罗斯的社会，经济和人口统计数据。 | +| SHFE | 上海期货交易所数据 | 大宗商品交换能源，金属和化学相关的工业产品。许多商品期货的衍生品市场。 | +| WGEP | 世界银行全球环境规划经济前景数据 | 关于全球经济的短期，中期和长期前景以及对发展中国家和减贫的影响的数据。 | +| USMISERY | 美国痛苦指数 | 由经济学家亚瑟·奥肯（Arthur Okun）开发的苦难指数是失业率加上通胀率。 | +| WJKP | 世界银行知识平台工作数据 | 与劳工有关的主题指标。 | +| WMDG | 世界银行千年发展目标数据 | 根据千年发展目标（MDGs）的目标和指标重新组织的世界发展指标数据。 | +| WPOV | 世界银行贫困统计 | 贫困人口比率，贫困差距以及国际和国家贫困线贫困人口数量的指标。 | +| EUREKA | Eurekahedge数据 | 一家研究公司专注于对冲基金和其他另类投资基金。它公布了对冲基金业绩的数据。 | +| MOFJ | 日本财务省数据 | 日本政府债券利率数据，由财政部每日公布。 | +| PIKETTY | Thomas Piketty数据 | “21世纪资本”中的收入和财富数据，哈佛大学出版社，2014。 | +| PSX | 巴基斯坦证交所数据 | 巴基斯坦证券交易所的股票收盘价格。 | +| SGX | 新加坡交易所数据 | 亚洲证券和衍生品交易所为许多大型新加坡和其他亚洲公司进行股票交易。在自己的交易所上市。 | +| UIFS | 联合国国际金融统计 | 该数据库提供有关国际财务指标的综合数据，如平均收入，债券收益率，政府收入和支出。 | +| UINC | 联合国工业商品数据 | 该数据库提供有关工业商品生产的全球数据，如矿石和矿物，食品，可运输货物和金属产品。 | +| INSEE | 国家统计和经济研究所（法国）数据 | INSEE是法国的国家统计机构。它收集有关法国经济和社会的数据，如社会经济指标和国民账户。 | +| SNB | 瑞士国家银行数据 | 中央银行负责货币政策和货币。有关国际账户，利率，货币供应和其他宏观经济指标的数据。 | +| ODE | 大阪道岛商品交易所数据 | 日本关西地区的一个非营利性商品交易所，交易七种主要农产品。 | +| WGEN | 世界银行性别统计 | 描述收入，工作类型，工作部门，农民生产率以及企业家公司规模和利润的性别差异的数据。 | +| WHNP | 世界银行健康营养与人口统计 | 关键的健康，营养和人口统计数据。 | +| WIDA | 世界银行国际发展协会 | 关于选定指标的IDA（国际开发协会）国家总体成果进展情况的数据。 | +| ECMCI | 欧盟委员会货币状况指数 | 每月更新，此数据库提供欧元区的货币状况指数值。历史可以追溯到1999年。 | +| NBSC | 中国国家统计局数据 | 中国有关金融，工业，贸易，农业，房地产和交通运输的统计数据。 | +| MAS | 新加坡金融管理局数据 | nan | +| MGEX | 明尼阿波利斯谷物交易所数据 | 促进农业指数贸易的区域商品期货和期权合约市场。 | +| WWGI | 世界银行全球治理指标 | 六个治理层面的总体和个别治理指标数据。 | +| ISM | 供应管理研究所 | ISM促进供应链管理实践，并发布有关生产和供应链，新订单，库存和资本支出的数据。 | +| UKR | 乌克兰交易所数据 | nan | +| FRBNY | 纽约联邦储备银行数据 | FRBNY是美国最大的区域中央银行。为纽约，康涅狄格州和新泽西州的大部分地区以及一些地区设定货币政策。 | +| FRBP | 费城联邦储备银行数据 | FRBP是美联储的区域中央银行。它发布有关商业信心指数，GDP，消费和其他经济指标的数据。 | +| FMSTREAS | 美国财政部 - 财务管理处数据 | 美利坚合众国的月收入/支出和赤字/盈余。 | +| EIA | 美国能源信息管理局数据 | 美国国家和州有关所有主要能源产品（如电力，煤炭，天然气和石油）的生产，消费和其他指标的数据。 | +| SOCSEC | 美国社会保障局数据 | 提供有关美国社会保障计划的数据，特别是受益人的人口统计数据;残疾人，老人和幸存者。 | +| TFGRAIN | 顶级飞行谷物合作社数据 | 玉米和大豆的现货价格，包括前月期货合约的基础。 | +| IRPR | 波多黎各统计研究所数据 | 波多黎各统计研究所制造业统计数据。 | +| BCHAIN | blockchain.com数据 | Blockchain是一个发布与比特币相关的数据的网站，每日更新。 | +| BITCOINWATCH | Bitcoin Watch数据 | 比特币采矿统计。 | +| ODA | 国际货币基金组织跨国宏观经济统计 | 国际货币基金组织的初级商品价格和世界经济展望数据，由非洲开放数据公布。优秀的跨国宏观经济数据。 | +| WADI | 世界银行非洲发展指标 | 关于非洲的一系列发展指标，包括国家，区域和全球估计数。 | +| WEDU | 世界银行教育统计 | 关于教育机会，进展，完成，扫盲，教师，人口和支出的国际可比指标。 | +| WGLF | 世界银行全球Findex（全球金融包容性数据库） | 关于人们如何储蓄，借贷，支付和管理风险的金融包容性指标。 | +| WWID | 世界财富和收入数据库 | 世界财富和收入数据库旨在提供开放和便捷的途径，以获取有关国家内部和国家之间世界收入和财富分配历史演变的最广泛的现有数据库。 | +| BTER | 比特儿数据 | 加密货币的历史汇率数据。 | +| CFTC | 商品期货交易委员会报告 | 交易员和集中比率的每周承诺。期货头寸以及期货加期权头寸的报告。新旧格式。 | +| BOE | 英格兰银行官方统计 | 当前和历史汇率，担保贷款和定期存款利率，欧元商业票据利率和政府证券收益率。 | +| EXMPL | Quandl时间序列数据示例 | 一个时间序列数据库示例。 | +| WORLDAL | 铝价格 | 世界铝产能和产量（千公吨）。 | +| WGC | 黄金价格 | 世界黄金协会是黄金行业的市场开发组织。它以不同货币发布黄金价格数据。 | +| MX | 加拿大期货数据 | 蒙特利尔交易所是一家衍生品交易所，交易期货合约以及股票，指数，货币，ETF，能源和利率的期权。 | +| UMICH | 消费者情绪 | 密歇根大学的消费者调查 - 最近6个月的数据点是非官方的;它们来自华尔街日报的文章。 | +| JOHNMATT | 稀有金属价格数据 | 关于铂族金属的当前和历史数据，如价格，供应和需求。 | +| NAHB | 美国住房指数 | 美国的住房和经济指数。 | +| RATEINF | 通货膨胀率 | 阿根廷，澳大利亚，加拿大，德国，欧元区，法国，意大利，日本，新西兰等国的通货膨胀率和消费物价指数CPI。 | +| RENCAP | IPO数据 | 有关美国IPO市场的数据。 | +| ML | 公司债券收益率数据 | 美林（Merrill Lynch）是美国一家大型银行，它发布了不同地区公司债券收益率的数据。 | +| MULTPL | S&P 500 | nan | +| RICI | 商品指数 | 综合，以美元为基础的总回报指数，代表全球经济中消费的一篮子商品的价值。 | +| AAII | 投资者情绪 | 美国个人投资者协会的情绪数据。 | +| BIS | 国际清算银行数据 | 国际清算银行为中央银行提供货币和金融稳定管理，促进国际合作，并作为中央银行的银行。 | +| BCB | 巴西中央银行统计数据库 | 巴西宏观经济数据，涵盖公共财政，国民账户，支付系统，通货膨胀，汇率，贸易和国际储备。 | +| BCRA | 阿根廷中央银行数据 | 阿根廷中央银行负责货币政策，提供外汇市场数据和主要宏观经济指标。 | +| FSE | 法兰克福证券交易所 | 法兰克福证券交易所的每日股票价格 | +| BLSN | 劳工统计局国际数据 | 各国的进出口价格统计，由劳工统计局公布。 | +| BLSP | 劳工统计局生产力数据 | 美国制造业，劳务和商业统计，由劳工统计局公布。 | +| FDIC | 联邦存款保险公司数据 | FDIC是一家银行存款高达25万美元的联邦保险公司，负责收集商业银行和储蓄机构的财务数据。 | +| BLSI | 美国劳工统计局通货膨胀和价格统计 | 美国国家和州一级的通胀数据，由劳工统计局公布。 | +| BLSE | 美国劳工统计局就业与失业统计 | 美国国家和州一级的就业和失业统计数据，由劳工统计局公布。 | +| BLSB | 美国劳工统计局薪酬福利统计 | 由劳工统计局公布的美国停工统计数据。 | +| BP | BP能源生产和消费数据 | BP是一家大型能源生产商和分销商。它提供了各个国家和较大次区域的能源生产和消费数据。 | +| LPPM | 白金和钯价格数据 | 全球钯金和铂金市场清算价格数据。 | +| CASS | 运费指数 | 自1990年以来，CASS每月提供与其他经济和供应链指标相关的货运趋势的CASS运费指数报告。 | +| MORTGAGEX | 可调利率抵押贷款指数 | ARM索引的历史住房数据。 | +| BUCHARESTSE | 布加勒斯特证券交易所数据 | 布加勒斯特证券交易所发布股票，权利，债券，基金单位，结构性产品和期货合约活动数据。 | +| AMECO | 欧盟委员会年度宏观经济数据库 | 欧洲委员会经济和财政事务总局（DG ECFIN）年度宏观经济数据库。 | +| ACC | 美国化学理事会数据 | 化学活性晴雨表（CAB）由美国化学理事会（ACC）出版。 CAB是一个经济指标，有助于预测整个美国经济的高峰和低谷，并突出了美国其他行业的潜在趋势。 | +| ABMI | 亚洲债券市场计划 | 中国和日本债券市场的指标，如规模和构成，市场流动性，收益率收益率和波动率。 | +| BITAL | 意大利证交所数据 | 该数据库提供了Borsa Italiana（现为伦敦证券交易所集团的一部分）的股票期货合约数据。 | +| BANKRUSSIA | 俄罗斯银行数据 | 俄罗斯银行的主要指标，包括银行业，货币供应量，金融市场和宏观经济统计数据。 | +| BOC | 加拿大银行统计数据库 | 加拿大的经济，金融和银行数据。包括利率，通货膨胀，国民账户等。每日更新。 | +| HKEX | 香港交易所数据 | 香港交易所股票价格，历史分割期货等每日更新。 | +| AMFI | 印度共同基金协会数据 | 该数据库代表印度共同基金协会的基金信息。 | +| BDM | 墨西哥银行数据 | 墨西哥银行负责货币政策和本国货币（比索），并提供账户和所有宏观经济变量的数据。 | +| BATS | BATS美国证券交易所数据 | Bats是美国的股票市场运营商，经营四个股票交易所--BZX Exchange，BYX Exchange，EDGA Exchange和EDGX Exchange | +| BSE | 孟买证券交易所数据 | 在印度孟买证券交易所交易的公司的日终价格，指数和其他信息。 | +| FRED | 美联储经济数据 | 来自圣路易斯联邦储备银行研究部门的增长，就业，通货膨胀，劳工，制造业和其他美国经济统计数据。 | +| FMAC | 房地美数据 | Freddie Mac的主要抵押贷款市场调查和其他地区特定历史抵押贷款利率的数据。 | +| EUREX | 欧洲期货交易所数据 | 欧洲最大的期货交易所EUREX的指数，利率，农业和能源期货，历史跨越了特定期货的十年。 | +| ECB | 欧洲中央银行数据 | 欧盟中央银行监督货币政策和欧元，并提供相关宏观经济变量的数据。 | +| BOF | 法国银行数据 | 法兰西银行通过欧洲中央银行体系的政策负责货币政策，并提供关键经济指标的数据。 | +| BELGRADESE | 贝尔格莱德证券交易所数据 | 贝尔格莱德证券交易所数据，每日更新。 | +| CHRIS | 维基连续期货 | Quandl所有600个期货的连续合约。建立在CME，ICE，LIFFE等原始数据之上。由Quandl社区策划。 50年的历史。 | +| BOJ | 日本银行数据 | nan | +| USTREASURY | 美国财政部数据 | 美国财政部确保国家的金融安全，管理国家债务，收取税收，发行货币，提供收益率数据。 | +| LBMA | 伦敦金银市场协会数据 | 伦敦黄金和白银市场的国际贸易协会，由中央银行，私人投资者，生产商，炼油商和其他代理商组成。 | +| PERTH | 珀斯铸币厂数据 | 珀斯造币厂的利率和商品价格的高点，低点和平均值每月更新一次。 | +| ZILLOW2 | Zillow房地产研究 | 房屋价格和租金按大小，类型和等级划分;住房供应，需求和销售。按邮政编码，街区，城市，都市区，县和州切片。 | \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/quickstart.md b/website/translated_docs/zh-CN/version-0.4.0/quickstart.md new file mode 100644 index 0000000..4794758 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/quickstart.md @@ -0,0 +1,148 @@ +--- +id: version-0.4.0-quickstart +title: '🌏 TestNet 快速开始' +original_id: quickstart +--- +## CovenantSQL 工具包 + +### 工具包简介 + +请根据您使用的操作系统平台选择 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。 + +例如，您使用的是： + +- MacOS 平台请下载：[**CovenantSQL-v0.4.0.osx-amd64.tar.gz**](https://github.com/CovenantSQL/CovenantSQL/releases/download/v0.4.0/CovenantSQL-v0.4.0.osx-amd64.tar.gz) +- Linux 平台请下载：[**CovenantSQL-v0.4.0.linux-amd64.tar.gz**](https://github.com/CovenantSQL/CovenantSQL/releases/download/v0.4.0/CovenantSQL-v0.4.0.linux-amd64.tar.gz) +- Windows 平台我们稍后发布，有需求请戳这里：[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/CovenantSQL/CovenantSQL) + +解压之后，你将得到以下命令行工具，包括：`cql`、`cql-utils` 等。 + +| 工具名 | 介绍 | +| ---------- | --------------------------------------------------- | +| cql | CovenantSQL 的客户端，类似 mysql 命令，用于执行 SQL | +| cql-utils | CovenantSQL 工具箱，用于和主链交互 | +| cql-minerd | CovenantSQL 矿工客户端，用于运行数据库赚取奖励，以后会开放加入 | +| cqld | CovenantSQL 主链节点，主要由 CovenantLabs 以及合作伙伴以 DPoS 模式运行 | + +### 测试网快速接入 + +目前，我们已经发布了测试网 v0.4.0，供大家进行原理性验证和体验。你可以选在使用公共的测试账号快速进行接入测试。 + +测试账号的配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) ，或者使用以下命令： + +```bash +mkdir conf +wget https://git.io/fhFZe -O conf/config.yaml +wget https://git.io/fhFZv -O conf/private.key +chmod 600 conf/private.key +``` + +**测试网注**： + +> 该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放你的应用信息，我们会不定期清理数据库数据。 +> +> 测试网暂时由 3 个 Miner 组成，所以暂时最大只支持`create 3`创建 3 个节点组成的数据库。 + +## 创建并访问 CovenantSQL 数据库 + +### 创建数据库 + +```shell +./cql -config conf/config.yaml -create 1 +``` + +输出： + + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + + +这里表示你提交了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库的创建请求到主链。 + +> 我们需要等待大概 30s 的时间，等待数据库创建，大致过程为： +> +> 1. 收到请求的 出块节点（Block Producer）进行 Miner 和数据库创建请求的撮合 +> 2. 数据库创建请求在 其它出块节点 进行验证和确认 +> 3. SQLChain 的符合条件的 Miner 收到数据库任务 +> 4. SQLChian 组建 Kayak 数据库集群 +> 5. 所有 Miner 准备就绪等待请求 + +### 访问数据库 + +```shell +./cql -config conf/config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，你可以按你操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 数据库 SDK + +- [Golang 开发指引](./development) + +## SQLChain 区块浏览器 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，你可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。 + +> 测试网的`区块浏览器`目前是开放权限的，所以任何知道数据库 ID 的人都能看到您的数据 + +查询时，请在其页面右上角填入你的数据库 ID。例如：`0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` + +## 创建账号 + +我们的测试网支持你创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（会询问设置主密码，测试期间建议直接回车留空）： + +```shell +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你在~目录下创建一个 `.cql` 目录： + +- `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```shell +./cql-utils -tool addrgen -private ~/.cql/private.key +``` + +输出： + +```toml +wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 +``` + +你可以在这里回复上面得到的钱包地址 [GitHub Issue](https://github.com/CovenantSQL/CovenantSQL/issues/283)，我们会为你的钱包充值。 + +使用 cql 命令行工具查询余额(未加 -config 参数时，命令会自动找 ~/.cql 目录的 config.yaml 文件)： + +```shell +./cql -config ~/.cql/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +恭喜，你已收到我们发出的 PTC 稳定币，现在即可开始使用 CovenantSQL， 你可以参考 [Golang 使用 CovenantSQL 文档](./development) 进行开发。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.4.0/usecase.md b/website/translated_docs/zh-CN/version-0.4.0/usecase.md new file mode 100644 index 0000000..6d4193c --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.4.0/usecase.md @@ -0,0 +1,6 @@ +--- +id: version-0.4.0-usecase +title: 使用案例 +original_id: usecase +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/adpater.md b/website/translated_docs/zh-CN/version-0.5.0/adpater.md new file mode 100644 index 0000000..8243854 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/adpater.md @@ -0,0 +1,59 @@ +--- +id: version-0.5.0-adapter +title: Adapter +original_id: adapter +--- + +# Use Adapter to access CovenantSQL + +`CovenantSQL` provides an HTTP/HTTPS adapter service. Developers could access CovenantSQL like a cloud database by using HTTP RESTful requests. + +## How to use + +First, [Install docker](https://docs.docker.com/install/). + +Secondly, before using CovenantSQL, a proper configuration file and an asymmetric key-pair is required. If no configuration file is specified, CovenantSQL tries to load configuration from `~/.cql/config.yaml`. For configuration file and key-pair generation, please refer to [QuickStart#CreateAccount](./quickstart#CreateAccount) + +### Start adapter using docker + +Following command will use config file `~/.cql/config.yaml` and key-pair `~/.cql/private.key` to start adapter service and serving at `0.0.0.0:11105`. + +```bash +export adapter_addr=0.0.0.0:11105 +docker rm -f cql-adapter +docker run -itd \ + --env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --name cql-adapter -p $adapter_addr:4661 \ + covenantsql/covenantsql:testnet 0.0.0.0:4661 +``` + +### Create database + +Create new database using `cql create` command and provide database instance requirements. + +For example, create a single node database instance: + +```bash +docker run -it --rm \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --entrypoint /app/cql covenantsql/covenantsql:testnet \ + create -config /app/config.yaml -wait-tx-confirm '{"node": 1}' +``` + +This command would produce a database connection string (DSN) similar to following example. + +```bash +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +Use DSN to access CovenantSQL using various drivers. + +## Drivers + +1. [Golang](./driver_golang) +2. [Java](./driver_java) +3. [Python](./driver_python) +4. [NodeJS](./driver_js) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/advanced_deployment.md b/website/translated_docs/zh-CN/version-0.5.0/advanced_deployment.md new file mode 100644 index 0000000..418a45c --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/advanced_deployment.md @@ -0,0 +1,160 @@ +--- +id: version-0.5.0-advanced_deployment +title: Private Deploy +original_id: advanced_deployment +--- + +## Deploy with CovenantSQL Docker + +### Install Docker + +You need to install docker and docker-compose on your machine to deploy CovenantSQL. + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### Download project + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +For all subsequent commands, the working directory is by default in the cloned CovenantSQL root directory, which can be saved as an environment variable: + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +### Start Docker container + +There are now two ways to start the CovenantSQL container: + +1. Use a public image on Docker Hub +2. Build a CovenantSQL Docker image + +> We recommend that regular users test CovenantSQL in the first way, and the second is only used to experience the latest development features. + +#### 1. Use a public image on Docker Hub + +Then start directly: + +```bash +make start +``` + +#### 2. Build a CovenantSQL Docker image + +Run CovenantSQL locally by executing the following command + +```bash +make docker # compile a new image from source files +make start +``` + +### Check running status + +Check the container status: + +```bash +docker-compose ps +``` + +Confirm that all components are in the `Up` state + + Name Command State Ports + ------------------------------------------------------------------------------------------------------ + covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp + covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp + covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp + covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp + covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp + covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp + covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp + covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp + covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp + covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp + + +## Operate CovenantSQL + +### Create a database + +Create a DB instance by using the `cql` command and using the `create` parameter to provide the required number of database nodes. + +e.g.: creating a single-node database instance + +```bash +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +> Modify the value of the `create` parameter to create an instance running on multiple nodes +> e.g.: create an instance of two nodes + +```bash +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +The command will return the connection string of the created database instance + + covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + + +### Accessing the database + +Use the `cql` command and use the `dsn` parameter to provide a connection string for the database instance access: + +```bash +docker exec -it covenantsql_adapter /app/cql console -config /app/config.yaml -no-password -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +After that, it will get the following output, and enter the `cql` interactive command line mode + +``` + +Connected with driver covenantsql (develop) Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> + +
The `cql` interactive command line mode is similar to the `mysql` command. For example, create a table named test, view the tables in the database, insert records, and query results etc. + + ```sql + CREATE TABLE test (test TEXT); + SHOW TABLES; + INSERT INTO test VALUES("happy"); + SELECT * FROM test; + + +After that, it will get the following output: + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); + CREATE TABLE + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name + ------ + test + (1 row) + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); + INSERT + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test + ------- + happy + (1 row) + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> + + +Use the `Ctrl + D` shortcut or type `\q` to exit the `cql` interactive command line + +### SQLChain Observer + +The Observer role in the image uses the same private.key as in the mysql-adapter image, so the new account authorization and transfer process can be eliminated. + +（For details on rights management, please refer to [Database Permission Managemen](cql.md#数据库权限管理)） + +#### Use SQLChain Observer in your browser + +We provide a SQLChain Observer at port `127.0.0.1:11108` to see the SQL statement on the chain. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/advanced_secure_gateway.md b/website/translated_docs/zh-CN/version-0.5.0/advanced_secure_gateway.md new file mode 100644 index 0000000..1850818 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/advanced_secure_gateway.md @@ -0,0 +1,80 @@ +--- +id: version-0.5.0-advanced_secure_gateway +title: Secure Gateway +original_id: advanced_secure_gateway +--- + +## SecureGateway + +CQL SecureGateway (CGS) is currently only available to enterprise users. If you have in-depth understanding or trial requirements, please [contact us](mailto:info@covenantsql.io). + +### Architecture + +![CovenantSQL.SecureGateway](https://github.com/CovenantSQL/docs/raw/master/website/static/img/CovenantSQL.SecureGateway.png) + +### API + +CGS uses the binary protocol of MySQL 5.x, and all language drivers compatible with MySQL 5.x can be used directly. + +### ACL Config + +Support for **User/User Group** and **Column/Column Group** combination authorization (columns are represented as **database.table.column** triples) + +#### ACL Example + +The settings are divided into two parts, `Group` and `Strategy`, as follows: + +User Group + +| User | Group | +| ----- | --------------- | +| user1 | admin,userGroup | +| user2 | admin,userGroup | +| user3 | userGroup | + +Column Group + +| Column | Group | +| ------------- | -------- | +| db1.tbl1.col2 | someCols | +| db1.tbl1.col3 | someCols | +| db1.tbl1.col4 | someCols | + +Strategy + +| User/Group | Column/Group | Permission（Write/Read） | +| ---------- | ------------- | ---------------------- | +| user1 | db1.tbl1.col1 | write | +| user2 | db1.tbl1.col1 | read | +| admin | someCols | read | +| userGroup | db1.tbl2.col1 | read | +| userGroup | db2.tbl1.* | read | + +### Encryption Config + +Support for configuring encryption settings in the form of fields & encryption keys (fields are represented as **database.table.field** triples) Encryption/decryption is valid only if the user has permission to the field. + +#### Example + +Keys + +| Column | Key | +| ------------- | ---- | +| db1.tbl1.col1 | key1 | +| db1.tbl1.col2 | key2 | +| db1.tbl1.col3 | key3 | +| db1.tbl2.col1 | key1 | +| db2.tbl1.col1 | key1 | + +In conjunction with the configuration of `ACL` & `Keys` above, the access restrictions that are in effect are as follows: + +Result + +| database | table | column | key | user permissions | +| -------- | ----- | ------ | ---- | ----------------------- | +| db1 | tbl1 | col1 | key1 | user1 write; user2 read | +| db1 | tbl1 | col2 | key2 | user1 read; user2 read | +| db1 | tbl1 | col3 | key3 | user1 read; user2 read | +| db1 | tbl1 | col4 | | user1 read; user2 read | +| db1 | tbl2 | col1 | key1 | userGroup read | +| db2 | tbl1 | * | key1 | userGroup read | \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/api.md b/website/translated_docs/zh-CN/version-0.5.0/api.md new file mode 100644 index 0000000..bcd93df --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/api.md @@ -0,0 +1,6 @@ +--- +id: version-0.5.0-api +title: '👩🏻‍💻 CovenantSQL API' +original_id: api +--- +## TBD \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/arch.md b/website/translated_docs/zh-CN/version-0.5.0/arch.md new file mode 100644 index 0000000..44a29b1 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/arch.md @@ -0,0 +1,60 @@ +--- +id: version-0.5.0-arch +title: Architecture +original_id: arch +--- + +## 3 Layers Arch + +![CovenantSQL 3 Layer design](https://github.com/CovenantSQL/CovenantSQL/raw/ed2878359345cd86e4221f14cd59e4654361b64e/logo/arch.png) + +- Layer 1: **Global Consensus Layer** (the main chain, the middle ring in the architecture diagram): + - There will only be one main chain throughout the network. + - Mainly responsible for database Miner and the user’s contract matching, transaction settlement, anti-cheating, shard chain lock hash and other global consensus matters. +- Layer 2: **SQL Consensus Layer** (shard chain, rings on both sides): + - Each database will have its own separate shard chain. + - Mainly responsible for: the signature, delivery and consistency of the various Transactions of the database. The data history of the permanent traceability is mainly implemented here, and the hash lock is performed in the main chain. +- Layer 3: **Datastore Layer** (database engine with SQL-92 support): + - Each Database has its own independent distributed engine. + - Mainly responsible for: database storage & encryption, query processing & signature, efficient indexing. + +## Consensus Algorithm + +CQL supports 2 kinds of consensus algorithm: + +1. DPoS (Delegated Proof-of-Stake) is applied in `Eventually consistency mode` database and also `Layer 1 (Global Consensus Layer)` in BlockProducer. CQL miners pack all SQL queries and its signatures by the client into blocks thus form a blockchain. We named the algorithm [`Xenomint`](https://github.com/CovenantSQL/CovenantSQL/tree/develop/xenomint). +2. BFT-Raft (Byzantine Fault-Toleranted Raft)bft-raft is applied in `Strong consistency mode` database. We named our implementation [`Kayak`](https://github.com/CovenantSQL/CovenantSQL/tree/develop/kayak). The CQL miner leader does a `Two-Phase Commit` with `Kayak` to support `Transaction`.transaction + +CQL database consistency mode and node count can be selected in database creation with command `cql create '{"UseEventualConsistency": true, "Node": 3}'` + +## Comparison + +| | Ethereum | Hyperledger Fabric | Amazon QLDB | CovenantSQL | +| ---------------------------- | ----------------- | ---------------------- | ----------- | -------------------------------------------------------------------- | +| **Dev language** | Solidity, ewasm | Chaincode (Go, NodeJS) | ? | Python, Golang, Java, PHP, NodeJS, MatLab | +| **Dev Pattern** | Smart Contract | Chaincode | SQL | SQL | +| **Open Source** | Y | Y | N | Y | +| **Nodes for HA** | 3 | 15 | ? | 3 | +| **Column Level ACL** | N | Y | ? | Y | +| **Data Format** | File | Key-value | Document | Filefuse, Key-value, Structured | +| **Storage Encryption** | N | API | Y | Y | +| **Data Desensitization** | N | N | N | Y | +| **Multi-tenant** | DIY | DIY | N | Y | +| **Throughput (1s delay)** | 15~10 tx/s | 3500 tx/s | ? | 11065 tx/s (Eventually Consistency) +1866 tx/s (Strong Consistency) | +| **Consistency Delay** | 2~6 min | < 1 s | ? | < 10 ms | +| **Secure for Open Internet** | Y | N | Only in AWS | Y | +| **Consensus** | PoW + PoS(Casper) | CFT | ? | DPoS (Eventually Consistency) +BFT-Raft (Strong Consistency) | + +### FootNotes + +- BFT-Raft: A CQL leader offline needs CQL Block Producer to decide whether to wait for leader online for data integrity or promote a follower node for availability. This part is still under construction and any advice is welcome. + +- Transaction: Talking about `ACID`, CQL has full "Consistency, Isolation, Durability" and a limited `Atomicity` support. That is even under strong consistency mode, CQL transaction is only supported on the leader node. If you want to do "read `v`, `v++`, write `v` back" parallelly and atomically, then the only way is "read `v` from the leader, `v++`, write `v` back to leader" + +- FUSE: CQL has a [simple FUSE](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql-fuse) support adopted from CockroachDB. The performance is not very ideal and still has some issues. But it can pass fio test like: + + ```bash + fio --debug=io --loops=1 --size=8m --filename=../mnt/fiotest.tmp --stonewall --direct=1 --name=Seqread --bs=128k --rw=read --name=Seqwrite --bs=128k --rw=write --name=4krandread --bs=4k --rw=randread --name=4krandwrite --bs=4k --rw=randwrite + ``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/arch_layers.md b/website/translated_docs/zh-CN/version-0.5.0/arch_layers.md new file mode 100644 index 0000000..da5b111 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/arch_layers.md @@ -0,0 +1,30 @@ +--- +id: version-0.5.0-arch_layers +title: Blockchains +original_id: arch_layers +--- + + +## MainChain & SQLChain + +CQL uses a layered architecture for database creation and operation. A typical data creation process can be roughly as follows: + +1. Miner will automatically register with the MainChain after startup. The registration information includes: "Minimum acceptable Gas price", "System metrics", "External IP and port", etc. +2. Miner subscribes to and pays attention to information related to themselves through ChainBus; +3. The client runs `cql create '{"node":2}'` to send a signed database creation request to any BP (Block Producer) in the MainChain; +4. The BP that received the request performs a match of Miner and database creation request in the process of producing the block (see: \[MainChain Produce Block\] (#mainchain-produce-block)); +5. Database creation requests and matching results are verified and confirmed at other BP nodes; +6. The Miner subscription receives the database task; +7. Miners discover and connect with each other through Kayak to form a SQLChain database cluster; +8. All miners are ready to wait for a request; +9. Users can connect to the database and execute SQL through the `cql console` command. + +See the image below to view [large picture](https://cdn.jsdelivr.net/gh/CovenantSQL/docs@b7143254adb804dff0e3bc1f2f6ab11ad9cd44f5/website/static/img/2layers.svg)： + +![2layers](https://cdn.jsdelivr.net/gh/CovenantSQL/docs@b7143254adb804dff0e3bc1f2f6ab11ad9cd44f5/website/static/img/2layers.svg) + +## MainChain Produce Block + +The complete main chain export process is complicated. Please refer to the numbers in the figure below for understanding. For the big picture, please click [here](https://cdn.jsdelivr.net/gh/CovenantSQL/docs/website/static/img/produce-block.svg) + +![MainChain Produce Block](https://cdn.jsdelivr.net/gh/CovenantSQL/docs/website/static/img/produce-block.svg) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/arch_network.md b/website/translated_docs/zh-CN/version-0.5.0/arch_network.md new file mode 100644 index 0000000..56a7d28 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/arch_network.md @@ -0,0 +1,281 @@ +--- +id: version-0.5.0-arch_network +title: RPC Framework +original_id: arch_network +--- + +The traditional key exchange like TLS or SSL needs a CA to ensure key exchange run safely. But in DH-RPC I use a DHT to do that. The main idea is removing CA Cert from the whole system by using a DHT for Naming and Key Exchange. + +DH-RPC is a secp256k1-ECDH-AES encrypted P2P RPC framework for decentralized applications written in golang. + +CovenantSQL is built on DH-RPC, including: + +- Byzantine Fault Tolerance consensus protocol [Kayak](https://godoc.org/github.com/CovenantSQL/CovenantSQL/kayak) +- Consistent Secure DHT +- DB API +- Metric Collect +- Blocks sync + +## Usage + +![](https://cdn.jsdelivr.net/gh/CovenantSQL/CovenantSQL@cc4aa933d80a5d31738081d13c7b1587ad47cffb/logo/dh-rpc.svg) + +Alice Client: + +```go +// Init Key Management System +route.InitKMS(PubKeyStoreFile) + +// Register Node public key, addr to Tracker +reqA := &proto.PingReq{ + Node: AliceNode, +} +respA := new(proto.PingResp) +rpc.NewCaller().CallNode(Tracker.NodeID, "DHT.Ping", reqA, respA) + +pc := rpc.NewPersistentCaller(BobNodeID) +respSimple := new(string) +pc.Call("Test.Talk", "Hi there", respSimple) +fmt.Printf("Response msg: %s", *respSimple) +``` + +Bob Server: + +```go +// RPC logic +// TestService to be register to RPC server +type TestService struct {} + +func (s *TestService) Talk(msg string, ret *string) error { + fmt.Println(msg) + resp := fmt.Sprintf("got msg %s", msg) + *ret = resp + return nil +} + +// Init Key Management System +route.InitKMS(PubKeyStoreFile) + +// Register DHT service +server, err := rpc.NewServerWithService(rpc.ServiceMap{ + "Test": &TestService{}, +}) + +// Init RPC server with an empty master key, which is not recommend +server.InitRPCServer("0.0.0.0:2120", PrivateKeyFile, "") + +// Start Node RPC server +server.Serve() +``` + +Tracker stuff can refer to the Example section below + +## Features + +- 100% compatible with Go [net/rpc](https://golang.org/pkg/net/rpc/) standard. +- ID based routing and Key exchange built on Secure Enhanced DHT. +- use MessagePack for serialization which support most types without writing `Marshal` and `Unmarshal`. +- Crypto Schema + - Use Elliptic Curve Secp256k1 for Asymmetric Encryption + - ECDH for Key Exchange + - PKCS#7 for padding + - AES-256-CFB for Symmetric Encryption + - Private key protected by master key + - Anonymous connection is also supported +- DHT persistence layer has 2 implementations: + - SQLite3 based simple traditional DHT + - [Kayak](https://godoc.org/github.com/CovenantSQL/CovenantSQL/kayak) based 2PC strong consistent DHT +- Connection pool based on [smux](https://github.com/xtaci/smux), make thousands of connections multiplexed over **One TCP connection**. + +## Stack + +[DH-RPC](rpc/) := TLS - Cert + DHT + +| Layer | Implementation | +|:------------------ |:------------------------------------------------------------------------------------------------------------:| +| RPC | `net/rpc` | +| Naming | [**C**onsistent **S**ecure **DHT**](https://godoc.org/github.com/CovenantSQL/CovenantSQL/consistent) | +| Pooling | Session Pool | +| Multiplex | [smux](https://github.com/xtaci/smux) | +| Transport Security | [**E**nhanced **TLS**](https://github.com/CovenantSQL/research/wiki/ETLS(Enhanced-Transport-Layer-Security)) | +| Network | TCP or KCP for optional later | + +## How it works + +As we all know, Elliptic Curve Public Key is computed form Private Key + +```go +ECPubKey := ECPrivKey.Pub() +``` + +DH-RPC node is generated by hash of NodePublicKey and an [Uint256 Nonce](../pow/cpuminer/uint256.go): + +```go +NodeID := sha256(blake2b-512(NodePublicKey + Uint256Nonce)) +``` + +DHT is used to hold the `NodeID`:`PublicKey` `NodeID`:`Addr` map. A RPC connection will do ECDH to get shared secret after TCP connection established. + +```go +GenECDHSharedSecret(APub, BPriv) == GenECDHSharedSecret(BPub, APriv) +``` + +The main procedure is described as sequence chart below: + + + +So anyone tries to fake NodeB by overwriting the address or public key on DHT without the private key of NodeB will be failed to get the correct shared secret. + +## Example + +The example below is 1 tracker and 2 nodes. + +Complete code can be found [here](_example/) + +#### Tracker Code + +```go +package main + +import ( + "os" + + "github.com/CovenantSQL/CovenantSQL/conf" + "github.com/CovenantSQL/CovenantSQL/consistent" + "github.com/CovenantSQL/CovenantSQL/route" + "github.com/CovenantSQL/CovenantSQL/rpc" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + //log.SetLevel(log.DebugLevel) + conf.GConf, _ = conf.LoadConfig(os.Args[1]) + log.Debugf("GConf: %#v", conf.GConf) + + // Init Key Management System + route.InitKMS(conf.GConf.PubKeyStoreFile) + + // Creating DHT RPC with simple persistence layer + dht, err := route.NewDHTService(conf.GConf.DHTFileName, new(consistent.KMSStorage), true) + if err != nil { + log.Fatalf("init dht failed: %v", err) + } + + // Register DHT service + server, err := rpc.NewServerWithService(rpc.ServiceMap{route.DHTRPCName: dht}) + if err != nil { + log.Fatal(err) + } + + // Init RPC server with an empty master key, which is not recommend + addr := conf.GConf.ListenAddr + masterKey := []byte("") + server.InitRPCServer(addr, conf.GConf.PrivateKeyFile, masterKey) + server.Serve() +} +``` + +#### Node Code + +```go +package main + +import ( + "bufio" + "fmt" + "os" + "strings" + + "github.com/CovenantSQL/CovenantSQL/conf" + "github.com/CovenantSQL/CovenantSQL/proto" + "github.com/CovenantSQL/CovenantSQL/route" + "github.com/CovenantSQL/CovenantSQL/rpc" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +// TestService to be register to RPC server +type TestService struct { +} + +func NewTestService() *TestService { + return &TestService{} +} + +func (s *TestService) Talk(msg string, ret *string) error { + fmt.Println(msg) + resp := fmt.Sprintf("got %s", msg) + *ret = resp + return nil +} + +func main() { + //log.SetLevel(log.DebugLevel) + conf.GConf, _ = conf.LoadConfig(os.Args[1]) + log.Debugf("GConf: %#v", conf.GConf) + + // Init Key Management System + route.InitKMS(conf.GConf.PubKeyStoreFile) + + // Register DHT service + server, err := rpc.NewServerWithService(rpc.ServiceMap{ + "Test": NewTestService(), + }) + if err != nil { + log.Fatal(err) + } + + // Init RPC server with an empty master key, which is not recommend + addr := conf.GConf.ListenAddr + masterKey := []byte("") + server.InitRPCServer(addr, conf.GConf.PrivateKeyFile, masterKey) + + // Start Node RPC server + go server.Serve() + + // Register Node public key, addr to Tracker(BP) + for _, n := range conf.GConf.KnownNodes { + client := rpc.NewCaller() + reqA := &proto.PingReq{ + Node: n, + } + respA := new(proto.PingResp) + err = client.CallNode(conf.GConf.BP.NodeID, "DHT.Ping", reqA, respA) + if err != nil { + log.Fatal(err) + } + log.Debugf("respA: %v", respA) + } + + // Read target node and connect to it + scanner := bufio.NewScanner(os.Stdin) + fmt.Print("Input target node ID: ") + scanner.Scan() + if scanner.Err() == nil { + target := proto.NodeID(strings.TrimSpace(scanner.Text())) + pc := rpc.NewPersistentCaller(target) + log.Debugf("connecting to %s", scanner.Text()) + + fmt.Print("Input msg: ") + for scanner.Scan() { + input := scanner.Text() + log.Debugf("get input %s", input) + repSimple := new(string) + err = pc.Call("Test.Talk", input, repSimple) + if err != nil { + log.Fatal(err) + } + log.Infof("resp msg: %s", *repSimple) + } + } +} +``` + +Start tracker and node1, node2 + +```bash +$ ./runTracker.sh & +$ ./runNode2.sh & +$ ./runNode1.sh +$ Input target node ID: 000005aa62048f85da4ae9698ed59c14ec0d48a88a07c15a32265634e7e64ade #node2 +$ Input msg: abcdefg +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/bck/api-json-rpc.md b/website/translated_docs/zh-CN/version-0.5.0/bck/api-json-rpc.md new file mode 100644 index 0000000..2935ee1 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/bck/api-json-rpc.md @@ -0,0 +1,443 @@ +--- +id: version-0.5.0-api-json-rpc +title: JSON RPC +original_id: api-json-rpc +--- + +> JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. + +CovenantSQL provides a suite of RPC methods in [JSON-RPC 2.0](https://www.jsonrpc.org/specification) for easily accessing to CovenantSQL networks. + +## Javascript API + +[cql.js](https://github.com/covenantsql/cql.js) is a Javascript SDK which has encapsulated the RPC methods in order to give a much more convenient way to talk to the CovenantSQL networks. See the [Javascript API](cql-js.md) for more. + +## JSON RPC Endpoint + +| Network | Provider | URL | +| ------------------------ | ------------- | -------------------------------------- | +| CovenantSQL Test Network | Covenant Labs | https://jsonrpc.testnet.covenantsql.io | +| CovenantSQL Main Network | Covenant Labs | Comming soon :) | + +## JSON RPC API Reference + +### bp_getProtocolVersion + +Returns the current CovenantSQL protocol version. + +#### Parameters + +None. + +#### Returns + +- string - the current CovenantSQL protocol version + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "method": "bp_getProtocolVersion", + "params": [], + "id": 1 +} +``` + +Response: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0.1.0" +} +``` + +### bp_getRunningStatus + +Returns some basic indicators describing the running status of the CovenantSQL network. + +#### Parameters + +None. + +#### Returns + +- object: an object describes the running status of the network. + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getRunningStatus", + "params": [] +} +``` + +Response: + +```js +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "block_height": 182414, // height of the latest block + "count_accounts": 103, // count of the accounts ever created + "count_shardchains": 912414, // count of the databases ever created + "qps": 10241 // estimated QPS of database operations of the whole net + "storage_size": 109870095269 // storage size + } +} +``` + +### bp_getBlockList + +Returns a list of the blocks. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ----- | ------- | ---------------------- | ------ | +| 0 | since | integer | since height, excluded | 1024 | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the blocks, the object in the list is a [Block](#s-block), but **without** transaction details + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockList", + "params": [1024, 1, 10] +} +``` + +Response: [Block](#s-block) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "blocks" [ { TODO: block object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 102, + "pages": 11 + } +} +``` + +### bp_getBlockListByTimeRange + +TODO: as a new API in the next release + +### bp_getBlockByHeight + +Returns information about the block specified by its height. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | height of the block | 1024 | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHeight", + "params": [1] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getBlockByHash + +Returns information about the block specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------- | ------ | +| 0 | hash | string | hash of the block | "TODO" | + +#### Returns + +- object: block information object, it's a [Block](#s-block) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getBlockByHash", + "params": ["TODO"] +} +``` + +Response: [Block](#s-block) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: block object + } +} +``` + +### bp_getTransactionList + +Returns a list of the transactions. Traverse page by page by using a transaction hash as the mark for paging. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ----- | ------- | -------------------- | ------ | +| 0 | since | string | since hash, excluded | "TODO" | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionList", + "params": ["KhytGjS0xjw5CJvcJYpsNg", 1, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "transactions": [ { TODO: transaction object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 8, + "pages": 1 + } + } +} +``` + +### bp_getTransactionListOfBlock + +Returns a list of the transactions from a block by the specified height. + +| Position | Name | type | Description | Sample | +| -------- | ------ | ------- | ------------------- | ------ | +| 0 | height | integer | of block height | 1024 | +| 1 | page | integer | page number | 1 | +| 2 | size | integer | page size, max 1000 | 10 | + +#### Returns + +- array: list of the transactions, the object in the list is a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionListOfBlock", + "params": [1024, 1, 10] +} +``` + +Response: [Transaction](#s-transaction) array + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "transactions": [ { TODO: transaction object } ], + "pagination": { + "page": 1, + "size": 10, + "total": 8, + "pages": 1 + } + } +} +``` + +### bp_getTransactionByHash + +Returns information about the transaction specified by its hash. + +#### Parameters + +| Position | Name | type | Description | Sample | +| -------- | ---- | ------ | ----------------------- | ------ | +| 0 | hash | string | hash of the transaction | "TODO" | + +#### Returns + +- object: transaction information object, it's a [Transaction](#s-transaction) + +#### Example + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "bp_getTransactionByHash", + "params": ["TODO"] +} +``` + +Response: [Transaction](#s-transaction) + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + TODO: transaction object + } +} +``` + +## Structure Reference + +Here are some common structure definitions used in the API. + + + +### Block + +The block generated in the CovenantSQL blockchain network. + +| Field | Type | Description | +| --------------- | ------- | ------------------------------------------------------- | +| height | integer | Height of the block | +| hash | string | Hash of the block | +| version | integer | Version number of the block | +| producer | string | Address of the node who generated this block | +| merkle_root | string | Hash of the merkle tree | +| parent | string | Hash of its parent block | +| timestamp | integer | Create time of the block, unix time in nanoseconds | +| timestamp_human | string | Create time of the block, human readable RFC3339 format | +| tx_count | integer | Count of the transactions in this block | + +Sample in JSON format: + +```json +{ + "height": 12, + "hash": "TODO", + "version": 1, + "producer": "4io8u9v9nydaQPXtmqibg8gJbkNFd7DdM47PLWuM7ubzBXZ4At7", + "merkle_root": "TODO", + "parent": "TODO", + "timestamp": "TODO", + "timestamp_human": "TODO", + "tx_count": 1 +} +``` + + + +### Transaction + +| Field | Type | Description | +| --------------- | ------- | ------------------------------------------------------------------------------------------- | +| block_height | integer | Height of the block this transaction belongs to | +| index | integer | Index of the transaction in the block | +| hash | string | Hash of the transaction data | +| block_hash | string | Hash of the block this transaction belongs to | +| type | integer | Type of the transaction | +| address | string | Account address who signed this transaction | +| timestamp | integer | Create time of the transaction, unix time in nanoseconds | +| timestamp_human | string | Create time of the transaction, human readable RFC3339 format | +| raw | string | Raw content of the transaction data, in JSON format | +| tx | object | Concrete transaction object, see supported [transaction types](#transaction-types) for more | + +Sample in JSON format: + +```json +{ + "block_height": 1, + "index": 0, + "hash": "TODO", + "block_hash": "TODO", + "timestamp": "TODO", + "timestamp_human": "TODO", + "type": 1, + "address": "TODO", + "raw": "TODO", + "tx": { + "field": "TODO" + } +} +``` + +**Supported Transaction Types:** + +- [CreateDatabase](#s-transaction-createdatabase) + +TODO: more types + + + +### Transaction: CreateDatabase + +TODO: more types \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/bck/development-cmd-cql-utils-zh.md b/website/translated_docs/zh-CN/version-0.5.0/bck/development-cmd-cql-utils-zh.md new file mode 100644 index 0000000..619f261 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/bck/development-cmd-cql-utils-zh.md @@ -0,0 +1,42 @@ +--- +id: version-0.5.0-keygen +title: 使用 cql-utils 生成密钥与钱包 +original_id: keygen +--- + +`cql-utils` 是 CovenantSQL 的一个命令行工具，具体用法如下。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 使用 + +### 生成公私钥对 + + $ cql-utils -tool keygen + Enter master key(press Enter for default: ""): + ⏎ + Private key file: private.key + Public key's hex: 03bc9e90e3301a2f5ae52bfa1f9e033cde81b6b6e7188b11831562bf5847bff4c0 + + +生成的 private.key 文件即是使用主密码加密过的私钥文件，而输出到屏幕上的字符串就是使用十六进制进行编码的公钥。 + +### 使用私钥文件或公钥生成钱包地址 + + $ cql-utils -tool addrgen -private private.key + Enter master key(default: ""): + ⏎ + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + $ cql-utils -tool addrgen -public 02f2707c1c6955a9019cd9d02ade37b931fbfa286a1163dfc1de965ec01a5c4ff8 + wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 + + +你可以通过指定私钥文件，或者把上述的公钥十六进制编码字符串作为命令行参数来直接生成钱包地址。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/bck/development-cmd-cql-zh.md b/website/translated_docs/zh-CN/version-0.5.0/bck/development-cmd-cql-zh.md new file mode 100644 index 0000000..fe17f21 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/bck/development-cmd-cql-zh.md @@ -0,0 +1,78 @@ +--- +id: version-0.5.0-cql +title: 使用命令行客户端 cql 创建数据库 +original_id: cql +--- + +本文档主要介绍 CovenantSQL 命令行客户端 `cql` 的使用。`cql` 是一个用于批量进行 SQLChain 上数据库的创建、查询、更新或删除操作的命令行工具。 + +## 安装 + +下载 [最新发布版本](https://github.com/CovenantSQL/CovenantSQL/releases) 或直接从源码编译： + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql +``` + +*保证 Golang 环境变量 `$GOPATH/bin` 已在 `$PATH` 中* + +## 生成默认配置文件 + +首先需要一个 config 文件和由你输入的主密码（master key）来初始化，其中主密码用来加密解密本地密钥对。使用 `cql-utils` 工具进行配置文件生成后，你可以在生成的配置文件目录下找到密钥文件。 + +具体请参考: [cql-utils 使用文档](https://github.com/CovenantSQL/docs/tree/master/development-cmd-utils-zh.md#使用) 中配置文件及钱包地址生成相关章节。 + +## 检查钱包余额 + +使用 `cql` 命令来检查钱包余额： + +```bash +$ cql -config conf/config.yaml -get-balance +INFO[0000] +### Public Key ### +0388954cf083bb6bb2b9c7248849b57c76326296fcc0d69764fc61eedb5b8d820c +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +这里我们得到结果 **"stable coin balance is: 100"**。 + +## 初始化一个 CovenantSQL 数据库 + +准备好配置文件和主密码后就可以使用 `cql` 命令来创建数据库了，你的数据库 ID 将会输出到屏幕上： + +```bash +# if a non-default password applied on master key, use `-password` to pass it +$ cql -config conf/config.yaml -create 1 +INFO[0000] +### Public Key ### +039bc931161383c994ab9b81e95ddc1494b0efeb1cb735bb91e1043a1d6b98ebfd +### Public Key ### + caller="privatekeystore.go:116 crypto/kms.InitLocalKeyPair" +INFO[0000] the newly created database is: covenantsql://0e9103318821b027f35b96c4fd5562683543276b72c488966d616bfe0fe4d213 caller="main.go:297 main.main" +``` + +这里 `-create 1` 表示创建一个单节点的 SQLChain。 + +```bash +$ cql -config conf/config.yaml -dsn covenantsql://address +``` + +`address` 就是你的数据库 ID。 + +`cql` 命令的详细使用帮助如下： + +```bash +$ cql -help +``` + +## 使用 `cql` + +现在可以使用 `cql` 进行数据库操作了: + +```bash +co:address=> show tables; +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/bck/development-golang-client-zh.md b/website/translated_docs/zh-CN/version-0.5.0/bck/development-golang-client-zh.md new file mode 100644 index 0000000..45ec3f0 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/bck/development-golang-client-zh.md @@ -0,0 +1,109 @@ +--- +id: version-0.5.0-golang-client +title: 使用 Golang 驱动访问数据库 +original_id: golang-client +--- + +本文档介绍 CovenantSQL 客户端的使用方式。客户端用来创建、查询、更新和删除 SQLChain 以及绑定的数据库。 + +## 开始之前 + +确保 `$GOPATH/bin` 目录在环境变量 `$PATH` 中，执行以下命令 + +```bash +$ go get github.com/CovenantSQL/CovenantSQL/client +$ go get github.com/CovenantSQL/CovenantSQL/cmd/cql-utils +``` + +然后在你的 go 代码中 import 第一个 `client` 包。 + +## 初始化一个 CovenantSQL 客户端 + +首先需要一个 config 文件和 master key 来初始化。master key 用来加密解密本地密钥对。以下是如何用一个自定义 master key 来生成默认的 config 文件： + +### 生成默认的配置文件 + +运行以下 `cql-utils` 命令，输入 master key（类似密码）来生成本地密钥对。等待几十秒，会在 `~/.cql` 文件夹中，生成一个私钥文件和一个名为 `config.yaml` 的配置文件。 + +```bash +./cql-utils -tool confgen +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: ~/.cql/private.key +Public key's hex: 025abec9b0072615170f4acf4a2fa1162a13864bb66bc3f140b29f6bf50ceafc75 +Generated key pair. +Generating nonce... +INFO[0005] cpu: 1 +INFO[0005] position: 0, shift: 0x0, i: 0 +nonce: {{1450338416 0 0 0} 26 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514} +node id: 0000002dd8bdb50ba0270642e4c4bc593c1630ef7784653f311b3c3d6374e514 +Generated nonce. +Generating config file... +Generated nonce. +``` + +有了配置文件之后，可以通过以下 go 代码来初始化 CovenantSQL 客户端： + +```go +client.Init(configFile, masterKey) +``` + +## 客户端使用方式 + +### 创建一个 SQLChain 数据库 + +创建 SQLChain 数据库需要指明需要几个节点（nodeCount变量）: + +```go +var ( + dsn string + meta client.ResourceMeta +) +meta.Node = uint16(nodeCount) +dsn, err = client.Create(meta) +// process err +``` + +创建完毕会返回一个 dsn 字符串，用来访问这个数据库。 + +### 查询和执行 + +拿到 dsn 字符串后，可以通过以下代码在 SQLChain 中执行 SQL 语句： + +```go +
db, err := sql.Open("covenantsql", dsn) + // process err + + _, err = db.Exec("CREATE TABLE testSimple ( column int );") + // process err + + _, err = db.Exec("INSERT INTO testSimple VALUES(?);", 42) + // process err + + row := db.QueryRow("SELECT column FROM testSimple LIMIT 1;") + + var result int + err = row.Scan(&result) + // process err + fmt.Printf("SELECT column FROM testSimple LIMIT 1; result %d\n", result) + + err = db.Close() + // process err + +``` + +用法和其他 go sql driver 一致。 + +### 删除数据库 + +使用 dsn 来删除数据库： + +```go + err = client.Drop(dsn) + // process err +``` + +### 完整示例 + +在以下目录中有一个简单示例和复杂示例可以参考 [示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/bck/getting-started-overview-zh.md b/website/translated_docs/zh-CN/version-0.5.0/bck/getting-started-overview-zh.md new file mode 100644 index 0000000..75df5c6 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/bck/getting-started-overview-zh.md @@ -0,0 +1,62 @@ +--- +id: version-0.5.0-intro +title: 简介 +original_id: intro +--- + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +- **SQL**: 支持 SQL-92 标准 +- **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +- **隐私**: 通过加密和授权许可进行访问 +- **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信[在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +#### 一行代码接入区块链数据 + +```go +sql.Open("CovenantSQL", dbURI) +``` + +# # + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +- 第一层: **全局共识层**(主链，架构图中的中间环): + - 整个网络中只有一个主链。 + - 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +- 第二层: **SQL 共识层**(子链，架构图中的两边环): + - 每个数据库都有自己独立的子链。 + - 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +- 第三层: **数据储存层**(支持 SQL-92 的数据库引擎): + - 每个数据库都有自己独立的分布式引擎。 + - 主要负责：数据库存储和加密；查询处理和签名；高效索引。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/bck/getting-started-testnet-zh.md b/website/translated_docs/zh-CN/version-0.5.0/bck/getting-started-testnet-zh.md new file mode 100644 index 0000000..80988af --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/bck/getting-started-testnet-zh.md @@ -0,0 +1,97 @@ +--- +id: version-0.5.0-testnet +title: CovenantSQL 测试网快速入门 +original_id: testnet +--- + +[CovenantSQL](https://github.com/CovenantSQL/CovenantSQL/blob/develop/README-zh.md) 是一个基于区块链技术的去中心化众筹式 SQL 数据库，并具备以下特点： + +1. **SQL**: 支持 SQL-92 标准 +2. **去中心化**: 基于独有的高效共识算法 DH-RPC 和 Kayak 实现的中心化 +3. **隐私**: 通过加密和授权许可进行访问 +4. **不可篡改**: CovenantSQL 中的查询历史记录是不可变且可跟踪的 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## 0. 下载 CovenantSQL 工具 + +在 [github](https://github.com/CovenantSQL/CovenantSQL/releases) 下载最新的发行版 + +## 1. 用 `cql-utils` 生成配置文件访问测试网 + +```bash +$ cql-utils -tool confgen +Generating key pair... +Enter master key(press Enter for default: ""): +⏎ +Private key file: ~/.cql/private.key +Public key's hex: 02296ea73240dcd69d2b3f1fb754c8debdf68c62147488abb10165428667ec8cbd +Generated key pair. +Generating nonce... +nonce: {{731613648 0 0 0} 11 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9} +node id: 001ea9c8381c4e8bb875372df9e02cd74326cbec33ef6f5d4c6829fcbf5012e9 +Generated nonce. +Generating config file... +Generated nonce. +``` + +该命令会为你在~目录下创建一个 `.cql` 目录： + +- `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +## 2. 用私钥生成钱包地址 + +私钥可以再上一步的 `~/.cql` 目录中找到，文件名为 `private.key` + +```bash +$ cql-utils -tool addrgen -private ~/.cql/private.key +Enter master key(default: ""): +⏎ +wallet address: 4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9 +``` + +上述 `4jXvNvPHKNPU8Sncz5u5F5WSGcgXmzC1g8RuAXTCJzLsbF9Dsf9` 就是钱包地址 + +## 3. 在水龙头(Faucet)获取 Particle(PTC) + +水龙头(Faucet)的地址为: [CovenantSQL 测试网 Particle(PTC) 水龙头](https://testnet.covenantsql.io/)。 + +完成教程之后，用 `cql` 命令来检查钱包地址的余额(未加-config参数时，命令会自动找~/.cql目录的config.yaml文件)： + +```bash +$ cql -get-balance +INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" +INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" +``` + +当看到 **"stable coin balance is: 100"** 时，表明余额已经为 100。 + +如果您需要更多的 PTC 作为长期测试使用，请联系 。 + +对于有合作的商业伙伴，我们将直接提供 PTC 以供使用。 + +## 4. 使用 `CLI` 创建数据库 + +```bash +$ cql -create 1 +INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" +``` + +第一行命令中的 `1` 表示申请几个矿工为你的数据库服务。`covenantsql://...` 开头的这个字符串就是创建的数据库访问地址，在 SDK 和 CLI 命令中都需要用此地址，在整个区块链中找到这个数据库。 + +## 5. CLI 和 SDK 的详细文档 + +创建好数据库后，您可以参考以下文档和示例，以便更快的使用CovenantSQL来开发应用。 + +- [CLI 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql/README-zh.md) +- [SDK 文档](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/README-zh.md) +- [SDK 示例](https://github.com/CovenantSQL/CovenantSQL/tree/develop/client/_example) + +## 6. SQLChain 浏览器 + +目前，测试网的数据库时不需要权限的。意味着您可以通过数据库的DSN(数据库访问地址)，在[SQLChain 浏览器](https://explorer.dbhub.org)中拿到所有的修改历史和区块信息。 + +更多的测试网技术支持，请访问: + +> [TestNet 发行日志](https://github.com/CovenantSQL/CovenantSQL/wiki/Release-Notes-zh) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/bck/getting-started-zh.md b/website/translated_docs/zh-CN/version-0.5.0/bck/getting-started-zh.md new file mode 100644 index 0000000..e8530b1 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/bck/getting-started-zh.md @@ -0,0 +1,487 @@ +--- +id: version-0.5.0-local-deployment +title: CovenantSQL 综述 +original_id: local-deployment +--- + +# CovenantSQL 介绍 + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + follow on Twitter + + Join the chat at https://gitter.im/CovenantSQL/CovenantSQL +

+ +CovenantSQL 是应用区块链技术构建的去中心化 SQL 云数据库， + +结合了区块链、共享经济、分布式数据库的优势，保障了用户隐私及对数据的所有权。 + +CovenantSQL 具备以下特点： + +* **SQL接口**: 支持 SQL-92 标准，传统 App 几乎0修改即可变成 ĐApp +* **去中心化**: 基于独有的高效拜占庭容错共识算法 Kayak 实现的去中心化结构 +* **不可篡改**: CovenantSQL 中的 Query 历史记录是可追溯的 +* **隐私**: 如果 Bitcoin 是用户的钱包，那么 CovenantSQL 就是是用户的去中心化数据库 + +我们相信 [在下一个互联网时代，每个人都应该有完整的**数据权利**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +## CovenantSQL 原理 + +CovenantSQL 是一个运行在 Internet 上的开放网络，主要有以下三种角色组成： + +* 主链节点： + * 通过去中心化的架构，DPoS 模式的共识机制对矿工和用户进行撮合、协调、仲裁 +* 侧链矿工： + * 所有人都可以通过运行 Covenant Miner 来提供数据库服务来赚取奖励 + * 通过 ETLS 传输层加密、应用层签名、落盘加密、端到端加密 保证用户数据隐私 +* 数据库用户： + * 用户通过一个私钥就可以创建指定数量节点的分布式数据库，存储自己的结构化数据 + * 数据矿工的分布和地址仅对数据库用户可见，防止用户数据被嗅探 + * 通过 **去中心化的高可用的架构** 和 **Miner 押金机制**，用户的数据可以在成本和可靠性、可用性上达到平衡可控 + +![CovenantSQL 3 Layer design](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/logo/arch.png) + +* 第一层：**全局共识层**（主链，架构图中的中间环）: + * 整个网络中只有一个主链。 + * 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。 +* 第二层：**SQL 共识层**（子链，架构图中的两边环）: + * 每个数据库都有自己独立的子链。 + * 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。 +* 第三层：**数据储存层**（支持 SQL-92 的数据库引擎）: + * 每个数据库都有自己独立的分布式引擎。 + * 主要负责：数据库存储和加密；查询处理和签名；高效索引。 + +# 安装 CovenantSQL 客户端 + +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```bash +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```bash +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +* [Go](./development-golang-client-zh.md) +* [Java](https://github.com/CovenantSQL/cql-java-driver) +* [Python](https://github.com/CovenantSQL/cql-python-driver) +* [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```bash +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你在~目录下创建一个 `.cql` 目录： + +* `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +* `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```bash +./cql-utils -tool addrgen -private ~/.cql/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额(未加 -config 参数时，命令会自动找 ~/.cql 目录的 config.yaml 文件)： + +```bash +./cql -config ~/.cql/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +* [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 + +# 部署 CovenantSQL + +## 使用 CovenantSQL Docker 部署 + +### 安装 Docker + +需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### 启动 Docker 容器 + +执行以下的命令在本地运行 CovenantSQL + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +make docker +make start +``` + +后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行`export COVENANTSQL_ROOT=$PWD`存为环境变量 + +### 检查运行状态 + +```bash +docker-compose ps +``` + +确认所有组件都处于 `Up` 的状态 + +```bash + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp +covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp +covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp +covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp +covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp +``` + +### SQLChain Observer + +我们在`:11108`端口提供了一个 SQLChain 的 Observer 可以看到 SQL 语句在链上的情况 + +# 操作 CovenantSQL + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```bash +cql -config config/config.yaml -create 1 +``` + +> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例 + +```bash +cql -config config/config.yaml -create 2 +``` + +命令会返回创建的数据库实例的连接串 + +```bash +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### 访问数据库 + +使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问 + +```bash +cql -config config/config.yaml -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +会得到如下输出，并进入 `cql` 交互命令行模式 + +```bash +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果 + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +会得到如下输出 + +```bash +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行 + +# 使用 CovenantSQL 开发 App + +## Golang 使用 CovenantSQL + +#### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +#### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +#### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```bash +go get github.com/CovenantSQL/CovenantSQL/client +``` + +#### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +#### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` + +# CovenantSQL API + +# 常见问题解答 + +补充 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/bck/guide-zh.md b/website/translated_docs/zh-CN/version-0.5.0/bck/guide-zh.md new file mode 100644 index 0000000..3fb04dc --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/bck/guide-zh.md @@ -0,0 +1,115 @@ +--- +id: version-0.5.0-guide-zh +title: 快速开始 +original_id: guide-zh +--- + +## 下载 CovenantSQL 工具包 + +请 [下载最新版 CovenantSQL 工具包](https://github.com/CovenantSQL/CovenantSQL/releases)。您将得到以下命令行工具：`cql`、`cql-utils`。 + +## 创建并访问 CovenantSQL 数据库 + +我们已经上线了 CovenantSQL 测试网，也为您准备了一个公共的测试账号，请下载账号配置文件和私钥：[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/feature/chainBus-SQLChain/test/service/node_c/config.yaml)、[private.key](https://github.com/CovenantSQL/CovenantSQL/raw/feature/chainBus-SQLChain/test/service/node_c/private.key) 用于测试。 + +**注**：该账号是公共的且只供测试使用，请不要在该账号创建的数据库中存放您的应用信息，我们会不定期清理数据库数据。 + +### 使用 cql 命令行工具创建数据库 + +```bash +./cql -config config.yaml -create 1 +``` + +输出： + + INFO[0000] the newly created database is: "covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872?use_follower=false&use_leader=true" + + +这里表示您创建了 `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` 这个数据库。 + +### 使用 cql 命令行工具访问数据库 + +```bash +./cql -config config.yaml -dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +连接上数据库后，您可以按您操作数据库的习惯来操作 CovenantSQL 上的数据库。比如执行 `CREATE TABLE` 创建表、`SELECT` 查询数据等操作。 + +### 使用数据库驱动访问数据库 + +- [Go](./development-golang-client-zh.md) +- [Java](https://github.com/CovenantSQL/cql-java-driver) +- [Python](https://github.com/CovenantSQL/cql-python-driver) +- [Javascript（开发中）](https://github.com/CovenantSQL/cql.js) + +## 通过区块浏览器查看您的数据库操作记录 + +CovenantSQL 有一个特性是**其操作记录是不可变且可跟踪的**，您可以通过 [测试网区块浏览器](https://explorer.dbhub.org/) 来查询某个数据库的操作记录。查询时，请在其页面右上角填入您的数据库地址。 + +## 创建账号 + +我们的测试网支持您创建自己的的账号，并在自己的账号下创建数据库。通过以下的命令创建账号（需要输入主密码）： + +```bash +./cql-utils -tool confgen +``` + +输出： + + Generating key pair... + Enter master key(press Enter for default: ""): + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +该命令会为你在~目录下创建一个 `.cql` 目录： + +- `~/.cql/private.key`: 为你生成的私钥通过主密码加密保存在该文件中，你的账号地址需要使用该文件创建； +- `~/.cql/config.yaml`: 为你生成的配置，cql 可以通过读取该配置来访问 CovenantSQL 测试网。 + +再运行命令用来生成账号地址（也叫钱包地址、CovenantSQL 地址）： + +```bash +./cql-utils -tool addrgen -private ~/.cql/private.key +``` + +输出： + + wallet address: 4kcCg4niPjWURuFyT633V8TF9Xb9PvUR5Xbf6aTvGxFZkJFQaS9 + + +您可以在我们的 [CovenantSQL 测试网](https://testnet.covenantsql.io/) 输入您生成的钱包地址，通过发微博、推特等社交媒体来帮助我们推广我们的项目，我们会为您的钱包充值。 + +使用 cql 命令行工具查询余额(未加 -config 参数时，命令会自动找 ~/.cql 目录的 config.yaml 文件)： + +```bash +./cql -config ~/.cql/config.yaml -get-balance +``` + +输出： + + INFO[0000] stable coin balance is: 100 caller="main.go:246 main.main" + INFO[0000] covenant coin balance is: 0 caller="main.go:247 main.main" + + +## 部署私有 CovenantSQL 数据库（搭建私链） + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +- [Docker 一键部署 CovenantSQL 测试网](./getting-started-zh.md) + +## CovenantSQL 联盟链解决方案 + +正在建设中，如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/cql.md b/website/translated_docs/zh-CN/version-0.5.0/cql.md new file mode 100644 index 0000000..5c15d84 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/cql.md @@ -0,0 +1,625 @@ +--- +id: version-0.5.0-cql +title: Client +original_id: cql +--- + +## Intro + +CovenantSQL provides a `cql` command line toolset for terminal users to access and manage user accounts, wallet balances, and databases. Check the complete toolset installation tutorial at \[CovenantSQL Toolset installation\](quickstart#工具包安装). + +### Private Key and Config File + +The `cql` command needs to rely on a private key file `private.key` and a config file `config.yaml`: + +- `private.key`：a private key file which is generated while creating an account, be sure to keep it safe +- `config.yaml`：mainly used to config the CovenantSQL network for `cql` command to connect (e.g., the [TestNet](quickstart) or the [Docker Environment by One Click](deployment)) + +For security, the private key file is usually encrypted with a master key. A master key is individually chosen by the user while creating an account and is memorized or kept somewhere by the user -- note that the config file will not keep the master key. When the private key is required by the `cql` command, it will ask the user to input the master key to decrypt the private key file. + +### Common Parameters for Sub-commands + +The following parameters are commonly used by `cql` sub-commands: + + -bypass-signature + Disable signature signing and verifying, for testing only + -config string + Config file for covenantsql (Usually no need to set, default is enough.) (default "~/.cql/config.yaml") + -no-password + Use an empty master key + -password string + Master key for covenantsql (NOT SAFE, for debugging or script mode only) + + +Note that the private key file path is specified in the config file, and its default value is `./private.key`, indicating that it's located in the same directory of the config. So usually we put the private key file together with config, instead of using an individual parameter to specify the private key file. + +## Account Management + +For the TestNet environment, we provide a public account for quick testing. Check the [CovenantSQL TestNet](quickstart) tutorial to find out the private key and config file of the public account. And you can also follow the next section to create an individual account with `cql` command. + +### Creating New Account + +The sub-command `generate` generates a private key file and a config file connecting to the TestNet in the specified directory, e.g.: + +```bash +cql generate config +``` + +> Currently, the generated config file is pointed to the TestNet, we will provide options to generated config for Docker Environment later. + +For a complete help message, check [Complete Parameters](#sub-command-generate-complete-parameters). + +Output: + + Generating key pair... + Enter master key(press Enter for default: ""): + + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +### Acquiring the Public Key + +The sub-command `generate` is also used to acquire the public key (in hex string format) of the private key file, e.g.: + +```bash +cql generate public +``` + +Output： + + Enter master key(press Enter for default: ""): + + INFO[0011] init config success path=/home/levente/.cql/private.key + INFO[0011] use public key in config file: /home/levente/.cql/config.yaml + Public key's hex: 02fd4089e7f4ca224f576d4baa573b3e9662153c952fce3f87f9586ffdd11baef6 + + +> This functionality is usually not used in common scene + +### Sub-command `generate` Complete Parameters + +Also see [Common Parameters for Sub-commands](#common-parameters-for-sub-commands). We will not mention this in the further sub-command introductions. + + usage: cql generate [parameters]... config | public + + Generate command can generate private.key and config.yaml for CovenantSQL. + e.g. + cql generate config + + Params: + + + +### Mine a Node ID + +The sub-command `idminer` is used to mine another Node ID of a private key (specified by a config file), (also check [Node ID](terms#Node-ID) for details). e.g.: + +```bash +cql idminer +``` + +Output: + + INFO[0000] cql build: cql develop-34ae741a-20190415161544 linux amd64 go1.11.5 + Enter master key(press Enter for default: ""): + + INFO[0008] init config success path=/home/levente/.cql/config.yaml + INFO[0008] use public key in config file: /home/levente/.cql/config.yaml + INFO[0008] cpu: 8 + INFO[0008] position: 3, shift: 0x20, i: 7 + INFO[0008] position: 0, shift: 0x0, i: 0 + INFO[0008] position: 3, shift: 0x0, i: 6 + INFO[0008] position: 1, shift: 0x0, i: 2 + INFO[0008] position: 2, shift: 0x0, i: 4 + INFO[0008] position: 1, shift: 0x20, i: 3 + INFO[0008] position: 2, shift: 0x20, i: 5 + INFO[0008] position: 0, shift: 0x20, i: 1 + nonce: {{1251426 4506240821 0 0} 25 00000041bc2b3de3bcb96328d0004c684628a908f0233eb31fe9998ef0c6288e} + node id: 00000041bc2b3de3bcb96328d0004c684628a908f0233eb31fe9998ef0c6288e + + +> This functionality is usually not used in common scene + +### Sub-command `idminer` Complete Parameters + + usage: cql idminer [parameter]... + + IDMiner command can calculate legal node id and it's nonce. Default 24 difficulty and no endless loop. + e.g. + cql idminer -difficulty 24 + + If you want to mine a good id, use: + cql idminer -config ~/.cql/config.yaml -loop -difficulty 24 + + Params: + -difficulty int + the difficulty for a miner to mine nodes and generating a nonce (default 24) + -loop + mining endless loop + + +## Wallet Management + +### Wallet Address + +Once the private key and config file is set, we can use sub-command `wallet` to check the wallet address of the account: + +```bash +cql wallet +``` + +Output: + + Enter master key(press Enter for default: ""): + + wallet address: 43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 + + +The wallet address of the test account here is `43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40`. + +### Wallet Balances + +We can also use sub-command `wallet` to check the balances in the wallet. CovenantSQL currently supports 5 types of tokens: + +- `Particle` +- `Wave` +- `Bitcoin` +- `Ether` +- `EOS` + +Among them, `Particle` and `Wave` are the token types used by CovenantSQL. To check the token balances, use: + +```bash +cql wallet -balance all +``` + +Output: + + INFO[0000] Particle balance is: 10000000000000000000 + INFO[0000] Wave balance is: 10000000000000000000 + + +You can also check the balance of a specified type of token, e.g., checking the balance of `Bitcoin`: + +```bash +cql wallet -balance Bitcoin +``` + +Output: + + INFO[0000] Bitcoin balance is: 0 + + +### Transferring Tokens to Another Account + +Once you get tokens from [TestNet](quickstart) or [Docker Environment by One-Click](deployment), you can use the `transfer` sub-command to transfer tokens to another account. The command takes a `json` format meta info as its main parameter, e.g.: + +```json +{ + "addr": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // Receiver wallet address + "amount": "1000000 Particle" // Transfer amount with token type +} +``` + +Note that the receiver wallet address could be a user account address or a database address -- we treat the database as a special kind of account. While transferring to a database, the tokens will be used as the deposit and advance payment of that database for the sender. + +> Check more detailed knowledge about [Deposit and Advance Payment](terms#deposit-and-advance-payment). + +Pass the parameter to `transfer`: + +```bash +cql transfer '{"addr": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount": "1000000 Particle"}' +``` + +Output: + + INFO[0000] succeed in sending transaction to CovenantSQL + + +Note that the above output message indicates that the transfer request is successfully sent to CovenantSQL network, but it will take a while before the block producers actually execute and confirm the transaction to take effect. You can use the `cql wallet -balance ` command again to check if the request takes effect, or add `-wait-tx-confirm` parameter to make `cql` wait for transaction confirmation before exit. + +### Sub-command `wallet` Complete Parameters + + usage: cql wallet [-config file] [-balance token_name] + + Wallet command can get CovenantSQL wallet address and the token balance of the current account + e.g. + cql wallet + + cql wallet -balance Particle + cql wallet -balance all + + Params: + -balance string + Get a specific token's balance of the current account, e.g. Particle, Wave, and etc. + + +### Sub-command `transfer` Complete Parameters + + usage: cql transfer [-config file] [-wait-tx-confirm] meta_json + + Transfer command can transfer your token to the target account. + The command argument is JSON meta info of a token transaction. + e.g. + cql transfer '{"addr":"your_account_addr","amount":"100 Particle"}' + + Since CovenantSQL is based on blockchain, you may want to wait for the transaction confirmation. + e.g. + cql transfer -wait-tx-confirm '{"addr":"your_account_addr","amount":"100 Particle"}' + + Params: + -wait-tx-confirm + Wait for transaction confirmation + + +## Database Management + +### Creating Database + +Like `transfer`, `create` takes a `json` format main parameter. Create a database with one miner node with: + +```bash +cql create '{"node": 1}' +``` + +Output: + + Enter master key(press Enter for default: ""): + + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + + +Here `covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` is the database source name (DSN) of the created database. And the `covenantsql` part is the scheme, which can be `cql` in abbreviation. The hex string after `://` is the database address, which can be used as a receiver address in `transfer` command. + +The sub-command `create` sends transactions to block producers to create databases, so it has a `wait-tx-confirm` parameter too. + +For a complete help message, check [Complete Parameters](#sub-command-create-complete-parameters). + +### ~~Deleting Database~~ + +~~Not yet implemented.~~ + +### Granting Permission + +#### Access Permission + +CovenantSQL database has 3 kinds of access permission: + +- `Admin` +- `Write` +- `Read` +- `Void` (for none) + +Among them, `Admin` is the permission that can assign permissions (`Admin`, `Write`, or `Read`) to the other accounts. `Admin` and `Write` allows the write queries (such as `CREATE`, `INSERT`, and etc.). `Admin` and `Read` allows the read queries (such as `SHOW`, `SELECT`, and etc.). If you want to allow a user to read/write the database but not allow to modify the permissions of itself or other accounts, you can assign the user permission as `Read,Write`. `Void` is a special kind of permission which means 'no permission'. Once the `Admin` sets the permission of an account as `Void`, it will no longer able to read or write the database. The account who creates the database will be granted the initial `Admin` permission by default. + +Assume that you have created a database `covenantsql:\\4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5` with default account, and have generated another account under directory `account2` which has the address `011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6`. Now you can grant permissions to `accounts` to access the database, with the `json` format main parameter as following: + +```json +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", // Target database adderss to give permission + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // Target wallet address to get permission + "perm": "Read,Write" // Permission, separated by commas +} +``` + +Pass the parameter to `grant`: + +```bash +cql grant '{"chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", "perm": "Read,Write"}' +``` + +Output: + + INFO[0000] succeed in sending transaction to CovenantSQL + + +Or revoke the permission: + +```bash +cql grant '{"chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", "perm": "Void"}' +``` + +Output: + + INFO[0000] succeed in sending transaction to CovenantSQL + + +The sub-command `grant` sends transactions to block producers to request permission granting, so it has a `wait-tx-confirm` parameter too. + +Since the database separately keeps billing for each user, you need to transfer tokens to the database (as user deposit and advance payment) from the new account before it can actually get access to the database. The minimum amount of deposit and advance payment can be calculated by: `gas_price*number_of_miner*120000`. + +Transferring from `account2` to the database: + +```bash +cql -config "account2/config.yaml" transfer '{"addr": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","amount": "90000000 Particle"}' +``` + +#### SQL White List + +CovenantSQL supports white list setting for each of its users. By setting up SQL white list, you can further limit the access permission of a user to a given list of SQL Patterns with assignable parameters. With this feature, your database can be further secured because it avoids important data breach and accidentally updating/deleting. + +Adding a white list: + +```bash +cql grant ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": { + "patterns": [ + "SELECT COUNT(1) FROM a", + "SELECT * FROM a WHERE id = ? LIMIT 1" + ], + "role": "Read,Write" + } +} +' +``` + +*SQL White List is an extension of the database permission system. It currently doesn't support incrementally updating, so you need to provide the complete permission information each time you use the `grant` sub-command* + +Cleaning the white list: + +```bash +cql grant ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": { + "patterns": nil, + "role": "Read,Write" + } +} +' +# or +cql grant ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": "Read,Write" +} +' +``` + +Either setting the `pattern` field to `nil` or just resetting the user permission directly, will eliminate the white list and give back the access permission to the user. + +### Sub-command `create` Complete Parameters + + usage: cql create [parameters]... db_meta_json + + Create CovenantSQL database by database meta info JSON string, meta info must include node count. + e.g. + cql create '{"node":2}' + + A complete introduction of db_meta_json fields： + targetminers []string // List of target miner addresses + node int // Target node number + space int // Minimum disk space requirement, 0 for none + memory int // Minimum memory requirement, 0 for none + loadavgpercpu float // Minimum idle CPU requirement, 0 for none + encryptionkey string // Encryption key for persistence data + useeventualconsistency bool // Use eventual consistency to sync among miner nodes + consistencylevel float // Consistency level, node*consistencylevel is the node number to perform strong consistency + isolationlevel int // Isolation level in a single node + + Since CovenantSQL is blockchain database, you may want get confirm of creation. + e.g. + cql create -wait-tx-confirm '{"node": 2}' + + Params: + -wait-tx-confirm + Wait for transaction confirmation + + +### Sub-command `drop` Complete Parameters + + usage: cql drop [parameter]... dsn/dbid + + Drop command can drop a database by DSN or database id + e.g. + cql drop covenantsql://the_dsn_of_your_database + + Since CovenantSQL is blockchain database, you may want get confirm of drop operation. + e.g. + cql drop -wait-tx-confirm covenantsql://the_dsn_of_your_database + + Params: + -wait-tx-confirm + Wait for transaction confirmation + + +### Sub-command `grant` Complete Parameters + + usage: cql grant [parameter]... permission_meta_json + + Grant command can give a user some specific permissions on your database + e.g. + cql grant '{"chain": "your_chain_addr", "user": "user_addr", "perm": "perm_struct"}' + + Since CovenantSQL is blockchain database, you may want get confirm of permission update. + e.g. + cql grant -wait-tx-confirm '{"chain":"your_chain_addr","user":"user_addr","perm":"perm_struct"}' + + Params: + -wait-tx-confirm + Wait for transaction confirmation + + +## Accessing Database + +Once your database is successfully created, you can use the `console` sub-command to access it in an interactive console: + +```bash +cql console -dsn 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + Enter master key(press Enter for default: ""): + + INFO[0010] init config success path=/home/levente/.cql/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-34ae741a-20190416184528) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Or access as `account2` if it has successfully been granted access permission: + +```bash +cql console -config "account2/config.yaml" -dsn 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + Enter master key(press Enter for default: ""): + + INFO[0010] init config success path=/home/levente/.config/cql/account2/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-34ae741a-20190416184528) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Here is an example of using the interactive console: + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> create table t1 (c1 int); + CREATE TABLE + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> insert into t1 values (1), (2), (3); + INSERT + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> select * from t1; + c1 + ---- + 1 + 2 + 3 + (3 rows) + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +### Sub-command `console` Complete Parameters + +The sub-command `console` also supports running `adapter` or `explorer` servers in the background. Check [Local Servers](#local-servers) for details. + + usage: cql console [parameter]... + + Console command can run a interactive SQL console for CovenantSQL + e.g. + cql console -dsn covenantsql://the_dsn_of_your_database + + There is also a -command param for SQL script, and a -file param for reading SQL in a file. + If those params are set, it will run SQL script and exit without staying console mode. + e.g. + cql console -dsn covenantsql://the_dsn_of_your_database -command "create table test1(test2 int);" + + Params: + -adapter string + Address to serve a database chain adapter, e.g.:7784 + -command string + Run only single command (SQL or usql internal command) and exit + -dsn string + Database url + -explorer string + Address to serve a database chain explorer, e.g.:8546 + -file string + Execute commands from file and exit + -no-rc + Do not read startup file + -out string + Record stdout to file + -single-transaction + Execute as a single transaction (if non-interactive) + -variable value + Set variable + + +## Local Servers + +### Sub-command `explorer` Complete Parameter + + usage: cql explorer [parameter]... address + + Explorer command serves a SQLChain web explorer. + e.g. + cql explorer 127.0.0.1:8546 + + Params: + -bg-log-level string + Background service log level + -tmp-path string + Background service temp file path, use os.TempDir for default + + +### Sub-command `mirror` Complete Parameter + + usage: cql mirror [parameter]... dsn/dbid address + + Mirror command subscribes database updates and serves a read-only database mirror. + e.g. + cql mirror database_id 127.0.0.1:9389 + + Params: + -bg-log-level string + Background service log level + -tmp-path string + Background service temp file path, use os.TempDir for default + + +### Sub-command `adapter` Complete Parameter + +See for details of adapter server. + + usage: cql adapter [parameter]... address + + Adapter command serves a SQLChain adapter + e.g. + cql adapter 127.0.0.1:7784 + + Params: + -bg-log-level string + Background service log level + -mirror string + mirror server for the target adapter to query + -tmp-path string + Background service temp file path, use os.TempDir for default + + +## Advance Usage + +Sub-command `rpc` calls the remote process directly in the CovenantSQL network. + +### Sub-command `rpc` Complete Parameter + + usage: cql rpc [parameter]... + + Rpc command make a RPC request to the target server + e.g. + cql rpc -name 'MCC.QuerySQLChainProfile' \ + -endpoint 000000fd2c8f68d54d55d97d0ad06c6c0d91104e4e51a7247f3629cc2a0127cf \ + -req '{"DBID": "c8328272ba9377acdf1ee8e73b17f2b0f7430c798141080d0282195507eb94e7"}' + + Params: + -endpoint string + RPC endpoint to do a test call + -name string + RPC name to do a test call + -req string + RPC request to do a test call, in json format + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/cql_account.md b/website/translated_docs/zh-CN/version-0.5.0/cql_account.md new file mode 100644 index 0000000..911c0df --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/cql_account.md @@ -0,0 +1,120 @@ +--- +id: version-0.5.0-cql_account +title: Account Management +original_id: cql_account +--- + +For the TestNet environment, we provide a public account for quick testing. Check the [CovenantSQL TestNet](quickstart) tutorial to find out the private key and config file of the public account. And you can also follow the next section to create an individual account with `cql` command. + +## Creating New Account + +The sub-command `generate` generates a private key file and a config file connecting to the TestNet in the specified directory, e.g.: + +```bash +cql generate config +``` + +> Currently, the generated config file is pointed to the TestNet, we will provide options to generated config for Docker Environment later. + +For a complete help message, check [Complete Parameters](#sub-command-generate-complete-parameters). + +Output: + + Generating key pair... + Enter master key(press Enter for default: ""): + + Private key file: ~/.cql/private.key + Public key's hex: 027af3584b8b4736d6ba1e78ace5f0fdefe561f08749c5cac39d23668c3030fe39 + Generated key pair. + Generating nonce... + INFO[0075] cpu: 4 + INFO[0075] position: 3, shift: 0x0, i: 3 + INFO[0075] position: 1, shift: 0x0, i: 1 + INFO[0075] position: 0, shift: 0x0, i: 0 + INFO[0075] position: 2, shift: 0x0, i: 2 + nonce: {{1056388 0 0 1424219234} 25 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01} + node id: 000000737633a77a39fc5e0a1855ca2c441486fef049ac4069e93dde6e58bb01 + Generated nonce. + Generating config file... + Generated nonce. + + +## Acquiring the Public Key + +The sub-command `generate` is also used to acquire the public key (in hex string format) of the private key file, e.g.: + +```bash +cql generate public +``` + +Output： + + Enter master key(press Enter for default: ""): + + INFO[0011] init config success path=/home/levente/.cql/private.key + INFO[0011] use public key in config file: /home/levente/.cql/config.yaml + Public key's hex: 02fd4089e7f4ca224f576d4baa573b3e9662153c952fce3f87f9586ffdd11baef6 + + +> This functionality is usually not used in common scene. + +## Sub-command `generate` Complete Parameters + +Also see [Common Parameters for Sub-commands](#common-parameters-for-sub-commands). We will not mention this again in the later sub-command introductions. + + usage: cql generate [common params] config | public + + Generate generates private.key and config.yaml for CovenantSQL. + e.g. + cql generate config + + Params: + + + +## Mine a Node ID + +The sub-command `idminer` is used to mine another Node ID of a private key (specified by a config file), (also check [Node ID](terms#node-id) for details). e.g.: + +```bash +cql idminer +``` + +Output: + + INFO[0000] cql build: cql develop-34ae741a-20190415161544 linux amd64 go1.11.5 + Enter master key(press Enter for default: ""): + + INFO[0008] init config success path=/home/levente/.cql/config.yaml + INFO[0008] use public key in config file: /home/levente/.cql/config.yaml + INFO[0008] cpu: 8 + INFO[0008] position: 3, shift: 0x20, i: 7 + INFO[0008] position: 0, shift: 0x0, i: 0 + INFO[0008] position: 3, shift: 0x0, i: 6 + INFO[0008] position: 1, shift: 0x0, i: 2 + INFO[0008] position: 2, shift: 0x0, i: 4 + INFO[0008] position: 1, shift: 0x20, i: 3 + INFO[0008] position: 2, shift: 0x20, i: 5 + INFO[0008] position: 0, shift: 0x20, i: 1 + nonce: {{1251426 4506240821 0 0} 25 00000041bc2b3de3bcb96328d0004c684628a908f0233eb31fe9998ef0c6288e} + node id: 00000041bc2b3de3bcb96328d0004c684628a908f0233eb31fe9998ef0c6288e + + +> This functionality is usually not used in common scene. + +## Sub-command `idminer` Complete Parameters + + usage: cql idminer [common params] [-difficulty number] [-loop [true]] + + IDMiner calculates legal node id and it's nonce. Default parameters are difficulty of 24 and no endless loop. + e.g. + cql idminer -difficulty 24 + + If you want to mine a good id, use: + cql idminer -config ~/.cql/config.yaml -loop -difficulty 24 + + Params: + -difficulty int + the difficulty for a miner to mine nodes and generating a nonce (default 24) + -loop + mining endless loop \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/cql_advance.md b/website/translated_docs/zh-CN/version-0.5.0/cql_advance.md new file mode 100644 index 0000000..d249d29 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/cql_advance.md @@ -0,0 +1,27 @@ +--- +id: version-0.5.0-cql_advance +title: Advanced Usage +original_id: cql_advance +--- + +Sub-command `rpc` calls the remote process directly in the CovenantSQL network. + +## Sub-command `rpc` Complete Parameter + + usage: cql rpc [common params] [-wait-tx-confirm] -name rpc_name -endpoint rpc_endpoint -req rpc_request + + RPC makes a RPC request to the target endpoint. + e.g. + cql rpc -name 'MCC.QuerySQLChainProfile' \ + -endpoint 000000fd2c8f68d54d55d97d0ad06c6c0d91104e4e51a7247f3629cc2a0127cf \ + -req '{"DBID": "c8328272ba9377acdf1ee8e73b17f2b0f7430c798141080d0282195507eb94e7"}' + + Params: + -endpoint string + RPC endpoint to do a test call + -name string + RPC name to do a test call + -req string + RPC request to do a test call, in json format + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/cql_db_access.md b/website/translated_docs/zh-CN/version-0.5.0/cql_db_access.md new file mode 100644 index 0000000..63b0c14 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/cql_db_access.md @@ -0,0 +1,93 @@ +--- +id: version-0.5.0-cql_db_access +title: Accessing Database +original_id: cql_db_access +--- + +Once your database is successfully created, you can use the `console` sub-command to access it in an interactive console: + +```bash +cql console -dsn 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + Enter master key(press Enter for default: ""): + + INFO[0010] init config success path=/home/levente/.cql/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-34ae741a-20190416184528) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Or access as `account2` if it has been granted access permission successfully: + +```bash +cql console -config "account2/config.yaml" -dsn 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + Enter master key(press Enter for default: ""): + + INFO[0010] init config success path=/home/levente/.config/cql/account2/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-34ae741a-20190416184528) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Here is an example of using the interactive console: + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> create table t1 (c1 int); + CREATE TABLE + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> insert into t1 values (1), (2), (3); + INSERT + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> select * from t1; + c1 + ---- + 1 + 2 + 3 + (3 rows) + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +## Sub-command `console` Complete Parameters + +The sub-command `console` also supports running `adapter` or `explorer` servers in the background. Check [Local Servers](#local-servers) for details. + + usage: cql console [common params] [-dsn dsn_string] [-command sqlcommand] [-file filename] [-out outputfile] [-no-rc true/false] [-single-transaction] [-variable variables] [-explorer explorer_addr] [-adapter adapter_addr] + + Console runs an interactive SQL console for CovenantSQL. + e.g. + cql console -dsn covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + There is also a -command param for SQL script, and a -file param for reading SQL in a file. + If those params are set, it will run SQL script and exit without staying console mode. + e.g. + cql console -dsn covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c -command "create table test1(test2 int);" + + Params: + -adapter string + Address to serve a database chain adapter, e.g.:7784 + -command string + Run only single command (SQL or usql internal command) and exit + -dsn string + Database url + -explorer string + Address to serve a database chain explorer, e.g.:8546 + -file string + Execute commands from file and exit + -no-rc + Do not read startup file + -out string + Record stdout to file + -single-transaction + Execute as a single transaction (if non-interactive) + -variable value + Set variable \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/cql_db_manage.md b/website/translated_docs/zh-CN/version-0.5.0/cql_db_manage.md new file mode 100644 index 0000000..76d7380 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/cql_db_manage.md @@ -0,0 +1,215 @@ +--- +id: version-0.5.0-cql_db_manage +title: Database Management +original_id: cql_db_manage +--- + +## Creating Database + +Like `transfer`, `create` takes a `json` format main parameter. Create a database with one miner node with: + +```bash +cql create '{"node": 1}' +``` + +Output: + + Enter master key(press Enter for default: ""): + + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + + +Here `covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` is the database source name (DSN) of the created database. And the `covenantsql` part is the scheme, which can be `cql` in abbreviation. The hex string after `://` is the database address, which can be used as a receiver address in `transfer` command. + +The sub-command `create` sends transactions to block producers to create databases, so it has a `wait-tx-confirm` parameter too. + +For a complete help message, check [Complete Parameters](#sub-command-create-complete-parameters). + +## Billing + +CovenantSQL uses Gas for billing just like the [Ethereum Gas](https://www.ethos.io/what-is-ethereum-gas/). The gas unit (a.k.a., the `Gas-Price`) in stable token `Particle` is specified while creating the database, and its corresponding field is `gas-price`. If not specified in the json string, it will be set as 1 by default. Another billing-related field is `advance-payment`, which will be used as deposit and query expending. The default advance payment is 20,000,000. Creating a database with specified `Gas-Price` and `Advance-Payment`: + +```bash +cql create '{"node": 2, "gas-price": 5, "advance-payment": 500000000}' +``` + +Thus we created a new database with `Gas-Price` 5 and `Advance-Payment` 500,000,000. Note that when the CovenantSQL network is short of miner resources, setting a higher `Gas-Price` will help your creation request to be accepted earlier, but it will cost you more tokens of course. + +> At present, we only accept the CovenantSQL stable token Particle for database billing. More token types will be supported soon. + +And the billing is processed as following: + +- For a Read request, the result `rows_count` is counted as the `Gas` cost +- For a Write request, the result `affected_rows` is counted as the `Gas` cost +- The SQLChain miner does periodic billing, sums up, and reports the `Gas` cost to the main chain, and the main chain verifies and deducts `Gas` * `Gas Price` tokens from the user accounts + +## ~~Deleting Database~~ + +~~Not yet implemented.~~ + +## Granting Permission + +### Access Permission + +CovenantSQL database has 3 kinds of access permission: + +- `Admin` +- `Write` +- `Read` +- `Void` (for none) + +Among them, `Admin` is the permission that can assign permissions (`Admin`, `Write`, or `Read`) to the other accounts. `Admin` and `Write` allows the write queries (such as `CREATE`, `INSERT`, and etc.). `Admin` and `Read` allows the read queries (such as `SHOW`, `SELECT`, and etc.). If you want to allow a user to read/write the database but not allow to modify the permissions of itself or other accounts, you can assign the user permission as `Read,Write`. `Void` is a special kind of permission which means 'no permission'. Once the `Admin` sets the permission of an account as `Void`, it will no longer able to read or write the database. The account who creates the database will be granted the initial `Admin` permission by default. + +Assume that you have created a database `covenantsql:\\4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5` with default account, and have generated another account under directory `account2` which has the address `011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6`. Now you can grant permissions to `accounts` to access the database, with the `json` format main parameter as following: + +```json +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", // Target database adderss to give permission + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // Target wallet address to get permission + "perm": "Read,Write" // Permission, separated by commas +} +``` + +Pass the parameter to `grant`: + +```bash +cql grant '{"chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", "perm": "Read,Write"}' +``` + +Output: + + INFO[0000] succeed in sending transaction to CovenantSQL + + +Or revoke the permission: + +```bash +cql grant '{"chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", "perm": "Void"}' +``` + +Output: + + INFO[0000] succeed in sending transaction to CovenantSQL + + +The sub-command `grant` sends transactions to block producers to request permission granting, so it has a `wait-tx-confirm` parameter too. + +Since the database separately keeps billing for each user, you need to transfer tokens to the database (as user deposit and advance payment) from the new account before it can actually get access to the database. The minimum amount of deposit and advance payment can be calculated by: `gas_price*number_of_miner*120000`. + +Transferring from `account2` to the database: + +```bash +cql -config "account2/config.yaml" transfer '{"addr": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5","amount": "90000000 Particle"}' +``` + +### SQL White List + +CovenantSQL supports white list setting for each of its users. By setting up SQL white list, you can further limit the access permission of a user to a given list of SQL Patterns with assignable parameters. With this feature, your database can be further secured because it avoids important data breach and accidentally updating/deleting. + +Adding a white list: + +```bash +cql grant ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": { + "patterns": [ + "SELECT COUNT(1) FROM a", + "SELECT * FROM a WHERE id = ? LIMIT 1" + ], + "role": "Read,Write" + } +} +' +``` + +*SQL White List is an extension of the database permission system. It currently doesn't support incrementally updating, so you need to provide the complete permission information each time you use the `grant` sub-command* + +Cleaning the white list: + +```bash +cql grant ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": { + "patterns": nil, + "role": "Read,Write" + } +} +' + or +cql grant ' +{ + "chain": "4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5", + "user": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", + "perm": "Read,Write" +} +' +``` + +Either setting the `pattern` field to `nil` or just resetting the user permission directly, will eliminate the white list and give back the access permission to the user. + +## Sub-command `create` Complete Parameters + + usage: cql create [common params] [-wait-tx-confirm] db_meta_json + + Create creates a CovenantSQL database by database meta info JSON string. The meta info must include node count. + e.g. + cql create '{"node": 2}' + + A complete introduction of db_meta_json fields: + target-miners []string // List of target miner addresses + node int // Target node number + space int // Minimum disk space requirement, 0 for none + memory int // Minimum memory requirement, 0 for none + load-avg-per-cpu float // Minimum idle CPU requirement, 0 for none + encrypt-key string // Encryption key for persistence data + eventual-consistency bool // Use eventual consistency to sync among miner nodes + consistency-level float // Consistency level, node*consistency_level is the node number to perform strong consistency + isolation-level int // Isolation level in a single node + gas-price int // Specified Gas Price of the database, default is 1 Particle + advance-payment int // Specified advance payment of the database, default is 20,000,000 Particles + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction confirmation before the creation takes effect. + e.g. + cql create -wait-tx-confirm '{"node": 2}' + + Params: + -wait-tx-confirm + Wait for transaction confirmation + + +## Sub-command `drop` Complete Parameters + + usage: cql drop [common params] [-wait-tx-confirm] dsn/dbid + + Drop drops a CovenantSQL database by DSN or database ID. + e.g. + cql drop covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction confirmation before the drop operation takes effect. + e.g. + cql drop -wait-tx-confirm covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + Params: + -wait-tx-confirm + Wait for transaction confirmation + + +## Sub-command `grant` Complete Parameters + + usage: cql grant [common params] [-wait-tx-confirm] permission_meta_json + + Grant grants specific permissions for the target user. + e.g. + cql grant '{"chain": "your_chain_addr", "user": "user_addr", "perm": "perm_struct"}' + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction confirmation before the permission takes effect. + e.g. + cql grant -wait-tx-confirm '{"chain":"your_chain_addr","user":"user_addr","perm":"perm_struct"}' + + Params: + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/cql_intro.md b/website/translated_docs/zh-CN/version-0.5.0/cql_intro.md new file mode 100644 index 0000000..903832d --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/cql_intro.md @@ -0,0 +1,32 @@ +--- +id: version-0.5.0-cql_intro +title: Overview +original_id: cql_intro +--- + +CovenantSQL provides a `cql` command line toolset for terminal users to access and manage user accounts, wallet balances, and databases. Check the complete toolset installation tutorial at \[CovenantSQL Toolset installation\](quickstart#工具包安装). + +## Private Key and Config File + +The `cql` command needs to rely on a private key file `private.key` and a config file `config.yaml`: + +- `private.key`：a private key file which is generated while creating an account, be sure to keep it safe +- `config.yaml`：mainly used to config the CovenantSQL network for `cql` command to connect (e.g., the [TestNet](quickstart) or the [Docker Environment](deployment)) + +For security, the private key file is usually encrypted with a master key. A master key is individually chosen by the user while creating an account and is memorized or kept somewhere by the user -- note that the config file will not keep the master key. When the private key is required by the `cql` command, it will ask the user to input the master key to decrypt the private key file. + +## Common Parameters for Sub-commands + +The following parameters are commonly used by `cql` sub-commands: + + -bypass-signature + Disable signature signing and verifying, for testing only + -config string + Config file for covenantsql (Usually no need to set, default is enough.) (default "~/.cql/config.yaml") + -no-password + Use an empty master key + -password string + Master key for covenantsql (NOT SAFE, for debugging or script mode only) + + +Note that the private key file path is specified in the config file, and its default value is `./private.key`, indicating that it's located in the same directory of the config. So usually we put the private key file together with config, instead of using an individual parameter to specify the private key file. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/cql_server.md b/website/translated_docs/zh-CN/version-0.5.0/cql_server.md new file mode 100644 index 0000000..d4bcf22 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/cql_server.md @@ -0,0 +1,53 @@ +--- +id: version-0.5.0-cql_server +title: Local Servers +original_id: cql_server +--- + +## Sub-command `explorer` Complete Parameter + + usage: cql explorer [common params] [-tmp-path path] [-bg-log-level level] listen_address + + Explorer serves a SQLChain web explorer. + e.g. + cql explorer 127.0.0.1:8546 + + Params: + -bg-log-level string + Background service log level + -tmp-path string + Background service temp file path, use os.TempDir for default + + +## Sub-command `mirror` Complete Parameter + + usage: cql mirror [common params] [-tmp-path path] [-bg-log-level level] dsn listen_address + + Mirror subscribes database updates and serves a read-only database mirror. + e.g. + cql mirror database_id 127.0.0.1:9389 + + Params: + -bg-log-level string + Background service log level + -tmp-path string + Background service temp file path, use os.TempDir for default + + +## Sub-command `adapter` Complete Parameter + +See for details of adapter server. + + usage: cql adapter [common params] [-tmp-path path] [-bg-log-level level] [-mirror addr] listen_address + + Adapter serves a SQLChain adapter. + e.g. + cql adapter 127.0.0.1:7784 + + Params: + -bg-log-level string + Background service log level + -mirror string + mirror server for the target adapter to query + -tmp-path string + Background service temp file path, use os.TempDir for default \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/cql_wallet.md b/website/translated_docs/zh-CN/version-0.5.0/cql_wallet.md new file mode 100644 index 0000000..a09de46 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/cql_wallet.md @@ -0,0 +1,115 @@ +--- +id: version-0.5.0-cql_wallet +title: Wallet Management +original_id: cql_wallet +--- + +## Wallet Address + +Once the private key and config file is set, you can use sub-command `wallet` to check the wallet address of the account: + +```bash +cql wallet +``` + +Output: + + Enter master key(press Enter for default: ""): + + wallet address: 43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 + + +The wallet address of the test account here is `43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40`. + +## Wallet Balances + +We can also use sub-command `wallet` to check the balances in the wallet. CovenantSQL currently supports 5 types of tokens: + +- `Particle` +- `Wave` +- `Bitcoin` +- `Ether` +- `EOS` + +Among them, `Particle` and `Wave` are the token types used by CovenantSQL. To check the token balances, use: + +```bash +cql wallet -balance all +``` + +Output: + + INFO[0000] Particle balance is: 10000000000000000000 + INFO[0000] Wave balance is: 10000000000000000000 + + +You can also check the balance of a specified type of token, e.g., checking the balance of `Bitcoin`: + +```bash +cql wallet -balance Bitcoin +``` + +Output: + + INFO[0000] Bitcoin balance is: 0 + + +## Transferring Tokens to Another Account + +Once you get tokens from [TestNet](quickstart) or [Docker Environment](deployment), you can use the `transfer` sub-command to transfer tokens to another account. The command takes a `json` format meta info as its main parameter, e.g.: + +```json +{ + "addr": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6", // Receiver wallet address + "amount": "1000000 Particle" // Transfer amount with token type +} +``` + +Note that the receiver wallet address could be a user account address or a database address -- we treat the database as a special kind of account. While transferring to a database, the tokens will be used as the deposit and advance payment of that database for the sender. + +> Check more detailed knowledge about [Deposit and Advance Payment](terms#deposit-and-advance-payment). + +Pass the parameter to `transfer`: + +```bash +cql transfer '{"addr": "011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6","amount": "1000000 Particle"}' +``` + +Output: + + INFO[0000] succeed in sending transaction to CovenantSQL + + +Note that the above output message indicates that the transfer request is successfully sent to CovenantSQL network, but it will take a while before the block producers actually execute and confirm the transaction to take effect. You can use the `cql wallet -balance ` command again to check if the request takes effect, or add `-wait-tx-confirm` parameter to make `cql` wait for transaction confirmation before exit. + +## Sub-command `wallet` Complete Parameters + + usage: cql wallet [common params] [-balance type] + + Wallet gets the CovenantSQL wallet address and the token balances of the current account. + e.g. + cql wallet + + cql wallet -balance Particle + cql wallet -balance all + + Params: + -balance string + Get a specific token's balance of the current account, e.g. Particle, Wave, and etc. + + +## Sub-command `transfer` Complete Parameters + + usage: cql transfer [common params] [-wait-tx-confirm] meta_json + + Transfer transfers your token to the target account. The command argument is a token transaction in JSON format. + e.g. + cql transfer '{"addr": "43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40", "amount": "100 Particle"}' + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction confirmation before the transfer takes effect. + e.g. + cql transfer -wait-tx-confirm '{"addr": "43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40", "amount": "100 Particle"}' + + Params: + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/deployment-en.md b/website/translated_docs/zh-CN/version-0.5.0/deployment-en.md new file mode 100644 index 0000000..ff73566 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/deployment-en.md @@ -0,0 +1,164 @@ +--- +id: version-0.5.0-deployment +title: Docker one-line deployment +original_id: deployment +--- + +## Deploy with CovenantSQL Docker + +### Install Docker + +You need to install docker and docker-compose on your machine to deploy CovenantSQL. + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### Download project + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +For all subsequent commands, the working directory is by default in the cloned CovenantSQL root directory, which can be saved as an environment variable: + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +### Start Docker container + +There are now two ways to start the CovenantSQL container: + +1. Use a public image on Docker Hub +2. Build a CovenantSQL Docker image + +> We recommend that regular users test CovenantSQL in the first way, and the second is only used to experience the latest development features. + +#### 1. Use a public image on Docker Hub + +Then start directly: + +```bash +make start +``` + +#### 2. Build a CovenantSQL Docker image + +Run CovenantSQL locally by executing the following command + +```bash +make docker # compile a new image from source files +make start +``` + +### Check running status + +Check the container status: + +```bash +docker-compose ps +``` + +Confirm that all components are in the `Up` state + +```bash + Name Command State Ports +------------------------------------------------------------------------------------------------------ +covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp +covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp +covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp +covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp +covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp +covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp +covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp +covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp +covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp +covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp +``` + +## Operate CovenantSQL + +### Create a database + +Create a DB instance by using the `cql` command and using the `create` parameter to provide the required number of database nodes. + +e.g.: creating a single-node database instance + +```bash +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +> Modify the value of the `create` parameter to create an instance running on multiple nodes +> e.g.: create an instance of two nodes + +```bash +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +The command will return the connection string of the created database instance + +```bash +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +### Accessing the database + +Use the `cql` command and use the `dsn` parameter to provide a connection string for the database instance access: + +```bash +docker exec -it covenantsql_adapter /app/cql console -config /app/config.yaml -no-password -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +After that, it will get the following output, and enter the `cql` interactive command line mode + +```bash +Connected with driver covenantsql (develop) +Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +The `cql` interactive command line mode is similar to the `mysql` command. For example, create a table named test, view the tables in the database, insert records, and query results etc. + +```sql +CREATE TABLE test (test TEXT); +SHOW TABLES; +INSERT INTO test VALUES("happy"); +SELECT * FROM test; +``` + +After that, it will get the following output: + +```bash +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); +CREATE TABLE +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name +------ + test +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); +INSERT +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test +------- + happy +(1 row) + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> +``` + +Use the `Ctrl + D` shortcut or type `\q` to exit the `cql` interactive command line + +### SQLChain Observer + +The Observer role in the image uses the same private.key as in the mysql-adapter image, so the new account authorization and transfer process can be eliminated. + +（For details on rights management, please refer to [Database Permission Managemen](cql.md#数据库权限管理)） + +#### Use SQLChain Observer in your browser + +We provide a SQLChain Observer at port `127.0.0.1:11108` to see the SQL statement on the chain. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/deployment.md b/website/translated_docs/zh-CN/version-0.5.0/deployment.md new file mode 100644 index 0000000..64da004 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/deployment.md @@ -0,0 +1,160 @@ +--- +id: version-0.5.0-deployment +title: Docker Deploy +original_id: deployment +--- + +## Deploy with CovenantSQL Docker + +### Install Docker + +You need to install docker and docker-compose on your machine to deploy CovenantSQL. + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### Download project + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +For all subsequent commands, the working directory is by default in the cloned CovenantSQL root directory, which can be saved as an environment variable: + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +### Start Docker container + +There are now two ways to start the CovenantSQL container: + +1. Use a public image on Docker Hub +2. Build a CovenantSQL Docker image + +> We recommend that regular users test CovenantSQL in the first way, and the second is only used to experience the latest development features. + +#### 1. Use a public image on Docker Hub + +Then start directly: + +```bash +make start +``` + +#### 2. Build a CovenantSQL Docker image + +Run CovenantSQL locally by executing the following command + +```bash +make docker # compile a new image from source files +make start +``` + +### Check running status + +Check the container status: + +```bash +docker-compose ps +``` + +Confirm that all components are in the `Up` state + + Name Command State Ports + ------------------------------------------------------------------------------------------------------ + covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp + covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp + covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp + covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp + covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp + covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp + covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp + covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp + covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp + covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp + + +## Operate CovenantSQL + +### Create a database + +Create a DB instance by using the `cql` command and using the `create` parameter to provide the required number of database nodes. + +e.g.: creating a single-node database instance + +```bash +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +> Modify the value of the `create` parameter to create an instance running on multiple nodes +> e.g.: create an instance of two nodes + +```bash +docker exec -it covenantsql_adapter /app/cql create -config /app/config.yaml -no-password '{"node":1}' +``` + +The command will return the connection string of the created database instance + + covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + + +### Accessing the database + +Use the `cql` command and use the `dsn` parameter to provide a connection string for the database instance access: + +```bash +docker exec -it covenantsql_adapter /app/cql console -config /app/config.yaml -no-password -dsn covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +After that, it will get the following output, and enter the `cql` interactive command line mode + +``` + +Connected with driver covenantsql (develop) Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> + +
The `cql` interactive command line mode is similar to the `mysql` command. For example, create a table named test, view the tables in the database, insert records, and query results etc. + + ```sql + CREATE TABLE test (test TEXT); + SHOW TABLES; + INSERT INTO test VALUES("happy"); + SELECT * FROM test; + + +After that, it will get the following output: + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); + CREATE TABLE + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name + ------ + test + (1 row) + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); + INSERT + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test + ------- + happy + (1 row) + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> + + +Use the `Ctrl + D` shortcut or type `\q` to exit the `cql` interactive command line + +### SQLChain Observer + +The Observer role in the image uses the same private.key as in the mysql-adapter image, so the new account authorization and transfer process can be eliminated. + +（For details on rights management, please refer to [Database Permission Managemen](cql.md#数据库权限管理)） + +#### Use SQLChain Observer in your browser + +We provide a SQLChain Observer at port `127.0.0.1:11108` to see the SQL statement on the chain. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/driver_golang.md b/website/translated_docs/zh-CN/version-0.5.0/driver_golang.md new file mode 100644 index 0000000..975c8a9 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/driver_golang.md @@ -0,0 +1,170 @@ +--- +id: version-0.5.0-driver_golang +title: Golang +original_id: driver_golang +--- + +## Use Golang to access CovenantSQL + +`CovenantSQL` provides `Golang SDK` to access database using native rpc protocol. The `cql` tool is developed based on `Golang SDK`. + +`Golang SDK` is compatible with Golang `database/sql` driver standard, and popular `Golang ORM` is supported for advanced uses. + +### Compatibility + +`Golang SDK` is compatible with Golang `1.10+`. + +### Installation and quick start + +Install it with: + +```bash +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API doc + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### Example + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // Use config file to initialize Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // Connect to database instance + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // Insert records + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // Query records + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/driver_java.md b/website/translated_docs/zh-CN/version-0.5.0/driver_java.md new file mode 100644 index 0000000..572047d --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/driver_java.md @@ -0,0 +1,68 @@ +--- +id: version-0.5.0-driver_java +title: Java +original_id: driver_java +--- + +## Use Java to access CovenantSQL + +`CovenantSQL` provides `Java SDK` to access database instance through [`Adapter`](./adapter) service. + +`Java SDK` is compatible with `JDBC4` specifications，and popular `ORM` like `MyBatis` is supported through JDBC interface. + +### Compatibility + +`Java SDK` requires `Java 1.7+`. + +### Installation and quick start + +Before using `Java SDK`, an adapter tool deployment is required, please see [Deploy Adapter Service](./adapter). + +Now you can use `jdbc:covenantsql:///` uri，replacing `adapter_endpoint` with adapter listen address，`database_id` with database id。 + +#### Maven + +```xml + + + mvn-repo + https://raw.github.com/CovenantSQL/cql-java-driver/mvn-repo + + true + + + true + + + +``` + +```xml + + + io.covenantsql + covenantsql-java-connector + 1.0-SNAPSHOT + + +``` + +#### Gradle + +```gradle +repositories { + maven { + url 'https://raw.github.com/CovenantSQL/cql-java-driver/mvn-repo' + } +} + +dependencies { + compile 'io.covenantsql:covenantsql-java-connector:1.0-SNAPSHOT' +} +``` + +### Examples + +1. [JDBC Example](https://github.com/CovenantSQL/cql-java-driver/blob/master/example/src/main/java/io/covenantsql/connector/example/jdbc/Example.java) +2. [MyBatis Example](https://github.com/CovenantSQL/cql-java-driver/blob/master/example/src/main/java/io/covenantsql/connector/example/mybatis/Example.java) +3. [SpringBoot + MyBatis Project Example](https://github.com/CovenantSQL/covenantsql-mybatis-spring-boot-jpetstore) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/driver_js.md b/website/translated_docs/zh-CN/version-0.5.0/driver_js.md new file mode 100644 index 0000000..34edca7 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/driver_js.md @@ -0,0 +1,66 @@ +--- +id: version-0.5.0-driver_js +title: JavaScript +original_id: driver_js +--- + +## Use JavaScript to access CovenantSQL + +Front-end developers could use [covenantsql-proxy-js](https://github.com/CovenantSQL/covenantsql-proxy-js) to access CovenantSQL through CovenantSQL [Adapter](./adapter). + +#### Installation + +Install `node-covenantsql` using package manager `npm` or `yarn`: + +```bash +npm install --save node-covenantsql +``` + +or + +```bash +yarn add node-covenantsql +``` + +#### Quick start + +First, [Deploy Adapter Service](./adapter). + +Configure `node-covenantsql`, replace `adapter_listen_address` with adapter listen address, replace `database_id` with created database id: + +```javascript +const config = { + endpoint: '', // local testnet endpoint without https + database: 'database_id', // your DB id created by `cql` tools +} +``` + +After successfully connected to adapter, any CRUD operation is available using typical database operations: + +```typescript +const cql from 'node-covenantsql' + +const config = {...} // see above + +cql.createConnection(config).then(async (connection: any) => { + // read + const data1 = await connection.query("select ? + ?", [2.1, 3.2]); + console.log(data1); + + // write + const createTableSQL = ` + CREATE TABLE IF NOT EXISTS contacts (\ + contact_id INTEGER PRIMARY KEY, + first_name TEXT NOT NULL, + last_name TEXT NOT NULL, + email text NOT NULL UNIQUE, + phone text NOT NULL UNIQUE + ); + ` + const status1 = await connection.exec(createTableSQL) + console.log(`exec1 status:`, status1); + + const data2 = await connection.query("show tables;"); + console.log(data2); +}).catch((e: any) => console.log(e)) +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/driver_python.md b/website/translated_docs/zh-CN/version-0.5.0/driver_python.md new file mode 100644 index 0000000..28b6efc --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/driver_python.md @@ -0,0 +1,55 @@ +--- +id: version-0.5.0-driver_python +title: Python +original_id: driver_python +--- + +## Use Python to access CovenantSQL + +Developers could use [PyCovenantSQL](https://github.com/CovenantSQL/cql-python-driver) to access CovenantSQL through [Adapter](./adapter). + +### Compatibility + +`Python SDK` requires `Python 3.4+`. + +### Installation and quick start + +Before using `Python SDK`, an adapter deployment is required, please see [Deploy Adapter Service](./adapter). + +Install `PyCovenantSQL` using pip: + +```bash +$ python3 -m pip install PyCovenantSQL +``` + +### Example + +Replace `adapter_host` with adapter listen host, `adapter_port` with adapter listen port, `dsn` with database dsn. + +```python +import pycovenantsql + +# Connect to the database +connection = pycovenantsql.connect(host='', + port=, + database='' + ) + +try: + with connection.cursor() as cursor: + # Create a new record + sql = "INSERT INTO `users` (`email`, `password`) VALUES (%s, %s)" + cursor.execute(sql, ('webmaster@python.org', 'very-secret')) + + # connection is autocommit. No need to commit in any case. + # connection.commit() + + with connection.cursor() as cursor: + # Read a single record + sql = "SELECT `id`, `password` FROM `users` WHERE `email`=%s" + cursor.execute(sql, ('webmaster@python.org',)) + result = cursor.fetchone() + print(result) +finally: + connection.close() +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/intro.md b/website/translated_docs/zh-CN/version-0.5.0/intro.md new file mode 100644 index 0000000..af0db85 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/intro.md @@ -0,0 +1,53 @@ +--- +id: version-0.5.0-intro +title: CovenantSQL Intro +original_id: intro +--- + +

+ +

+ +

+ + Go Report Card + + Coverage + + Build Status + + License + + GoDoc + + homebrew +

+ +CovenantSQL(CQL) is a decentralized, GDPR-compliant, trusted, SQL database with blockchain features: + +- **ServerLess**: Free, High Availabile, Auto Sync Database Service for Serverless App +- **GDPR-compliant**: Zero pain to be GDPR-compliant. +- **SQL**: Most SQL-92 support. +- **Decentralize**: Running on Open Internet without Central Coordination. +- **Privacy**: Access with Granted Permission and Encryption Pass. +- **Immutable**: Query History in CQL is Immutable and Trackable. +- **Permission**: Column Level ACL and SQL Pattern Whitelist. + +We believe [On the next Internet, everyone should have a complete **Data Rights**](https://medium.com/@covenant_labs/covenantsql-the-sql-database-on-blockchain-db027aaf1e0e) + +**One Line Makes Data on Blockchain** + +```go +sql.Open("cql", dbURI) +``` + +## What is CQL? + +- Open source alternative of [Amazon QLDB](https://aws.amazon.com/qldb/) +- Just like [filecoin](https://filecoin.io/) + [IPFS](https://ipfs.io/) is the decentralized file system, CQL is the decentralized database \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/native.md b/website/translated_docs/zh-CN/version-0.5.0/native.md new file mode 100644 index 0000000..031e172 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/native.md @@ -0,0 +1,173 @@ +--- +id: version-0.5.0-native +title: '📦 CovenantSQL Native SDK' +original_id: native +--- +## 用 Golang 使用 CovenantSQL + +### 简介 + +`CovenantSQL` 提供了 `Golang SDK` ，支持以 `Golang` App 以原生通讯协议的形式访问数据库实例，是当前性能最高的使用方法， `cql` 等工具也是基于 `Golang SDK` 进行开发的。 + +`Golang SDK` 遵守 `Golang` 标准的 `database/sql` 接口定义，能够使用常见的 `Golang ORM` 进行使用。 + +### 兼容性 + +`Golang SDK` 目前只兼容 `1.10+` 的 Golang 版本。 + +### 安装和使用 + +`Golang SDK` 的 import 地址是 `github.com/CovenantSQL/CovenantSQL/client` + +可以执行 `go get` 命令进行安装 + +```shell +go get github.com/CovenantSQL/CovenantSQL/client +``` + +### API 文档 + +https://godoc.org/github.com/CovenantSQL/CovenantSQL/client + +### 示例 + +```go +package main + +import ( + "database/sql" + "flag" + + "github.com/CovenantSQL/CovenantSQL/client" + "github.com/CovenantSQL/CovenantSQL/utils/log" +) + +func main() { + log.SetLevel(log.DebugLevel) + var config, password, dsn string + + flag.StringVar(&config, "config", "./conf/config.yaml", "config file path") + flag.StringVar(&dsn, "dsn", "", "database url") + flag.StringVar(&password, "password", "", "master key password for covenantsql") + flag.Parse() + + // 使用节点配置文件初始化 Golang SDK + err := client.Init(config, []byte(password)) + if err != nil { + log.Fatal(err) + } + + // 连接数据库实例 + db, err := sql.Open("covenantsql", dsn) + if err != nil { + log.Fatal(err) + } + + Q := `DROP TABLE IF EXISTS cityPop; + CREATE TABLE cityPop ( + ID INT, + Name VARCHAR, + CountryCode VARCHAR, + District VARCHAR, + Population INT + ); + CREATE INDEX cityCountryCodeIndex ON cityPop ( CountryCode ); + + DROP TABLE IF EXISTS countryGDP; + CREATE TABLE countryGDP ( + ID integer PRIMARY KEY, + CountryCode string NOT NULL, + GDP integer + ); + CREATE INDEX countryCountryCodeIndex ON countryGDP ( CountryCode );` + + // 写入数据 + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `INSERT INTO countryGDP VALUES + (0, "ZWE", 99999),(1, "CHN", 3000000000000), + (2, "PSE", 321312313),(3, "JPN", 300000000); + INSERT INTO cityPop VALUES (707,'Shenzhen','CHN','Guangzhou',99442); + INSERT INTO cityPop VALUES (1074,'Shenzhen','CHN','Guangzhou',353632); + INSERT INTO cityPop VALUES (1591,'Toyama','JPN','Toyama',325790); + INSERT INTO cityPop VALUES (1649,'Takaoka','JPN','Toyama',174380); + INSERT INTO cityPop VALUES (1762,'Takasago','JPN','Hyogo',97632); + INSERT INTO cityPop VALUES (1763,'Fujimi','JPN','Saitama',96972); + INSERT INTO cityPop VALUES (1764,'Urasoe','JPN','Okinawa',96002); + INSERT INTO cityPop VALUES (1765,'Yonezawa','JPN','Yamagata',95592); + INSERT INTO cityPop VALUES (1766,'Konan','JPN','Aichi',95521); + INSERT INTO cityPop VALUES (1767,'Yamatokoriyama','JPN','Nara',95165); + INSERT INTO cityPop VALUES (1768,'Maizuru','JPN','Kyoto',94784); + INSERT INTO cityPop VALUES (1769,'Onomichi','JPN','Hiroshima',93756); + INSERT INTO cityPop VALUES (1770,'Higashimatsuyama','JPN','Saitama',93342); + INSERT INTO cityPop VALUES (2707,'Xai-Xai','MOZ','Gaza',99442); + INSERT INTO cityPop VALUES (4074,'Gaza','PSE','Gaza',353632); + INSERT INTO cityPop VALUES (4077,'Jabaliya','PSE','North Gaza',113901);` + _, err = db.Exec(Q) + if err != nil { + log.Warn(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT * FROM cityPop + WHERE District IN ("Shenzhen", "Balkh", "Gaza", "North Gaza") + GROUP BY cityPop.CountryCode + ORDER BY Population DESC + LIMIT 10;` + + // 查询数据 + rows, err := db.Query(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + log.Println("ID Name CountryCode District Population") + var ID, GDP, Population int + var Name, CountryCode, District string + var GDPPerson float64 + + for rows.Next() { + err = rows.Scan(&ID, &Name, &CountryCode, &District, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %s %d", ID, Name, CountryCode, District, Population) + } + Q = `UPDATE countryGDP SET GDP = 1234567 WHERE CountryCode LIKE "CHN"; + UPDATE cityPop SET Population = 123456 WHERE CountryCode LIKE "CHN"; + REPLACE INTO countryGDP (ID, CountryCode, GDP) VALUES (77, "AFG", 11111111);` + _, err = db.Exec(Q) + if err != nil { + log.Fatal(err) + } + log.Printf("\nExec:\n %s\n", Q) + + Q = `SELECT cityPop.ID, cityPop.CountryCode, cityPop.District, + countryGDP.GDP / cityPop.Population, countryGDP.GDP, cityPop.Population + FROM cityPop + LEFT JOIN countryGDP + ON countryGDP.CountryCode = cityPop.CountryCode + WHERE District IN ( "Shenzhen", "Balkh", "North Gaza", "Toyama", "Yonezawa") AND countryGDP.GDP > 0 + GROUP BY cityPop.CountryCode + ORDER BY countryGDP.GDP / cityPop.Population DESC + LIMIT 10;` + rows, err = db.Query(Q) + log.Printf("\nExec:\n %s\n", Q) + + log.Println("ID CountryCode District GDPPerson GDP Population") + for rows.Next() { + err = rows.Scan(&ID, &CountryCode, &District, &GDPPerson, &GDP, &Population) + if err != nil { + log.Fatal(err) + } + + log.Printf("%d %s %s %f %d %d", + ID, CountryCode, District, GDPPerson, GDP, Population) + } +} +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/nav.md b/website/translated_docs/zh-CN/version-0.5.0/nav.md new file mode 100644 index 0000000..b2cbc94 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/nav.md @@ -0,0 +1,33 @@ +--- +id: version-0.5.0-nav +title: 使用导航 +original_id: nav +--- + +## 快速开始 + +[TestNet 快速开始](./quickstart) + +[CQL 操作手册](./cql) + +## 开发应用 + +[Golang](./driver_golang) + +[Java](./driver_java) + +[Python](./driver_python) + +[NodeJS](./driver_js) + +## 高级使用 + +#### 私有部署 + +如果您是企业用户，希望在自己的网络搭建 CovenantSQL 数据库服务，请参考： + +[🐳 Docker 一键部署](./deployment) + +#### 联盟链解决方案 + +如需咨询请邮件至 webmaster@covenantsql.io。 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/proxy.md b/website/translated_docs/zh-CN/version-0.5.0/proxy.md new file mode 100644 index 0000000..254b24b --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/proxy.md @@ -0,0 +1,111 @@ +--- +id: version-0.5.0-adapter +title: '📦 CovenantSQL Adapter SDK' +original_id: adapter +--- +# 通过 Adapter 使用 CovenantSQL + +## 简介 + +`CovenantSQL` 提供了 HTTP/HTTPS Adapter，类似于云数据库， 开发者可以直接用 HTTP 的形式使用 CovenantSQL。 + +## 安装和使用 + +首先，需要确认我们有一个可用的配置和公私钥对，通常我们默认的配置和公私钥对的存储位置为 `~/.cql/` 目录。生成或获取请参考 [QuickStart#创建账号](./quickstart#创建账号) + +### Docker 运行 Adapter + +下面的命令将使用`~/.cql/config.yaml` 和 `~/.cql/private.key` 启动 Adapter，并把端口映射在 `0.0.0.0:11105` + +```bash +export adapter_addr=0.0.0.0:11105 +docker rm -f cql-adapter +docker run -itd \ + --env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --name cql-adapter -p $adapter_addr:4661 \ + covenantsql/covenantsql:testnet -listen 0.0.0.0:4661 +``` + +### 创建数据库 + +使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例 + +```shell +docker run -it --rm \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --entrypoint /app/cql covenantsql/covenantsql:testnet \ + -config /app/config.yaml -create 1 +``` + +命令会返回创建的数据库实例的连接串（DSN） + +```shell +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +## 主流语言 Driver 的使用 + +### NodeJS + +NodeJS 开发者可以通过 [node-covenantsql](https://github.com/CovenantSQL/node-covenantsql) 来与 CovenantSQL Adapter 进行交互。 + +#### 下载安装 + +可以直接通过 `npm` 或者 `yarn` 来安装 `node-covenantsql` + +```bash +npm install --save node-covenantsql +``` + +or + +```bash +yarn add node-covenantsql +``` + +#### 使用 + +在运行本地 Adapter 之后，将 Adapter 的 endpoint 填入 `node-covenantsql` 的 config 之中： + +```javascript +const config = { + endpoint: 'localhost:11105', // local testnet endpoint without https + database: `${DSN}`, // your DB id created by `cql` tools + bypassPem: true // bypass https config +} +``` + +这里 `bypassPem` 为 `true` 表示应用中所有对链上数据库的操作都会经过本地的 Adapter 进行代理，我们默认本地环境是可控，安全的，无需用 HTTPS 来保证这段连接的信道安全，少了证书的繁琐认证，所以成为 `bypassPem`。 + +接着连通之后则可进行链上数据库的增删改查： + +```typescript +const cql from 'node-covenantsql' + +const config = {...} // see above + +cql.createConnection(config).then(async (connection: any) => { + // read + const data1 = await connection.query("select ? + ?", [2.1, 3.2]); + console.log(data1); + + // write + const createTableSQL = ` + CREATE TABLE IF NOT EXISTS contacts (\ + contact_id INTEGER PRIMARY KEY, + first_name TEXT NOT NULL, + last_name TEXT NOT NULL, + email text NOT NULL UNIQUE, + phone text NOT NULL UNIQUE + ); + ` + const status1 = await connection.exec(createTableSQL) + console.log(`exec1 status:`, status1); + + const data2 = await connection.query("show tables;"); + console.log(data2); +}).catch((e: any) => console.log(e)) +``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/qna.md b/website/translated_docs/zh-CN/version-0.5.0/qna.md new file mode 100644 index 0000000..c76054c --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/qna.md @@ -0,0 +1,59 @@ +--- +id: version-0.5.0-qna +title: Q&A +original_id: qna +--- + +## Frequently Asked + +- **Q:** What level of consistency does the CQL database support and how is the CQL database created? + + **A:** See [Consensus Algorithm](./arch#consensus-algorithm) + +- **Q:** How is CQL database security done? + + **A:** Unlike traditional databases, CQL is a distributed database system that runs on the open Internet. In terms of security, CQL mainly does the following work: + + 1. Key Management: CQL uses public and private key pairs generated by Bitcoin's `scep256k1` asymmetric encryption curve. + + 2. Network communication: see [RPC Framework](./arch_network)。 + + 3. Database Permissions & Encryption: + + 1. [Secure Gateway](./advanced_secure_gateway) + + 2. Support of SQL encryption functions `encrypt`, `decrypt`, for example: + + ```sql + INSERT INTO "t1" ("k", "v") VALUES (1, encrypt("data", "pass", "salt")); + SELECT decrypt("v", "pass", "salt") FROM "t1" WHERE "k"=1; + ``` + +- **Q:** If CQL data is Immutable, how do CQL deal with the need for data deletion in GDPR? + + **A:** CQL supports two development modes, one is the traditional `DB per App`, and the other is the `DB per User` which is biased towards privacy. + + The development mode of `DB per User` is very suitable for the development of applications such as "Password Manager" and "Personal Information Management". Since users manage their personal data through a CQL private key which is quite like using Bitcoin a private key to manage their own property. App developed in this model naturally does not store any user data, and technically conforms to the following Stringent requirements of laws and regulations: + + - [EU GDPR（General Data Protection Regulation）](https://gdpr-info.eu/) + - [CCPA（California_Consumer_Privacy_Act）](https://en.wikipedia.org/wiki/California_Consumer_Privacy_Act) + - [HIPAA（Health Insurance Portability and Accountability Act of 1996）](https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act) + - [HongKong Personal Data (Privacy) Ordinance](https://www.elegislation.gov.hk/hk/cap486) + + The complete data of CQL is stored on Miner of SQLChain. The data related SQL history is completely saved on Miner. Compared to the traditional database `CRUD` (Create, Read, Update, Delete), CQL supports `CRAP` (Create, Read, Append, Privatize). + + > **Append** vs **Update** + > + > After the traditional database changes the data (Update), there is no history, in other words, the data can be tampered with. CQL supports the Append of data, and the result is that the history of the data is preserved. + > + > **Privatize** vs **Delete** + > + > The traditional database deletes the data (Delete), which is irreversible and irreversible. CQL supports Privatization of data, that is, transferring the permissions of the database to an impossible public key. This allows substantial deletion of sub-chain data. Deletion of all traces on the chain for a single piece of data is currently only supported in the Enterprise Edition. + +- **Q:** How does CQL store data for a database? + + **A:** Most of the operation of the user database is done on SQLChain. By default, the MainChain only saves the block hash of the SQLChain. For more details, please refer to [MainChain & SQLChain](./arch_layers#mainchain-sqlchain)。 + +- **Q:** What is the maximum amount of data supported by CQL? + + **A:** CQL's database data is stored on a separate SQLChain. The number of CQL databases depends on the number of Miners across the network. The upper limit of a single CQL database depends on the hardware performance. As of 2019-04-25, the largest table online of TestNet is a 2 Miner database running continuously on a AWS c5.2xlarge standard configuration with 433,211,000 rows of data and 3.2 TB of disk. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/quandl.md b/website/translated_docs/zh-CN/version-0.5.0/quandl.md new file mode 100644 index 0000000..79f18df --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/quandl.md @@ -0,0 +1,299 @@ +--- +id: version-0.5.0-quandl +title: 基于 Quandl 的金融数据分析 +original_id: quandl +--- + +## 关于 Quandl + +Quandl 是一个针对金融投资行业的大数据平台，其数据来源包括联合国、世界银行、中央银行等公开数据，核心财务数据来自 CLS 集团，Zacks 和 ICE 等，所有的数据源自 500 多家发布商， 是为投资专业人士提供金融，经济和替代数据的首选平台，拥有海量的经济和金融数据。 + +## Quandl 数据索引 + +### CovenantSQL 使用简介 + +首先，我们已基于 Quandl 的开放 API 将数据存放在 CovenantSQL 中，首先应该浏览一下 CovenantSQL 的使用介绍来熟悉一下如何连接并且使用 CovenantSQL。 + +现在由于客户端兼容问题， 请直接使用我们的 HTTP 服务来对 Quandl 数据库进行 query，未来兼容现在的 `cql` 客户端后会第一时间更新此文档。 + +具体通过 HTTP 服务来使用 CovenantSQL 请参考 [Python 驱动文档](https://github.com/CovenantSQL/cql-python-driver/blob/master/README.rst) 和 [NodeJS 驱动文档](https://github.com/CovenantSQL/node-covenantsql/blob/master/README.md) + +所需参数: + + host: 'e.morenodes.com' + port: 11108 + database: '057e55460f501ad071383c95f691293f2f0a7895988e22593669ceeb52a6452a' + + +### 数据使用方法 + +Quandl 数据分为表以及子表两层索引 + +数据库中，表名为`quandl_` + `database_code`为完整表名 + +通过查询表名来查看表的内容 + +具体使用时，需要结合`quandl_updateindex` 这张索引表来使用，（查询索引表时，请务必 limit 小于 10 万，因为全表数据量过大） + +使用时，请使用 where 语句限定`quandlcode`字段来查询表中的子表数据。 + +### 查询示例 + +1. 我们想要查询 欧盟委员会年度宏观经济数据库 的数据，我们找到其第一层索引的 `databasecode` 为`quandl_ameco`，于是，我们可以查询其第二层索引，用以下 SQL 命令行： + + `select * from quandl_updateindex where databasecode like 'ameco' group by quandlcode limit 10000` + +2. 然后通过第三列，我们可以查看`quandlcode`对应的描述 + + 比如 AMECO/ALB_1_0_0_0_AAGE 对应的就是阿尔巴尼亚的进出口相关信息，时间从 1960 到 1988。 + + Average share of imports and exports of goods in world trade excluding intra EU trade; Foreign trade statistics (1960-1998 Former EU-15) - Albania + + 于是，我们可以用以下方式把这个子表给查询出来 + + `select * from quandl_ameco where quandlcode like 'AMECO/ALB_1_0_0_0_AAGE' limit 10000` + +3. 注意：如果内容整列为 null 的，属于表结构本身不存在的字段，可以自行去除。 + +## Quandl 数据 Excel 插件使用说明 + +您可以下载 Quandl 数据 Excel 插件，无须安装，请解压到任意文件夹中。此插件目前仅支持 Office 2010 以及以上版本，office 2007 以及以下版本目前暂不支持。 + +### 配置 Excel 插件 + +解压下载后压缩包，在文件夹中有两个.xll 文件，`ClassLibrary7-AddIn.xll` 以及 `ClassLibrary7-AddIn64.xll` 文件，这两个文件分别对应 32 位的 Excel 与 64 位的 Excel，请根据您的电脑配置使用对应插件。 + +#### 修改 xml 配置 + +每个 `.xll` 文件对应一个 `.config` 的配置文件，也就是 `ClassLibrary7-AddIn.xll.config` 和`ClassLibrary7-AddIn64.xll.config`，为如下 xml 配置： + +```xml + + + + + + + + + +``` + +其中有如下配置需要修改，并保存： + +- certpath: 请填写 `read.data.thunderdb.io.pfx` 证书的绝对路径 + +#### 安装插件 + +有两种办法使用此 Excel 插件 + +1. 直接双击对应的 32 位或 64 位 Excel 的 xll 文件打开 + +![quandl_ext_1](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_1.png) + +如果弹出如上对话框，选择第一个： `仅为本回话启用此加载项`。然后新建一个 Excel 表格，如果在 Excel 的上方选项卡中看到 CovenantSQL，说明插件加载成功。 + +2. 打开 Excel，然后依次选择 `文件 — 选项 — 加载项`，管理选择 Excel 加载项，点击转到然后浏览选择解压后的对应版本的 `.xll` 文件，然后点击 `确定`，在选项卡中如果成功加载出 CovenantSQL 即为成功加载，如下图： + +![quandl_ext_2](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_2.png) + +#### 使用插件 + +选择 CovenantSQL 的选项卡可以看到 Quandl 数据查询，点击 Quandl 数据查询，会弹出一个窗体如下图所示： + +![quandl_ext_3](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_3.png) + +- 其中红色框住的列表部分是一级目录，下方则是所选项的具体描述 + +- 绿色按钮是通过选择的一级目录来查询二级目录。这里查询时间会随着所查询二级目录的大小以及用户自身的网络速度等因素而不同，可能查询时间会超过 1 分钟，请耐心等待。 + +- 黄色部分左边的列表是二级目录，右边的窗体则为列表项所选择的表的描述。 + +- 蓝色部分是导出数据的可选项 + + - Limit Number 是一次导出的最多数据条数，默认为 10000 条，最大值可填写 100000 + - Offset Number 是从数据库的第几条开始导出，因为之前会限定条数，例如我们之前导出了 10000 条数据，但是明显数据还没有导出全部，我们可以使用此功能选择 offset 10000 来从第 10000 条开始导出（注：数据库的计数从 0 开始，所以前 10000 条为 0-9999） + +现在，您即可在 Excel 中方便的调用存在 CovenantSQL 上的 Quandl 数据。 + +## 附件表 + +| DataBase | 名称 | 描述 | +| ------------ | ------------------------ | ------------------------------------------------------------------------------------------- | +| BUNDESBANK | 德意志联邦银行数据仓库 | 有关德国经济，货币和资本市场，公共财政，银行，家庭，欧元区总量，贸易和外债的数据。 | +| URC | 独角兽研究公司数据 | 纽约证券交易所，美国证券交易所和纳斯达克证券交易所的预付和下跌数据。从各种公开来源和报告中值。 | +| DCE | 大连商品交易所数据 | 来自DCE的农业和商品期货，历史跨越了近十年的特定期货。 | +| WFC | 富国银行住房抵押贷款数据 | 该数据库提供富国银行（Wells Fargo Bank）分部Wells Fargo Home Mortgage的抵押贷款购买和再融资利率。 | +| USDAFNS | 美国农业部食品与营养服务项目数据 | 食品和营养服务局为低收入家庭和儿童管理联邦营养援助计划。成本和参与率数据。 | +| LJUBSE | 卢布尔雅那证券交易所数据 | 该数据库包含卢布尔雅那股票交易所指数，总部位于斯洛文尼亚的卢布尔雅那。 | +| TOCOM | 东京商品交易所数据 | 来自东京商品交易所（TOCOM）的农业和商品期货，历史跨越了近十年的特定期货。 | +| WCSC | 世界银行企业积分卡数据 | 该数据库旨在提供世界银行集团在消除极端贫困和促进共同繁荣方面的表现的战略概述。 | +| CMHC | 加拿大住房抵押贷款公司 | CMHC是一家政府所有的公司，为加拿大公民提供经济适用房，并收集价格，建筑和供应等数据。 | +| WGEC | 世界银行全球经济监测商品数据（GEM） | 包含1960年至今的商品价格和指数的数据。 | +| FED | 美联储数据公布 | 美国官方关于货币供应量，利率，抵押贷款，政府财政，银行资产和债务，汇率，工业生产的数据。 | +| WPSD | 世界银行公共部分支出数据 | 由世界银行和国际货币基金组织共同开发的数据，汇集了详细的公共部门政府债务数据。 | +| UGID | 联合国全球指标 | 该数据库提供广泛的全球指标，涵盖人口，公共卫生，就业，贸易，教育，通货膨胀和外债。 | +| RBA | 澳大利亚储备银行数据 | 中央银行和货币当局，监管银行业，设定利率，并为政府债务提供服务。关键经济指标数据。 | +| UCOM | 联合国商品贸易数据 | 该数据库提供有关食品，活体动物，药品，金属，燃料和机械等商品进出口的全面综合数据。 | +| SIDC | 太阳影响数据分析中心数据 | SIDC主持从1700年开始的太阳活动数据，特别是太阳黑子活动。 | +| ZCE | 郑州商品交易所数据 | 来自ZCE的农业和商品期货，历史跨越了近十年的特定期货。 | +| USDAFAS | 美国农业部外国农业服务数据（FAS） | 美国农业部外国农业服务局将美国农业与世界市场联系起来。它提供了国外生产和出口的统计数据。 | +| OECD | 世界经济合作与发展组织数据 | 促进经济福利的发达国家国际组织。从成员和其他人收集数据以提出政策建议。 | +| OPEC | 欧佩克数据 | 国际组织和经济卡特尔监督伊拉克，伊朗，沙特阿拉伯和委内瑞拉等石油生产国的政策、油价数据。 | +| MCX | 印度多种商品交易所数据 | 印度最大的商品交易所，为金属，能源和农业期货交易提供服务。世界第三大合约和交易量交易所。 | +| ECONOMIST | 经济学人 - 巨无霸指数 | 巨无霸指数是由经济学家于1986年发明的，是一个轻松的指南，指出货币是否处于“正确”水平。它基于购买力平价理论（PPP）。 | +| NSDL | 国家证券存管有限公司（印度）数据 | 在印度存放负责该国经济发展的国家，该国家建立了国际标准的国家基础设施，处理在印度资本市场以非物质形式持有和结算的大部分证券。 | +| GDT | 全球乳品贸易数据 | nan | +| CFFEX | 中国金融期货交易所数据 | 来自CFFEX的指数和债券期货，对于特定期货的历史跨越近十年。 | +| CITYPOP | Thomas Brinkhoff的城市人口数据 | Thomas Brinkhoff提供了大多数国家城市和行政区域的人口数据。 | +| BCHARTS | 比特币图表汇率数据 | 来自所有主要比特币交易所的比特币兑换大量货币的汇率，包括当前和历史汇率。 | +| LOCALBTC | Local Bitcoins数据 | nan | +| JODI | JODI石油世界数据库 | JODI石油和天然气数据来自100多个国家，包括多种能源产品和各种计量方法。 | +| UENG | 联合国能源统计数据 | 该数据库提供有关新能源和可再生能源的生产，贸易，转换和最终消费的全面统计数据。 | +| ULMI | 联合国劳工市场指标 | 该数据库为世界上所有国家提供了按性别划分的全面青年失业数字。 | +| MAURITIUSSE | 毛里求斯证券交易所数据 | 毛里求斯证券交易所指数数据。 | +| UKRSE | 乌克兰交易所数据 | UKRSE提供与乌克兰最大证券交易所相关的最新数据。该交易所位于基辅，约占乌克兰总股本交易量的四分之三 | +| BITSTAMP | Bitstamp数据 | Bitstamp是一个比特币的交易平台。 | +| UNAE | 联合国国民账户估算数据 | 该数据库提供了全球所有国家不同部门的国内生产总值，国民总收入和总增加值的全球数据。 | +| UNAC | 联合国国民账户官方国家数据 | 该数据库提供有关国民账户的全球数据，例如家庭，公司和政府的资产和负债。 | +| UTOR | 联合国世界旅游业数据 | 该数据库提供有关国际旅游的综合数据。数据包括所有国家的旅游人数和旅游支出。 | +| WFE | 世界交易所联合会数据 | 该数据库提供有关国际旅游的综合数据。数据包括所有国家的旅游人数和旅游支出。 | +| FRBC | 克利夫兰联邦储备银行数据 | 克利夫兰联邦储备银行从数百家金融机构收集数据，包括存款机构，银行控股公司和其他用于评估金融机构状况的实体，以及收集经济和金融体系运作方式的见解。 | +| UGEN | 联合国性别信息 | 该数据库提供关于各种与性别有关的指标的全面综合数据，涵盖人口，卫生，教育和就业。 | +| BITFINEX | Bitfinex数据 | Bitfinex是比特币，莱特币和Darkcoin的交易平台，具有许多先进功能，包括保证金交易，交易所和点对点保证金融资。 | +| UGHG | 联合国温室气体清单 | 该数据库提供有关六种主要温室气体人为排放的全面综合数据。数据可以追溯到1990年。 | +| UIST | 联合国工业发展组织数据 | 该数据库提供有关工业发展指标的全球数据，包括产量，员工，工资，各种行业的增加值。 | +| PRAGUESE | 布拉格证券交易所数据 | 布拉格证券交易所的价格指数数据。 | +| PFTS | PFTS证券交易所（乌克兰）数据 | 来自PFTS证券交易所的指数数据，这是乌克兰最大的市场。 | +| WARSAWSE | 华沙证券交易所数据 | WIG20指数自1994年4月16日起根据WSE主要清单中20家最主要和最具流动性公司的股票价值计算。 | +| TUNISSE | 突尼斯证券交易所数据 | 突尼斯证券交易所的主要参考指数。 | +| FRKC | 堪萨斯城联邦储备银行数据 | FRKC是美联储第10区的区域中央银行，主要发布农业交易中的银行业务数据。 | +| UENV | 联合国环境统计数据 | 该数据库提供有关水和废物相关指标的全球数据，包括淡水供应和降水，以及废物的产生和收集。 | +| UFAO | 联合国粮食和农业数据 | 该数据库提供全球粮食和农业数据，包括作物生产，化肥消费，农业用地和牲畜用途。 | +| TAIFEX | 台湾期货交易所数据 | 来自TAIFEX的指数和债券期货，其历史跨越了十多年的特定期货。 | +| GDAX | GDAX（全球数字资产交易所）数据 | GDAX是世界上最受欢迎的买卖比特币的地方。 | +| ARES | 房地产证券化协会数据 | ARES保护投资者，有助于房地产证券化产品市场的发展，并促进房地产投资市场的扩张。 | +| SHADOWS | 影子联邦基金利率模型数据 | 该数据集包含 吴-侠 论文中关于影子联邦基金的三个主要指标，用于识别所有三大银行的影子利率。 | +| NAAIM | 全国积极投资管理者协会头寸指数 | NAAIM暴露指数代表NAAIM成员报告的美国股票市场的平均风险敞口。 | +| CBRT | 土耳其共和国中央银行数据 | CBRT负责采取措施维持土耳其金融体系的稳定。 | +| CEGH | 中欧天然气中心数据 | nan | +| FINRA | 美国金融业监管局数据 | 金融业监管局提供证券公司和交易所市场的短期利息数据。 | +| NASDAQOMX | 纳斯达克OMX全球指数数据 | 纳斯达克OMX发布的全球指数超过35,000种，包括全球股票，固定收益，股息，绿色，北欧，伊斯兰教等。每日数据。 | +| EURONEXT | 泛欧证券交易所数据 | 欧洲最大的交易所Euronext的历史股票数据。 | +| UICT | 联合国信息和通信技术数据 | 该数据库提供有关信息和通信技术的全面全球数据，包括所有国家的电话，蜂窝和互联网使用情况。 | +| USAID | 美国国际开发署数据 | 美国国际开发署提供了美国向世界其他地方提供的所有外国援助的完整历史记录。 | +| ZAGREBSE | 萨格勒布证券交易所数据 | 克罗地亚唯一的证券交易所。它发布有关其股票和债券指数表现的数据。 | +| QUITOSE | 基多证券交易所（厄瓜多尔）数据 | 厄瓜多尔国家证券交易所的指数。 | +| ECBCS | 欧盟委员会商业和消费者调查 | 该数据库中的数据来自欧盟（EU）和欧盟申请国的不同经济部门的统一调查。 | +| PSE | 巴黎经济学院数据 | 该数据库描述了越来越多国家的最高收入分配。数字是使用税收数据得出的。 | +| MALTASE | 马耳他证券交易所数据 | 马耳他证券交易所发挥作用，为其认可的名单提供金融工具的结构，随后可在受监管，透明和有序的市场（二级市场）进行交易。市场的主要参与者是发行人，股票交易所会员（股票经纪人）和投资者一般。 | +| GPP | 全球石油价格 | nan | +| PPE | 波兰电力交易所（TGE）数据 | nan | +| UKONS | 英国国家统计局数据 | 关于英国就业，投资，住房，家庭支出，国民账户和许多其他社会经济指标的数据。 | +| NCDEX | 国家商品及衍生品交易所（印度）数据 | 印度专业管理的在线多商品交易所 | +| WSE | 华沙证券交易所（GPW）数据 | nan | +| TFX | 东京金融交易所数据 | 东京金融交易所是一个期货交易所，主要交易金融工具市场，处理证券和市场衍生品。 | +| WGFD | 世界银行全球金融发展数据 | 有关金融系统特征的数据，包括金融机构和市场的规模，使用，获取，效率和稳定性的衡量标准。 | +| CEPEA | 应用经济学应用研究中心（巴西）数据 | CEPEA是圣保罗大学的一个经济研究中心，专注于农业企业问题，发布巴西商品价格指数。 | +| SBJ | 日本统计局数据 | 日本政府统计机构，提供有关就业和劳动力的统计数据。 | +| WGEM | 世界银行全球经济监测 | 关于全球经济发展的数据，涵盖高收入国家和发展中国家。 | +| WGDF | 世界银行全球发展金融 | 关于金融系统特征的数据，包括金融机构和市场的规模，使用，获取，效率和稳定性的衡量标准。 | +| WWDI | 世界银行世界发展指标 | 最新和最准确的发展指标，由官方认可的国际来源汇编而成。 | +| WESV | 世界银行企业调查 | 公司级私营部门数据，涵盖金融，腐败，基础设施，犯罪，竞争和绩效衡量等业务主题。 | +| WDBU | 世界银行存续商业数据 | 关于成员国和地方和区域一级选定城市的商业法规及其执法的数据。 | +| OSE | 大阪证券交易所数据 | 日本第二大证券交易所。与东京证券交易所不同，OSE在衍生品交易方面表现最为强劲，是日本的大多数期货和期权。 | +| RFSS | 俄罗斯联邦统计局数据 | 俄罗斯政府统计机构，负责在国家和地方层面发布俄罗斯的社会，经济和人口统计数据。 | +| SHFE | 上海期货交易所数据 | 大宗商品交换能源，金属和化学相关的工业产品。许多商品期货的衍生品市场。 | +| WGEP | 世界银行全球环境规划经济前景数据 | 关于全球经济的短期，中期和长期前景以及对发展中国家和减贫的影响的数据。 | +| USMISERY | 美国痛苦指数 | 由经济学家亚瑟·奥肯（Arthur Okun）开发的苦难指数是失业率加上通胀率。 | +| WJKP | 世界银行知识平台工作数据 | 与劳工有关的主题指标。 | +| WMDG | 世界银行千年发展目标数据 | 根据千年发展目标（MDGs）的目标和指标重新组织的世界发展指标数据。 | +| WPOV | 世界银行贫困统计 | 贫困人口比率，贫困差距以及国际和国家贫困线贫困人口数量的指标。 | +| EUREKA | Eurekahedge数据 | 一家研究公司专注于对冲基金和其他另类投资基金。它公布了对冲基金业绩的数据。 | +| MOFJ | 日本财务省数据 | 日本政府债券利率数据，由财政部每日公布。 | +| PIKETTY | Thomas Piketty数据 | “21世纪资本”中的收入和财富数据，哈佛大学出版社，2014。 | +| PSX | 巴基斯坦证交所数据 | 巴基斯坦证券交易所的股票收盘价格。 | +| SGX | 新加坡交易所数据 | 亚洲证券和衍生品交易所为许多大型新加坡和其他亚洲公司进行股票交易。在自己的交易所上市。 | +| UIFS | 联合国国际金融统计 | 该数据库提供有关国际财务指标的综合数据，如平均收入，债券收益率，政府收入和支出。 | +| UINC | 联合国工业商品数据 | 该数据库提供有关工业商品生产的全球数据，如矿石和矿物，食品，可运输货物和金属产品。 | +| INSEE | 国家统计和经济研究所（法国）数据 | INSEE是法国的国家统计机构。它收集有关法国经济和社会的数据，如社会经济指标和国民账户。 | +| SNB | 瑞士国家银行数据 | 中央银行负责货币政策和货币。有关国际账户，利率，货币供应和其他宏观经济指标的数据。 | +| ODE | 大阪道岛商品交易所数据 | 日本关西地区的一个非营利性商品交易所，交易七种主要农产品。 | +| WGEN | 世界银行性别统计 | 描述收入，工作类型，工作部门，农民生产率以及企业家公司规模和利润的性别差异的数据。 | +| WHNP | 世界银行健康营养与人口统计 | 关键的健康，营养和人口统计数据。 | +| WIDA | 世界银行国际发展协会 | 关于选定指标的IDA（国际开发协会）国家总体成果进展情况的数据。 | +| ECMCI | 欧盟委员会货币状况指数 | 每月更新，此数据库提供欧元区的货币状况指数值。历史可以追溯到1999年。 | +| NBSC | 中国国家统计局数据 | 中国有关金融，工业，贸易，农业，房地产和交通运输的统计数据。 | +| MAS | 新加坡金融管理局数据 | nan | +| MGEX | 明尼阿波利斯谷物交易所数据 | 促进农业指数贸易的区域商品期货和期权合约市场。 | +| WWGI | 世界银行全球治理指标 | 六个治理层面的总体和个别治理指标数据。 | +| ISM | 供应管理研究所 | ISM促进供应链管理实践，并发布有关生产和供应链，新订单，库存和资本支出的数据。 | +| UKR | 乌克兰交易所数据 | nan | +| FRBNY | 纽约联邦储备银行数据 | FRBNY是美国最大的区域中央银行。为纽约，康涅狄格州和新泽西州的大部分地区以及一些地区设定货币政策。 | +| FRBP | 费城联邦储备银行数据 | FRBP是美联储的区域中央银行。它发布有关商业信心指数，GDP，消费和其他经济指标的数据。 | +| FMSTREAS | 美国财政部 - 财务管理处数据 | 美利坚合众国的月收入/支出和赤字/盈余。 | +| EIA | 美国能源信息管理局数据 | 美国国家和州有关所有主要能源产品（如电力，煤炭，天然气和石油）的生产，消费和其他指标的数据。 | +| SOCSEC | 美国社会保障局数据 | 提供有关美国社会保障计划的数据，特别是受益人的人口统计数据;残疾人，老人和幸存者。 | +| TFGRAIN | 顶级飞行谷物合作社数据 | 玉米和大豆的现货价格，包括前月期货合约的基础。 | +| IRPR | 波多黎各统计研究所数据 | 波多黎各统计研究所制造业统计数据。 | +| BCHAIN | blockchain.com数据 | Blockchain是一个发布与比特币相关的数据的网站，每日更新。 | +| BITCOINWATCH | Bitcoin Watch数据 | 比特币采矿统计。 | +| ODA | 国际货币基金组织跨国宏观经济统计 | 国际货币基金组织的初级商品价格和世界经济展望数据，由非洲开放数据公布。优秀的跨国宏观经济数据。 | +| WADI | 世界银行非洲发展指标 | 关于非洲的一系列发展指标，包括国家，区域和全球估计数。 | +| WEDU | 世界银行教育统计 | 关于教育机会，进展，完成，扫盲，教师，人口和支出的国际可比指标。 | +| WGLF | 世界银行全球Findex（全球金融包容性数据库） | 关于人们如何储蓄，借贷，支付和管理风险的金融包容性指标。 | +| WWID | 世界财富和收入数据库 | 世界财富和收入数据库旨在提供开放和便捷的途径，以获取有关国家内部和国家之间世界收入和财富分配历史演变的最广泛的现有数据库。 | +| BTER | 比特儿数据 | 加密货币的历史汇率数据。 | +| CFTC | 商品期货交易委员会报告 | 交易员和集中比率的每周承诺。期货头寸以及期货加期权头寸的报告。新旧格式。 | +| BOE | 英格兰银行官方统计 | 当前和历史汇率，担保贷款和定期存款利率，欧元商业票据利率和政府证券收益率。 | +| EXMPL | Quandl时间序列数据示例 | 一个时间序列数据库示例。 | +| WORLDAL | 铝价格 | 世界铝产能和产量（千公吨）。 | +| WGC | 黄金价格 | 世界黄金协会是黄金行业的市场开发组织。它以不同货币发布黄金价格数据。 | +| MX | 加拿大期货数据 | 蒙特利尔交易所是一家衍生品交易所，交易期货合约以及股票，指数，货币，ETF，能源和利率的期权。 | +| UMICH | 消费者情绪 | 密歇根大学的消费者调查 - 最近6个月的数据点是非官方的;它们来自华尔街日报的文章。 | +| JOHNMATT | 稀有金属价格数据 | 关于铂族金属的当前和历史数据，如价格，供应和需求。 | +| NAHB | 美国住房指数 | 美国的住房和经济指数。 | +| RATEINF | 通货膨胀率 | 阿根廷，澳大利亚，加拿大，德国，欧元区，法国，意大利，日本，新西兰等国的通货膨胀率和消费物价指数CPI。 | +| RENCAP | IPO数据 | 有关美国IPO市场的数据。 | +| ML | 公司债券收益率数据 | 美林（Merrill Lynch）是美国一家大型银行，它发布了不同地区公司债券收益率的数据。 | +| MULTPL | S&P 500 | nan | +| RICI | 商品指数 | 综合，以美元为基础的总回报指数，代表全球经济中消费的一篮子商品的价值。 | +| AAII | 投资者情绪 | 美国个人投资者协会的情绪数据。 | +| BIS | 国际清算银行数据 | 国际清算银行为中央银行提供货币和金融稳定管理，促进国际合作，并作为中央银行的银行。 | +| BCB | 巴西中央银行统计数据库 | 巴西宏观经济数据，涵盖公共财政，国民账户，支付系统，通货膨胀，汇率，贸易和国际储备。 | +| BCRA | 阿根廷中央银行数据 | 阿根廷中央银行负责货币政策，提供外汇市场数据和主要宏观经济指标。 | +| FSE | 法兰克福证券交易所 | 法兰克福证券交易所的每日股票价格 | +| BLSN | 劳工统计局国际数据 | 各国的进出口价格统计，由劳工统计局公布。 | +| BLSP | 劳工统计局生产力数据 | 美国制造业，劳务和商业统计，由劳工统计局公布。 | +| FDIC | 联邦存款保险公司数据 | FDIC是一家银行存款高达25万美元的联邦保险公司，负责收集商业银行和储蓄机构的财务数据。 | +| BLSI | 美国劳工统计局通货膨胀和价格统计 | 美国国家和州一级的通胀数据，由劳工统计局公布。 | +| BLSE | 美国劳工统计局就业与失业统计 | 美国国家和州一级的就业和失业统计数据，由劳工统计局公布。 | +| BLSB | 美国劳工统计局薪酬福利统计 | 由劳工统计局公布的美国停工统计数据。 | +| BP | BP能源生产和消费数据 | BP是一家大型能源生产商和分销商。它提供了各个国家和较大次区域的能源生产和消费数据。 | +| LPPM | 白金和钯价格数据 | 全球钯金和铂金市场清算价格数据。 | +| CASS | 运费指数 | 自1990年以来，CASS每月提供与其他经济和供应链指标相关的货运趋势的CASS运费指数报告。 | +| MORTGAGEX | 可调利率抵押贷款指数 | ARM索引的历史住房数据。 | +| BUCHARESTSE | 布加勒斯特证券交易所数据 | 布加勒斯特证券交易所发布股票，权利，债券，基金单位，结构性产品和期货合约活动数据。 | +| AMECO | 欧盟委员会年度宏观经济数据库 | 欧洲委员会经济和财政事务总局（DG ECFIN）年度宏观经济数据库。 | +| ACC | 美国化学理事会数据 | 化学活性晴雨表（CAB）由美国化学理事会（ACC）出版。 CAB是一个经济指标，有助于预测整个美国经济的高峰和低谷，并突出了美国其他行业的潜在趋势。 | +| ABMI | 亚洲债券市场计划 | 中国和日本债券市场的指标，如规模和构成，市场流动性，收益率收益率和波动率。 | +| BITAL | 意大利证交所数据 | 该数据库提供了Borsa Italiana（现为伦敦证券交易所集团的一部分）的股票期货合约数据。 | +| BANKRUSSIA | 俄罗斯银行数据 | 俄罗斯银行的主要指标，包括银行业，货币供应量，金融市场和宏观经济统计数据。 | +| BOC | 加拿大银行统计数据库 | 加拿大的经济，金融和银行数据。包括利率，通货膨胀，国民账户等。每日更新。 | +| HKEX | 香港交易所数据 | 香港交易所股票价格，历史分割期货等每日更新。 | +| AMFI | 印度共同基金协会数据 | 该数据库代表印度共同基金协会的基金信息。 | +| BDM | 墨西哥银行数据 | 墨西哥银行负责货币政策和本国货币（比索），并提供账户和所有宏观经济变量的数据。 | +| BATS | BATS美国证券交易所数据 | Bats是美国的股票市场运营商，经营四个股票交易所--BZX Exchange，BYX Exchange，EDGA Exchange和EDGX Exchange | +| BSE | 孟买证券交易所数据 | 在印度孟买证券交易所交易的公司的日终价格，指数和其他信息。 | +| FRED | 美联储经济数据 | 来自圣路易斯联邦储备银行研究部门的增长，就业，通货膨胀，劳工，制造业和其他美国经济统计数据。 | +| FMAC | 房地美数据 | Freddie Mac的主要抵押贷款市场调查和其他地区特定历史抵押贷款利率的数据。 | +| EUREX | 欧洲期货交易所数据 | 欧洲最大的期货交易所EUREX的指数，利率，农业和能源期货，历史跨越了特定期货的十年。 | +| ECB | 欧洲中央银行数据 | 欧盟中央银行监督货币政策和欧元，并提供相关宏观经济变量的数据。 | +| BOF | 法国银行数据 | 法兰西银行通过欧洲中央银行体系的政策负责货币政策，并提供关键经济指标的数据。 | +| BELGRADESE | 贝尔格莱德证券交易所数据 | 贝尔格莱德证券交易所数据，每日更新。 | +| CHRIS | 维基连续期货 | Quandl所有600个期货的连续合约。建立在CME，ICE，LIFFE等原始数据之上。由Quandl社区策划。 50年的历史。 | +| BOJ | 日本银行数据 | nan | +| USTREASURY | 美国财政部数据 | 美国财政部确保国家的金融安全，管理国家债务，收取税收，发行货币，提供收益率数据。 | +| LBMA | 伦敦金银市场协会数据 | 伦敦黄金和白银市场的国际贸易协会，由中央银行，私人投资者，生产商，炼油商和其他代理商组成。 | +| PERTH | 珀斯铸币厂数据 | 珀斯造币厂的利率和商品价格的高点，低点和平均值每月更新一次。 | +| ZILLOW2 | Zillow房地产研究 | 房屋价格和租金按大小，类型和等级划分;住房供应，需求和销售。按邮政编码，街区，城市，都市区，县和州切片。 | \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/quickstart.md b/website/translated_docs/zh-CN/version-0.5.0/quickstart.md new file mode 100644 index 0000000..f3009fa --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/quickstart.md @@ -0,0 +1,186 @@ +--- +id: version-0.5.0-quickstart +title: Quick Start +original_id: quickstart +--- + + +## CovenantSQL Client + +### Install + +Please choose the installation method according to the operating system platform you use: + +#### MacOS + +- 🍺 Homebrew users can just run: + +```bash + brew install cql + ``` + +- non-Homebrew users can run: + + ```bash + sudo bash -c 'curl -L "https://bintray.com/covenantsql/bin/download_file?file_path=CovenantSQL-v0.5.0.osx-amd64.tar.gz" | \ + tar xzv -C /usr/local/bin/ --strip-components=1' + ``` + +#### Linux + +- Just run： + + ```bash + sudo bash -c 'curl -L "https://bintray.com/covenantsql/bin/download_file?file_path=CovenantSQL-v0.5.0.linux-amd64.tar.gz" | \ + tar xzv -C /usr/local/bin/ --strip-components=1' + ``` + +After the installation is complete, you can execute the following command to check whether the installation is successful. + +```bash +cql version +``` + +If you have any errors on the MacOS or Linux, you can try the following to fix it: + +```bash +sudo chmod a+x /usr/local/bin/cql* # Fix Permission +sudo ln -s /usr/local/bin/cql* /usr/bin/ # Fix if /usr/local/bin not in $PATH +``` + +If the problem persists please check out our GitHub page [submit issue](https://github.com/CovenantSQL/CovenantSQL/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D) + +### Utils + +| Tool | Introduction | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| cql | CovenantSQL client, `cql console` The command is similar to the `mysql` command and is used to manage the CQL databases, [More](./cql_intro) | +| cql-fuse | CovenantSQL's FUSE client, which can mount a CovenantSQL database as a file system | +| cql-minerd | CovenantSQL miner client, used to run the database to earn rewards, will open later | +| cqld | CovenantSQL main chain node, mainly run by CovenantLabs and partners in DPoS mode | + +> Windows platform we will release later, if there is a need please [submit issue](https://github.com/CovenantSQL/CovenantSQL/issues/new?assignees=&labels=&template=feature_request.md&title=) + +### TestNet + +At present, we have released the test network v0.5.0 for everyone to verify and experience the principle. You can choose to quickly perform access testing using the "public account". + +The configuration file and private key of the "public account":[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) (empty password)，or just run： + +```bash +mkdir -p ~/.cql/testnet-conf +curl -L https://git.io/fhFZe --output ~/.cql/testnet-conf/config.yaml +curl -L https://git.io/fhFZv --output ~/.cql/testnet-conf/private.key +chmod 600 ~/.cql/testnet-conf/private.key +``` + +**TestNet Notes**： + +> The "public account" is public and only for testing. Please do not store your application information in the database created by the "public account". We will clean the database data from time to time. +> +> The test network is temporarily composed of 3 Miners, so temporarily only supports `create 3` to create a database of 3 nodes. + +## Create a database + +```bash +cql create -config=~/.cql/testnet-conf/config.yaml -no-password \ +-wait-tx-confirm '{"node":1}' +``` + +The command execution takes a little long time, and the console outputs after about 30 seconds: + +> covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + +​ + +This means that you submitted the database `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` creation request to the main chain and created the database to complete. + +> Command execution takes some time, and the general process is: +> +> 1. The "Block Producer" that received the request performs a match of Miner and database creation requests. +> 2. Database creation request is verified and confirmed at other "Block Producer" nodes +> 3. Eligible Miner on SQLChain receives database task +> 4. SQLChain Miners builds a database cluster with Kayak +> 5. All Miners are ready to wait for a database request + +## Access the database + +```bash +cql console -config=~/.cql/testnet-conf/config.yaml -no-password \ +-dsn covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +After connecting to the database, you can manipulate the database on CovenantSQL according to your habit of operating the database. For example, execute `CREATE TABLE` to create a table, `SELECT` query data, and so on. + +## SQLChain Explorer + +One feature of CovenantSQL is that its query records are **immutable and traceable**, you can query the operation of a database through \[Test Web Block Browser\] (https://explorer.dbhub.org/) recording. + +> The TestNet's SQLChain Explorer is currently open-access, and anyone who knows the database ID can manipulate your data using TestNet's public key. + +Please fill in your database ID in the upper right corner of the page. For example: `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872`. You can see information about all the data created using TestNet's Key: + +![explorer](https://github.com/CovenantSQL/docs/raw/master/website/static/img/explorer.png) + +> **If you want to create your own private database, you need to create a new public-private key pair from scratch, please refer to the following section.** + +## Create your own account + +Our test network allows you to create your own account and create a database under your own account. Create an account with the following command (you will be asked to set the master password, you can add `-no-password` to leave blank)： + +```bash +cql generate -no-password config +``` + +Output： + + INFO[0000] cql build: cql HEAD-48fff30-20190328075135 linux amd64 go1.11.6 + "/home/work/.cql" already exists. + Do you want to delete it? (y or n, press Enter for default n): + y + Generating key pair... + Private key file: /home/work/.cql/private.key + Public key's hex: 024123d10696cf54fbf2b1e2b507ec4d1cbf2b4e87095774ad5fd6376cdae88e87 + Generated key pair. + Generating nonce... + INFO[0001] cpu: 2 + INFO[0001] position: 2, shift: 0x0, i: 1 + INFO[0001] position: 0, shift: 0x0, i: 0 + nonce: {{2556203225 0 0 0} 24 000000829171cb94b765b4d51f2601aaf2c0f5270827ed97ddbecf0075437dad} + node id: 000000829171cb94b765b4d51f2601aaf2c0f5270827ed97ddbecf0075437dad + Generated nonce. + Generating config file... + Generated config. + + +This command will create a `.cql` directory for you in your `$HOME` directory: + +- `~/.cql/private.key`: The generated private key is stored in the file by the master password encryption, and your account address needs to be created using this file; +- `~/.cql/config.yaml`: The generated configuration, cql can access the CovenantSQL TestNet with it. + +Let's continue to generate the account address (also called the wallet address, CovenantSQL address): + +```bash +cql wallet -no-password +``` + +Output： + + wallet address: bc3cba461500f49c2adf6e6e98c1b3513063227063512f0dd6a5160c01de5e3c + + +You can get the test PTC here with the wallet address obtained above: \[Request for PTC\] (https://testnet.covenantsql.io/). + +After up to 2 minutes, you can use the cql command line tool to check the balance: + +```bash +cql wallet -no-password -balance all +``` + +output： + + Particle balance is: 10000000 + Wave balance is: 0 + + +Congratulations, you have received our PTC stable currency, and you can start using CovenantSQL now. You can refer to [Golang uses CovenantSQL documentation](./driver_golang) for development. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/usecase.md b/website/translated_docs/zh-CN/version-0.5.0/usecase.md new file mode 100644 index 0000000..e0ab7d4 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/usecase.md @@ -0,0 +1,40 @@ +--- +id: version-0.5.0-usecase +title: Use case +original_id: usecase +--- + +## Traditional App + +### Privacy data + +If you are a developper of password management tools just like [1Password](https://1password.com/) or [LastPass](https://www.lastpass.com/). You can use CQL as the database to take benefits: + +1. Serverless: no need to deploy a server to store your user's password for sync which is the hot potato. +2. Security: CQL handles all the encryption work. Decentralized data storage gives more confidence to your users. +3. Regulation: CQL naturally comply with [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation). + +### IoT storage + +CQL miners are deployed globally, IoT node can write to nearest CQL miner directly. + +1. Cheaper: Without passing all the traffic through a gateway, you can save a large bandwidth fee. And, CQL is a shared economic database which makes storage cheaper. +2. Faster: CQL consensus protocol is designed for Internet where network latency is unavoidable. + +### Open data service + +For example, you are the most detailed Bitcoin OHLC data maintainer. You can directly expose an online SQL interface to your customers to meet a wide range of query needs. + +1. CQL can limit specific SQL query statements to meet the needs while also balancing data security; +2. CQL can record SQL query records on the blockchain, which is very convenient for customers to check their bills for long-tail customers and billing, like [this](https://explorer.dbhub.org/dbs/7a51191ae06afa22595b3904dc558d41057a279393b22650a95a3fc610e1e2df/requests/f466f7bf89d4dd1ece7849ef3cbe5c619c2e6e793c65b31966dbe4c7db0bb072) +3. For customers with high performance requirements, Slave nodes can be deployed at the customer to meet the needs of customers with low latency queries while enabling almost real-time data updates. + +### Secure storage + +Thanks to the CQL data history is immutable, CQL can be used as a storage for sensitive operational logs to prevent hacking and erasure access logs. + +* * * + +## ĐApp + +Storing data on Bitcoin or Ethereum is quite expensive ($4305 / MB on Ethereum 2018-05-15). Programming is very complicated due to the lack of support for structured data storage. CQL gives you a low-cost structured SQL database and also provides more room for ĐApp to exchange data with real-world. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/usecase_dapp.md b/website/translated_docs/zh-CN/version-0.5.0/usecase_dapp.md new file mode 100644 index 0000000..31b7e1b --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/usecase_dapp.md @@ -0,0 +1,7 @@ +--- +id: version-0.5.0-usecase_dapp +title: DApp +original_id: usecase_dapp +--- + +Storing data on Bitcoin or Ethereum is quite expensive ($4305 / MB on Ethereum 2018-05-15). Programming is very complicated due to the lack of support for structured data storage. CQL gives you a low-cost structured SQL database and also provides more room for ĐApp to exchange data with real-world. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/usecase_data_analysis.md b/website/translated_docs/zh-CN/version-0.5.0/usecase_data_analysis.md new file mode 100644 index 0000000..cb67b28 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/usecase_data_analysis.md @@ -0,0 +1,301 @@ +--- +id: version-0.5.0-usecase_data_analysis +title: Data Analysis +original_id: usecase_data_analysis +--- + +# Financial data analysis based on Quandl + +## About Quandl + +Quandl is a big data platform for the financial investment industry. Its data sources include public data such as the United Nations, the World Bank, and the Central Bank. The core financial data comes from CLS Group, Zacks and ICE. All data comes from more than 500 publishers. It is the preferred platform for investment professionals to provide financial, economic and alternative data with vast economic and financial data. + +## Quandl Data Index + +### Introduction to CovenantSQL + +First, we have stored the data in CovenantSQL based on Quandl's open API. Next, you should take a look at the introduction of CovenantSQL to know how to connect and use CovenantSQL. + +Now due to client compatibility issues, please use our HTTP service to query the Quandl database directly. This document will be updated as soon as possible after the current cql client is compatible. + +Use CovenantSQL specifically through the HTTP service. Please refer to the Python driver documentation and the NodeJS driver documentation. + +Required parameters: + + host: 'e.morenodes.com' + port: 11111 + database: '057e55460f501ad071383c95f691293f2f0a7895988e22593669ceeb52a6452a' + + +### How to use CQL-Quandl + +Quandl data is divided into tables and sub-tables + +In the database, the table name is `quandl_ + database_code` for the full table name + +View the contents of the table by querying the table name + +For specific use, you need to use the `quandl_updateindex` index table to use it. (When querying the index table, be sure to limit less than 100,000 because the full data is too large) + +Please using the `where` statement to qualify the `quandlcode` field to query the sub table data in the table. + +## Example + +1. We want to query the data of the European Commission's annual macroeconomic database. We find the database code of its first index is `quandl_ameco`, so we can query its second index, using the following SQL command line: + +```SQL + select * from quandl_updateindex where databasecode like 'ameco' group by quandlcode limit 10000; + ``` + +2. Then through the third column, we can see the description corresponding to the `quandlcode` + + For example, `AMECO/ALB_1_0_0_0_AAGE` corresponds to the import and export information of Albania from 1960 to 1988. + + Average share of imports and exports of goods in world trade excluding intra EU trade; Foreign trade statistics (1960-1998 Former EU-15) - Albania + + So, we can query this subtable in the following way. + + ```SQL + select * from quandl_ameco where quandlcode like 'AMECO/ALB_1_0_0_0_AAGE' limit 10000; + ``` + +3. Note: If the content of the content is null, it belongs to the field that does not exist in the table structure itself, you can remove it yourself. + +# Quandl Data Excel Plugin Instructions + +You can download the Quandl Data Excel plugin without having to install it, unzip it into any folder. This plugin currently only supports Office 2010 and above, and Office 2007 and below are currently not supported. + +## Configuring the Excel plugin + +Unzip the downloaded package. There are two .xll files in the folder, `ClassLibrary7-AddIn.xll` and `ClassLibrary7-AddIn64.xll` files. These two files correspond to 32-bit Excel and 64-bit Excel respectively. Please refer to your The computer configuration uses the corresponding plugin. + +### Modify the xml configuration + +Each .xll file corresponds to a .config configuration file, which is `ClassLibrary7-AddIn.xll.config` and `ClassLibrary7-AddIn64.xll.config`, configured for the following xml: + +```xml + + + + + + + + + +``` + +The following configuration needs to be modified and saved: + +`Certpath`: Please fill in the absolute path of the `read.data.covenantsql.io.pfx` certificate + +### Plugin installation + +There are two ways to use this Excel plugin + +1. Double-click the corresponding 32-bit or 64-bit Excel xll file to open it. + +![quandl_ext_1](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_1.png) + +If the above dialog box shows up, select the first one: Enable this add-on only for this callback. Then create a new Excel table. If you see CovenantSQL in the upper tab of Excel, the plugin is loaded successfully. + +2. Open Excel, then select File - Options - Add-ons, Manage Select Excel Add-Ins, click Go and browse to select the .xll file for the corresponding version after decompression, and then click OK. If you successfully load CovenantSQL in the tab, Successfully loaded, as shown below: + +![quandl_ext_2](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_2.png) + +### How to use plugin + +Select the CovenantSQL tab to see the Quandl data query. Click on the Quandl data query and a pop-up will appear as shown below: + +![quandl_ext_3](https://raw.githubusercontent.com/CovenantSQL/cql-excel-extension/master/refs/quandl_ext_3_en.png) + +- The part of the list that is framed by red is the first-level directory, and the lower part is the specific description of the selected item. +- The green button queries the se condary directory by selecting the primary directory. The query time will vary depending on the size of the secondary directory being queried and the user's own network speed. The query time may exceed 1 minute. Please be patient. +- The list on the left of the yellow part is the secondary directory, and the form on the right is the description of the table selected by the list item. + +- The blue part is an option to export data + + - Limit Number is the maximum number of data exported at a time. The default is 10000, and the maximum value can be filled in 100000. + - Offset Number is derived from the first few columns of the database, because the number of bars is limited. For example, we exported 10000 data before, but the obvious data has not been exported yet. We can use this function to select offset 10000 to start from the 10000th. Export (Note: the database count starts from 0, so the first 10000 is 0-9999) + +## Attachment + +| Database | Name | description | +| ------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| PIKETTY | Thomas Piketty | Data on Income and Wealth from "Capital in the 21st Century", Harvard University Press 2014. | +| BUNDESBANK | Deutsche Bundesbank Data Repository | Data on the German economy, money and capital markets, public finances, banking, households, Euro-area aggregates, trade and external debt. | +| URC | Unicorn Research Corporation | Advance and decline data for the NYSE, AMEX, and NASDAQ stock exchanges. From various publicly-available sources and the median value is reported. | +| DCE | Dalian Commodities Exchange | Agriculture and commodities futures from DCE, with history spanning almost a decade for select futures. | +| WFC | Wells Fargo Home Mortgage Loans | This database offers mortgage purchase and refinance rates from Wells Fargo Home Mortgage, a division of Wells Fargo Bank. | +| USDAFNS | U.S. Department of Agriculture FNS | Food and Nutrition Service administrates federal nutrition assistance programs for low-income households and children. Data on costs and participation rates. | +| LJUBSE | Ljubljana Stock Exchange (Slovenia) | This database contains the Ljubljana Stock Exchange indexes and is based in Ljubljana, Slovenia. | +| TOCOM | Tokyo Commodities Exchange | Agriculture and commodities futures from Tokyo Commodities Exchange (TOCOM), with history spanning almost a decade for select futures. | +| WCSC | World Bank Corporate Scorecard | This database is designed to provide a strategic overview of the World Bank Group’s performance toward ending extreme poverty and promoting shared prosperity. | +| CMHC | Canadian Mortgage and Housing Corporation | The CMHC is a gov’t-owned corporation that provides affordable housing to Canadian citizens and collects data such as prices, construction, and supply. | +| WGEC | World Bank Global Economic Monitor (GEM) Commodities | Data containing commodity prices and indices from 1960 to present. | +| FED | US Federal Reserve Data Releases | Official US figures on money supply, interest rates, mortgages, government finances, bank assets and debt, exchange rates, industrial production. | +| WPSD | World Bank Public Sector Debt | Data jointly developed by the World Bank and the International Monetary Fund, which brings together detailed public sector government debt data. | +| UGID | United Nations Global Indicators | This database offers a wide range of global indicators, covering population, public health, employment, trade, education, inflation and external debt. | +| RBA | Reserve Bank of Australia | Central bank and monetary authority, regulates banking industry, sets interest rates, and services governments debt. Data on key economic indicators. | +| UCOM | United Nations Commodity Trade | This database offers comprehensive global data on imports and exports of commodities such as food, live animals, pharmaceuticals, metals, fuels and machinery. | +| SIDC | Solar Influences Data Analysis Center | The SIDC hosts data spanning from the 1700s on solar activity, specifically sunspot activity. | +| ZCE | Zhengzhou Commodities Exchange | Agriculture and commodities futures from ZCE, with history spanning almost a decade for select futures. | +| USDAFAS | U.S. Department of Agriculture FAS | The USDA Foreign Agricultural Service connects U.S. agriculture with the world markets. It provides statistics on production and exports in foreign countries. | +| OECD | Organisation for Economic Co-operation and Development | International organization of developed countries that promotes economic welfare. Collects data from members and others to make policy recommendations. | +| OPEC | Organization of the Petroleum Exporting Countries | International organization and economic cartel overseeing policies of oil-producers, such as Iraq, Iran, Saudi Arabia, and Venezuela. Data on oil prices. | +| MCX | Multi Commodity Exchange India | Indias largest commodity exchange servicing futures trading in metals, energy, and agriculture. Worlds 3rd largest exchange in contracts and trading volume. | +| ECONOMIST | The Economist - Big Mac Index | The Big Mac index was invented by The Economist in 1986 as a lighthearted guide to whether currencies are at their “correct” level. It is based on the theory of purchasing-power parity (PPP). | +| NSDL | National Securities Depository Limited (India) | Depository in India responsible for economic development of the country that has established a national infrastructure of international standards that handles most of the securities held and settled in dematerialised form in the Indian capital market. | +| GDT | Global Dairy Trade | nan | +| CFFEX | China Financial Futures Exchange | Index and bond futures from CFFEX, with history spanning almost a decade for select futures. | +| CITYPOP | Thomas Brinkhoff: City Populations | Thomas Brinkhoff provides population data for cities and administrative areas in most countries. | +| BCHARTS | Bitcoin Charts Exchange Rate Data | Exchange rates for bitcoin against a large number of currencies, from all major bitcoin exchanges, including current and historical exchange rates. | +| LOCALBTC | Local Bitcoins | nan | +| JODI | JODI Oil World Database | JODI oil and gas data comes from over 100 countries consisting of multiple energy products and flows in various methods of measurement. | +| UENG | United Nations Energy Statistics | This database offers comprehensive global statistics on production, trade, conversion, and final consumption of new and renewable energy sources. | +| ULMI | United Nations Labour Market Indicators | This database offers comprehensive youth unemployment figures broken up by gender for all countries in the world. | +| MAURITIUSSE | Stock Exchange of Mauritius | Stock Exchange of Mauritius indices data. | +| UKRSE | Ukrainian Exchange | UKRSE presents the most current available data related to the largest stock exchanges in Ukraine. The exchange is located in Kiev and accounts for roughly three-quarters of Ukraines total equity trading volume | +| BITSTAMP | Bitstamp | Bitstamp is a trading platform for Bitcoin. | +| UNAE | United Nations National Accounts Estimates | This database offers global data on gross domestic product, gross national income, and gross value added by different sectors for all countries in the world. | +| UNAC | United Nations National Accounts Official Country Data | This database offers global data on national accounts, such as assets and liabilities of households, corporations and governments. | +| UTOR | United Nations World Tourism | This database offers comprehensive data on international tourism. Data includes number of tourist arrivals and tourism expenditures for all countries. | +| WFE | World Federation of Exchanges | A trade association of sixty publicly regulated stock, futures, and options exchanges that publishes data for its exchanges, like market capitalization. | +| FRBC | Federal Reserve Bank of Cleveland | The Federal Reserve Bank of Cleveland collects data from hundreds of financial institutions, including depository institutions, bank holding companies, and other entities that is used to assess financial institution conditions and also to glean insights into how the economy and financial system are doing. | +| UGEN | United Nations Gender Information | This database offers comprehensive global data on a wide range of gender-related indicators, covering demography, health, education and employment. | +| BITFINEX | Bitfinex | Bitfinex is a trading platform for Bitcoin, Litecoin and Darkcoin with many advanced features including margin trading, exchange and peer to peer margin funding. | +| UGHG | United Nations Greenhouse Gas Inventory | This database offers comprehensive global data on anthropogenic emissions of the six principal greenhouse gases. Data goes back to 1990. | +| UIST | United Nations Industrial Development Organization | This database offers global data on industrial development indicators, including output, employees, wages, value added for a wide range of industries. | +| PRAGUESE | Prague Stock Exchange | Price index data from the Prague Stock Exchange. | +| PFTS | PFTS Stock Exchange (Ukraine) | Index data from the PFTS Stock Exchange, the largest marketplace in Ukraine. | +| WARSAWSE | Warsaw Stock Exchange | WIG20 index has been calculated since April 16, 1994 based on the value of portfolio with shares in 20 major and most liquid companies in the WSE Main List. | +| TUNISSE | Tunis Stock Exchange | The main reference index of Tunis Stock Exchange. | +| FRKC | Federal Reserve Bank of Kansas City | FRKC is the regional central bank for the 10th District of the Federal Reserve, publishing data on banking in mostly agricultural transactions. | +| UENV | United Nations Environment Statistics | This database offers global data on water and waste related indicators, including fresh water supply and precipitation, and generation and collection of waste. | +| UFAO | United Nations Food and Agriculture | This database offers global food and agricultural data, covering crop production, fertilizer consumption, use of land for agriculture, and livestock. | +| TAIFEX | Taiwan Futures Exchange | Index and bond futures from TAIFEX, with history spanning over a decade for select futures. | +| GDAX | GDAX (Global Digital Asset Exchange) | GDAX is the world’s most popular place to buy and sell bitcoin. | +| ARES | Association for Real Estate Securitization | ARES protects investors, contributes to development of the real estate securitization product market, and facilitates expansion of the real estate investment market. | +| SHADOWS | Wu-Xia Shadow Federal Funds Rate | This dataset contains the three major indicators from the Wu-Xia papers which serve to identify the shadow rates on all three major banks. | +| NAAIM | NAAIM Exposure Index | The NAAIM Exposure Index represents the average exposure to US Equity markets reported by NAAIM members. | +| CBRT | Central Bank of the Republic of Turkey | CBRT is responsible for taking measures to sustain the stability of the financial system in Turkey. | +| CEGH | Central European Gas Hub | No description for this database yet. | +| FINRA | Financial Industry Regulatory Authority | Financial Industry Regulatory Authority provides short interest data on securities firms and exchange markets. | +| NASDAQOMX | NASDAQ OMX Global Index Data | Over 35,000 global indexes published by NASDAQ OMX including Global Equity, Fixed Income, Dividend, Green, Nordic, Sharia and more. Daily data. | +| EURONEXT | Euronext Stock Exchange | Historical stock data from Euronext, the largest European exchange. | +| UICT | United Nations Information and Communication Technology | This database offers comprehensive global data on information and communication technology, including telephone, cellular and internet usage for all countries. | +| USAID | U.S. Agency for International Development | US Agency for International Development provides a complete historical record of all foreign assistance provided by the United States to the rest of the world. | +| ZAGREBSE | Zagreb Stock Exchange | Croatias only stock exchange. It publishes data on the performance of its stock and bond indexes. | +| QUITOSE | Quito Stock Exchange (Ecuador) | The indexes of the national Stock Exchange of Ecuador. | +| ECBCS | European Commission Business and Consumer Surveys | Data in this database is derived from harmonized surveys for different sectors of the economies in the European Union (EU) and in the EU applicant countries. | +| PSE | Paris School of Economics | This database describes the distribution of top incomes in a growing number of countries. Numbers are derived using tax data. | +| MALTASE | Malta Stock Exchange | The Malta Stock Exchange carries out the role of providing a structure for admission of financial instruments to its recognised lists which may subsequently be traded on a regulated, transparent and orderly market place (secondary market).The main participants in the market are Issuers, Stock Exchange Members (stockbrokers), and the investors in general. | +| GPP | Global Petroleum Prices | No description for this database yet. | +| PPE | Polish Power Exchange (TGE) | No description for this database yet. | +| UKONS | United Kingdom Office of National Statistics | Data on employment, investment, housing, household expenditure, national accounts, and many other socioeconomic indicators in the United Kingdom. | +| NCDEX | National Commodity & Derivatives Exchange Limited (India) | A professionally managed on-line multi-commodity exchange in India | +| WSE | Warsaw Stock Exchange (GPW) | No description for this database yet. | +| TFX | Tokyo Financial Exchange | The Tokyo Financial Exchange is a futures exchange that primary deals in financial instruments markets that handle securities and market derivatives. | +| WGFD | World Bank Global Financial Development | Data on financial system characteristics, including measures of size, use, access to, efficiency, and stability of financial institutions and markets. | +| CEPEA | Center for Applied Studies on Applied Economics (Brazil) | CEPEA is an economic research center at the University of Sao Paulo focusing on agribusiness issues, publishing price indices for commodities in Brazil. | +| SBJ | Statistics Bureau of Japan | A Japanese government statistical agency that provides statistics related to employment and the labour force. | +| WGEM | World Bank Global Economic Monitor | Data on global economic developments, with coverage of high-income, as well as developing countries. | +| WGDF | World Bank Global Development Finance | Data on financial system characteristics, including measures of size, use, access to, efficiency, and stability of financial institutions and markets. | +| WWDI | World Bank World Development Indicators | Most current and accurate development indicators, compiled from officially-recognized international sources. | +| WESV | World Bank Enterprise Surveys | Company-level private sector data, covering business topics including finance, corruption, infrastructure, crime, competition, and performance measures. | +| WDBU | World Bank Doing Business | Data on business regulations and their enforcement for member countries and selected cities at the subnational and regional level. | +| OSE | Osaka Securities Exchange | The second largest securities exchange in Japan. Unlike the TSE, OSE is strongest in derivatives trading, the majority of futures and options in Japan. | +| RFSS | Russian Federation Statistics Service | The Russian governmental statistical agency that publishes social, economic, and demographic statistics for Russia at the national and local levels. | +| SHFE | Shanghai Futures Exchange | Commodities exchange for energy, metal, and chemical-related industrial products. A derivatives marketplace for many commodities futures. | +| WGEP | World Bank GEP Economic Prospects | Data on the short-, medium, and long-term outlook for the global economy and the implications for developing countries and poverty reduction. | +| USMISERY | United States Misery Index | Developed by economist Arthur Okun, the Misery Index is the unemployment rate added to the inflation rate. | +| WJKP | World Bank Jobs for Knowledge Platform | Indicators on labor-related topics. | +| WMDG | World Bank Millennium Development Goals | Data drawn from the World Development Indicators, reorganized according to the goals and targets of the Millennium Development Goals (MDGs). | +| WPOV | World Bank Poverty Statistics | Indicators on poverty headcount ratio, poverty gap, and number of poor at both international and national poverty lines. | +| EUREKA | Eurekahedge | A research company focused on hedge funds and other alternative investment funds. It publishes data on the performances of hedge funds. | +| MOFJ | Ministry of Finance Japan | Japanese government bond interest rate data, published daily by the Ministry of Finance. | +| PSX | Pakistan Stock Exchange | Daily closing stock prices from the Pakistan Stock Exchange. | +| SGX | Singapore Exchange | Asian securities and derivatives exchange that trades in equities for many large Singaporean and other Asian companies. Listed on its own exchange. | +| UIFS | United Nations International Financial Statistics | This database offers comprehensive data on international financial indicators, such as average earnings, bond yields, government revenues and expenditures. | +| UINC | United Nations Industrial Commodities | This database offers global data on production of industrial commodities, such as ores and minerals, food products, transportable goods, and metal products. | +| INSEE | National Institute of Statistics and Economic Studies (France) | INSEE is the national statistical agency of France. It collects data on Frances economy and society, such as socioeconomic indicators and national accounts. | +| SNB | Swiss National Bank | Central bank responsible for monetary policy and currency. Data on international accounts, interest rates, money supply, and other macroeconomic indicators. | +| ODE | Osaka Dojima Commodity Exchange | A non-profit commodity exchange in the Kansai region of Japan that trades in seven key agricultural commodities. | +| WGEN | World Bank Gender Statistics | Data describing gender differences in earnings, types of jobs, sectors of work, farmer productivity, and entrepreneurs’ firm sizes and profits. | +| WHNP | World Bank Health Nutrition and Population Statistics | Key health, nutrition and population statistics. | +| WIDA | World Bank International Development Association | Data on progress on aggregate outcomes for IDA (International Development Association) countries for selected indicators. | +| ECMCI | European Commission Monetary Conditions Index | Updated monthly, this database provides monetary conditions index values in the Euro zone. History goes back to 1999. | +| NBSC | National Bureau of Statistics of China | Statistics of China relating to finance, industry, trade, agriculture, real estate, and transportation. | +| MAS | Monetary Authority of Singapore | No description for this database yet. | +| MGEX | Minneapolis Grain Exchange | A marketplace of futures and options contracts for regional commodities that facilitates trade of agricultural indexes. | +| WWGI | World Bank Worldwide Governance Indicators | Data on aggregate and individual governance indicators for six dimensions of governance. | +| ISM | Institute for Supply Management | ISM promotes supply-chain management practices and publishes data on production and supply chains, new orders, inventories, and capital expenditures. | +| UKR | Ukrainian Exchange | No description for this database yet. | +| FRBNY | Federal Reserve Bank of New York | The FRBNY is the largest regional central bank in the US. Sets monetary policy for New York, most of Connecticut and New Jersey, and some territories. | +| FRBP | Federal Reserve Bank of Philadelphia | The FRBP is a regional central bank for the Federal Reserve. It publishes data on business confidence indexes, GDP, consumption, and other economic indicators. | +| FMSTREAS | US Treasury - Financial Management Service | The monthly receipts/outlays and deficit/surplus of the United States of America. | +| EIA | U.S. Energy Information Administration Data | US national and state data on production, consumption and other indicators on all major energy products, such as electricity, coal, natural gas and petroleum. | +| SOCSEC | Social Security Administration | Provides data on the US social security program, particularly demographics of beneficiaries; disabled, elderly, and survivors. | +| TFGRAIN | Top Flight Grain Co-operative | Cash price of corn and soybeans including basis to front month futures contract. | +| IRPR | Puerto Rico Institute of Statistics | Puerto Rico Institute of Statistics statistics on manufacturing. | +| BCHAIN | Blockchain | Blockchain is a website that publishes data related to Bitcoin, updated daily. | +| BITCOINWATCH | Bitcoin Watch | Bitcoin mining statistics. | +| ODA | IMF Cross Country Macroeconomic Statistics | IMF primary commodity prices and world economic outlook data, published by Open Data for Africa. Excellent cross-country macroeconomic data. | +| WADI | World Bank Africa Development Indicators | A collection of development indicators on Africa, including national, regional and global estimates. | +| WEDU | World Bank Education Statistics | Internationally comparable indicators on education access, progression, completion, literacy, teachers, population, and expenditures. | +| WGLF | World Bank Global Findex (Global Financial Inclusion database) | Indicators of financial inclusion measures on how people save, borrow, make payments and manage risk. | +| WWID | World Wealth and Income Database | The World Wealth and Income Database aims to provide open and convenient access to the most extensive available database on the historical evolution of the world distribution of income and wealth, both within countries and between countries. | +| BTER | BTER | Historical exchange rate data for crypto currencies. | +| CFTC | Commodity Futures Trading Commission Reports | Weekly Commitment of Traders and Concentration Ratios. Reports for futures positions, as well as futures plus options positions. New and legacy formats. | +| BOE | Bank of England Official Statistics | Current and historical exchange rates, interest rates on secured loans and time deposits, Euro-commercial paper rates, and yields on government securities. | +| EXMPL | Quandl Example Time-Series Data | An example time series database. | +| WORLDAL | Aluminium Prices | World Aluminium capacity and production in thousand metric tonnes. | +| WGC | Gold Prices | The World Gold Council is a market development organization for the gold industry. It publishes data on gold prices in different currencies. | +| MX | Canadian Futures | Montreal Exchange is a derivatives exchange that trades in futures contracts and options for equities, indices, currencies, ETFs, energy, and interest rates. | +| UMICH | Consumer Sentiment | The University of Michigan’s consumer survey - data points for the most recent 6 months are unofficial; they are sourced from articles in the Wall Street Journal. | +| JOHNMATT | Rare Metals | Current and historical data on platinum group metals such as prices, supply, and demand. | +| NAHB | US Housing Indices | Housing and economic indices for the United States. | +| RATEINF | Inflation Rates | Inflation Rates and the Consumer Price Index CPI for Argentina, Australia, Canada, Germany, Euro area, France, Italy, Japan, New Zealand and more. | +| RENCAP | IPOs | Data on the IPO market in the United States. | +| ML | Corporate Bond Yield Rates | Merrill Lynch, a major U.S. bank, publishes data on yield rates for corporate bonds in different regions. | +| MULTPL | S&P 500 Ratios | No description for this database yet. | +| RICI | Commodity Indices | Composite, USD based, total return index, representing the value of a basket of commodities consumed in the global economy. | +| AAII | Investor Sentiment | American Association of Individual Investor’s sentiment data. | +| BIS | Bank for International Settlements | BIS serves central banks with administration of monetary and financial stability, fosters international cooperation, and acts as bank for central banks. | +| BCB | Central Bank of Brazil Statistical Database | Brazilian macroeconomic data, covering public finances, national accounts, payment systems, inflation, exchange rates, trade, and international reserves. | +| BCRA | Central Bank of Argentina | The Central Bank of Argentina is responsible monetary policy and provides data on foreign exchange markets and key macroeconomic indicators. | +| FSE | Frankfurt Stock Exchange | Daily stock prices from the Frankfurt Stock Exchange | +| BLSN | BLS International | Import and export price statistics for various countries, published by the Bureau of Labor Statistics. | +| BLSP | BLS Productivity | US manufacturing, labor and business statistics, published by the Bureau of Labor Statistics. | +| FDIC | Federal Deposit Insurance Corporation | The FDIC is a federal insurer of bank deposits up to $250k and collects finance data on commercial banking and savings institutions. | +| BLSI | BLS Inflation & Prices | US national and state-level inflation data, published by the Bureau of Labor Statistics. | +| BLSE | BLS Employment & Unemployment | US national and state-level employment and unemployment statistics, published by the Bureau of Labor Statistics. | +| BLSB | BLS Pay & Benefits | US work stoppage statistics, published by the Bureau of Labor Statistics. | +| BP | Energy Production and Consumption | BP is a large energy producer and distributor. It provides data on energy production and consumption in individual countries and larger subregions. | +| LPPM | Platinum & Palladium Prices | Price data on the market-clearing level for Palladium and Platinum around the world. | +| CASS | Freight Indices | Since 1990, CASS provides monthly Cass Freight Index Reports on freight trends as they relate to other economic and supply chain indicators. | +| MORTGAGEX | ARM Indices | Historical housing data on ARM indexes. | +| BUCHARESTSE | Bucharest Stock Exchange | The Bucharest Stock Exchange publishes data on it activity in equity, rights, bonds, fund units, structured products, and futures contracts. | +| AMECO | European Commission Annual Macro-Economic Database | Annual macro-economic database of the European Commissions Directorate General for Economic and Financial Affairs (DG ECFIN). | +| ACC | American Chemistry Council | Chemical Activity Barometer (CAB) published by the American Chemistry Council (ACC). The CAB is an economic indicator that helps anticipate peaks and troughs in the overall US economy and highlights potential trends in other industries in the US. | +| ABMI | Asia Bond Market Initiative | Indicators of Chinese and Japanese bond markets, such as size and composition, market liquidity, yield returns, and volatility. | +| BITAL | Borsa Italiana | This database provides data on stock future contracts from the Borsa Italiana, now part of London Stock Exchange Group. | +| BANKRUSSIA | Bank of Russia | Primary indicators from the Bank of Russia, including data on the banking sector, money supply, financial markets and macroeconomic statistical data. | +| BOC | Bank of Canada Statistical Database | Economic, financial and banking data for Canada. Includes interest rates, inflation, national accounts and more. Daily updates. | +| HKEX | Hong Kong Exchange | Hong Kong Exchange stock prices, historical divided futures, etc. updated daily. | +| AMFI | Association of Mutual Funds in India | This database represents fund information from The Association of Mutual Funds in India. | +| BDM | Bank of Mexico | The Bank of Mexico is responsible for monetary policy and the national currency (peso), and provides data on accounts and all macroeconomic variables. | +| BATS | BATS U.S. Stock Exchanges | Bats is an equities market operator in the U.S., operating four equities exchanges — BZX Exchange, BYX Exchange, EDGA Exchange, and EDGX Exchange | +| BSE | Bombay Stock Exchange | End of day prices, indices, and additional information for companies trading on the Bombay Stock Exchange in India. | +| FRED | Federal Reserve Economic Data | Growth, employment, inflation, labor, manufacturing and other US economic statistics from the research department of the Federal Reserve Bank of St. Louis. | +| FMAC | Freddie Mac | Data from Freddie Mac’s Primary Mortgage Market Survey and other region specific historical mortgage rates. | +| EUREX | EUREX Futures Data | Index, rate, agriculture and energy futures from EUREX, Europes largest futures exchange, with history spanning a decade for select futures. | +| ECB | European Central Bank | The central bank for the European Union oversees monetary policy and the Euro, and provides data on related macroeconomic variables. | +| BOF | Bank of France | The Banque de France is responsible for monetary policy through policies of the European System of Central Banks and providing data on key economic indictors. | +| BELGRADESE | Belgrade Stock Exchange | Belgrade Stock Exchange data, updated daily. | +| CHRIS | Wiki Continuous Futures | Continuous contracts for all 600 futures on Quandl. Built on top of raw data from CME, ICE, LIFFE etc. Curated by the Quandl community. 50 years history. | +| BOJ | Bank of Japan | nan | +| USTREASURY | US Treasury | The U.S. Treasury ensures the nations financial security, manages the nations debt, collects tax revenues, and issues currency, provides data on yield rates. | +| LBMA | London Bullion Market Association | An international trade association in the London gold and silver market, consisting of central banks, private investors, producers, refiners, and other agents. | +| PERTH | Perth Mint | The Perth Mint’s highs, lows and averages of interest rates and commodities prices, updated on a monthly basis. | +| ZILLOW2 | Zillow Real Estate Research | Home prices and rents by size, type and tier; housing supply, demand and sales. Sliced by zip code, neighbourhood, city, metro area, county and state. | \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.5.0/usecase_traditional_app.md b/website/translated_docs/zh-CN/version-0.5.0/usecase_traditional_app.md new file mode 100644 index 0000000..6ea9f47 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.5.0/usecase_traditional_app.md @@ -0,0 +1,32 @@ +--- +id: version-0.5.0-usecase_traditional_app +title: Traditional App +original_id: usecase_traditional_app +--- + +## Privacy data + +If you are a developper of password management tools just like [1Password](https://1password.com/) or [LastPass](https://www.lastpass.com/). You can use CQL as the database to take benefits: + +1. Serverless: no need to deploy a server to store your user's password for sync which is the hot potato. +2. Security: CQL handles all the encryption work. Decentralized data storage gives more confidence to your users. +3. Regulation: CQL naturally comply with [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation). + +## IoT storage + +CQL miners are deployed globally, IoT node can write to nearest CQL miner directly. + +1. Cheaper: Without passing all the traffic through a gateway, you can save a large bandwidth fee. And, CQL is a shared economic database which makes storage cheaper. +2. Faster: CQL consensus protocol is designed for Internet where network latency is unavoidable. + +## Open data service + +For example, you are the most detailed Bitcoin OHLC data maintainer. You can directly expose an online SQL interface to your customers to meet a wide range of query needs. + +1. CQL can limit specific SQL query statements to meet the needs while also balancing data security; +2. CQL can record SQL query records on the blockchain, which is very convenient for customers to check their bills for long-tail customers and billing, like [this](https://explorer.dbhub.org/dbs/7a51191ae06afa22595b3904dc558d41057a279393b22650a95a3fc610e1e2df/requests/f466f7bf89d4dd1ece7849ef3cbe5c619c2e6e793c65b31966dbe4c7db0bb072) +3. For customers with high performance requirements, Slave nodes can be deployed at the customer to meet the needs of customers with low latency queries while enabling almost real-time data updates. + +## Secure storage + +Thanks to the CQL data history is immutable, CQL can be used as a storage for sensitive operational logs to prevent hacking and erasure access logs. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/adapter.md b/website/translated_docs/zh-CN/version-0.6.0/adapter.md new file mode 100644 index 0000000..bb58d67 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/adapter.md @@ -0,0 +1,60 @@ +--- +id: version-0.6.0-adapter +title: Adapter +original_id: adapter +--- + +# Use Adapter to access CovenantSQL + +`CovenantSQL` provides an HTTP/HTTPS adapter service. Developers could access CovenantSQL like a cloud database by using HTTP RESTful requests. + +## How to use + +First, [Install docker](https://docs.docker.com/install/). + +Secondly, before using CovenantSQL, a proper configuration file and an asymmetric key-pair is required. If no configuration file is specified, CovenantSQL tries to load configuration from `~/.cql/config.yaml`. For configuration file and key-pair generation, please refer to [QuickStart#CreateAccount](./quickstart#CreateAccount) + +### Start adapter using docker + +Following command will use config file `~/.cql/config.yaml` and key-pair `~/.cql/private.key` to start adapter service and serving at `0.0.0.0:11105`. + +```bash +export adapter_addr=0.0.0.0:11105 +docker rm -f cql-adapter +docker run -itd \ + --env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \ + --env COVENANTSQL_ADAPTER_ADDR=0.0.0.0:4661 \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --name cql-adapter -p $adapter_addr:4661 \ + covenantsql/covenantsql:testnet +``` + +### Create database + +Create new database using `cql create` command and provide database instance requirements. + +For example, create a single node database instance: + +```bash +docker run -it --rm \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --entrypoint /app/cql covenantsql/covenantsql:testnet \ + create -config /app/config.yaml -wait-tx-confirm -db-node 1 +``` + +This command would produce a database connection string (DSN) similar to following example. + +```bash +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +Use DSN to access CovenantSQL using various drivers. + +## Drivers + +1. [Golang](./driver_golang) +2. [Java](./driver_java) +3. [Python](./driver_python) +4. [NodeJS](./driver_js) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/adpater.md b/website/translated_docs/zh-CN/version-0.6.0/adpater.md new file mode 100644 index 0000000..adfb54d --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/adpater.md @@ -0,0 +1,59 @@ +--- +id: version-0.6.0-adapter +title: Adapter +original_id: adapter +--- + +# Use Adapter to access CovenantSQL + +`CovenantSQL` provides an HTTP/HTTPS adapter service. Developers could access CovenantSQL like a cloud database by using HTTP RESTful requests. + +## How to use + +First, [Install docker](https://docs.docker.com/install/). + +Secondly, before using CovenantSQL, a proper configuration file and an asymmetric key-pair is required. If no configuration file is specified, CovenantSQL tries to load configuration from `~/.cql/config.yaml`. For configuration file and key-pair generation, please refer to [QuickStart#CreateAccount](./quickstart#CreateAccount) + +### Start adapter using docker + +Following command will use config file `~/.cql/config.yaml` and key-pair `~/.cql/private.key` to start adapter service and serving at `0.0.0.0:11105`. + +```bash +export adapter_addr=0.0.0.0:11105 +docker rm -f cql-adapter +docker run -itd \ + --env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --name cql-adapter -p $adapter_addr:4661 \ + covenantsql/covenantsql:testnet 0.0.0.0:4661 +``` + +### Create database + +Create new database using `cql create` command and provide database instance requirements. + +For example, create a single node database instance: + +```bash +docker run -it --rm \ + -v ~/.cql/config.yaml:/app/config.yaml \ + -v ~/.cql/private.key:/app/private.key \ + --entrypoint /app/cql covenantsql/covenantsql:testnet \ + create -config /app/config.yaml -wait-tx-confirm '{"node": 1}' +``` + +This command would produce a database connection string (DSN) similar to following example. + +```bash +covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 +``` + +Use DSN to access CovenantSQL using various drivers. + +## Drivers + +1. [Golang](./driver_golang) +2. [Java](./driver_java) +3. [Python](./driver_python) +4. [NodeJS](./driver_js) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/advanced_deployment.md b/website/translated_docs/zh-CN/version-0.6.0/advanced_deployment.md new file mode 100644 index 0000000..e094f97 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/advanced_deployment.md @@ -0,0 +1,160 @@ +--- +id: version-0.6.0-advanced_deployment +title: Private Deploy +original_id: advanced_deployment +--- + +## Deploy with CovenantSQL Docker + +### Install Docker + +You need to install docker and docker-compose on your machine to deploy CovenantSQL. + +Docker：https://docs.docker.com/install/ + +Docker-Compose：https://docs.docker.com/compose/install/ + +### Download project + +```bash +git clone https://github.com/CovenantSQL/CovenantSQL +cd CovenantSQL +``` + +For all subsequent commands, the working directory is by default in the cloned CovenantSQL root directory, which can be saved as an environment variable: + +```bash +export COVENANTSQL_ROOT=$PWD +``` + +### Start Docker container + +There are now two ways to start the CovenantSQL container: + +1. Use a public image on Docker Hub +2. Build a CovenantSQL Docker image + +> We recommend that regular users test CovenantSQL in the first way, and the second is only used to experience the latest development features. + +#### 1. Use a public image on Docker Hub + +Then start directly: + +```bash +make start +``` + +#### 2. Build a CovenantSQL Docker image + +Run CovenantSQL locally by executing the following command + +```bash +make docker # compile a new image from source files +make start +``` + +### Check running status + +Check the container status: + +```bash +docker-compose ps +``` + +Confirm that all components are in the `Up` state + + Name Command State Ports + ------------------------------------------------------------------------------------------------------ + covenantsql_bp_0 "./docker-entry.sh" Up 0.0.0.0:11099->4661/tcp + covenantsql_bp_1 "./docker-entry.sh" Up 0.0.0.0:11100->4661/tcp + covenantsql_bp_2 "./docker-entry.sh" Up 0.0.0.0:11101->4661/tcp + covenantsql_miner_0 "./docker-entry.sh" Up 0.0.0.0:11102->4661/tcp + covenantsql_miner_1 "./docker-entry.sh" Up 0.0.0.0:11103->4661/tcp + covenantsql_miner_2 "./docker-entry.sh" Up 0.0.0.0:11104->4661/tcp + covenantsql_adapter "./docker-entry.sh" Up 0.0.0.0:11105->4661/tcp + covenantsql_mysql_adapter "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11107->4664/tcp + covenantsql_observer "./docker-entry.sh" Up 4661/tcp, 0.0.0.0:11108->80/tcp + covenantsql_fn_0 "./docker-entry.sh -…" Up 4661/tcp, 0.0.0.0:11110->8546/tcp + + +## Operate CovenantSQL + +### Create a database + +Create a DB instance by using the `cql` command and using the `create` parameter to provide the required number of database nodes. + +e.g.: creating a single-node database instance + +```bash +cql create -config ${COVENANTSQL_ROOT}/test/service/node_c/config.yaml -db-node 1 +``` + +> Modify the value of the `create` parameter to create an instance running on multiple nodes +> e.g.: create an instance of two nodes + +```bash +cql create -config ${COVENANTSQL_ROOT}/test/service/node_c/config.yaml -db-node 2 +``` + +The command will return the connection string of the created database instance + + covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + + +### Accessing the database + +Use the `cql` command and use the `dsn` parameter to provide a connection string for the database instance access: + +```bash +cql console -config ${COVENANTSQL_ROOT}/test/service/node_c/config.yaml covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4 + ``` + +After that, it will get the following output, and enter the `cql` interactive command line mode + +``` + +Connected with driver covenantsql (develop) Type "help" for help. + +co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> + +
The `cql` interactive command line mode is similar to the `mysql` command. For example, create a table named test, view the tables in the database, insert records, and query results etc. + + ```sql + CREATE TABLE test (test TEXT); + SHOW TABLES; + INSERT INTO test VALUES("happy"); + SELECT * FROM test; + + +After that, it will get the following output: + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> CREATE TABLE test (test TEXT); + CREATE TABLE + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SHOW TABLES; + name + ------ + test + (1 row) + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> INSERT INTO test VALUES("happy"); + INSERT + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> SELECT * FROM test; + test + ------- + happy + (1 row) + + co:0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4=> + + +Use the `Ctrl + D` shortcut or type `\q` to exit the `cql` interactive command line + +### SQLChain Observer + +The Observer role in the image uses the same private.key as in the mysql-adapter image, so the new account authorization and transfer process can be eliminated. + +（For details on rights management, please refer to [Database Permission Managemen](cql_db_manage#granting-permission)） + +#### Use SQLChain Observer in your browser + +We provide a SQLChain Observer at port `127.0.0.1:11108` to see the SQL statement on the chain. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/cql_account.md b/website/translated_docs/zh-CN/version-0.6.0/cql_account.md new file mode 100644 index 0000000..77608b5 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/cql_account.md @@ -0,0 +1,144 @@ +--- +id: version-0.6.0-cql_account +title: Account Management +original_id: cql_account +--- + +For the TestNet environment, we provide a public account for quick testing. Check the [CovenantSQL TestNet](quickstart) tutorial to find out the private key and config file of the public account. And you can also follow the next section to create an individual account with `cql` command. + +## Creating New Account + +The sub-command `generate` generates a private key file and a config file connecting to the TestNet in the specified directory, e.g.: + +```bash +cql generate +``` + +> Currently, the generated config file is pointed to the TestNet, we will provide options to generated config for Docker Environment later. + +For a complete help message, check [Complete Parameters](#sub-command-generate-complete-parameters). + +Output: + + Generating private key... + Please enter password for new private key + Generated private key. + Generating nonce... + INFO cpu: 4 + INFO position: 2, shift: 0x0, i: 2 + INFO position: 0, shift: 0x0, i: 0 + INFO position: 3, shift: 0x0, i: 3 + INFO position: 1, shift: 0x0, i: 1 + nonce: {{973366 0 586194564 0} 26 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b} + node id: 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b + Generated nonce. + Generating config file... + Generated config. + + Config file: ~/.cql/config.yaml + Private key file: ~/.cql/private.key + Public key's hex: 03f195dfe6237691e724bcf54359d76ef388b0996a3de94a7e782dac69192c96f0 + + Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + Any further command could costs PTC. + You can get some free PTC from: + https://testnet.covenantsql.io/wallet/dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + +### Public Key + +Generate command also print public key (in hex string format) of the private key file, e.g.: + +Output： + + Public key's hex: 03f195dfe6237691e724bcf54359d76ef388b0996a3de94a7e782dac69192c96f0 + + +> This info is usually not used in common scene. + +### Wallet address + +Generate command shows wallet address (in hex string format) and will store in `config.yaml` file, e.g.: + +Output： + + Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + Any further command could costs PTC. + You can get some free PTC from: + https://testnet.covenantsql.io/wallet/dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + +After get a wallet address, you may need to request PTC as above. + +## Sub-command `generate` Complete Parameters + +Also see [Common Parameters for Sub-commands](cql_intro#common-parameters-for-sub-commands). We will not mention this again in the later sub-command introductions. + + usage: cql generate [common params] [-source template_file] [-miner] [-private existing_private_key] [dest_path] + + Generate generates private.key and config.yaml for CovenantSQL. + You can input a passphrase for local encrypt your private key file by set -with-password + e.g. + cql generate + + or input a passphrase by + + cql generate -with-password + + Generate params: + -miner string + Generate miner config with specified miner address + -private string + Generate config using an existing private key + -source string + Generate config using the specified config template + + +## Mine a Node ID + +The sub-command `idminer` is used to mine another Node ID of a private key (specified by a config file), (also check [Node ID](terms#node-id) for details). e.g.: + +```bash +cql idminer +``` + +Output: + + INFO[0000] cql build: cql develop-34ae741a-20190415161544 linux amd64 go1.11.5 + Enter master key(press Enter for default: ""): + + INFO[0008] init config success path=/home/levente/.cql/config.yaml + INFO[0008] use public key in config file: /home/levente/.cql/config.yaml + INFO[0008] cpu: 8 + INFO[0008] position: 3, shift: 0x20, i: 7 + INFO[0008] position: 0, shift: 0x0, i: 0 + INFO[0008] position: 3, shift: 0x0, i: 6 + INFO[0008] position: 1, shift: 0x0, i: 2 + INFO[0008] position: 2, shift: 0x0, i: 4 + INFO[0008] position: 1, shift: 0x20, i: 3 + INFO[0008] position: 2, shift: 0x20, i: 5 + INFO[0008] position: 0, shift: 0x20, i: 1 + nonce: {{1251426 4506240821 0 0} 25 00000041bc2b3de3bcb96328d0004c684628a908f0233eb31fe9998ef0c6288e} + node id: 00000041bc2b3de3bcb96328d0004c684628a908f0233eb31fe9998ef0c6288e + + +> This functionality is usually not used in common scene. + +## Sub-command `idminer` Complete Parameters + + usage: cql idminer [common params] [-difficulty number] [-loop [true]] + + IDMiner calculates legal node id and it's nonce. Default parameters are difficulty of 24 and no endless loop. + e.g. + cql idminer -difficulty 24 + + If you want to mine a good id, use: + cql idminer -config ~/.cql/config.yaml -loop -difficulty 24 + + Params: + -difficulty int + the difficulty for a miner to mine nodes and generating a nonce (default 24) + -loop + mining endless loop \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/cql_advance.md b/website/translated_docs/zh-CN/version-0.6.0/cql_advance.md new file mode 100644 index 0000000..7de9d99 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/cql_advance.md @@ -0,0 +1,29 @@ +--- +id: version-0.6.0-cql_advance +title: Advanced Usage +original_id: cql_advance +--- + +Sub-command `rpc` calls the remote process directly in the CovenantSQL network. + +## Sub-command `rpc` Complete Parameter + + usage: cql rpc [common params] [-wait-tx-confirm] [-endpoint rpc_endpoint | -bp] -name rpc_name -req rpc_request + + RPC makes a RPC request to the target endpoint. + e.g. + cql rpc -name 'MCC.QuerySQLChainProfile' \ + -endpoint 000000fd2c8f68d54d55d97d0ad06c6c0d91104e4e51a7247f3629cc2a0127cf \ + -req '{"DBID": "c8328272ba9377acdf1ee8e73b17f2b0f7430c798141080d0282195507eb94e7"}' + + RPC params: + -bp + Call block producer node + -endpoint string + RPC endpoint Node ID to do test call + -name string + RPC name to do test call + -req string + RPC request to do test call, in json format + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/cql_db_access.md b/website/translated_docs/zh-CN/version-0.6.0/cql_db_access.md new file mode 100644 index 0000000..b6b90e4 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/cql_db_access.md @@ -0,0 +1,89 @@ +--- +id: version-0.6.0-cql_db_access +title: Accessing Database +original_id: cql_db_access +--- + +Once your database is successfully created, you can use the `console` sub-command to access it in an interactive console: + +```bash +cql console 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io + INFO[0010] init config success path=~/.cql/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-da3af8f6-20190515152207) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Or access as `account2` (Should been granted access permission and transfered deposit token to the database successfully in last section): + +```bash +cql console -config "account2/config.yaml" 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io + INFO[0010] init config success path=~/.config/cql/account2/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-da3af8f6-20190515152207) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Here is an example of using the interactive console: + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> create table t1 (c1 int); + CREATE TABLE + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> insert into t1 values (1), (2), (3); + INSERT + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> select * from t1; + c1 + ---- + 1 + 2 + 3 + (3 rows) + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +## Sub-command `console` Complete Parameters + +The sub-command `console` also supports running `adapter` or `explorer` servers in the background. Check [Local Servers](#local-servers) for details. + + usage: cql console [common params] [Console params] dsn + + Console runs an interactive SQL console for CovenantSQL. + e.g. + cql console covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + There is also a -command param for SQL script, and a -file param for reading SQL in a file. + If those params are set, it will run SQL script and exit without staying console mode. + e.g. + cql console -command "create table test1(test2 int);" covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + Console params: + -adapter string + Address to serve a database chain adapter, e.g. :7784 + -command string + Run only single command (SQL or usql internal command) and exit + -explorer string + Address serve a database chain explorer, e.g. :8546 + -file string + Execute commands from file and exit + -no-rc + Do not read start up file + -out string + Record stdout to file + -single-transaction + Execute as a single transaction (if non-interactive) + -variable value + Set variable \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/cql_db_manage.md b/website/translated_docs/zh-CN/version-0.6.0/cql_db_manage.md new file mode 100644 index 0000000..8fd2f9a --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/cql_db_manage.md @@ -0,0 +1,244 @@ +--- +id: version-0.6.0-cql_db_manage +title: Database Management +original_id: cql_db_manage +--- + +## Creating Database + +Like `transfer`, `create` takes several parameters. e.g. Create a database with one miner node: + +```bash +cql create -db-node 1 +``` + +Output: + + INFO[0000] Geting bp address from dns: bp00.testnet.gridb.io + INFO[0048] Register self to blockproducer: 00000000000589366268c274fdc11ec8bdb17e668d2f619555a2e9c1a29c91d8 + INFO init config success path=~/.cql/config.yaml + INFO create database requested + + The newly created database is: "covenantsql://962bbb3a8028a203e99121d23173a38fa24a670d52c8775a9d987d007a767ce4" + The connecting string beginning with 'covenantsql://' could be used as a dsn for `cql console` + or any command, or be used in website like https://web.covenantsql.io + + +Here `covenantsql://962bbb3a8028a203e99121d23173a38fa24a670d52c8775a9d987d007a767ce4` is the database source name (DSN) of the created database. And the `covenantsql` part is the scheme, which can be `cql` in abbreviation. The hex string after `://` is the database address, which can be used as a receiver address in `transfer` command. + +The sub-command `create` sends transactions to block producers to create databases, so it has a `wait-tx-confirm` parameter too. + +For a complete help message, check [Complete Parameters](#sub-command-create-complete-parameters). + +## Billing + +CovenantSQL uses Gas for billing just like the [Ethereum Gas](https://www.ethos.io/what-is-ethereum-gas/). The gas unit (a.k.a., the `Gas-Price`) in stable token `Particle` is specified while creating the database, and its corresponding field is `-db-gas-price`. If not specified in the parameter, it will be set as 1 by default. Another billing-related field is `-db-advance-payment`, which will be used as deposit and query expending. The default advance payment is 20,000,000. Creating a database with specified `Gas-Price` and `Advance-Payment`: + +```bash +cql create -db-node 2 -db-gas-price 5 -db-advance-payment 500000000 +``` + +Thus we created a new database with `Gas-Price` 5 and `Advance-Payment` 500,000,000. Note that when the CovenantSQL network is short of miner resources, setting a higher `Gas-Price` will help your creation request to be accepted earlier, but it will cost you more tokens of course. + +> At present, we only accept the CovenantSQL stable token Particle for database billing. More token types will be supported soon. + +And the billing is processed as following: + +- For a Read request, the result `rows_count` is counted as the `Gas` cost +- For a Write request, the result `affected_rows` is counted as the `Gas` cost +- The SQLChain miner does periodic billing, sums up, and reports the `Gas` cost to the main chain, and the main chain verifies and deducts `Gas` * `Gas Price` tokens from the user accounts + +## ~~Deleting Database~~ + +~~Not yet implemented.~~ + +## Granting Permission + +### Access Permission + +CovenantSQL database has 3 kinds of access permission: + +- `Admin` +- `Write` +- `Read` +- `Void` (for none) + +Among them, `Admin` is the permission that can assign permissions (`Admin`, `Write`, or `Read`) to the other accounts. `Admin` and `Write` allows the write queries (such as `CREATE`, `INSERT`, and etc.). `Admin` and `Read` allows the read queries (such as `SHOW`, `SELECT`, and etc.). If you want to allow a user to read/write the database but not allow to modify the permissions of itself or other accounts, you can assign the user permission as `Read,Write`. `Void` is a special kind of permission which means 'no permission'. Once the `Admin` sets the permission of an account as `Void`, it will no longer able to read or write the database. The account who creates the database will be granted the initial `Admin` permission by default. + +Assume that you have created a database `covenantsql:\\4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5` with default account, and have generated another account under directory `account2` which has the address `011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6`. Now you can grant permissions to `accounts` to access the database, with parameters as following: + +```bash +`-to-dsn` Target database adderss to give permission +`-to-user` Target wallet address to get permission +`-perm` Permission, separated by commas +``` + +Pass the parameter to `grant`: + +```bash +cql grant -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 \ + -perm "Read,Write" +``` + +Output: + + INFO[0000] Geting bp address from dns: bp04.testnet.gridb.io + INFO[0003] Self register to blockproducer: 00000000003b2bd120a7d07f248b181fc794ba8b278f07f9a780e61eb77f6abb + INFO init config success path=~/.cql/config.yaml + INFO succeed in grant permission on target database + + +Or revoke the permission: + +```bash +cql grant -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 \ + -perm "Void" +``` + +Output: + + INFO[0000] Geting bp address from dns: bp04.testnet.gridb.io + INFO[0003] Self register to blockproducer: 00000000003b2bd120a7d07f248b181fc794ba8b278f07f9a780e61eb77f6abb + INFO init config success path=~/.cql/config.yaml + INFO succeed in grant permission on target database + + +The sub-command `grant` sends transactions to block producers to request permission granting, so it has a `wait-tx-confirm` parameter too. + +Since the database separately keeps billing for each user, you need to transfer tokens to the database (as user deposit and advance payment) from the new account before it can actually get access to the database. The minimum amount of deposit and advance payment can be calculated by: `gas_price*number_of_miner*120000`. + +Transferring from `account2` to the database: + +```bash +cql transfer -config "account2/config.yaml" \ + -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -amount 90000000 \ + -token Particle +``` + +### SQL White List + +CovenantSQL supports white list setting for each of its users. By setting up SQL white list, you can further limit the access permission of a user to a given list of SQL Patterns with assignable parameters. With this feature, your database can be further secured because it avoids important data breach and accidentally updating/deleting. + +Adding a white list: + +```bash +cql grant -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 \ + -perm ' +{ + "patterns": [ + "SELECT COUNT(1) FROM a", + "SELECT * FROM a WHERE id = ? LIMIT 1" + ], + "role": "Read,Write" +} +' +``` + +*SQL White List is an extension of the database permission system. It currently doesn't support incrementally updating, so you need to provide the complete permission information each time you use the `grant` sub-command* + +Cleaning the white list: + +```bash +
cql grant -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 \ + -perm ' +{ + "patterns": null, + "role": "Read,Write" +} +' + + or + +cql grant -to-dsn covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5 \ + -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 \ + -perm "Read,Write" +``` + +Either setting the `pattern` field to `null` or just resetting the user permission directly, will eliminate the white list and give back the access permission to the user. + +## Sub-command `create` Complete Parameters + + usage: cql create [common params] [-wait-tx-confirm] [db_meta_params] + + Create command creates a CovenantSQL database by database meta params. The meta info must include + node count. + e.g. + cql create -db-node 2 + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction + confirmation before the creation takes effect. + e.g. + cql create -wait-tx-confirm -db-node 2 + + DB meta params: + -db-advance-payment uint + Customized advance payment + -db-consistency-level float + Consistency level, node*consistency_level is the node count to perform strong consistency + -db-encrypt-key string + Encryption key for persistence data + -db-eventual-consistency + Use eventual consistency to sync among miner nodes + -db-gas-price uint + Customized gas price + -db-isolation-level int + Isolation level in a single node + -db-load-avg-per-cpu float + Minimum idle CPU requirement, 0 for none + -db-memory uint + Minimum memory requirement, 0 for none + -db-node uint + Target node count + -db-space uint + Minimum disk space requirement, 0 for none + -db-target-miners value + List of target miner addresses(separated by ',') + -wait-tx-confirm + Wait for transaction confirmation + + +## Sub-command `drop` Complete Parameters + + usage: cql drop [common params] [-wait-tx-confirm] dsn + + Drop drops a CovenantSQL database by DSN or database ID. + e.g. + cql drop covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction + confirmation before the drop operation takes effect. + e.g. + cql drop -wait-tx-confirm covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + Drop params: + -wait-tx-confirm + Wait for transaction confirmation + + +## Sub-command `grant` Complete Parameters + + usage: cql grant [common params] [-wait-tx-confirm] [-to-user wallet] [-to-dsn dsn] [-perm perm_struct] + + Grant grants specific permissions for the target user on target dsn. + e.g. + cql grant -to-user=43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 -to-dsn="covenantsql://xxxx" -perm perm_struct + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction + confirmation before the permission takes effect. + e.g. + cql grant -wait-tx-confirm -to-user=43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 -to-dsn="covenantsql://xxxx" -perm perm_struct + + Grant params: + -perm string + Permission type struct for grant. + -to-dsn string + Target database dsn to grant permission. + -to-user string + Target address of an user account to grant permission. + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/cql_intro.md b/website/translated_docs/zh-CN/version-0.6.0/cql_intro.md new file mode 100644 index 0000000..e83c52b --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/cql_intro.md @@ -0,0 +1,41 @@ +--- +id: version-0.6.0-cql_intro +title: Overview +original_id: cql_intro +--- + +CovenantSQL provides a `cql` command line toolset for terminal users to access and manage user accounts, wallet balances, and databases. Check the complete toolset installation tutorial at \[CovenantSQL Toolset installation\](quickstart#工具包安装). + +## Private Key and Config File + +The `cql` command needs to rely on a private key file `private.key` and a config file `config.yaml`: + +- `private.key`：a private key file which is generated while creating an account, be sure to keep it safe +- `config.yaml`：mainly used to config the CovenantSQL network for `cql` command to connect (e.g., the [TestNet](quickstart) or the [Private Deploy](advanced_deployment)) + +For security, the private key file is usually encrypted with a master key. A master key is individually chosen by the user while creating an account and is memorized or kept somewhere by the user -- note that the config file will not keep the master key. When the private key is required by the `cql` command, it will ask the user to input the master key to decrypt the private key file. + +## Command Format + +The `cql` command has more than a dozen subcommands, each one follows the same command format. e.g: + + cql sub-command [common parameters] [subcommand parameters] arguments + + +The content of `arguments` may be empty, but it must be placed at the end of the command when it is not empty. + +## Common Parameters for Sub-commands + +The following parameters are commonly used by `cql` sub-commands: + + -config string + Config file for covenantsql (Usually no need to set, default is enough.) (default "~/.cql/config.yaml") + -with-password + Use passphrase for private.key + -password string + Master key for covenantsql (NOT SAFE, for debugging or script mode only) + -help + Show help message + + +Note that the private key file path is specified in the config file, and its default value is `./private.key`, indicating that it's located in the same directory of the config. So usually we put the private key file together with config, instead of using an individual parameter to specify the private key file. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/cql_server.md b/website/translated_docs/zh-CN/version-0.6.0/cql_server.md new file mode 100644 index 0000000..033770a --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/cql_server.md @@ -0,0 +1,53 @@ +--- +id: version-0.6.0-cql_server +title: Local Servers +original_id: cql_server +--- + +## Sub-command `explorer` Complete Parameter + + usage: cql explorer [common params] [-tmp-path path] [-bg-log-level level] listen_address + + Explorer serves a SQLChain web explorer. + e.g. + cql explorer 127.0.0.1:8546 + + Explorer params: + -bg-log-level string + Background service log level: trace debug info warning error fatal panic (default "info") + -tmp-path string + Background service temp file path, use "dirname $(mktemp -u)" to check it out + + +## Sub-command `mirror` Complete Parameter + + usage: cql mirror [common params] [-tmp-path path] [-bg-log-level level] dsn listen_address + + Mirror subscribes database updates and serves a read-only database mirror. + e.g. + cql mirror dsn 127.0.0.1:9389 + + Mirror params: + -bg-log-level string + Background service log level: trace debug info warning error fatal panic (default "info") + -tmp-path string + Background service temp file path, use "dirname $(mktemp -u)" to check it out + + +## Sub-command `adapter` Complete Parameter + +See for details of adapter server. + + usage: cql adapter [common params] [-tmp-path path] [-bg-log-level level] [-mirror addr] listen_address + + Adapter serves a SQLChain adapter. + e.g. + cql adapter 127.0.0.1:7784 + + Adapter params: + -bg-log-level string + Background service log level: trace debug info warning error fatal panic (default "info") + -mirror string + Mirror server for adapter to query + -tmp-path string + Background service temp file path, use "dirname $(mktemp -u)" to check it out \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/cql_wallet.md b/website/translated_docs/zh-CN/version-0.6.0/cql_wallet.md new file mode 100644 index 0000000..73fb204 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/cql_wallet.md @@ -0,0 +1,131 @@ +--- +id: version-0.6.0-cql_wallet +title: Wallet Management +original_id: cql_wallet +--- + +## Wallet Address + +Once the private key and config file is set, you can use sub-command `wallet` to check the wallet address of the account: + +```bash +cql wallet +``` + +Output: + + INFO[0000] Geting bp address from dns: bp00.testnet.gridb.io + INFO[0003] Register self to blockproducer: 00000000000589366268c274fdc11ec8bdb17e668d2f619555a2e9c1a29c91d8 + INFO init config success path=~/.cql/config.yaml + + + wallet address: 290f7dbbff2aa0d5a5af65f4caa0bfd68663f97f9b08d0ee71e76a172349b613 + Particle balance is: 100000000 + Wave balance is: 0 + found no related database + + +The wallet address of the test account here is `290f7dbbff2aa0d5a5af65f4caa0bfd68663f97f9b08d0ee71e76a172349b613`. And balances are also shown. + +## Wallet Balances + +CovenantSQL currently supports 5 types of tokens: + +- `Particle` +- `Wave` +- `Bitcoin` +- `Ether` +- `EOS` + +Among them, `Particle` and `Wave` are the token types used by CovenantSQL. You can also check the balance of a specified type of token, e.g., checking the balance of `Bitcoin`: + +```bash +cql wallet -token Bitcoin +``` + +Output: + + INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io + INFO[0006] Register self to blockproducer: 0000000000293f7216362791b6b1c9772184d6976cb34310c42547735410186c + INFO init config success path=~/.cql/config.yaml + + wallet address: 290f7dbbff2aa0d5a5af65f4caa0bfd68663f97f9b08d0ee71e76a172349b613 + Bitcoin balance is: 0 + + +## Transferring Tokens to Another Account + +Once you get tokens from [TestNet](quickstart) or [Private Deploy](advanced_deployment), you can use the `transfer` sub-command to transfer tokens to another account. The command takes 3 main parameters, e.g.: + +```bash +cql transfer -to-user 011f72fea9efa1a49a6663d66e514a34e45e426524c13335cf20bec1b47d10d6 -amount 1000000 -token Particle +``` + +`-to-user` is set for other user's wallet address, `-amount` param is for token count, and `-token` is for token type + +## Transferring Tokens to a database + +If you want to transfer token to a database address, replace `-to-user` to `-to-dsn`, and set a CovenantSQL dsn string. e.g. + +```bash +cql transfer -to-dsn covenantsql://0bfea233d20676bb848b66d072bb768945507bb8a3b8b22b13133cde0583e208 -amount 1000000 -token Particle +``` + +While transferring to a database, the tokens will be used as the deposit and advance payment of that database for the sender. + +> Check more detailed knowledge about [Deposit and Advance Payment](terms#deposit-and-advance-payment). + +Output: + + INFO[0000] Geting bp address from dns: bp04.testnet.gridb.io + INFO[0043] Register self to blockproducer: 00000000003b2bd120a7d07f248b181fc794ba8b278f07f9a780e61eb77f6abb + INFO init config success path=~/.cql/config.yaml + INFO succeed in sending transaction to CovenantSQL + + +Note that the above output message indicates that the transfer request is successfully sent to CovenantSQL network, but it will take a while before the block producers actually execute and confirm the transaction to take effect. You can use the `cql wallet -token ` command again to check if the request takes effect, or add `-wait-tx-confirm` parameter to make `cql` wait for transaction confirmation before exit. + +## Sub-command `wallet` Complete Parameters + + usage: cql wallet [common params] [-token type] [-dsn dsn] + + Wallet gets the CovenantSQL wallet address and the token balances of the current account. + e.g. + cql wallet + + cql wallet -token Particle + + cql wallet -dsn "covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c" + + Wallet params: + -dsn string + Show specified database deposit + -token string + Get specific token's balance of current account, e.g. Particle, Wave, All + + +## Sub-command `transfer` Complete Parameters + + usage: cql transfer [common params] [-wait-tx-confirm] [-to-user wallet | -to-dsn dsn] [-amount count] [-token token_type] + + Transfer transfers your token to the target account or database. + The command arguments are target wallet address(or dsn), amount of token, and token type. + e.g. + cql transfer -to-user=43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 -amount=100 -token=Particle + + Since CovenantSQL is built on top of blockchains, you may want to wait for the transaction + confirmation before the transfer takes effect. + e.g. + cql transfer -wait-tx-confirm -to-dsn=43602c17adcc96acf2f68964830bb6ebfbca6834961c0eca0915fcc5270e0b40 -amount=100 -token=Particle + + Transfer params: + -amount uint + Token account to transfer. + -to-dsn string + Target database dsn to transfer token. + -to-user string + Target address of an user account to transfer token. + -token string + Token type to transfer. + -wait-tx-confirm + Wait for transaction confirmation \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.6.0/quickstart.md b/website/translated_docs/zh-CN/version-0.6.0/quickstart.md new file mode 100644 index 0000000..f4ef129 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.6.0/quickstart.md @@ -0,0 +1,184 @@ +--- +id: version-0.6.0-quickstart +title: Quick Start +original_id: quickstart +--- + + +## CovenantSQL Client + +### Install + +Please choose the installation method according to the operating system platform you use: + +#### MacOS + +- 🍺 Homebrew users can just run: + +```bash + brew install cql + ``` + +- non-Homebrew users can run: + + ```bash + sudo bash -c 'curl -L "https://mac.gridb.io/cql" | \ + tar xzv -C /usr/local/bin/ --strip-components=1' + ``` + +#### Linux + +- Just run： + + ```bash + sudo bash -c 'curl -L "https://linux.gridb.io/cql" | \ + tar xzv -C /usr/local/bin/ --strip-components=1' + ``` + +After the installation is complete, you can execute the following command to check whether the installation is successful. + +```bash +cql version +``` + +If you have any errors on the MacOS or Linux, you can try the following to fix it: + +```bash +sudo chmod a+x /usr/local/bin/cql* # Fix Permission +sudo ln -s /usr/local/bin/cql* /usr/bin/ # Fix if /usr/local/bin not in $PATH +``` + +If the problem persists please check out our GitHub page [submit issue](https://github.com/CovenantSQL/CovenantSQL/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D) + +### Utils + +| Tool | Introduction | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| cql | CovenantSQL client, `cql console` command is similar to the `mysql` command and is used to manage the CQL databases, [More](./cql_intro) | +| cql-fuse | CovenantSQL's FUSE client, which can mount a CovenantSQL database as a file system | +| cql-minerd | CovenantSQL miner client, used to run the database to earn rewards, will open later | +| cqld | CovenantSQL main chain node, mainly run by CovenantLabs and partners in DPoS mode | + +> Windows platform we will release later, if there is a need please [submit issue](https://github.com/CovenantSQL/CovenantSQL/issues/new?assignees=&labels=&template=feature_request.md&title=) + +### TestNet + +At present, we have released the test network v0.5.0 for everyone to verify and experience the principle. You can choose to quickly perform access testing using the "public account". + +The configuration file and private key of the "public account":[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) (empty password)，or just run： + +```bash +mkdir -p ~/.cql/testnet-conf +curl -L https://git.io/fhFZe --output ~/.cql/testnet-conf/config.yaml +curl -L https://git.io/fhFZv --output ~/.cql/testnet-conf/private.key +chmod 600 ~/.cql/testnet-conf/private.key +``` + +**TestNet Notes**： + +> The "public account" is public and only for testing. Please do not store your application information in the database created by the "public account". We will clean the database data from time to time. +> +> The test network is temporarily composed of 3 Miners, so temporarily only supports `create 3` to create a database of 3 nodes. + +## Create a testnet database + +```bash +cql create -config=~/.cql/testnet-conf/config.yaml \ + -db-node 1 -wait-tx-confirm +``` + +The command execution takes a little long time, and after about 30 seconds the console outputs something like below: + +> covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + +​ + +This means that you submitted the database(dsn) `covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` creation request to the main chain and created the database to complete. + +> Command execution takes some time, and the general process is: +> +> 1. The "Block Producer" that received the request performs a match of Miner and database creation requests. +> 2. Database creation request is verified and confirmed at other "Block Producer" nodes +> 3. Eligible Miner on SQLChain receives database task +> 4. SQLChain Miners builds a database cluster with Kayak +> 5. All Miners are ready to wait for a database request + +## Access the testnet database + +```bash +cql console -config=~/.cql/testnet-conf/config.yaml \ + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +After connecting to the database, you can manipulate the database on CovenantSQL according to your habit of operating the database. For example, execute `CREATE TABLE` to create a table, `SELECT` query data, and so on. + +## SQLChain Explorer + +One feature of CovenantSQL is that its query records are **immutable and traceable**, you can query the operation of a database through \[Test Web Block Browser\] (https://explorer.dbhub.org/) recording. + +> The TestNet's SQLChain Explorer is currently open-access, and anyone who knows the database ID can manipulate your data using TestNet's public key. + +Please fill in your database ID in the upper right corner of the page. For example: `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872`. You can see information about all the data created using TestNet's Key: + +![explorer](https://github.com/CovenantSQL/docs/raw/master/website/static/img/explorer.png) + +> **If you want to create your own private database, you need to create a new public-private key pair from scratch, please refer to the following section.** + +## Create your own account + +Our test network allows you to create your own account and create a database under your own account. Create an account with the following command (default empty passphrase for private.key, you can add `-with-password` to set passphrase)： + +```bash +cql generate +``` + +Output： + + Generating private key... + Please enter password for new private key + Generated private key. + Generating nonce... + INFO cpu: 4 + INFO position: 2, shift: 0x0, i: 2 + INFO position: 0, shift: 0x0, i: 0 + INFO position: 3, shift: 0x0, i: 3 + INFO position: 1, shift: 0x0, i: 1 + nonce: {{973366 0 586194564 0} 26 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b} + node id: 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b + Generated nonce. + Generating config file... + Generated config. + + Config file: ~/.cql/config.yaml + Private key file: ~/.cql/private.key + Public key's hex: 03f195dfe6237691e724bcf54359d76ef388b0996a3de94a7e782dac69192c96f0 + + Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + Any further command could costs PTC. + You can get some free PTC from: + https://testnet.covenantsql.io/wallet/dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + +This command will create a `.cql` directory for you in your `$HOME` directory: + +- `~/.cql/private.key`: The generated private key is stored in the file by the master password encryption, and your account address needs to be created using this file; +- `~/.cql/config.yaml`: The generated configuration, cql can access the CovenantSQL TestNet with it. + +It alse print your wallet address(also called the account address, CovenantSQL address): `Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95` + +You can get the test PTC here with the wallet address obtained above: \[Request for PTC\] (https://testnet.covenantsql.io/). + +After up to 2 minutes while requested PTC, you can use the cql command line tool to check the balance: + +```bash +cql wallet +``` + +output： + + Particle balance is: 10000000 + Wave balance is: 0 + + +Congratulations, you have received our PTC stable currency, and you can start using CovenantSQL now. You can refer to [Golang uses CovenantSQL documentation](./driver_golang) for development. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.7.0/arch.md b/website/translated_docs/zh-CN/version-0.7.0/arch.md new file mode 100644 index 0000000..cb39044 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.7.0/arch.md @@ -0,0 +1,61 @@ +--- +id: version-0.7.0-arch +title: Architecture +original_id: arch +--- + +## 3 Layers Arch + +![CovenantSQL 3 Layer design](https://github.com/CovenantSQL/CovenantSQL/raw/ed2878359345cd86e4221f14cd59e4654361b64e/logo/arch.png) + +- Layer 1: **Global Consensus Layer** (the main chain, the middle ring in the architecture diagram): + - There will only be one main chain throughout the network. + - Mainly responsible for database Miner and the user’s contract matching, transaction settlement, anti-cheating, shard chain lock hash and other global consensus matters. +- Layer 2: **SQL Consensus Layer** (shard chain, rings on both sides): + - Each database will have its own separate shard chain. + - Mainly responsible for: the signature, delivery and consistency of the various Transactions of the database. The data history of the permanent traceability is mainly implemented here, and the hash lock is performed in the main chain. +- Layer 3: **Datastore Layer** (database engine with SQL-92 support): + - Each Database has its own independent distributed engine. + - Mainly responsible for: database storage & encryption, query processing & signature, efficient indexing. + +## Consensus Algorithm + +CQL supports 2 kinds of consensus algorithm: + +1. DPoS (Delegated Proof-of-Stake) is applied in `Eventually consistency mode` database and also `Layer 1 (Global Consensus Layer)` in BlockProducer. CQL miners pack all SQL queries and its signatures by the client into blocks thus form a blockchain. We named the algorithm [`Xenomint`](https://github.com/CovenantSQL/CovenantSQL/tree/develop/xenomint). +2. BFT-Raft (Byzantine Fault-Toleranted Raft)bft-raft is applied in `Strong consistency mode` database. We named our implementation [`Kayak`](https://github.com/CovenantSQL/CovenantSQL/tree/develop/kayak). The CQL miner leader does a `Two-Phase Commit` with `Kayak` to support `Transaction`.transaction + +CQL database consistency mode and node count can be selected in database creation with command `cql create -db-eventual-consistency -db-node 3` + +## Comparison + +| | Ethereum | Hyperledger Fabric | Amazon QLDB | CovenantSQL | +| ---------------------------- | ----------------- | ---------------------- | ----------- | -------------------------------------------------------------------- | +| **Dev language** | Solidity, ewasm | Chaincode (Go, NodeJS) | ? | Python, Golang, Java, PHP, NodeJS, MatLab | +| **Dev Pattern** | Smart Contract | Chaincode | SQL | SQL | +| **Open Source** | Y | Y | N | Y | +| **Nodes for HA** | 3 | 15 | ? | 3 | +| **Column Level ACL** | N | Y | ? | Y | +| **Data Format** | File | Key-value | Document | Filefuse, Key-value, Structured | +| **Storage Encryption** | N | API | Y | Y | +| **Data Desensitization** | N | N | N | Y | +| **Multi-tenant** | DIY | DIY | N | Y | +| **Throughput (1s delay)** | 15~10 tx/s | 3500 tx/s | ? | 11065 tx/s (Eventually Consistency) +1866 tx/s (Strong Consistency) | +| **Consistency Delay** | 2~6 min | < 1 s | ? | < 10 ms | +| **Secure for Open Internet** | Y | N | Only in AWS | Y | +| **Consensus** | PoW + PoS(Casper) | CFT | ? | DPoS (Eventually Consistency) +BFT-Raft (Strong Consistency) | + + +### FootNotes + +- BFT-Raft: A CQL leader offline needs CQL Block Producer to decide whether to wait for leader online for data integrity or promote a follower node for availability. This part is still under construction and any advice is welcome. + +- Transaction: Talking about `ACID`, CQL has full "Consistency, Isolation, Durability" and a limited `Atomicity` support. That is even under strong consistency mode, CQL transaction is only supported on the leader node. If you want to do "read `v`, `v++`, write `v` back" parallelly and atomically, then the only way is "read `v` from the leader, `v++`, write `v` back to leader" + +- FUSE: CQL has a [simple FUSE](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql-fuse) support adopted from CockroachDB. The performance is not very ideal and still has some issues. But it can pass fio test like: + + ```bash + fio --debug=io --loops=1 --size=8m --filename=../mnt/fiotest.tmp --stonewall --direct=1 --name=Seqread --bs=128k --rw=read --name=Seqwrite --bs=128k --rw=write --name=4krandread --bs=4k --rw=randread --name=4krandwrite --bs=4k --rw=randwrite + ``` \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.7.0/arch_layers.md b/website/translated_docs/zh-CN/version-0.7.0/arch_layers.md new file mode 100644 index 0000000..aae9a8f --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.7.0/arch_layers.md @@ -0,0 +1,30 @@ +--- +id: version-0.7.0-arch_layers +title: Blockchains +original_id: arch_layers +--- + + +## MainChain & SQLChain + +CQL uses a layered architecture for database creation and operation. A typical data creation process can be roughly as follows: + +1. Miner will automatically register with the MainChain after startup. The registration information includes: "Minimum acceptable Gas price", "System metrics", "External IP and port", etc. +2. Miner subscribes to and pays attention to information related to themselves through ChainBus; +3. The client runs `cql create -db-node 2` to send a signed database creation request to any BP (Block Producer) in the MainChain; +4. The BP that received the request performs a match of Miner and database creation request in the process of producing the block (see: \[MainChain Produce Block\] (#mainchain-produce-block)); +5. Database creation requests and matching results are verified and confirmed at other BP nodes; +6. The Miner subscription receives the database task; +7. Miners discover and connect with each other through Kayak to form a SQLChain database cluster; +8. All miners are ready to wait for a request; +9. Users can connect to the database and execute SQL through the `cql console` command. + +See the image below to view [large picture](https://cdn.jsdelivr.net/gh/CovenantSQL/docs@b7143254adb804dff0e3bc1f2f6ab11ad9cd44f5/website/static/img/2layers.svg)： + +![2layers](https://cdn.jsdelivr.net/gh/CovenantSQL/docs@b7143254adb804dff0e3bc1f2f6ab11ad9cd44f5/website/static/img/2layers.svg) + +## MainChain Produce Block + +The complete main chain export process is complicated. Please refer to the numbers in the figure below for understanding. For the big picture, please click [here](https://cdn.jsdelivr.net/gh/CovenantSQL/docs/website/static/img/produce-block.svg) + +![MainChain Produce Block](https://cdn.jsdelivr.net/gh/CovenantSQL/docs/website/static/img/produce-block.svg) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.7.0/cql_db_access.md b/website/translated_docs/zh-CN/version-0.7.0/cql_db_access.md new file mode 100644 index 0000000..31da3bc --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.7.0/cql_db_access.md @@ -0,0 +1,85 @@ +--- +id: version-0.7.0-cql_db_access +title: Accessing Database +original_id: cql_db_access +--- + +Once your database is successfully created, you can use the `console` sub-command to access it in an interactive console: + +```bash +cql console 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io + INFO[0010] init config success path=~/.cql/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-da3af8f6-20190515152207) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Or access as `account2` (Should been granted access permission and transfered deposit token to the database successfully in last section): + +```bash +cql console -config "account2/config.yaml" 'covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5' +``` + +Output: + + INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io + INFO[0010] init config success path=~/.config/cql/account2/config.yaml + INFO[0010] connecting to "covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5" + Connected with driver covenantsql (develop-da3af8f6-20190515152207) + Type "help" for help. + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +Here is an example of using the interactive console: + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> create table t1 (c1 int); + CREATE TABLE + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> insert into t1 values (1), (2), (3); + INSERT + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> select * from t1; + c1 + ---- + 1 + 2 + 3 + (3 rows) + + co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> + + +## Sub-command `console` Complete Parameters + +The sub-command `console` also supports running `adapter` or `explorer` servers in the background. Check [Local Servers](#local-servers) for details. + + usage: cql console [common params] [Console params] dsn + + Console runs an interactive SQL console for CovenantSQL. + e.g. + cql console covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + There is also a -command param for SQL script, and you can add "< file.sql" at end of command for executing a SQL file. + If those params are set, it will run SQL script and exit without staying console mode. + e.g. + cql console -command "create table test1(test2 int);" covenantsql://4119ef997dedc585bfbcfae00ab6b87b8486fab323a8e107ea1fd4fc4f7eba5c + + Console params: + -adapter string + Address to serve a database chain adapter, e.g. :7784 + -command string + Run only single command (SQL or usql internal command) and exit + -explorer string + Address serve a database chain explorer, e.g. :8546 + -out string + Record stdout to file + -single-transaction + Execute as a single transaction (if non-interactive) + -variable value + Set variable \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.7.0/deploy_miner.md b/website/translated_docs/zh-CN/version-0.7.0/deploy_miner.md new file mode 100644 index 0000000..81f4f98 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.7.0/deploy_miner.md @@ -0,0 +1,372 @@ +--- +id: version-0.7.0-deploy_miner +title: Deploy custom miner +original_id: deploy_miner +--- + +## 部署 CovenantSQL Miner 节点 + +文档对应版本： + + cql HEAD-f0e4e13d-2019080103005 + covenantsql/covenantsql 1601418d1aef + + +### 环境依赖 + +#### 机器配置 + +推荐运行服务在 AWS 的 `c5.2xlarge` 型机器或其他同等配置的机器上 (8 核, 16 GB 内存)。 + +另外建议单独挂载数据盘用于 DB 存储。 + +#### Docker + +CovenantSQL 使用 docker 来简化部署，可通过 Docker 的 [官方文档](https://docs.docker.com/install/) 来进行安装。 + +#### Docker 镜像 + +使用 docker 获取 CovenantSQL 的服务镜像以提供数据存储节点服务 + +```shell +docker pull covenantsql/covenantsql:latest +``` + +### 配置服务 + +#### 生成 Miner 配置文件 + +执行以下命令在当前目录中创建一个 config 目录，并生成 Miner 启动所需的配置文件 `config.yaml` 和 私钥 `private.key` + +> 请将命令中的 `miner_external_ip` 和 `miner_listen_port` 替换成实际 miner 运行时对外提供服务的 ip 或域名以及端口号；需要注意的是，之后使用者的命令行客户端或 Adapter 都将使用这个地址连接 Miner，请确保这个地址在使用者的机器上可以访问（没有被云平台或其他防火墙限制访问）。可以使用 telnet 或者 nc 的形式在 Miner 启动后检查服务的可用性 + +```shell +docker run -it --rm -v $(pwd)/config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + generate -miner ":" /app/config/ +``` + +命令将会生成一个 miner 的配置文件和私钥，并在命令行中输出 Miner 的节点 id、公钥 hex 和 钱包地址，例如： + +```shel +Generated private key. +Generating nonce... +INFO cpu: 8 +INFO position: 3, shift: 0x20, i: 7 +INFO position: 1, shift: 0x20, i: 3 +INFO position: 3, shift: 0x0, i: 6 +INFO position: 2, shift: 0x0, i: 4 +INFO position: 2, shift: 0x20, i: 5 +INFO position: 0, shift: 0x0, i: 0 +INFO position: 1, shift: 0x0, i: 2 +INFO position: 0, shift: 0x20, i: 1 +nonce: {{2677734 0 6632872946 0} 26 0000003e2c8d0b39711edf19ef266a44996b93f7f830149f5d01491a6b7da99d} +node id: 0000003e2c8d0b39711edf19ef266a44996b93f7f830149f5d01491a6b7da99d +Generated nonce. +Generating config file... +Generated config. + +Config file: /Users/xq262144/.cql/config.yaml +Private key file: /Users/xq262144/.cql/private.key +Public key's hex: 0338816967be3c24bd490f841de57f2c42daf024dd7f462305aab9a601c423ab8d +Wallet address: eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451 + +Any further command could costs PTC. +You can get some free PTC from: + https://testnet.covenantsql.io/wallet/eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451 +``` + +可以得到 miner 的钱包地址：`eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451` + +#### 给 Miner 帐户充值 + +执行以下命令将会给 miner 的钱包地址转入 `10000000000` 个 `Particle` + +> 请将命令中的 `miner_wallet_address` 替换成上一步中生成的 miner 的钱包地址，例如上例中的 `eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451` + +```shell +mkdir -v ./testnet/ +curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql/develop/conf/testnet/config.yaml' -o ./testnet/config.yaml +curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql/develop/conf/testnet/private.key' -o ./testnet/private.key + +docker run -it --rm -v $(pwd)/testnet/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + transfer -config /app/config/config.yaml \ + -wait-tx-confirm -to-user "" \ + -amount 10000000000 \ + -token Particle +``` + +命令将会从测试网帐户中划转金额给 miner 使用，miner 后续将会使用这笔费用作为押金来提供服务，将会得到类似以下的输出： + +```shell +INFO[0000] Geting bp address from dns: bp04.testnet.gridb.io +INFO[0002] Register self to blockproducer: 00000000000589366268c274fdc11ec8bdb17e668d2f619555a2e9c1a29c91d8 +INFO init config success path=/app/config/config.yaml + + +INFO wait transaction confirmation error="" tx_hash=09001b9904194400e85018984c5428616000669e5de0efac0dc65c72f11950a2 tx_state=Confirmed +INFO succeed in sending transaction to CovenantSQL +``` + +查询 miner 的账户余额以确定转账成功 + +```shell +docker run -it --rm -v $(pwd)/config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + wallet -config ./config/config.yaml +``` + +将会得到类似以下的输出： + +```shell +INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io +INFO[0002] Register self to blockproducer: 0000000000293f7216362791b6b1c9772184d6976cb34310c42547735410186c +INFO init config success path=/app/config/config.yaml + + +wallet address: eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451 +Particle balance is: 100000000 +Wave balance is: 0 +``` + +Particle balance 这行输出中可以看到转账的金额，这样 miner 就可以提供服务了。 + +#### 添加 Miner 可服务的用户限制 + +在默认启动的情况下，Miner 是面向全网用户提供服务的。如果只希望给指定的 Miner 提供服务，需要在 Miner 上设置 TargetUsers 配置，并指定需要服务的用户的钱包地址。 + +修改 `miner` 的配置文件 `./config/config.yaml`，在 `Miner` 配置段下添加 `TargetUsers` 配置，指定一个需要服务的用户的 List，例如如下修改： + +```diff +--- old.yaml 2019-05-14 00:12:33.000000000 +0800 ++++ new.yaml 2019-05-14 00:12:19.000000000 +0800 +@@ -1,4 +1,5 @@ + Miner: + RootDir: './data' + MaxReqTimeGap: '5m' + ProvideServiceInterval: '10s' ++ TargetUsers: ['eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451'] +``` + +### 启动 Miner 服务 + +#### 创建 Container + +执行以下命令以创建 miner 的 + +> 请将下述命令中的 `miner_name` 替换成所需的 miner docker container 名用于管理；`data_disk_dir` 替换成用于存放 miner 数据的目录的绝对地址(推荐挂载一个盘用于提供服务)；`miner_listen_port` 替换成miner 对外提供服务的端口号 + +```shell +docker create --name "" \ + --restart always \ + -v $(pwd)/config/:/app/config/ \ + -v ":/app/config/data/" \ + -e COVENANT_ROLE=miner \ + -e COVENANT_CONF=/app/config/config.yaml \ + -e METRIC_WEB_ADDR=0.0.0.0:4665 \ + --log-driver "json-file" \ + --log-opt "max-size=1g" \ + --log-opt "max-file=3" \ + -p ":4661" \ + covenantsql/covenantsql:latest +``` + +#### 启动 Miner + +> 同样，请将 `miner_name` 替换为实际使用的 miner container 名 + +```shell +docker start "" +``` + +#### 检查 Miner 状态 + +> 同样，请将 `miner_name` 替换为实际使用的 miner container 名 + +```shell +docker ps -a -f "name = " +docker logs --tail=10 -f "" +``` + +在单台或多台机器上重复上述步骤，启动多个实例，可以提供至多对应节点数量的 DB SideChain 服务。 + +#### 服务升级 + +执行以下命令更新镜像，然后重复 **创建 Container** 步骤 和 **启动 Miner** 步骤 + +```shell + docker pull covenantsql/covenantsql:latest +``` + +### 使用 + +#### 使用者账户和配置 + +使用 CovenantSQL 需要创建一个 DB 使用者的账户。这个账户必须与提供服务的 Miner 节点的账号不同，与此同时一个 Miner 账户也不能同时启动多个 Miner 服务，否则将会导致 Miner 或 DB 使用者的 Transaction 执行异常，用户不能正确创建 DB 或 Miner 不能正确上报使用者的费用信息等。 + +##### 生成使用者账户配置 + +执行如下命令将在 `./client_config` 目录下生成使用者账户的私钥和配置 + +```shell +docker run -it --rm -v $(pwd)/client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + generate /app/config/ +``` + +##### 向使用者账户中充值 + +类似向 Miner 账户充值，请执行如下命令： + +> 请将 `client_wallet_address` 替换为创建的使用者账号的钱包地址 + +```shell +docker run -it --rm -v $(pwd)/testnet/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + transfer -config /app/config/config.yaml \ + -wait-tx-confirm -to-user "" \ + -amount 10000000000 \ + -token Particle +``` + +#### 创建 DB 和使用 + +由于需要在指定的 Miner 上创建 DB，需要在创建 DB 时指定提供服务的 Miner 列表 + +> `create` 命令接收一系列描述 DB 实例的参数，可以用 `cql help create` 查看详细参数；将 `node_count` 替换为所需的节点数量，例如 1 代表创建一个节点的 DB SideChain；`miner1_wallet_address, miner2_wallet_address` 等替换为指定 miner 的钱包地址列表；另外需要格外注意的时，所需创建的 DB SideChain 的节点数量需要小于或等于提供的指定 miner 数量，否则 CovenantSQL 会在指定 miner 之外的公用 miner 中随机分配节点以满足用户所需节点数量要求。 + +```shell +docker run -it --rm -v $(pwd)/client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + create -config /app/config/config.yaml -wait-tx-confirm \ + -db-node -db-target-miners ", , ..." +``` + +命令执行完成后将会有类似如下的输出： + +```shell +time="2019-05-07T03:41:03Z" level=info msg="Geting bp address from dns: bp04.testnet.gridb.io" +time="2019-05-07T03:41:05Z" level=info msg="Register self to blockproducer: 00000000003b2bd120a7d07f248b181fc794ba8b278f07f9a780e61eb77f6abb" +level=info msg="init config success" path=/root/.cql/config.yaml +level=info msg="create database requested" +The newly created database is: "covenantsql://163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df" +The connecting string beginning with 'covenantsql://' could be used as a dsn for `cql console` + or any command, or be used in website like https://web.covenantsql.io +``` + +其中 `covenantsql://163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df` 是数据库的连接串，可以在各类 SDK 或命令行工具中使用这个连接串访问数据库服务 + +#### 使用命令行工具连接数据库服务 + +可以是用 `cql` 工具提供的命令行功能访问数据库 + +> 将命令行中的 `dsn` 替换为上一步生成的数据库连接串 + +```shell +docker run -it --rm -v $(pwd)/client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + console -config /app/config/config.yaml "" +``` + +#### 启动 Adapter + +Java SDK 因为CovenantSQL 的 RPC 和网络连接协议的限制，不能直接访问 Miner 或 BlockProducer 节点，需要通过 Adapter 进行协议转换来访问。实际运行时，Java SDK/Adapter/Miner 是以如下图所示的形式交互的： + +```sequence +Java SDK ->Adapter: HTTP(s) Request +Adapter->Miner: ETLS RPC Request +Miner->Adapter: ETLS RPC Response +Adapter->Java SDK: HTTP(s) with JSON Response +``` + +可以通过如下命令启动 Adapter： + +> 请将命令中的 `adapter_name` 替换为所需的 adapter 的 docker container 名，将 `adapter_listen_port` 替换为所需暴露在物理机器上的端口号 + +```shell +docker run -d -v $(pwd)/client_config/:/app/config/ \ + -e COVENANT_ROLE=adapter \ + -e COVENANT_CONF=/app/config/config.yaml \ + -e COVENANTSQL_ADAPTER_ADDR=0.0.0.0:4661 \ + --name "" \ + --restart always \ + --log-driver "json-file" \ + --log-opt "max-size=1g" \ + --log-opt "max-file=3" \ + -p ":4661" \ + covenantsql/covenantsql:latest +``` + +启动后如果 adapter 的 docker container 运行正常，将可以通过 `http://localhost:/` 访问 adapter 并获取到 adapter 的版本信息 + +#### 使用 Java SDK + +参考 [CovenantSQL Java SDK Github](https://github.com/CovenantSQL/covenant-connector/tree/master/covenantsql-java-connector) 和 [CovenantSQL Java SDK 使用文档](https://developers.covenantsql.io/docs/en/driver_java) 通过 Adapter 访问 + +> 上一步启动的 Adapter 是运行在非 TLS 模式下的开发权限服务，任何访问 Adapter 的人都将以 Adapter 启动的账户（也就是 `./client_config` 中的私钥与配置）的权限访问数据库服务。 +> +> 在 Java SDK 中设置配置 `ssl=false`（因为 Adapter 运行在了非 TLS 模式下提供的 http 服务），并以 `jdbc:covenantsql://:/` 即可访问（请将 `adapter_host` 替换为实际的运行机器的域名或 IP，将 `adapter_listen_port` 替换为上一步中的监听端口号，`database_id` 替换为创建 DB 后返回的 `dsn` 中去除 `covenantsql://` scheme 的 hex 串部分，例如：`jdbc:covenantsql://127.0.0.1:11151/163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df`） + +#### 获取 Miner 节点的 metric 信息 + +Miner 提供了 metric 数据的导出接口，可以通过下述命令访问和导出： + +> 讲命令中的 `miner_name` 替换为 启动 miner 的 container 名 + +```shell +miner_internal_ip=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "" | head -1) +curl -s "http://${miner_internal_ip}:4665/debug/vars" +``` + +metric 信息对应表 + +| 字段名 | 含义 | +| ------------------------ | ----------------------------------------------------------------------- | +| service:miner:addr | 可访问的 Miner 的外部地址和端口（配置中的 ListenAddr） | +| service:miner:node | Miner 的 DHT 网络节点 ID | +| service:miner:wallet | Miner 的 钱包地址 | +| service:miner:disk:root | Miner 的 数据目录地址 | +| service:miner:disk:usage | Miner 使用的磁盘空间（KB） | +| service:miner:db:count | Miner 上正在提供服务的 ShardChain 数量 | +| service:miner:chain | Miner 上所有 ShardChain 统计信息，类型是一个 Map Map 的 key 是 ShardChain 的 DatabaseID | + + +针对每个 ShardChain 的统计信息，有如下字段 + +| 字段 | 含义 | +| -------------- | ------------------------------- | +| head:count | Chain 最新 Block 的编号（第几个块） | +| head:height | Chain 最新 Block 的 Epoch（第几个出块周期） | +| head:hash | Chain 最新 Block 的 Hash | +| head:timestamp | Chain 最新 Block 的产生时间（UTC） | +| requests:count | 最近 5 分钟统计范围内，1m 的请求数的平均值 | + + +#### 查看 Miner 节点上某个 DB Chain 的块信息 + +CovenantSQL 提供了一个方便的 Explorer 来展示数据库子链上的块信息，可以在通过如下命令启动 Explorer： + +> 其中替换 `explorer_name` 为想要运行 explorer 的 docker container 名，`explorer_listen_port` 替换为所需暴露在物理机器上的端口号 + +```shell +docker run -d -v $(pwd)/client_config/:/app/config/ \ + -e COVENANT_ROLE=observer \ + -e COVENANT_CONF=/app/config/config.yaml \ + -e COVENANTSQL_OBSERVER_ADDR=0.0.0.0:4661 \ + --name "" \ + --restart always \ + --log-driver "json-file" \ + --log-opt "max-size=1g" \ + --log-opt "max-file=3" \ + -p ":" \ + covenantsql/covenantsql:latest +``` + +启动在浏览器里访问 `http://:/dbs/` + +> 其中 `explorer_external_address` 替换为物理机的外网 IP，`explorer_listen_port` 替换为上一步中指定的端口， `database_id` 替换为创建 DB 后返回的 `dsn` 中去除 `covenantsql://` scheme 的 hex 串部分，例如：`http://miner_machine:11106/dbs/163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df` + +稍后等待块同步，即可在页面中看到历史产生的 Block，点击 Block 可以看到 Block 上承载的历史查询过的 Query 情况（如果没有自动出现块的信息，可以尝试手动刷新） + +> CovenantSQL 有严格的权限控制，需要对数据库有读权限的人才能使用 Explorer 看到这些 Query 历史和 Block 信息 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.7.0/quickstart.md b/website/translated_docs/zh-CN/version-0.7.0/quickstart.md new file mode 100644 index 0000000..8dc8d9f --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.7.0/quickstart.md @@ -0,0 +1,184 @@ +--- +id: version-0.7.0-quickstart +title: Quick Start +original_id: quickstart +--- + + +## CovenantSQL Client + +### Install + +Please choose the installation method according to the operating system platform you use: + +#### MacOS + +- 🍺 Homebrew users can just run: + + ```bash + brew install cql + ``` + +- non-Homebrew users can run: + + ```bash + sudo bash -c 'curl -L "https://mac.gridb.io/cql" | \ + tar xzv -C /usr/local/bin/ --strip-components=1' + ``` + +#### Linux + +- Just run： + + ```bash + sudo bash -c 'curl -L "https://linux.gridb.io/cql" | \ + tar xzv -C /usr/local/bin/ --strip-components=1' + ``` + +After the installation is complete, you can execute the following command to check whether the installation is successful. + +```bash +cql version +``` + +If you have any errors on the MacOS or Linux, you can try the following to fix it: + +```bash +sudo chmod a+x /usr/local/bin/cql* # Fix Permission +sudo ln -s /usr/local/bin/cql* /usr/bin/ # Fix if /usr/local/bin not in $PATH +``` + +If the problem persists please check out our GitHub page [submit issue](https://github.com/CovenantSQL/CovenantSQL/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D) + +### Utils + +| Tool | Introduction | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| cql | CovenantSQL client, `cql console` command is similar to the `mysql` command and is used to manage the CQL databases, [More](./cql_intro) | +| cql-fuse | CovenantSQL's FUSE client, which can mount a CovenantSQL database as a file system | +| cql-minerd | CovenantSQL miner client, used to run the database to earn rewards, will open later | +| cqld | CovenantSQL main chain node, mainly run by CovenantLabs and partners in DPoS mode | + +> Windows platform we will release later, if there is a need please [submit issue](https://github.com/CovenantSQL/CovenantSQL/issues/new?assignees=&labels=&template=feature_request.md&title=) + +### TestNet + +At present, we have released the test network v0.7.0 for everyone to verify and experience the principle. You can choose to quickly perform access testing using the "public account". + +The configuration file and private key of the "public account":[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) (empty password)，or just run： + +```bash +mkdir -p ~/.cql/testnet-conf +curl -L https://git.io/fhFZe --output ~/.cql/testnet-conf/config.yaml +curl -L https://git.io/fhFZv --output ~/.cql/testnet-conf/private.key +chmod 600 ~/.cql/testnet-conf/private.key +``` + +**TestNet Notes**： + +> The "public account" is public and only for testing. Please do not store your application information in the database created by the "public account". We will clean the database data from time to time. +> +> The test network is temporarily composed of 3 Miners, so temporarily only supports `create 3` to create a database of 3 nodes. + +## Create a testnet database + +```bash +cql create -config=~/.cql/testnet-conf/config.yaml \ + -db-node 1 -wait-tx-confirm +``` + +The command execution takes a little long time, and after about 30 seconds the console outputs something like below: + +> covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + +​ + +This means that you submitted the database(dsn) `covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` creation request to the main chain and created the database to complete. + +> Command execution takes some time, and the general process is: +> +> 1. The "Block Producer" that received the request performs a match of Miner and database creation requests. +> 2. Database creation request is verified and confirmed at other "Block Producer" nodes +> 3. Eligible Miner on SQLChain receives database task +> 4. SQLChain Miners builds a database cluster with Kayak +> 5. All Miners are ready to wait for a database request + +## Access the testnet database + +```bash +cql console -config=~/.cql/testnet-conf/config.yaml \ + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +After connecting to the database, you can manipulate the database on CovenantSQL according to your habit of operating the database. For example, execute `CREATE TABLE` to create a table, `SELECT` query data, and so on. + +## SQLChain Explorer + +One feature of CovenantSQL is that its query records are **immutable and traceable**, you can query the operation of a database through \[Test Web Block Browser\] (https://explorer.dbhub.org/) recording. + +> The TestNet's SQLChain Explorer is currently open-access, and anyone who knows the database ID can manipulate your data using TestNet's public key. + +Please fill in your database ID in the upper right corner of the page. For example: `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872`. You can see information about all the data created using TestNet's Key: + +![explorer](https://github.com/CovenantSQL/docs/raw/master/website/static/img/explorer.png) + +> **If you want to create your own private database, you need to create a new public-private key pair from scratch, please refer to the following section.** + +## Create your own account + +Our test network allows you to create your own account and create a database under your own account. Create an account with the following command (default empty passphrase for private.key, you can add `-with-password` to set passphrase)： + +```bash +cql generate +``` + +Output： + + Generating private key... + Please enter password for new private key + Generated private key. + Generating nonce... + INFO cpu: 4 + INFO position: 2, shift: 0x0, i: 2 + INFO position: 0, shift: 0x0, i: 0 + INFO position: 3, shift: 0x0, i: 3 + INFO position: 1, shift: 0x0, i: 1 + nonce: {{973366 0 586194564 0} 26 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b} + node id: 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b + Generated nonce. + Generating config file... + Generated config. + + Config file: ~/.cql/config.yaml + Private key file: ~/.cql/private.key + Public key's hex: 03f195dfe6237691e724bcf54359d76ef388b0996a3de94a7e782dac69192c96f0 + + Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + Any further command could costs PTC. + You can get some free PTC from: + https://testnet.covenantsql.io/wallet/dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + +This command will create a `.cql` directory for you in your `$HOME` directory: + +- `~/.cql/private.key`: The generated private key is stored in the file by the master password encryption, and your account address needs to be created using this file; +- `~/.cql/config.yaml`: The generated configuration, cql can access the CovenantSQL TestNet with it. + +It alse print your wallet address(also called the account address, CovenantSQL address): `Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95` + +You can get the test PTC here with the wallet address obtained above: \[Request for PTC\] (https://testnet.covenantsql.io/). + +After up to 2 minutes while requested PTC, you can use the cql command line tool to check the balance: + +```bash +cql wallet +``` + +output： + + Particle balance is: 10000000 + Wave balance is: 0 + + +Congratulations, you have received our PTC stable currency, and you can start using CovenantSQL now. You can refer to [Golang uses CovenantSQL documentation](./driver_golang) for development. \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.8.0/deploy_miner.md b/website/translated_docs/zh-CN/version-0.8.0/deploy_miner.md new file mode 100644 index 0000000..2cf6180 --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.8.0/deploy_miner.md @@ -0,0 +1,407 @@ +--- +id: version-0.8.0-deploy_miner +title: Deploy custom miner +original_id: deploy_miner +--- + +## 部署 CovenantSQL Miner 节点 + +文档对应版本： + + covenantsql/covenantsql e87bfd412293 + + +本教程可以为中国测试网(testnet cn)或者国外测试网(testnet w) 部署 miner 节点，注意区分网络环境。 + +本教程在当前目录(`$PWD`) 会产生三个目录，分别是： + + miner_config: 您自己的 miner 节点配置 + super_client_config: 测试网超级客户端配置 + client_config: 您 miner 的使用者客户端配置 + + +各个命令都会使用上述配置之一，代表了命令的执行角色。 + +### 环境依赖 + +#### 机器配置 + +推荐运行服务在 AWS 的 `c5.2xlarge` 型机器或其他同等配置的机器上 (8 核, 16 GB 内存)。 + +另外建议单独挂载数据盘用于 DB 存储。 + +#### Docker + +CovenantSQL 使用 docker 来简化部署，可通过 Docker 的 [官方文档](https://docs.docker.com/install/) 来进行安装。 + +#### Docker 镜像 + +使用 docker 获取 CovenantSQL 的服务镜像以提供数据存储节点服务 + +```shell +docker pull covenantsql/covenantsql:latest +``` + +### 配置服务 + +#### 生成 Miner 配置文件 + +执行以下命令在当前目录中创建一个 miner_config 目录，并生成 Miner 启动所需的配置文件 `config.yaml` 和 私钥 `private.key` + +> 请将命令中的 `miner_external_ip` 和 `miner_listen_port` 替换成实际 miner 运行时对外提供服务的 ip 或域名以及端口号；需要注意的是，之后使用者的命令行客户端或 Adapter 都将使用这个地址连接 Miner，请确保这个地址在使用者的机器上可以访问（没有被云平台或其他防火墙限制访问）。可以使用 telnet 或者 nc 的形式在 Miner 启动后检查服务的可用性 + +```shell +mkdir -v ./miner_config + +docker run -it --rm -v $(pwd)/miner_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + generate -miner ":" /app/config/ +``` + +> 如果需要生成国外区测试网配置，将上述命令的 `generate` 后面增加 `-testnet w` 参数。并且注意下述第一行输出会变成 `Generating testnet w config` + +命令将会生成一个 miner 的配置文件和私钥，并在命令行中输出 Miner 的节点 id、公钥 hex 和 钱包地址，例如： + +```shell +Generating testnet cn config +Generated private key. +Generating nonce... +INFO cpu: 8 +INFO position: 3, shift: 0x20, i: 7 +INFO position: 1, shift: 0x20, i: 3 +INFO position: 3, shift: 0x0, i: 6 +INFO position: 2, shift: 0x0, i: 4 +INFO position: 2, shift: 0x20, i: 5 +INFO position: 0, shift: 0x0, i: 0 +INFO position: 1, shift: 0x0, i: 2 +INFO position: 0, shift: 0x20, i: 1 +nonce: {{2677734 0 6632872946 0} 26 0000003e2c8d0b39711edf19ef266a44996b93f7f830149f5d01491a6b7da99d} +node id: 0000003e2c8d0b39711edf19ef266a44996b93f7f830149f5d01491a6b7da99d +Generated nonce. +Generating config file... +Generated config. + +Config file: /app/config/config.yaml +Private key file: /app/config/private.key +Public key's hex: 0338816967be3c24bd490f841de57f2c42daf024dd7f462305aab9a601c423ab8d +Wallet address: eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451 + +Any further command could costs PTC. +You can get some free PTC from: + https://testnet.covenantsql.io/wallet/eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451 +``` + +可以得到 miner 的钱包地址：`eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451` + +#### 给 Miner 帐户充值 + +为了大家使用方便，我们创建了一个公共使用的超级客户端节点，拥有大量测试余额，首先需要下载这个超级客户端节点的配置： + +国内测试网： + +```shell +mkdir -v ./super_client_config/ +curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql/develop/conf/testnet/config.yaml' -o ./super_client_config/config.yaml +curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql/develop/conf/testnet/private.key' -o ./super_client_config/private.key +``` + +国外测试网： + +```shell +mkdir -v ./super_client_config/ +curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql/develop/conf/testnet/w/config.yaml' -o ./super_client_config/config.yaml +curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql/develop/conf/testnet/w/private.key' -o ./super_client_config/private.key +``` + +执行以下命令将会给 miner 的钱包地址转入 `10000000000` 个 `Particle` + +> 请将命令中的 `miner_wallet_address` 替换成上一步中生成的 miner 的钱包地址，例如上例中的 `eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451` + +```shell +docker run -it --rm -v $(pwd)/super_client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + transfer -config /app/config/config.yaml \ + -wait-tx-confirm -to-user "" \ + -amount 10000000000 \ + -token Particle +``` + +命令将会从测试网帐户中划转金额给 miner 使用，miner 后续将会使用这笔费用作为押金来提供服务，将会得到类似以下的输出： + +```shell +INFO[0000] Geting bp address from dns: bp04.testnet.gridb.io +INFO[0002] Register self to blockproducer: 00000000000589366268c274fdc11ec8bdb17e668d2f619555a2e9c1a29c91d8 +INFO init config success path=/app/config/config.yaml + + +INFO wait transaction confirmation error="" tx_hash=09001b9904194400e85018984c5428616000669e5de0efac0dc65c72f11950a2 tx_state=Confirmed +INFO succeed in sending transaction to CovenantSQL +``` + +查询 miner 的账户余额以确定转账成功 + +```shell +docker run -it --rm -v $(pwd)/miner_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + wallet -config ./config/config.yaml +``` + +将会得到类似以下的输出： + +```shell +INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io +INFO[0002] Register self to blockproducer: 0000000000293f7216362791b6b1c9772184d6976cb34310c42547735410186c +INFO init config success path=/app/config/config.yaml + + +wallet address: eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451 +Particle balance is: 100000000 +Wave balance is: 0 +``` + +Particle balance 这行输出中可以看到转账的金额，这样 miner 就可以提供服务了。 + +#### 添加 Miner 可服务的用户限制 + +在默认启动的情况下，Miner 是面向全网用户提供服务的。如果只希望给指定的 Miner 提供服务，需要在 Miner 上设置 TargetUsers 配置，并指定需要服务的用户的钱包地址。 + +修改 `miner` 的配置文件 `./miner_config/config.yaml`，在 `Miner` 配置段下添加 `TargetUsers` 配置，指定一个需要服务的用户的 List，例如如下修改： + +```diff +--- old.yaml 2019-05-14 00:12:33.000000000 +0800 ++++ new.yaml 2019-05-14 00:12:19.000000000 +0800 +@@ -1,4 +1,5 @@ + Miner: + RootDir: './data' + MaxReqTimeGap: '5m' + ProvideServiceInterval: '10s' ++ TargetUsers: ['eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451'] +``` + +### 启动 Miner 服务 + +#### 创建 Container + +执行以下命令以创建 miner 的 + +> 请将下述命令中的 `miner_name` 替换成所需的 miner docker container 名用于管理；`data_disk_dir` 替换成用于存放 miner 数据的目录的绝对地址(推荐挂载一个盘用于提供服务)；`miner_listen_port` 替换成miner 对外提供服务的端口号 + +```shell +docker create --name "" \ + --restart always \ + -v $(pwd)/miner_config/:/app/config/ \ + -v ":/app/config/data/" \ + -e COVENANT_ROLE=miner \ + -e COVENANT_CONF=/app/config/config.yaml \ + -e METRIC_WEB_ADDR=0.0.0.0:4665 \ + --log-driver "json-file" \ + --log-opt "max-size=1g" \ + --log-opt "max-file=3" \ + -p ":" \ + covenantsql/covenantsql:latest +``` + +#### 启动 Miner + +> 同样，请将 `miner_name` 替换为实际使用的 miner container 名 + +```shell +docker start "" +``` + +#### 检查 Miner 状态 + +> 同样，请将 `miner_name` 替换为实际使用的 miner container 名 + +```shell +docker ps -a -f "name = " +docker logs --tail=10 -f "" +``` + +在单台或多台机器上重复上述步骤，启动多个实例，可以提供至多对应节点数量的 DB SideChain 服务。 + +#### 服务升级 + +执行以下命令更新镜像，然后重复 **创建 Container** 步骤 和 **启动 Miner** 步骤 + +```shell + docker pull covenantsql/covenantsql:latest +``` + +### 使用 + +#### 使用者账户和配置 + +使用 CovenantSQL 需要创建一个 DB 使用者的账户。这个账户必须与提供服务的 Miner 节点的账号不同，与此同时一个 Miner 账户也不能同时启动多个 Miner 服务，否则将会导致 Miner 或 DB 使用者的 Transaction 执行异常，用户不能正确创建 DB 或 Miner 不能正确上报使用者的费用信息等。 + +##### 生成使用者账户配置 + +执行如下命令将在 `./client_config` 目录下生成使用者账户的私钥和配置 + +> 如果需要生成国外区测试网配置，将上述命令的 `generate` 后面增加 `-testnet w` 参数。并且注意第一行输出会变成 `Generating testnet w config` + +```shell +mkdir -v client_config + +docker run -it --rm -v $(pwd)/client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + generate /app/config/ +``` + +命令最后一行会显示 wallet address，注意需要将此 wallet address 加入到 miner 的 `TargetUsers` 配置中，并重启 miner。 + +##### 向使用者账户中充值 + +类似向 Miner 账户充值，请执行如下命令： + +> 请将 `client_wallet_address` 替换为创建的使用者账号的钱包地址 + +```shell +docker run -it --rm -v $(pwd)/super_client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + transfer -config /app/config/config.yaml \ + -wait-tx-confirm -to-user "" \ + -amount 10000000000 \ + -token Particle +``` + +#### 创建 DB 和使用 + +由于需要在指定的 Miner 上创建 DB，需要在创建 DB 时指定提供服务的 Miner 列表 + +> `create` 命令接收一系列描述 DB 实例的参数，可以用 `cql help create` 查看详细参数；将 `node_count` 替换为所需的节点数量，例如 1 代表创建一个节点的 DB SideChain；`miner1_wallet_address, miner2_wallet_address` 等替换为指定 miner 的钱包地址列表；另外需要格外注意的时，所需创建的 DB SideChain 的节点数量需要小于或等于提供的指定 miner 数量，否则 CovenantSQL 会在指定 miner 之外的公用 miner 中随机分配节点以满足用户所需节点数量要求。 + +```shell +docker run -it --rm -v $(pwd)/client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + create -config /app/config/config.yaml -wait-tx-confirm \ + -db-node -db-target-miners ", , ..." +``` + +命令执行完成后将会有类似如下的输出： + +```shell +time="2019-05-07T03:41:03Z" level=info msg="Geting bp address from dns: bp04.testnet.gridb.io" +time="2019-05-07T03:41:05Z" level=info msg="Register self to blockproducer: 00000000003b2bd120a7d07f248b181fc794ba8b278f07f9a780e61eb77f6abb" +level=info msg="init config success" path=/root/.cql/config.yaml +level=info msg="create database requested" +The newly created database is: "covenantsql://163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df" +The connecting string beginning with 'covenantsql://' could be used as a dsn for `cql console` + or any command, or be used in website like https://web.covenantsql.io +``` + +其中 `covenantsql://163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df` 是数据库的连接串，可以在各类 SDK 或命令行工具中使用这个连接串访问数据库服务 + +#### 使用命令行工具连接数据库服务 + +可以是用 `cql` 工具提供的命令行功能访问数据库 + +> 将命令行中的 `dsn` 替换为上一步生成的数据库连接串 + +```shell +docker run -it --rm -v $(pwd)/client_config/:/app/config/ \ + --entrypoint /app/cql covenantsql/covenantsql:latest -- \ + console -config /app/config/config.yaml "" +``` + +#### 启动 Adapter + +Java SDK 因为CovenantSQL 的 RPC 和网络连接协议的限制，不能直接访问 Miner 或 BlockProducer 节点，需要通过 Adapter 进行协议转换来访问。实际运行时，Java SDK/Adapter/Miner 是以如下图所示的形式交互的： + +```sequence +Java SDK ->Adapter: HTTP(s) Request +Adapter->Miner: ETLS RPC Request +Miner->Adapter: ETLS RPC Response +Adapter->Java SDK: HTTP(s) with JSON Response +``` + +可以通过如下命令启动 Adapter： + +> 请将命令中的 `adapter_name` 替换为所需的 adapter 的 docker container 名，将 `adapter_listen_port` 替换为所需暴露在物理机器上的端口号 + +```shell +docker run -d -v $(pwd)/client_config/:/app/config/ \ + -e COVENANT_ROLE=adapter \ + -e COVENANT_CONF=/app/config/config.yaml \ + -e COVENANTSQL_ADAPTER_ADDR=0.0.0.0:4661 \ + --name "" \ + --restart always \ + --log-driver "json-file" \ + --log-opt "max-size=1g" \ + --log-opt "max-file=3" \ + -p ":4661" \ + covenantsql/covenantsql:latest +``` + +启动后如果 adapter 的 docker container 运行正常，将可以通过 `http://localhost:/` 访问 adapter 并获取到 adapter 的版本信息 + +#### 使用 Java SDK + +参考 [CovenantSQL Java SDK Github](https://github.com/CovenantSQL/covenant-connector/tree/master/covenantsql-java-connector) 和 [CovenantSQL Java SDK 使用文档](https://developers.covenantsql.io/docs/en/driver_java) 通过 Adapter 访问 + +> 上一步启动的 Adapter 是运行在非 TLS 模式下的开发权限服务，任何访问 Adapter 的人都将以 Adapter 启动的账户（也就是 `./client_config` 中的私钥与配置）的权限访问数据库服务。 +> +> 在 Java SDK 中设置配置 `ssl=false`（因为 Adapter 运行在了非 TLS 模式下提供的 http 服务），并以 `jdbc:covenantsql://:/` 即可访问（请将 `adapter_host` 替换为实际的运行机器的域名或 IP，将 `adapter_listen_port` 替换为上一步中的监听端口号，`database_id` 替换为创建 DB 后返回的 `dsn` 中去除 `covenantsql://` scheme 的 hex 串部分，例如：`jdbc:covenantsql://127.0.0.1:11151/163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df`） + +#### 获取 Miner 节点的 metric 信息 + +Miner 提供了 metric 数据的导出接口，可以通过下述命令访问和导出： + +> 讲命令中的 `miner_name` 替换为 启动 miner 的 container 名 + +```shell +miner_internal_ip=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "" | head -1) +curl -s "http://${miner_internal_ip}:4665/debug/vars" +``` + +metric 信息对应表 + +| 字段名 | 含义 | +| ------------------------ | ----------------------------------------------------------------------- | +| service:miner:addr | 可访问的 Miner 的外部地址和端口（配置中的 ListenAddr） | +| service:miner:node | Miner 的 DHT 网络节点 ID | +| service:miner:wallet | Miner 的 钱包地址 | +| service:miner:disk:root | Miner 的 数据目录地址 | +| service:miner:disk:usage | Miner 使用的磁盘空间（KB） | +| service:miner:db:count | Miner 上正在提供服务的 ShardChain 数量 | +| service:miner:chain | Miner 上所有 ShardChain 统计信息，类型是一个 Map Map 的 key 是 ShardChain 的 DatabaseID | + + +针对每个 ShardChain 的统计信息，有如下字段 + +| 字段 | 含义 | +| -------------- | ------------------------------- | +| head:count | Chain 最新 Block 的编号（第几个块） | +| head:height | Chain 最新 Block 的 Epoch（第几个出块周期） | +| head:hash | Chain 最新 Block 的 Hash | +| head:timestamp | Chain 最新 Block 的产生时间（UTC） | +| requests:count | 最近 5 分钟统计范围内，1m 的请求数的平均值 | + + +#### 查看 Miner 节点上某个 DB Chain 的块信息 + +CovenantSQL 提供了一个方便的 Explorer 来展示数据库子链上的块信息，可以在通过如下命令启动 Explorer： + +> 其中替换 `explorer_name` 为想要运行 explorer 的 docker container 名，`explorer_listen_port` 替换为所需暴露在物理机器上的端口号 + +```shell +docker run -d -v $(pwd)/client_config/:/app/config/ \ + -e COVENANT_ROLE=explorer \ + -e COVENANT_CONF=/app/config/config.yaml \ + -e COVENANTSQL_OBSERVER_ADDR=0.0.0.0:4661 \ + --name "" \ + --restart always \ + --log-driver "json-file" \ + --log-opt "max-size=1g" \ + --log-opt "max-file=3" \ + -p ":4661" \ + covenantsql/covenantsql:latest +``` + +启动在浏览器里访问 `http://:/dbs/` + +> 其中 `explorer_external_address` 替换为物理机的外网 IP，`explorer_listen_port` 替换为上一步中指定的端口， `database_id` 替换为创建 DB 后返回的 `dsn` 中去除 `covenantsql://` scheme 的 hex 串部分，例如：`http://miner_machine:11106/dbs/163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df` + +稍后等待块同步，即可在页面中看到历史产生的 Block，点击 Block 可以看到 Block 上承载的历史查询过的 Query 情况（如果没有自动出现块的信息，可以尝试手动刷新） + +> CovenantSQL 有严格的权限控制，需要对数据库有读权限的人才能使用 Explorer 看到这些 Query 历史和 Block 信息 \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.8.0/driver_java.md b/website/translated_docs/zh-CN/version-0.8.0/driver_java.md new file mode 100644 index 0000000..95df21e --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.8.0/driver_java.md @@ -0,0 +1,53 @@ +--- +id: version-0.8.0-driver_java +title: Java +original_id: driver_java +--- + +## Use Java to access CovenantSQL + +`CovenantSQL` provides `Java SDK` to access database instance through [`Adapter`](./adapter) service. + +`Java SDK` is compatible with `JDBC4` specifications，and popular `ORM` like `MyBatis` is supported through JDBC interface. + +### Compatibility + +`Java SDK` requires `Java 1.7+`. + +### Installation and quick start + +Before using `Java SDK`, an adapter tool deployment is required, please see [Deploy Adapter Service](./adapter). + +Now you can use `jdbc:covenantsql:///` uri，replacing `adapter_endpoint` with adapter listen address，`database_id` with database id。 + +#### Maven + +```xml + + + io.covenantsql + cql-java-connector + 1.0.1 + + +``` + +#### Gradle + +```gradle +repositories { + maven { + url 'https://raw.github.com/CovenantSQL/cql-java-driver/mvn-repo' + } +} + +dependencies { + compile 'io.covenantsql:covenantsql-java-connector:1.0-SNAPSHOT' +} +``` + +### Examples + +1. [JDBC Example](https://github.com/CovenantSQL/cql-java-driver/blob/master/example/src/main/java/io/covenantsql/connector/example/jdbc/Example.java) +2. [MyBatis Example](https://github.com/CovenantSQL/cql-java-driver/blob/master/example/src/main/java/io/covenantsql/connector/example/mybatis/Example.java) +3. [SpringBoot + MyBatis Project Example](https://github.com/CovenantSQL/covenantsql-mybatis-spring-boot-jpetstore) \ No newline at end of file diff --git a/website/translated_docs/zh-CN/version-0.8.0/quickstart.md b/website/translated_docs/zh-CN/version-0.8.0/quickstart.md new file mode 100644 index 0000000..560fd5a --- /dev/null +++ b/website/translated_docs/zh-CN/version-0.8.0/quickstart.md @@ -0,0 +1,184 @@ +--- +id: version-0.8.0-quickstart +title: Quick Start +original_id: quickstart +--- + + +## CovenantSQL Client + +### Install + +Please choose the installation method according to the operating system platform you use: + +#### MacOS + +- 🍺 Homebrew users can just run: + + ```bash + brew install cql + ``` + +- non-Homebrew users can run: + + bash + sudo bash -c 'curl -L "https://mac.gridb.io/cql" | \ + tar xzv -C /usr/local/bin/ --strip-components=1' + +#### Linux + +- Just run： + + ```bash + sudo bash -c 'curl -L "https://linux.gridb.io/cql" | \ + tar xzv -C /usr/local/bin/ --strip-components=1' + ``` + +After the installation is complete, you can execute the following command to check whether the installation is successful. + +```bash +cql version +``` + +If you have any errors on the MacOS or Linux, you can try the following to fix it: + +```bash +sudo chmod a+x /usr/local/bin/cql* # Fix Permission +sudo ln -s /usr/local/bin/cql* /usr/bin/ # Fix if /usr/local/bin not in $PATH +``` + +If the problem persists please check out our GitHub page [submit issue](https://github.com/CovenantSQL/CovenantSQL/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D) + +### Utils + +| Tool | Introduction | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| cql | CovenantSQL client, `cql console` command is similar to the `mysql` command and is used to manage the CQL databases, [More](./cql_intro) | +| cql-fuse | CovenantSQL's FUSE client, which can mount a CovenantSQL database as a file system | +| cql-minerd | CovenantSQL miner client, used to run the database to earn rewards, will open later | +| cqld | CovenantSQL main chain node, mainly run by CovenantLabs and partners in DPoS mode | + + +> Windows platform we will release later, if there is a need please [submit issue](https://github.com/CovenantSQL/CovenantSQL/issues/new?assignees=&labels=&template=feature_request.md&title=) + +### TestNet + +At present, we have released the test network v0.8.0 for everyone to verify and experience the principle. You can choose to quickly perform access testing using the "public account". + +The configuration file and private key of the "public account":[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) (empty password)，or just run： + +```bash +mkdir -p ~/.cql/testnet-conf +curl -L https://git.io/fhFZe --output ~/.cql/testnet-conf/config.yaml +curl -L https://git.io/fhFZv --output ~/.cql/testnet-conf/private.key +chmod 600 ~/.cql/testnet-conf/private.key +``` + +**TestNet Notes**： + +> The "public account" is public and only for testing. Please do not store your application information in the database created by the "public account". We will clean the database data from time to time. +> +> The test network is temporarily composed of 3 Miners, so temporarily only supports `create 3` to create a database of 3 nodes. + +## Create a testnet database + +```bash +cql create -config=~/.cql/testnet-conf/config.yaml \ + -db-node 1 -wait-tx-confirm +``` + +The command execution takes a little long time, and after about 30 seconds the console outputs something like below: + +> covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 + +​ + +This means that you submitted the database(dsn) `covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872` creation request to the main chain and created the database to complete. + +> Command execution takes some time, and the general process is: +> +> 1. The "Block Producer" that received the request performs a match of Miner and database creation requests. +> 2. Database creation request is verified and confirmed at other "Block Producer" nodes +> 3. Eligible Miner on SQLChain receives database task +> 4. SQLChain Miners builds a database cluster with Kayak +> 5. All Miners are ready to wait for a database request + +## Access the testnet database + +```bash +cql console -config=~/.cql/testnet-conf/config.yaml \ + covenantsql://0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872 +``` + +After connecting to the database, you can manipulate the database on CovenantSQL according to your habit of operating the database. For example, execute `CREATE TABLE` to create a table, `SELECT` query data, and so on. + +## SQLChain Explorer + +One feature of CovenantSQL is that its query records are **immutable and traceable**, you can query the operation of a database through \[Test Web Block Browser\] (https://explorer.dbhub.org/) recording. + +> The TestNet's SQLChain Explorer is currently open-access, and anyone who knows the database ID can manipulate your data using TestNet's public key. + +Please fill in your database ID in the upper right corner of the page. For example: `0a10b74439f2376d828c9a70fd538dac4b69e0f4065424feebc0f5dbc8b34872`. You can see information about all the data created using TestNet's Key: + +![explorer](https://github.com/CovenantSQL/docs/raw/master/website/static/img/explorer.png) + +> **If you want to create your own private database, you need to create a new public-private key pair from scratch, please refer to the following section.** + +## Create your own account + +Our test network allows you to create your own account and create a database under your own account. Create an account with the following command (default empty passphrase for private.key, you can add `-with-password` to set passphrase)： + +```bash +cql generate +``` + +Output： + + Generating private key... + Please enter password for new private key + Generated private key. + Generating nonce... + INFO cpu: 4 + INFO position: 2, shift: 0x0, i: 2 + INFO position: 0, shift: 0x0, i: 0 + INFO position: 3, shift: 0x0, i: 3 + INFO position: 1, shift: 0x0, i: 1 + nonce: {{973366 0 586194564 0} 26 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b} + node id: 0000002c32aa3ee39e4f461a5f5e7fda50859f597464d81c9618d443c476835b + Generated nonce. + Generating config file... + Generated config. + + Config file: ~/.cql/config.yaml + Private key file: ~/.cql/private.key + Public key's hex: 03f195dfe6237691e724bcf54359d76ef388b0996a3de94a7e782dac69192c96f0 + + Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + Any further command could costs PTC. + You can get some free PTC from: + https://testnet.covenantsql.io/wallet/dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95 + + +This command will create a `.cql` directory for you in your `$HOME` directory: + +- `~/.cql/private.key`: The generated private key is stored in the file by the master password encryption, and your account address needs to be created using this file; +- `~/.cql/config.yaml`: The generated configuration, cql can access the CovenantSQL TestNet with it. + +It alse print your wallet address(also called the account address, CovenantSQL address): `Wallet address: dbb7d1ee90452b8ee9cf514540b8d14fe5b7a750cc0c2f3824db6c8b284ada95` + +You can get the test PTC here with the wallet address obtained above: \[Request for PTC\] (https://testnet.covenantsql.io/). + +After up to 2 minutes while requested PTC, you can use the cql command line tool to check the balance: + +```bash +cql wallet +``` + +output： + + Particle balance is: 10000000 + Wave balance is: 0 + + +Congratulations, you have received our PTC stable currency, and you can start using CovenantSQL now. You can refer to [Golang uses CovenantSQL documentation](./driver_golang) for development. \ No newline at end of file