---

name: sql-backend description: "Use Lux optional PostgreSQL SQL executor workflows with LuxSQLTable and JoinedSQLTable." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

sql-backend

Use this sub-skill when a user wants Lux to explore data that already lives in a PostgreSQL database through LuxSQLTable, JoinedSQLTable, and the SQL executor.

SQL support is optional and service-backed. Do not assume that a PostgreSQL service, database credentials, fixture tables, psycopg2, or SQLAlchemy are available. The required CPU Lux environment verifies base Pandas/visualization workflows only; SQL native behavior remains an optional backend until a user supplies a database service.

Route map

• Start with references/sql-workflows.md for connection setup, executor switching, table/view setup, JoinedSQLTable, query-template behavior, and safe schema notes.
• Use references/api-reference.md when the task depends on exact APIs, signatures, executor behavior, generated SQL patterns, or class limitations.
• Use references/troubleshooting.md for missing connector, missing table, PostgreSQL service, schema, permissions, expensive metadata, or unsupported Pandas/SQL operations.
• Use scripts/sql_table_probe.py before constructing a LuxSQLTable when credentials are available and the user wants a non-destructive connectivity/table probe.

Minimal decision checklist

1. Confirm the user has PostgreSQL >= 9.5 and a table or view that already exists.
2. Confirm exactly one connector path: a psycopg2 connection/DSN or a SQLAlchemy PostgreSQL engine/URL.
3. Configure Lux with lux.config.set_SQL_connection(connection_or_engine) and keep lux.config.set_executor_type("SQL") in mind when refreshing SQL executor state.
4. Bind the table with either lux.LuxSQLTable(table_name="...") or sql_tbl.set_SQL_table("...").
5. Avoid ordinary Pandas manipulation on LuxSQLTable; if the user needs arbitrary transforms, perform them in SQL first or load a small result into Pandas and use Lux's Pandas workflow.
6. Treat joins as a special, permission-sensitive JoinedSQLTable(joins=[...]) workflow, not as a normal SQL executor capability.

Do not use this sub-skill for

• In-memory Pandas DataFrame recommendations and intents; route to the Pandas/intent sub-skill.
• Clause, Vis, VisList, and export-only questions that do not involve a SQL-backed table; route to the visualization/export sub-skill.
• Global Lux style, widget, or action configuration unless the issue is specific to SQL executor switching.