machbase/machbase-neo repository overview

⁠Machbase Neo

Machbase⁠ is the fastest time-series database for IoT in the world implemented in C++. machbase-neo is an IoT Database Server that embedding the Machbase engine and provides essential and convenient features to build IoT platforms such as MQTT and HTTP API. It can be installed on machines ranging from Raspberry PI to high-performance servers.

⁠Quick Reference

• How to get started machbase-neo with docker:
  (https://neo.machbase.com/docs/getting-started/installation-docker⁠)
• Supported OS/Architecures:
  linux/amd64, linux/arm64
• Machbase-neo Documentation
  (https://neo.machbase.com⁠)
• Contact Machbase
  (https://www.machbase.com/Contactus⁠)

⁠Quick Start

Running Machbase Neo in Docker is very simple. Follow the steps below.

⁠Run machbase-neo in the background

$ docker run -d                     \
             -p 5652:5652/tcp       \
             -p 5654:5654/tcp       \
             --name machbase-neo    \
             machbase/machbase-neo

you can also run it in the foreground, but in this case, you'll need to prepare another shell.

$ docker run -it                    \
             -p 5652:5652/tcp       \
             -p 5654:5654/tcp       \
             --name machbase-neo    \             
             machbase/machbase-neo

both ways activate machbase-neo automatically.

⁠Enter in Machbase Neo Shell

Direct access to the Machbase Neo Shell.

$ docker exec -it machbase-neo /opt/machbase-neo shell

Can also be accessed using ssh.

• Default User: SYS
• Default Password: manager

$ ssh -p 5652 [email protected]
[email protected]'s password: manager

Then after machbase-neo» prompt, users can query with SQL statements.

machbase-neo» create tag table example (name varchar(20) primary key, time datetime basetime, value double summarized);
executed.
machbase-neo» show tables;
┌────────────────────────────────┐
│ ROWNUM │ DB         │ USER │ NAME    │ TYPE      │
├──────────────────────────────
│      1 │ MACHBASEDB │ SYS  │ EXAMPLE │ Tag Table │
└────────────────────────────────┘

⁠Remote access to machbase-neo shell using ssh-key

Before connecting to machbase-neo shell, you need to generate an SSH key.

$ ssh-keygen -t rsa

After you create the ssh key, run machbase-neo in a different environment.

$ docker pull machbase/machbase-neo
$ docker run -d
             -p 5652-5656:5652-5656/tcp
             --name machbase-neo
             machbase/machbase-neo

By default, you will be prompted to enter your password every time you connect via SSH. However, by registering with the machbase-neo shell, you can set it up to enter your password just once.

$ ssh -l sys -p 5652 192.168.0.116 ssh-key add `cat ~/.ssh/id_rsa.pub`
[email protected]'s password? manager
Add sshkey success

This will allow you to access without having to enter your password every time.

For Example

$ ssh -l sys -p 5652 192.168.0.116 'create table example (v1 int)';
executed.

$ ssh -l sys -p 5652 192.168.0.116 'show tables';
┌────────────────────────────────┐
│ ROWNUM │ DB         │ USER │ NAME    │ TYPE      │
├────────────────────────────────┤
│      1 │ MACHBASEDB │ SYS  │ EXAMPLE │ Log Table │
└────────────────────────────────┘

⁠Access to internal website and Send query

If you mapped the container's 5654 port, you can access this website.

• http://127.0.0.1:5654/⁠

Various features are available on this website. For more details click here⁠.

Additionally, you can use HTTP to send query directly to the database.

$ curl -o - http://127.0.0.1:5654/db/query \
            --data-urlencode               \
            "q=drop table example"

if you want to use more API or SQL, then click here⁠.

⁠Configuration

⁠Volume

You can bind to machbase-neo home path in docker from host directory.

docker run -d
           -v /path/to/host/data:/data 
           -v /path/to/host/file:/file
           machbase/machbase-neo

• /data: machbase-neo home path in docker
• /file: machbase-neo tql path in docker
• -v, --volume: Bind mount a volume.

Even if Docker stops, the host directory of the mounted volume remains.

⁠Exposed Ports

Machbase-neo exposes several ports in Docker.

When run machbase-neo container, you can map host port to container port like this.

$ docker run -d                       \
             -p 5652:5652             \
             -p 5653:5653             \
             -p 5654:5654             \
             -p 5655:5655             \
             -p 5656:5656             \
             --name machbase-neo      \
             machbase/machbase-neo

With this configuration, all requests made to the host port will be forwarded to the container port.

⁠via Docker compose

Save the contents below in docker-compose.yml and place them in your project's root directory.

# docker-compose.yml
version: '3'
services:
  machbase-neo:
    image: machbase/machbase-neo
    container_name: machbase-neo
    hostname: machbase
    volumes:
      - /data:/data
      - /file:/file
    ports:
      - "5652:5652" # sshd
      - "5653:5653" # mqtt
      - "5654:5654" # http
      - "5655:5655" # grpc
      - "5656:5656" # database engine

Then copy below and execute in your project's root direcotry.

$ docker compose up -d

Or:

$ docker compose -f docker-compose.yml up -d

If you want to shut down docker compose, use this.

$ docekr compose down

Then all of the services shut down gracefully.