update docs

main
Ziyang Hu 2 years ago
parent cc7f6ccbd3
commit 285c9a57ad

@ -168,19 +168,19 @@ end[] <- [['YPO]]
Cozo 可以安装在一大堆不同的语言与环境中: Cozo 可以安装在一大堆不同的语言与环境中:
| 语言/环境 | 官方支持的平台 | 存储引擎 | | 语言/环境 | 官方支持的平台 | 存储引擎 |
|-------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------| |-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------|
| [Python](https://github.com/cozodb/pycozo) | Linux (x86_64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | | [Python](https://github.com/cozodb/pycozo)[国内镜像](https://gitee.com/cozodb/pycozo) | Linux (x86_64), Mac (ARM64, x86_64), Windows (x86_64) | MQR |
| [NodeJS](./cozo-lib-nodejs) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | | [NodeJS](./cozo-lib-nodejs) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR |
| [浏览器](./cozo-lib-wasm) | 支持[WASM](https://developer.mozilla.org/en-US/docs/WebAssembly#browser_compatibility)的浏览器(较新的浏览器全都支持) | M | | [浏览器](./cozo-lib-wasm) | 支持[WASM](https://developer.mozilla.org/en-US/docs/WebAssembly#browser_compatibility)的浏览器(较新的浏览器全都支持) | M |
| [Java (JVM)](https://github.com/cozodb/cozo-lib-java) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | | [Java (JVM)](https://github.com/cozodb/cozo-lib-java)[国内镜像](https://gitee.com/cozodb/cozo-lib-java) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR |
| [Clojure (JVM)](https://github.com/cozodb/cozo-clj) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | | [Clojure (JVM)](https://github.com/cozodb/cozo-clj)[国内镜像](https://gitee.com/cozodb/cozo-clj) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR |
| [安卓](https://github.com/cozodb/cozo-lib-android) | Android (ARM64, ARMv7, x86_64, x86) | MQ | | [安卓](https://github.com/cozodb/cozo-lib-android)[国内镜像](https://gitee.com/cozodb/cozo-lib-android) | Android (ARM64, ARMv7, x86_64, x86) | MQ |
| [iOS/macOS (Swift)](./cozo-lib-swift) | iOS (ARM64, 模拟器), Mac (ARM64, x86_64) | MQ | | [iOS/macOS (Swift)](./cozo-lib-swift) | iOS (ARM64, 模拟器), Mac (ARM64, x86_64) | MQ |
| [Rust](https://docs.rs/cozo/) | 任何支持`std`的[平台](https://doc.rust-lang.org/nightly/rustc/platform-support.html)(源代码编译) | MQRST | | [Rust](https://docs.rs/cozo/) | 任何支持`std`的[平台](https://doc.rust-lang.org/nightly/rustc/platform-support.html)(源代码编译) | MQRST |
| [Go](https://github.com/cozodb/cozo-lib-go) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | | [Go](https://github.com/cozodb/cozo-lib-go)[国内镜像](https://gitee.com/cozodb/cozo-lib-go) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR |
| [C/C++/支持C FFI的语言](./cozo-lib-c) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | | [C/C++/支持 C FFI 的语言](./cozo-lib-c) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR |
| [独立的HTTP服务](./cozoserver) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQRST | | [独立的 HTTP 服务](./cozoserver) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQRST |
“存储引擎”列中各个字母的含义: “存储引擎”列中各个字母的含义:

@ -11,10 +11,7 @@
//! //!
//! This doc describes the Rust API. To learn how to use CozoDB to query (CozoScript), see: //! This doc describes the Rust API. To learn how to use CozoDB to query (CozoScript), see:
//! //!
//! * [CozoScript Manual](https://docs.cozodb.org) //! * [The CozoDB documentation](https://docs.cozodb.org)
//!
//! You can run all the queries described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/)
//! without installing anything.
//! //!
//! Rust API usage: //! Rust API usage:
//! ``` //! ```

@ -5,9 +5,7 @@
This directory contains the source of the Cozo C API. This directory contains the source of the Cozo C API.
This document describes how to set up the C library. This document describes how to set up the C library.
To learn how to use CozoDB (CozoScript), follow To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html).
the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries
described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/).
You can download pre-built libraries from the [release page](https://github.com/cozodb/cozo/releases), You can download pre-built libraries from the [release page](https://github.com/cozodb/cozo/releases),
look for those starting with `libcozo_c`. look for those starting with `libcozo_c`.

@ -4,9 +4,9 @@
一般情况下,这个库不是直接使用的。用于应当使用以下调用此库的库: 一般情况下,这个库不是直接使用的。用于应当使用以下调用此库的库:
* [Cozo Java](https://github.com/cozodb/cozo-lib-java):在 JVM Java 中使用 * [Cozo Java](https://github.com/cozodb/cozo-lib-java) [镜像](https://gitee.com/cozodb/cozo-lib-java):在 JVM Java 中使用
* [Cozo Clojure](https://github.com/cozodb/cozo-clj):在 JVM Clojure 中使用 * [Cozo Clojure](https://github.com/cozodb/cozo-clj) [镜像](https://gitee.com/cozodb/cozo-clj):在 JVM Clojure 中使用
* [Cozo Android](https://github.com/cozodb/cozo-lib-android):在安卓中使用 * [Cozo Android](https://github.com/cozodb/cozo-lib-android) [镜像](https://gitee.com/cozodb/cozo-lib-android):在安卓中使用
下面几个小节介绍在上面几个库不支持你的平台时如何从源码编译此库。 下面几个小节介绍在上面几个库不支持你的平台时如何从源码编译此库。

@ -2,23 +2,27 @@
[![cozo-node](https://img.shields.io/npm/v/cozo-node)](https://www.npmjs.com/package/cozo-node) [![cozo-node](https://img.shields.io/npm/v/cozo-node)](https://www.npmjs.com/package/cozo-node)
Embedded [CozoDB](https://github.com/cozodb/cozo) for NodeJS. NodeJS 的嵌入式 [CozoDB](https://www.cozodb.org) 库。
This document describes how to set up the Cozo module for use in NodeJS. 本文叙述的是如何安装设置库本身。有关如何使用 CozoDBCozoScript的信息见 [文档](https://docs.cozodb.org/zh_CN/latest/index.html) 。
To learn how to use CozoDB (CozoScript), follow
the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries
described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/).
## Installation ## 安装
```bash ```bash
npm install --save cozo-node npm install --save cozo-node
``` ```
If that doesn't work because there are no precompiled binaries for your platform, 安装过程中需要从 [GitHub 发布页](https://github.com/cozodb/cozo-lib-nodejs/releases/tag/0.4.0) 下载二进制文件。如果因为网络问题失败,可以使用此 [镜像](https://github.com/cozodb/cozo-lib-nodejs/releases/tag/0.4.0) ,使用方法为
scroll below to the building section.
## Usage ```bash
npm install --save cozo-node --cozo_node_prebuilt_binary_host_mirror=https://gitee.com/cozodb/cozo-lib-nodejs/releases/download/
```
注意:如果你用的是 Yarn 而不是 NPM类似的命令 [可能不奏效](https://github.com/mapbox/node-pre-gyp/issues/514) 。
如果你的操作系统、平台不是常见的平台,可能会报错说找不到预编译库。这种情况下可以参见后面关于如何从源码编译的内容。
## 用法
```javascript ```javascript
const {CozoDb} = require('cozo-node') const {CozoDb} = require('cozo-node')
@ -41,93 +45,84 @@ printQuery("?[a] <- [[1, 2]]")
```ts ```ts
class CozoDb { class CozoDb {
/** /**
* Constructor * 构造函数
* *
* @param engine: defaults to 'mem', the in-memory non-persistent engine. * @param engine: 默认为 'mem',即纯内存的非持久化存储。其他值可以是 'sqlite'、'rocksdb' 等
* 'sqlite', 'rocksdb' and maybe others are available, * @param path: 存储文件或文件夹的路径,默认为 'data.db'。在 'mem' 引擎下无用。
* depending on compile time flags. * @param options: 默认为 {},在 NodeJS 支持的引擎中无用。
* @param path: path to store the data on disk, defaults to 'data.db',
* may not be applicable for some engines such as 'mem'
* @param options: defaults to {}, ignored by all the engines in the published NodeJS artefact
*/ */
constructor(engine: string, path: string, options: object): CozoDb; constructor(engine: string, path: string, options: object): CozoDb;
/** /**
* You must call this method for any database you no longer want to use: * 关闭数据库,并释放其原生资源。如果不调用此方法而直接删除数据库的变量,则会造成原生资源泄漏。
* otherwise the native resources associated with it may linger for as
* long as your program runs. Simply `delete` the variable is not enough.
*/ */
close(): void; close(): void;
/** /**
* Runs a query * 执行查询文本
* *
* @param script: the query * @param script: 查询文本
* @param params: the parameters as key-value pairs, defaults to {} * @param params: 传入的参数,默认为 {}
*/ */
async run(script: string, params: object): object; async run(script: string, params: object): object;
/** /**
* Export several relations * 导出存储表
* *
* @param relations: names of relations to export, in an array. * @param relations: 需要导出的存储表名称
*/ */
async exportRelations(relations: Array<string>): object; async exportRelations(relations: Array<string>): object;
/** /**
* Import several relations. * 导入数据至存储表
* *
* Note that triggers are _not_ run for the relations, if any exists. * 注意:以此方法导入数据不会激活存储表上任何的触发器。
* If you need to activate triggers, use queries with parameters.
* *
* @param data: in the same form as returned by `exportRelations`. The relations * @param data: 导入的表以及数据,格式与 `exportRelations` 返回的相同
* must already exist in the database.
*/ */
async importRelations(data: object): object; async importRelations(data: object): object;
/** /**
* Backup database * 备份数据库
* *
* @param path: path to file to store the backup. * @param path: 备份文件路径
*/ */
async backup(path: string): object; async backup(path: string): object;
/** /**
* Restore from a backup. Will fail if the current database already contains data. * 从备份文件恢复数据至当前数据库。若当前数据库非空,则报错。
* *
* @param path: path to the backup file. * @param path: 备份文件路径
*/ */
async restore(path: string): object; async restore(path: string): object;
/** /**
* Import several relations from a backup. The relations must already exist in the database. * 将备份文件中指定存储表里的数据插入当前数据库中同名表里。
* *
* Note that triggers are _not_ run for the relations, if any exists. * 注意:以此方法导入数据不会激活存储表上任何的触发器。
* If you need to activate triggers, use queries with parameters.
* *
* @param path: path to the backup file. * @param path: 备份文件路径
* @param rels: the relations to import. * @param rels: 需导入数据的表名
*/ */
async importRelationsFromBackup(path: string, rels: Array<string>): object; async importRelationsFromBackup(path: string, rels: Array<string>): object;
} }
``` ```
## Building 更多信息 [见此](https://docs.cozodb.org/zh_CN/latest/nonscript.html) 。
## 编译
Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run 编译 `cozo-node` 需要 [Rust 工具链](https://rustup.rs)。运行
```bash ```bash
cargo build --release -p cozo-node -F compact -F storage-rocksdb cargo build --release -p cozo-node -F compact -F storage-rocksdb
``` ```
and then find the dynamic library (names can vary a lot, the file extension is `.so` on Linux, `.dylib` on Mac, 完成后,动态链接库可以在 `../target/` 文件夹中找到(具体文件名根据平台与操作系统会有差异,一般来说 Linux 上 扩展名为 `.so`Mac 上为 `.dylib`Windows 上为 `.dll`)。
and `.dll` on Windows) under the `../target/` folder (you may need to search for it). 将找到的动态库拷贝为此目录下的 `native/6/cozo_node_prebuilt.node` 文件(中间目录若不存在,则需建立)。
Copy it to the file `native/6/cozo_node_prebuilt.node` under this directory (create intermediate directories if they don't exist).
If you did everything correctly, you should get the hello world message printed out when you run 如果一切操作正确,在此目录下执行下列命令则会正常返回:
```bash ```bash
node example.js node example.js
``` ```
under this directory.

@ -2,12 +2,10 @@
[![cozo-node](https://img.shields.io/npm/v/cozo-node)](https://www.npmjs.com/package/cozo-node) [![cozo-node](https://img.shields.io/npm/v/cozo-node)](https://www.npmjs.com/package/cozo-node)
Embedded [CozoDB](https://github.com/cozodb/cozo) for NodeJS. Embedded [CozoDB](https://www.cozodb.org) for NodeJS.
This document describes how to set up the Cozo module for use in NodeJS. This document describes how to set up the Cozo module for use in NodeJS.
To learn how to use CozoDB (CozoScript), follow To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html).
the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries
described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/).
## Installation ## Installation
@ -112,6 +110,8 @@ class CozoDb {
} }
``` ```
More information are [here](https://docs.cozodb.org/en/latest/nonscript.html).
## Building ## Building
Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run

@ -2,19 +2,14 @@
[![pypi](https://img.shields.io/pypi/v/cozo_embedded)](https://pypi.org/project/cozo_embedded/) [![pypi](https://img.shields.io/pypi/v/cozo_embedded)](https://pypi.org/project/cozo_embedded/)
Native bindings for embedding [CozoDB](https://github.com/cozodb/cozo) in Python, providing the [CozoDB](https://www.cozodb.org) 的 Python 嵌入式库 `cozo_embedded` 的源代码。
`cozo_embedded` package.
You are not supposed to be using this package directly in your code. Use [PyCozo](https://github.com/cozodb/pycozo), 一般来说你应该使用 [PyCozo](https://github.com/cozodb/pycozo) 库( [Gitee 镜像](https://gitee.com/cozodb/pycozo) ),而不是直接使用此库。
which depends on this package.
To build this package, you need to install the Rust toolchain 编译此库需要安装 Rust 工具链以及 [maturin](https://github.com/PyO3/maturin) 。安装好后运行
as well as the [maturin](https://github.com/PyO3/maturin) python package.
Then run
```bash ```bash
maturin build -F compact -F storage-rocksdb --release maturin build -F compact -F storage-rocksdb --release
``` ```
Refer maturin's docs for more information about how to [develop](https://www.maturin.rs/develop.html) 更多选项参见 maturin 的 [文档](https://www.maturin.rs/) 。
and [build](https://www.maturin.rs/distribution.html) this package.

@ -2,7 +2,7 @@
[![pypi](https://img.shields.io/pypi/v/cozo_embedded)](https://pypi.org/project/cozo_embedded/) [![pypi](https://img.shields.io/pypi/v/cozo_embedded)](https://pypi.org/project/cozo_embedded/)
Native bindings for embedding [CozoDB](https://github.com/cozodb/cozo) in Python, providing the Native bindings for embedding [CozoDB](https://www.cozodb.org) in Python, providing the
`cozo_embedded` package. `cozo_embedded` package.
You are not supposed to be using this package directly in your code. Use [PyCozo](https://github.com/cozodb/pycozo), You are not supposed to be using this package directly in your code. Use [PyCozo](https://github.com/cozodb/pycozo),

@ -2,18 +2,13 @@
[![pod](https://img.shields.io/cocoapods/v/CozoSwiftBridge)](https://github.com/cozodb/cozo/tree/main/cozo-lib-swift) [![pod](https://img.shields.io/cocoapods/v/CozoSwiftBridge)](https://github.com/cozodb/cozo/tree/main/cozo-lib-swift)
This document describes how to set up the Cozo module for use in Swift on Apple hardware. 本文叙述的是如何安装设置库本身。有关如何使用 CozoDBCozoScript的信息见 [文档](https://docs.cozodb.org/zh_CN/latest/index.html) 。
To learn how to use CozoDB (CozoScript), follow
the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries
described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/).
This package can be used for MacOS (both Apple ARM and Intel) and iOS (iPad, iPhone and simulators). 本库可在 macOS苹果 ARM 或 Intel 芯片)以及 iOSiPad、iPhone、模拟器中使用。
Only the `storage-sqlite` engine is enabled for the Swift prebuilt binaries, as using 预编译的二进制包里,持久化引擎中,只有 `storage-sqlite` 在此库中可用。如果需要其他引擎请从源码编译。
other storage engines on desktop or mobile does not make too much sense. If you disagree,
see the Building section below.
## Installation ## 安装
### CocoaPods ### CocoaPods
@ -27,28 +22,9 @@ end
### Swift Package Manager (SPM) ### Swift Package Manager (SPM)
The package is published as an archive containing a Swift package. 从 [GitHub 发布页面](https://github.com/cozodb/cozo/releases) 下载名为 `CozoSwiftBridge.tgz` 的包,然后手动导入至 XCode 中。详见 [英文文档](./README.md)。
Download it from the [release page](https://github.com/cozodb/cozo/releases) (look for `CozoSwiftBridge.tgz`).
Uncompress.
In XCode of your project, select from the menu `File > Add Packages`, ## 基本使用
select `Add Local ...` on the bottom, choose the folder you just decompressed
(the one containing a `Package.swift` at the root), then click `Add Package`.
Then click your project on the left pane, and go to
`General > Frameworks, Libraries, and Embedded Content`,
click on the plus sign, and add `Workspace > CozoSwiftBridge > CozoSwiftBridge`
(with a library icon).
If you did everything right, you should also see `CozoSwiftBridge` under
`Build Phases > Link Binary With Libraries`.
> You cannot download swift packages directly from GitHub repo, since
in order to support that we would need to check the binaries
into version control, and GitHub does not like it (we tried to work
this around with Git LFS, but no luck).
## Using the library
```swift ```swift
import CozoSwiftBridge import CozoSwiftBridge
@ -60,7 +36,9 @@ import CozoSwiftBridge
let res = try! db.run("?[] <- [[1,2,3]]").toString() let res = try! db.run("?[] <- [[1,2,3]]").toString()
} }
``` ```
Above we created an SQLite-based database. For memory-based ones:
上例中创建了一个 SQLite 引擎支持的数据库。如果要用纯内存引擎:
```swift ```swift
let db = CozoDB() let db = CozoDB()
``` ```
@ -72,101 +50,93 @@ public class CozoDB {
public let db: DbInstance public let db: DbInstance
/** /**
* Constructs an in-memory database. * 构造一个纯内存引擎的数据库
*/ */
public init(); public init();
/** /**
* Constructs a database. * 构造一个数据库
* *
* `kind`: the engine kind, can be `mem` or `sqlite`. * `kind`: 引擎类型,`mem` 或 `sqlite`
* `path`: specifies the path to the storage file, only used for `sqlite` engine * `path`: 存储文件的路径,仅在 `sqlite` 引擎下有效。
*/ */
public init(kind: String, path: String) throws; public init(kind: String, path: String) throws;
/** /**
* Run query against the database. * 执行查询文本
* *
* `query`: the CozoScript to execute. * `query`: 查询文本
*/ */
public func run(_ query: String) throws -> [NamedRow]; public func run(_ query: String) throws -> [NamedRow];
/** /**
* Run query against the database. * 执行查询文本
* *
* `query`: the CozoScript to execute. * `query`: 查询文本
* `params`: the params of the query in JSON format. * `params`: 文本中可用的参数
*/ */
public func run(_ query: String, params: JSON) throws -> [NamedRow]; public func run(_ query: String, params: JSON) throws -> [NamedRow];
/** /**
* Export relations as JSON * 导出纯出表至 JSON
* *
* `relations`: the stored relations to export * `relations`: 需导出的表名
*/ */
public func exportRelations(relations: [String]) throws -> JSON; public func exportRelations(relations: [String]) throws -> JSON;
/** /**
* Import data into relations * 导入数据至存储表中
* *
* Note that triggers are _not_ run for the relations, if any exists. * 注意此方法不会激活任何触发器。
* If you need to activate triggers, use queries with parameters.
* *
* `data`: the payload, in the same format as returned by `exportRelations`. * `data`: 导入内容,与 `exportRelations` 返回的格式相同
*/ */
public func importRelations(data: JSON) throws; public func importRelations(data: JSON) throws;
/** /**
* Backup the database. * 备份数据库
* *
* `path`: path of the output file. * `path`: 备份路径
*/ */
public func backup(path: String) throws; public func backup(path: String) throws;
/** /**
* Restore the database from a backup. * 将备份恢复到当前数据库
* *
* `path`: path of the input file. * `path`: 备份路径
*/ */
public func restore(path: String) throws; public func restore(path: String) throws;
/** /**
* Import data into a relation from a backup. * 将备份中表里的数据插入当前数据库中选定的同名表中
* *
* Note that triggers are _not_ run for the relations, if any exists. * 注意此方法不会激活任何触发器。
* If you need to activate triggers, use queries with parameters.
* *
* `path`: path of the input file. * `path`: 备份路径
* `relations`: the stored relations to import into. * `relations`: 需要导入数据的表名
*/ */
public func importRelationsFromBackup(path: String, relations: [String]) throws; public func importRelationsFromBackup(path: String, relations: [String]) throws;
} }
``` ```
## Building the Swift Package 更多信息 [见此](https://docs.cozodb.org/zh_CN/latest/nonscript.html) 。
First, install the [Rust toolchain](https://rustup.rs). ## 编译
Then run the [build script](build-rust.sh) in this directory.
It is recommended to also set the environment variable `CARGO_PROFILE_RELEASE_LTO=fat`:
this makes the building process much longer, but in turn the library runs a little bit faster.
When everything goes well, you should find the compiled Swift package in a directory called 首先安装 [Rust 工具链](https://rustup.rs)。然后执行 [此批处理文件](build-rust.sh) 。建议执行时设置环境变量`CARGO_PROFILE_RELEASE_LTO=fat`:编译时间会变长,但是生成的库更快。
`CozoSwiftBridge`.
If you want to use the RocksDB engine on Desktop, in the build script change the two lines 如果一切都没问题,则 `CozoSwiftBridge` 文件夹里会有编译好的文件。
如果想使用 RocksDB 引擎,则在批处理文件中,将以下两行
```bash ```bash
cargo build -p cozo-swift -F compact --target x86_64-apple-darwin --release cargo build -p cozo-swift -F compact --target x86_64-apple-darwin --release
cargo build -p cozo-swift -F compact --target aarch64-apple-darwin --release cargo build -p cozo-swift -F compact --target aarch64-apple-darwin --release
``` ```
to 改为
```bash ```bash
cargo build -p cozo-swift -F compact -F storage-rocksdb --target x86_64-apple-darwin --release cargo build -p cozo-swift -F compact -F storage-rocksdb --target x86_64-apple-darwin --release
cargo build -p cozo-swift -F compact -F storage-rocksdb --target aarch64-apple-darwin --release cargo build -p cozo-swift -F compact -F storage-rocksdb --target aarch64-apple-darwin --release
``` ```
注意,给 iOS 编译 RocksDB 不是一件简单的事情。
Then you also need to link your executable with `libc++`: in XCode, click on your project 在使用生成的库时,需要在 XCode 中选择链接至 `libc++` 动态库。
in the left drawer, then on the right go to `Build phases > Link Binary With Libraries`,
click the plus sign, search for `libc++`, then add `libc++.tbd` found under Apple SDKs.
Similar same process goes if you want to enable other features. Note that building the
RocksDB engine for mobile is a very demanding task!

@ -3,13 +3,11 @@
[![pod](https://img.shields.io/cocoapods/v/CozoSwiftBridge)](https://github.com/cozodb/cozo/tree/main/cozo-lib-swift) [![pod](https://img.shields.io/cocoapods/v/CozoSwiftBridge)](https://github.com/cozodb/cozo/tree/main/cozo-lib-swift)
This document describes how to set up the Cozo module for use in Swift on Apple hardware. This document describes how to set up the Cozo module for use in Swift on Apple hardware.
To learn how to use CozoDB (CozoScript), follow To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html).
the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries
described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/).
This package can be used for MacOS (both Apple ARM and Intel) and iOS (iPad, iPhone and simulators). This package can be used for MacOS (both Apple ARM and Intel) and iOS (iPad, iPhone and simulators).
Only the `storage-sqlite` engine is enabled for the Swift prebuilt binaries, as using Only the `storage-sqlite` persistent engine is enabled for the Swift prebuilt binaries, as using
other storage engines on desktop or mobile does not make too much sense. If you disagree, other storage engines on desktop or mobile does not make too much sense. If you disagree,
see the Building section below. see the Building section below.
@ -143,6 +141,8 @@ public class CozoDB {
} }
``` ```
More information are [here](https://docs.cozodb.org/en/latest/nonscript.html).
## Building the Swift Package ## Building the Swift Package
First, install the [Rust toolchain](https://rustup.rs). First, install the [Rust toolchain](https://rustup.rs).

@ -1,35 +1,26 @@
# Cozo WASM 库(浏览器) # Cozo WASM 库(浏览器)
This crate provides Cozo web assembly modules for browsers. 可以在浏览器中运行的 Cozo WASM 库。NodeJS 用户请使用 [原生库](../cozo-lib-nodejs) :速度更快,功能也更多。
If you are targeting NodeJS, use [this](../cozo-lib-nodejs) instead:
native code is still _much_ faster than WASM.
This document describes how to set up the Cozo WASM module for use. 本文叙述的是如何安装设置库本身。有关如何使用 CozoDBCozoScript的信息见 [文档](https://docs.cozodb.org/zh_CN/latest/index.html) 。
To learn how to use CozoDB (CozoScript), follow
the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries
described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/).
## Installation 安装
``` ```
npm install cozo-lib-wasm npm install cozo-lib-wasm
``` ```
Alternatively, you can download `cozo_wasm-<VERSION>-wasm32-unknown-unknown.zip` 你也可以直接从 [发布页面](https://github.com/cozodb/cozo/releases) 下载 `cozo_wasm-<VERSION>-wasm32-unknown-unknown.zip` 文件,然后直接在你的网页代码中引用:见 [此处](https://rustwasm.github.io/docs/wasm-bindgen/examples/without-a-bundler.html) 的 `index.html` 范例。
from the [release page](https://github.com/cozodb/cozo/releases) and include
the JS and WASM files directly in your project: see the `index.html` example
[here](https://rustwasm.github.io/docs/wasm-bindgen/examples/without-a-bundler.html) for
what is required in your code.
## Usage ## 使用
See the code [here](wasm-react-demo/src/App.js). Basically, you write 参考 [此文件](wasm-react-demo/src/App.js)。简单地说:
```js ```js
import init, {CozoDb} from "cozo-lib-wasm"; import init, {CozoDb} from "cozo-lib-wasm";
``` ```
and call 然后:
```js ```js
let db; let db;
@ -51,36 +42,26 @@ export class CozoDb {
export_relations(data: string): string; export_relations(data: string): string;
// Note that triggers are _not_ run for the relations, if any exists. // 注意:通过此接口载入数据不会激活触发器
// If you need to activate triggers, use queries with parameters.
import_relations(data: string): string; import_relations(data: string): string;
} }
``` ```
Note that this API is synchronous. If your computation runs for a long time, 注意所有的 API 都是同步的。如果你的查询需要比较长的时间返回,浏览器的主线程会被阻塞。阻塞浏览器主线程不是好事,因此在这种情况下你可以考虑在 web worker 中运行 Cozo WASM 模块。不过预编译的 WASM 模块不支持在有些浏览器的 web worker 中运行:见 [此页面](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker#browser_compatibility) 的 "Support for ECMAScript
**it will block the main thread**. If you know that some of your queries are going to be heavy, modules" 信息。
you should consider running Cozo in a web worker. However, the published module
may not work across browsers in web workers (look for the row "Support for ECMAScript
modules" [here](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker#browser_compatibility)).
The next section contains some pointers for how to alleviate this, but expect a lot of work. ## 编译
## Compiling 编译需要 [Rust 工具链](https://rustup.rs/)[NodeJS 与 npm](https://nodejs.org/),再加上 [wasm-pack](https://github.com/rustwasm/wasm-pack)。
You will need to install [Rust](https://rustup.rs/), [NodeJS with npm](https://nodejs.org/), 用以下命令来编译:
and [wasm-pack](https://github.com/rustwasm/wasm-pack) first.
The published module was built with
```bash ```bash
wasm-pack build --target web --release wasm-pack build --target web --release
``` ```
and the environment variable `CARGO_PROFILE_RELEASE_LTO=fat`. 建议编译时设置环境变量 `CARGO_PROFILE_RELEASE_LTO=fat` 使生成的库更快(以增加编译时间为代价)。
The important option is `--target web`: the above usage instructions only work for this target. 以上我们给出了参数 `--target web`:上面在浏览器中的使用例子只支持用此参数编译出的库。更多信息参见 [WASM 的文档](https://rustwasm.github.io/wasm-pack/book/commands/build.html#target)。
See the documentation [here](https://rustwasm.github.io/wasm-pack/book/commands/build.html#target).
if you are interested in running Cozo in a web worker and expect it to run across browsers, 使用 `--target no-modules` 编译出的库可以在更多浏览器中的 web worker 运行,但是调用方式与上面给出的例子有区别,也更麻烦。详情见 [文档](https://rustwasm.github.io/wasm-bindgen/examples/wasm-in-web-worker.html) 。
you will need to use the `--target no-modules` option, and write a lot of gluing code.
See [here](https://rustwasm.github.io/wasm-bindgen/examples/wasm-in-web-worker.html) for tips.

@ -5,9 +5,7 @@ If you are targeting NodeJS, use [this](../cozo-lib-nodejs) instead:
native code is still _much_ faster than WASM. native code is still _much_ faster than WASM.
This document describes how to set up the Cozo WASM module for use. This document describes how to set up the Cozo WASM module for use.
To learn how to use CozoDB (CozoScript), follow To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html).
the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries
described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/).
## Installation ## Installation

@ -0,0 +1,3 @@
# Cozo WASM 示例
此示例的展示在 https://www.cozodb.org/wasm-demo/ 。源码供参考。

@ -2,84 +2,56 @@
[![server](https://img.shields.io/github/v/release/cozodb/cozo)](https://github.com/cozodb/cozo/releases) [![server](https://img.shields.io/github/v/release/cozodb/cozo)](https://github.com/cozodb/cozo/releases)
This document describes how to set up cozoserver. 本文叙述的是如何安装设置服务程序本身。有关如何使用 CozoDBCozoScript的信息见 [文档](https://docs.cozodb.org/zh_CN/latest/index.html) 。
To learn how to use CozoDB (CozoScript), follow
the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries
described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/).
## Download ## 下载
The standalone executable for Cozo can be downloaded from the [release page](https://github.com/cozodb/cozo/releases). 独立服务的程序可以从 [GitHub 发布页](https://github.com/cozodb/cozo/releases) 或 [Gitee 发布页](https://gitee.com/cozodb/cozo/releases) 下载,其中名为 `cozoserver-*` 的是独立服务程序,名为 `cozoserver_all-*` 的独立程序同时支持更多地存储引擎,比如 [TiKV](https://tikv.org/)。
Look for those with names `cozoserver-*`.
Those with names `cozoserver_all-*` supports additional storage backends
such as [TiKV](https://tikv.org/) storage, but are larger.
## Starting the server ## 启动服务程序
Run the cozoserver command in a terminal: 在终端中执行:
```bash ```bash
./cozoserver ./cozoserver
``` ```
This starts an in-memory, non-persistent database. 如此执行命令会使用纯内存的非持久化存储引擎。执行 `./cozoserver -h` 可查看如何启用其它引擎,以及其它参数。
For more options such as how to run a persistent database with other storage engines,
see `./cozoserver -h`
To stop Cozo, press `CTRL-C`, or send `SIGTERM` to the process with e.g. `kill`. 若要终止程序,按下 `CTRL-C` 按键,或向进程发送 `SIGTERM` (比如通过 `kill` 命令)。
## The query API ## 查询 API
Queries are run by sending HTTP POST requests to the server. 查询通过向 API 发送 POST 请求来完成。默认的请求地址是 `http://127.0.0.1:9070/text-query` 。请求必须包含 JSON 格式的正文,具体内容如下:
By default, the API endpoint is `http://127.0.0.1:9070/text-query`.
A JSON body of the following form is expected:
```json ```json
{ {
"script": "<COZOSCRIPT QUERY STRING>", "script": "<COZOSCRIPT QUERY STRING>",
"params": {} "params": {}
} }
``` ```
params should be an object of named parameters. For example, if params is `{"num": 1}`, `params` 给出了查询文本中可用的变量。例如,当 `params``{"num": 1}` 时,查询文本中可以以 `$num` 来代替常量 `1`。请善用此功能,而不是手动拼接查询字符串。
then `$num` can be used anywhere in your query string where an expression is expected.
Always use params instead of concatenating strings when you need parametrized queries. HTTP API 返回的结果永远是 JSON 格式的。如果请求成功,则返回结果的 `"ok"` 字段将为 `true`,且 `"rows"` 字段将含有查询结果的行,而 `"headers"` 将含有表头。如果查询报错,则 `"ok"` 字段将为 `false`,而错误信息会在 `"message"` 字段中,同时 `"display"` 字段会包含格式化好的友好的错误提示。
The HTTP API always responds in JSON. If a request is successful, then its `"ok"` field will be `true`, > Cozo 的设计,基于其在一个受信任的环境中运行,且其所有用户也是由受信任的这种假设。因此 Cozo 没有内置认证与复杂的安全机制。如果你需要远程访问 Cozo 服务,你必须自己设置防火墙、加密和代理等,用来保护服务器上资源的安全。
and the `"rows"` field will contain the data for the resulting relation, and `"headers"` will contain
the headers. If an error occurs, then `"ok"` will contain `false`, the error message will be in `"message"`
and a nicely-formatted diagnostic will be in `"display"` if available.
> Cozo is designed to run in a trusted environment and be used by trusted clients.
> It does not come with elaborate authentication and security features.
> If you must access Cozo remotely, you are responsible for setting up firewalls, encryptions and proxies yourself.
> >
> As a guard against users accidentally exposing sensitive data, > 由于总是会有用户不小心将服务接口暴露于外网Cozo 有一个补救措施:如果从非回传地址访问 Cozo则必须在所有请求中以 HTTP 文件头 `x-cozo-auth` 的形式附上访问令牌。访问令牌的内容在启动服务的终端中有提示。注意这仅仅是一个补救措施,并不是特别可靠的安全机制,是为了尽量防止一些不由于小心而造成严重后果的悲剧。
> If you bind Cozo to non-loopback addresses,
> Cozo will generate a token string and require all queries from non-loopback addresses ## 所有 API
> to provide the token string in the HTTP header field x-cozo-auth.
> The warning printed when you start Cozo with a * `POST /text-query`,见上。
> non-default binding will tell you where to find the token string. * `GET /export/{relations: String}`,导出指定表中的数据,其中 `relations` 是以逗号分割的表名。
> This “security measure” is not considered sufficient for any purpose * `PUT /import`,向数据库导入数据。所导入的数据应以在正文中以 `application/json` MIME 类型传入,具体格式与 `/export` 返回值中的 `data` 字段相同。
> and is only intended as a last defence against carelessness. * `POST /backup`,备份数据库,需要传入 JSON 正文 `{"path": <路径>}`
* `POST /import-from-backup`,将备份中指定存储表中的数据插入当前数据库中同名存储表。需要传入 JSON 正文 `{"path": <路径>, "relations": <表名数组>}`.
## API * `GET /`,用浏览器打开这个地址,然后打开浏览器的调试工具,就可以使用一个简陋的 JS 客户端。
* `POST /text-query`, described above. > 注意 `import``import-from-backup` 接口不会激活任何触发器。
* `GET /export/{relations: String}`, where `relations` is a comma-separated list of relations to export.
* `PUT /import`, import data into the database. Data should be in `application/json` MIME type in the body,
in the same format as returned in the `data` field in the `/export` API. ## 编译
* `POST /backup`, backup database, should supply a JSON body of the form `{"path": <PATH>}`
* `POST /import-from-backup`, import data into the database from a backup. Should supply a JSON body 编译 `cozoserver` 需要 [Rust 工具链](https://rustup.rs)。运行
of the form `{"path": <PATH>, "relations": <ARRAY OF RELATION NAMES>}`.
* `GET /`, if you open this in your browser and open your developer tools, you will be able to use
a very simple client to query this database.
> For `import` and `import-from-backup`, triggers are _not_ run for the relations, if any exists.
If you need to activate triggers, use queries with parameters.
## Building
Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run
```bash ```bash
cargo build --release -p cozoserver -F compact -F storage-rocksdb cargo build --release -p cozoserver -F compact -F storage-rocksdb

@ -3,9 +3,7 @@
[![server](https://img.shields.io/github/v/release/cozodb/cozo)](https://github.com/cozodb/cozo/releases) [![server](https://img.shields.io/github/v/release/cozodb/cozo)](https://github.com/cozodb/cozo/releases)
This document describes how to set up cozoserver. This document describes how to set up cozoserver.
To learn how to use CozoDB (CozoScript), follow To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html).
the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries
described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/).
## Download ## Download
@ -79,7 +77,7 @@ If you need to activate triggers, use queries with parameters.
## Building ## Building
Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run Building `cozoserver` requires a [Rust toolchain](https://rustup.rs). Run
```bash ```bash
cargo build --release -p cozoserver -F compact -F storage-rocksdb cargo build --release -p cozoserver -F compact -F storage-rocksdb

Loading…
Cancel
Save