README
¶
Schema dialect fact probes
These probes record how MySQL, PostgreSQL and SQLite define and enforce
schema objects. docs/spec/dialects.md cites each probe ID in its schema
definition tables; a neutral dbspec feature is supported only when the
probes show one meaning on all three databases and a catalog source that
restores it.
Probe
A probe has a stable ID <database>.<topic>.<fact>, the fact it asserts
and a body of DDL, DML and catalog queries. A step that must succeed, a
statement that must fail with a given MySQL error number, PostgreSQL
SQLSTATE or SQLite message, and a query result that must equal a given
text are the only assertions. A probe that observes another value fails;
correcting a probe means recording the observed fact, not weakening it.
Each probe runs in its own disposable object:
| Database | Object | Cleanup |
|---|---|---|
| MySQL | database dfx_<pid>_<index> and, when needed, <database>_b; a login of the same name when the probe needs one |
DROP USER IF EXISTS, DROP DATABASE, then information_schema.SCHEMATA must not list them |
| PostgreSQL | schema dfx_<pid>_<index> and, when needed, <schema>_b |
DROP SCHEMA … CASCADE, then pg_namespace must not list them |
| SQLite | file dfx_<pid>_<index>.sqlite in the test's temporary directory and, when needed, dfx_<pid>_<index>_b.sqlite |
the files and their journal files are removed and must not exist |
Run
make dialect-facts-check TEST_ENV=<path of the environment file of make orm-test-servers>
The target first checks probe IDs without a database, then runs
TestDialectFacts (build tag physical) with ORM_TEST_MYSQL_DSN and
ORM_TEST_POSTGRES_DSN from TEST_ENV. SQLite needs no server: the Go
probe connection uses modernc.org/sqlite, and sqlite.env.library
reports the library version it links.
TestSQLiteFileNameWithQuery runs with the probes and records which SQLite
openers keep a DSN query in the file name: it opens
<dir>/bench.sqlite?_pragma=busy_timeout(5000)&timezone=%2B00:00 with Go
modernc.org/sqlite, PHP PDO, node:sqlite and the sqlite3 shell and
asserts the file names created in its own temporary directory.
Every probe is a case of packages/go/testcase: it prints RUN <probe> deadline=1m0s, a STEP line for its start and for each observed value,
and PASS <probe> elapsed=<elapsed> or FAIL <probe> elapsed=<elapsed>: <reason> while the run continues. Each probe has its own 30-second deadline
and its cleanup has another 30 seconds, which make the case deadline, so the
go test binary runs with -timeout 0. A server that cannot
be reached fails each of its probes with the connection error; the other
databases still run and the summary lines report passed and failed counts
per database.
Language
The probes are Go tests in shared tests/; the conformance checker
(tests/conformance/check) is cross-language infrastructure and is TypeScript.
The facts belong to the databases, not to a client, so the Go probes state
them once. The module already links the MySQL (go-sql-driver/mysql),
PostgreSQL (pgx) and SQLite (modernc.org/sqlite) drivers, and Go's
error types expose the MySQL error number and PostgreSQL SQLSTATE that the
assertions compare. The SQLite library differs per client; the versions are
listed in docs/spec/dialects.md.
Documentation
¶
Overview ¶
Package dialects holds the schema dialect fact probes of docs/spec/dialects.md.
Each probe states one observable fact about MySQL, PostgreSQL or SQLite, runs DDL, DML and catalog queries in its own disposable database, schema or file, and fails when the database does not behave as stated. The physical test in facts_physical_test.go runs every probe with its own deadline.
Index ¶
- func ErrorCode(err error) string
- func ScanCells(rows *sql.Rows, n int) ([]string, error)
- func Validate(probes []Probe) error
- type Env
- func (e *Env) Check(ok bool, format string, args ...any)
- func (e *Env) Column(query string, args ...any) string
- func (e *Env) Exec(statements ...string)
- func (e *Env) ExecArgs(statement string, args ...any)
- func (e *Env) Fails(statement, want string, args ...any)
- func (e *Env) FailsAny(statement string, args ...any)
- func (e *Env) Merge(other *Env)
- func (e *Env) Note(format string, args ...any)
- func (e *Env) Other() *Env
- func (e *Env) Value(query string, args ...any) string
- func (e *Env) Want(query, want string, args ...any)
- func (e *Env) WantRows(query, want string, args ...any)
- type Probe
- type ProbeFixture
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ErrorCode ¶
ErrorCode returns the MySQL error number, the PostgreSQL SQLSTATE or the SQLite message of an error.
Types ¶
type Env ¶
type Env struct {
Ctx context.Context
Conn *sql.Conn
DB string
Name string // database, schema or file of this probe
Session func() (*Env, error)
// Second creates the probe's second database, schema or file, named
// <name>_b, and opens a session on it; cleanup removes it with the first.
Second func() (*Env, error)
Admin *sql.DB // server connection used to create and drop probe objects
Extra map[string]string
Err error
Notes []string
}
Env is the connection of one probe. A failed step records the first error; later steps do nothing, so a probe body reads as its list of steps.
func (*Env) Fails ¶
Fails runs a statement that must fail with the given error: a MySQL error number, a PostgreSQL SQLSTATE, or a substring of the SQLite message.
type Probe ¶
type Probe struct {
ID string
DB string
Fact string
Fixture ProbeFixture
Run func(e *Env)
}
Probe is one asserted fact. ID is stable and is cited by docs/spec/dialects.md.
type ProbeFixture ¶
type ProbeFixture string
ProbeFixture names an explicitly selected test server fixture for a probe.
const ( ProbeFixtureDefault ProbeFixture = "" ProbeFixtureMySQLPrivilege ProbeFixture = "mysql-privilege" )
Source Files