README
¶
dialect/postgres — the PostgreSQL dialect
Placeholders ($1, $2), identifier quoting (double quotes), and the capabilities this engine has.
It imports render and nothing else — which is exactly what a dialect written in another repository imports. That is the point of the layout: adding PostgreSQL and adding an engine nobody has written yet are the same act, and TestDialects_ImportOnlyRender reads this package's import list and fails on anything else.
It declares SupportsReturning, so InsertReturning and its siblings compile against it, and SupportsLikeEscape, so expr.Contains and its siblings emit an ESCAPE clause rather than leaving a user-typed % to match far more rows than intended. It also declares SupportsILike, so the fold predicates, expr.ContainsFold and its siblings, write ILIKE here and lower() on both sides on every other engine.
The constructs PostgreSQL spells differently are not here. They live in the engine construct package, because a caller naming the engine it builds for should not have to import several hundred constructs to do it.
Full documentation
docs/dialect/README.md covers all three and how to write a fourth; docs/dialects.md covers what a dialect decides and how a construct fails closed under the wrong one.
Documentation
¶
Overview ¶
Package postgres is the Postgres dialect: how Postgres writes a bound parameter and quotes an identifier, and which optional capabilities it has.
It is a package of its own so that the dialects this module ships are built exactly the way a dialect from another repository is built. It imports the render layer and nothing else, declares no construct, and knows nothing about statements. If adding an engine here needed anything the render layer does not export, that would be a hole in the extension point rather than a detail of this package, which is the property the split exists to keep testable.
The constructs that only Postgres has live in github.com/ubgo/sqlb/pg. This package is the smaller half of an engine, and a caller that only needs to say which engine it is building for imports this one alone.
Index ¶
- Constants
- type Dialect
- func (Dialect) Name() string
- func (Dialect) Placeholder(n int) string
- func (Dialect) QuoteIdent(ident string) string
- func (Dialect) QuoteLiteral(v any) (string, error)
- func (Dialect) SupportsCombinedAlter() bool
- func (Dialect) SupportsILike() bool
- func (Dialect) SupportsInsertAlias() bool
- func (Dialect) SupportsLikeEscape() bool
- func (Dialect) SupportsReturning() bool
- func (Dialect) SupportsUnrestrictedAddColumn() bool
- func (Dialect) TextParam(placeholder string) string
Constants ¶
const Name = render.DialectPostgres
Name is the engine name this dialect reports, and what an unsupported construct error prints. Engine packages guard on it.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Dialect ¶
type Dialect struct{}
Dialect renders $1, $2 placeholders and double-quoted identifiers.
func (Dialect) Name ¶
Name reports "postgres", which is what an engine package checks and what an unsupported-construct error names.
func (Dialect) Placeholder ¶
Placeholder renders $1, $2 and so on. Postgres numbers its placeholders, which is what lets one bound value be referenced twice.
func (Dialect) QuoteIdent ¶
QuoteIdent double-quotes an identifier, doubling any embedded quote.
func (Dialect) QuoteLiteral ¶
QuoteLiteral writes v as a Postgres literal that reads back as exactly v, whatever the server's standard_conforming_strings setting.
That setting is the whole difficulty. With it off, Postgres reads a backslash in a plain '...' string as an escape, so 'a\b' is four characters on one server and three on another, with only a WARNING to say so; measured on Postgres 17, a jsonpath's like_regex "^\\d$" matched with the setting on and did not with it off. So a string containing a backslash is written in the E'...' form with the backslash doubled, which reads the same under both. A string without one is written plainly, which also reads the same under both, and keeps every constant this package already renders byte-identical.
The value set is closed: strings, bools, every integer and float kind, []byte, time.Time, nil, a pointer to any of those, and named types whose underlying type is one of them. A NUL in a string, a NaN or an infinity, and every other type are ErrNotInlinable.
func (Dialect) SupportsCombinedAlter ¶
SupportsCombinedAlter reports true: Postgres applies several ALTER TABLE actions in one statement, under one lock.
func (Dialect) SupportsILike ¶
SupportsILike reports true: Postgres has ILIKE, and it is the engine whose LIKE is case-sensitive, so expr.ContainsFold and its siblings write ILIKE here and lower() on both sides everywhere else.
func (Dialect) SupportsInsertAlias ¶
SupportsInsertAlias reports true: INSERT INTO t AS alias is Postgres only, and the capability interface is how the builder finds that out without naming the engine.
func (Dialect) SupportsLikeEscape ¶
SupportsLikeEscape reports true: Postgres accepts an ESCAPE clause on LIKE.
Postgres treats a backslash as the default escape, so the clause is redundant there and costs nothing to write; naming it keeps one rendering for both engines.
func (Dialect) SupportsReturning ¶
SupportsReturning reports true: Postgres has RETURNING on every write.
func (Dialect) SupportsUnrestrictedAddColumn ¶
SupportsUnrestrictedAddColumn reports true: Postgres's ADD COLUMN takes any column CREATE TABLE would, rewriting the table when it must.
Source Files