Databases AWS

MatrixOne 4.2.6 on AWS User Guide

Last updated: 2026-10-25 | Product: MatrixOne 4.2.6 on Ubuntu 24.04 on AWS

Overview

This guide covers launching and using MatrixOne 4.2.6 on Ubuntu 24.04 from cloudimg on Amazon EC2. It is one version of cloudimg's distributed and embedded SQL databases listing on AWS Marketplace; you pick it as the software version when you subscribe and launch. The other databases in the listing are described on the listing's guide hub.

MatrixOne is an open source HTAP database: one engine for transactional and analytical SQL. It speaks the MySQL wire protocol, so the ordinary mysql client and standard MySQL drivers connect to it, and it adds vector search (a VECF32 column type with l2_distance and vector indexes) and full-text search (FULLTEXT indexes with MATCH ... AGAINST). This image runs MatrixOne standalone: one mo-service process holds the log service, the transaction node and one compute node.

What the cloudimg image adds:

No default login, passwords unique to your instance. Upstream MatrixOne creates two built-in accounts, root and dump, both with the well-known password 111, unless a different password is supplied at the moment the database is first created. So the image ships no database at all: first boot creates this instance's catalogue on the data volume with a 32 character root password generated on the instance and handed to the server on standard input (never on a command line, in a file, a log or the journal), then gives dump its own password. The password 111 never exists on your instance, and first boot proves it is refused for both accounts. Both passwords are written to the root only file /root/matrixone-credentials.txt. MatrixOne refuses to start until first boot has finished, and refuses to start on an empty data volume, so it can never create a catalogue with 111.
Every port bound to localhost. The MySQL-protocol port 6001 and every internal port MatrixOne opens (log service, transaction node, compute node, query service) listen on 127.0.0.1 only, and MatrixOne's Prometheus endpoint (which upstream binds to every interface) is switched off. From the network, only SSH is reachable; you reach the database through an SSH tunnel (Step 8).
A MatrixOne built for this image. The MatrixOne 4.2.6 release binary was built with Go 1.26.4 and modules that now carry fixed security advisories, so cloudimg compiles MatrixOne 4.2.6 from its unmodified release source with Go 1.26.10 and the fixed module releases. The build's provenance is on the instance (/usr/share/doc/matrixone/BUILD-PROVENANCE.txt; Step 9).
Iceberg connector switched off. MatrixOne's Apache Iceberg connector reads Avro files with a library that has three security advisories with no fixed release (see Security notes). Upstream's default configuration turns the connector on; this image turns it off, so every Iceberg statement is refused before any Avro data is read.
Hardened service. MatrixOne runs as an unprivileged matrixone user with no capabilities, a read-only view of the system and no access to /root; MatrixOne and its first boot service are blocked from the instance metadata service (MatrixOne can fetch a URL you name from SQL, for example when loading data), and the AMI requires IMDSv2. The MatrixOne binaries and configuration are owned by root and read-only to the service. SSH accepts keys only, and fwupd's automatic firmware-metadata refresh is switched off (EC2 has no firmware it can update).
Your data on its own disk. The store (/var/lib/matrixone) is on a separate 20 GiB EBS volume you can grow or snapshot on its own.
Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: MatrixOne 4.2.6 (/opt/matrixone, running as matrixone.service, configuration in /etc/matrixone/launch), the MariaDB mysql client from Ubuntu, a helper matrixone-mysql that signs the client in as root, a demo database demo with a vector column and a full-text index, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent. There is no MySQL or MariaDB server on the image.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

What this is not

This is a single-instance MatrixOne. The distributed deployment (several compute nodes on shared object storage) is out of scope for this image. MatrixOne is compatible with a large part of MySQL 8.0 syntax but is not MySQL; check Matrix Origin's documentation for the statements your application uses.

MatrixOne is built for the x86-64-v3 instruction set (AVX2), like upstream's own release. Every current EC2 instance family has it; first boot stops with a clear message, and MatrixOne stays stopped, on a processor that does not.

Prerequisites

An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet (or a private route you use for management).
A security group that allows TCP 22 (SSH) from your admin network. MatrixOne listens on the loopback address only, so no database port needs to be open; you reach it through an SSH tunnel (Step 8).

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick MatrixOne 4.2.6 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large (or larger for analytical work), your key pair and a security group as above. The AMI brings two volumes: the root volume and a 20 GiB data volume (/dev/sdf) for /var/lib/matrixone. Make the data volume as large as your data needs at launch.

With the AWS CLI (replace the values in angle brackets; this example grows the data volume to 100 GiB):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --block-device-mappings 'DeviceName=/dev/sdf,Ebs={VolumeSize=100,VolumeType=gp3}' \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=matrixone}]'

If you make the data volume larger at launch, grow the file system once after first boot with sudo resize2fs "$(findmnt -no SOURCE /var/lib/matrixone)". First boot takes under a minute once the instance is running.

Step 2: Connect to your instance

Version	SSH user
MatrixOne 4.2.6 on Ubuntu 24.04	`ubuntu`

ssh -i <your-key.pem> ubuntu@<public-ip>

Step 3: Check the services

Both the first boot service and MatrixOne itself should be active:

systemctl is-active matrixone-firstboot.service matrixone.service

active
active

Every MatrixOne port listens on the loopback address; from the network, only SSH is reachable:

sudo ss -Htln

LISTEN 0      4096   127.0.0.53%lo:53    0.0.0.0:*
LISTEN 0      4096       127.0.0.1:22000 0.0.0.0:*
LISTEN 0      4096       127.0.0.1:22001 0.0.0.0:*
LISTEN 0      4096       127.0.0.1:22002 0.0.0.0:*
LISTEN 0      4096       127.0.0.1:6001  0.0.0.0:*
LISTEN 0      4096       127.0.0.1:6002  0.0.0.0:*
LISTEN 0      4096       127.0.0.1:6003  0.0.0.0:*
LISTEN 0      4096      127.0.0.54:53    0.0.0.0:*
LISTEN 0      4096       127.0.0.1:19998 0.0.0.0:*
LISTEN 0      4096       127.0.0.1:32000 0.0.0.0:*
LISTEN 0      4096       127.0.0.1:32001 0.0.0.0:*
LISTEN 0      4096       127.0.0.1:32002 0.0.0.0:*
LISTEN 0      4096         0.0.0.0:22    0.0.0.0:*
LISTEN 0      4096            [::]:22       [::]:*

6001 is the MySQL-protocol port; the others are MatrixOne's internal services (log service 32000 to 32002, transaction node 22000 to 22002, compute node 6002 and 6003, query service 19998). The two port 53 lines are Ubuntu's local DNS resolver, also loopback only.

Step 4: Get your passwords

sudo cat /root/matrixone-credentials.txt

# MatrixOne 4.2.6 on Ubuntu 24.04 - generated on first boot by matrixone-firstboot.service
# These passwords are unique to this instance; none was baked into the image. Keep this file secret.

MATRIXONE_HOST=127.0.0.1
MATRIXONE_PORT=6001
MATRIXONE_ROOT_USER=root
MATRIXONE_ROOT_PASSWORD=<MATRIXONE_ROOT_PASSWORD>
MATRIXONE_DUMP_USER=dump
MATRIXONE_DUMP_PASSWORD=<your-dump-password>
MATRIXONE_SERVER_VERSION=8.0.30-MatrixOne-v4.2.6

# On the instance (the mysql client signed in as root; the password never goes on a command line):
#   sudo matrixone-mysql demo
# From your computer, through an SSH tunnel (MatrixOne listens on 127.0.0.1:6001 only):
#   ssh -i <your-key.pem> -N -L 6001:127.0.0.1:6001 ubuntu@<public-ip>
#   mysql -h 127.0.0.1 -P 6001 -u root -p
# User guide: https://www.cloudimg.co.uk/guides/matrixone-4-2-6-on-ubuntu-24-04-aws/

root is MatrixOne's administrator in the sys tenant. dump is the second built-in account upstream creates; it has its own password so the two accounts never share one.

Step 5: Connect with the mysql client

matrixone-mysql runs the mysql client signed in as root with the password from the credentials file, passed to the client in a temporary root-only option file rather than on the command line:

sudo matrixone-mysql demo -e 'SELECT version(); SELECT current_user();'

version()
8.0.30-MatrixOne-v4.2.6
current_user()
root@localhost

Run sudo matrixone-mysql demo with no -e for an interactive session.

Step 6: Explore the demo database

First boot created a small table, demo.articles, with a vector column (embedding VECF32(3)) and a full-text index on body:

sudo matrixone-mysql demo -e 'SELECT id, title FROM articles;'

id  title
1   Getting started
2   Vector search
3   Full-text search

Vector search

Find the rows whose embedding is nearest to a query vector:

sudo matrixone-mysql demo -e "SELECT id, title, l2_distance(embedding, '[0.85,0.8,0.75]') AS distance FROM articles ORDER BY distance LIMIT 2;"

id  title   distance
2   Vector search   0.07071065157651901
3   Full-text search    0.6964194178581238

Full-text search

sudo matrixone-mysql demo -e "SELECT id, title FROM articles WHERE MATCH(body) AGAINST('columns');"

id  title
2   Vector search

Step 7: Create your own database

Ordinary MySQL-style SQL works for your own data:

sudo matrixone-mysql -e "CREATE DATABASE IF NOT EXISTS shop; CREATE TABLE IF NOT EXISTS shop.orders (id INT PRIMARY KEY, customer VARCHAR(50), amount DECIMAL(10,2)); INSERT INTO shop.orders VALUES (1,'alice',19.99),(2,'bob',5.00),(3,'alice',42.50) ON DUPLICATE KEY UPDATE amount=VALUES(amount); SELECT customer, count(*) AS orders, sum(amount) AS total FROM shop.orders GROUP BY customer ORDER BY customer;"

customer    orders  total
alice   2   62.49
bob 1   5.00

For applications, create a dedicated account rather than using root, for example CREATE USER app IDENTIFIED BY '<password>'; followed by the GRANT statements your application needs (MatrixOne grants privileges through roles: CREATE ROLE, GRANT ... TO ROLE, GRANT <role> TO <user>).

Step 8: Connect from your own computer through an SSH tunnel

MatrixOne listens on 127.0.0.1:6001 only. Forward the port over SSH from your computer, then point any MySQL client or driver at your local end of the tunnel:

ssh -i <your-key.pem> -N -L 6001:127.0.0.1:6001 ubuntu@<public-ip>
mysql -h 127.0.0.1 -P 6001 -u root -p

Enter the root password from Step 4 when prompted. For applications inside your VPC, the same tunnel (or an SSH-based bastion) keeps the database port closed to the network.

Step 9: Security checks

MatrixOne and its first boot service cannot reach the instance metadata service:

systemctl show -p IPAddressDeny matrixone.service matrixone-firstboot.service

IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32

IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32

The MySQL-protocol port is pinned to loopback, the Iceberg connector and the Prometheus endpoint are off:

grep -E '^(host|port|enable|enable-metric-to-prom) =' /etc/matrixone/launch/cn.toml

host = "127.0.0.1"
port = 6001
enable = false
host = "127.0.0.1"
enable-metric-to-prom = false

Iceberg statements are refused by MatrixOne's feature gate:

{ sudo matrixone-mysql -e 'SHOW ICEBERG CATALOGS' 2>&1 || true; } | grep -o 'ICEBERG_FEATURE_DISABLED.*'

ICEBERG_FEATURE_DISABLED: SHOW ICEBERG CATALOGS is disabled by configuration [account_id=0]

MatrixOne runs unprivileged:

ps -o user:12=,comm= -C mo-service
sudo grep -E '^(CapEff|NoNewPrivs)' /proc/$(systemctl show -p MainPID --value matrixone.service)/status

matrixone    mo-service
CapEff: 0000000000000000
NoNewPrivs: 1

The image's own round trip: both per-instance passwords work and the demo searches return the right rows, while 111, blank, common and random passwords are refused for root and dump:

sudo /usr/local/sbin/matrixone-roundtrip.sh | tail -1

OK-matrixone-roundtrip

How MatrixOne was built, and what govulncheck found:

grep -E '^(toolchain|govulncheck|source change|unfixed) ' /usr/share/doc/matrixone/BUILD-PROVENANCE.txt

toolchain         go1.26.10 linux/amd64, official tarball https://go.dev/dl/go1.26.10.linux-amd64.tar.gz
toolchain sha256  ccfe7ae822d2c2f41f4fe7c956199967a4dac22d0ee0d2b2bfdb440aab3b20c5
source change     none (upstream source, unmodified)
govulncheck       v1.9.0, source: Your code is affected by 3 vulnerabilities from 1 module. (GO-2026-5046 GO-2026-5047 GO-2026-5048); binary: Your code is affected by 3 vulnerabilities from 1 module. (GO-2026-5046 GO-2026-5047 GO-2026-5048)
unfixed           GO-2026-5046, GO-2026-5047, GO-2026-5048 (github.com/hamba/avro/v2: no fixed release exists). Imported only

Security notes

GO-2026-5046, GO-2026-5047, GO-2026-5048 are denial-of-service advisories (CPU exhaustion, integer overflow, unbounded memory) in the Avro decoder github.com/hamba/avro/v2, for which no fixed release exists. MatrixOne uses that library only in its Iceberg connector, to read Iceberg manifest files. The connector is off on this image, and every Iceberg statement is refused before any Avro data is read, as shown above. If you turn it on ([cn.frontend.iceberg] enable = true in /etc/matrixone/launch/cn.toml), these advisories apply to the Iceberg tables you query: only point it at storage you trust.
MatrixOne cannot reach the instance metadata service, so loading data from S3 cannot use the instance's IAM role; pass credentials in the statement or stage you create, as Matrix Origin's documentation describes.

Step 10: Change the passwords

Choose a new password, set it, then update the credentials file so matrixone-mysql keeps working:

sudo matrixone-mysql
mysql> ALTER USER root IDENTIFIED BY '<new-password>';
mysql> exit
sudo sed -i 's/^MATRIXONE_ROOT_PASSWORD=.*/MATRIXONE_ROOT_PASSWORD=<new-password>/' /root/matrixone-credentials.txt

Use ALTER USER: MatrixOne accepts SET PASSWORD but does not change the password with it. Change dump the same way (ALTER USER dump IDENTIFIED BY '<new-password>';) and update MATRIXONE_DUMP_PASSWORD.

Step 11: Backup, updates and maintenance

Back up by snapshotting the data volume, or by copying /var/lib/matrixone with the service stopped (sudo systemctl stop matrixone). MatrixOne also has its own backup tooling and mo-dump for logical dumps; see Matrix Origin's documentation.
Memory: MatrixOne sets its Go memory limit to about 70 percent of the instance's RAM each time it starts, so it adapts to the instance type you choose. The file service caches are capped at 128 MB (local) and 256 MB (shared) in /etc/matrixone/launch/*.toml; raise them on large instances for analytical work.
Logs: sudo journalctl -u matrixone.service -n 50.
Configuration lives in /etc/matrixone/launch/; restart the service after editing it (sudo systemctl restart matrixone). Keep every listen-address and host on 127.0.0.1 unless you deliberately expose a port, and never enable the Prometheus endpoint on a network you do not trust (MatrixOne binds it to every interface).
Updates: Ubuntu security updates install automatically. MatrixOne is pinned to the version this image was built with; upgrade it deliberately, after taking a copy of the data volume and reading Matrix Origin's upgrade notes for the release.

Support and licensing

MatrixOne is open source software under the Apache License 2.0 (/usr/share/doc/matrixone/LICENSE); the jieba dictionary MatrixOne uses for Chinese full-text tokenising is under the MIT licence (/usr/share/doc/matrixone/LICENSE.jieba-dict). The MatrixOne on this image is built from the unmodified upstream source. cloudimg provides 24/7 technical support for this image by email and live chat: support@cloudimg.co.uk. MatrixOne is a trademark of Matrix Origin; cloudimg is not affiliated with or endorsed by Matrix Origin.