sql.schema

import sql.schema

sql lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled sql.schema.* needs import sql.schema.

Asking a database what is in it.

Every engine can list its tables and describe its columns, and every engine does it differently: PostgreSQL has information_schema, SQLite has PRAGMA table_info. The queries have nothing in common, so each adapter writes its own and they all return the same shape.

for table in db.schema.tables() {
  echo table
}

for column in db.schema.columns('posts') {
  echo '${column.name} ${column.type}${column.nullable ? "" : " not null"}'
}

This is what makes insert() portable: on an engine with no last insert id, the insert needs a RETURNING clause, and the column to return is the table’s primary key, which is asked for here.

Functions

column_shape()

sql.column_shape() -> dict

The description of one column, as every adapter returns it.

Returns dict

Classes

Schema

class sql.Schema

Introspection for one connection.

The methods here delegate to the adapter, which is where the queries that differ per engine live. An adapter that has not implemented introspection raises NotSupportedError rather than returning something empty, so “this engine cannot tell you” never looks like “there is nothing there”.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

sql.Schema(connection)

Parameters

• connection (Connection)

Schema.tables()

sql.Schema.tables(schema) -> list[string]

The names of the tables in the database.

Tables the engine keeps for itself are left out, so what comes back is what the application created.

Parameters

• schema (string|nil) — Which schema to look in, on an engine that has them. The default schema when nil.

Returns list[string]

Schema.views()

sql.Schema.views(schema) -> list[string]

The names of the views in the database.

Parameters

• schema (string|nil)

Returns list[string]

Schema.has_table()

sql.Schema.has_table(table: string, schema) -> bool

Whether table exists.

Parameters

• table (string)
• schema (string|nil)

Returns bool

Schema.columns()

sql.Schema.columns(table: string, schema) -> list[dict]

The columns of table, in order.

Parameters

• table (string)
• schema (string|nil)

Returns list[dict] — Each as described by column_shape().

Schema.column_names()

sql.Schema.column_names(table: string, schema) -> list[string]

The names of table’s columns, in order.

Parameters

• table (string)
• schema (string|nil)

Returns list[string]

Schema.has_column()

sql.Schema.has_column(table: string, column: string, schema) -> bool

Whether table has a column called column.

Parameters

• table (string)
• column (string)
• schema (string|nil)

Returns bool

Schema.primary_key()

sql.Schema.primary_key(table: string, schema) -> string|nil

The name of table’s primary key column, or nil.

Nil for a table with no primary key and for one whose primary key spans several columns, since neither has a single column to name. primary_key_columns() covers the composite case.

Parameters

• table (string)
• schema (string|nil)

Returns string|nil

Schema.primary_key_columns()

sql.Schema.primary_key_columns(table: string, schema) -> list[string]

The columns making up table’s primary key, in key order.

Parameters

• table (string)
• schema (string|nil)

Returns list[string]

Schema.indexes()

sql.Schema.indexes(table: string, schema) -> list[dict]

The indexes on table.

Each is { name, columns, unique }.

Parameters

• table (string)
• schema (string|nil)

Returns list[dict]

Schema.foreign_keys()

sql.Schema.foreign_keys(table: string, schema) -> list[dict]

The foreign keys declared on table.

Each is { columns, references_table, references_columns, on_delete, on_update }.

Parameters

• table (string)
• schema (string|nil)

Returns list[dict]

Schema.to_string()

sql.Schema.to_string()

2026, Richard Ore and Zuri contributors