Compatible with the MySQL wire protocol

What this is, and what it is not

This is a compatibility statement about a protocol, not a database product. OriginChainDB implements the MySQL wire protocol independently so that clients written for it can talk to an OriginChainDB instance. We do not run, embed, fork or redistribute MySQL server software, and an instance is not a drop-in replacement for one: the SQL surface is OriginChainDB's, and the differences are listed under limits.

Concretely, the listener speaks protocol version 10: the standard handshake, the text protocol for ordinary queries, and binary prepared statements (PREPARE / EXECUTE / CLOSE / RESET, with ? placeholders bound server-side). Statements arrive in MySQL's dialect and are translated into the engine's, construct by construct - never guessed at. Anything the translator does not recognise comes back as a clean error naming the construct, so a query either runs or fails; it is never quietly turned into a different query.

Row-level security and column masking are applied inside the engine, below the wire, so a MySQL session sees exactly the rows and columns your policies allow - the same ones an HTTP call under that identity would see.

Connect

First find out whether your instance has a listener at all. Ask the capabilities endpoint:

curl -s -H "Authorization: Bearer $OC_TOKEN" \
  "https://$OC_HOST/v1/capabilities" | jq '.wire.mysql'

# Until a listener is configured for your instance:
#   { "available": false }
#
# "available" reports that CONFIGURATION IS COMPLETE. It is a precondition
# for starting a listener, not an observation of a bound socket - so when it
# turns true, still check the port and a real login before you rely on it.

Once it is enabled, connect the way you would connect to anything speaking this protocol:

# The port follows the convention MySQL clients expect. The host and port
# your instance is actually published on are shown in the console once the
# listener is enabled - use those, not this default.

mysql --host "$OC_MYSQL_HOST" --port 3306 \
      --user "$OC_DB_USER" --password \
      --ssl-mode=REQUIRED \
      --database "$OC_DB"

The authentication plugin depends on which credential model your listener runs: mysql_native_password for a shared credential, caching_sha2_password for per-user login. Both are what a stock client already negotiates, so you do not configure the plugin - you configure the model, and the plugin follows.

TLS, and why a certificate is not optional

The listener implements the standard TLS upgrade: it advertises TLS support in the handshake, a capable client answers by asking to upgrade before it authenticates, and the rest of the session runs inside TLS. That is exactly what --ssl-mode=REQUIRED does, so stock clients interoperate without special handling.

Per-user login is the opposite: it cannot be configured without TLS. That model's authentication delivers the password to the server in cleartext inside the session, so the engine forces the refuse-plaintext option on and will not start a per-user listener that has no certificate. If the tenant you are enabling must use per-user login - see below - TLS is settled for you.

Credential models, and which one you will be on

There are two, and the choice is not a preference - it is decided by whether your tenant has any database authorization to enforce: a database RBAC grant or a row-level security policy. Either one is enough; a row-security policy is not the lighter case.

A worked example: Sequelize over mysql2

This is the client we drove against the shipping engine - Sequelize 6.37 on top of mysql2 3.24 - so what follows is a transcript of what worked, not a sketch of what should. The shape to take away: declare your tables in code and the ORM drives a complete single-table workload; let it introspect the database instead and it will not get far.

Connect and define

import mysql2 from "mysql2";
import { Sequelize, DataTypes } from "sequelize";

// Verified against the shipping engine with Sequelize 6.37 over mysql2 3.24.
const sequelize = new Sequelize(process.env.OC_DB, process.env.OC_DB_USER, process.env.OC_DB_PASSWORD, {
  host: process.env.OC_MYSQL_HOST,
  port: 3306,
  dialect: "mysql",
  dialectModule: mysql2,
  // Ask for TLS explicitly. A listener with no certificate will happily
  // serve you in cleartext instead of refusing - see "TLS" above.
  dialectOptions: { ssl: { minVersion: "TLSv1.2", rejectUnauthorized: true } },
  logging: false,
});

// Describe the table in code. Do NOT call sequelize.sync() and do not rely on
// queryInterface.describeTable() - both introspect with SHOW, which is refused.
const Order = sequelize.define(
  "Order",
  {
    id: { type: DataTypes.STRING, primaryKey: true },
    customer: DataTypes.STRING,
    total_cents: DataTypes.INTEGER,
    status: DataTypes.STRING,
  },
  { tableName: "orders", timestamps: false, freezeTableName: true },
);

await sequelize.authenticate();

Insert, select, update, delete

// INSERT
await Order.create({ id: "o_1", customer: "c_7", total_cents: 4200, status: "open" });

// SELECT with a filter and an ordering
const open = await Order.findAll({
  where: { status: "open" },
  order: [["total_cents", "DESC"]],
  limit: 10,
});

// UPDATE
await Order.update({ status: "shipped" }, { where: { id: "o_1" } });

// DELETE, bounded by a WHERE
await Order.destroy({ where: { id: "o_1" } });

Transactions

Transactions are real, not acknowledged-and-ignored. A block that commits persists, and a block that rolls back leaves nothing behind - both were exercised.

// Both outcomes were exercised against the engine: a transaction that
// commits, and one that rolls back leaving no trace.
const tx = await sequelize.transaction();
try {
  await Order.create({ id: "o_2", customer: "c_7", total_cents: 900, status: "open" }, { transaction: tx });
  await Order.update({ status: "paid" }, { where: { id: "o_2" }, transaction: tx });
  await tx.commit();
} catch (err) {
  await tx.rollback();
  throw err;
}

More recipes, one per page, are under MySQL examples.

The catalog surface

This is the section that decides whether a tool works, so read it before you adopt one. Metadata is split down the middle: the information_schema views are answered, and every SHOW form is refused.

Answered: the information_schema views

Five views are served, by the same shared catalog the other wire protocols read: tables, columns, table_constraints, key_column_usage and referential_constraints. They are ordinary queries, so they work from any client:

-- Answered by the shared catalog, the same one the other wire
-- protocols and the HTTP API read.
SELECT table_name FROM information_schema.tables WHERE table_schema = 'shop';
SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'orders';

Refused: every SHOW form

mysql> SHOW TABLES;
ERROR 1235 (42000): MySQL `SHOW …` metadata commands are not supported —
the engine keeps no MySQL information schema.

-- Refusing is the deliberate choice. The shared front door carries a
-- PostgreSQL "SHOW <guc>" shim that would otherwise answer ANY SHOW with a
-- single fabricated row reading  x = 'on'  - so SHOW TABLES would return a
-- confident, wrong answer instead of an error.

SHOW TABLES, SHOW DATABASES, SHOW COLUMNS, SHOW CREATE TABLE, SHOW INDEX, SHOW WARNINGS and SHOW VARIABLES LIKE … all return an error. We would rather hand you an error you can act on than a fabricated row you would believe.

Session variables are handled separately and honestly: the ones a connector reads at startup are answered with their true values, and one that does not exist is refused with the unknown-variable error rather than a made-up value. SET NAMES is accepted as a no-op, because every official connector opens with one.

Limits

Every one of these returns a clear error naming the construct. None of them silently returns a different answer.

Trademark

MySQL is a registered trademark of Oracle Corporation and/or its affiliates. OriginChainDB is not affiliated with, endorsed by, or sponsored by Oracle Corporation. OriginChainDB implements a compatible wire protocol so that existing MySQL clients can connect to it; it does not distribute MySQL software.