### Initialize UI Server with Custom Log Writer

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/ui-server.md

This example demonstrates starting the UI server with a custom log writer, specifically a StoringConsoleWriter. This allows for more control over logging output. Ensure the context and output stream are correctly provided.

```go
// Create storing log writer
logWriter := logwriter.NewStoringConsoleWriter(context.Background(), os.Stdout)

// Create UI server with logging
uiServer := ui.NewUIServerWithLogWriter("my_project", "github.com/myorg/myproject", 8080, debugDag, logWriter)

if err := uiServer.Start(); err != nil {
	panic(err)
}
```

--------------------------------

### ChannelDag Usage Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/dags.md

Demonstrates how to initialize a ChannelDag with tests, define assets and tests, build the DAG graph, start execution, push tasks, and handle results.

```go
package main

import (
	"github.com/go-teal/teal/pkg/dags"
	"github.com/go-teal/teal/pkg/configs"
	// ... import processing, models, drivers
)

func main() {
	// Build your assets and tests
	assetsMap := map[string]processing.Asset{
		"staging.customers": initCustomersAsset(),
		"mart.summary":      initSummaryAsset(),
	}
	
testsMap := map[string]processing.ModelTesting{
		"staging.test_customers": initCustomerTest(),
	}
	
	config := &configs.Config{
		Cores: 4,
		// ... other fields
	}
	
	// DAG graph (root assets first, then downstream)
	dagGraph := [][]string{
		{"staging.customers"},
		{"mart.summary"},
	}
	
	// Create DAG with tests enabled
	dag := dags.InitChannelDagWithTests(dagGraph, assetsMap, testsMap, config, "etl_batch_001")
	
	// Start execution
	wg := dag.Run()
	
	// Submit a task
	resultChan := make(chan map[string]interface{})
	dag.Push("task_001", map[string]interface{}{"date": "2024-01-01"}, resultChan)
	
	// Wait for completion
	go func() {
		results := <-resultChan
		// Process results
	}()
	
	// Cleanup
	dag.Stop()
	wg.Wait()
}
```

--------------------------------

### Begin Method Signature

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/drivers.md

Starts a new database transaction. Returns a driver-specific transaction object or an error if the transaction fails to start.

```go
func (driver DBDriver) Begin() (interface{}, error)
```

--------------------------------

### YAML Project Configuration Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/configs.md

An example of a project profile configuration in YAML format, demonstrating stages and models.

```yaml
version: "1.0"
name: my_etl_project
connection: analytics
models:
  stages:
    - name: staging
      models:
        - name: customers
          description: Raw customer data
          materialization: table
          connection: analytics
        - name: orders
          description: Raw order data
          materialization: table
    
    - name: dds
      models:
        - name: dim_customers
          description: Customer dimension
          materialization: table
          primary_key_fields: [customer_id]
    
    - name: mart
      models:
        - name: summary
          materialization: view
```

--------------------------------

### Full config.yaml Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/configuration.md

This example demonstrates a complete `config.yaml` file, showcasing various connection types like DuckDB and PostgreSQL with their respective configurations.

```yaml
version: "1.0"
module: github.com/myorg/myproject
cores: 4

connections:
  - name: raw_data
    type: duckdb
    config:
      path: ./data/raw.db
      extensions:
        - parquet
        - json
        - httpfs

  - name: analytics
    type: duckdb
    config:
      path: ./data/analytics.db
      extensions:
        - parquet

  - name: warehouse
    type: postgres
    config:
      host: postgres.example.com
      host_env: DB_HOST
      port: 5432
      port_env: DB_PORT
      database: warehouse
      database_env: DB_NAME
      user: etl_user
      user_env: DB_USER
      password: change_me
      password_env: DB_PASSWORD
      db_sslnmode: require
      db_sslnmode_env: DB_SSL_MODE
      db_root_cert: /etc/ssl/certs/ca-bundle.crt
      db_root_cert_env: DB_ROOT_CERT
      db_cert: /etc/ssl/certs/client.pem
      db_cert_env: DB_CLIENT_CERT
      db_key: /etc/ssl/private/client-key.pem
      db_key_env: DB_CLIENT_KEY
      pool_max_conns: 10

```

--------------------------------

### Build and Install Teal CLI with Go

Source: https://github.com/go-teal/teal/blob/main/CLAUDE.md

Directly build and install the teal CLI using Go commands.

```bash
go build -o bin/teal ./cmd/teal
go install ./cmd/teal
```

--------------------------------

### Custom Database Driver Implementation Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/drivers.md

Example of implementing the DBDriver interface for a custom database, including Connect, Begin, and GetListOfFields methods.

```go
package drivers

import "github.com/go-teal/teal/pkg/configs"

type MyDatabaseEngine struct {
	dbConnection *configs.DBConnectionConfig
	// Your database connection fields
}

// Implement all DBDriver interface methods
func (m *MyDatabaseEngine) Connect() error {
	// Establish connection using m.dbConnection
	return nil
}

func (m *MyDatabaseEngine) Begin() (interface{}, error) {
	// Start transaction
	return nil, nil
}

// ... implement remaining methods ...

func (m *MyDatabaseEngine) GetListOfFields(tx interface{}, tableName string) []string {
	// Query schema for field names
	return []string{}
}
```

--------------------------------

### Initialize and Start UI Server

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/ui-server.md

This snippet shows how to create and start the UI server with a debug DAG. Access the UI at http://localhost:8081 and the API at http://localhost:8080. Ensure necessary packages are imported.

```go
package main

import (
	"github.com/go-teal/teal/pkg/dags"
	"github.com/go-teal/teal/pkg/ui"
)

func main() {
	// Create debug DAG
	debugDag := dags.InitDebugDag(dagGraph, assetsMap, testsMap, config, "etl_batch")
	
	// Create UI server
	uiServer := ui.NewUIServer("my_project", "github.com/myorg/myproject", 8080, debugDag)
	
	// Start server (blocks)
	if err := uiServer.Start(); err != nil {
		panic(err)
	}
	
	// Access UI at http://localhost:8081
	// API at http://localhost:8080
}
```

--------------------------------

### Project directory structure example

Source: https://github.com/go-teal/teal/blob/main/README.md

After initialization, the project will have a structure similar to this. Ensure the necessary directories and configuration files are present.

```bash
total 16
drwxr-xr-x@ 6 wwtlf  wwtlf  192 24 Jun 21:23 .
drwxr-xr-x  5 wwtlf  wwtlf  160 24 Jun 21:21 ..
drwxr-xr-x@ 3 wwtlf  wwtlf   96 24 Jun 07:46 assets
-rw-r--r--@ 1 wwtlf  wwtlf  302 24 Jun 07:51 config.yaml
drwxr-xr-x@ 2 wwtlf  wwtlf   64 24 Jun 20:03 docs
-rw-r--r--@ 1 wwtlf  wwtlf  137 24 Jun 07:46 profile.yaml
```

--------------------------------

### Begin

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/drivers.md

Starts a new database transaction. Returns a driver-specific transaction object or an error if the transaction fails to start.

```APIDOC
## Begin

Starts a new database transaction.

### Method

```go
func (driver DBDriver) Begin() (interface{}, error)
```

### Description

Starts a new database transaction.

### Returns

- `interface{}` — Driver-specific transaction object (`*sql.Tx` for DuckDB, `pgx.Tx` for PostgreSQL).

### Error

Returns error if transaction start fails.

### Source

`pkg/drivers/duckdb.go:68`, `pkg/drivers/postgres.go:89`
```

--------------------------------

### Curl Example for README Endpoint

Source: https://github.com/go-teal/teal/blob/main/docs/tasks/task_5.md

Demonstrates how to use curl to access the `GET /api/docs/readme` endpoint.

```bash
curl http://localhost:8080/api/docs/readme
```

--------------------------------

### Pagination Examples for GET /api/dag/asset/:name/data

Source: https://github.com/go-teal/teal/blob/main/docs/API Specifications.md

Demonstrates various ways to paginate results when retrieving asset data. These examples show how to fetch all records, a specific number of records, or a range of records using offset and limit parameters.

```http
GET /api/dag/asset/staging.hello/data?taskId=task_123
```

```http
GET /api/dag/asset/staging.hello/data?taskId=task_123&limit=10
```

```http
GET /api/dag/asset/staging.hello/data?taskId=task_123&offset=10&limit=10
```

```http
GET /api/dag/asset/staging.hello/data?taskId=task_123&offset=100
```

--------------------------------

### Full Teal Project Configuration Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/configuration.md

A comprehensive example of a profile.yaml file, defining project metadata, connections, and a multi-stage model hierarchy with detailed settings for each model, including tests and materialization.

```yaml
version: "1.0"
name: my_etl_project
connection: analytics

models:
  stages:
    - name: staging
      models:
        - name: customers
          description: Raw customer data from CRM
          connection: raw_data
          materialization: table
          primary_key_fields: []
          indexes: []
          is_data_framed: false
          persist_inputs: false
          raw_upstreams: []
          tests:
            - name: test_customers_unique
              description: Ensure customer_id is unique
              connection: raw_data

        - name: orders
          description: Raw orders from transactional system
          materialization: incremental
          primary_key_fields: [order_id]
          indexes:
            - name: idx_order_date
              fields: [order_date]
              unique: false

    - name: dds
      models:
        - name: dim_customers
          description: Customer dimension
          materialization: table
          primary_key_fields: [customer_id]
          indexes:
            - name: uk_email
              fields: [email]
              unique: true
            - name: idx_created_date
              fields: [created_date]

    - name: mart
      models:
        - name: summary
          description: Daily customer summary
          materialization: view
```

--------------------------------

### Install Teal CLI

Source: https://github.com/go-teal/teal/blob/main/README.md

Installs the latest version of the Teal CLI using go install.

```bash
go install github.com/go-teal/teal/cmd/teal@latest
```

--------------------------------

### Start UIServer Method

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/ui-server.md

Starts the UI server's HTTP listener and registers all necessary API endpoints. Call this in a goroutine if your application needs to continue execution.

```go
func (s *UIServer) Start() error
```

--------------------------------

### AI Assistant Integration Examples

Source: https://github.com/go-teal/teal/blob/main/README.md

Demonstrates how to integrate the project's documentation (docs/README.md) with various AI code assistants like Claude, Cursor, GitHub Copilot, and Gemini Code Assist. Provides example prompts for using the documentation context.

```txt
@docs/README.md - Include this file to provide complete project context
```

```txt
@docs/README.md
```

```txt
// See docs/README.md
```

```txt
"Based on @docs/README.md, add a new mart layer asset aggregating transactions by address"
"Using @docs/README.md, which database connection should staging models use?"
"According to @docs/README.md, create an incremental model in the dds stage"
```

--------------------------------

### Start UI Assets Server in Go

Source: https://github.com/go-teal/teal/blob/main/docs/tasks/task_8.md

This Go code demonstrates how to start the UI assets server. It configures the server port based on the main UI server's port and runs the server in a separate goroutine, logging any errors.

```go
// Start UI assets server on port+1
uiAssetsPort := s.Port + 1
uiAssetsServer := services.NewUIAssetsServer(uiAssetsPort)

// Run UI assets server in a goroutine
go func() {
    if err := uiAssetsServer.Start(); err != nil {
        log.Error().Err(err).Int("port", uiAssetsPort).Msg("UI assets server failed")
    }
}()
```

--------------------------------

### Start

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/ui-server.md

Starts the UI server's HTTP listener and registers all defined API endpoints. This method should be called to make the UI dashboard accessible.

```APIDOC
## Start

### Description
Starts the HTTP server and registers all endpoints.

### Method
`func (s *UIServer) Start() error`

### Returns
- `error` — Error if server fails to start.

### Behavior
Configures Gin framework, sets up CORS, registers all API routes, and starts listening on configured port.

### Blocking
Call in a goroutine if your code needs to continue: `go server.Start()`

### Source
`pkg/ui/server.go:84`
```

--------------------------------

### Start Teal UI development server

Source: https://github.com/go-teal/teal/blob/main/README.md

Starts the UI development server for debugging and monitoring. The dashboard is accessible on port + 1.

```bash
teal ui
```

```bash
teal ui --port 9090
```

```bash
teal ui --log-level info
```

```bash
teal ui --project-path ./my-project
```

--------------------------------

### PostgreSQL Configuration Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/configuration.md

Example configuration for a PostgreSQL connection, including host, port, database name, user credentials, SSL mode, and connection pooling settings.

```yaml
config:
  host: localhost
  host_env: DB_HOST
  port: 5432
  port_env: DB_PORT
  database: warehouse
  database_env: DB_NAME
  user: etl_user
  user_env: DB_USER
  password: change_me
  password_env: DB_PASSWORD
  db_sslnmode: prefer
  db_sslnmode_env: DB_SSL_MODE
  db_root_cert: /etc/ssl/ca.pem
  db_root_cert_env: DB_ROOT_CERT
  db_cert: /etc/ssl/client.pem
  db_cert_env: DB_CLIENT_CERT
  db_key: /etc/ssl/client-key.pem
  db_key_env: DB_CLIENT_KEY
  pool_max_conns: 10
  extraParams: []
```

--------------------------------

### DuckDB Configuration Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/configs.md

Example of configuring a DuckDB connection. Specifies the database file path and DuckDB extensions to load.

```yaml
connections:
  - name: analytics
    type: duckdb
    config:
      path: ./data/analytics.db
      extensions:
        - parquet
        - json
        - httpfs

```

--------------------------------

### Example profile.yaml for Project Structure

Source: https://github.com/go-teal/teal/blob/main/README.md

Sets up project metadata, default connection, and defines model stages with nested models and tests.

```yaml
version: '1.0.0'
name: 'my-test-project'
connection: 'default'
models: 
  stages:
    - name: staging
      models:
        - name: model1
          # see model profiles
          tests:
            - name: "root.test_model1_unique"
            # see test profiles
    - name: dds  
    - name: mart
      models:
        - name: custom_asset
          materialization: 'raw'
          connection: 'default'
          raw_upstreams:
            - "dds.model1"
            - "dds.model2"
```

--------------------------------

### FromTaskContext Function Examples

Source: https://github.com/go-teal/teal/blob/main/docs/tasks/task_1.md

Examples of how to retrieve task-related information using the FromTaskContext function.

```go
{{ TaskID }} - Returns task identifier
```

```go
{{ TaskUUID }} - Returns unique task UUID
```

```go
{{ InstanceName }} - Returns DAG instance name
```

```go
{{ InstanceUUID }} - Returns DAG instance UUID
```

--------------------------------

### Example SQL with Generation-time and Runtime Template Functions

Source: https://github.com/go-teal/teal/blob/main/README.md

This example demonstrates how `Ref()` is resolved at generation time and `TaskID` is evaluated at runtime. It shows dynamic SQL generation based on model references and execution context.

```sql
-- Generation time: Ref() resolves to "staging.raw_orders"
-- Runtime: TaskID gets actual value during execution
SELECT *
FROM {{ Ref("staging.raw_orders") }}
WHERE task_id = '{{ TaskID }}'
```

--------------------------------

### DuckDB Configuration Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/configuration.md

Example configuration for a DuckDB connection, specifying the database file path, environment variable for path override, and extensions to load.

```yaml
config:
  path: ./data/analytics.db
  path_env: DB_PATH
  extensions:
    - parquet
    - json
    - httpfs
  extraParams: []
```

--------------------------------

### PostgreSQL with SSL Configuration Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/configs.md

Example of configuring a PostgreSQL connection with SSL enabled. Includes host, port, database name, user, password override, SSL mode, and certificate paths.

```yaml
connections:
  - name: warehouse
    type: postgres
    config:
      host: postgres.example.com
      port: 5432
      database: warehouse
      user: etl_user
      password_env: DB_PASSWORD      # Read from $DB_PASSWORD
      db_sslnmode: require           # Require SSL
      db_root_cert: /etc/ssl/ca.pem
      db_cert: /etc/ssl/client.pem
      db_key: /etc/ssl/client-key.pem
      pool_max_conns: 10

```

--------------------------------

### Creating and Registering a Raw Asset

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/models.md

Example of initializing a RawModelDescriptor, creating a raw asset, and registering its executor function.

```go
descriptor := &models.RawModelDescriptor{
	Name: "mart.custom_aggregation",
	Upstreams: []string{"staging.customers"},
	Downstreams: []string{},
	ModelProfile: &configs.ModelProfile{
		Name: "custom_aggregation",
		Stage: "mart",
		Connection: "analytics",
		Materialization: configs.MAT_RAW,
	},
}

asset := processing.InitRawModelAsset(descriptor)

// Register the executor function
executors := processing.GetExecutors()
executors.Execurots["mart.custom_aggregation"] = func(ctx *processing.TaskContext, profile *configs.ModelProfile) (interface{}, error) {
	// Custom logic here
	return result, nil
}
```

--------------------------------

### Logging Example with Task UUID

Source: https://github.com/go-teal/teal/blob/main/docs/API Specifications.md

This example demonstrates a structured log entry, including standardized fields like taskId and the auto-generated taskUUID for tracing.

```json
{
  "level": "debug",
  "taskId": "task_001",
  "taskUUID": "abc-123",
  "assetName": "staging.hello",
  "message": "Executing SQL select query"
}
```

--------------------------------

### Start Debug UI Server on Default Port

Source: https://github.com/go-teal/teal/blob/main/CLAUDE.md

Run the debug UI binary to start the UI server on the default port 8080.

```bash
# Start UI server on default port 8080
go run cmd/<project-name>-ui/<project-name>-ui.go
```

--------------------------------

### Custom Raw Asset Executor Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/types.md

An example demonstrating how to register a custom executor function for a specific asset. It shows accessing upstream data and returning a result.

```go
executors.Execurots["mart.custom_model"] = func(ctx *processing.TaskContext, profile *configs.ModelProfile) (interface{}, error) {
	upstreamData := ctx.Input["staging.source"]
	// Custom logic
	return result, nil
}
```

--------------------------------

### Initializing SQLModelTestDescriptor

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/models.md

Example of initializing and using an SQLModelTestDescriptor to create a SQL model test.

```go
descriptor := &models.SQLModelTestDescriptor{
	Name: "staging.test_customers_unique",
	RawSQL: "SELECT customer_id FROM staging.customers GROUP BY customer_id HAVING COUNT(*) > 1",
	CountTestSQL: "SELECT COUNT(*) FROM (SELECT customer_id FROM staging.customers GROUP BY customer_id HAVING COUNT(*) > 1) HAVING COUNT(*) > 0 LIMIT 1",
	TestProfile: &configs.TestProfile{
		Name: "test_customers_unique",
		Description: "Ensure customer_id is unique in staging",
		Connection: "analytics",
		Stage: "staging",
	},
}

test := processing.InitSQLModelTesting(descriptor)
```

--------------------------------

### Custom Database Factory Implementation

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/drivers.md

Example of a factory implementation for a custom database driver, including the CreateConnection and InitMyDatabaseFactory functions.

```go
// Factory implementation
type MyDatabaseFactory struct {}

func (f *MyDatabaseFactory) CreateConnection(config configs.DBConnectionConfig) (DBDriver, error) {
	return &MyDatabaseEngine{dbConnection: &config}, nil
}

func InitMyDatabaseFactory() DBconnectionFactory {
	return &MyDatabaseFactory{}
}
```

--------------------------------

### Start UI Server with Hot-Reload

Source: https://github.com/go-teal/teal/blob/main/README.md

Starts the UI server with automatic file watching and hot-reloading. The command monitors changes in assets, profile.yaml, and config.yaml, then regenerates Go code and restarts the API server.

```bash
# Start UI server with automatic file watching and hot-reload
teal ui

# Access the UI Dashboard at http://localhost:8081
# API server runs on http://localhost:8080
```

--------------------------------

### Start Debug UI Server on Custom Port

Source: https://github.com/go-teal/teal/blob/main/CLAUDE.md

Run the debug UI binary and specify a custom port for the UI server.

```bash
# Start on custom port
go run cmd/<project-name>-ui/<project-name>-ui.go --port 9090
```

--------------------------------

### GET /api/dag/tasks

Source: https://github.com/go-teal/teal/blob/main/docs/API Specifications.md

Retrieves a list of all task executions, sorted by start time with the most recent first.

```APIDOC
## GET /api/dag/tasks

### Description
Retrieves a list of all task executions, sorted by start time (most recent first).

### Method
GET

### Endpoint
/api/dag/tasks

### Response
#### Success Response (200 OK)
- **tasks** (array)
  - **taskId** (string)
  - **status** (string)
  - **startTime** (integer, optional)
  - **endTime** (integer, optional)
  - **totalAssets** (integer)
  - **completedAssets** (integer)
  - **failedAssets** (integer)
  - **inProgressAssets** (integer)
- **total** (integer)

#### Response Example (200 OK)
{
  "tasks": [
    {
      "taskId": "task_20250125_143022",
      "status": "SUCCESS",
      "startTime": 1737816622000,
      "endTime": 1737816625000,
      "totalAssets": 2,
      "completedAssets": 2,
      "failedAssets": 0,
      "inProgressAssets": 0
    },
    {
      "taskId": "task_20250125_142015",
      "status": "FAILED",
      "startTime": 1737816015000,
      "endTime": 1737816018000,
      "totalAssets": 2,
      "completedAssets": 1,
      "failedAssets": 1,
      "inProgressAssets": 0
    }
  ],
  "total": 2
}
```

--------------------------------

### GET /api/logs

Source: https://github.com/go-teal/teal/blob/main/docs/API Specifications.md

Retrieves all log entries for all tasks. This endpoint is available when the UI server is started with the StoringConsoleWriter logger configured.

```APIDOC
## GET /api/logs

### Description
Retrieves all log entries for all tasks.

### Method
GET

### Endpoint
/api/logs

### Response
#### Success Response (200 OK)
- **logs** (object): Map of task IDs to their respective log entries
  - Keys are task IDs
  - Values are arrays of log entry objects
- **taskCount** (integer): Number of unique tasks with logs
- **totalLogCount** (integer): Total number of log entries across all tasks

### Response Example
```json
{
  "logs": {
    "task_20250125_143022": [
      {
        "level": "info",
        "time": "2025-01-25T14:30:22Z",
        "message": "Starting DAG execution",
        "taskId": "task_20250125_143022"
      }
    ],
    "task_20250125_142015": [
      {
        "level": "error",
        "time": "2025-01-25T14:20:15Z",
        "message": "Asset execution failed",
        "taskId": "task_20250125_142015",
        "error": "Connection timeout"
      }
    ]
  },
  "taskCount": 2,
  "totalLogCount": 2
}
```
```

--------------------------------

### Establish and Use Database Connection

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/drivers.md

This snippet shows how to define connection configurations, establish a database connection using a factory, and manage transactions. It includes examples of executing DDL, checking table existence, running test queries, and performing cross-database transfers.

```go
package main

import (
	"github.com/go-teal/teal/pkg/drivers"
	"github.com/go-teal/teal/pkg/configs"
)

func main() {
	// Define connection configuration
	config := &configs.DBConnectionConfig{
		Name: "analytics",
		Type: "duckdb",
		Config: &struct{
			Path string
			// ... other fields
		}{
			Path: "./analytics.db",
		},
	}
	
	// Establish connection using factory
	driver, err := drivers.EstablishDBConnection(config)
	if err != nil {
		panic(err)
	}
	
	// Connect to database
	if err := driver.Connect(); err != nil {
		panic(err)
	}
	defer driver.Close()
	
	// Lock for concurrency control (important for DuckDB)
	driver.ConcurrencyLock()
	defer driver.ConcurrencyUnlock()
	
	// Start transaction
	tx, err := driver.Begin()
	if err != nil {
		panic(err)
	}
	
	// Execute DDL
	if err := driver.Exec(tx, "CREATE TABLE IF NOT EXISTS staging.customers AS SELECT 1"); err != nil {
		driver.Rallback(tx)
		panic(err)
	}
	
	// Check table existence
	if driver.CheckTableExists(tx, "staging.customers") {
		fields := driver.GetListOfFields(tx, "staging.customers")
		// Use field names
	}
	
	// Run a test query
	msg, testErr := driver.SimpleTest("SELECT COUNT(*) FROM staging.customers HAVING count > 0 LIMIT 1")
	if testErr != nil {
		driver.Rallback(tx)
		panic(testErr)
	}
	
	if msg != "" {
		driver.Rallback(tx)
		panic("Test failed: " + msg)
	}
	
	// Cross-database transfer using DataFrame
	df, err := driver.ToDataFrame("SELECT * FROM staging.customers")
	if err != nil {
		driver.Rallback(tx)
		panic(err)
	}
	
	// Commit changes
	if err := driver.Commit(tx); err != nil {
		panic(err)
	}
}
```

--------------------------------

### API Specification for README Endpoint

Source: https://github.com/go-teal/teal/blob/main/docs/tasks/task_5.md

Documents the `GET /api/docs/readme` endpoint, including success and error responses, and usage examples.

```markdown
## Documentation

### Get Project Documentation

**Endpoint:** `GET /api/docs/readme`

**Description:** Retrieves the project's README.md file content.

**Success Response:**

```
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8

# Project Documentation
...
```

**Error Responses:**

- **404 Not Found:** If the README path is not configured.
- **500 Internal Server Error:** If there is an error reading the file.
```

--------------------------------

### Run Method

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/dags.md

Starts all asset routines and returns a sync.WaitGroup for synchronization. The caller should use Wait() to block until all assets complete.

```APIDOC
## Method Run

Starts all asset routines and returns a `sync.WaitGroup` for synchronization.

### Signature

```go
func (dag DAG) Run() *sync.WaitGroup
```

### Returns

- `*sync.WaitGroup` — Synchronization primitive for waiting on all goroutines. Caller should call `Wait()` to block until all assets complete.

### Example

```go
wg := dag.Run()
wg.Wait()
```
```

--------------------------------

### GET /api/logs/:taskId

Source: https://github.com/go-teal/teal/blob/main/docs/API Specifications.md

Retrieves all log entries for a specific task. This endpoint is available when the UI server is started with the StoringConsoleWriter logger configured.

```APIDOC
## GET /api/logs/:taskId

### Description
Retrieves all log entries for a specific task.

### Method
GET

### Endpoint
/api/logs/:taskId

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The task ID to retrieve logs for

### Response
#### Success Response (200 OK)
- **taskId** (string): The task ID requested
- **logs** (array): Array of log entry objects with varying fields based on log content
  - Common fields include: `level`, `time`, `message`, `taskId`
  - Additional fields vary based on the specific log entry
- **count** (integer): Total number of log entries for this task

### Response Example
```json
{
  "taskId": "task_20250125_143022",
  "logs": [
    {
      "level": "info",
      "time": "2025-01-25T14:30:22Z",
      "message": "Starting DAG execution",
      "taskId": "task_20250125_143022",
      "stage": "initialization"
    },
    {
      "level": "debug",
      "time": "2025-01-25T14:30:23Z",
      "message": "Executing SQL select query",
      "taskId": "task_20250125_143022",
      "taskUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "assetName": "staging.hello",
      "connection": "memory_duck"
    }
  ],
  "count": 2
}
```

#### Error Response (501 Not Implemented)
```json
{
  "error": "Log writer not configured"
}
```
```

--------------------------------

### Typical Core Lifecycle Example

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/core.md

Demonstrates the typical lifecycle of the Core service in a Go application, including initialization, connection, usage, and shutdown.

```go
func main() {
	// Get singleton
	core := core.GetInstance()
	
	// Initialize configuration
	core.Init("config.yaml", ".")
	
	// Connect to all databases
	core.ConnectAll()
	defer core.Shutdown()
	
	// Get a connection for use in asset execution
	dbDriver := core.GetDBConnection("analytics")
	
	// Use driver for queries
	tx, _ := dbDriver.Begin()
	// ... execute asset logic ...
	dbDriver.Commit(tx)
}
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/go-teal/teal/blob/main/CLAUDE.md

Illustrates various commit message types and scopes for feature additions, bug fixes, documentation, refactoring, and chores. Use these as guides for your commits.

```bash
# Feature additions
feat(cli): add comprehensive help system for all commands
feat(drivers): add MySQL database driver support
feat(ui): add real-time log streaming to dashboard

# Bug fixes
fix(dag): resolve deadlock in channel-based execution
fix(postgres): handle SSL certificate validation errors
fix(gen): correct template rendering for pointer fields

# Documentation
docs(readme): add CLI commands reference section
docs(api): document test execution endpoints

# Refactoring
refactor(drivers): extract common DataFrame operations
refactor(templates): migrate from text/template to pongo2

# Chores
chore: update dependencies to latest versions
chore(release): bump version to v1.0.2

# Multiple scopes
feat(cli,docs): enhance help system and update documentation
```

--------------------------------

### Get All Task Logs

Source: https://github.com/go-teal/teal/blob/main/docs/API Specifications.md

Retrieves all log entries for all tasks. The response is a map where keys are task IDs and values are arrays of log entries. This endpoint is available when the UI server is started with the StoringConsoleWriter logger configured.

```json
{
  "logs": {
    "task_20250125_143022": [
      {
        "level": "info",
        "time": "2025-01-25T14:30:22Z",
        "message": "Starting DAG execution",
        "taskId": "task_20250125_143022"
      }
    ],
    "task_20250125_142015": [
      {
        "level": "error",
        "time": "2025-01-25T14:20:15Z",
        "message": "Asset execution failed",
        "taskId": "task_20250125_142015",
        "error": "Connection timeout"
      }
    ]
  },
  "taskCount": 2,
  "totalLogCount": 2
}
```

--------------------------------

### Safe Configuration Loading with Panic Recovery

Source: https://github.com/go-teal/teal/blob/main/_autodocs/errors.md

This Go snippet demonstrates how to safely load configuration and initialize core components. It uses `defer` and `recover` to catch panics during initialization, logging a fatal error if recovery is needed. This pattern is crucial for ensuring the application cannot proceed in an uninitialized or unsafe state.

```Go
func main() {
    defer func() {
        if r := recover(); r != nil {
            log.Fatal("Initialization failed:", r)
        }
    }()
    
    core := core.GetInstance()
    core.Init("config.yaml", ".")
    core.ConnectAll()
    
    // If we reach here, everything is initialized safely
}
```

--------------------------------

### Get Task Logs

Source: https://github.com/go-teal/teal/blob/main/docs/API Specifications.md

Retrieves all log entries for a specific task ID. This endpoint requires the UI server to be started with the StoringConsoleWriter logger configured. The response includes log details such as level, time, and message.

```json
{
  "taskId": "task_20250125_143022",
  "logs": [
    {
      "level": "info",
      "time": "2025-01-25T14:30:22Z",
      "message": "Starting DAG execution",
      "taskId": "task_20250125_143022",
      "stage": "initialization"
    },
    {
      "level": "debug",
      "time": "2025-01-25T14:30:23Z",
      "message": "Executing SQL select query",
      "taskId": "task_20250125_143022",
      "taskUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "assetName": "staging.hello",
      "connection": "memory_duck"
    }
  ],
  "count": 2
}
```

--------------------------------

### Install Teal CLI Globally

Source: https://github.com/go-teal/teal/blob/main/CLAUDE.md

Installs the teal CLI tool globally on your system.

```bash
make install
```

--------------------------------

### Go: Execute SQL Model Asset and Run Tests

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/processing.md

This snippet demonstrates how to initialize and execute a SQL model asset, including defining its schema, dependencies, and profile. It also shows how to set up and run tests against the executed model.

```go
package main

import (
	"github.com/go-teal/teal/pkg/processing"
	"github.com/go-teal/teal/pkg/models"
	"github.com/go-teal/teal/pkg/configs"
)

func main() {
	// Create and execute a SQL asset
	sqlDescriptor := &models.SQLModelDescriptor{
		Name: "staging.customers",
		CreateTableSQL: "CREATE TABLE staging.customers AS SELECT * FROM raw.customers",
		Upstreams: []string{},
		Downstreams: []string{"mart.customer_summary"},
		ModelProfile: &configs.ModelProfile{
			Name: "customers",
			Stage: "staging",
			Connection: "analytics",
			Materialization: configs.MAT_TABLE,
		},
	}
	
	asset := processing.InitSQLModelAsset(sqlDescriptor)
	
	// Create task context
	ctx := &processing.TaskContext{
		TaskID: "task_001",
		TaskUUID: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
		InstanceName: "etl_batch",
		InstanceUUID: "a1b2c3d4-e5f6-7890-1234-567890abcdef",
		Input: make(map[string]interface{}),
	}
	
	// Execute asset
	result, err := asset.Execute(ctx)
	if err != nil {
		panic(err)
	}
	
	// Create and run tests
	testDescriptor := &models.SQLModelTestDescriptor{
		Name: "staging.test_customers_unique",
		RawSQL: "SELECT customer_id FROM staging.customers GROUP BY customer_id HAVING COUNT(*) > 1",
		TestProfile: &configs.TestProfile{
			Name: "test_customers_unique",
			Stage: "staging",
			Connection: "analytics",
		},
	}
	
	test := processing.InitSQLModelTesting(testDescriptor)
	testsMap := map[string]processing.ModelTesting{
		"staging.test_customers_unique": test,
	}
	
	testResults := asset.RunTests(ctx, testsMap)
	for _, result := range testResults {
		if result.Status == processing.TestStatusFailed {
			println("Test failed:", result.TestName, result.Message)
		}
	}
	
	// Register raw asset executor
	executors := processing.GetExecutors()
	executors.Execurots["mart.custom_aggregation"] = func(taskCtx *processing.TaskContext, profile *configs.ModelProfile) (interface{}, error) {
		// Custom Python/Go logic
		// Access upstream data: taskCtx.Input["staging.customers"]
		return customResult, nil
	}
	
	// Create raw asset
	rawDescriptor := &models.RawModelDescriptor{
		Name: "mart.custom_aggregation",
		Upstreams: []string{"staging.customers"},
		Downstreams: []string{},
		ModelProfile: &configs.ModelProfile{
			Name: "custom_aggregation",
			Stage: "mart",
			Connection: "analytics",
		},
	}
	
	rawAsset := processing.InitRawModelAsset(rawDescriptor)
	rawResult, err := rawAsset.Execute(ctx)
}
```

--------------------------------

### Build and Run Production Binary

Source: https://github.com/go-teal/teal/blob/main/CLAUDE.md

Build the Go Teal project into a production binary and then execute it with a specified log level.

```bash
# Build and run production binary
go build -o bin/<project-name> cmd/<project-name>/<project-name>.go
./bin/<project-name> --log-level info
```

--------------------------------

### Initialize New Teal Project

Source: https://github.com/go-teal/teal/blob/main/CLAUDE.md

Initializes a new project using the teal CLI.

```bash
teal init
```

--------------------------------

### Update Server Initialization in Template

Source: https://github.com/go-teal/teal/blob/main/docs/tasks/task_5.md

Sets the `readmePath` to "./docs/README.md" and uses the new constructor during server initialization in the main UI template.

```go
server := NewUIServerWithLogWriterAndReadme(
			log.New(os.Stdout, "", log.LstdFlags),
			"./docs/README.md",
			// ... other params
		)
```

--------------------------------

### GET /api/dag/tasks Response Structure

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/ui-server.md

Lists all executed tasks with their respective statuses and execution times. This is the response for the GET /api/dag/tasks endpoint.

```json
{
  "tasks": [
    {
      "taskId": "task_001",
      "status": "SUCCESS",
      "startTime": 1704110400000,
      "endTime": 1704110420000
    },
    {
      "taskId": "task_002",
      "status": "FAILED",
      "startTime": 1704110420000,
      "endTime": 1704110425000
    }
  ]
}
```

--------------------------------

### NewUIServer Constructor

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/ui-server.md

Creates a basic UI server instance. Use this when log writing and readme documentation are not immediately required.

```go
func NewUIServer(projectName, moduleName string, port int, dag *dags.DebugDag) *UIServer
```

--------------------------------

### Build Production Binary with Go

Source: https://github.com/go-teal/teal/blob/main/README.md

Compile the production binary using `go build`. Ensure the output path is `bin/my-test-project`. Make the binary executable on Unix-like systems.

```bash
# Build the production binary
go build -o bin/my-test-project ./cmd/my-test-project/my-test-project.go

# Make it executable (Unix/Linux/Mac)
chmod +x bin/my-test-project
```

--------------------------------

### Handle Missing Configuration File

Source: https://github.com/go-teal/teal/blob/main/_autodocs/errors.md

Verify configuration files exist before initializing the core. This prevents panics due to missing 'config.yaml' or 'profile.yaml'.

```go
func main() {
    // Verify files exist before Core initialization
    if _, err := os.Stat("config.yaml"); os.IsNotExist(err) {
        log.Fatal("config.yaml not found")
    }
    
    core := core.GetInstance()
    core.Init("config.yaml", ".")
}
```

--------------------------------

### Teal Configuration Service Usage

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/configs.md

Demonstrates how to initialize the Teal configuration service, load configuration from a YAML file, and access project profiles. Includes loading project details, connection information, and specific model/test profiles.

```go
package main

import (
	"github.com/go-teal/teal/pkg/configs"
)

func main() {
	// Initialize config service
	cs := configs.InitConfigService()
	
	// Load configuration from YAML
	config, err := cs.GetConfig("./config.yaml", ".")
	if err != nil {
		panic(err)
	}
	
	println("Version:", config.Version)
	println("Module:", config.Module)
	println("Cores:", config.Cores)
	println("Connections:", len(config.Connections))
	
	// Print all connection names
	for _, conn := range config.Connections {
		println("  -", conn.Name, "(" + conn.Type + ")")
	}
	
	// Load project profile
	profile, err := cs.GetProfileProfile(".")
	if err != nil {
		panic(err)
	}
	
	println("Project:", profile.Name)
	println("Default connection:", profile.Connection)
	
	// Convert profile to flat map
	modelMap := profile.ToMap()
	for modelName := range modelMap {
		println("  -", modelName)
	}
	
	// Access specific model
	custModel := profile.GetModelProfile("staging", "customers")
	println("Customer model connection:", custModel.Connection)
	println("Customer model materialization:", custModel.Materialization)
	
	// Access test profile
	testProf := profile.GetTestProfile("staging", "test_customers")
	println("Test:", testProf.Name, "on connection", testProf.Connection)
}
```

--------------------------------

### Go Teal Core Initialization and Database Operations

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/core.md

This Go snippet demonstrates how to initialize the Teal core, establish database connections, execute SQL queries within a transaction, and perform basic checks. It includes error handling and transaction management.

```go
package main

import (
	"github.com/go-teal/teal/pkg/core"
	"github.com/go-teal/teal/pkg/processing"
)

func main() {
	// Get singleton Core instance
	c := core.GetInstance()
	
	// Load configuration from files
	c.Init("config.yaml", ".")
	
	// Establish all database connections
	c.ConnectAll()
	defer c.Shutdown()
	
	// Retrieve a specific database connection
	analytics := c.GetDBConnection("analytics")
	
	// Example: Execute a query in an asset
	analytics.ConcurrencyLock()
	defer analytics.ConcurrencyUnlock()
	
tx, err := analytics.Begin()
	if err != nil {
		panic(err)
	}
	
	// Create table
	err = analytics.Exec(tx, "CREATE TABLE staging.customers AS SELECT * FROM raw_data")
	if err != nil {
		analytics.Rallback(tx)
		panic(err)
	}
	
	// Check if schema exists
	if !analytics.CheckSchemaExists(tx, "staging.customers") {
		analytics.Rallback(tx)
		panic("Schema not created")
	}
	
	// Run a test query
	msg, err := analytics.SimpleTest("SELECT COUNT(*) FROM staging.customers WHERE customer_id IS NULL HAVING count > 0 LIMIT 1")
	if err != nil {
		analytics.Rallback(tx)
		panic(err)
	}
	
	if msg != "" {
		analytics.Rallback(tx)
		panic("Test failed: " + msg)
	}
	
	// Commit
	err = analytics.Commit(tx)
	if err != nil {
		panic(err)
	}
	
	// Access project profile
	for stage, models := range c.Profile.ToMap() {
		println("Model:", stage, "uses connection:", models.Connection)
	}
	
	// Access core config
	println("Total cores for parallelism:", c.Config.Cores)
}
```

--------------------------------

### Init

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/core.md

Loads configuration from YAML files (config.yaml and profile.yaml) based on the provided file names and project path. Panics if files are not found or YAML is invalid.

```APIDOC
## Init

### Description
Loads configuration from YAML files. It expects paths to `config.yaml` and `profile.yaml`.

### Method
`Init(configFileName string, projectPath string)`

### Parameters
#### Path Parameters
- **configFileName** (string) - Required - Path to config.yaml. Example: "config.yaml" or "./config.yaml"
- **projectPath** (string) - Required - Project directory containing profile.yaml. Example: "."

### Behavior
- Uses ConfigService to load configuration.
- Panics if files are not found or YAML is invalid (fail-fast).
- Sets Core.Config and Core.Profile.
- Does NOT establish database connections.
```

--------------------------------

### GET /api/dag Response Structure

Source: https://github.com/go-teal/teal/blob/main/_autodocs/api-reference/ui-server.md

Represents the structure of a DAG, including all nodes and their current execution state. This is returned when querying the GET /api/dag endpoint.

```json
{
  "projectName": "my_etl",
  "moduleName": "github.com/myorg/myproject",
  "dagInstanceName": "etl_batch_001",
  "nodes": [
    {
      "name": "staging.customers",
      "description": "Raw customer data",
      "upstreams": [],
      "downstreams": ["mart.summary"],
      "sqlSelectQuery": "SELECT customer_id, name FROM raw_data.customers",
      "sqlCompiledQuery": "CREATE TABLE staging.customers AS SELECT customer_id, name FROM raw_data.customers",
      "materialization": "table",
      "connectionType": "duckdb",
      "connectionName": "analytics",
      "isDataFramed": false,
      "persistInputs": false,
      "tests": ["staging.test_customers_unique"],
      "state": "INITIAL",
      "totalTests": 1,
      "successfulTests": 0,
      "lastExecutionDuration": 0,
      "lastTestsDuration": 0,
      "TaskGroupIndex": 0
    }
  ]
}
```

--------------------------------

### Start Teal Debug UI with Custom Port

Source: https://github.com/go-teal/teal/blob/main/README.md

Starts the Teal debug UI server on a specified port. The UI Dashboard will be available on the next port.

```bash
teal ui --port 8080 --log-level debug
```