CedarDB as Server
This guide will show you how you can launch CedarDB as a server, create users and configure it to accept outside connections.
Prerequisites
CedarDB currently supports Linux. You can run it standalone without any system setup dependencies.
The CedarDB distribution comes with a binary called server
, located in the bin
directory.
This binary launches a server daemon that allows outside connections to the database.
Launching the server
Create a database
The server needs to connect to an existing database. If you have followed the Quick Start Guide you did already create a database and can skip this step.
Otherwise, create a new database directory:
mkdir mydb
Then start the sql shell, instructing it to initialize a new database (called test
, for example):
bin/sql --createdb mydb/test.db
finally exit the shell with CTRL-D
.
Launch the server process
Run the server interactively:
bin/server mydb/test.db
After this 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 launched the server process.
Connect to the server via the psql
shell
The server speaks the PostgreSQL wire protocol making it
compatible with a wide array of PostgreSQL supporting tools, the most important being psql
, the default terminal-based
front-end to PostgreSQL.
psql
. On Ubuntu, for example, it is provided by
the postgresql-client
package.Connect to the server in a separate terminal via a local domain socket as the postgres DB super user:
psql -h /tmp -U postgres
Create a new user
You probably do not want to execute all your queries as the default superuser, or only connect via domain socket, so
create a new user and initialize it from within the psql
shell:
-- Create a user that can manage the database
create user test superuser; -- You can also grant rights more fine-grained.
create database test; -- By default the user will use the database with its name, so let's create one.
alter user test with password '1234';
Connecting to the server
You can now connect to CedarDB with your newly created user over IP:
psql -h localhost -U test
If you want to connect from a different machine, you have to instruct CedarDB to accept non-local connections:
# '::' specifies all IPv4 and IPv6 connections
bin/server mydb/test.db --address=::
Afterward, you can connect remotely:
psql -h CedarDB.example.com -U test
Manage CedarDB with systemd
You can optionally let systemd automatically launch the CedarDB server whenever a new connection request comes in using
its Socket Activation
feature.
First create the following service and socket file, replacing the path to the CedarDB server binary and database file with your own values.
[Unit]
Description=CedarDB server
After=network.target
[Service]
Type=simple
Environment=COMPILATIONMODE=a
ExecStart=path/to/bin/server -verbose path/to/your/db/dbname.db
[Unit]
Description=Socket activation unit for CedarDB server
PartOf=cedardb-server.service
[Socket]
ListenStream=/tmp/.s.PGSQL.5432
ListenStream=127.0.0.1:5432
ListenStream=[::1]:5432
You can now use the following script to create an CedarDB service and register it with systemd:
#!/usr/bin/env bash
set -euo pipefail
SYSTEMD_PATH="${1:-$HOME/.config/systemd/user}"
install <(< cedardb-server.service sed "s:XXX:$PWD:g") "$SYSTEMD_PATH/cedardb-server.service"
install cedardb-server.socket "$SYSTEMD_PATH/cedardb-server.socket"
systemctl --user daemon-reload
You have now installed the CedarDB systemd service. Start socket activation with:
systemctl --user start cedardb-server.socket"