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.

Starting a K9db server

You can start a K9db server by navigating to this repo's root directory and running the following command.

bazel run :k9db

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

Stopping a K9db server

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>.

Connecting to K9db server from the command line

You can connect to a running K9db server using any MySQL-compatible command line client. We recommend using MariaDB's client, which comes in our provided Docker container. 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.

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