v0.2.0

The Spanner provider after Ptah's built-in Spanner engine

Ptah no longer builds in a Spanner engine (stokaro/ptah#5657). This release is
the one that serves Spanner without it: the provider now states what the
built-in engine stated on its behalf, adopts provider contracts 25.29 and 25.31,
and carries the host Spanner tests the deletion removed. Its support level is
still best effort, measured against pgadapter-emulator v0.56.2; the managed
service and GoogleSQL are not covered.

Which Ptah it needs. The provider is built with provider-sdk v0.29.0
(contract 25.31). It still starts on a Ptah of provider contract 25.27 or a
later minor of 25, and serves an older minor without the additions it does not
list. It is built for a Ptah without a built-in Spanner engine: a Ptah release
that includes stokaro/ptah#5657. Schemas, the SQL TTL
clause, filtered indexes and the reserved seed ledger need contract 25.29
(stokaro/ptah#5641); enum columns need contract 25.31 (stokaro/ptah#5697). With
Ptah v0.22.1 the provider works as v0.1.0 did, and that release still sends
some commands to its own Spanner engine; use the next Ptah release.

What changed

• Offline capability facts (#17). The engine states the capability facts
  Ptah plans it with when no database is connected, the 149 facts of the
  deleted built-in engine's preset, and states them for its release line 0.
  ptah sql lint --dialect spanner reports CAP001 for CREATE INDEX CONCURRENTLY again, and ptah db capabilities reports Spanner's facts at
  best effort, where a Ptah without the built-in engine read PGAdapter's
  PostgreSQL 14.1 banner as certified PostgreSQL 14.
• Schemas (#19, contract 25.29). A declared schema, in SQL, Go or HCL, is
  created with CREATE SCHEMA IF NOT EXISTS, an empty one too, and the down
  file of a generated migration drops it. A read lists the schemas, so a held
  schema is not created again and one the declaration leaves out is kept. A
  rehearsal on a dev database removes the schemas it created there.
• The SQL TTL clause (#19, contract 25.29). A SQL schema document
  declares a row deletion policy with TTL INTERVAL '30 days' ON created_at
  after the column list. It plans, applies and converges, and the SQL that
  ptah db read writes now replays.
• Filtered indexes (#19, contract 25.29). An index with a WHERE clause of
  NOT NULL tests, the only predicate Spanner takes, is created and converges;
  a changed clause rebuilds the index, and ptah db read writes the clause.
  Ptah's built-in engine rebuilt such an index on every plan. Any other clause
  is refused by name.
• The seed ledger (#19, contract 25.29). A read reports schema_seeds as
  reserved, so ptah schema apply no longer plans to drop it after ptah seed.
• Enum columns (#22, contract 25.31). The engine states that an enum
  column is TEXT under a CHECK that lists its values, as the built-in
  engine built it, so Ptah builds that column instead of refusing an enum
  type.
• An index comment is refused (#21) before a statement is sent, as a table
  or column comment is: Spanner stores none, and a plan reported synced while
  the declaration held one.
• Documentation (#18). The pages drop the advice for a Ptah with a built-in
  Spanner engine and the search_path=public pin, and say that --disable MF104 reaches SP101.

Tests

The host Spanner tests stokaro/ptah#5657 deleted are ported or covered here
(#21, #19 and #22), so each runs against the emulator through the shipped host
binary. The live suite drops each test's database when the
test ends (#20), so a run stays under the emulator's 100 databases.

Install it with ptah providers install spanner.

The Spanner provider on provider contract 25.33

This release adopts provider contract 25.33 where Spanner needs it: Ptah reads
a SQL schema document as Spanner runs it, and a render says what Spanner does
not keep of a declared column type. It also makes ptah schema render --dialect spanner work without a database. Its support level is still best
effort, measured against pgadapter-emulator v0.56.2; the managed service and
GoogleSQL are not covered.

Which Ptah it needs. The provider is built with provider-sdk v0.31.0
(contract 25.33). It still starts on a Ptah of provider contract 25.27 or a
later minor of 25, and serves an older minor without the additions it does not
list. Both additions below need a Ptah of contract 25.33 (stokaro/ptah#5753);
with an older Ptah the provider works as v0.2.0 did.

What changed

• DROP VIEW IF EXISTS of a table in a SQL schema document (#25, contract
  25.33). The engine states that Spanner runs the statement and ignores it
  when the name is a table's (source.sql-statement-facts), so Ptah reads the
  document as the server runs it. An older Ptah refuses the document with the schema declares t as another kind of object, as it does for PostgreSQL,
  which refuses the statement.
• Render omissions (#25, contract 25.33). A column declared integer or
  int, or an array of either, keeps that spelling in the statement, and
  Spanner stores a bigint: the column takes values outside the 32-bit range.
  The render now reports this as an omission (render.omissions), with the
  CHECK that keeps the range of a scalar column. Ptah's Go API returns the
  omission with the statements, and a caller that must not lose a declaration
  refuses the rendering; the CLI prints no render omission.
• ptah schema render --dialect spanner (#25). An offline render names a
  table of the default schema without its schema, and the provider refused
  every table (a Spanner table operation names a table by its schema and name and nothing else). It now plans such a table in public, and the command
  writes the schema's statements.

Measured and not adopted

• View query equivalence (schema.view-query-equivalence). Spanner
  rewrites a view's query when it stores it, so a view with a literal in a
  condition, a join, IN, BETWEEN, LIKE, CASE, LIMIT or a table alias
  is replaced on every plan, as Ptah's built-in Spanner engine replaced it.
  The contract would let the provider decide, but Ptah then compares no view
  query by text, and the request carries neither the columns a SELECT *
  stands for nor a way to hand a pair back to Ptah's comparison: a provider
  answer would replan SELECT * and UNION views that converge today. A test
  pins which views converge.
• Table grants (planning.table-grants). The provider plans no table
  rebuild, carries no grants, and the emulator refuses CREATE ROLE and
  GRANT (Statement is not supported).

Install it with ptah providers install spanner.

Spanner's text read by Ptah's PostgreSQL-family lexer, and its lexical rules

The provider reads Spanner's text with pgsyntax from
github.com/stokaro/ptah/sqlsyntax v0.1.0, the lexer Ptah reads the
PostgreSQL family with (stokaro/ptah#5586, #24). A dollar-quoted string, an
escape string, a Unicode escape string and a nested block comment are read as
Spanner reads them, so a migration, a seed file or a ptah sql lint input that
holds one no longer fails: ptah sql lint on such a file stopped at exit 2
with a dollar-quoted string is not part of the provider's SQL. A string
constant is one token, and a refusal names the construct that does not close
and its line.

The engine also states its lexical rules under query.lexical (provider
contract 25.34, stokaro/ptah#5754): escape strings, continued and Unicode
strings and nested comments, each measured on pgadapter-emulator v0.56.2. A
Ptah of contract 25.34 reads Spanner's SQL schema files by them, so
DEFAULT E'it\'s' and a nested comment no longer break a file; an older Ptah
receives the query dialect without the rules. The provider builds with
provider-sdk v0.32.0 and still starts on a Ptah of contract 25.27.

Changelog

• c7b580c Adopt contract 25.29: schemas, the SQL TTL clause, the seed ledger, filtered indexes (#19)
• 8c8de17 Adopt contract 25.33: SQL statement facts and render omissions (#25)
• 7666e83 Assert the order of a cyclic down file that Spanner requires (#23)
• 36613b4 Drop each live test's database when the test ends (#20)
• 81dd2c9 Drop the docs for a Ptah that builds in Spanner (#18)
• e285032 Gate a release on tests of the binary it packages (#27)
• 44e33ea Port the host's remaining Spanner tests to the provider (#21)
• 16e9ad8 Publish only a commit whose CI run passed (#28)
• 127e82d Read Spanner's text with the shared PostgreSQL-family lexer (#24)
• ec351d1 Run the conformance suite against the emulator (#29)
• f89a7e8 State that an enum column is TEXT under a CHECK (#22)
• 50d93bc State the capability facts Ptah plans Spanner with offline (#17)