@tablecraft-app/plugin-api 1.4.0 → 1.5.0

package/dist/manifest.d.ts

@@ -74,6 +74,7 @@ export declare const connectionUrlSchema: z.ZodObject<{
         values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strict>>>;
     sets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>>;
+    semicolonParams: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type ConnectionUrl = z.infer<typeof connectionUrlSchema>;
 /**
@@ -181,6 +182,7 @@ export declare const pluginManifestSchema: z.ZodObject<{
                 values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             }, z.core.$strict>>>;
             sets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>>;
+            semicolonParams: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         network: z.ZodOptional<z.ZodObject<{
             host: z.ZodString;

package/dist/manifest.js

@@ -68,6 +68,11 @@ export const connectionUrlSchema = z.strictObject({
     sets: z
         .record(z.string().regex(URL_SCHEME), z.record(z.string().regex(FIELD_KEY), z.union([z.string(), z.number(), z.boolean()])))
         .optional(),
+    /**
+     * The JDBC SQL Server form, `scheme://host[\instance][:port][;name=value…]` (plan 055): parameters
+     * follow `;`, a `{…}` value may hold one, and `\instance` is the parameter `instanceName`.
+     */
+    semicolonParams: z.boolean().optional(),
 });
 /**
  * Which fields hold the server's address (decision 070), so the host can open an SSH tunnel and

package/dist/plugin.d.ts

@@ -122,6 +122,12 @@ export interface ExecuteOptions {
      * leads each row with a `node` column, and anything else is a `ServerNode.id`.
      */
     readonly node?: string;
+    /**
+     * `StatementSpan.repeat` of the statement, at least 2, when the script asks for it to run more
+     * than once (SQL Server's `GO 3`, decision 100). A plugin that splits such scripts runs it that
+     * many times and answers with the last run; any other plugin never receives it.
+     */
+    readonly repeat?: number;
 }
 /** `ExecuteOptions.node`: the plugin routes the command by its keys (decision 114). */
 export declare const NODE_AUTO = "auto";
@@ -311,7 +317,8 @@ export interface StatementSpan {
     readonly sql: string;
     /**
      * How many times the script asks for the statement to run: SQL Server's `GO 3` after it
-     * (decision 100). Absent means once. The host never repeats a statement; a plugin may.
+     * (decision 100). Absent means once. The host never repeats a statement; it passes the count
+     * as `ExecuteOptions.repeat` and the plugin runs it that many times.
      */
     readonly repeat?: number;
 }

package/dist/sql/complete.js

@@ -70,6 +70,8 @@ const BOOST = {
     keyword: -10,
 };
 const UNQUOTED_WORD = "^[A-Za-z0-9_$]*$";
+/** Where `@` and `#` start a name (`variables`), the typed `@@` stays part of what is filtered. */
+const VARIABLE_WORD = "^[@#]*[A-Za-z0-9_$]*$";
 const ALIAS_WORD_BREAK = /[^A-Za-z0-9]+|(?<=[a-z0-9])(?=[A-Z])/;
 const FALLBACK_ALIAS = "t";
 const QUOTES = new Set(['"', "`", "["]);
@@ -126,6 +128,7 @@ function relationKind(relation) {
 /** The shared completion and navigation every built-in plugin spreads into its `SqlLanguage` (decision 028). */
 export function sqlCompleter(options) {
     const reserved = new Set(options.keywords.map((keyword) => keyword.toUpperCase()));
+    const unquotedWord = options.dialect.variables === true ? VARIABLE_WORD : UNQUOTED_WORD;
     const { denotes, sameIdentifier, cteNamed, sourceNamed, serverOf, Lookup } = nameRules(options);
     const specs = new Map();
     for (const spec of options.functions) {
@@ -224,7 +227,9 @@ export function sqlCompleter(options) {
             .filter((word) => word !== "")
             .map((word) => word.charAt(0).toLowerCase())
             .join("");
-        const base = initials === "" || !options.plainIdentifier.test(initials) ? FALLBACK_ALIAS : initials;
+        // Unquoted, an alias folds like any name; `c` is written as is and reads back as `C` under upper folding.
+        const folded = options.identifierFolding === "upper" ? initials.toUpperCase() : initials;
+        const base = initials === "" || !options.plainIdentifier.test(folded) ? FALLBACK_ALIAS : initials;
         let alias = base;
         for (let suffix = 1; taken.has(alias) || reserved.has(alias.toUpperCase()); suffix += 1)
             alias = `${base}${String(suffix)}`;
@@ -258,7 +263,9 @@ export function sqlCompleter(options) {
                 continue;
             const near = source.alias === null
                 ? relationReference(found.path, found.relation.name, lookup.current)
-                : quoted(source.alias.name);
+                : source.alias.quoted
+                    ? options.quoteIdentifier(source.alias.name)
+                    : source.alias.name;
             for (const key of found.relation.foreignKeys) {
                 const alias = aliasFor(key.target.relation, new Set(taken));
                 const on = key.columns
@@ -376,7 +383,7 @@ export function sqlCompleter(options) {
                 const lookup = new Lookup(catalog);
                 await lookup.follow(request.text, request.offset);
                 const items = await namespaceItems(slot, lookup);
-                return { from: slot.from, to: slot.to, items, validFor: slot.quote === null ? UNQUOTED_WORD : null };
+                return { from: slot.from, to: slot.to, items, validFor: slot.quote === null ? unquotedWord : null };
             }
         }
         const { text, offset, shift } = wrap(request);
@@ -390,7 +397,7 @@ export function sqlCompleter(options) {
             from: scope.prefixFrom - shift,
             to: offset - shift,
             items: typedQuote ? quotedLabels(items) : items,
-            validFor: typedQuote ? null : UNQUOTED_WORD,
+            validFor: typedQuote ? null : unquotedWord,
         };
     }
     function sourceDeclaring(query, word) {

package/dist/sql/inspectResolve.js

@@ -28,6 +28,7 @@ const COLUMN_CLAUSES = new Set([
 /** Symbols right before a word that make it a parameter or variable: `:name`, `@var`, `x::type`. */
 const PARAMETER_MARKS = new Set([":", "@", "?"]);
 const PARAMETER_START = /^[$@:]/;
+const PARAMETER_OR_TEMPORARY = /^[@#]/;
 /** Rows a statement may name without declaring them: PostgreSQL's `EXCLUDED`, a trigger's `NEW` and `OLD`. */
 const PSEUDO_RELATIONS = new Set(["EXCLUDED", "NEW", "OLD"]);
 const RELATION_INTRODUCERS = new Set(["FROM", "JOIN", "UPDATE", "INTO", "STRAIGHT_JOIN"]);
@@ -146,6 +147,9 @@ async function unresolvedRelation(view, query, source) {
         return [];
     if (!source.name.quoted && NOT_RELATION_NAMES.has(source.name.name.toUpperCase()))
         return [];
+    // SQL Server's `#temp` and `@table` live in no catalog the explorer reads.
+    if (!source.name.quoted && PARAMETER_OR_TEMPORARY.test(source.name.name))
+        return [];
     const { lookup } = view;
     let path = lookup.current;
     if (source.qualifier.length > 0) {

package/dist/sql/namespace.d.ts

@@ -23,7 +23,8 @@ export interface NamespaceSlot {
 }
 /**
  * Where the caret at `offset` names a namespace a session-namespace statement of the dialect moves
- * to: `USE |` or the elements of `SET search_path TO a, |` and `SET SCHEMA |`. Null anywhere else,
+ * to: `USE |`, `ALTER SESSION SET CURRENT_SCHEMA = |` or the elements of `SET search_path TO a, |`
+ * and `SET SCHEMA |`. Null anywhere else,
  * and after a name whose closing quote is typed.
  */
 export declare function namespaceSlotAt(text: string, offset: number, dialect: SqlDialectOptions): NamespaceSlot | null;

package/dist/sql/namespace.js

@@ -82,6 +82,17 @@ function searchPathTarget(text, tokens) {
         return null;
     return { kind: "schema", candidates: names };
 }
+const ALTER_SESSION_PREFIX = ["ALTER", "SESSION", "SET", "CURRENT_SCHEMA", "="];
+function alterSessionPrefix(text, tokens) {
+    return ALTER_SESSION_PREFIX.every((word, at) => wordAt(text, tokens, at) === word);
+}
+function alterSessionTarget(text, tokens) {
+    if (tokens.length !== ALTER_SESSION_PREFIX.length + 1 || !alterSessionPrefix(text, tokens))
+        return null;
+    const token = tokens[ALTER_SESSION_PREFIX.length];
+    const name = identifier(text, token);
+    return name === null || token?.kind === "string" ? null : { kind: "schema", candidates: [name] };
+}
 const NAME_TOKENS = new Set(["word", "quoted", "string"]);
 /** The statement's tokens around `offset`, comments dropped; null when the caret is in a comment. */
 function tokensAround(text, offset, dialect) {
@@ -136,7 +147,8 @@ function searchPathListStart(text, tokens) {
 }
 /**
  * Where the caret at `offset` names a namespace a session-namespace statement of the dialect moves
- * to: `USE |` or the elements of `SET search_path TO a, |` and `SET SCHEMA |`. Null anywhere else,
+ * to: `USE |`, `ALTER SESSION SET CURRENT_SCHEMA = |` or the elements of `SET search_path TO a, |`
+ * and `SET SCHEMA |`. Null anywhere else,
  * and after a name whose closing quote is typed.
  */
 export function namespaceSlotAt(text, offset, dialect) {
@@ -168,6 +180,13 @@ export function namespaceSlotAt(text, offset, dialect) {
                 continue;
             return { kind: "database", from, to: offset, quote, listed: [] };
         }
+        if (form === "alterSessionSchema") {
+            if (prefix?.kind === "string" || before.length !== ALTER_SESSION_PREFIX.length)
+                continue;
+            if (!alterSessionPrefix(text, before))
+                continue;
+            return { kind: "schema", from, to: offset, quote, listed: [] };
+        }
         const start = searchPathListStart(text, before);
         if (start === null)
             continue;
@@ -190,15 +209,26 @@ export function namespaceTarget(sql, dialect) {
         return null;
     const tokens = significantTokens(sql, dialect).filter((token) => token.kind !== "delimiter");
     for (const form of forms) {
-        const target = form === "use" ? useTarget(sql, tokens) : searchPathTarget(sql, tokens);
+        const target = TARGET_READERS[form](sql, tokens);
         if (target !== null)
             return target;
     }
     return null;
 }
+const TARGET_READERS = {
+    use: useTarget,
+    searchPath: searchPathTarget,
+    alterSessionSchema: alterSessionTarget,
+};
 const SWITCH_TARGETS = {
     use: "topLevel",
     searchPath: "schema",
+    alterSessionSchema: "schema",
+};
+const SWITCH_STATEMENTS = {
+    use: (quoted) => `USE ${quoted}`,
+    searchPath: (quoted) => `SET search_path TO ${quoted}`,
+    alterSessionSchema: (quoted) => `ALTER SESSION SET CURRENT_SCHEMA = ${quoted}`,
 };
 /**
  * The console's namespace switch for a dialect moving its namespace by `form` (decision 060):
@@ -214,7 +244,7 @@ export function namespaceSwitcher(form, quoteIdentifier) {
             if (name === undefined) {
                 throw new PluginError("statementFailed", "A namespace switch names no namespace; pick one from the list.");
             }
-            return form === "use" ? `USE ${quoteIdentifier(name)}` : `SET search_path TO ${quoteIdentifier(name)}`;
+            return SWITCH_STATEMENTS[form](quoteIdentifier(name));
         },
     };
 }

package/dist/sql/tokens.d.ts

@@ -26,13 +26,16 @@ export interface SqlDialectOptions {
     readonly qQuotes?: boolean;
     /** `N'…'` national character strings. */
     readonly nationalStrings?: boolean;
+    /** SQL Server `@local`, `@@global` and `#temp` names: `@` and `#` are part of a word. */
+    readonly variables?: boolean;
 }
 export type BatchSeparator = "go" | "slash";
 /**
  * `use` is MySQL's `USE db`; `searchPath` is PostgreSQL's `SET [SESSION | LOCAL] search_path`,
- * `SET SCHEMA` and `RESET search_path` / `RESET ALL`.
+ * `SET SCHEMA` and `RESET search_path` / `RESET ALL`; `alterSessionSchema` is Oracle's
+ * `ALTER SESSION SET CURRENT_SCHEMA = name`.
  */
-export type NamespaceStatementForm = "use" | "searchPath";
+export type NamespaceStatementForm = "use" | "searchPath" | "alterSessionSchema";
 export type TokenKind = "word" | "quoted" | "string" | "comment" | "symbol" | "delimiter";
 export interface Token {
     readonly kind: TokenKind;

package/dist/sql/tokens.js

@@ -16,6 +16,7 @@ const Q_QUOTE_PAIRS = new Map([
 const STRING_QUOTE = "'";
 const BRACKET_OPEN = "[";
 const BRACKET_CLOSE = "]";
+const VARIABLE_CHARS = new Set(["@", "#"]);
 function isSpace(char) {
     return char === " " || char === "\t" || char === "\n" || char === "\r" || char === "\f" || char === "\v";
 }
@@ -70,13 +71,16 @@ export class Lexer {
         else if (char === "$" && this.options.dollarQuotes === true && this.#dollarTag(at) !== null) {
             token = this.#dollarQuoted(at, this.#dollarTag(at) ?? "");
         }
-        else if (isWordChar(char))
+        else if (this.#isWordChar(char))
             token = this.#word(at, delimiter);
         else
             token = { kind: "symbol", from: at, to: at + 1 };
         this.position = token.to;
         return token;
     }
+    #isWordChar(char) {
+        return isWordChar(char) || (this.options.variables === true && VARIABLE_CHARS.has(char));
+    }
     #lineComment(from) {
         const end = this.text.indexOf(NEWLINE, from);
         return { kind: "comment", from, to: end < 0 ? this.text.length : end };
@@ -160,7 +164,7 @@ export class Lexer {
         const text = this.text;
         const customDelimiter = delimiter !== DEFAULT_DELIMITER;
         let at = from;
-        while (at < text.length && isWordChar(text.charAt(at))) {
+        while (at < text.length && this.#isWordChar(text.charAt(at))) {
             if (customDelimiter && at > from && text.startsWith(delimiter, at))
                 break;
             at += 1;

package/dist/testing/index.d.ts

@@ -87,6 +87,16 @@ export interface ContractFixture {
             readonly config: unknown;
             readonly note: RegExp;
         };
+        /**
+         * False where the dialect cannot interrupt another session's statement and keep it connected,
+         * as SQL Server's `KILL` cannot: every row's `cancel` is null and `cancelSession` rejects.
+         */
+        readonly cancels?: boolean;
+        /**
+         * A session id no session has, for servers that hand a closed session's id to the next login
+         * (SQL Server): without it the test closes a session of its own and waits for its id to go.
+         */
+        readonly missingId?: string;
     };
     /** Required when the plugin declares `routineCall`, which also needs `catalog`. */
     readonly routines?: {
@@ -108,6 +118,8 @@ export interface ContractFixture {
      * default. `LINE_ITEMS_TABLE` is quoted in every dialect and never folded.
      */
     readonly foldName?: (name: string) => string;
+    /** The database stores an empty string as NULL, as Oracle does, so an empty text reads back null. */
+    readonly emptyTextIsNull?: boolean;
 }
 /** Dialect-specific text the suite runs; every member is optional (decision 100). */
 export interface ContractSql {
@@ -128,6 +140,10 @@ export interface ContractSql {
     };
     /** Opens a transaction explicitly in auto-commit mode. */
     readonly begin?: string;
+    /** A name only quoting makes legal, which the dialect accepts; Oracle refuses a `"` inside one. */
+    readonly awkwardIdentifier?: string;
+    /** What `ExplainedPlan.statement` starts with; `EXPLAIN` by default, `SET SHOWPLAN_XML ON` on SQL Server. */
+    readonly explainStatement?: RegExp;
 }
 /** A command and the result tab it opens: column names and rows as wire values. */
 export interface CommandRows {

package/dist/testing/index.js

@@ -117,8 +117,11 @@ export function contractSql(fixture) {
         temporaryTable: fixture.sql?.temporaryTable ??
             ((name, columns) => ({ create: `CREATE TEMPORARY TABLE ${name} (${columns})`, name })),
         begin: fixture.sql?.begin ?? "BEGIN",
+        awkwardIdentifier: fixture.sql?.awkwardIdentifier ?? AWKWARD_IDENTIFIER,
+        explainStatement: fixture.sql?.explainStatement ?? DEFAULT_EXPLAIN_STATEMENT,
     };
 }
+const DEFAULT_EXPLAIN_STATEMENT = /^EXPLAIN\b/i;
 const ROWS_READ_BEFORE_RETURN = 3;
 /** Longer than `BYTES_PREVIEW_LENGTH` and within every fixture's `payload` column (MySQL's is `VARBINARY(64)`). */
 const LONG_BYTES_LENGTH = 48;
@@ -678,9 +681,9 @@ export function runPluginContract(plugin, fixture) {
             });
             it("givenAwkwardIdentifier_whenQuotedAndSelected_thenNameReadsBack", async () => {
                 await withSession(plugin, fixture, async (session) => {
-                    const result = await session.execute(dialectSql.select(`1 AS ${language().quoteIdentifier(AWKWARD_IDENTIFIER)}`));
+                    const result = await session.execute(dialectSql.select(`1 AS ${language().quoteIdentifier(dialectSql.awkwardIdentifier)}`));
                     await collect(result.rows);
-                    expect(result.columns.map((column) => column.name)).toEqual([AWKWARD_IDENTIFIER]);
+                    expect(result.columns.map((column) => column.name)).toEqual([dialectSql.awkwardIdentifier]);
                 });
             });
             it("givenTypeProbeRow_whenSqlInsertPerDialect_thenRoundTripsEqual", async () => {
@@ -861,7 +864,7 @@ export function runPluginContract(plugin, fixture) {
                     const texts = AWKWARD_TEXTS;
                     const rows = texts.map((text, index) => target.columns.map((column) => column.name === fold("id") ? String(index + 1) : column.name === fold("unicode_text") ? text : null));
                     await insertRowsOf(session)(target, rows);
-                    expect(await run(session, `SELECT unicode_text FROM ${TYPE_PROBE_COPY_TABLE} ORDER BY id`)).toEqual(texts.map((text) => [text]));
+                    expect(await run(session, `SELECT unicode_text FROM ${TYPE_PROBE_COPY_TABLE} ORDER BY id`)).toEqual(texts.map((text) => [text === "" && fixture.emptyTextIsNull === true ? null : text]));
                 });
             });
             it("givenCreateTable_whenEveryImportType_thenTableTakesSampleText", async () => {
@@ -904,7 +907,7 @@ export function runPluginContract(plugin, fixture) {
                 return session.introspector;
             }
             async function relationOf(session, name) {
-                return (await introspectorOf(session).describe(path())).relations.find((relation) => relation.name === name);
+                return (await introspectorOf(session).describe(path())).relations.find((relation) => relation.name === fold(name));
             }
             /** Runs a script as the engine does: prepare, the statements in one transaction where it says so, verify, finish. */
             async function apply(session, script) {
@@ -948,14 +951,14 @@ export function runPluginContract(plugin, fixture) {
                 return editorOf().script(change, context);
             }
             function column(name, type, nullable = true) {
-                return { name, type, nullable, default: null, autoIncrement: false, comment: null, original: null };
+                return { name: fold(name), type, nullable, default: null, autoIncrement: false, comment: null, original: null };
             }
             function parentDesign() {
                 return {
-                    name: OBJECT_PARENT_TABLE,
+                    name: fold(OBJECT_PARENT_TABLE),
                     comment: null,
                     columns: [column("id", OBJECT_KEY_TYPE, false)],
-                    primaryKey: ["id"],
+                    primaryKey: [fold("id")],
                     primaryKeyName: null,
                     indexes: [],
                     foreignKeys: [],
@@ -964,7 +967,7 @@ export function runPluginContract(plugin, fixture) {
             }
             function childDesign() {
                 return {
-                    name: OBJECT_CHILD_TABLE,
+                    name: fold(OBJECT_CHILD_TABLE),
                     comment: null,
                     columns: [
                         column("id", OBJECT_KEY_TYPE, false),
@@ -972,14 +975,14 @@ export function runPluginContract(plugin, fixture) {
                         column("label", OBJECT_NARROW_TYPE),
                         column("obsolete", OBJECT_NARROW_TYPE),
                     ],
-                    primaryKey: ["id"],
+                    primaryKey: [fold("id")],
                     primaryKeyName: null,
-                    indexes: [{ name: OBJECT_INDEX, columns: ["label"], unique: false, original: null }],
+                    indexes: [{ name: fold(OBJECT_INDEX), columns: [fold("label")], unique: false, original: null }],
                     foreignKeys: [
                         {
-                            name: OBJECT_FOREIGN_KEY,
-                            columns: ["parent_id"],
-                            target: { path: path(), relation: OBJECT_PARENT_TABLE, columns: ["id"] },
+                            name: fold(OBJECT_FOREIGN_KEY),
+                            columns: [fold("parent_id")],
+                            target: { path: path(), relation: fold(OBJECT_PARENT_TABLE), columns: [fold("id")] },
                             onDelete: "CASCADE",
                             onUpdate: null,
                             original: null,
@@ -1020,8 +1023,8 @@ export function runPluginContract(plugin, fixture) {
                     ...described,
                     columns: [
                         ...described.columns
-                            .filter((entry) => entry.name !== "obsolete")
-                            .map((entry) => (entry.name === "label" ? { ...entry, type: OBJECT_WIDE_TYPE } : entry)),
+                            .filter((entry) => entry.name !== fold("obsolete"))
+                            .map((entry) => (entry.name === fold("label") ? { ...entry, type: OBJECT_WIDE_TYPE } : entry)),
                         column("note", OBJECT_NARROW_TYPE),
                     ],
                     ...extra,
@@ -1030,11 +1033,11 @@ export function runPluginContract(plugin, fixture) {
             it("givenObjectsDeclared_whenCreateTableWithKeyIndexAndForeignKey_thenDescribedAsDesigned", async () => {
                 await withTables(async (session) => {
                     const child = await relationOf(session, OBJECT_CHILD_TABLE);
-                    expect(child?.columns.map((entry) => entry.name)).toEqual(["id", "parent_id", "label", "obsolete"]);
-                    expect(child?.primaryKey?.columns).toEqual(["id"]);
-                    expect(child?.indexes.map((index) => index.name)).toContain(OBJECT_INDEX);
+                    expect(child?.columns.map((entry) => entry.name)).toEqual(["id", "parent_id", "label", "obsolete"].map(fold));
+                    expect(child?.primaryKey?.columns).toEqual([fold("id")]);
+                    expect(child?.indexes.map((index) => index.name)).toContain(fold(OBJECT_INDEX));
                     expect(child?.foreignKeys.map((key) => [key.target.relation, key.target.columns, key.onDelete])).toEqual([
-                        [OBJECT_PARENT_TABLE, ["id"], "CASCADE"],
+                        [fold(OBJECT_PARENT_TABLE), [fold("id")], "CASCADE"],
                     ]);
                 });
             });
@@ -1046,7 +1049,7 @@ export function runPluginContract(plugin, fixture) {
                     const script = await scriptOf(session, {
                         kind: "alterTable",
                         path: path(),
-                        relation: OBJECT_CHILD_TABLE,
+                        relation: fold(OBJECT_CHILD_TABLE),
                         design: editorOf().design(relation),
                     });
                     expect(script.statements).toEqual([]);
@@ -1055,37 +1058,38 @@ export function runPluginContract(plugin, fixture) {
             it("givenTable_whenColumnAddedTypeChangedAndDropped_thenDescribedAfterAndRowsKept", async () => {
                 await withTables(async (session) => {
                     const design = await widenedChild(session);
-                    await apply(session, await scriptOf(session, { kind: "alterTable", path: path(), relation: OBJECT_CHILD_TABLE, design }));
+                    await apply(session, await scriptOf(session, { kind: "alterTable", path: path(), relation: fold(OBJECT_CHILD_TABLE), design }));
                     const child = await relationOf(session, OBJECT_CHILD_TABLE);
-                    expect(child?.columns.map((entry) => entry.name)).toEqual(["id", "parent_id", "label", "note"]);
-                    expect(child?.columns.find((entry) => entry.name === "label")?.type).toMatch(OBJECT_WIDE_LENGTH);
+                    expect(child?.columns.map((entry) => entry.name)).toEqual(["id", "parent_id", "label", "note"].map(fold));
+                    expect(child?.columns.find((entry) => entry.name === fold("label"))?.type).toMatch(OBJECT_WIDE_LENGTH);
                     expect(child?.foreignKeys).toHaveLength(1);
-                    expect(child?.indexes.map((index) => index.name)).toContain(OBJECT_INDEX);
+                    expect(child?.indexes.map((index) => index.name)).toContain(fold(OBJECT_INDEX));
                     expect(await run(session, `SELECT label FROM ${OBJECT_CHILD_TABLE}`)).toEqual([["kept"]]);
                 });
             });
             it.runIf(plugin.capabilities.includes("transactions"))("givenTransactionalScript_whenStatementFails_thenNothingApplied", async () => {
                 await withTables(async (session) => {
-                    // An index named like a table clashes in every dialect whose index names share the table namespace.
+                    // A second index under the table's own index name clashes in every dialect; one named like a
+                    // table does not where index names are per table, as on SQL Server.
                     const design = await widenedChild(session, {});
                     const clashing = {
                         ...design,
                         indexes: [
                             ...design.indexes,
-                            { name: OBJECT_PARENT_TABLE, columns: ["note"], unique: false, original: null },
+                            { name: fold(OBJECT_INDEX), columns: [fold("note")], unique: false, original: null },
                         ],
                     };
                     const script = await scriptOf(session, {
                         kind: "alterTable",
                         path: path(),
-                        relation: OBJECT_CHILD_TABLE,
+                        relation: fold(OBJECT_CHILD_TABLE),
                         design: clashing,
                     });
                     if (!script.transactional)
                         return;
                     await expect(apply(session, script)).rejects.toThrow();
                     const child = await relationOf(session, OBJECT_CHILD_TABLE);
-                    expect(child?.columns.map((entry) => entry.name)).toEqual(["id", "parent_id", "label", "obsolete"]);
+                    expect(child?.columns.map((entry) => entry.name)).toEqual(["id", "parent_id", "label", "obsolete"].map(fold));
                     expect(await run(session, `SELECT label FROM ${OBJECT_CHILD_TABLE}`)).toEqual([["kept"]]);
                 });
             });
@@ -1094,8 +1098,8 @@ export function runPluginContract(plugin, fixture) {
                     await apply(session, await scriptOf(session, {
                         kind: "rename",
                         path: path(),
-                        object: { kind: "table", name: OBJECT_CHILD_TABLE },
-                        name: OBJECT_RENAMED_TABLE,
+                        object: { kind: "table", name: fold(OBJECT_CHILD_TABLE) },
+                        name: fold(OBJECT_RENAMED_TABLE),
                     }));
                     expect(await relationOf(session, OBJECT_CHILD_TABLE)).toBeUndefined();
                     expect((await relationOf(session, OBJECT_RENAMED_TABLE))?.columns).toHaveLength(4);
@@ -1103,7 +1107,12 @@ export function runPluginContract(plugin, fixture) {
             });
             it("givenTableWithRows_whenTruncated_thenEmptyAndStillDescribed", async () => {
                 await withTables(async (session) => {
-                    await apply(session, await scriptOf(session, { kind: "truncate", path: path(), relation: OBJECT_CHILD_TABLE, cascade: false }));
+                    await apply(session, await scriptOf(session, {
+                        kind: "truncate",
+                        path: path(),
+                        relation: fold(OBJECT_CHILD_TABLE),
+                        cascade: false,
+                    }));
                     expect(await run(session, `SELECT id FROM ${OBJECT_CHILD_TABLE}`)).toEqual([]);
                     expect(await relationOf(session, OBJECT_CHILD_TABLE)).toBeDefined();
                 });
@@ -1113,7 +1122,7 @@ export function runPluginContract(plugin, fixture) {
                     await apply(session, await scriptOf(session, {
                         kind: "drop",
                         path: path(),
-                        object: { kind: "table", name: OBJECT_CHILD_TABLE },
+                        object: { kind: "table", name: fold(OBJECT_CHILD_TABLE) },
                         cascade: false,
                     }));
                     expect(await relationOf(session, OBJECT_CHILD_TABLE)).toBeUndefined();
@@ -1405,7 +1414,10 @@ export function runPluginContract(plugin, fixture) {
                 await withCompletion(async (language, catalog) => {
                     const result = await language.complete(at("SELECT * FROM orders o JOIN |", "|"), catalog);
                     const first = [...result.items].sort((left, right) => right.boost - left.boost)[0];
-                    expect(first).toMatchObject({ kind: "join", apply: "customers c ON c.id = o.customer_id" });
+                    expect(first).toMatchObject({
+                        kind: "join",
+                        apply: `${fold("customers")} c ON c.${fold("id")} = o.${fold("customer_id")}`,
+                    });
                 });
             });
             it("givenNameNeedingQuotes_whenCompleting_thenApplyIsQuotedByDialect", async () => {
@@ -1498,7 +1510,7 @@ export function runPluginContract(plugin, fixture) {
                     const read = session.introspector?.definition?.bind(session.introspector);
                     if (read === undefined)
                         throw new Error("A ddl session needs introspector.definition.");
-                    definition = await read(path, name);
+                    definition = await read(path, fold(name));
                 });
                 return definition;
             }
@@ -1634,7 +1646,7 @@ export function runPluginContract(plugin, fixture) {
                 await withSession(plugin, fixture, async (session) => {
                     const plan = await explained(session, dialectSql.explainJoin, false);
                     expect(plan.analyzed).toBe(false);
-                    expect(plan.statement).toMatch(/^EXPLAIN\b/i);
+                    expect(plan.statement).toMatch(dialectSql.explainStatement);
                     expect(plan.statement).toContain(dialectSql.explainJoin);
                     expect(plan.raw).toMatch(/\S/);
                     const nodes = planNodes(plan.roots);
@@ -1787,10 +1799,14 @@ export function runPluginContract(plugin, fixture) {
                 const { path } = namespaceSwitch();
                 const written = switcher();
                 await withSession(plugin, fixture, async (session) => {
+                    // A database switch reaches [database, default schema] on SQL Server, so the target may be a prefix.
                     const listed = (await session.introspector?.namespaces()) ?? [];
-                    const target = listed.find((namespace) => namespace.path.join(".") === path.join("."));
-                    expect(target === undefined ? false : switchableTo(written.targets, target)).toBe(true);
-                    const sql = written.statement(path);
+                    const target = listed
+                        .filter((namespace) => namespace.path.every((part, index) => part === path[index]))
+                        .filter((namespace) => switchableTo(written.targets, namespace))
+                        .sort((a, b) => b.path.length - a.path.length)[0];
+                    expect(target).toBeDefined();
+                    const sql = written.statement(target?.path ?? path);
                     expect(plugin.language?.classify(sql).setsNamespace).toBe(true);
                     await collect((await session.execute(sql)).rows);
                     expect(await current(session)).toEqual(path);
@@ -2240,7 +2256,16 @@ export function runPluginContract(plugin, fixture) {
                     });
                 });
             });
-            it("givenActiveQuery_whenCancel_thenQueryCancelled", async () => {
+            it.runIf(fixture.sessions?.cancels === false)("givenNoCancel_whenCancelSession_thenRejects", async () => {
+                await withMonitor(async (monitor) => {
+                    await withSleeper(async (sleeper) => {
+                        const row = await present(monitor, idOf(sleeper), (listed) => listed.state === "active");
+                        expect(row.cancel).toBeNull();
+                        expect(await rejectionCode(monitor.cancelSession({ id: row.id, instance: row.instance }))).toBe("statementFailed");
+                    });
+                });
+            });
+            it.runIf(fixture.sessions?.cancels !== false)("givenActiveQuery_whenCancel_thenQueryCancelled", async () => {
                 await withMonitor(async (monitor) => {
                     await withSleeper(async (sleeper, running) => {
                         const row = await present(monitor, idOf(sleeper), (listed) => listed.state === "active");
@@ -2268,6 +2293,15 @@ export function runPluginContract(plugin, fixture) {
                 }
             });
             it("givenMissingSession_whenTerminate_thenRejects", async () => {
+                const missingId = sessionsFixture().missingId;
+                if (missingId !== undefined) {
+                    await withMonitor(async (monitor) => {
+                        const listed = await monitor.list();
+                        expect(listed.sessions.map((session) => session.id)).not.toContain(missingId);
+                        expect(await rejectionCode(monitor.terminateSession({ id: missingId, instance: null }))).toBe("statementFailed");
+                    });
+                    return;
+                }
                 const victim = await connect(plugin, fixture.config);
                 const id = idOf(victim);
                 await victim.close();

package/dist/url.d.ts

@@ -25,6 +25,7 @@ export interface ConnectionUrlSpec {
         readonly values?: Readonly<Record<string, string>> | undefined;
     }[] | undefined;
     readonly sets?: Readonly<Record<string, Readonly<Record<string, ConnectionValue>>>> | undefined;
+    readonly semicolonParams?: boolean | undefined;
 }
 interface UrlField {
     readonly key: string;

package/dist/url.js

@@ -9,6 +9,9 @@ const SCHEME = /^([a-zA-Z][a-zA-Z0-9+.-]*):/;
 const WINDOWS_DRIVE_PATH = /^\/[A-Za-z]:[/\\]/;
 const LEADING_SLASHES = /^\/+/;
 const LOCAL_HOSTS = new Set(["", "localhost"]);
+/** `host`, `[v6]`, then SQL Server's `\instance` and the port, as the JDBC driver reads them. */
+const SEMICOLON_AUTHORITY = /^(\[[^\]]*\]|[^\\:]*)(?:\\([^:]*))?(?::([^:]*))?$/;
+const INSTANCE_PARAM = "instanceName";
 /** libpq's names for the parts of the URL, accepted as query parameters by every server form. */
 const PART_PARAMS = {
     host: "host",
@@ -104,6 +107,8 @@ function parseServer(form, url, text) {
     if (scheme === undefined || !url.schemes.includes(scheme) || !text.slice(scheme.length + 1).startsWith("//")) {
         throw new ConnectionUrlError(`Expected a URL starting with ${schemeList(url)}.`);
     }
+    if (url.semicolonParams === true)
+        return parseSemicolon(form, url, scheme, text);
     let parsed;
     try {
         parsed = new URL(text);
@@ -121,6 +126,56 @@ function parseServer(form, url, text) {
     collected.query(parsed.search);
     return collected.done();
 }
+/** Splits on `;` outside `{…}`, which the JDBC driver uses to put a `;` in a value. */
+function semicolonPairs(text) {
+    const pairs = [];
+    let current = "";
+    let braced = false;
+    for (const char of text) {
+        if (char === "{")
+            braced = true;
+        else if (char === "}")
+            braced = false;
+        if (char === ";" && !braced) {
+            pairs.push(current);
+            current = "";
+        }
+        else
+            current += char;
+    }
+    pairs.push(current);
+    return pairs.filter((pair) => pair.trim() !== "");
+}
+function unbraced(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith("{") && trimmed.endsWith("}") ? trimmed.slice(1, -1) : trimmed;
+}
+function parseSemicolon(form, url, scheme, text) {
+    const [authority = "", ...pairs] = semicolonPairs(text.slice(scheme.length + "://".length));
+    const match = SEMICOLON_AUTHORITY.exec(authority.trim());
+    if (match === null) {
+        throw new ConnectionUrlError(`"${authority}" is not host, host\\instance or host:port.`);
+    }
+    const [, host = "", instance, port] = match;
+    if (port !== undefined && !/^\d+$/.test(port)) {
+        throw new ConnectionUrlError(`The port "${port}" is not a number.`);
+    }
+    const collected = new Collected(form, url);
+    Object.assign(collected.values, url.sets?.[scheme]);
+    collected.part("host", host.replace(/^\[(.*)\]$/, "$1"));
+    if (port !== undefined)
+        collected.part("port", port);
+    if (instance !== undefined && instance !== "")
+        collected.param(INSTANCE_PARAM, instance);
+    for (const pair of pairs) {
+        const equals = pair.indexOf("=");
+        if (equals < 0)
+            collected.ignored.push(pair.trim());
+        else
+            collected.param(pair.slice(0, equals).trim(), unbraced(pair.slice(equals + 1)));
+    }
+    return collected.done();
+}
 function parseFile(form, url, text) {
     const collected = new Collected(form, url);
     const scheme = SCHEME.exec(text)?.[1]?.toLowerCase();
@@ -175,6 +230,37 @@ function isConnectionValue(value) {
 function written(value) {
     return String(value);
 }
+function bracedValue(value) {
+    return /[;{}=]/.test(value) || value !== value.trim() ? `{${value}}` : value;
+}
+/** Every parameter after a `;`, one per field, so a part a parameter also names is written once. */
+function semicolonUrl(form, url, scheme, config) {
+    const text = (key) => {
+        if (key === undefined || fieldOf(form, key)?.secret === true)
+            return "";
+        const value = config[key];
+        return isConnectionValue(value) ? written(value) : "";
+    };
+    const host = text(url.parts.host);
+    const port = text(url.parts.port);
+    const pairs = [];
+    const keys = new Set([url.parts.host, url.parts.port]);
+    for (const param of url.params ?? []) {
+        if (keys.has(param.key))
+            continue;
+        keys.add(param.key);
+        const value = config[param.key];
+        const field = fieldOf(form, param.key);
+        if (field?.secret === true || !isConnectionValue(value) || value === "" || value === field?.default)
+            continue;
+        const shown = param.values === undefined
+            ? written(value)
+            : Object.entries(param.values).find(([, mapped]) => mapped === value)?.[0];
+        if (shown !== undefined)
+            pairs.push(`;${param.name}=${bracedValue(shown)}`);
+    }
+    return `${scheme}://${host.includes(":") ? `[${host}]` : host}${port === "" ? "" : `:${port}`}${pairs.join("")}`;
+}
 function encodedPath(path) {
     return encodeURI(path).replaceAll("?", "%3F").replaceAll("#", "%23");
 }
@@ -193,6 +279,8 @@ export function formatConnectionUrl(form, config) {
         url.schemes.find((candidate) => url.sets?.[candidate] === undefined) ??
         url.schemes[0] ??
         "";
+    if (url.semicolonParams === true)
+        return semicolonUrl(form, url, scheme, config);
     const valueOf = (part) => {
         const key = url.parts[part];
         if (key === undefined || fieldOf(form, key)?.secret === true)

package/dist/version.js

@@ -2,7 +2,7 @@
  * The plugin contract's version, by semver (decision 106): a host loads a plugin built for the same
  * major and an older or equal minor. Typed `string` so a bump does not change the API report.
  */
-export const API_VERSION = "1.4.0";
+export const API_VERSION = "1.5.0";
 const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 /** `major.minor.patch` and nothing else; pre-release and build tags are not accepted. */
 export function parseVersion(text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablecraft-app/plugin-api",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "The datasource plugin contract for TableCraft",
   "license": "MIT",
   "type": "module",