IF Commons GitHub

sql/physical/dialect

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0007-physical FR-004, 0007-physical FR-005

The dialect (commons data 0007-physical FR-004): how one engine writes what a logical schema says. A dialect is a value: how a name is quoted and a literal written, the type of each logical type, how the moment of the insert is a default, whether it can say a pattern, whether it has COMMENT ON, and how long a name may be. The library's three are extensions of sql/dialects/, which contribute themselves through the engine's point physical.dialect; what a dialect cannot express is an error of bind, never SQL its engine refuses.

Source: commons/data/sql/physical/dialect.ts

3 of 21 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Dialectinterface
interface Dialect

One engine's way of writing.

MemberTypeWhat it is
namestring
featuresreadonly Feature[]
maxNamenumberThe longest a name may be.
nowstringThe default that is the moment of the insert.
quote(name: string) => string
literal(value: Literal) => string
type(type: LogicalType) => string
hash?((text: string) => string | undefined)The expression that hashes a text expression, or none where the engine has no hash (0014-sql-protected-access FR-011).
hasRole?((role: string) => string | undefined)A condition that is true when the role that reads is a member of a role, or none where the engine has no way to say it.
unsupported?((type: LogicalType) => string | undefined)Why the dialect cannot store a type, or nothing where it can (0009-sql-features FR-003).
addColumnRefusal?((column: { readonly type: LogicalType; readonly nullable: boolean; readonly default?: LogicalDefault | undefined; }) => string | undefined)Why the dialect cannot add a column like this to a table that exists, or nothing where it can (0011-sql-lifecycle FR-006).
ifExists?readonly IfExistsForm[]Which forms of DROP and ADD COLUMN the dialect writes with IF [NOT] EXISTS.
catalog?CatalogHow the dialect reads its catalog; none where it cannot.
observe?((query: Query, schema?: string | undefined) => Promise<readonly ObservedTable[]>)How the dialect observes a whole database: tables, columns, keys, unique constraints, foreign keys and indexes (0055-sql-introspect FR-001); none where it cannot.
advisory?AdvisoryHow the dialect keeps one instance applying at a time; none where there is only one.
cascade?booleanWhether DROP TABLE and DROP VIEW take CASCADE, so that a table can be made again under views that read it (0023-sql-transforms).
attach?AttachHow a database file of the same engine is attached for reading and let go; none where the engine cannot (0022-sql-integrations).
rebuild?RebuildHow a table is made again where the dialect cannot change it in place (0017-sql-rewrite).
locks?LocksHow the dialect asks for its locks with a limit; none where it has no such thing.
deferredValidation?booleanWhether a foreign key or a check can be added without checking the rows that are there, and checked afterwards.
probes?ProbesHow to ask the catalog whether a table, column, constraint or index exists.
setup?((types: readonly LogicalType[]) => readonly string[])Statements to run before the tables, for the types a schema uses (0009-sql-features FR-003).
pattern?((column: string, pattern: string) => string)A check that a column matches a regular expression, or none where the engine has no way to say it.

Imported by 163 tests of the run (163 passed, 0 failed): the library's results

dialectExtensionfunctionno test imports it
function dialectExtension(d: Dialect, version?: string): Result<Extension, IdError>

An extension that contributes a dialect, named sql.dialect.<name>.

ParameterWhat it is
dthe dialect
versionthe extension's version

Returns: the extension, or why its identifier is not one

dialectPointconstno test imports it
const dialectPoint: ContributionPoint<Dialect>

The contribution point an extension fills to add a dialect.

dialectsFromfunction
function dialectsFrom(composition: Composition): readonly Dialect[]

The dialects of a composition, in its order.

ParameterWhat it is
compositionthe project's composition

Returns: the dialects its extensions contribute

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

Featuretypeno test imports it
type Feature =
  | "comment-on"
  | "regex-check"
  | "add-constraint"
  | "or-replace-view"
  | "row-security"
  | "grants"
  | "routines"
  | "partitions"
  | "alter-column"
  | "schemas"
  | "updatable-views"
  | "instead-of-triggers"
  | "triggers"
  | "event-triggers";

What a dialect can do beyond the common ground.

IfExistsFormtypeno test imports it
type IfExistsForm = "addColumn" | "dropColumn" | "dropConstraint" | "dropTable" | "dropIndex";

The forms of DROP and ADD COLUMN that a dialect writes with IF [NOT] EXISTS (0012-sql-idempotency FR-001).

Advisoryinterfaceno test imports it
interface Advisory

How a dialect keeps one instance from applying a plan while another does.

MemberTypeWhat it is
acquire(key: number) => string
release(key: number) => string
Attachinterfaceno test imports it
interface Attach

How a database file is attached for reading, and detached.

MemberTypeWhat it is
attach(file: string, alias: string) => string
detach(alias: string) => string
Cataloginterfaceno test imports it
interface Catalog

How a dialect reads its own catalog (0019-sql-convergence FR-001).

MemberTypeWhat it is
comparesreadonly string[]What the dialect compares, in words, so that what it does not is said.
read(query: Query, schema?: string | undefined) => Promise<readonly LiveTable[]>
Observedinterface
interface Observed

What a database holds, as a dialect observes it (0055-sql-introspect FR-001).

MemberTypeWhat it is
dialectstring
schema?string
tablesreadonly ObservedTable[]

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

ObservedColumninterfaceno test imports it
interface ObservedColumn

A column as a database holds it.

MemberTypeWhat it is
namestring
typestringThe type as the engine says it, in lower case (integer, numeric(10,2), timestamp with time zone, vector(3)).
nullableboolean
default?string
ObservedTableinterfaceno test imports it
interface ObservedTable

A table as a database holds it.

MemberTypeWhat it is
namestring
columnsreadonly ObservedColumn[]
primaryKeyreadonly string[]
uniquesreadonly { readonly columns: readonly string[]; }[]
foreignKeysreadonly { readonly columns: readonly string[]; readonly references: { readonly table: string; readonly columns: readonly string[]; }; }[]
indexesreadonly { readonly name: string; readonly columns: readonly string[]; readonly unique: boolean; }[]
Locksinterfaceno test imports it
interface Locks

How a dialect asks for its locks with a limit, and how its error for giving up is told (0015-sql-safety FR-008).

MemberTypeWhat it is
timeouts(lockMs: number, statementMs: number) => readonly string[]The statements that make the rest of the transaction wait at most so long for a lock and run at most so long.
timedOut(message: string) => booleanWhether an error message is the engine giving up on a lock.
LiveColumninterfaceno test imports it
interface LiveColumn

A column as a database's catalog says it is.

MemberTypeWhat it is
namestring
typestring
nullableboolean
default?stringThe default as the catalog says it, where the dialect can list it (0019-sql-convergence FR-001).
LiveTableinterfaceno test imports it
interface LiveTable

A table as a database's catalog says it is.

MemberTypeWhat it is
namestring
columnsreadonly LiveColumn[]
primaryKeyreadonly string[]
indexesreadonly string[]The names of the indexes that no constraint owns.
constraints?readonly { readonly name: string; readonly kind: "check" | "foreignKey" | "unique"; }[]The names and kinds of its foreign keys, uniques and checks, where the dialect can list them.
Querytypeno test imports it
type Query = (sql: string) => Promise<readonly Record<string, unknown>[]>;

A way to run a query and read its rows.

Rebuildinterfaceno test imports it
interface Rebuild

What a dialect needs to make a table again: statements to run first (so that rows that refer to it are not checked until the end) and whether tables that refer to it stop it.

MemberTypeWhat it is
preludereadonly string[]
blockedByParentsbooleanWhether a table that other tables' foreign keys refer to cannot be dropped.
Probesinterfaceno test imports it
interface Probes

Queries on a dialect's catalog that return a row if and only if the thing exists, or none where the engine cannot say (0012-sql-idempotency FR-001).

MemberTypeWhat it is
table(table: string, schema?: string | undefined) => string
column(table: string, column: string, schema?: string | undefined) => string
constraint(table: string, name: string, schema?: string | undefined) => string | undefined
index(name: string, schema?: string | undefined) => string
validConstraint?((table: string, name: string, schema?: string | undefined) => string)A query that returns a row if and only if the constraint exists and its rows have been checked (0015-sql-safety FR-009).
triggers?((table: string, schema?: string | undefined) => string)A query that returns one row of one number: how many triggers the table has (0017-sql-rewrite FR-009).
Literaltypeno test imports it
type Literal = string | number | boolean | null;

A literal a statement may hold.

quoteNameconstno test imports it
const quoteName: (name: string) => string

A name in double quotes, a quote in it doubled: how SQL's standard writes an identifier.

standardLiteralfunctionno test imports it
function standardLiteral(value: Literal): string

A literal as SQL's standard writes it: text in single quotes with a quote doubled, true and false, a number as it is, null.

Titles, headings, exports, tables, columns and requirements. Esc closes.