| [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 |
| [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 服务](./cozo-bin) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQRST |
“存储引擎”列中各个字母的含义：
“存储引擎”列中各个字母的含义：
@ -199,7 +199,7 @@ Cozo 的 [Rust API 文档](https://docs.rs/cozo/)（英文）中有一些额外
@ -229,7 +229,7 @@ Follow the links in the table below:
| [Rust](https://docs.rs/cozo/) | Source only, usable on any [platform](https://doc.rust-lang.org/nightly/rustc/platform-support.html) with `std` support | MQRST |
| [Rust](https://docs.rs/cozo/) | Source only, usable on any [platform](https://doc.rust-lang.org/nightly/rustc/platform-support.html) with `std` support | MQRST |
| [Golang](https://github.com/cozodb/cozo-lib-go) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR |
| [Golang](https://github.com/cozodb/cozo-lib-go) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR |
| [C/C++/language with C FFI](./cozo-lib-c) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR |
| [C/C++/language with C FFI](./cozo-lib-c) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR |
| [Standalone HTTP server](./cozoserver) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQRST |
| [Standalone HTTP server](./cozo-bin) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQRST |
For the storage column:
For the storage column:
@ -255,7 +255,7 @@ When you create the CozoDB instance with the RocksDB backend option, you are ask
provide a path to a directory to store the data (will be created if it does not exist).
provide a path to a directory to store the data (will be created if it does not exist).
If you put a file named `options` inside this directory, the engine will expect this
If you put a file named `options` inside this directory, the engine will expect this
to be a [RocksDB options file](https://github.com/facebook/rocksdb/wiki/RocksDB-Options-File)
to be a [RocksDB options file](https://github.com/facebook/rocksdb/wiki/RocksDB-Options-File)
and use it. If you are using `cozoserver`, you will get a log message if
and use it. If you are using the standalone `cozo` executable, you will get a log message if
this feature is activated.
this feature is activated.
Note that improperly set options can make your database misbehave!
Note that improperly set options can make your database misbehave!
@ -8,28 +8,27 @@ To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org
## Download
## Download
The standalone executable for Cozo can be downloaded from the [release page](https://github.com/cozodb/cozo/releases).
The standalone executable for Cozo can be downloaded from the [release page](https://github.com/cozodb/cozo/releases).
Look for those with names `cozoserver-*`.
Look for those with names `cozo-*`.
Those with names `cozoserver_all-*` supports additional storage backends
Those with names `cozo_all-*` supports additional storage backends
such as [TiKV](https://tikv.org/) storage, but are larger.
such as [TiKV](https://tikv.org/) storage, but are larger.
## Starting the server
## Starting the server
Run the cozoserver command in a terminal:
Run the cozo command in a terminal:
```bash
```bash
./cozoserver
./cozoserver
```
```
This starts an in-memory, non-persistent database.
This starts an in-memory, non-persistent database.
For more options such as how to run a persistent database with other storage engines,
For more options such as how to run a persistent database with other storage engines,
see `./cozoserver -h`
see `./cozoserver -h`
To stop Cozo, press `CTRL-C`, or send `SIGTERM` to the process with e.g. `kill`.
To stop Cozo, press `CTRL-C`, or send `SIGTERM` to the process with e.g. `kill`.
## The REPL
## The REPL
If you start the server with the `-r` or `--repl` option, a web server will not be started.
Run `./cozo repl` to enter a terminal-based REPL. The engine options can be used when
Instead, a terminal-based REPL is presented to you. The engine options can be used when
invoking the executable to choose the backend.
invoking the executable to choose the backend.
You can use the following meta ops in the REPL:
You can use the following meta ops in the REPL:
@ -69,12 +68,15 @@ and a nicely-formatted diagnostic will be in `"display"` if available.
>
>
> As a guard against users accidentally exposing sensitive data,
> As a guard against users accidentally exposing sensitive data,
> If you bind Cozo to non-loopback addresses,
> If you bind Cozo to non-loopback addresses,
> Cozo will generate a token string and require all queries from non-loopback addresses
> Cozo will generate a token string and require all queries
> to provide the token string in the HTTP header field `x-cozo-auth`.
> to provide the token string in the HTTP header field `x-cozo-auth`.
> The warning printed when you start Cozo with a
> The warning printed when you start Cozo with a
> non-default binding will tell you where to find the token string.
> non-default binding will tell you where to find the token string.
> This “security measure” is not considered sufficient for any purpose
> This “security measure” is not considered sufficient for any purpose
> and is only intended as a last defence against carelessness.
> and is only intended as a last defence against carelessness.
>
> In some environments, setting the header may be difficult or impossible
> for some of the APIs. In this case you can pass the token in the query parameter `auth`.
## API
## API
@ -91,11 +93,22 @@ and a nicely-formatted diagnostic will be in `"display"` if available.
> For `import` and `import-from-backup`, triggers are _not_ run for the relations, if any exists.
> 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.
If you need to activate triggers, use queries with parameters.
The following are experimental:
* `GET(SSE) /changes/{relation: String}` get changes when mutations are made against a relation, relies on [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events).
* `GET(SSE) /rules/{name: String}` register a custom fixed rule and receive requests for computation.
Query parameter `arity` must also be present.
* `POST /rule-result/{id}` post results of custom fixed rule computation back to the server, used together with the last API.
* `POST /transact` start a multi-statement transaction, the ID returned is used in the following two APIs.
Need to set the `write=true` query parameter if mutations are present.
* `POST /transact/{id}` do queries inside a multi-statement transaction, JSON payload expected is the same as for `/text-query`.
* `PUT /transact/{id}` commit or abort a multi-statement transaction. JSON payload is of the form `{"abort": <bool>}`, pass `false` for commit and `true` for abort. If you forget to do this, a resource leak results, even for read-only transactions.
## Building
## Building
Building `cozoserver` requires a [Rust toolchain](https://rustup.rs). Run
Building `cozo` requires a [Rust toolchain](https://rustup.rs). Run
Ziyang Hu
2 years ago