catalog

package
v0.0.0-...-6e34275 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 19, 2026 License: Apache-2.0 Imports: 39 Imported by: 0

Documentation

Overview

Copyright 2024-2025 ApeCloud, Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

Constants

View Source 
const (
	// ManagedCommentPrefix is the prefix for comments that are managed by the catalog.
	ManagedCommentPrefix = "base64:"
	// SequenceNamePrefix is the prefix for sequence names that are managed by the catalog.
	SequenceNamePrefix = "__sys_table_seq_"
)
View Source 
const (
	TableStorageLocal  TableStorageKind = "local"
	TableStorageObject TableStorageKind = "object"

	// TableStorageDuckLake is an explicit spelling for callers that think in
	// terms of the underlying implementation. It has the same durable value as
	// TableStorageObject.
	TableStorageDuckLake = TableStorageObject
	// TableStorageObjectStorage is retained as a descriptive alias for API
	// callers; object is the only persisted value.
	TableStorageObjectStorage = TableStorageObject
)
View Source 
const (
	// TableStorageOptionName is the protocol-neutral PostgreSQL storage
	// parameter. MySQL clients use ENGINE=DUCKLAKE because Vitess accepts only
	// its built-in table-option grammar.
	TableStorageOptionName  = "myduck_storage"
	TableStorageObjectValue = "object"
	TableStorageLocalValue  = "local"
	TableStorageMySQLEngine = "ducklake"
)
View Source 
const DuckDBDecimalTypeMaxPrecision = 38
View Source 
const DuckDBExtensionABI = DuckDBExtensionVersion

DuckDBExtensionABI is kept as a separate field in the manifest so an artifact cannot be accidentally paired with a different DuckDB binding.

View Source 
const DuckDBExtensionVersion = "1.5.5"

DuckDBExtensionVersion is the ABI/version used by the Go DuckDB binding in this repository. Extension artifacts are never downloaded at runtime.

View Source 
const DuckLakeCatalogName = "__myduck_ducklake"

DuckLakeCatalogName is the one service-owned catalog attached to each eligible physical connection. Logical MyDuck databases and schemas are mapped into this catalog by the provider; clients never select it directly.

View Source 
const DuckLakeSecretName = "__myduckserver_ducklake_service"

DuckLakeSecretName is an internal, service-owned secret name. User SQL that mentions any SECRET object is rejected before it reaches DuckDB.

View Source 
const RedactedSensitiveSQL = "[redacted service-managed SQL]"

RedactedSensitiveSQL is the stable audit value used when a service-managed statement must not be retained in logs.

View Source 
const SchemaSummaryQuery = `` /* 630-byte string literal not displayed */

SchemaSummaryQuery is the stable, read-only schema discovery query for clients and agent integrations. table_schema is the client-visible database (MySQL) or schema (Postgres) name.

Keep the projection and ordering explicit: callers can consume the result without depending on information_schema's wider, version-specific schema.

Variables

View Source 
var (
	ErrExternalSessionClosed              = errors.New("external session is closed")
	ErrExternalSessionStale               = errors.New("external session belongs to a stale pool generation")
	ErrExternalSessionGenerationPoisoned  = errors.New("external session driver panic poisoned the storage generation")
	ErrExternalSessionTransactionMismatch = errors.New(
		"external session transaction does not match the active transaction",
	)
)
View Source 
var (
	ErrDuckDB     = errors.NewKind("duckdb: %v")
	ErrTranspiler = errors.NewKind("transpiler: %v")
)
View Source 
var (
	SchemaNameSYS           string = "__sys__"
	MacroNameMyListContains string = "my_list_contains"

	MacroNameMySplitListStr string = "my_split_list_str"

	MacroNameMyCRC32 string = "mysql_crc32"
)
View Source 
var (
	ErrInvalidTableStorage       = errors.New("invalid table storage selection")
	ErrTableStorageConflict      = errors.New("conflicting table storage selections")
	ErrTableStorageDuplicate     = errors.New("duplicate table storage selection")
	ErrTableStorageCredentialSQL = errors.New("table storage credentials must come from service configuration")
	ErrTableStoragePathSQL       = errors.New("table storage paths must come from service configuration")
)
View Source 
var ErrSensitiveSQL = errors.New("statement uses a service-managed SQL feature")

ErrSensitiveSQL is returned for user statements that would bypass the service-owned DuckLake/S3 credential boundary. It intentionally contains no statement text or credential-shaped data.

View Source 
var InitialDataTables = struct {
	PGNamespace [][]any
	PGRange     [][]any
}{
	PGNamespace: [][]any{
		{"99", "pg_toast", "10", ""},
		{"11", "pg_catalog", "10", "{postgres=UC/postgres,=U/postgres}"},
		{"2200", "public", "6171", "{pg_database_owner,=UC/pg_database_owner,=U/pg_database_owner}"},
		{"13219", "information_schema", "10", "{postgres=UC/postgres,=U/postgres}"},
		{"16395", "test_schema", "10", ""},
	},
	PGRange: [][]any{
		{"3904", "23", "4451", "0", "1978", "int4range_canonical", "int4range_subdiff"},
		{"3906", "1700", "4532", "0", "3125", "-", "numrange_subdiff"},
		{"3908", "1114", "4533", "0", "3128", "-", "tsrange_subdiff"},
		{"3910", "1184", "4534", "0", "3127", "-", "tstzrange_subdiff"},
		{"3912", "1082", "4535", "0", "3122", "daterange_canonical", "daterange_subdiff"},
		{"3926", "20", "4536", "0", "3124", "int8range_canonical", "int8range_subdiff"},
	},
}
View Source 
var InternalMacros = []InternalMacro{
	{
		Schema:       "information_schema",
		Name:         "_pg_expandarray",
		IsTableMacro: true,
		Definitions: []MacroDefinition{
			{
				Params: []string{"a"},

				DDL: `SELECT STRUCT_PACK(
    x := unnest(a),
    n := unnest(generate_series(1, CAST(len(a) AS BIGINT)))
) AS item`,
			},
		},
	},
	{
		Schema:       "pg_catalog",
		Name:         "pg_get_indexdef",
		IsTableMacro: false,
		Definitions: []MacroDefinition{
			{
				Params: []string{"index_oid"},

				DDL: `''`,
			},
			{
				Params: []string{"index_oid", "column_no", "pretty_bool"},

				DDL: `''`,
			},
		},
	},
	{
		Schema:       "pg_catalog",
		Name:         "pg_get_expr",
		IsTableMacro: false,
		Definitions: []MacroDefinition{
			{
				Params: []string{"pg_node_tree", "relation_oid"},

				DDL: `pg_catalog.pg_get_expr(pg_node_tree, relation_oid)`,
			},
			{
				Params: []string{"pg_node_tree", "relation_oid", "pretty_bool"},

				DDL: `pg_catalog.pg_get_expr(pg_node_tree, relation_oid)`,
			},
		},
	},
	{
		Schema:       SchemaNameSYS,
		Name:         MacroNameMyListContains,
		IsTableMacro: false,
		Definitions: []MacroDefinition{
			{
				Params: []string{"l", "v"},
				DDL: `CASE
    WHEN typeof(l) = 'VARCHAR' THEN
        list_contains(regexp_split_to_array(l::VARCHAR, '[{},\s]+'), v::VARCHAR)
    ELSE
        list_contains(CAST(l AS VARCHAR[]), v::VARCHAR)
    END`,
			},
		},
	},
	{
		Schema:       SchemaNameSYS,
		Name:         MacroNameMySplitListStr,
		IsTableMacro: false,
		Definitions: []MacroDefinition{
			{
				Params: []string{"l"},
				DDL:    `regexp_split_to_array(l::VARCHAR, '[{},\s]+')`,
			},
		},
	},
	{
		Schema:       SchemaNameSYS,
		Name:         MacroNameMyCRC32,
		IsTableMacro: false,
		Definitions: []MacroDefinition{
			{
				Params: []string{"s"},
				DDL: `xor(
    list_reduce(
      list_prepend(
        4294967295,
        list_transform(
          range(1, length(CAST(s AS TEXT)) + 1),
          i -> ascii(substring(CAST(s AS TEXT), i, 1))
        )
      ),
      (crc, b) -> xor(
        crc // 256,
        [0,1996959894,3993919788,2567524794,124634137,1886057615,3915621685,2657392035,249268274,2044508324,3772115230,2547177864,162941995,2125561021,3887607047,2428444049,498536548,1789927666,4089016648,2227061214,450548861,1843258603,4107580753,2211677639,325883990,1684777152,4251122042,2321926636,335633487,1661365465,4195302755,2366115317,997073096,1281953886,3579855332,2724688242,1006888145,1258607687,3524101629,2768942443,901097722,1119000684,3686517206,2898065728,853044451,1172266101,3705015759,2882616665,651767980,1373503546,3369554304,3218104598,565507253,1454621731,3485111705,3099436303,671266974,1594198024,3322730930,2970347812,795835527,1483230225,3244367275,3060149565,1994146192,31158534,2563907772,4023717930,1907459465,112637215,2680153253,3904427059,2013776290,251722036,2517215374,3775830040,2137656763,141376813,2439277719,3865271297,1802195444,476864866,2238001368,4066508878,1812370925,453092731,2181625025,4111451223,1706088902,314042704,2344532202,4240017532,1658658271,366619977,2362670323,4224994405,1303535960,984961486,2747007092,3569037538,1256170817,1037604311,2765210733,3554079995,1131014506,879679996,2909243462,3663771856,1141124467,855842277,2852801631,3708648649,1342533948,654459306,3188396048,3373015174,1466479909,544179635,3110523913,3462522015,1591671054,702138776,2966460450,3352799412,1504918807,783551873,3082640443,3233442989,3988292384,2596254646,62317068,1957810842,3939845945,2647816111,81470997,1943803523,3814918930,2489596804,225274430,2053790376,3826175755,2466906013,167816743,2097651377,4027552580,2265490386,503444072,1762050814,4150417245,2154129355,426522225,1852507879,4275313526,2312317920,282753626,1742555852,4189708143,2394877945,397917763,1622183637,3604390888,2714866558,953729732,1340076626,3518719985,2797360999,1068828381,1219638859,3624741850,2936675148,906185462,1090812512,3747672003,2825379669,829329135,1181335161,3412177804,3160834842,628085408,1382605366,3423369109,3138078467,570562233,1426400815,3317316542,2998733608,733239954,1555261956,3268935591,3050360625,752459403,1541320221,2607071920,3965973030,1969922972,40735498,2617837225,3943577151,1913087877,83908371,2512341634,3803740692,2075208622,213261112,2463272603,3855990285,2094854071,198958881,2262029012,4057260610,1759359992,534414190,2176718541,4139329115,1873836001,414664567,2282248934,4279200368,1711684554,285281116,2405801727,4167216745,1634467795,376229701,2685067896,3608007406,1308918612,956543938,2808555105,3495958263,1231636301,1047427035,2932959818,3654703836,1088359270,936918000,2847714899,3736837829,1202900863,817233897,3183342108,3401237130,1404277552,615818150,3134207493,3453421203,1423857449,601450431,3009837614,3294710456,1567103746,711928724,3020668471,3272380065,1510334235,755167117][1 + (xor(crc, b) % 256)]
      )
    ),
    4294967295
  )`,
			},
		},
	},
}
View Source 
var InternalSchemas = struct {
	SYS   InternalSchema
	MySQL InternalSchema
}{
	SYS: InternalSchema{
		Schema: "__sys__",
	},
	MySQL: InternalSchema{
		Schema: "mysql",
	},
}
View Source 
var InternalTables = struct {
	PersistentVariable InternalTable
	BinlogPosition     InternalTable
	PgSubscription     InternalTable
	GlobalStatus       InternalTable
	// TODO(sean): This is a temporary work around for clients that query the 'pg_catalog.pg_stat_replication'.
	//             Once we add 'pg_catalog' and support views for PG, replace this by a view.
	//             https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW
	PGStatReplication InternalTable
	PGRange           InternalTable
	PGType            InternalTable
	PGProc            InternalTable
	PGClass           InternalTable
	PGNamespace       InternalTable
	PGMatViews        InternalTable
}{
	PersistentVariable: InternalTable{
		Schema:       "__sys__",
		Name:         "persistent_variable",
		KeyColumns:   []string{"name"},
		ValueColumns: []string{"value", "vtype"},
		DDL:          "name TEXT PRIMARY KEY, value TEXT, vtype TEXT",
	},
	BinlogPosition: InternalTable{
		Schema:       "__sys__",
		Name:         "binlog_position",
		KeyColumns:   []string{"channel"},
		ValueColumns: []string{"position"},
		DDL:          "channel TEXT PRIMARY KEY, position TEXT",
	},
	PgSubscription: InternalTable{
		Schema:       "__sys__",
		Name:         "pg_subscription",
		KeyColumns:   []string{"subname"},
		ValueColumns: []string{"subconninfo", "subpublication", "subskiplsn", "subenabled"},
		DDL:          "subname TEXT PRIMARY KEY, subconninfo TEXT, subpublication TEXT, subskiplsn TEXT, subenabled BOOLEAN",
	},
	GlobalStatus: InternalTable{
		Schema:       "performance_schema",
		Name:         "global_status",
		KeyColumns:   []string{"VARIABLE_NAME"},
		ValueColumns: []string{"VARIABLE_VALUE"},
		DDL:          "VARIABLE_NAME TEXT PRIMARY KEY, VARIABLE_VALUE TEXT",
		InitialData: [][]any{
			{"Innodb_redo_log_enabled", "OFF"},
		},
	},

	PGStatReplication: InternalTable{

		Schema: "__sys__",
		Name:   "pg_stat_replication",
		KeyColumns: []string{
			"pid",
		},
		ValueColumns: []string{
			"usesysid",
			"usename",
			"application_name",
			"client_addr",
			"client_hostname",
			"client_port",
			"backend_start",
			"backend_xmin",
			"state",
			"sent_lsn",
			"write_lsn",
			"flush_lsn",
			"replay_lsn",
			"write_lag",
			"flush_lag",
			"replay_lag",
			"sync_priority",
			"sync_state",
			"reply_time",
		},
		DDL: "pid INTEGER PRIMARY KEY, usesysid TEXT, usename TEXT, application_name TEXT, client_addr TEXT, client_hostname TEXT, client_port INTEGER, backend_start TIMESTAMP, backend_xmin INTEGER, state TEXT, sent_lsn TEXT, write_lsn TEXT, flush_lsn TEXT, replay_lsn TEXT, write_lag INTERVAL, flush_lag INTERVAL, replay_lag INTERVAL, sync_priority INTEGER, sync_state TEXT, reply_time TIMESTAMP",
	},
	PGRange: InternalTable{
		Schema:       "__sys__",
		Name:         "pg_range",
		KeyColumns:   []string{"rngtypid"},
		ValueColumns: []string{"rngsubtype", "rngmultitypid", "rngcollation", "rngsubopc", "rngcanonical", "rngsubdiff"},
		DDL:          "rngtypid BIGINT PRIMARY KEY, rngsubtype BIGINT, rngmultitypid BIGINT, rngcollation BIGINT, rngsubopc BIGINT, rngcanonical VARCHAR, rngsubdiff VARCHAR",
		InitialData:  InitialDataTables.PGRange,
	},

	PGType: InternalTable{
		Schema: "__sys__",
		Name:   "pg_type",
		KeyColumns: []string{
			"oid",
		},
		ValueColumns: []string{
			"typname", "typnamespace", "typowner", "typlen", "typbyval",
			"typtype", "typcategory", "typispreferred", "typisdefined", "typdelim",
			"typrelid", "typsubscript", "typelem", "typarray", "typinput",
			"typoutput", "typreceive", "typsend", "typmodin", "typmodout",
			"typanalyze", "typalign", "typstorage", "typnotnull", "typbasetype",
			"typtypmod", "typndims", "typcollation", "typdefaultbin", "typdefault",
			"typacl",
		},
		DDL: "oid BIGINT NOT NULL PRIMARY KEY, " +
			"typname VARCHAR , " +
			"typnamespace BIGINT , " +
			"typowner BIGINT , " +
			"typlen SMALLINT , " +
			"typbyval BOOLEAN , " +
			"typtype CHAR , " +
			"typcategory CHAR , " +
			"typispreferred BOOLEAN , " +
			"typisdefined BOOLEAN , " +
			"typdelim CHAR , " +
			"typrelid BIGINT , " +
			"typsubscript BIGINT , " +
			"typelem BIGINT , " +
			"typarray BIGINT , " +
			"typinput BIGINT , " +
			"typoutput BIGINT , " +
			"typreceive BIGINT , " +
			"typsend BIGINT , " +
			"typmodin BIGINT , " +
			"typmodout BIGINT , " +
			"typanalyze BIGINT , " +
			"typalign CHAR , " +
			"typstorage CHAR , " +
			"typnotnull BOOLEAN , " +
			"typbasetype BIGINT , " +
			"typtypmod INTEGER , " +
			"typndims INTEGER , " +
			"typcollation BIGINT , " +
			"typdefaultbin VARCHAR, " +
			"typdefault TEXT, " +
			"typacl TEXT",
	},

	PGProc: InternalTable{
		Schema: "__sys__",
		Name:   "pg_proc",
		KeyColumns: []string{
			"oid",
		},
		ValueColumns: []string{
			"proname",
			"pronamespace",
			"proowner",
			"prolang",
			"procost",
			"prorows",
			"provariadic",
			"prosupport",
			"prokind",
			"prosecdef",
			"proleakproof",
			"proisstrict",
			"proretset",
			"provolatile",
			"proparallel",
			"pronargs",
			"pronargdefaults",
			"prorettype",
			"proargtypes",
			"proallargtypes",
			"proargmodes",
			"proargnames",
			"proargdefaults",
			"protrftypes",
			"prosrc",
			"probin",
			"prosqlbody",
			"proconfig",
			"proacl",
		},
		DDL: "oid BIGINT NOT NULL PRIMARY KEY," +
			"proname VARCHAR ," +
			"pronamespace BIGINT ," +
			"proowner BIGINT ," +
			"prolang BIGINT ," +
			"procost FLOAT ," +
			"prorows FLOAT ," +
			"provariadic BIGINT ," +
			"prosupport BIGINT ," +
			"prokind CHAR ," +
			"prosecdef BOOLEAN ," +
			"proleakproof BOOLEAN ," +
			"proisstrict BOOLEAN ," +
			"proretset BOOLEAN ," +
			"provolatile CHAR ," +
			"proparallel CHAR ," +
			"pronargs SMALLINT ," +
			"pronargdefaults SMALLINT ," +
			"prorettype BIGINT ," +
			"proargtypes VARCHAR ," +
			"proallargtypes VARCHAR," +
			"proargmodes VARCHAR," +
			"proargnames VARCHAR," +
			"proargdefaults TEXT," +
			"protrftypes VARCHAR," +
			"prosrc TEXT ," +
			"probin TEXT," +
			"prosqlbody TEXT," +
			"proconfig VARCHAR," +
			"proacl VARCHAR",
	},

	PGClass: InternalTable{
		Schema: "__sys__",
		Name:   "pg_class_catalog",
		KeyColumns: []string{
			"oid",
		},
		ValueColumns: []string{
			"relname",
			"relnamespace",
			"reltype",
			"reloftype",
			"relowner",
			"relam",
			"relfilenode",
			"reltablespace",
			"relpages",
			"reltuples",
			"relallvisible",
			"reltoastrelid",
			"relhasindex",
			"relisshared",
			"relpersistence",
			"relkind",
			"relnatts",
			"relchecks",
			"relhasrules",
			"relhastriggers",
			"relhassubclass",
			"relrowsecurity",
			"relforcerowsecurity",
			"relispopulated",
			"relreplident",
			"relispartition",
			"relrewrite",
			"relfrozenxid",
			"relminmxid",
			"relacl",
			"reloptions",
			"relpartbound",
		},
		DDL: "oid BIGINT NOT NULL PRIMARY KEY," +
			"relname VARCHAR ," +
			"relnamespace BIGINT ," +
			"reltype BIGINT ," +
			"reloftype BIGINT ," +
			"relowner BIGINT ," +
			"relam BIGINT ," +
			"relfilenode BIGINT ," +
			"reltablespace BIGINT ," +
			"relpages INTEGER ," +
			"reltuples FLOAT ," +
			"relallvisible INTEGER ," +
			"reltoastrelid BIGINT ," +
			"relhasindex BOOLEAN ," +
			"relisshared BOOLEAN ," +
			"relpersistence CHAR ," +
			"relkind CHAR ," +
			"relnatts SMALLINT ," +
			"relchecks SMALLINT ," +
			"relhasrules BOOLEAN ," +
			"relhastriggers BOOLEAN ," +
			"relhassubclass BOOLEAN ," +
			"relrowsecurity BOOLEAN ," +
			"relforcerowsecurity BOOLEAN ," +
			"relispopulated BOOLEAN ," +
			"relreplident CHAR ," +
			"relispartition BOOLEAN ," +
			"relrewrite BIGINT ," +
			"relfrozenxid BIGINT ," +
			"relminmxid BIGINT ," +
			"relacl TEXT," +
			"reloptions TEXT," +
			"relpartbound TEXT",
	},

	PGNamespace: InternalTable{
		Schema: "__sys__",
		Name:   "pg_namespace_catalog",
		KeyColumns: []string{
			"oid",
		},
		ValueColumns: []string{
			"nspname",
			"nspowner",
			"nspacl",
		},
		DDL: "oid BIGINT NOT NULL PRIMARY KEY," +
			"nspname VARCHAR NOT NULL," +
			"nspowner BIGINT NOT NULL," +
			"nspacl TEXT",
		InitialData: InitialDataTables.PGNamespace,
	},

	PGMatViews: InternalTable{
		Schema: "__sys__",
		Name:   "pg_matviews",
		KeyColumns: []string{
			"schemaname",
			"matviewname",
		},
		ValueColumns: []string{
			"matviewowner",
			"tablespace",
			"hasindexes",
			"ispopulated",
			"definition",
		},
		DDL: "schemaname VARCHAR NOT NULL, " +
			"matviewname VARCHAR NOT NULL, " +
			"matviewowner VARCHAR, " +
			"tablespace VARCHAR, " +
			"hasindexes BOOLEAN, " +
			"ispopulated BOOLEAN, " +
			"definition TEXT",
	},
}
View Source 
var InternalViews = []InternalView{
	{
		Schema: "__sys__",
		Name:   "pg_stat_user_tables",
		DDL: `SELECT
    t.table_schema || '.' || t.table_name AS relid, -- Create a unique ID for the table
    t.table_schema AS schemaname,                  -- Schema name
    t.table_name AS relname,                       -- Table name
    0 AS seq_scan,                                 -- Default to 0 (DuckDB doesn't track this)
    NULL AS last_seq_scan,                         -- Placeholder (DuckDB doesn't track this)
    0 AS seq_tup_read,                             -- Default to 0
    0 AS idx_scan,                                 -- Default to 0
    NULL AS last_idx_scan,                         -- Placeholder
    0 AS idx_tup_fetch,                            -- Default to 0
    0 AS n_tup_ins,                                -- Default to 0 (inserted tuples not tracked)
    0 AS n_tup_upd,                                -- Default to 0 (updated tuples not tracked)
    0 AS n_tup_del,                                -- Default to 0 (deleted tuples not tracked)
    0 AS n_tup_hot_upd,                            -- Default to 0 (HOT updates not tracked)
    0 AS n_tup_newpage_upd,                        -- Default to 0 (new page updates not tracked)
    0 AS n_live_tup,                               -- Default to 0 (live tuples not tracked)
    0 AS n_dead_tup,                               -- Default to 0 (dead tuples not tracked)
    0 AS n_mod_since_analyze,                      -- Default to 0
    0 AS n_ins_since_vacuum,                       -- Default to 0
    NULL AS last_vacuum,                           -- Placeholder
    NULL AS last_autovacuum,                       -- Placeholder
    NULL AS last_analyze,                          -- Placeholder
    NULL AS last_autoanalyze,                      -- Placeholder
    0 AS vacuum_count,                             -- Default to 0
    0 AS autovacuum_count,                         -- Default to 0
    0 AS analyze_count,                            -- Default to 0
    0 AS autoanalyze_count                         -- Default to 0
FROM
    information_schema.tables t
WHERE
    t.table_type = 'BASE TABLE'; -- Include only base tables (not views)`,
	},
	{
		Schema: "__sys__",
		Name:   "pg_index",
		DDL: `SELECT
    (300000 + (hash(k.table_schema || '.' || k.table_name || '.' || c.constraint_name)::UBIGINT % 800000000))::BIGINT AS indexrelid,
    t.table_oid AS indrelid,                          -- OID of the table
    COUNT(k.column_name) AS indnatts,                 -- Number of columns included in the index
    COUNT(k.column_name) AS indnkeyatts,              -- Number of key columns in the index (same as indnatts here)
    CASE
        WHEN c.constraint_type = 'UNIQUE' THEN TRUE
        ELSE FALSE
    END AS indisunique,                               -- Indicates if the index is unique
    CASE
        WHEN c.constraint_type = 'PRIMARY KEY' THEN TRUE
        ELSE FALSE
    END AS indisprimary,                              -- Indicates if the index is a primary key
    ARRAY_AGG(k.ordinal_position ORDER BY k.ordinal_position) AS indkey,  -- Array of column positions
    ARRAY[]::BIGINT[] AS indcollation,                -- DuckDB does not support collation, set to default
    ARRAY[]::BIGINT[] AS indclass,                    -- DuckDB does not support index class, set to default
    ARRAY[]::INTEGER[] AS indoption,                  -- DuckDB does not support index options, set to default
    NULL AS indexprs,                                 -- DuckDB does not support expression indexes, set to NULL
    NULL AS indpred                                   -- DuckDB does not support partial indexes, set to NULL
FROM
    information_schema.key_column_usage k
JOIN
    information_schema.table_constraints c
    ON k.constraint_name = c.constraint_name
    AND k.table_name = c.table_name
    AND k.table_schema = c.table_schema
JOIN
    duckdb_tables() t
    ON k.table_name = t.table_name
    AND k.table_schema = t.schema_name
WHERE
    c.constraint_type IN ('PRIMARY KEY', 'UNIQUE')    -- Only select primary key and unique constraints
GROUP BY
    t.table_oid, c.constraint_type, c.constraint_name, k.table_schema, k.table_name
ORDER BY
    t.table_oid;`,
	},
	{
		Schema: "__sys__",
		Name:   "pg_namespace",

		DDL: `SELECT oid, nspname, nspowner, nspacl FROM __sys__.pg_namespace_catalog
UNION ALL
SELECT
    (200000 + (hash(s.schema_name)::UBIGINT % 800000000))::BIGINT AS oid,
    s.schema_name AS nspname,
    10::BIGINT AS nspowner,
    CAST(NULL AS VARCHAR) AS nspacl
FROM (
    SELECT DISTINCT schema_name
    FROM information_schema.schemata
    WHERE catalog_name NOT IN ('system', 'temp', 'memory')
      AND schema_name NOT IN ('__sys__', 'mysql', 'performance_schema', 'main')
      AND schema_name NOT IN (SELECT nspname FROM __sys__.pg_namespace_catalog)
) s`,
	},
	{
		Schema: "__sys__",
		Name:   "pg_class",

		DDL: `SELECT * FROM __sys__.pg_class_catalog
UNION ALL
SELECT
    live.oid,
    live.relname,
    live.relnamespace,
    live.reltype,
    live.reloftype,
    live.relowner,
    live.relam,
    live.relfilenode,
    live.reltablespace,
    live.relpages,
    live.reltuples,
    live.relallvisible,
    live.reltoastrelid,
    live.relhasindex,
    live.relisshared,
    live.relpersistence,
    live.relkind,
    live.relnatts,
    live.relchecks,
    live.relhasrules,
    live.relhastriggers,
    live.relhassubclass,
    live.relrowsecurity,
    live.relforcerowsecurity,
    live.relispopulated,
    live.relreplident,
    live.relispartition,
    live.relrewrite,
    live.relfrozenxid,
    live.relminmxid,
    live.relacl,
    live.reloptions,
    live.relpartbound
FROM (
    SELECT
        t.table_oid::BIGINT AS oid,
        t.table_name::VARCHAR AS relname,
        n.oid AS relnamespace,
        0::BIGINT AS reltype,
        0::BIGINT AS reloftype,
        10::BIGINT AS relowner,
        0::BIGINT AS relam,
        0::BIGINT AS relfilenode,
        0::BIGINT AS reltablespace,
        0::INTEGER AS relpages,
        0::FLOAT AS reltuples,
        0::INTEGER AS relallvisible,
        0::BIGINT AS reltoastrelid,
        (t.has_primary_key OR t.index_count > 0) AS relhasindex,
        false AS relisshared,
        'p' AS relpersistence,
        'r' AS relkind,
        t.column_count::SMALLINT AS relnatts,
        t.check_constraint_count::SMALLINT AS relchecks,
        false AS relhasrules,
        false AS relhastriggers,
        false AS relhassubclass,
        false AS relrowsecurity,
        false AS relforcerowsecurity,
        true AS relispopulated,
        'n' AS relreplident,
        false AS relispartition,
        0::BIGINT AS relrewrite,
        0::BIGINT AS relfrozenxid,
        0::BIGINT AS relminmxid,
        CAST(NULL AS VARCHAR) AS relacl,
        CAST(NULL AS VARCHAR) AS reloptions,
        CAST(NULL AS VARCHAR) AS relpartbound,
        ROW_NUMBER() OVER (
            PARTITION BY t.schema_name, t.table_name
            ORDER BY CASE t.database_name WHEN 'myduck' THEN 0 ELSE 1 END, t.database_name
        ) AS rn
    FROM duckdb_tables() t
    INNER JOIN __sys__.pg_namespace n ON n.nspname = t.schema_name
    WHERE NOT t.internal
      AND NOT t.temporary
      AND t.database_name NOT IN ('system', 'temp', 'memory')
      AND t.schema_name NOT IN ('__sys__', 'mysql', 'performance_schema', 'main', 'pg_catalog', 'information_schema', 'pg_toast')
    UNION ALL
    SELECT
        v.view_oid::BIGINT AS oid,
        v.view_name::VARCHAR AS relname,
        n.oid AS relnamespace,
        0::BIGINT AS reltype,
        0::BIGINT AS reloftype,
        10::BIGINT AS relowner,
        0::BIGINT AS relam,
        0::BIGINT AS relfilenode,
        0::BIGINT AS reltablespace,
        0::INTEGER AS relpages,
        0::FLOAT AS reltuples,
        0::INTEGER AS relallvisible,
        0::BIGINT AS reltoastrelid,
        false AS relhasindex,
        false AS relisshared,
        'p' AS relpersistence,
        'v' AS relkind,
        v.column_count::SMALLINT AS relnatts,
        0::SMALLINT AS relchecks,
        false AS relhasrules,
        false AS relhastriggers,
        false AS relhassubclass,
        false AS relrowsecurity,
        false AS relforcerowsecurity,
        true AS relispopulated,
        'n' AS relreplident,
        false AS relispartition,
        0::BIGINT AS relrewrite,
        0::BIGINT AS relfrozenxid,
        0::BIGINT AS relminmxid,
        CAST(NULL AS VARCHAR) AS relacl,
        CAST(NULL AS VARCHAR) AS reloptions,
        CAST(NULL AS VARCHAR) AS relpartbound,
        ROW_NUMBER() OVER (
            PARTITION BY v.schema_name, v.view_name
            ORDER BY CASE v.database_name WHEN 'myduck' THEN 0 ELSE 1 END, v.database_name
        ) AS rn
    FROM duckdb_views() v
    INNER JOIN __sys__.pg_namespace n ON n.nspname = v.schema_name
    WHERE NOT v.internal
      AND NOT v.temporary
      AND v.database_name NOT IN ('system', 'temp', 'memory')
      AND v.schema_name NOT IN ('__sys__', 'mysql', 'performance_schema', 'main', 'pg_catalog', 'information_schema', 'pg_toast')
    UNION ALL
    SELECT
        (300000 + (hash(c.table_schema || '.' || c.table_name || '.' || c.constraint_name)::UBIGINT % 800000000))::BIGINT AS oid,
        c.constraint_name::VARCHAR AS relname,
        n.oid AS relnamespace,
        0::BIGINT AS reltype,
        0::BIGINT AS reloftype,
        10::BIGINT AS relowner,
        0::BIGINT AS relam,
        0::BIGINT AS relfilenode,
        0::BIGINT AS reltablespace,
        0::INTEGER AS relpages,
        0::FLOAT AS reltuples,
        0::INTEGER AS relallvisible,
        0::BIGINT AS reltoastrelid,
        false AS relhasindex,
        false AS relisshared,
        'p' AS relpersistence,
        'i' AS relkind,
        1::SMALLINT AS relnatts,
        0::SMALLINT AS relchecks,
        false AS relhasrules,
        false AS relhastriggers,
        false AS relhassubclass,
        false AS relrowsecurity,
        false AS relforcerowsecurity,
        true AS relispopulated,
        'n' AS relreplident,
        false AS relispartition,
        0::BIGINT AS relrewrite,
        0::BIGINT AS relfrozenxid,
        0::BIGINT AS relminmxid,
        CAST(NULL AS VARCHAR) AS relacl,
        CAST(NULL AS VARCHAR) AS reloptions,
        CAST(NULL AS VARCHAR) AS relpartbound,
        ROW_NUMBER() OVER (
            PARTITION BY c.table_schema, c.table_name, c.constraint_name
            ORDER BY c.constraint_catalog
        ) AS rn
    FROM information_schema.table_constraints c
    INNER JOIN __sys__.pg_namespace n ON n.nspname = c.table_schema
    WHERE c.constraint_type IN ('PRIMARY KEY', 'UNIQUE')
      AND c.table_schema NOT IN ('__sys__', 'mysql', 'performance_schema', 'main', 'pg_catalog', 'information_schema', 'pg_toast')
) live
WHERE live.rn = 1`,
	},
	{
		Schema: "__sys__",
		Name:   "pg_attribute",

		DDL: `SELECT
    col.attrelid,
    col.attname,
    col.atttypid,
    col.attstattarget,
    col.attlen,
    col.attnum,
    col.attndims,
    col.attcacheoff,
    col.atttypmod,
    col.attbyval,
    col.attalign,
    col.attstorage,
    col.attcompression,
    col.attnotnull,
    col.atthasdef,
    col.atthasmissing,
    col.attidentity,
    col.attgenerated,
    col.attisdropped,
    col.attislocal,
    col.attinhcount,
    col.attcollation,
    col.attacl,
    col.attoptions,
    col.attfdwoptions
FROM (
    SELECT
        t.table_oid::BIGINT AS attrelid,
        c.column_name::VARCHAR AS attname,
        25::BIGINT AS atttypid,
        -1::INTEGER AS attstattarget,
        4::SMALLINT AS attlen,
        c.ordinal_position::SMALLINT AS attnum,
        0::INTEGER AS attndims,
        -1::INTEGER AS attcacheoff,
        -1::INTEGER AS atttypmod,
        true AS attbyval,
        'i' AS attalign,
        'p' AS attstorage,
        '' AS attcompression,
        (c.is_nullable = 'NO') AS attnotnull,
        false AS atthasdef,
        false AS atthasmissing,
        '' AS attidentity,
        '' AS attgenerated,
        false AS attisdropped,
        true AS attislocal,
        0::INTEGER AS attinhcount,
        0::BIGINT AS attcollation,
        CAST(NULL AS VARCHAR) AS attacl,
        CAST(NULL AS VARCHAR) AS attoptions,
        CAST(NULL AS VARCHAR) AS attfdwoptions,
        ROW_NUMBER() OVER (
            PARTITION BY t.schema_name, t.table_name, c.column_name
            ORDER BY CASE t.database_name WHEN 'myduck' THEN 0 ELSE 1 END, t.database_name
        ) AS rn
    FROM information_schema.columns c
    JOIN duckdb_tables() t
      ON c.table_schema = t.schema_name
     AND c.table_name = t.table_name
    WHERE NOT t.internal
      AND NOT t.temporary
      AND t.database_name NOT IN ('system', 'temp', 'memory')
      AND t.schema_name NOT IN ('__sys__', 'mysql', 'performance_schema', 'main', 'pg_catalog', 'information_schema', 'pg_toast')
) col
WHERE col.rn = 1`,
	},
}
View Source 
var SystemViews = map[string]struct{}{
	"duckdb_columns":       {},
	"duckdb_constraints":   {},
	"duckdb_databases":     {},
	"duckdb_indexes":       {},
	"duckdb_schemas":       {},
	"duckdb_tables":        {},
	"duckdb_types":         {},
	"duckdb_views":         {},
	"pragma_database_list": {},
	"sqlite_master":        {},
	"sqlite_schema":        {},
	"sqlite_temp_master":   {},
	"sqlite_temp_schema":   {},
}

Functions

func ClearTableStorageSelection 

func ClearTableStorageSelection(ctx *sql.Context)

ClearTableStorageSelection consumes the request-scoped selector installed by SetTableStorageSelection. This prevents a reusable sql.Context (for example a session transaction context) from carrying one CREATE TABLE's choice into a later statement.

func ConnectIdentifiersANSI 

func ConnectIdentifiersANSI(identifiers ...string) string

func DecodeCreateindex 

func DecodeCreateindex(createIndexSQL string) ([]string, error)

func DecodeIndexName 

func DecodeIndexName(encodedName string) (string, string)

func EncodeIndexName 

func EncodeIndexName(table, index string) string

EncodeIndexName uses a simple encoding scheme (table$$index) for better visibility which is useful for debugging.

func FullColumnName 

func FullColumnName(catalog, schema, table, column string) string

func FullIndexName 

func FullIndexName(catalog, schema, index string) string

func FullSchemaName 

func FullSchemaName(catalog, schema string) string

func FullTableName 

func FullTableName(catalog, schema, table string) string

func IsDuckDBCatalogError 

func IsDuckDBCatalogError(err error) bool

func IsDuckDBIndexAlreadyExistsError 

func IsDuckDBIndexAlreadyExistsError(err error) bool

ERROR 1105 (HY000): duckdb: Catalog Error: Index with name "x_idx" already exists!

func IsDuckDBNotNullConstraintViolationError 

func IsDuckDBNotNullConstraintViolationError(err error) (bool, string)

Constraint Error: NOT NULL constraint failed: <column>

func IsDuckDBSetSchemaNotFoundError 

func IsDuckDBSetSchemaNotFoundError(err error) bool

ERROR 1105 (HY000): unknown error: Catalog Error: SET schema: No catalog + schema named "mysql.db0" found.

func IsDuckDBTableAlreadyExistsError 

func IsDuckDBTableAlreadyExistsError(err error) bool

func IsDuckDBTableNotFoundError 

func IsDuckDBTableNotFoundError(err error) bool

func IsDuckDBUniqueConstraintViolationError 

func IsDuckDBUniqueConstraintViolationError(err error) bool

ERROR 1105 (HY000): duckdb: Constraint Error: Data contains duplicates on indexed column(s)

func IsDuckDBViewNotFoundError 

func IsDuckDBViewNotFoundError(err error) bool

func IsSensitiveSQL 

func IsSensitiveSQL(query string) bool

IsSensitiveSQL reports whether query contains a DuckLake/S3 control or credential-inspection operation. The scanner is deliberately lexical: the MySQL and PostgreSQL parsers accept different SQL dialects, while comments, quoted identifiers, dollar-quoted strings, and multi-statements must all be handled consistently at the protocol boundary.

func IsSystemView 

func IsSystemView(viewName string) bool

func QuoteIdentifierANSI 

func QuoteIdentifierANSI(identifier string) string

func RedactSensitiveSQL 

func RedactSensitiveSQL(query string) string

RedactSensitiveSQL is a defensive logging helper for callers that receive a statement before they can reject it. Non-sensitive text is returned as-is; sensitive text is replaced wholesale so no literal can reach a log field.

func RejectSensitiveSQL 

func RejectSensitiveSQL(query string) error

RejectSensitiveSQL rejects service-control and credential-inspection SQL before protocol parsing, tracing, auditing, or prepared-statement handling. Internal service code does not call this function and can use parameterized APIs instead.

func RollbackCleanupOwner 

func RollbackCleanupOwner(ctx context.Context) *stdsql.Conn

RollbackCleanupOwner returns the physical connection reserved by a rollback finalizer, if the context was marked with WithRollbackCleanupOwner.

func SetTableStorageSelection 

func SetTableStorageSelection(ctx *sql.Context, selection TableStorageSelection) error

SetTableStorageSelection attaches a validated selector to a GMS SQL context. It mutates only the context wrapper passed by the caller; the underlying request/session remains otherwise unchanged.

func VerifyDuckLakeExtensions 

func VerifyDuckLakeExtensions(extensionDir string, manifest []ExtensionArtifact) error

VerifyDuckLakeExtensions verifies every fixed artifact before it is handed to DuckDB. It rejects symlinks and non-regular files so a mutable service path cannot silently substitute a different extension.

func VerifyDuckLakeExtensionsForTarget 

func VerifyDuckLakeExtensionsForTarget(extensionDir string, manifest []ExtensionArtifact, goos, goarch string) error

VerifyDuckLakeExtensionsForTarget additionally binds every artifact to the requested Linux architecture. It is used by the runtime before LOAD so an arm64 artifact cannot be substituted into an amd64 image (or vice versa).

func WithDuckLakeCleanupLease 

func WithDuckLakeCleanupLease(ctx context.Context) context.Context

WithDuckLakeCleanupLease marks a context used by a rollback finalizer that already acquired the provider cleanup barrier before entering the pool lifecycle lock. CleanupDuckLakeOrphansOnConn must not acquire that barrier a second time in this scope.

func WithRollbackCleanupOwner 

func WithRollbackCleanupOwner(ctx context.Context, conn *stdsql.Conn) context.Context

WithRollbackCleanupOwner marks a maintenance context whose connection is reserved by the session rollback finalizer. Provider setup and cleanup can then avoid re-reading the session transaction map while that map's lock is held by the finalizer.

func WithTableStorageSelection 

func WithTableStorageSelection(ctx *sql.Context, selection TableStorageSelection) (*sql.Context, error)

WithTableStorageSelection returns a copy of ctx carrying a validated table selector. The copy form is useful in hooks that must not mutate a context owned by another execution path.

Types

type AnnotatedDuckType 

type AnnotatedDuckType struct {
	// contains filtered or unexported fields
}

func DuckdbDataType 

func DuckdbDataType(mysqlType sql.Type) (AnnotatedDuckType, error)

func (AnnotatedDuckType) MySQL 

func (t AnnotatedDuckType) MySQL() MySQLType

func (AnnotatedDuckType) Name 

func (t AnnotatedDuckType) Name() string

type ColumnInfo 

type ColumnInfo struct {
	ColumnName    string
	ColumnIndex   int
	DataType      sql.Type
	IsNullable    bool
	ColumnDefault stdsql.NullString
	Comment       stdsql.NullString
}

type Comment 

type Comment[T any] struct {
	Text string `json:"text,omitempty"`
	Meta T      `json:"meta,omitempty"` // extra information, e.g. the original MySQL column type, etc.
}

func DecodeComment 

func DecodeComment[T any](encodedOrRawText string) *Comment[T]

func NewComment 

func NewComment[T any](text string) *Comment[T]

func NewCommentWithMeta 

func NewCommentWithMeta[T any](text string, meta T) *Comment[T]

func (*Comment[T]) Encode 

func (c *Comment[T]) Encode() string

type ConnectionPool 

type ConnectionPool struct {
	*stdsql.DB
	// contains filtered or unexported fields
}

func NewConnectionPool 

func NewConnectionPool(connector *duckdb.Connector, db *stdsql.DB, defaultCatalog string) *ConnectionPool

func (*ConnectionPool) Close 

func (p *ConnectionPool) Close() error

func (*ConnectionPool) CloseConn 

func (p *ConnectionPool) CloseConn(id uint32) error

func (*ConnectionPool) CloseConnIf 

func (p *ConnectionPool) CloseConnIf(id uint32, conn *stdsql.Conn) error

func (*ConnectionPool) CloseConnIfBinding 

func (p *ConnectionPool) CloseConnIfBinding(id uint32, conn *stdsql.Conn, expectedTx *stdsql.Tx) error

CloseConnIfBinding closes a connection only while both the generic session mapping and the transaction binding still match the caller's snapshot. The session lock keeps a replacement transaction from being admitted between the identity check and closeConnLocked, which may itself roll back an active tx.

func (*ConnectionPool) CloseTxn 

func (p *ConnectionPool) CloseTxn(id uint32)

func (*ConnectionPool) CloseTxnAndGet 

func (p *ConnectionPool) CloseTxnAndGet(id uint32) *stdsql.Tx

CloseTxnAndGet removes the transaction currently bound to id and returns the exact mapping that was removed. Capturing, identity removal, and completion notification happen under one release/session lifecycle section; callers do not need to perform a racy lookup followed by an unconditional CloseTxn. A nil result means that no valid transaction mapping was removed.

func (*ConnectionPool) CloseTxnIf 

func (p *ConnectionPool) CloseTxnIf(id uint32, tx *stdsql.Tx)

CloseTxnIf removes a transaction mapping only if it still refers to tx. Older deferred cleanup must not delete a newer transaction for the same logical session ID.

func (*ConnectionPool) CommitTxn 

func (p *ConnectionPool) CommitTxn(id uint32, expected *stdsql.Tx) error

CommitTxn commits the transaction only while it is still the transaction bound to id. The driver operation, identity check, and bad-connection eviction are serialized under lifecycleMu, so a delayed commit cannot remove or close a replacement binding.

func (*ConnectionPool) CommitTxnWithOutcome 

func (p *ConnectionPool) CommitTxnWithOutcome(id uint32, expected *stdsql.Tx) (matched bool, err error)

CommitTxnWithOutcome is the identity-aware commit surface used by the production Session adapter. matched is false when the expected transaction is no longer the current binding (for example, it was already rolled back or replaced). The legacy CommitTxn wrapper intentionally preserves its historic no-op behavior for that stale case, while callers that need to report the distinction can turn matched=false into a binding error without guessing.

func (*ConnectionPool) Connector 

func (p *ConnectionPool) Connector() *duckdb.Connector

func (*ConnectionPool) CurrentCatalog 

func (p *ConnectionPool) CurrentCatalog(id uint32) string

CurrentCatalog retrieves the current catalog of the connection. Before the first connection, it returns the owning provider's catalog so GMS can resolve fully qualified names. Closed or broken connections still return empty.

func (*ConnectionPool) CurrentSchema 

func (p *ConnectionPool) CurrentSchema(id uint32) string

CurrentSchema retrieves the current schema of the connection. Returns an empty string if the connection is not established or the schema cannot be retrieved.

func (*ConnectionPool) GetConn 

func (p *ConnectionPool) GetConn(ctx context.Context, id uint32) (*stdsql.Conn, error)

func (*ConnectionPool) GetConnForSchema 

func (p *ConnectionPool) GetConnForSchema(ctx context.Context, id uint32, schemaName string) (*stdsql.Conn, error)

func (*ConnectionPool) GetConnForSchemaWithBinding 

func (p *ConnectionPool) GetConnForSchemaWithBinding(ctx context.Context, id uint32, schemaName string) (*stdsql.Conn, *stdsql.Tx, error)

GetConnForSchemaWithBinding is the schema-selecting counterpart to GetConnWithBinding. The connection, schema selection, and transaction identity are observed under one lifecycle/session lock.

func (*ConnectionPool) GetConnWithBinding 

func (p *ConnectionPool) GetConnWithBinding(ctx context.Context, id uint32) (*stdsql.Conn, *stdsql.Tx, error)

GetConnWithBinding acquires a catalog connection and returns the transaction binding observed in the same lifecycle/session critical section. Callers that need to remember an identity for a later close must use this method instead of doing a second GetTxnBinding lookup after GetConn returns.

func (*ConnectionPool) GetExecutionSnapshot 

func (p *ConnectionPool) GetExecutionSnapshot(ctx context.Context, id uint32, schemaName string, catalogOnly bool) (*stdsql.Conn, *stdsql.Tx, error)

GetExecutionSnapshot acquires the connection and observes the transaction binding while holding the lifecycle lock. It retains the historical snapshot-only contract by releasing the lifecycle lease before returning; callers that execute or consume results after this point should use GetExecutionSnapshotLease through the adapter helper instead.

func (*ConnectionPool) GetExecutionSnapshotLease 

func (p *ConnectionPool) GetExecutionSnapshotLease(
	ctx context.Context,
	id uint32,
	schemaName string,
	catalogOnly bool,
) (*stdsql.Conn, *stdsql.Tx, func(), error)

GetExecutionSnapshotLease acquires the connection and observes the transaction binding while holding the lifecycle lock. The returned release function keeps that lifecycle reader held until the caller has finished all driver work and consumed any result iterator. This prevents Close, Reset, and provider Restart from retiring the selected physical generation in the gap between snapshot acquisition and execution.

The release function is idempotent. On an acquisition error the lease is released before returning and the returned callback is a no-op, so callers do not need a special error cleanup branch.

func (*ConnectionPool) GetTxn 

func (p *ConnectionPool) GetTxn(ctx context.Context, id uint32, schemaName string, options *stdsql.TxOptions) (*stdsql.Tx, error)

func (*ConnectionPool) GetTxnBinding 

func (p *ConnectionPool) GetTxnBinding(id uint32) (*stdsql.Conn, *stdsql.Tx)

GetTxnBinding returns the physical connection and transaction currently associated with a logical session. The connection is returned even when no transaction is active, which lets statement callers use one atomic snapshot instead of acquiring a connection and then racing a transaction opener.

func (*ConnectionPool) GetTxnBindingForRelease 

func (p *ConnectionPool) GetTxnBindingForRelease(id uint32) (*stdsql.Conn, *stdsql.Tx)

GetTxnBindingForRelease captures a transaction binding from a release-side lifecycle section. It is intended for close/finalizer paths that may run after shutdown has been announced; ordinary execution must continue using GetTxnBinding or GetExecutionSnapshot so new work remains excluded during teardown.

func (*ConnectionPool) GetTxnBindingForReleaseStatus 

func (p *ConnectionPool) GetTxnBindingForReleaseStatus(id uint32) (*stdsql.Conn, *stdsql.Tx, bool, error)

GetTxnBindingForReleaseStatus is the error-preserving form used by lifecycle callback bridges. A malformed active transaction mapping must remain distinguishable from an absent mapping; otherwise a callback could release a lease while the physical transaction is still live but uninspectable.

func (*ConnectionPool) GetTxnWithBinding 

func (p *ConnectionPool) GetTxnWithBinding(ctx context.Context, id uint32, schemaName string, options *stdsql.TxOptions) (*stdsql.Conn, *stdsql.Tx, error)

GetTxnWithBinding opens (or observes) a transaction and returns its exact physical owner from the same lifecycle/session critical section. Session adapters use this to remember a close identity without a second, racy pool lookup.

func (*ConnectionPool) OpenExternalSession 

func (p *ConnectionPool) OpenExternalSession(ctx context.Context) (*ExternalSession, error)

OpenExternalSession checks out one exact physical connection and registers an opaque identity with the pool generation that owns it.

func (*ConnectionPool) RegisterTransactionCompletion 

func (p *ConnectionPool) RegisterTransactionCompletion(tx *stdsql.Tx, callback func(bool)) bool

RegisterTransactionCompletion attaches a callback to a raw transaction's terminal lifecycle. It is intentionally small and optional; backend.Session uses it to bridge provider/pool teardown into its protocol callback registry.

A recent terminal outcome is delivered inline before this method returns. Ordinary finalizers also deliver callbacks synchronously, but only after releasing the pool lifecycle and session locks, so callbacks may re-enter pool release/read APIs. Callbacks must remain terminal notification/resource release hooks and must not re-enter provider DDL, cleanup, Close, or Restart; a provider generation transition may still own those outer locks.

func (*ConnectionPool) Reset 

func (p *ConnectionPool) Reset(connector *duckdb.Connector, db *stdsql.DB) error

func (*ConnectionPool) RollbackTxn 

func (p *ConnectionPool) RollbackTxn(id uint32, expected *stdsql.Tx) (*stdsql.Conn, bool, error)

RollbackTxn rolls back the transaction only while it is still the binding owned by id. It returns the physical owner and whether the driver proved the transaction inactive. Unexpected rollback errors invalidate and evict that owner; a stale callback returns no owner so it cannot clean a replacement.

func (*ConnectionPool) RollbackTxnWithCleanup 

func (p *ConnectionPool) RollbackTxnWithCleanup(
	id uint32,
	expected *stdsql.Tx,
	cleanup func(*stdsql.Conn) error,
) (bool, error)

RollbackTxnWithCleanup performs rollback, unbinds the transaction, and runs cleanup before releasing the session lock. A replacement transaction for the same logical session therefore cannot slip between rollback and maintenance. The callback is invoked only for the still-current transaction and only when the driver proves that it is inactive.

func (*ConnectionPool) SetConnectionAdmissionGuard 

func (p *ConnectionPool) SetConnectionAdmissionGuard(guard func(context.Context) error)

SetConnectionAdmissionGuard installs the provider-owned guard used by ordinary connection, execution-snapshot, and metadata entry points. The guard runs once before lifecycle admission and once after the pool/session locks are held. The second check closes the gap where shutdown completed and the lifecycle gate reopened while the provider transition was still active.

func (*ConnectionPool) SetConnectionInitializer 

func (p *ConnectionPool) SetConnectionInitializer(initializer func(context.Context, *stdsql.Conn) error)

SetConnectionInitializer installs a hook that runs whenever a logical session acquires a connection outside an active session transaction. The hook receives the acquisition context, including its query-origin classification. Running it for both new and reused logical connections prevents a connection that was previously used by one origin from carrying session settings into another origin; GetTxn runs it before BeginTx and then keeps transaction-scoped state stable until that transaction closes.

func (*ConnectionPool) SetTransactionAdmissionGuard 

func (p *ConnectionPool) SetTransactionAdmissionGuard(guard func() error)

SetTransactionAdmissionGuard installs an optional provider-owned guard for new physical transaction admission. Existing transactions still use the ordinary fast path so they can be finalized or repaired after a generation failure; only attempts to open a new transaction are rejected.

func (*ConnectionPool) SetTransactionLifecycleHooks 

func (p *ConnectionPool) SetTransactionLifecycleHooks(
	admission func() func(*stdsql.Tx),
	finished func(*stdsql.Tx),
)

SetTransactionLifecycleHooks installs optional hooks for providers that need to coordinate transaction admission with shared catalog maintenance. The admission hook is called only when a new transaction is about to be opened; it returns a completion function that must be called with the newly opened transaction, or nil when opening failed. The finished hook is called whenever a transaction mapping is removed by any pool lifecycle path.

Hooks are deliberately optional so standalone test pools and callers that do not own a provider retain the original pool behavior.

func (*ConnectionPool) SetTransactionLifecycleHooksWithError 

func (p *ConnectionPool) SetTransactionLifecycleHooksWithError(
	admission func() (func(*stdsql.Tx), error),
	finished func(*stdsql.Tx),
)

SetTransactionLifecycleHooksWithError installs the provider-aware transaction admission hook. A non-nil error prevents the pool from calling BeginTx; the returned completion callback is invoked only for an admission that actually reserved a transaction slot. The legacy setter above remains available for test pools and downstream embedders.

func (*ConnectionPool) TryGetTxn 

func (p *ConnectionPool) TryGetTxn(id uint32) *stdsql.Tx

func (*ConnectionPool) TryGetTxnForRelease 

func (p *ConnectionPool) TryGetTxnForRelease(id uint32) *stdsql.Tx

TryGetTxnForRelease is the release-side transaction snapshot. Unlike the ordinary lookup, it remains admissible while pool shutdown is waiting for readers to drain, so a close/finalizer path can still discover the binding it needs to release. The returned pointer is only a snapshot; callers must use an identity-safe finalizer for the subsequent driver operation.

type Database 

type Database struct {
	// contains filtered or unexported fields
}

func NewDatabase 

func NewDatabase(name string, catalogName string) *Database

func NewDatabaseWithProvider 

func NewDatabaseWithProvider(name string, catalogName string, provider *DatabaseProvider) *Database

NewDatabaseWithProvider constructs a logical database bound to the owning provider. Protocol adapters that bypass DatabaseProvider.Database (notably PostgreSQL's direct parser path) must use this form so object-table materialization and physical-name resolution retain the DuckLake runtime.

func (*Database) AllViews 

func (d *Database) AllViews(ctx *sql.Context) ([]sql.ViewDefinition, error)

AllViews implements sql.ViewDatabase.

func (*Database) CopyTableData 

func (d *Database) CopyTableData(ctx *sql.Context, sourceTable string, destinationTable string) (uint64, error)

CopyTableData implements sql.TableCopierDatabase interface.

func (*Database) CreateTable 

func (d *Database) CreateTable(ctx *sql.Context, name string, schema sql.PrimaryKeySchema, collation sql.CollationID, comment string) error

CreateTable implements sql.TableCreator.

func (*Database) CreateTableWithStorage 

func (d *Database) CreateTableWithStorage(ctx *sql.Context, name string, schema sql.PrimaryKeySchema, collation sql.CollationID, comment string, storage TableStorageSelection) error

CreateTableWithStorage is the explicit catalog boundary for protocol adapters that already normalized a table selector. It is intentionally limited to selection propagation and metadata; object-table physical routing is owned by the follow-up storage implementation.

func (*Database) CreateTemporaryTable 

func (d *Database) CreateTemporaryTable(ctx *sql.Context, name string, schema sql.PrimaryKeySchema, collation sql.CollationID) error

CreateTemporaryTable implements sql.CreateTemporaryTable.

func (*Database) CreateTrigger 

func (d *Database) CreateTrigger(ctx *sql.Context, definition sql.TriggerDefinition) error

CreateTrigger implements sql.TriggerDatabase.

func (*Database) CreateView 

func (d *Database) CreateView(ctx *sql.Context, name string, selectStatement string, createViewStmt string) error

CreateView implements sql.ViewDatabase.

func (*Database) DropStoredProcedure 

func (d *Database) DropStoredProcedure(ctx *sql.Context, name string) error

DropStoredProcedure implements sql.StoredProcedureDatabase.

func (*Database) DropTable 

func (d *Database) DropTable(ctx *sql.Context, name string) error

DropTable implements sql.TableDropper.

func (*Database) DropTrigger 

func (d *Database) DropTrigger(ctx *sql.Context, name string) error

DropTrigger implements sql.TriggerDatabase.

func (*Database) DropView 

func (d *Database) DropView(ctx *sql.Context, name string) error

DropView implements sql.ViewDatabase.

func (*Database) GetCollation 

func (d *Database) GetCollation(ctx *sql.Context) sql.CollationID

GetCollation implements sql.CollatedDatabase.

func (*Database) GetStoredProcedure 

func (d *Database) GetStoredProcedure(ctx *sql.Context, name string) (sql.StoredProcedureDetails, bool, error)

GetStoredProcedure implements sql.StoredProcedureDatabase. Routines are not hosted in DuckDB; SHOW FUNCTION STATUS should be empty.

func (*Database) GetStoredProcedures 

func (d *Database) GetStoredProcedures(ctx *sql.Context) ([]sql.StoredProcedureDetails, error)

GetStoredProcedures implements sql.StoredProcedureDatabase.

func (*Database) GetTableInsensitive 

func (d *Database) GetTableInsensitive(ctx *sql.Context, tblName string) (sql.Table, bool, error)

GetTableInsensitive implements sql.Database.

func (*Database) GetTableNames 

func (d *Database) GetTableNames(ctx *sql.Context) ([]string, error)

GetTableNames implements sql.Database.

func (*Database) GetTriggers 

func (d *Database) GetTriggers(ctx *sql.Context) ([]sql.TriggerDefinition, error)

GetTriggers implements sql.TriggerDatabase.

func (*Database) GetViewDefinition 

func (d *Database) GetViewDefinition(ctx *sql.Context, viewName string) (sql.ViewDefinition, bool, error)

GetViewDefinition implements sql.ViewDatabase.

func (*Database) MaterializeObjectTable 

func (d *Database) MaterializeObjectTable(ctx *sql.Context, name string) error

MaterializeObjectTable exposes the PostgreSQL parser bridge without exposing the internal shadow-table representation.

func (*Database) Name 

func (d *Database) Name() string

Name implements sql.Database.

func (*Database) RecordTableStorageSelection 

func (d *Database) RecordTableStorageSelection(ctx *sql.Context, name string, storage TableStorageSelection) error

RecordTableStorageSelection updates the managed table metadata for a table created by a protocol path that bypasses sql.TableCreator (currently the PostgreSQL handler). It preserves the user-visible table comment and makes the selection available after a fresh catalog reload.

func (*Database) RecordTableStorageSelectionWithExecutor 

func (d *Database) RecordTableStorageSelectionWithExecutor(
	ctx *sql.Context,
	name string,
	storage TableStorageSelection,
	execer adapter.SQLExecutor,
	conn *stdsql.Conn,
) error

RecordTableStorageSelectionWithExecutor updates managed table metadata through an executor/connection pair that the caller already captured. PG protocol execution holds that snapshot across the statement (and often its result iterator), so reacquiring it here can deadlock behind a pending pool shutdown writer. Callers using this method own any surrounding transaction; this method deliberately does not open a second scoped transaction.

func (*Database) RenameTable 

func (d *Database) RenameTable(ctx *sql.Context, oldName string, newName string) error

RenameTable implements sql.TableRenamer.

func (*Database) SaveStoredProcedure 

func (d *Database) SaveStoredProcedure(ctx *sql.Context, spd sql.StoredProcedureDetails) error

SaveStoredProcedure implements sql.StoredProcedureDatabase.

func (*Database) SetCollation 

func (d *Database) SetCollation(ctx *sql.Context, collation sql.CollationID) error

SetCollation implements sql.CollatedDatabase.

type DatabaseProvider 

type DatabaseProvider struct {
	// contains filtered or unexported fields
}

func NewDBProvider 

func NewDBProvider(defaultTimeZone, dataDir, defaultDB string, options ...ProviderOption) (prov *DatabaseProvider, err error)

func NewInMemoryDBProvider 

func NewInMemoryDBProvider(options ...ProviderOption) *DatabaseProvider

func (*DatabaseProvider) AllDatabases 

func (prov *DatabaseProvider) AllDatabases(ctx *sql.Context) []sql.Database

AllDatabases implements sql.DatabaseProvider.

func (*DatabaseProvider) AttachCatalog 

func (prov *DatabaseProvider) AttachCatalog(file interface {
	IsDir() bool
	Name() string
}, ignoreNonDB bool) error

func (*DatabaseProvider) BeginDuckLakeOperation 

func (prov *DatabaseProvider) BeginDuckLakeOperation(ctx context.Context) func()

BeginDuckLakeOperation reserves admission for one top-level frontend operation that may read or write the service-managed DuckLake relation.

GMS creates a logical autocommit transaction without a physical *sql.Tx when @@autocommit=1. The transaction barrier therefore cannot observe that work through duckLakeActiveTx alone. This lease covers the interval from execution-build through iterator consumption, allowing rollback cleanup to wait for the operation even when no physical transaction exists.

The returned release function is idempotent. Callers must release it on build failure and from every terminal iterator path (EOF, error, or Close).

func (*DatabaseProvider) BeginDuckLakeOperationForOwner 

func (prov *DatabaseProvider) BeginDuckLakeOperationForOwner(ctx context.Context, owner any) func()

BeginDuckLakeOperationForOwner is the owner-aware form of BeginDuckLakeOperation. owner should be the logical transaction identity used by the caller's rollback path (for example, the concrete GMS transaction). A physical *sql.Tx is also accepted and is matched against a rollback target. Owners that are not safely comparable are retained as anonymous blocking leases.

func (*DatabaseProvider) BeginDuckLakeOperationForOwnerWithError 

func (prov *DatabaseProvider) BeginDuckLakeOperationForOwnerWithError(ctx context.Context, owner any) (func(), error)

BeginDuckLakeOperationForOwnerWithError is the owner-aware, error-preserving admission surface. A non-nil error means no lease was admitted and the returned release function is a safe no-op.

func (*DatabaseProvider) BeginDuckLakeOperationWithError 

func (prov *DatabaseProvider) BeginDuckLakeOperationWithError(ctx context.Context) (func(), error)

BeginDuckLakeOperationWithError is the error-preserving admission surface. Legacy callers may continue to use BeginDuckLakeOperation, but new protocol paths should use this form so a poisoned generation cannot be mistaken for a successful no-op admission.

func (*DatabaseProvider) BeginDuckLakeRollbackCleanup 

func (prov *DatabaseProvider) BeginDuckLakeRollbackCleanup(target *stdsql.Tx) func()

BeginDuckLakeRollbackCleanup reserves the provider-wide DuckLake cleanup barrier for a rollback finalizer. Unlike beginDuckLakeCleanup, the target transaction is allowed to remain active while the reservation is acquired: the caller must still run the driver's Rollback before maintenance can use the owner's physical connection. Every other physical transaction, pending admission, and logical frontend operation is drained first, and no new work can enter until the returned release function is called.

The reservation must be obtained before entering a pool/session finalizer. That ordering prevents a finalizer holding the pool release lock from waiting on an operation that itself needs the pool lock to finish. The returned callback is idempotent and safe to defer on all paths.

func (*DatabaseProvider) BeginDuckLakeRollbackCleanupForOwner 

func (prov *DatabaseProvider) BeginDuckLakeRollbackCleanupForOwner(target *stdsql.Tx, owner any) func()

BeginDuckLakeRollbackCleanupForOwner is the owner-aware rollback barrier. The physical target and logical owner are both considered when deciding which already-admitted operation leases belong to this rollback caller. Only those leases are exempt; every other owner, plus anonymous leases, keeps the reservation blocked.

func (*DatabaseProvider) BeginDuckLakeRollbackCleanupForOwnerWithError 

func (prov *DatabaseProvider) BeginDuckLakeRollbackCleanupForOwnerWithError(target *stdsql.Tx, owner any) (func(), error)

BeginDuckLakeRollbackCleanupForOwnerWithError is the owner-aware, error-preserving rollback barrier. The returned release is always safe to call, including when admission fails before the provider mutexes are held.

func (*DatabaseProvider) BeginDuckLakeRollbackCleanupWithError 

func (prov *DatabaseProvider) BeginDuckLakeRollbackCleanupWithError(target *stdsql.Tx) (func(), error)

BeginDuckLakeRollbackCleanupWithError is the error-preserving counterpart to BeginDuckLakeRollbackCleanup. A non-nil error means the provider did not reserve its cleanup barrier; callers must still finalize the driver transaction, but must skip DuckLake maintenance for this poisoned generation.

func (*DatabaseProvider) CleanupDuckLakeOrphans 

func (prov *DatabaseProvider) CleanupDuckLakeOrphans(ctx context.Context) error

CleanupDuckLakeOrphans runs the product-owned orphan cleanup function on a newly acquired service connection. It is a compatibility entry point for maintenance callers that do not already hold a session connection.

func (*DatabaseProvider) CleanupDuckLakeOrphansOnConn 

func (prov *DatabaseProvider) CleanupDuckLakeOrphansOnConn(ctx context.Context, conn *stdsql.Conn) error

CleanupDuckLakeOrphansOnConn performs orphan cleanup on the supplied physical connection. Callers that own a session transaction must invoke it only after that transaction has become inactive, and should pass the same connection so cleanup cannot acquire a second pooled connection.

func (*DatabaseProvider) Close 

func (prov *DatabaseProvider) Close() (err error)

func (*DatabaseProvider) Connector 

func (prov *DatabaseProvider) Connector() *duckdb.Connector

func (*DatabaseProvider) CreateCatalog 

func (prov *DatabaseProvider) CreateCatalog(name string, ifNotExists bool) error

func (*DatabaseProvider) CreateCatalogOnConn 

func (prov *DatabaseProvider) CreateCatalogOnConn(ctx context.Context, conn *stdsql.Conn, name string, ifNotExists bool) error

CreateCatalogOnConn creates and attaches a database using the caller's already-owned physical connection. The provider lock serializes the whole ATTACH/initialization sequence with Restart, while the connection preserves the PostgreSQL client's session catalog state.

func (*DatabaseProvider) CreateDatabase 

func (prov *DatabaseProvider) CreateDatabase(ctx *sql.Context, name string) error

CreateDatabase implements sql.MutableDatabaseProvider.

func (*DatabaseProvider) DataDir 

func (prov *DatabaseProvider) DataDir() string

func (*DatabaseProvider) Database 

func (prov *DatabaseProvider) Database(ctx *sql.Context, name string) (sql.Database, error)

Database implements sql.DatabaseProvider.

func (*DatabaseProvider) DbFile 

func (prov *DatabaseProvider) DbFile() string

func (*DatabaseProvider) DefaultCatalogName 

func (prov *DatabaseProvider) DefaultCatalogName() string

func (*DatabaseProvider) DropCatalog 

func (prov *DatabaseProvider) DropCatalog(name string, ifExists bool) error

func (*DatabaseProvider) DropCatalogOnConn 

func (prov *DatabaseProvider) DropCatalogOnConn(ctx context.Context, conn *stdsql.Conn, name string, ifExists bool) error

DropCatalogOnConn detaches and removes a database using the caller's physical connection. It is serialized with Restart for the full detach/file removal sequence.

func (*DatabaseProvider) DropDatabase 

func (prov *DatabaseProvider) DropDatabase(ctx *sql.Context, name string) error

DropDatabase implements sql.MutableDatabaseProvider.

func (*DatabaseProvider) DuckLakeEnabled 

func (prov *DatabaseProvider) DuckLakeEnabled() bool

DuckLakeEnabled reports whether the service-managed DuckLake connection layer passed validation at provider construction. It never exposes secret values.

func (*DatabaseProvider) DuckLakeObjectStorageEnabled 

func (prov *DatabaseProvider) DuckLakeObjectStorageEnabled() bool

DuckLakeObjectStorageEnabled reports whether the service has both sides of the DuckLake catalog configured. An enabled extension layer may intentionally omit these paths, but it cannot produce or clean lake-table files.

func (*DatabaseProvider) EnsureDuckLakeConnection 

func (prov *DatabaseProvider) EnsureDuckLakeConnection(ctx context.Context, conn *stdsql.Conn) error

EnsureDuckLakeConnection makes the service-owned lake available on an already acquired physical connection. Object-table paths call this after resolving persisted metadata; ordinary local and catalog operations do not need to invoke it explicitly.

func (*DatabaseProvider) EnsureDuckLakeConnectionWithBinding 

func (prov *DatabaseProvider) EnsureDuckLakeConnectionWithBinding(
	ctx context.Context,
	conn *stdsql.Conn,
	tx *stdsql.Tx,
) error

EnsureDuckLakeConnectionWithBinding initializes DuckLake on a connection selected by an already-captured execution snapshot. bindingKnown is kept private in the implementation so this boundary cannot accidentally perform a second pool lookup while the caller retains a lifecycle lease.

A non-nil tx proves that the pool initializer ran before BeginTx and that this exact physical owner is already attached. It does not bypass provider admission: frontend snapshots, including active transactions, are rejected while the storage generation is transitioning or poisoned. A nil tx means an admitted connection-only snapshot may perform the driver-level attach.

func (*DatabaseProvider) EnsureDuckLakeConnectionWithExecutor 

func (prov *DatabaseProvider) EnsureDuckLakeConnectionWithExecutor(
	ctx context.Context,
	execer adapter.SQLExecutor,
	conn *stdsql.Conn,
) error

EnsureDuckLakeConnectionWithExecutor is the convenient form used by statement paths that already carry both the SQL executor and its physical owner. *sql.Tx is recognized without consulting the session/pool maps.

func (*DatabaseProvider) ExternalStoredProcedure 

func (prov *DatabaseProvider) ExternalStoredProcedure(ctx *sql.Context, name string, numOfParams int) (*sql.ExternalStoredProcedureDetails, error)

ExternalStoredProcedure implements sql.ExternalStoredProcedureProvider.

func (*DatabaseProvider) ExternalStoredProcedures 

func (prov *DatabaseProvider) ExternalStoredProcedures(ctx *sql.Context, name string) ([]sql.ExternalStoredProcedureDetails, error)

ExternalStoredProcedures implements sql.ExternalStoredProcedureProvider.

func (*DatabaseProvider) HasCatalog 

func (prov *DatabaseProvider) HasCatalog(name string) bool

func (*DatabaseProvider) HasDatabase 

func (prov *DatabaseProvider) HasDatabase(ctx *sql.Context, name string) bool

HasDatabase implements sql.DatabaseProvider.

func (*DatabaseProvider) InitializeConnection 

func (prov *DatabaseProvider) InitializeConnection(ctx context.Context, conn *stdsql.Conn) error

InitializeConnection applies the service-managed DuckLake setup to an already acquired physical connection. Callers must provide an explicit frontend, maintenance, or recovery origin in ctx; unknown and replication origins deliberately no-op. The runtime keys successful setup by the underlying driver.Conn, so a reused logical *sql.Conn is cheap while every newly opened physical connection is initialized independently.

func (*DatabaseProvider) InitializeStorage 

func (prov *DatabaseProvider) InitializeStorage(ctx context.Context) error

InitializeStorage is retained as a compatibility wrapper for callers that have not yet acquired a connection. New request paths must use InitializeConnection on their already-owned *sql.Conn; this wrapper never caches a database generation and is not used to warm a different request connection.

func (*DatabaseProvider) IsReady 

func (prov *DatabaseProvider) IsReady() bool

func (*DatabaseProvider) LakeSchemaName 

func (prov *DatabaseProvider) LakeSchemaName(catalogName, schemaName string) string

LakeSchemaName returns the deterministic physical schema used for a logical MyDuck catalog/schema pair. The default database retains its schema names so the attached catalog remains inspectable with the normal DuckLake helpers; additional database files are prefixed to avoid collisions in the single service lake catalog.

func (*DatabaseProvider) ObjectTableName 

func (prov *DatabaseProvider) ObjectTableName(ctx *sql.Context, catalogName, schemaName, tableName string) (string, bool, error)

ObjectTableName resolves a persisted object-table comment to its physical DuckLake relation. It deliberately consults the durable local shadow table on every call, so a provider restart cannot retain stale in-memory routing.

func (*DatabaseProvider) ObjectTableNameWithExecutor 

func (prov *DatabaseProvider) ObjectTableNameWithExecutor(
	ctx *sql.Context,
	execer adapter.SQLExecutor,
	catalogName, schemaName, tableName string,
) (string, bool, error)

ObjectTableNameWithExecutor resolves a persisted object-table comment using the caller's execution snapshot. The executor and connection must come from the same adapter.GetExecutionSnapshot call; this is important while a session transaction is active because metadata written in that transaction is only visible through its *sql.Tx.

func (*DatabaseProvider) ObjectTables 

func (prov *DatabaseProvider) ObjectTables(ctx *sql.Context, catalogName string) ([]ObjectTableMapping, error)

func (*DatabaseProvider) ObjectTablesWithExecutor 

func (prov *DatabaseProvider) ObjectTablesWithExecutor(
	ctx *sql.Context,
	execer adapter.SQLExecutor,
	catalogName string,
) ([]ObjectTableMapping, error)

ObjectTablesWithExecutor returns durable object-table mappings through an already selected execution snapshot. It never acquires another connection.

func (*DatabaseProvider) PhysicalTableNameForTable 

func (prov *DatabaseProvider) PhysicalTableNameForTable(ctx *sql.Context, table sql.Table) (string, bool, error)

PhysicalTableNameForTable is used by protocol COPY helpers and by callers that already resolved a GMS table. Local tables return their normal fully qualified name; object tables return the fixed lake relation.

func (*DatabaseProvider) PhysicalTableNameForTableWithExecutor 

func (prov *DatabaseProvider) PhysicalTableNameForTableWithExecutor(
	ctx *sql.Context,
	table sql.Table,
	execer adapter.SQLExecutor,
	conn *stdsql.Conn,
) (string, bool, error)

PhysicalTableNameForTableWithExecutor resolves a table through the supplied execution snapshot. Metadata lookup and the eventual statement execution therefore remain on one transaction/connection pair.

func (*DatabaseProvider) Pool 

func (prov *DatabaseProvider) Pool() *ConnectionPool

func (*DatabaseProvider) Restart 

func (prov *DatabaseProvider) Restart(readOnly bool) (err error)

func (*DatabaseProvider) Storage 

func (prov *DatabaseProvider) Storage() *stdsql.DB

type EmptyTableEditor 

type EmptyTableEditor struct {
}

func (*EmptyTableEditor) Close 

func (e *EmptyTableEditor) Close(*sql.Context) error

Close implements sql.RowUpdater.

func (*EmptyTableEditor) DiscardChanges 

func (e *EmptyTableEditor) DiscardChanges(ctx *sql.Context, errorEncountered error) error

DiscardChanges implements sql.RowUpdater.

func (*EmptyTableEditor) StatementBegin 

func (e *EmptyTableEditor) StatementBegin(ctx *sql.Context)

StatementBegin implements sql.RowUpdater.

func (*EmptyTableEditor) StatementComplete 

func (e *EmptyTableEditor) StatementComplete(ctx *sql.Context) error

StatementComplete implements sql.RowUpdater.

func (*EmptyTableEditor) Update 

func (e *EmptyTableEditor) Update(ctx *sql.Context, old sql.Row, new sql.Row) error

Update implements sql.RowUpdater.

type ExtensionArtifact 

type ExtensionArtifact struct {
	Name         string
	FileName     string
	SHA256       string
	Architecture string
	ABI          string
	Version      string
}

ExtensionArtifact is one fixed, decompressed DuckDB extension binary. The filename is deliberately fixed so service configuration cannot select an arbitrary extension or trigger an INSTALL/network fallback.

func CurrentDuckLakeExtensionManifest 

func CurrentDuckLakeExtensionManifest() ([]ExtensionArtifact, error)

CurrentDuckLakeExtensionManifest resolves the manifest for the running binary's target platform.

func DuckLakeExtensionManifest 

func DuckLakeExtensionManifest(goos, goarch string) ([]ExtensionArtifact, error)

DuckLakeExtensionManifest returns a copy of the fixed manifest for a supported target. Only Linux amd64 and arm64 artifacts are accepted.

type ExternalSession 

type ExternalSession struct {
	// contains filtered or unexported fields
}

ExternalSession is an opaque, pool-owned connection identity for protocol surfaces whose handles do not share the uint32 namespace used by MySQL and PostgreSQL sessions. Driver access is exposed only through ExecutionLease so pool generation teardown can wait for admitted work before retiring the exact connection.

func (*ExternalSession) BeginTx 

func (s *ExternalSession) BeginTx(ctx context.Context, opts *stdsql.TxOptions) (*stdsql.Tx, error)

BeginTx opens a transaction on the handle's exact connection. Provider transaction admission is reserved without holding a lifecycle reader so a generation transition can make progress while admission waits.

func (*ExternalSession) Close 

func (s *ExternalSession) Close() error

Close releases an external handle. It is idempotent and uses release-side lifecycle admission so callers can close handles while pool shutdown waits for older operations to drain.

func (*ExternalSession) Commit 

func (s *ExternalSession) Commit(expected *stdsql.Tx) error

Commit commits only the exact active transaction supplied by the caller. A stale or mismatched pointer is rejected before any driver operation.

func (*ExternalSession) ExecutionLease 

func (s *ExternalSession) ExecutionLease(
	ctx context.Context,
) (*stdsql.Conn, *stdsql.Tx, func(), error)

ExecutionLease returns the exact connection and transaction owned by this handle. The release function is idempotent and must be held through all synchronous driver work and result consumption.

func (*ExternalSession) Rollback 

func (s *ExternalSession) Rollback(
	expected *stdsql.Tx,
	cleanup func(*stdsql.Conn) error,
) error

Rollback rolls back only the exact active transaction supplied by the caller. cleanup runs on the same physical connection after the driver proves the transaction inactive and before another operation can enter the handle. The caller must reserve any provider rollback-maintenance barrier first.

func (*ExternalSession) SetCleanupHook 

func (s *ExternalSession) SetCleanupHook(hook func()) error

SetCleanupHook installs the protocol-owned prepared-state cleanup for this handle. Only one hook may be installed. If teardown won the race, the hook is invoked inline so protocol state is never left behind; the returned state error still tells the caller that the handle can no longer be used.

Cleanup hooks must not re-enter this ExternalSession. Both the normal teardown path and an already-invalid late registration invoke hooks outside opMu; a late registration waits for the teardown owner first so hooks cannot overlap or race connection retirement.

type ExtraTableInfo 

type ExtraTableInfo struct {
	PkOrdinals []int
	Replicated bool
	Sequence   string
	Checks     []sql.CheckDefinition
	// Storage records the table's durable storage class. An empty value is
	// treated as local for metadata written before table-level storage
	// selection existed; newly-created tables always write the explicit value.
	Storage TableStorageKind `json:"storage,omitempty"`
}

func (ExtraTableInfo) StorageKind 

func (info ExtraTableInfo) StorageKind() TableStorageKind

StorageKind returns the effective storage class for this metadata. Missing storage metadata is the backwards-compatible local-table behavior.

type ExtraViewInfo 

type ExtraViewInfo struct {
	TextDefinition      string `json:"text_definition,omitempty"`
	CreateViewStatement string `json:"create_view_statement,omitempty"`
	SqlMode             string `json:"sql_mode,omitempty"`
}

type Index 

type Index struct {
	DbName     string
	TableName  string
	Exprs      []sql.Expression
	Name       string
	Unique     bool
	CommentObj *Comment[IndexMeta]
	PrefixLens []uint16
}

func NewIndex 

func NewIndex(dbName, tableName, name string, unique bool, comment *Comment[IndexMeta], exprs []sql.Expression) *Index

func (*Index) CanSupport 

func (idx *Index) CanSupport(_ *sql.Context, ranges ...sql.Range) bool

CanSupport returns whether this index supports lookups on the given range filters.

func (*Index) CanSupportOrderBy 

func (idx *Index) CanSupportOrderBy(expr sql.Expression) bool

CanSupportOrderBy returns whether this index can optimize ORDER BY a given expression type. Verifying that the expression's children match the index columns are done separately.

func (*Index) ColumnExpressionTypes 

func (idx *Index) ColumnExpressionTypes(ctx *sql.Context) []sql.ColumnExpressionType

ColumnExpressionTypes returns each expression and its associated Type. Each expression string should exactly match the string returned from Index.Expressions(). ColumnExpressionTypes implements the interface sql.Index.

func (*Index) Comment 

func (idx *Index) Comment() string

Comment returns the comment for this index

func (*Index) CoversColumns 

func (idx *Index) CoversColumns(cols []string) bool

CoversColumns reports whether every requested column is present in this index.

func (*Index) Database 

func (idx *Index) Database() string

Database returns the database name this index belongs to.

func (*Index) Expressions 

func (idx *Index) Expressions() []string

Expressions returns the indexed expressions. If the result is more than one expression, it means the index has multiple columns indexed. If it's just one, it means it may be an expression or a column.

func (*Index) ID 

func (idx *Index) ID() string

ID returns the identifier of the index.

func (*Index) IndexType 

func (idx *Index) IndexType() string

IndexType returns the type of this index, e.g. BTREE

func (*Index) IsFullText 

func (idx *Index) IsFullText() bool

IsFullText returns whether this index is a Full-Text index

func (*Index) IsGenerated 

func (idx *Index) IsGenerated() bool

IsGenerated returns whether this index was generated. Generated indexes are used for index access, but are not displayed (such as with SHOW INDEXES).

func (*Index) IsSpatial 

func (idx *Index) IsSpatial() bool

IsSpatial returns whether this index is a spatial index

func (*Index) IsUnique 

func (idx *Index) IsUnique() bool

IsUnique returns whether this index is unique

func (*Index) IsVector 

func (idx *Index) IsVector() bool

IsVector returns whether this index is a vector index

func (*Index) PrefixLengths 

func (idx *Index) PrefixLengths() []uint16

PrefixLengths returns the prefix lengths for each column in this index

func (*Index) Table 

func (idx *Index) Table() string

Table returns the table name this index belongs to.

type IndexMeta 

type IndexMeta struct {
	PrefixLengths []uint16 `json:"prefix_lengths,omitempty"`
}

type IndexedTable 

type IndexedTable struct {
	*Table
	Lookup sql.IndexLookup
}

func (*IndexedTable) LookupPartitions 

func (t *IndexedTable) LookupPartitions(ctx *sql.Context, lookup sql.IndexLookup) (sql.PartitionIter, error)

type InternalMacro 

type InternalMacro struct {
	Schema       string
	Name         string
	IsTableMacro bool
	// A macro can be overloaded with multiple definitions, each with a different set of parameters.
	// https://duckdb.org/docs/sql/statements/create_macro.html#overloading
	Definitions []MacroDefinition
}

func (*InternalMacro) LogicalName 

func (v *InternalMacro) LogicalName() string

func (*InternalMacro) QualifiedName 

func (v *InternalMacro) QualifiedName() string

type InternalSchema 

type InternalSchema struct {
	Schema string
}

type InternalTable 

type InternalTable struct {
	Schema       string
	Name         string
	KeyColumns   []string
	ValueColumns []string
	DDL          string
	InitialData  [][]any
}

func GetInternalTables 

func GetInternalTables() []InternalTable

func (*InternalTable) CountAllStmt 

func (it *InternalTable) CountAllStmt() string

func (*InternalTable) DeleteAllStmt 

func (it *InternalTable) DeleteAllStmt() string

func (*InternalTable) DeleteStmt 

func (it *InternalTable) DeleteStmt() string

func (*InternalTable) QualifiedName 

func (it *InternalTable) QualifiedName() string

func (*InternalTable) SelectAllStmt 

func (it *InternalTable) SelectAllStmt() string

func (*InternalTable) SelectColumnsStmt 

func (it *InternalTable) SelectColumnsStmt(valueColumns []string) string

func (*InternalTable) SelectStmt 

func (it *InternalTable) SelectStmt() string

func (*InternalTable) UpdateAllStmt 

func (it *InternalTable) UpdateAllStmt(valueColumns []string) string

func (*InternalTable) UpdateStmt 

func (it *InternalTable) UpdateStmt(keyColumns []string, valueColumns []string) string

func (*InternalTable) UpsertStmt 

func (it *InternalTable) UpsertStmt() string

type InternalView 

type InternalView struct {
	Schema string
	Name   string
	DDL    string
}

func (*InternalView) QualifiedName 

func (v *InternalView) QualifiedName() string

type MacroDefinition 

type MacroDefinition struct {
	Params []string
	DDL    string
}

type MySQLType 

type MySQLType struct {
	Name          string
	Length        uint32   `json:",omitempty"`
	Precision     uint8    `json:",omitempty"`
	Scale         uint8    `json:",omitempty"`
	Unsigned      bool     `json:",omitempty"`
	Display       uint8    `json:",omitempty"` // Display width for integer types
	Collation     uint16   `json:",omitempty"` // For string types
	Values        []string `json:",omitempty"` // For ENUM and SET
	Default       string   `json:",omitempty"` // Default value of column
	Generated     string   `json:",omitempty"` // Generated column expression
	Virtual       bool     `json:",omitempty"`
	Nullable      *bool    `json:",omitempty"` // Preserve constraints DuckDB cannot attach to generated columns.
	AutoIncrement bool     `json:",omitempty"` // Auto increment flag
}

type ObjectTableMapping 

type ObjectTableMapping struct {
	Catalog        string
	Schema         string
	Table          string
	PhysicalName   string
	PhysicalSchema string
}

ObjectTables returns all durable object-table mappings for a logical catalog. The result is used by the protocol SQL rewriter and is intentionally sourced from duckdb_tables() rather than process-local state.

type ProviderOption 

type ProviderOption func(*providerOptions) error

ProviderOption configures optional provider behavior while preserving the historical three-argument NewDBProvider call sites.

func WithDuckLakeConfig 

func WithDuckLakeConfig(config configuration.DuckLakeConfig) ProviderOption

WithDuckLakeConfig enables the service-managed DuckLake connection layer. The feature remains disabled when config.Enabled is false.

func WithDuckLakeServiceConfig 

func WithDuckLakeServiceConfig(config configuration.DuckLakeServiceConfig) ProviderOption

WithDuckLakeServiceConfig is a descriptive alias for WithDuckLakeConfig.

type Table 

type Table struct {
	// contains filtered or unexported fields
}

func NewTable 

func NewTable(db *Database, name string, hasPrimaryKey bool) *Table

func (*Table) AddColumn 

func (t *Table) AddColumn(ctx *sql.Context, column *sql.Column, order *sql.ColumnOrder) error

AddColumn implements sql.AlterableTable.

func (*Table) AutoIncrementSetter 

func (t *Table) AutoIncrementSetter(ctx *sql.Context) sql.AutoIncrementSetter

AutoIncrementSetter implements sql.AutoIncrementTable.

func (*Table) Collation 

func (t *Table) Collation() sql.CollationID

Collation implements sql.Table.

func (*Table) Comment 

func (t *Table) Comment() string

Comment implements sql.CommentedTable.

func (*Table) CreateCheck 

func (t *Table) CreateCheck(ctx *sql.Context, check *sql.CheckDefinition) error

AddCheck implements sql.CheckAlterableTable.

func (*Table) CreateIndex 

func (t *Table) CreateIndex(ctx *sql.Context, indexDef sql.IndexDef) error

CreateIndex implements sql.IndexAlterableTable.

func (*Table) DataLength 

func (t *Table) DataLength(ctx *sql.Context) (uint64, error)

DataLength implements sql.StatisticsTable.

func (*Table) Deleter 

func (t *Table) Deleter(*sql.Context) sql.RowDeleter

Deleter implements sql.DeletableTable.

func (*Table) DropCheck 

func (t *Table) DropCheck(ctx *sql.Context, checkName string) error

DropCheck implements sql.CheckAlterableTable.

func (*Table) DropColumn 

func (t *Table) DropColumn(ctx *sql.Context, columnName string) error

DropColumn implements sql.AlterableTable.

func (*Table) DropIndex 

func (t *Table) DropIndex(ctx *sql.Context, indexName string) error

DropIndex implements sql.IndexAlterableTable.

func (*Table) ExtraTableInfo 

func (t *Table) ExtraTableInfo() ExtraTableInfo

func (*Table) GetChecks 

func (t *Table) GetChecks(ctx *sql.Context) ([]sql.CheckDefinition, error)

CheckConstraints implements sql.CheckTable.

func (*Table) GetIndexes 

func (t *Table) GetIndexes(ctx *sql.Context) ([]sql.Index, error)

GetIndexes implements sql.IndexAddressableTable. This is only used for show index in SHOW INDEX and SHOW CREATE TABLE.

func (*Table) GetNextAutoIncrementValue 

func (t *Table) GetNextAutoIncrementValue(ctx *sql.Context, insertVal any) (uint64, error)

GetNextAutoIncrementValue implements sql.AutoIncrementTable.

func (*Table) HasPrimaryKey 

func (t *Table) HasPrimaryKey() bool

func (*Table) IndexedAccess 

func (t *Table) IndexedAccess(_ *sql.Context, lookup sql.IndexLookup) sql.IndexedTable

IndexedAccess implements sql.IndexAddressableTable.

func (*Table) Inserter 

func (t *Table) Inserter(*sql.Context) sql.RowInserter

Inserter implements sql.InsertableTable.

func (*Table) ModifyColumn 

func (t *Table) ModifyColumn(ctx *sql.Context, columnName string, column *sql.Column, order *sql.ColumnOrder) error

ModifyColumn implements sql.AlterableTable.

func (*Table) ModifyComment 

func (t *Table) ModifyComment(ctx *sql.Context, text string) error

ModifyComment implements sql.CommentAlterableTable.

func (*Table) Name 

func (t *Table) Name() string

Name implements sql.Table.

func (*Table) PartitionRows 

func (t *Table) PartitionRows(ctx *sql.Context, _ sql.Partition) (sql.RowIter, error)

PartitionRows implements sql.Table.

func (*Table) Partitions 

func (t *Table) Partitions(ctx *sql.Context) (sql.PartitionIter, error)

Partitions implements sql.Table.

func (*Table) PeekNextAutoIncrementValue 

func (t *Table) PeekNextAutoIncrementValue(ctx *sql.Context) (uint64, error)

PeekNextAutoIncrementValue implements sql.AutoIncrementTable.

func (*Table) PreciseMatch 

func (t *Table) PreciseMatch() bool

PreciseMatch implements sql.IndexAddressableTable.

func (*Table) PrimaryKeySchema 

func (t *Table) PrimaryKeySchema(_ *sql.Context) sql.PrimaryKeySchema

PrimaryKeySchema implements sql.PrimaryKeyTable.

func (*Table) RenameIndex 

func (t *Table) RenameIndex(ctx *sql.Context, fromIndexName string, toIndexName string) error

RenameIndex implements sql.IndexAlterableTable.

func (*Table) Replacer 

func (t *Table) Replacer(*sql.Context) sql.RowReplacer

Replacer implements sql.ReplaceableTable.

func (*Table) RowCount 

func (t *Table) RowCount(ctx *sql.Context) (uint64, bool, error)

RowCount implements sql.StatisticsTable.

func (*Table) Schema 

func (t *Table) Schema(_ *sql.Context) sql.Schema

Schema implements sql.Table.

func (*Table) String 

func (t *Table) String() string

String implements sql.Table.

func (*Table) Truncate 

func (t *Table) Truncate(ctx *sql.Context) (int, error)

Truncate implements sql.TruncateableTable.

func (*Table) Updater 

func (t *Table) Updater(ctx *sql.Context) sql.RowUpdater

Updater implements sql.AlterableTable.

type TableStorageKind 

type TableStorageKind string

TableStorageKind is the durable storage class for a user table. Resolver functions use local when no selector is present; object is the DuckLake- backed class selected by the 0.3 table-storage slice.

type TableStorageOption 

type TableStorageOption struct {
	Name  string
	Value any
}

TableStorageOption is a parser-neutral name/value pair. Keeping options as a slice lets protocol adapters preserve duplicates and reject them before a map-based planner silently overwrites one declaration with another.

type TableStorageSelection 

type TableStorageSelection struct {
	Kind     TableStorageKind
	Explicit bool
	Source   string
}

TableStorageSelection is the normalized result of a CREATE TABLE storage selector. Explicit is false only when no selector was supplied, in which case Kind is always TableStorageLocal.

func DefaultTableStorageSelection 

func DefaultTableStorageSelection() TableStorageSelection

func NormalizeTableStorageOptions 

func NormalizeTableStorageOptions(options []TableStorageOption) (TableStorageSelection, error)

NormalizeTableStorageOptions resolves the selectors that protocol parsers expose. Ordinary MySQL/PostgreSQL table options are ignored and retain their historical local behavior. Only the explicit selector and recognized ENGINE alias affect the result.

func ResolveMySQLTableStorage 

func ResolveMySQLTableStorage(options map[string]interface{}) (TableStorageSelection, error)

ResolveMySQLTableStorage consumes the map produced by go-mysql-server's planner. The planner has already removed duplicate keys, so protocol adapters that need duplicate detection should call NormalizeTableStorageOptions on a token-preserving slice first.

func ResolvePostgresStorageOptions 

func ResolvePostgresStorageOptions(options []TableStorageOption) (TableStorageSelection, error)

ResolvePostgresStorageOptions is the duplicate-preserving form for callers that walk tree.StorageParams directly.

func ResolvePostgresStorageParams 

func ResolvePostgresStorageParams(params map[string]string) (TableStorageSelection, error)

ResolvePostgresStorageParams consumes literal values extracted from Cockroach's tree.CreateTable.StorageParams. Values may retain SQL quoting; the strict value parser removes one matching quote pair.

func TableStorageSelectionFromContext 

func TableStorageSelectionFromContext(ctx *sql.Context) (TableStorageSelection, bool)

TableStorageSelectionFromContext retrieves a selector attached by SetTableStorageSelection or WithTableStorageSelection. A missing or invalid value is reported as absent so callers can safely fall back to local.

func (TableStorageSelection) EffectiveKind 

func (s TableStorageSelection) EffectiveKind() TableStorageKind

EffectiveKind makes the local default explicit for callers that receive a zero-valued selection from an optional context or metadata field.

func (TableStorageSelection) IsObjectStorage 

func (s TableStorageSelection) IsObjectStorage() bool

func (TableStorageSelection) Validate 

func (s TableStorageSelection) Validate() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.