Prepare connections, fixtures and acceptance checks

Scope

These tutorials are derived from ecosystem validation against MatrixOne build 652c643666428f1c434e03369834f2a9bead7c27, with MySQL 8.4.11 controls where semantics overlap. Record your release, driver versions and read/write directions separately. A working MySQL protocol connection does not establish support for MySQL binlog, every generated statement or every inferred type.

The code is a minimal example adapted from the validated routes, rather than a claim that every new tutorial configuration has been redeployed. Each tool page records the actual boundary. Functional checks on a memory filesystem do not establish disk throughput, long-duration stability, scheduler HA or cross-system exactly-once certification.

Environment and connection

Install and start MatrixOne. Have an administrator create the dedicated doc_lake database and grant an ecosystem user access; the database creation below requires that privilege. The client port is 6001. Use a separate database and retain inputs, logs and destination data until validation is complete.

Save the examples in a new working directory and use a Python virtual environment. Inject passwords through environment variables or a secret manager. Replace the empty password placeholder with a real secret outside source control. Configure a CA for remote access using the TLS guide; omitting MO_SSL_CA is for an isolated local experiment.

python -m venv .venv
. .venv/bin/activate
python -m pip install pymysql sqlalchemy
export MO_HOST=127.0.0.1
export MO_PORT=6001
export MO_DATABASE=doc_lake
export MO_USER=ecosystem_user
export MO_PASSWORD=''
# export MO_SSL_CA=/path/to/ca.pem
mysql -h "$MO_HOST" -P "$MO_PORT" -u "$MO_USER" -p

Create exact-value fixtures

Save this as fixtures.sql and run source fixtures.sql in a client with the required privileges. Expect two rows: the first ID exceeds the consecutive integer range of floating point; the second distinguishes SQL NULL, empty bytes and an empty string. Keep all 18 decimal places in amount; the first binary value is 00FF80 in hex. Check these results before starting a tool. Initialization restores these two example keys to the supplied values without clearing other rows.

CREATE DATABASE IF NOT EXISTS doc_lake;
USE doc_lake;
CREATE TABLE IF NOT EXISTS lake_demo (
    id BIGINT PRIMARY KEY,
    amount DECIMAL(38,18),
    payload VARBINARY(256),
    label VARCHAR(256),
    rev BIGINT
);
INSERT INTO lake_demo VALUES
    (9007199254740993, 12345678901234567890.123456789012345678, UNHEX('00FF80'), '中文😀', 0),
    (2, NULL, UNHEX(''), '', 0)
ON DUPLICATE KEY UPDATE amount=VALUES(amount), payload=VALUES(payload), label=VALUES(label), rev=VALUES(rev);
SELECT id, CAST(amount AS CHAR), HEX(payload), label, rev FROM lake_demo ORDER BY id;

Save the shared connection module

Save the complete code below as mo_common.py, next to the later scripts. engine() uses a structured URL so special characters in passwords are parsed correctly and sets a bounded pool. Roll back failed transactions and close connections or dispose the pool when a script ends.

import os
from decimal import getcontext
import pymysql
import sqlalchemy as sa

getcontext().prec = 80

def options():
    return dict(host=os.environ["MO_HOST"], port=int(os.environ["MO_PORT"]),
                user=os.environ["MO_USER"], password=os.environ["MO_PASSWORD"],
                database=os.environ["MO_DATABASE"], charset="utf8mb4",
                connect_timeout=10, read_timeout=45, write_timeout=45)

def connect():
    kw = options()
    if os.environ.get("MO_SSL_CA"):
        kw["ssl"] = {"ca": os.environ["MO_SSL_CA"]}
        kw["ssl_verify_cert"] = True
        kw["ssl_verify_identity"] = True
    return pymysql.connect(**kw, autocommit=False)

def engine():
    kw = options()
    url = sa.URL.create("mysql+pymysql", username=kw["user"], password=kw["password"],
                        host=kw["host"], port=kw["port"], database=kw["database"])
    args = dict(charset="utf8mb4", connect_timeout=10, read_timeout=45, write_timeout=45)
    if os.environ.get("MO_SSL_CA"):
        args.update(ssl={"ca": os.environ["MO_SSL_CA"]},
                    ssl_verify_cert=True, ssl_verify_identity=True)
    return sa.create_engine(url, pool_size=2, max_overflow=0,
                            pool_pre_ping=True, connect_args=args)

Acceptance and troubleshooting

Retain source SQL values, in-memory types, file types, fresh-connection destination reads and duplicate-key checks. Row counts and process exit codes are insufficient. Keep exact decimals out of float, compare binary bytes, represent negative TIME as signed microseconds or a defined SQL time string, and retain microsecond DATETIME precision with a time-zone contract. Check JSON text null separately from SQL NULL, and empty strings separately from NULL.

Before retrying, determine whether the prior batch committed. A broken connection can leave the commit outcome unknown: discard it and inspect committed effects using a business key, event ID or batch receipt. Append cannot be replayed blindly; deletion requires keyed delete events. Qualify added fields, renames, narrowing and NOT NULL changes separately. A throughput report needs hardware, storage, dataset, actual duration, batch size, connection count, failure timeline and value checks.

Historical ecosystem reports and evidence start at matrixone#29848. After a report closes, check its fix commit, the first release containing it and the regression result on your deployment.