stubs for more localized README
parent
34d4b5372c
commit
cd43966389
@ -0,0 +1,5 @@
|
|||||||
|
# Cozo-core
|
||||||
|
|
||||||
|
[![Crates.io](https://img.shields.io/crates/v/cozo)](https://crates.io/crates/cozo)
|
||||||
|
|
||||||
|
Cozo数据库核心部分的实现。
|
@ -0,0 +1,32 @@
|
|||||||
|
# Cozo C语言库
|
||||||
|
|
||||||
|
[![C](https://img.shields.io/github/v/release/cozodb/cozo)](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库
|
||||||
|
|
||||||
|
[![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.
|
||||||
|
|
||||||
|
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库
|
||||||
|
|
||||||
|
[![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
|
||||||
|
`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
|
||||||
|
|
||||||
|
[![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), 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