8.1 ActorDB configuration files
ActorDB configuration files:
- app.config - where to store data, mysql protocol port.
- vm.args - set name of node (also erlang vm tweak parameters, which you should probably leave default).
- init.example.sql - initialize cluster, add users and set schema using an sql script
app.config and vm.args need to be set on every node.
init.sql needs to be created by the user to set nodes, users and initial schema. Settings can later be changed using actordb_console or by creating a second file and applying sql statements from it.
On install, default configuration files are placed in /etc/actordb or whichever is equivalent for your platform.
Default example initialize script is divided into three sections. First section which initializes cluster is mandatory. Setting schema can be done later, users can be added at any time.
--WARNING: Every sql statement must be in its own line. -- First initialize node. Create group, create node and create root user. Only this created -- user is able to change schema or change configuration. Once initialization is done -- console will be connected as this user. Every user created in this stage will have all privileges. -- Which means you should not create more than one. Add additional users later. use config insert into groups values ('grp1','cluster') -- localnode() is whatever is in vm.args (-name ....) for node we are connected to. insert into nodes values (localnode(),'grp1') CREATE USER 'root' IDENTIFIED BY 'rootpass' commit -- Still in config db, now add second user to run queries with CREATE USER 'myuser' IDENTIFIED BY 'mypass' -- * means user has access to all actor types GRANT read,write ON * to 'myuser' -- We could also set a user that only has access to type1 actors with -- CREATE USER 'type1user' IDENTIFIED BY 'type1pass' -- GRANT read,write ON type1 to 'type1user'; commit -- Set schema use schema actor type1 CREATE TABLE tab (id INTEGER PRIMARY KEY, txt TEXT) CREATE TABLE tab1 (id INTEGER PRIMARY KEY, txt TEXT) ALTER TABLE tab ADD i INTEGER CREATE TABLE tabx (id INTEGER PRIMARY KEY CHECK (typeof(id) == 'integer'), txt TEXT CHECK (typeof(id) == 'text')) actor type2 CREATE TABLE asdf (id INTEGER PRIMARY KEY AUTOINCREMENT, txt BLOB) -- KV type of actor. This means counters is a sharded table across all nodes. actor counters kv CREATE TABLE actors (id TEXT UNIQUE, hash INTEGER, val INTEGER) -- Another KV type. This one with a nother sub table. -- Any sub table must use foreign key on actors.id and have "on delete cascade" actor filesystem kv CREATE TABLE actors (id TEXT UNIQUE, hash INTEGER, size INTEGER) CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, fileid TEXT, uid INTEGER, FOREIGN KEY (fileid) REFERENCES actors(id) ON DELETE CASCADE) commit
The above example sets a schema with 4 different types of actors. These actor types are completely independent.
Schema statements are permanent. Modifying schema at a later time results in adding lines to schema, never replacing any of them.
8.3 Setup guide
FOR EVERY NODE
- 1. Install package
- 2. Open /etc/actordb/vm.args and set name for node in format: nodename@ipordomain. Changing the cookie is good practice but not mandatory. Cookie has to be the same on every server.
- 3. OPTIONAL: Open /etc/actordb/app.config and set "main_db_folder" to something other than default. You can also specify additional DB folders on different hard drives.
- 4. Run: sudo actordb start
ON ONE NODE
- 1. Create your init.sql file, recommended path is /etc/actordb/init.sql
- 2. Run: actordb_console -f /etc/actordb/init.sql
8.4 Changing schema
Changing schema in ActorDB means adding new sql statements. So when a new actor gets created, ActorDB will initialize it with the original schema statements and any additional ones that are set later. Existing actors who have already been created before a schema change will execute only the new statements.
- 1. Create a new file named /etc/actordb/v2.sql
- 2. Add lines:
- use schema
- actor mytype
- CREATE TABLE....
- ALTER TABLE....
- 2. Run: actordb_console -f /etc/actordb/v2.sql
8.5 Adding a cluster
- 1. Do steps 8.3.1-8.3.4 for every node in cluster.
- 2. Run actordb_console connect it to one of the active servers.
- 3. Insert to groups, nodes and commit. You must specifiy nodes with full name (like: 'firstname.lastname@example.org').
8.6 Building ActorDB
- 1. Clone from github
- 2. make package
- 3. Release should be generated in: ./package/packages
8.7 Running ActorDB development mode
- 1. git clone https://github.com/biokoda/actordb.git
- 2. cd actordb
- 3. make
- 4. ./startdev.sh
- 5. (in a new terminal) ./actordb_console -f etc/init.sql
You can now execute commands in the erlang console: actordb:exec("actor type1(actor1) create; select * from tab;").