ITTIA DB SQL Getting Started Guide

Linux

June 2021
Contents

Introduction.....................................................................................................................................................................3
About ITTIA DB SQL Database ...............................................................................................................................3
Obtaining ITTIA DB SQL for Linux........................................................................................................................3
Running the Database for the First Time ..........................................................................................................4
Connecting to the ITTIA DB Console with a Browser..................................................................................4
Process Time Series Embedded Data .............................................................................................................5
Concurrent Read and Write to Flash Media ................................................................................................7
Secure Data on the Device with DB-SEAL ....................................................................................................8
ITTIA DB SQL Package Contents............................................................................................................................9
Programs ......................................................................................................................................................................9
Libraries .......................................................................................................................................................................9
Documentation....................................................................................................................................................... 10
Technical Support ...................................................................................................................................................... 10
Introduction
The purpose of this document is to provide information on data processing, management,
and distribution for Linux on PC hardware. The target audience for this document is
developers.

About ITTIA DB SQL Database

ITTIA DB SQL is an embedded relational database management system for intelligent
applications on mobile devices and other embedded systems. ITTIA DB SQL brings robust
data management facilities to bear on the tough data management problems now faced by
embedded developers, in a package that is lightweight, cross-platform, fast, and easy to use.

Obtaining ITTIA DB SQL for Linux

To download ITTIA DB SQL:
1. Visit https://www.ittia.com/downloads
2. Choose Target Platform: Linux x86_64
3. Enter Target Development Board: PC
4. Complete and Submit your contact information

You will receive:

• ITTIA DB SQL package: ittiasql-x.x.x-x86_64-pc-linux.tar.gz
 • License Certificate: ittia_license.dat

Running the Database for the First Time

To download and run ITTIA DB SQL:
1. Transfer ITTIA DB SQL and License Certificate file to the target.
$ cp ittiasql-*-x86_64-pc-linux.tar.gz $HOME/
$ cp ittia_license.dat $HOME/

2. Set the ITTIA_LICENSE environment variable to file name of the License Certificate:
$ export ITTIA_LICENSE=$HOME/ittia_license.dat

3. Extract ITTIA DB SQL on the target hardware:

$ tar xzf -C / $HOME/ittiasql-*-x86_64-pc-linux.tar.gz

4. Run ITTIA DB Console:

$ /opt/ittiadb-*/bin/ittiadb console \
--config-data="ittiadb-console: { default: { database: {\
example: { location: example.ittiadb, access: write, open_mode: create }\
} } }"

This command starts the ITTIA DB Console HTTP server and creates an empty database file
in the current directory.

Connecting to the ITTIA DB Console with a Browser

ITTIA DB Console is a tool for applications and developers to access ITTIA DB SQL through
robust web services with a web-based graphical user interface. It provides a simple yet
powerful way to create and manage data, design schemas, generate simulated data, and test
SQL queries. ITTIA DB Console includes many features to remotely manage data:
1. SQL: Execute SQL statements and queries
2. Database Monitoring: Monitor schema definitions and describe tables
3. Table Schema: Monitor table structures and content (columns, fields, indexes, etc.)
4. Replication: Monitor and configure data distribution settings for both databases and
tables
5. Import and export: Access data in XML or JSON format
To access ITTIA DB Console, open a web browser on the host computer and connect to the
network address of the target hardware. For example:
http://localhost:8080
Process Time Series Embedded Data
ITTIA IoT Stream Processing is a high-performance data processing solution for IoT edge
network devices. An IoT Stream receives data from sensors and other data sources in real
time. Continuous queries process data as it arrives and push the results to applications and
materialized views.
Developers create IoT Streams with SQL create stream statements and write continuous
queries as SQL cselect statements. This tutorial explains how to quickly get started
processing data using only the ITTIA DB IoT Stream server and a web browser.
An IoT Stream is created with an SQL create stream statement. Go to the Continuous Query
tab and execute this statement to create an IoT Stream named drill_sensors.
create stream drill_sensors (
sensor_id bigint primary key,
start_time timestamp not null,
end_time timestamp not null,
temperature_C float64 not null,
pressure_Pa float64 not null
)

You can use the ITTIA DB Console to submit data to an IoT Stream directly from a web
browser. Open ITTIA DB Console in a new browser window, select drill_sensors from the
sidebar, and go to the Content tab.

Press the Generate button to start generating data at a constant sample rate. Press
Increment or Random next to any field to change the value over time.
A continuous query processes new data from a data source and displays changes to the
query result state in real time.
To manually execute a continuous query in your web browser, open ITTIA DB Console in a
new browser tab or window, select drill_sensors from the sidebar. Go to the Query tab and
execute this statement:
cselect *
from drill_sensors
where temperature_C > 70

The results of this query will initially be empty. But when data matching the where clause is
submitted by a sensor_data data source, it will be immediately displayed in the continuous
query browser tab or window. Furthermore, if data is submitted that does not match the
where clause, the row corresponding to that sensor will be immediately removed.
Multiple continuous queries can be run at the same time. To run another query, open the
same drill_sensors Query tab but in another browser tab. Execute this statement:
cselect sensor_id,
8.314 * (temperature_C + 273.15) / pressure_Pa
as volume_m3_per_mol
from drill_sensors

This query calculates the volume per mol of each sensor from the ideal gas law, PV=nRT.

Concurrent Read and Write to Flash Media

IoT streams are also integrated with a database storage engine. The results of a stream can
be stored in a database table. To create a database table, click on the database and go to the
Query tab. Execute this statement:
create table high_temperature_events (
sensor_id integer not null,
start_time timestamp not null,
end_time timestamp not null,
temperature_C float64 not null,
primary key (sensor_id, start_time)
)
To put the data of the drill_sensors stream into the high_temperature_events table, click on
drill_sensors and go to the Query tab. Execute this statement:
insert into persistent_database.high_temperature_events
cselect sensor_id, start_time, end_time, temperature_C
from drill_sensors
where temperature_C > 70

Once the data from the drill_sensors stream is in the high_temperature_events table, more
traditional SQL queries can be executed in the Query tab. This can be useful to answer
questions that require looking back at the data over a long period of time. For example, the
following query identifies the sensors that spent the most time with a temperature
exceeding 70 degrees Celsius over the last 24-hour period.
select sensor_id,
count(*) as number_of_events,
sum((end_time – start_time) second) as total_duration
from high_temperature_events
where start_time > localtimestamp – interval '1' day
group by sensor_id
order by sum((end_time – start_time) second) desc
fetch first 10 rows only

Secure Data on the Device with DB-SEAL

Though applications can specify multiple different queries that they are interested to run,
there is potential for side channel attacks. An attacker can intercept queries and modify
them by performing injection attacks. To combat this, there is a security agent, called DB-
SEAL, built into the library that keeps track of queries that have been executed. DB-SEAL
uses that data as training data. A developer can then enable a watchdog that rejects any
queries that were not recognized during the training phase. This ensures that the
applications using the database on the board are only running queries only vetted by the
developers.
ITTIA DB SQL Package Contents
The contents of the ITTIA DB SQL SDK are extracted to the /opt/ittiadb-${VERSION}/
directory. This directory has the following folder structure:

Folder Description
include Header files for ITTIA DB SQL
lib ITTIA DB SQL libraries
bin Utilities and applications
share/doc/ittiadb/manuals Manuals
examples Example programs
src Supplemental database support source code

Programs
ITTIA DB SQL includes an interactive utility that can be run with the command ittiadb.
ITTIA DB SQL includes a light-weight data server for shared access to database files. Run
the dbserver command to start the data server.

Libraries
The ITTIA DB SQL kernel is a software library that can be directly embedded in an
application or accessed through a separate server process. The database kernel provides a
transactional C API that the application can use directly or through a variety of higher-level
APIs, include the ITTIA DB SQL C++ API, libstorage.
Documentation
ITTIA DB documentation includes:
6. Embedded Database Manual: The essential guide to ITTIA DB usage and software
development.

7. C API Reference: Reference manual for the ITTIA DB C API.

8. C++ API Reference: Reference manual for the ITTIA DB C++ API.

Technical Support
Do you need assistance with edge device data processing and management? Contact
support@ittia.com to request support.

An evaluation license includes 30-day technical support.

 Disclaimer

Information in this document is provided solely to enable system and software implementers
to use ITTIA products. No express or implied copyright license is granted hereunder to design
or implement any database management system software based on the information in this
document. ITTIA reserves the right to make changes without further notice to any products
described herein. ITTIA makes no warranty, representation or guarantee regarding the
suitability of its products for any particular purpose, nor does ITTIA assume any liability
arising out of the application of or use of any product, and specifically disclaims any and all
liability, including without limitation consequential or incidental damages. Statistics and
parameters provided in ITTIA white papers and data sheets can and do vary in different
applications and actual performance may vary over time. All operating parameters must be
validated for each customer application by customer's technical experts. ITTIA and the ITTIA
logo are trademarks or registered trademarks of ITTIA L.L.C. in the U.S. and other countries.
All other product or service names are the property of their respective owners.

Copyright (c) 2021 ITTIA L.L.C. All rights Reserved. References in this document to ITTIA
products and services do not imply that ITTIA intends to make them available in every
country.