Console design

[lriuui0x0]

Grakn Core

NOTE: The console change has been drastically modified. Please check the other comments below.

Below is the list of commands we want to support within console.

exit

Exit the console.

help

Print the list of commands to support

database list

List the databases on the server. We can also consider using a different flavoured syntax list database which is more readable, but less hierarchical when there're multiple types of entities you need to manage.

database create <db>

Create a database.

database delete <db>

Delete a database. The <db> argument is optional. When not specified, the command will try to delete the currently connected database.

database use <db>

Switch the database the user is currently connecting to. In the prompt we will show what's the database that's currently connected to. It's possible for the user not connecting to any database (as opposed to creating a default database grakn on the fly in the current behaviour).

<query>

Run a query and commit it immediately. This is different from the current behaviour, which will not commit any changes unless explicit commit. This is more friendly and more consistent with other DBMS.

The session type will be inferred from the query type. The transaction type will always be write.

We need to take extra care that the command keywords don't clash with query keywords (match, insert, delete ...), however, this is more user friendly.

source <file1> <file2> ...

Run a list of files and commit them. Each file can contain multiple queries.

The session type will be infererd from the first query that's parsed.

Some other command keywords we thought about are run, execute.

transaction

Start a new transaction. This alters the following query and source commands that they will not commit automatically but batched in the current transaction.

We will show an indicator at prompt suggesting the user that it's now within a transaction.

rollback

Rollback the current transaction.

commit

Commit the current transaction.

close

Close the current transaction without commit it. This is useful when the user opens a transaction, but then decides not to use the transaction, so he needs a way to escape from the current transation state.

If we don't provide this command, the user can do rollback then commit which commits an empty transaction.

Other possible command keywords are transaction / transaction close, since just having close is slightly to general. Or transaction begin / transaction end. Or just begin / end.

option <key> <value>

Change the future options to use for transactions. For example, we can have option infer true/false, or option batch_size 1000

Command line interface

Given that most of the commands can be done within the console, we don't need to have many mandatory command line arguments. The only thing we need to provide is the server address, and we can even have a default value for that.

One question is what functionality of console commands should we expose to the command line interface. One idea was to expose every command so that providing them in the command line arguments will be equivalent to running the commands in the interactive mode in sequence, e.g.:

./console --database-use grakn --transaction --source <file1> --query 'insert $x isa person;' --commit

This has the advantage of giving the command line interface the same power as interactive commands, also the semantics of the argument combination is clear to communicate.

Note that this usage is compatible with typical interactive usage of console. Say the user wants to get into the console and connect to database grakn at the same time, we can just say:

./console --database-use grakn

Another question is when we run console command, should we get into interactive mode or not? What we can do is, when certain options are present in the arguments, we don't get into interactive mode, otherwise we get into interactive mode.

Command line functionalities

The following functionalities will be implemented:

• Syntax highlighting
• Easy line navigation and editing
• Multiline query support
• History

Cluster permission model

We decided to have three level permission model: user -> role -> permission. Each user can have any number of roles, and each role can have any number of permissions.

Currently the permission levels are coarse. We will have the following permissions:

• admin: user, role, database management
• read <db>/all: reading access to <db> or all databases
• write <db>/all: writing access to <db> or all databases.

Initially we will have one user root, with password root, assigned to one role root, with all the above permissions.

These permission data (and other future cluster management data), will be saved in a database system which will be modelled by normal grakn schema. We leverage raft to replicate these data.

Below is the list of commands we want to support:

role create <role> <permission1> <permission2> ...

Create a role with following permissions. The permission list can be empty.

role grant <permission1> <permission2> ...

Add following permissions to the role.

role revoke <permission1> <permission2> ...

Remove following permissions to the role.

user create <user> <role1> <role2> ...

This command will prompt to create a password for the user. Grant the roles to the user, the role list can be empty.

user grant <role1> <role2> ...

Add following roles to the user.

user revoke <role1> <role2> ...

Remove following roles to the user.

user delete <user>

Delete the user.

user use <user>

Switch the current logged in user, will be prompted for password.

user password

Prompt to change the current user's password.

Command line interface

Given that we pretty much cannot do anything without knowing the user, we disallow people interact with console without user specified. Therefore we will add the following mandatory command line arguments:

./console --user root --password <password>

Cluster membership change

Currently how cluster should handle membership change is still not very clear, as that depends on a deeper look into how raft handles membership changes, as well as more detailed thought on the UX side.

Below are some preliminary thoughts on what are the semantics of membership change commands we can consider supporting.

• start: Start the current server as single node cluster, or the configuration saved in the log.
• stop: Stop the current server without affecting the log and data.
• join: Clean all of current data (prompt for confirmation) and join an existing cluster.
• leave: Leave the current cluster and form a single node cluster.
• list: List the current information in the cluster.

There're following points that needs to be considered while designing this:

• Do we support a file of static configuration or not? Having a static configuration file will face the problem of:
  • Dynamic changes after cluster starts run out of sync with the static file.
  • There needs to be an extra bootstrapping process that validates the static cluster configuration across nodes.
• We should be able to use cluster in the same way as using core.
• How easy is it to operate with cluster management commands?

[lriuui0x0]

We change the console design to be two level REPL:

First the user will be prompted to login into the database. Once logged in, that user will be the user for the entire console session. There's no mechanism to switch user.

In the first level, we allow database/user/permission management command.

In the second level, we allow people type queries. To get into the second level, we need to fully determine the transaction to use. E.g. transaction open <database> schema/data read/write <options>. This model is more aligned with client API and more consistent with our model, with some sacrifice on convenience.

Within the second level, we can run query, source query files, and allow transaction management commands like commit, rollback and close. The details of these commands haven't been fleshed out yet.

[lriuui0x0]

This has been implemented.