stubs for more localized README
Ziyang Hu
2 years ago
parent
34d4b5372c
commit
cd43966389
@ -0,0 +1,5 @@
|
||||
# Cozo-core
|
||||
|
||||
[](https://crates.io/crates/cozo)
|
||||
|
||||
Cozo数据库核心部分的实现。
|
||||
@ -0,0 +1,32 @@
|
||||
# Cozo C语言库
|
||||
|
||||
[](https://github.com/cozodb/cozo/releases)
|
||||
|
||||
This directory contains the source of the Cozo C API.
|
||||
|
||||
This document describes how to set up the C library.
|
||||
To learn how to use CozoDB (CozoScript), follow
|
||||
the [tutorial](https://github.com/cozodb/cozo-docs/blob/main/tutorial/tutorial.ipynb)
|
||||
first and then read the [manual](https://cozodb.github.io/current/manual/). You can run all the queries
|
||||
described in the tutorial with an in-browser DB [here](https://cozodb.github.io/wasm-demo/).
|
||||
|
||||
You can download pre-built libraries from the [release page](https://github.com/cozodb/cozo/releases),
|
||||
look for those starting with `libcozo_c`.
|
||||
|
||||
The API is contained in this single [header file](./cozo_c.h).
|
||||
|
||||
An example for using the API is [here](./example.c).
|
||||
|
||||
To build and run the example:
|
||||
|
||||
```bash
|
||||
gcc -L../target/release/ -lcozo_c example.c -o example && ./example
|
||||
```
|
||||
|
||||
# Building Cozo from source
|
||||
|
||||
You need to install the [Rust toolchain](https://www.rust-lang.org/tools/install) on your system. Then:
|
||||
|
||||
```bash
|
||||
cargo build --release -p cozo_c -F compact -F storage-rocksdb
|
||||
```
|
||||
@ -0,0 +1,43 @@
|
||||
# Cozo Java语言库
|
||||
|
||||
This crate provides the JNI bindings for using Cozo in Java/JVM languages/Android.
|
||||
|
||||
You do not use this crate directly. Instead, use:
|
||||
|
||||
* ... for Java or other JVM languages
|
||||
* ... for Clojure on JVM (you can also use the Java library, but this one is nicer)
|
||||
* ... for Android
|
||||
|
||||
Keep reading only if the prebuilt binaries provided by these libraries do not suit your needs.
|
||||
|
||||
## Building for JDK
|
||||
|
||||
With the Rust toolchain installed,
|
||||
```bash
|
||||
cargo build --release -p cozo_java -F storage-rocksdb
|
||||
```
|
||||
|
||||
## Building for Android
|
||||
|
||||
Building for Android is not easy, and we will be very sketchy.
|
||||
|
||||
The first thing to note is that you should omit `-F storage-rocksdb` from the build command above,
|
||||
unless you are prepared to manually change lots of `build.rs` flags in
|
||||
[cozorocks](../cozorocks) to build the RocksDB dependency.
|
||||
|
||||
Then, in addition to adding Android targets to the Rust toolchain,
|
||||
you also need to set up the Android NDK
|
||||
cross-compilation and libraries paths, etc.
|
||||
This is notoriously hard to get right, but fortunately
|
||||
you can just use the Docker image [here](https://github.com/cross-rs/cross)
|
||||
which has everything set up for you.
|
||||
|
||||
When everything is set up correctly, the following command show complete without errors:
|
||||
|
||||
```bash
|
||||
for TARGET in aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android; do
|
||||
cross build -p cozo_java --release --target=$TARGET
|
||||
done
|
||||
```
|
||||
|
||||
For running on modern Android phones, the single target `aarch64-linux-android` is probably enough.
|
||||
@ -0,0 +1,134 @@
|
||||
# Cozo NodeJS库
|
||||
|
||||
[](https://www.npmjs.com/package/cozo-node)
|
||||
|
||||
Embedded [CozoDB](https://github.com/cozodb/cozo) for NodeJS.
|
||||
|
||||
This document describes how to set up the Cozo module for use in NodeJS.
|
||||
To learn how to use CozoDB (CozoScript), follow
|
||||
the [tutorial](https://github.com/cozodb/cozo-docs/blob/main/tutorial/tutorial.ipynb)
|
||||
first and then read the [manual](https://cozodb.github.io/current/manual/). You can run all the queries
|
||||
described in the tutorial with an in-browser DB [here](https://cozodb.github.io/wasm-demo/).
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install --save cozo-node
|
||||
```
|
||||
|
||||
If that doesn't work because there are no precompiled binaries for your platform,
|
||||
scroll below to the building section.
|
||||
|
||||
## Usage
|
||||
|
||||
```javascript
|
||||
const {CozoDb} = require('cozo-node')
|
||||
|
||||
const db = new CozoDb()
|
||||
|
||||
function printQuery(query, params) {
|
||||
db.run(query, params)
|
||||
.then(data => console.log(data))
|
||||
.catch(err => console.error(err.display || err.message))
|
||||
}
|
||||
|
||||
printQuery("?[] <- [['hello', 'world!']]")
|
||||
printQuery("?[] <- [['hello', 'world', $name]]", {"name": "JavaScript"})
|
||||
printQuery("?[a] <- [[1, 2]]")
|
||||
```
|
||||
|
||||
### API
|
||||
|
||||
```ts
|
||||
class CozoDb {
|
||||
/**
|
||||
* Constructor
|
||||
*
|
||||
* @param engine: defaults to 'mem', the in-memory non-persistent engine.
|
||||
* 'sqlite', 'rocksdb' and maybe others are available,
|
||||
* depending on compile time flags.
|
||||
* @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;
|
||||
|
||||
/**
|
||||
* 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;
|
||||
|
||||
/**
|
||||
* Runs a query
|
||||
*
|
||||
* @param script: the query
|
||||
* @param params: the parameters as key-value pairs, defaults to {}
|
||||
*/
|
||||
async run(script: string, params: object): object;
|
||||
|
||||
/**
|
||||
* Export several relations
|
||||
*
|
||||
* @param relations: names of relations to export, in an array.
|
||||
*/
|
||||
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
|
||||
* must already exist in the database.
|
||||
*/
|
||||
async importRelations(data: object): object;
|
||||
|
||||
/**
|
||||
* Backup database
|
||||
*
|
||||
* @param path: path to file to store the backup.
|
||||
*/
|
||||
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.
|
||||
*/
|
||||
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 rels: the relations to import.
|
||||
*/
|
||||
async importRelationsFromBackup(path: string, rels: Array<string>): object;
|
||||
}
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run
|
||||
|
||||
```bash
|
||||
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,
|
||||
and `.dll` on Windows) under the `../target/` folder (you may need to search for it).
|
||||
Copy it to the file `native/6/index.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
|
||||
node example.js
|
||||
```
|
||||
|
||||
under this directory.
|
||||
@ -0,0 +1,20 @@
|
||||
# Cozo Python库
|
||||
|
||||
[](https://pypi.org/project/cozo_embedded/)
|
||||
|
||||
Native bindings for embedding [CozoDB](https://github.com/cozodb/cozo) in Python, providing the
|
||||
`cozo_embedded` package.
|
||||
|
||||
You are not supposed to be using this package directly in your code. Use [PyCozo](https://github.com/cozodb/pycozo),
|
||||
which depends on this package.
|
||||
|
||||
To build this package, you need to install the Rust toolchain
|
||||
as well as the [maturin](https://github.com/PyO3/maturin) python package.
|
||||
Then run
|
||||
|
||||
```bash
|
||||
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)
|
||||
and [build](https://www.maturin.rs/distribution.html) this package.
|
||||
@ -0,0 +1,86 @@
|
||||
# Cozo WASM库
|
||||
|
||||
This crate provides Cozo web assembly modules for browsers.
|
||||
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.
|
||||
To learn how to use CozoDB (CozoScript), follow the [tutorial](https://github.com/cozodb/cozo-docs/blob/main/tutorial/tutorial.ipynb)
|
||||
first and then read the [manual](https://cozodb.github.io/current/manual/). You can run all the queries
|
||||
described in the tutorial with an in-browser DB [here](https://cozodb.github.io/wasm-demo/).
|
||||
|
||||
## Installation
|
||||
|
||||
```
|
||||
npm install cozo-lib-wasm
|
||||
```
|
||||
|
||||
Alternatively, you can download `cozo_wasm-<VERSION>-wasm32-unknown-unknown.zip`
|
||||
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
|
||||
|
||||
```js
|
||||
import init, {CozoDb} from "cozo-lib-wasm";
|
||||
```
|
||||
|
||||
and call
|
||||
|
||||
```js
|
||||
let db;
|
||||
init().then(() => {
|
||||
db = CozoDb.new();
|
||||
// db can only be used after the promise resolves
|
||||
})
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
```ts
|
||||
export class CozoDb {
|
||||
free(): void;
|
||||
|
||||
static new(): CozoDb;
|
||||
|
||||
run(script: string, params: 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;
|
||||
}
|
||||
```
|
||||
|
||||
Note that this API is synchronous. If your computation runs for a long time,
|
||||
**it will block the main thread**. If you know that some of your queries are going to be heavy,
|
||||
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
|
||||
|
||||
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
|
||||
wasm-pack build --target web --release
|
||||
```
|
||||
|
||||
and the environment variable `CARGO_PROFILE_RELEASE_LTO=fat`.
|
||||
|
||||
The important option is `--target web`: the above usage instructions only work for this 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,
|
||||
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.
|
||||
@ -0,0 +1,3 @@
|
||||
# Cozorocks
|
||||
|
||||
对RocksDB C++接口的封装。
|
||||
@ -0,0 +1,87 @@
|
||||
# CozoServer
|
||||
|
||||
[](https://github.com/cozodb/cozo/releases)
|
||||
|
||||
This document describes how to set up cozoserver.
|
||||
To learn how to use CozoDB (CozoScript), follow
|
||||
the [tutorial](https://github.com/cozodb/cozo-docs/blob/main/tutorial/tutorial.ipynb)
|
||||
first and then read the [manual](https://cozodb.github.io/current/manual/). You can run all the queries
|
||||
described in the tutorial with an in-browser DB [here](https://cozodb.github.io/wasm-demo/).
|
||||
|
||||
## 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 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 `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run
|
||||
|
||||
```bash
|
||||
cargo build --release -p cozoserver -F compact -F storage-rocksdb
|
||||
```
|
||||
Loading…
Reference in New Issue