Manages GizmoSQL processes that expose DuckLake databases as PostgreSQL-compatible SQL endpoints. Each process runs as a Docker container and connects to a DuckLake catalog backed by PostgreSQL.

Usage

starlake gizmosql <action> [options]

Actions

Action	Description
`start`	Start a new GizmoSQL process
`stop`	Stop a specific process by name
`list`	List all running GizmoSQL processes
`stop-all`	Stop all running GizmoSQL processes

Options

action (required): Action to perform: start, stop, list, stop-all
--connection <value>: Connection name (required for start and stop). Must reference a DuckLake connection
--port <value>: Port for the GizmoSQL process (optional, for start). Overrides the SL_DUCKDB_PORT connection option
--reportFormat <value>: Report output format: console, json, or html

Configuration Context

GizmoSQL Server Settings

The GizmoSQL server URL and API key are configured in application.sl.yml:

version: 1
application:
  gizmo:
    url: "http://localhost:8080"
    apiKey: "your-api-key"

DuckLake Connection Requirements

The start action requires a DuckLake connection. The connection must have preActions containing a 'ducklake: reference and a USE command to identify the database.

version: 1
application:
  connections:
    my-ducklake:
      type: "jdbc"
      options:
        url: "jdbc:duckdb::memory:"
        driver: "org.duckdb.DuckDBDriver"
        preActions: "INSTALL ducklake FROM community; LOAD ducklake; ATTACH 'ducklake:postgres:mydb' AS mydb (DATA_PATH 'ducklake_files/mydb'); USE mydb"
        PG_HOST: "localhost"
        PG_PORT: "5432"
        PG_USERNAME: "postgres"
        PG_PASSWORD: "secret"
        SL_DUCKDB_PORT: "5433"
        SL_DATA_PATH: "ducklake_files/mydb"

Connection Options for Start

The following connection options are read when starting a GizmoSQL process:

Option	Description	Default
`preActions`	Must contain `'ducklake:` and a `USE <db>` command	(required)
`PG_HOST`	PostgreSQL catalog host	`localhost`
`PG_PORT`	PostgreSQL catalog port	`5432`
`PG_USERNAME`	PostgreSQL catalog username	(empty)
`PG_PASSWORD`	PostgreSQL catalog password	(empty)
`SL_DUCKDB_PORT`	Default port for the GizmoSQL process	(none)
`SL_DATA_PATH`	Data file storage path	`ducklake_files/<db_name>`
`storageType`	Storage backend: `local`, `gcs`, or `s3`	`local`

Cloud Storage Options (S3/GCS)

When storageType is gcs or s3, additional options are read from the connection:

Option	Environment Variable	Description
`fs.s3a.access.key`	`AWS_KEY_ID`	AWS access key ID
`fs.s3a.secret.key`	`AWS_SECRET`	AWS secret access key
`fs.s3a.endpoint.region`	`AWS_REGION`	AWS region
`fs.s3a.endpoint`	`AWS_ENDPOINT`	S3-compatible endpoint

Cloud Storage Data Path Examples

GCS (Google Cloud Storage)

version: 1
application:
  connections:
    my-ducklake-gcs:
      type: "jdbc"
      options:
        url: "jdbc:duckdb:"
        driver: "org.duckdb.DuckDBDriver"
        preActions: >
          INSTALL POSTGRES;
          INSTALL ducklake;
          LOAD POSTGRES;
          LOAD ducklake;
          CREATE OR REPLACE SECRET (
              TYPE gcs,
              KEY_ID '{{GCS_HMAC_ACCESS_KEY_ID}}',
              SECRET '{{GCS_HMAC_SECRET_ACCESS_KEY}}'
              SCOPE 'gs://{{GCS_BUCKET}}/');
          ATTACH IF NOT EXISTS 'ducklake:postgres:
                  dbname={{PG_DATABASE}}
                  host={{PG_HOST}}
                  port={{PG_PORT}}
                  user={{PG_USER}}
                  password={{PG_PASSWORD}}' AS my_ducklake
              (DATA_PATH 'gs://{{GCS_BUCKET}}/data_files/');
          USE my_ducklake;
        PG_HOST: "{{PG_HOST}}"
        PG_PORT: "{{PG_PORT}}"
        PG_USERNAME: "{{PG_USER}}"
        PG_PASSWORD: "{{PG_PASSWORD}}"
        SL_DUCKDB_PORT: "5433"
        SL_DATA_PATH: "gs://{{GCS_BUCKET}}/data_files/"
        storageType: "gcs"
        fs.s3a.access.key: "{{GCS_HMAC_ACCESS_KEY_ID}}"
        fs.s3a.secret.key: "{{GCS_HMAC_SECRET_ACCESS_KEY}}"
        fs.s3a.endpoint: "https://storage.googleapis.com"
        fs.s3a.endpoint.region: "auto"

Note: GCS uses HMAC keys for S3-compatible access. Generate them in the GCP Console under Cloud Storage > Settings > Interoperability.

AWS S3

version: 1
application:
  connections:
    my-ducklake-s3:
      type: "jdbc"
      options:
        url: "jdbc:duckdb:"
        driver: "org.duckdb.DuckDBDriver"
        preActions: >
          INSTALL POSTGRES;
          INSTALL ducklake;
          LOAD POSTGRES;
          LOAD ducklake;
          CREATE OR REPLACE SECRET (
              TYPE s3,
              KEY_ID '{{AWS_ACCESS_KEY_ID}}',
              SECRET '{{AWS_SECRET_ACCESS_KEY}}',
              REGION '{{AWS_REGION}}'
              SCOPE 's3://{{S3_BUCKET}}/');
          ATTACH IF NOT EXISTS 'ducklake:postgres:
                  dbname={{PG_DATABASE}}
                  host={{PG_HOST}}
                  port={{PG_PORT}}
                  user={{PG_USER}}
                  password={{PG_PASSWORD}}' AS my_ducklake
              (DATA_PATH 's3://{{S3_BUCKET}}/data_files/');
          USE my_ducklake;
        PG_HOST: "{{PG_HOST}}"
        PG_PORT: "{{PG_PORT}}"
        PG_USERNAME: "{{PG_USER}}"
        PG_PASSWORD: "{{PG_PASSWORD}}"
        SL_DUCKDB_PORT: "5433"
        SL_DATA_PATH: "s3://{{S3_BUCKET}}/data_files/"
        storageType: "s3"
        fs.s3a.access.key: "{{AWS_ACCESS_KEY_ID}}"
        fs.s3a.secret.key: "{{AWS_SECRET_ACCESS_KEY}}"
        fs.s3a.endpoint: "https://s3.amazonaws.com"
        fs.s3a.endpoint.region: "{{AWS_REGION}}"

Azure Blob Storage

version: 1
application:
  connections:
    my-ducklake-azure:
      type: "jdbc"
      options:
        url: "jdbc:duckdb:"
        driver: "org.duckdb.DuckDBDriver"
        preActions: >
          INSTALL POSTGRES;
          INSTALL ducklake;
          LOAD POSTGRES;
          LOAD ducklake;
          CREATE OR REPLACE SECRET (
              TYPE azure,
              CONNECTION_STRING 'DefaultEndpointsProtocol=https;AccountName={{AZURE_STORAGE_ACCOUNT}};AccountKey={{AZURE_STORAGE_KEY}};EndpointSuffix=core.windows.net'
              SCOPE 'az://{{AZURE_CONTAINER}}/');
          ATTACH IF NOT EXISTS 'ducklake:postgres:
                  dbname={{PG_DATABASE}}
                  host={{PG_HOST}}
                  port={{PG_PORT}}
                  user={{PG_USER}}
                  password={{PG_PASSWORD}}' AS my_ducklake
              (DATA_PATH 'az://{{AZURE_CONTAINER}}/data_files/');
          USE my_ducklake;
        PG_HOST: "{{PG_HOST}}"
        PG_PORT: "{{PG_PORT}}"
        PG_USERNAME: "{{PG_USER}}"
        PG_PASSWORD: "{{PG_PASSWORD}}"
        SL_DUCKDB_PORT: "5433"
        SL_DATA_PATH: "az://{{AZURE_CONTAINER}}/data_files/"

Note: Azure uses the az:// URI scheme for DuckDB. Alternative schemes include abfss://{{AZURE_CONTAINER}}@{{AZURE_STORAGE_ACCOUNT}}.dfs.core.windows.net/ for ADLS Gen2 access.

Examples

Start a GizmoSQL Process

starlake gizmosql start --connection my-ducklake

Start on a Specific Port

starlake gizmosql start --connection my-ducklake --port 5433

List Running GizmoSQL Processes

starlake gizmosql list

Output columns: connectionName, port, pid, status

Stop a Specific GizmoSQL Process

starlake gizmosql stop --connection my-ducklake

Stop All GizmoSQL Processes

starlake gizmosql stop-all

Related Skills

connection: Database connection configuration
settings: Print settings and test connections
config: Configuration reference