Tutorial

K9db provides a MySQL-like interface to developers and applications to interact with.

Many common SQL operations and queries should with K9db without much modification. However, you are required to add annotations to the schema to reflect application-specific information about the relationships between data and users and the application's compliance policy. K9db also introduces additional SQL-like commands helpful for compliance.

Running K9db: using the release docker image

The quickest way to get a K9db server running is the pre-built release image (see Using Docker):

docker pull kinanbab/k9db:latest
docker run -d --name k9db -p 10001:10001 -v k9db-data:/var/lib/k9db kinanbab/k9db:latest

The server listens on port 10001, which the command above publishes on your host, so you can connect to it as described below.

To stop the server, stop the container. K9db shuts down cleanly, and the next docker start reloads the database as it was:

docker stop k9db
docker start k9db

The database lives in the k9db-data docker volume and persists across containers, so removing the container is not enough to reset it. To start from a fresh, empty database, remove the volume as well:

docker stop k9db && docker rm k9db && docker volume rm k9db-data

Running K9db: using the dev docker image or a bare metal installation

If you built K9db from source (inside the dev docker container, or on a bare metal installation), start the server with bazel from the repo root:

bazel run :k9db  # --config=opt for optimized mode

By default, K9db's server will listen over port 10001 and hostname 127.0.0.1. Unlike MySQL, every instance of K9db only manages a single database. If you want to have multiple databases, you will need to run several instances of K9db server, each at a different port and with a different database name. By default, databases are stored in /tmp/k9db_<db_name>.

All these defaults can be changed using command line flags:

# View command line arguments
bazel run :k9db -- --help
   Flags from k9db/proxy/src/ffi/ffi.cc:
      -consistent (Dataflow consistency with futures) type: bool default: true
      -db_name (Name of the database) type: string default: "k9db"
      -db_path (Path to where to store db) type: string default: ""
      -hostname (Hostname to bind against) type: string
       default: "127.0.0.1:10001"
      -workers (Number of workers) type: uint32 default: 1

# Run K9db at a different port and for a different database.
bazel run :k9db -- --hostname=127.0.0.1:10005 --db_name=test_db

You can stop a foreground running K9db server at any time using ctrl-c. K9db server will try to shutdown cleanly when possible: it will wait for all open sessions to close and for all pending operations to commit before shutting down.

If running in the background, you can use kill <pid> to similarly shut the server down.

Whenever K9db is started, it will look at the database path and name to identify if it already exists (due to earlier runs of the server), and will reload the schema and various internal state to pick up where it left of. If you want to start with a fresh database from scratch, you will need to delete the database directory yourself, e.g. rm -rf /tmp/k9db_<db_name>.

Note: if you are running inside the dev docker container, make sure the container publishes port 10001 (our docker run command does) so that you can connect to K9db from your host.

Connecting to K9db server from the command line

You can connect to a running K9db server using a MySQL-compatible command line client. We recommend using MariaDB's client, which comes in our provided Docker container.

Note: MySQL clients version 9 and later can not connect to K9db: they removed the mysql_native_password authentication plugin, which is the only one K9db's proxy supports (connections fail with Cannot run backend via MySqlIntermediary in the K9db log). Use a MariaDB client (e.g. apt-get install mariadb-client, or brew install mariadb on Macs) or a MySQL client older than 9. If your client complains about SSL, pass --skip-ssl, as K9db does not support SSL connections. If you do not want to install a client, you can use a dockerized one:

docker run --rm -it mariadb:10.11 mariadb -h host.docker.internal -P 10001 --skip-ssl

After you run a K9db server as above, open a new terminal and connect to the server as below.

mariadb -P10001
> # now connected to K9db server running at port 10001
> # you can now feed K9db some SQL commands.
-- Instructs the server to echo every command to its log before processing it
SET echo;

You can close your connection at any time using ctrl+d or exit. You can connect to K9db from many clients (e.g. separate terminals) at the same time.

You can also connect and execute an SQL file in one shot, rather than having to type in the commands from the file one at a time.

mariadb -P10001 < examples/websubmit.sql

Connecting to K9db from an application

You can use any mysql connector/driver to connect to K9db from your applications. We tested this for C++, Java, and Rust using mariadb-connector-cpp, org.mariadb.jdbc:mariadb-java-client, and mysql_async respectively.

When specifying the connection string, you can set the username, password, and database to any values, as K9db ignores those and instead uses the database name it was started with from the command line. Use server side prepared statements to make the most of K9db's integrated cache. We do not currently support SSL connections. The same authentication caveat as above applies: the connector must support mysql_native_password (MariaDB connectors do; MySQL connectors version 9 and later do not).

You can find an example of this in examples/PreparedStatements.java and experiments/ownCloud/src/db.rs.