RelationalDialect
Interface: RelationalDialect
Defined in: packages/sql/src/relational/dialect.ts:89
Engine syntax of the relational layout: typed columns from a plan, DDL, introspection and JSON operations on a named JSON column. Column arguments are physical (unquoted) names, quoted by the dialect; paths are validated segments.
Extends
Properties
binaryCollation
readonlybinaryCollation:string
Defined in: packages/sql/src/dialect.ts:52
Clause ordering text in code unit order: COLLATE "C" / COLLATE BINARY
Inherited from
inlineForeignKeys
readonlyinlineForeignKeys:boolean
Defined in: packages/sql/src/relational/dialect.ts:94
Foreign keys are declared inside CREATE TABLE and none can be added to an existing table (SQLite): the planner
then emits no addForeignKey step and reports a missing one as drift
Methods
asNumber()
asNumber(
json):string
Defined in: packages/sql/src/dialect.ts:101
Comparable number of a JSON value known to be a number
Parameters
json
string
a JSON value expression
Returns
string
the expression
Inherited from
asString()
asString(
json):string
Defined in: packages/sql/src/dialect.ts:107
Text of a JSON value known to be a string
Parameters
json
string
a JSON value expression
Returns
string
the expression
Inherited from
backfillTypes()
backfillTypes(
table):string
Defined in: packages/sql/src/dialect.ts:230
Statement stamping __type = parameter 1 on the untyped rows of the table
Parameters
table
string
the table name
Returns
string
the statement
Inherited from
bulkAssign()
bulkAssign(
table,assignments,args):string
Defined in: packages/sql/src/dialect.ts:224
data with the UPDATE SET assignments applied: missing parents created, existing arrays indexed; binds values
Parameters
table
string
the table name
assignments
object[]
the SET assignments
args
any[]
the statement parameters
Returns
string
the expression
Inherited from
castText()
castText(
expr):string
Defined in: packages/sql/src/relational/dialect.ts:144
Return the expression as text
Parameters
expr
string
a SQL expression
Returns
string
the expression as text
collectionItemCondition()
collectionItemCondition(
attr,index,field,valueParam):string
Defined in: packages/sql/src/dialect.ts:216
Condition: the field of the item at index of the top-level array equals the parameter
Parameters
attr
string
the array attribute
index
number | undefined
the index
field
string
the item field
valueParam
number
position of the bound value
Returns
string
the condition
Inherited from
SQLDialect.collectionItemCondition
columnJsonItemCondition()
columnJsonItemCondition(
column,index,field,valueParam):string
Defined in: packages/sql/src/relational/dialect.ts:228
Condition: the field of the item at index of the JSON array column equals the parameter
Parameters
column
string
the JSON column
index
number
the index
field
string
the item field
valueParam
number
position of the bound value
Returns
string
the condition
columnJsonMerge()
columnJsonMerge(
column,patch,args):string
Defined in: packages/sql/src/relational/dialect.ts:189
The JSON column shallow-merged with the patch (top-level keys replaced, a NULL column counts as {}); binds
what it needs
Parameters
column
string
the JSON column
patch
Record<string, unknown>
the patch
args
unknown[]
the statement parameters
Returns
string
the expression
columnJsonRemoveItem()
columnJsonRemoveItem(
column,index):string
Defined in: packages/sql/src/relational/dialect.ts:219
The JSON array column without the item at index
Parameters
column
string
the JSON column
index
number
the index
Returns
string
the expression
columnJsonRemoveKey()
columnJsonRemoveKey(
column,param):string
Defined in: packages/sql/src/relational/dialect.ts:196
The JSON column without the top-level key bound at param
Parameters
column
string
the JSON column
param
number
position of the bound key
Returns
string
the expression
columnJsonSetItem()
columnJsonSetItem(
column,itemParam,index):string
Defined in: packages/sql/src/relational/dialect.ts:212
The JSON array column with the item bound at itemParam appended (index undefined) or set at index
Parameters
column
string
the JSON column
itemParam
number
position of the bound JSON text
index
number | undefined
the index, undefined to append
Returns
string
the expression
columnJsonSetPath()
columnJsonSetPath(
column,path,valueParam):string
Defined in: packages/sql/src/relational/dialect.ts:204
The JSON column with the value bound at valueParam set at the path, missing parents created as objects
Parameters
column
string
the JSON column
path
string[]
validated segments, at least one
valueParam
number
position of the bound JSON text
Returns
string
the expression
columnJsonText()
columnJsonText(
column,path):string
Defined in: packages/sql/src/relational/dialect.ts:166
SQL text of the value at a path of a JSON column, NULL for a missing key and a JSON null
Parameters
column
string
the JSON column
path
string[]
the path inside the column, may be empty
Returns
string
the expression
columnJsonValue()
columnJsonValue(
column,path):string
Defined in: packages/sql/src/relational/dialect.ts:173
JSON value at a path of a JSON column
Parameters
column
string
the JSON column
path
string[]
the path inside the column, may be empty
Returns
string
the expression
columnJsonValueOrNull()
columnJsonValueOrNull(
column,path):string
Defined in: packages/sql/src/relational/dialect.ts:180
JSON value at a path of a JSON column, a JSON null folded into SQL NULL
Parameters
column
string
the JSON column
path
string[]
the path inside the column, may be empty
Returns
string
the expression
columnType()
columnType(
type):string
Defined in: packages/sql/src/relational/dialect.ts:106
Return the DDL type
Parameters
type
ColumnType
a plan column type
Returns
string
the DDL type
contains()
contains(
json,value):string
Defined in: packages/sql/src/dialect.ts:129
Condition: the JSON value is an array holding the value (a literal, inlined)
Parameters
json
string
a JSON value expression
value
string | number | boolean
the value
Returns
string
the condition
Inherited from
countStoredTypes()
countStoredTypes(
table):string
Defined in: packages/sql/src/dialect.ts:236
Statement returning type, n per stored type (parameter 1 = unreadable label, 2 = untyped label)
Parameters
table
string
the table name
Returns
string
the statement
Inherited from
createTable()
createTable(
table):string
Defined in: packages/sql/src/dialect.ts:142
CREATE TABLE IF NOT EXISTS statement of a document table
Parameters
table
string
the table name
Returns
string
the statement
Inherited from
decode()
decode(
value):any
Defined in: packages/sql/src/dialect.ts:247
Decode a JSON column of a result row: the object (pg parses jsonb), parsed text otherwise
Parameters
value
any
the column value
Returns
any
the decoded value
Inherited from
describeSchema()
describeSchema(
client,tables):Promise<LiveSchema>
Defined in: packages/sql/src/relational/dialect.ts:132
Describe the tables as the database holds them
Parameters
client
the client
tables
string[]
the table names to describe
Returns
Promise<LiveSchema>
the live schema, without the tables that do not exist
distinctFrom()
distinctFrom(
left,right):string
Defined in: packages/sql/src/dialect.ts:122
Null-safe !=: IS DISTINCT FROM / IS NOT
Parameters
left
string
left operand
right
string
right operand
Returns
string
the condition
Inherited from
hasStoredType()
hasStoredType():
string
Defined in: packages/sql/src/dialect.ts:153
Condition: the row has a __type key
Returns
string
the condition
Inherited from
increment()
increment(
entries,updateDate,args):string
Defined in: packages/sql/src/dialect.ts:189
data with the counters incremented and _lastUpdate set to the ISO date; binds the increments
Parameters
entries
object[]
the counters
updateDate
string
ISO date
args
any[]
the statement parameters
Returns
string
the expression
Inherited from
isForeignKeyViolation()
isForeignKeyViolation(
err): {constraint?:string; } |undefined
Defined in: packages/sql/src/relational/dialect.ts:234
Check whether foreign key violation
Parameters
err
unknown
an error thrown by the client
Returns
{ constraint?: string; } | undefined
the violated constraint when the error is a foreign key violation, undefined otherwise
isObjectRow()
isObjectRow():
string
Defined in: packages/sql/src/dialect.ts:241
Condition: the data column is a JSON object
Returns
string
the condition
Inherited from
isType()
isType(
json,type):string
Defined in: packages/sql/src/dialect.ts:95
Condition: the JSON value has the type
Parameters
json
string
a JSON value expression
type
the type
Returns
string
the condition
Inherited from
isUniqueViolation()
isUniqueViolation(
err):boolean
Defined in: packages/sql/src/dialect.ts:148
Whether the error is a primary key / unique violation on insert
Parameters
err
unknown
the error
Returns
boolean
true for a unique violation
Inherited from
jsonParam()
jsonParam(
i):string
Defined in: packages/sql/src/dialect.ts:64
The i-th parameter, a JSON text, as a JSON value: $1::jsonb / json(?1)
Parameters
i
number
the parameter position
Returns
string
the expression
Inherited from
jsonText()
jsonText(
path):string
Defined in: packages/sql/src/dialect.ts:70
SQL text of the value at a path, NULL for a missing field and a JSON null
Parameters
path
string[]
validated segments
Returns
string
the expression
Inherited from
jsonValue()
jsonValue(
path):string
Defined in: packages/sql/src/dialect.ts:76
JSON value at a path
Parameters
path
string[]
validated segments
Returns
string
the expression
Inherited from
jsonValueOrNull()
jsonValueOrNull(
path):string
Defined in: packages/sql/src/dialect.ts:82
JSON value at a path, a JSON null folded into SQL NULL (aggregations)
Parameters
path
string[]
validated segments
Returns
string
the expression
Inherited from
keptType()
keptType(
mapParam):string
Defined in: packages/sql/src/dialect.ts:159
The stored type of the row, rewritten through the legacy type map bound at mapParam (JSON text)
Parameters
mapParam
number
position of the bound map parameter
Returns
string
the expression
Inherited from
keyText()
keyText(
key):string
Defined in: packages/sql/src/dialect.ts:88
SQL text of a top-level key: data->>'k'
Parameters
key
string
the key
Returns
string
the expression
Inherited from
like()
like(
text,pattern):string
Defined in: packages/sql/src/dialect.ts:136
Case-sensitive LIKE condition on the text (% / _, \% / \_ literal)
Parameters
text
string
the text expression
pattern
string
the LIKE pattern
Returns
string
the condition
Inherited from
placeholder()
placeholder(
i):string
Defined in: packages/sql/src/dialect.ts:58
Positional placeholder of the i-th (1-based) parameter: $1 / ?1
Parameters
i
number
the parameter position
Returns
string
the placeholder
Inherited from
quote()
quote(
identifier):string
Defined in: packages/sql/src/relational/dialect.ts:100
Return the quoted identifier
Parameters
identifier
string
a table, column, index or constraint name
Returns
string
the quoted identifier
removeCollectionItem()
removeCollectionItem(
attr,index,updateDate):string
Defined in: packages/sql/src/dialect.ts:207
data with the item at index removed from the top-level array, _lastUpdate set
Parameters
attr
string
the array attribute
index
number
the index
updateDate
string
ISO date
Returns
string
the expression
Inherited from
SQLDialect.removeCollectionItem
removeKey()
removeKey(
attribute,args):string
Defined in: packages/sql/src/dialect.ts:181
data without the top-level attribute; binds what it needs
Parameters
attribute
string
the attribute
args
any[]
the statement parameters
Returns
string
the expression
Inherited from
renderContractStep()?
optionalrenderContractStep(step):string[]
Defined in: packages/sql/src/relational/dialect.ts:125
Render contract step
Parameters
step
a contract step
Returns
string[]
the statements applying it, empty when the engine cannot (reported, never failed)
renderOnlineStep()?
optionalrenderOnlineStep(step):OnlineStatements
Defined in: packages/sql/src/relational/dialect.ts:119
Statements of an online step (a table with rows and traffic): the engine may keep the heavy work out of the
DDL transaction. Without it, renderStep runs inside the transaction
Parameters
step
a schema change flagged online
Returns
the statements, split
renderStep()
renderStep(
step):string[]
Defined in: packages/sql/src/relational/dialect.ts:112
Render step
Parameters
step
a schema change
Returns
string[]
the idempotent statements applying it
schemaLock()
schemaLock(
name):string|undefined
Defined in: packages/sql/src/relational/dialect.ts:138
Statement serializing DDL across processes, run first inside the DDL transaction
Parameters
name
string
the lock name (the store name)
Returns
string | undefined
the statement, undefined when the engine needs none
setCollectionItem()
setCollectionItem(
attr,itemParam,index,updateDate):string
Defined in: packages/sql/src/dialect.ts:199
data with the item bound at itemParam appended to (index undefined) or set at index of the top-level array,
_lastUpdate set
Parameters
attr
string
the array attribute
itemParam
number
position of the bound item (JSON text)
index
number | undefined
the index, undefined to append
updateDate
string
ISO date
Returns
string
the expression
Inherited from
shallowMerge()
shallowMerge(
json,patch,args):string
Defined in: packages/sql/src/dialect.ts:174
The JSON value shallow-merged with the patch (top-level keys replaced); binds what it needs
Parameters
json
string
a JSON value expression
patch
Record<string, any>
the patch
args
any[]
the statement parameters
Returns
string
the expression
Inherited from
timeText()
timeText(
expr,type):string
Defined in: packages/sql/src/relational/dialect.ts:152
ISO 8601 text of a time column expression: YYYY-MM-DD for a date, the UTC ...Z form for a timestamptz
(what the models store and compare), for LIKE and the loose text comparisons
Parameters
expr
string
a SQL expression
type
ColumnType
the column type (date or timestamptz)
Returns
string
the text
toJson()
toJson(
expr,type):string
Defined in: packages/sql/src/relational/dialect.ts:159
JSON value of a scalar column expression, for aggregations: a time column renders as its ISO 8601 UTC text
Parameters
expr
string
a SQL expression
type
ColumnType
the column type
Returns
string
the JSON value
typedAttribute()
typedAttribute(
text,json,type):string
Defined in: packages/sql/src/dialect.ts:115
Attribute of a typed comparison: the number or boolean, NULL when the field has another type
Parameters
text
string
the text expression of the attribute
json
string
the JSON value expression of the attribute
type
"number" | "boolean"
the type of the compared value
Returns
string
the expression
Inherited from
uniqueViolation()
uniqueViolation(
err):UniqueViolation|undefined
Defined in: packages/sql/src/relational/dialect.ts:241
Return what a unique violation hit: the table, the constraint or index name when the engine reports it, and
Parameters
err
unknown
an error thrown by the client
Returns
UniqueViolation | undefined
what a unique violation hit: the table, the constraint or index name when the engine reports it, and whether it is the primary key; undefined for any other error
withStoredType()
withStoredType(
json,type):string
Defined in: packages/sql/src/dialect.ts:166
The JSON value with __type set to the type expression
Parameters
json
string
a JSON value expression
type
string
the type expression
Returns
string
the expression