SingleStore · SingleStore Helios

singlestorechange.
shard key
as code.

The first migration tool built for SingleStore's distributed SQL model. SHARD KEY, SORT KEY (columnstore), and VECTOR INDEX versioned in YAML. A 7-rule analyser catches sharding anti-patterns before they reach production. Other tools see MySQL — singlestorechange sees the sharding layer.

pip install singlestorechange See 7 Analyser Rules

CLI Commands

Analyser Rules

HNSW

Vector Index

singlestorechange — myapp deploy

$ singlestorechange analyse --profile prod

[S001] orders: no explicit SHARD KEY

[S007] users: PRIMARY KEY must include SHARD KEY cols

✓ 1 script passes all checks

$ singlestorechange deploy --profile prod --tag 2.0.0

[RUN] V1.0.0__create_core_tables.sql 1.2s

[RUN] V1.1.0__add_vector_search.yaml 890ms

[vec] HNSW index products.embedding dims=1536

[RUN] V1.2.0__add_shard_config.yaml 45ms

[shard] SHARD KEY orders(id)

✓ 3 applied · tag=2.0.0

Validated on SingleStore Helios SingleStore Self-Managed MySQL wire protocol singlestoredb SDK VECTOR (HNSW / IVF) Columnstore + Rowstore

Why singlestorechange

SingleStore is not
just MySQL.

Other tools connect on port 3306 and fire SQL. They have no concept of sharding, no understanding of columnstore vs rowstore, and no ability to manage VECTOR indexes. singlestorechange treats SingleStore as a first-class distributed SQL engine.

Key Differentiator

SHARD KEY + SORT KEY as YAML Migrations

SHARD KEY controls data distribution across partitions — getting it wrong causes hotspots, cross-partition joins, and performance degradation that's hard to undo after data is loaded. SORT KEY controls columnstore sort order for range scan acceleration. singlestorechange versions both in YAML, so sharding strategy is reviewable, auditable, and rollbackable.

Key Differentiator

VECTOR INDEX Lifecycle Management

SingleStore supports HNSW and IVF vector indexes for approximate nearest-neighbour search at scale. These indexes are expensive to create on large tables. singlestorechange versions them in YAML migrations with index_type, dimensions, and metric — and the advisor warns when they should be scheduled during low-traffic windows.

Schema Analyser

7 rules.
Catch it in CI.

Run singlestorechange analyse before every deploy. It scans your migration scripts and live schema for SingleStore-specific anti-patterns that other tools can't even see.

S001

Missing SHARD KEY

Table has no explicit SHARD KEY — defaults to keyless sharding. Keyless sharding prevents shard-local joins and single-partition queries.

S002

AUTO_INCREMENT PK Hotspot

AUTO_INCREMENT primary key causes all inserts to land on the master aggregator. Use UUID() (application-supplied) or a sequence for distributed inserts.

S003

Missing SORT KEY on Columnstore

Columnstore table without a SORT KEY forces full segment scans. Add SORT KEY on the most frequently filtered column to enable range-scan acceleration.

S004

ALTER MODIFY on Columnstore

ALTER TABLE MODIFY COLUMN for data type changes is not supported on columnstore tables. Use ADD COLUMN + data migration instead.

S005

DDL Inside Transaction

SingleStore DDL is non-transactional. Wrapping CREATE/ALTER/DROP in BEGIN...COMMIT has no effect and causes schema drift if the transaction rolls back.

S006

DEFAULT UUID() on Sharded Table

DEFAULT UUID() is not allowed on sharded table columns — SingleStore requires deterministic defaults for shard distribution. Supply UUIDs from the application.

S007

PRIMARY KEY Missing SHARD KEY Columns

Every UNIQUE and PRIMARY KEY must include all SHARD KEY columns. SingleStore enforces uniqueness per partition — if the shard key isn't in the unique key, the uniqueness constraint can't be enforced across nodes. This is a deployment error, not a warning.

YAML Migrations

Distributed SQL
as code.

SQL handles tables and indexes. YAML handles the distributed topology layer — sharding, columnstore configuration, and vector search indexes.

# V1.1.0__add_vector_search.yaml

# VECTOR INDEX — Other tools have zero vector index support

sql: |

ALTER TABLE `products`

ADD COLUMN embedding VECTOR(1536) NOT NULL;

vector_indexes:

- table: products

column: embedding

name: vidx_products_embedding

index_type: HNSW

dimensions: 1536

metric: DOT_PRODUCT

# V1.2.0__add_shard_config.yaml

shard_keys:

- table: orders

columns: [id] # SHARD KEY must be in PRIMARY KEY

sort_keys:

- table: order_events

columns: [event_time] # columnstore range scan

Capabilities

Every command
S2-aware.

⚡

Rowstore vs Columnstore

Monitor shows table type alongside row counts — rowstore for OLTP, columnstore for analytics. Baseline generation captures SORT KEY and table type in YAML.

TABLE TYPE

🔍

VECTOR Index Lifecycle

Create HNSW and IVF vector indexes with dimensions and metric (DOT_PRODUCT, L2_DISTANCE, EUCLIDEAN) as versioned YAML. Advisor warns about CPU-intensive creation.

ANN SEARCH

🗄

Dedicated History DB

Tracking tables live in singlestorechange_history database — never in your application database. Capacity snapshots stored there too. No tooling tables pollute your schema.

ISOLATED

📐

SHARD KEY Contracts

Governance contracts enforce that all CREATE TABLE statements include a SHARD KEY. Block non-compliant migrations in CI before they reach the cluster.

POLICY AS CODE

📊

OLS Capacity Projections

Daily row count snapshots with 180-day OLS projections. High/medium/low confidence based on R² and data point count. Flags tables at risk.

180-DAY OLS

🔑

singlestoredb SDK

Uses the official singlestoredb Python SDK (10x faster than PyMySQL via C extension). Falls back to pymysql automatically if singlestoredb is not installed.

OFFICIAL SDK

Comparison

singlestorechange vs
alternatives

Other tools see a MySQL-compatible endpoint. singlestorechange sees distributed SQL.

Capability	singlestorechange	Other tools	Plain MySQL client
SQL DDL migrations	✓	✓	manual
SHARD KEY versioning	✓ YAML	✗	✗
SORT KEY (columnstore)	✓ YAML	✗	✗
VECTOR INDEX (HNSW/IVF)	✓ YAML	✗	✗
7-rule SingleStore analyser	✓ S001–S007	✗	✗
PK + SHARD KEY alignment check	✓ S007 ERROR	✗	✗
Rowstore vs columnstore tracking	✓	✗	✗
SHARD KEY governance contracts	✓	✗	✗
OLS capacity projections	✓ 180-day	✗	✗
Official singlestoredb SDK support	✓ primary	pymysql only	✗
Immutable audit log	✓	basic	✗

Installation

Start in
two minutes.

$ pip install singlestorechange

Python 3.9+ · pyyaml · singlestoredb (recommended) or pymysql

# Recommended: pip install singlestoredb (10x faster than PyMySQL, official SDK)

# singlestorechange.yml — local profile

profiles:

local:

host: localhost

port: 3306 # ← MySQL wire protocol

database: myapp

user: root

# Run analyser before deploy to catch S001–S007:

singlestorechange analyse --profile local

singlestorechange.shard keyas code.

SingleStore is notjust MySQL.

7 rules.Catch it in CI.

Distributed SQLas code.

Every commandS2-aware.

singlestorechange vsalternatives