vsql-docs

Get a working VillageSQL server on this machine and prove it works — choose an install path (installer, Docker, or source), start the server, connect, load a bundled extension, and call one of its functions. Also covers reconnecting to a server that is already running. VillageSQL is a drop-in replacement for MySQL that adds extensions. Use when a task needs a local MySQL server for development or tests, starts a new project on MySQL, ports a PostgreSQL application to MySQL, or needs something MySQL lacks: UUIDv7 or 16-byte UUID keys, LLM calls or embeddings in SQL, password hashing or encryption in SQL, IP/CIDR/MAC columns, HTTP calls from SQL, fuzzy or phonetic text matching, a strict boolean, currency codes, n-dimensional cubes, a REST or MCP endpoint over the database, or JWT login. Also use before vsql-extension-builder, or any time a VillageSQL server is needed and none is confirmed working.

About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.

Maintain a semantic grounding layer (.aidp/semantic.md) for AIDP — logical entity names, SQL-defined metrics, joins with cardinality, synonyms, and value dictionaries. Use when the user wants to define metrics/business terms, improve NL-to-SQL accuracy, standardize "revenue/customers/etc.", or set up a semantic model. Read by analyzing-data, verified-queries, profiling, and data-quality.

Compare source-DB rows against a migrated AIDP target via `infa2aidp cli reconcile`, driven by a YAML config (row_count / schema / aggregate / data checks, with ignore_columns for audit/surrogate columns that never match). Use after a migrated notebook has actually run and populated its AIDP target — this is the customer-facing proof the migration is correct, not merely that it ran.

Write-side Spark SQL on the AIDP lakehouse — DDL (CREATE/ALTER/DROP table·view·schema), DML (INSERT/UPDATE/DELETE/MERGE upsert), and Delta maintenance (OPTIMIZE, VACUUM, time travel, RESTORE, schema evolution, liquid clustering). Use when the user wants to create/alter/drop a table or view, insert/update/delete/merge rows, upsert, compact/optimize/vacuum a Delta table, query an old version (time travel), restore, evolve a schema, or run any non-SELECT SQL. For read-only analytics use aidp-analyzing-data; for control-plane (CLI/REST) table lifecycle use aidp-table-management.

Control-plane lifecycle for AIDP catalog objects — create/update/delete/refresh tables, views, schemas, and catalogs, and register an EXTERNAL catalog/connection (ALH/ADW/object-storage) as a persistent catalog object. Use when the user wants to create or drop a table/view/schema/catalog via the control plane (not a SELECT), register an external data source as a catalog, refresh catalog metadata, or test a connection. For SQL-native CREATE/ALTER/DROP use aidp-sql-ddl; for file→table ingestion use aidp-ingest-file-to-table; for browsing use aidp-catalog-explore.

Register and validate reusable question→Spark-SQL pairs in .aidp/verified-queries.md so the agent reuses trusted SQL before generating new SQL. Use when the user wants to save a working query as canonical, build a verified-query repository, or improve answer reliability for recurring questions. Validates each pair on the cluster before marking it verified.

Work with AIDP volumes — list volumes, browse files inside a volume, upload/download via the PAR flow, and create directories. Use when the user mentions volumes, needs to stage large/binary files, or move data in/out of a volume (distinct from the workspace filesystem). Control-plane via the official `aidp` CLI.

Field-level data lineage report per mapping via `infa2aidp cli lineage`. Use when the user asks "where does this field come from" or wants a lineage artifact for documentation/audit purposes. Operates on the Informatica export directly (source mappings), not on the generated PySpark notebooks.