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.
interface Dialect
One engine's way of writing.
| Member | Type | What it is |
|---|
name | string | |
features | readonly Feature[] | |
maxName | number | The longest a name may be. |
now | string | The 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? | Catalog | How 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? | Advisory | How the dialect keeps one instance applying at a time; none where there is only one. |
cascade? | boolean | Whether DROP TABLE and DROP VIEW take CASCADE, so that a table can be made again under views that read it (0023-sql-transforms). |
attach? | Attach | How a database file of the same engine is attached for reading and let go; none where the engine cannot (0022-sql-integrations). |
rebuild? | Rebuild | How a table is made again where the dialect cannot change it in place (0017-sql-rewrite). |
locks? | Locks | How the dialect asks for its locks with a limit; none where it has no such thing. |
deferredValidation? | boolean | Whether a foreign key or a check can be added without checking the rows that are there, and checked afterwards. |
probes? | Probes | How 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 itfunction dialectExtension(d: Dialect, version?: string): Result<Extension, IdError>
An extension that contributes a dialect, named sql.dialect.<name>.
| Parameter | What it is |
|---|
d | the dialect |
version | the extension's version |
Returns: the extension, or why its identifier is not one
dialectPointconstno test imports itconst dialectPoint: ContributionPoint<Dialect>
The contribution point an extension fills to add a dialect.
function dialectsFrom(composition: Composition): readonly Dialect[]
The dialects of a composition, in its order.
| Parameter | What it is |
|---|
composition | the 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 ittype 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 ittype 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 itinterface Advisory
How a dialect keeps one instance from applying a plan while another does.
| Member | Type | What it is |
|---|
acquire | (key: number) => string | |
release | (key: number) => string | |
Attachinterfaceno test imports itinterface Attach
How a database file is attached for reading, and detached.
| Member | Type | What it is |
|---|
attach | (file: string, alias: string) => string | |
detach | (alias: string) => string | |
Cataloginterfaceno test imports itinterface Catalog
How a dialect reads its own catalog (0019-sql-convergence FR-001).
| Member | Type | What it is |
|---|
compares | readonly string[] | What the dialect compares, in words, so that what it does not is said. |
read | (query: Query, schema?: string | undefined) => Promise<readonly LiveTable[]> | |
interface Observed
What a database holds, as a dialect observes it (0055-sql-introspect FR-001).
| Member | Type | What it is |
|---|
dialect | string | |
schema? | string | |
tables | readonly ObservedTable[] | |
Imported by 4 tests of the run (4 passed, 0 failed): the library's results
ObservedColumninterfaceno test imports itinterface ObservedColumn
A column as a database holds it.
| Member | Type | What it is |
|---|
name | string | |
type | string | The type as the engine says it, in lower case (integer, numeric(10,2), timestamp with time zone, vector(3)). |
nullable | boolean | |
default? | string | |
ObservedTableinterfaceno test imports itinterface ObservedTable
A table as a database holds it.
| Member | Type | What it is |
|---|
name | string | |
columns | readonly ObservedColumn[] | |
primaryKey | readonly string[] | |
uniques | readonly { readonly columns: readonly string[]; }[] | |
foreignKeys | readonly { readonly columns: readonly string[]; readonly references: { readonly table: string; readonly columns: readonly string[]; }; }[] | |
indexes | readonly { readonly name: string; readonly columns: readonly string[]; readonly unique: boolean; }[] | |
Locksinterfaceno test imports itinterface 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).
| Member | Type | What 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) => boolean | Whether an error message is the engine giving up on a lock. |
LiveColumninterfaceno test imports itinterface LiveColumn
A column as a database's catalog says it is.
| Member | Type | What it is |
|---|
name | string | |
type | string | |
nullable | boolean | |
default? | string | The default as the catalog says it, where the dialect can list it (0019-sql-convergence FR-001). |
LiveTableinterfaceno test imports itinterface LiveTable
A table as a database's catalog says it is.
| Member | Type | What it is |
|---|
name | string | |
columns | readonly LiveColumn[] | |
primaryKey | readonly string[] | |
indexes | readonly 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 ittype Query = (sql: string) => Promise<readonly Record<string, unknown>[]>;
A way to run a query and read its rows.
Rebuildinterfaceno test imports itinterface 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.
| Member | Type | What it is |
|---|
prelude | readonly string[] | |
blockedByParents | boolean | Whether a table that other tables' foreign keys refer to cannot be dropped. |
Probesinterfaceno test imports itinterface 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).
| Member | Type | What 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 ittype Literal = string | number | boolean | null;
A literal a statement may hold.
quoteNameconstno test imports itconst quoteName: (name: string) => string
A name in double quotes, a quote in it doubled: how SQL's standard writes an identifier.
standardLiteralfunctionno test imports itfunction 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.