¶Installation

Upgrading to 1.5.0 or later

1.5.0 changed the default collation to utf8mb4_0900_ai_ci, which changes the bytes under which text is stored. A database created by an earlier version is migrated automatically the first time 1.5.0 or later opens it: text index entries are rebuilt and text primary keys re-keyed, before any connection is accepted. Databases whose indexed text is pure ASCII are not rewritten.

The migration writes in batches so that a large table cannot exhaust memory at startup, and it is idempotent: an already re-keyed row encodes to the key it is already stored under. The version marker is written only once every table is done, so an interrupted upgrade simply resumes on the next start. Take a backup first, and note that downgrading to 1.4.x afterwards is not supported.

Upgrading to 1.9.8

Arithmetic that used to be approximate is now exact. Results and result types both change. None of it touches your data, and every change moves toward MySQL — but if you have code that compensated for the old behaviour, that compensation is now wrong.

Rounding a decimal gives a different answer at the halfway point.

SELECT ROUND(1.005, 2);   -- was 1.00, now 1.01 (MySQL: 1.01)

1.005 has no exact binary form, so the old path rounded it down. Anything that reconciled against MySQL, a spreadsheet or an accounting system was seeing our answer, not theirs. If you stored the old results, they do not match what the same query returns now.

Division, MOD, ROUND, TRUNCATE, AVG and SUM now return DECIMAL. They returned DOUBLE, or BIGINT for an integer SUM. Drivers hand a DECIMAL to your language differently — Python gets decimal.Decimal where it got float, PHP and Go get a string where they got a float. Code that assumes a float from SUM() or AVG() needs a conversion it did not need before.

The scales follow MySQL exactly: 10 / 3 is 3.3333 (the dividend's scale plus four), AVG over DECIMAL(12,2) has scale 6, and SUM over an INT column is DECIMAL because the total can exceed the column's range.

A range bound written as a string now returns the rows it should.

SELECT COUNT(*) FROM t WHERE k > '1.5';   -- k INT: was missing row 2

The bound was coerced to 2 while the strict > was kept, so row 2 was silently dropped. Any query comparing an indexed numeric column against a string literal — or against a scalar subquery whose result is rendered as text — was affected. Queries that returned too few rows now return the right ones.

Upgrading to 1.9.6

Three changes alter answers your client already reads, and one changes how the process fails. None touches your data.

Affected-row counts now match MySQL. They were wrong in five shapes, and the 1-vs-2 distinction is how a client tells an insert from an update — so updateOrCreate-style code was reading the wrong answer and may contain a workaround that now reads the wrong answer in the other direction:

statement	was	now (and MySQL)
INSERT ... ON DUPLICATE KEY UPDATE, row updated	1	2
... set to the values it already had	1	0
REPLACE replacing an existing row	1	2
UPDATE that matched a row but changed nothing	1	0

Search your code for anything that compensated for the old counts before upgrading. Code that treats "affected == 1" as "inserted" will now see 2 for an update, which is the correct signal but the opposite conclusion.

A boolean used as a number is now an integer. SELECT TRUE + 1 returns 2 as BIGINT where it returned 2.0 as DOUBLE; likewise (1 = 1) + 1 and (2 > 1) + (3 > 2). Code asserting on the column type, or round-tripping through a typed language, sees the new type.

CREATE VIEW over an existing table name now reports 1050 (ER_TABLE_EXISTS_ERROR) instead of 1146 (ER_NO_SUCH_TABLE). 1146 was simply wrong; a migration tool that treats 1050 as "already done" will now behave correctly here.

The server aborts on panic instead of unwinding, so it must be supervised. A panic is now a crash and a restart rather than a degraded process — which is the point: a panic that unwound while holding an internal lock left the server answering health checks while failing every query. The shipped packaging/elyrasql.service already sets Restart=on-failure. If you run the container or the binary under anything that does not restart it, add a restart policy before upgrading; see Deployment.

Upgrading to 1.9.5

Four changes can affect a working deployment. None touches your data.

A partial cluster TLS configuration now refuses to start. Setting only one of ELYRASQL_CLUSTER_TLS_CERT / ELYRASQL_CLUSTER_TLS_KEY, or pointing them at a certificate that cannot be loaded, previously logged a warning and continued in plaintext. That is now a startup error. If a node fails to start after upgrading, it was running unencrypted before: fix the pair rather than working around the error.

An exposed Raft control plane now requires authentication. A control listener bound to anything other than loopback refuses to start unless ELYRASQL_CLUSTER_SECRET is set. To keep the previous behaviour deliberately, set ELYRASQL_ALLOW_OPEN_AUTH=1.

SHOW PROCESSLIST is scoped. A non-Admin account now sees only its own connections. Monitoring that reads the full process list must connect as an Admin account.

Slow-query and audit output is redacted. String literals are replaced with ? and CREATE USER / ALTER USER / SET PASSWORD statements are elided entirely, so log pipelines that parsed literal values out of these lines will no longer find them. The audit log file is created owner-only (0600) on Unix.

Two smaller behaviour changes worth knowing: ELYRASQL_AUTH_LOCKOUT_SECS is no longer read (the account lockout was removed — it let unauthenticated traffic lock out valid accounts), and queries that read a column-restricted table through a subquery, CTE or GROUP BY are now correctly refused where the restriction was previously bypassed.

Upgrading to 1.9.4

Two changes can affect a working deployment. Neither touches your data.

The container image has no shell. It is now built FROM scratch — 22.3 MB down to 13.6 MB, with no OS packages and so no OS CVEs. But docker exec <container> sh no longer works, and neither does anything built on it: shell-based health checks, debugging one-liners, init wrappers. Check liveness over the MySQL protocol from outside the container instead:

mysql -h 127.0.0.1 -P 3307 -u root -e 'SELECT 1'

If you run the image under an orchestrator with an exec-based probe, change the probe before upgrading.

Result-column metadata reports different values. Character columns now advertise their declared width under a utf8mb4 collation, matching MySQL: a VARCHAR(32) reports 128 bytes where it previously reported the unbounded text capacity, and clients that divide by the charset width now show 32 instead of 21845. This is a fix — the old values were wrong in a way that made every client's length arithmetic wrong — but if you have code asserting on column lengths or collation ids, it will see new numbers. Row data, types and flags are unchanged.

Tables created before 1.9.1 have no stored width and keep the unbounded value. Nothing needs to be rebuilt.

Also: elyrasql serve now exits on Ctrl-C. If you deliberately started it with SIGINT ignored, installing the handler overrides that, and it will exit on a signal it used to survive.

# Linux
VER=X.Y.Z
ARCH=x86_64   # or aarch64
curl -L -o elyrasql.tar.gz \
  "https://github.com/kwhorne/ElyraSQL/releases/download/v${VER}/elyrasql-${VER}-linux-${ARCH}.tar.gz"
tar xzf elyrasql.tar.gz
cd elyrasql-${VER}-linux-${ARCH}
./elyrasql version

# Apple Silicon, macOS 11+
VER=X.Y.Z
curl -L -o elyrasql.tar.gz \
  "https://github.com/kwhorne/ElyraSQL/releases/download/v${VER}/elyrasql-${VER}-macos-aarch64.tar.gz"
tar xzf elyrasql.tar.gz
cd elyrasql-${VER}-macos-aarch64
./elyrasql version

docker pull ghcr.io/kwhorne/elyrasql:1.9.9   # or :latest
docker run -p 3307:3307 -v elyra:/var/lib/elyrasql ghcr.io/kwhorne/elyrasql:1.9.9

git clone https://github.com/kwhorne/ElyraSQL.git
cd ElyraSQL
cargo build --release
./target/release/elyrasql serve

rustup target add aarch64-apple-darwin
MACOSX_DEPLOYMENT_TARGET=11.0 \
  cargo build --release --locked --target aarch64-apple-darwin -p elyra-cli
./target/aarch64-apple-darwin/release/elyrasql version

rustup target add x86_64-unknown-linux-musl
sudo apt-get install -y musl-tools
cargo build --release --target x86_64-unknown-linux-musl -p elyra-cli

sudo ./packaging/deploy.sh
# or with credentials + TLS:
ELYRASQL_USER=root ELYRASQL_PASSWORD=secret \
  ELYRASQL_LISTEN=0.0.0.0:3307 sudo -E ./packaging/deploy.sh