# CedarDB - Getting Started

CedarDB is a relational database management system.
CedarDB supports a large part of standard SQL with a syntax similar to PostgreSQL.
You can run CedarDB either locally via the `cedardb --interactive` REPL, or with a `psql` client
via the `cedardb` server that communicates over the PostgreSQL wire protocol.

CedarDB implements SQL language compatibility with PostgreSQL.
For an in-depth overview of the features, please refer to the
documentation: https://cedardb.com/docs/

## Installation

CedarDB can be run standalone without any system setup dependencies.
CedarDB currently only supports linux.

## Setup

CedarDB has two main modes that users can use to interact with the database:
`server` and `interactive`.

### `interactive`

This mode provides an interactive shell to directly open a database and query
it using SQL.

```shell
# Create a new database - will create a new subdirectory mydb
./cedardb --interactive --createdb mydb
# For a list of options see:
./cedardb --help
```

In the shell you can directly enter SQL queries and commands.
To load a table into the database, you can use the copy command:

```sql
create table example
(
    i int
);
copy example from 'example.csv' delimiter '|' null 'null';
```

For an in-depth reference of the syntax, you can refer to the
[Documentation](https://cedardb.com/docs/references/sqlreference/).

The REPL supports the common readline keyboard shortcuts, e.g., CTRL + R to
search the history.
It also supports backslash commands, e.g., to execute commands from a file:

```sql
\i
schema_definition.sql
-- For a list of options see:
\?
```

### `server`

If you don't provide an `interactive` flag, CedarDB runs in server mode, 
i.e. as a server daemon that allows outside connections to the database.
As with any server process, you should be mindful how this process can
interact with the rest of the system and which users can use it.

After the initial startup, the CedarDB server does not allow arbitrary
connections.
During this state, you can only connect via a local domain socket as the same
OS user that also runs the server.

```shell
# Run the server interactively:
./cedardb mydb
# This assumes you've created the database beforehand. Otherwise run ./cedardb -createdb mydb

# Connect in a separate terminal as the postgres DB superuser:
psql -h /tmp -U postgres
```

Now you can manage DB users via SQL:

```sql
-- Create a user that can manage the database
create user test superuser; -- You can also grant rights more fine-grained.
create database test;
alter user test with password '1234';
```

Afterward, you can connect with that DB user via IP:

```shell
# Run the server on one machine:
# '::' specifies all IPv4 and IPv6 connections, if you do not specify this,
# CedarDB only listens on localhost
./server mydb/test.db --address=::
# On the same machine, connect via:
psql -h localhost -U test
# But you can also connect over the network
psql -h cedardb.example.com -U test
```
### Resource usage

By default, CedarDB uses 40% of the available system memory for the page cache and 40% for working memory.
Consider setting the start-up parameter via an environment variable to a setting that plays works for your setup:

```shell
export BUFFERSIZE=1G
```

CedarDB also uses *all* threads of the system for best performance.
This is intended behaviour, but might generate high load on your machine.
If you want to keep other applications responsive, consider starting CedarDB with `nice`.
Alternatively, you can restrict the number of threads that CedarDB uses.
However, keep in mind that this comes with a hard performance limit for CedarDB.

```shell
export PARALLEL=8
```

### License

(c) CedarDB GmbH. All rights reserved.
For licenses of third-party code see:
```sh
./cedardb -license
```
