diff options
Diffstat (limited to 'README.md')
| -rwxr-xr-x | README.md | 52 |
1 files changed, 31 insertions, 21 deletions
@@ -1,8 +1,21 @@ -ETDB +METRIC ==== To enable edge computing in its full capacity, a crucial requirement is to manage the state of edge applications, preferably in database that provides the full features of SQL including joins and transactions. The key challenge here is to provide a replicated database for the edge that can scale to thousands of geo-distributed nodes. Existing solutions either provide semantics that are too weak (PostgreSQL replicates asynchronously) or too strong and hence expensive to realize in a geo-distributed network with its WAN latencies and complex failure modes (MariaDb, Spanner, provide full transactionality). Inspired by entry consistency in shared memory systems, wherein only the lock holder for an object obtains sequential consistency for the object, we define the notion of an entry transactional database, which is a novel partitioned database in which only the “owner” of a partition obtains full ACID transactionality. In this work, we define the semantics of an entry transactional database, describe the hard challenges faced in building it and present a novel middleware called mdbc that combines existing SQL databases with an underlying geo-distributed entry consistent store to provide entry transactional semantics. Further, we present crucial use cases such as a federated regional controller for the network control plane and a state management service for edge mobility enabled by entry transactionality. +## Dependencies + +Given that METRIC is still a project in development, we are using newer versions (aka not release) of MUSIC, such that once +it reaches production it matches the latest MUSIC version. So for now we cannot use maven repositories to pull MUSIC. Follow +the next steps to compile and add the right version of music locally: +```bash +cd /tmp/ +git clone https://gerrit.onap.org/r/music +cd music +git checkout dev-cassandra-only +mvn install -Dfile=target/MUSIC.jar -DpomFile=./pom.xml -DskipTests +``` + ## Running METRIC run cassandra (tested with v3.11) @@ -64,25 +77,22 @@ It requires three parameters: src/main/java/com/att/research/mdbc/examples +## Building METRIC - - -## Building ETDB - -ETDB is built with Maven. This directory contains two pom.xml files. +METRIC is built with Maven. This directory contains two pom.xml files. The first (*pom.xml*) will build a jar file to be used by applications wishing to use the -ETDB JDBC driver. +MDBC JDBC driver. The second (*pom-h2server.xml*) is used to built the special code that needs to be loaded -into an H2 server, when running ETDB against a copy of H2 running as a server. +into an H2 server, when running METRIC against a copy of H2 running as a server. -### Building the JBoss ETDB Module +### Building the JBoss METRIC Module There is a shell script (located in `src/main/shell/mk_jboss_module`) which, when run in the mdbc source directory, will create a tar file `target/mdbc-jboss-module.tar` which can be used as a JBoss module. This tar file should be installed by un-taring it in the $JBOSS_DIR/modules directory on the JBoss server. -## Using ETDB +## Using METRIC This package provides a JDBC driver that can be used to mirror the contents of a database to and from Cassandra. The mirroring occurs as a side effect of execute() statements against @@ -96,7 +106,7 @@ communicate the existence of dirty rows to other Cassandra replicas (with the Ca Mixin, the table is called DIRTY\_\_\_\_ and there is only one table). Dirty rows will be copied, as needed back into the database from Cassandra before any SELECT. -### To use directly with JDBC + 1. Add this jar, and all dependent jars to your CLASSPATH. 2. Rewrite your JDBC URLs from jdbc:_yourdb_:... to jdbc:mdbc:.... @@ -106,7 +116,7 @@ Dirty rows will be copied, as needed back into the database from Cassandra befor Class.forName("com.att.research.mdbc.ProxyDriver"); The following properties can be passed to the JDBC DriverManager.getConnection(String, Properties) -call to influence how ETDB works. +call to influence how METRIC works. | Property Name | Property Value | Default Value | |--------------------|--------------------------------------------------------------------------------|---------------| @@ -114,7 +124,7 @@ call to influence how ETDB works. | MDBC\_MUSIC\_MIXIN | The mixin name to use to select the MUSIC mixin to use for this connection. | cassandra2 | | myid | The ID of this replica in the collection of replicas sharing the same tables. | 0 | | replicas | A comma-separated list of replica names for the collection of replicas sharing the same tables. | the value of myid | -| music\_keyspace | The keyspace name to use in Cassandra for all tables created by this instance of ETDB. | mdbc | +| music\_keyspace | The keyspace name to use in Cassandra for all tables created by this instance of METRIC. | mdbc | | music\_address | The IP address to use to connect to Cassandra. | localhost | | music\_rfactor | The replication factor to use for the new keyspace that is created. | 2 | | disabled | If set to true the mirroring is completely disabled; this is the equivalent of using the database driver directly. | false | @@ -182,7 +192,7 @@ probably need to make changes to the _connectionProperties_ attribute. ## Databases Supported -Currently, the following databases are supported with ETDB: +Currently, the following databases are supported with METRIC: * H2: The `H2Mixin` mixin is used when H2 is used with an in-memory (`jdbc:h2:mem:...`) or local file based (`jdbc:h2:path_to_file`) database. @@ -195,29 +205,29 @@ or local file based (`jdbc:h2:path_to_file`) database. ## Testing Mixin Combinations -The files under `src/main/java/com/att/research/mdbc/tests` can be used to test various ETDB +The files under `src/main/java/com/att/research/mdbc/tests` can be used to test various METRIC operations with various combinations of Mixins. The tests are controlled via the file `src/main/resources/tests.json`. More details are available in the javadoc for this package. -## Limitations of ETDB +## Limitations of METRIC -* The `java.sql.Statement.executeBatch()` method is not supported by ETDB. +* The `java.sql.Statement.executeBatch()` method is not supported by METRIC. It is not prohibited either; if you use this, your results will be unpredictable (and probably wrong). * When used with a DB server, there is some delay as dirty row information is copied from a table in the database, to the dirty table in Cassandra. This opens a window during which all sorts of mischief may occur. -* ETDB *only* copies the results of SELECTs, INSERTs, DELETEs, and UPDATEs. Other database -operations must be performed outside of the purview of ETDB. In particular, CREATE-ing or +* METRIC *only* copies the results of SELECTs, INSERTs, DELETEs, and UPDATEs. Other database +operations must be performed outside of the purview of METRIC. In particular, CREATE-ing or DROP-ing tables or databases must be done individually on each database instance. * Some of the table definitions may need adjusting depending upon the variables of your use -of ETDB. For example, the MySQL mixin assumes (in its definition of the ETDB_TRANSLOG table) +of METRIC. For example, the MySQL mixin assumes (in its definition of the METRIC_TRANSLOG table) that all table names will be no more than 255 bytes, and that tables rows (expressed in JSON) will be no longer than 512 bytes. If this is not true, you should adjust, edit, and recompile. -* ETDB is limited to only data types that can be easily translated to a Cassandra equivalent; +* METRIC is limited to only data types that can be easily translated to a Cassandra equivalent; e.g. BIGINT, BOOLEAN, BLOB, DOUBLE, INT, TIMESTAMP, VARCHAR * To find the data types that your database is currently using run the following command: |