You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
102 lines
4.6 KiB
Markdown
102 lines
4.6 KiB
Markdown
# CozoServer
|
|
|
|
[![server](https://img.shields.io/github/v/release/cozodb/cozo)](https://github.com/cozodb/cozo/releases)
|
|
|
|
This document describes how to set up cozoserver.
|
|
To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html).
|
|
|
|
## Download
|
|
|
|
The standalone executable for Cozo can be downloaded from the [release page](https://github.com/cozodb/cozo/releases).
|
|
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
|
|
./cozoserver
|
|
```
|
|
|
|
This starts an in-memory, non-persistent database.
|
|
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`.
|
|
|
|
## The REPL
|
|
|
|
If you start the server with the `-r` or `--repl` option, a web server will not be started.
|
|
Instead, a terminal-based REPL is presented to you. The engine options can be used when
|
|
invoking the executable to choose the backend.
|
|
|
|
You can use the following meta ops in the REPL:
|
|
|
|
* `%set <KEY> <VALUE>`: set a parameter that can be used in queries.
|
|
* `%unset <KEY>`: unset a parameter.
|
|
* `%clear`: unset all parameters.
|
|
* `%params`: print all set parameters.
|
|
* `%import <FILE OR URL>`: import data in JSON format from the file or URL.
|
|
* `%save <FILE>`: the result of the next successful query will be saved in JSON format in a file instead of printed on screen. If `<FILE>` is omitted, then the effect of any previous `%save` command is nullified.
|
|
* `%backup <FILE>`: the current database will be backed up into the file.
|
|
* `%restore <FILE>`: restore the data in the backup to the current database. The current database must be empty.
|
|
|
|
## The query API
|
|
|
|
Queries are run by sending HTTP POST requests to the server.
|
|
By default, the API endpoint is `http://127.0.0.1:9070/text-query`.
|
|
A JSON body of the following form is expected:
|
|
```json
|
|
{
|
|
"script": "<COZOSCRIPT QUERY STRING>",
|
|
"params": {}
|
|
}
|
|
```
|
|
params should be an object of named parameters. For example, if params is `{"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.
|
|
|
|
The HTTP API always responds in JSON. If a request is successful, then its `"ok"` field will be `true`,
|
|
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,
|
|
> If you bind Cozo to non-loopback addresses,
|
|
> Cozo will generate a token string and require all queries from non-loopback addresses
|
|
> to provide the token string in the HTTP header field x-cozo-auth.
|
|
> The warning printed when you start Cozo with a
|
|
> non-default binding will tell you where to find the token string.
|
|
> This “security measure” is not considered sufficient for any purpose
|
|
> and is only intended as a last defence against carelessness.
|
|
|
|
## API
|
|
|
|
* `POST /text-query`, described above.
|
|
* `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
|
|
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 `cozoserver` requires a [Rust toolchain](https://rustup.rs). Run
|
|
|
|
```bash
|
|
cargo build --release -p cozoserver -F compact -F storage-rocksdb
|
|
```
|