### Run Knex Server Example

Source: https://github.com/google/sqlcommenter/blob/master/nodejs/sqlcommenter-nodejs/samples/express-opentelemetry/README.md

Start the Knex server example. This command initiates the Express application using Knex for database interactions.

```bash
$ npm run knexServer
```

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

### Install go-sql-driver

Source: https://github.com/google/sqlcommenter/blob/master/go/gorrila/mux/README.md

Use go get to install the SQLCommenter middleware for gorilla/mux.

```shell
go get -u github.com/google/sqlcommenter/go/gorrila/mux
```

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

### Run Sequelize Server Example

Source: https://github.com/google/sqlcommenter/blob/master/nodejs/sqlcommenter-nodejs/samples/express-opentelemetry/README.md

Start the Sequelize server example. This command initiates the Express application using Sequelize for database interactions.

```bash
$ npm run sequelizeServer
```

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

### Install go-sql-driver

Source: https://github.com/google/sqlcommenter/blob/master/go/database/sql/README.md

Use 'go get' to install the go-sql-driver for SQLCommenter. This command fetches the latest version of the package.

```shell
go get -u github.com/google/sqlcommenter/go/database/sql
```

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

### Basic Knex.js setup with SQLCommenter

Source: https://context7.com/google/sqlcommenter/llms.txt

Set up Knex.js with SQLCommenter by wrapping the main Knex instance. Specify which fields like `db_driver`, `traceparent`, and `tracestate` to include in the SQL comments. Requires `npm install @google-cloud/sqlcommenter-knex`.

```javascript
const Knex = require('knex');
const { wrapMainKnex } = require('@google-cloud/sqlcommenter-knex');

const knex = Knex({
    client: 'pg',
    connection: {
        host: 'localhost',
        user: 'user',
        password: 'pass',
        database: 'mydb'
    }
});

// Wrap Knex with SQLCommenter - specify which fields to include
wrapMainKnex(Knex, {
    db_driver: true,
    traceparent: true,
    tracestate: true,
}, {
    TraceProvider: 'OpenTelemetry'  // or 'OpenCensus'
});

// Execute queries - comments are automatically added
const users = await knex('users').where('id', 1).select('*');

// Resulting SQL in database logs:
// SELECT * FROM users WHERE id = 1
// /*db_driver='knex:2.5.0',traceparent='00-abc123-def456-01'*/
```

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

### Install Dependencies

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/sqlcommenter_rails/README.md

Run this command to install the necessary dependencies for the project.

```bash
bin/setup
```

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

### Go Database/SQL Driver Wrapper

Source: https://context7.com/google/sqlcommenter/llms.txt

Provides a drop-in replacement for sql.Open that instruments SQL queries with comments. Use context-based methods for full instrumentation. Installation: go get -u github.com/google/sqlcommenter/go/database/sql.

```go
package main

import (
    "context"
    "log"

    gosql "github.com/google/sqlcommenter/go/database/sql"
    sqlcommentercore "github.com/google/sqlcommenter/go/core"
    _ "github.com/lib/pq" // PostgreSQL driver
)

func main() {
    // Open database connection with SQLCommenter wrapper
    db, err := gosql.Open("postgres", "postgres://user:pass@localhost/mydb",
        sqlcommentercore.CommenterOptions{
            Config: sqlcommentercore.CommenterConfig{
                EnableDBDriver:    true,  // Include database driver name
                EnableTraceparent: true,  // Include OpenTelemetry trace context
                EnableRoute:       true,  // Include route (when used with web framework)
                EnableFramework:   true,  // Include framework name
                EnableController:  true,  // Include controller/handler name
                EnableAction:      true,  // Include action name
                EnableApplication: true,  // Include application name
            },
            Tags: sqlcommentercore.StaticTags{
                Application: "my-app",      // Optional: override application name
                DriverName:  "postgresql",  // Optional: override driver name
            },
        },
    )
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // Use context-based methods for full instrumentation
    ctx := context.Background()

    rows, err := db.QueryContext(ctx, "SELECT * FROM users WHERE id = $1", 1)
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    // Process results...
}

// Installation: go get -u github.com/google/sqlcommenter/go/database/sql

// Resulting SQL in database logs:
// SELECT * FROM users WHERE id = $1
// /*application='my-app',db_driver='postgres',traceparent='00-abc123-def456-01'*/
```

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

### Install Dependencies and Run Postgres Sample

Source: https://github.com/google/sqlcommenter/blob/master/python/samples/README.md

Follow these steps to set up your virtual environment, install required packages, and run the Python sample with a Postgres DSN.

```bash
# Create virtualenv and install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run with Postgres DSN environment variable
export POSTGRES_DSN="postgresql://<user>:<pass>@<dbname>?host=<host>"
python psycopgy_opentelemetry_sample.py 
```

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

### Install SQLCommenter

Source: https://github.com/google/sqlcommenter/blob/master/python/sqlcommenter-python/README.md

Install the base SQLCommenter package using pip. For trace context, install with the desired integration.

```shell
pip3 install --user google-cloud-sqlcommenter
```

```shell
pip3 install google-cloud-sqlcommenter[opencensus]
```

```shell
pip3 install google-cloud-sqlcommenter[opentelemetry]
```

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

### Install gem manually

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/marginalia-opencensus/README.md

Alternatively, you can install the gem directly using the gem install command.

```bash
$ gem install marginalia-opencensus
```

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

### Start test application server

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/marginalia-opencensus/README.md

Run this command to start a web server with the embedded test application for development or debugging.

```bash
bin/rails s
```

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

### Install SQLCommenter http-net

Source: https://github.com/google/sqlcommenter/blob/master/go/net/http/README.md

Use this command to install the SQLCommenter http-net package for Go.

```bash
go get -u github.com/google/sqlcommenter/go/net/http
```

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

### Install Dependencies with Composer

Source: https://github.com/google/sqlcommenter/blob/master/php/sqlcommenter-php/samples/sqlcommenter-laravel/README.md

Use this command to install the necessary PHP packages for the project.

```shell
composer install
```

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

### Install SQLCommenter for Sequelize

Source: https://github.com/google/sqlcommenter/blob/master/nodejs/sqlcommenter-nodejs/packages/sqlcommenter-sequelize/README.md

Install the SQLCommenter Sequelize plugin using npm.

```shell
npm install @google-cloud/sqlcommenter-sequelize
```

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

### Express middleware setup for Knex.js with SQLCommenter

Source: https://context7.com/google/sqlcommenter/llms.txt

Integrate SQLCommenter with Express.js and Knex.js using the `wrapMainKnexAsMiddleware` function. This captures route context to be appended to SQL queries. Ensure `@google-cloud/sqlcommenter-knex` is installed.

```javascript
const express = require('express');
const Knex = require('knex');
const { wrapMainKnexAsMiddleware } = require('@google-cloud/sqlcommenter-knex');

const app = express();
const knex = Knex({ client: 'pg', connection: '...' });

// Use as Express middleware to capture route information
app.use(wrapMainKnexAsMiddleware(Knex, {
    db_driver: true,
    route: true,
    traceparent: true,
}, {
    TraceProvider: 'OpenTelemetry'
}));

app.get('/users/:id', async (req, res) => {
    const user = await knex('users').where('id', req.params.id).first();
    res.json(user);
});

// Installation: npm install @google-cloud/sqlcommenter-knex

// Resulting SQL with Express middleware:
// SELECT * FROM users WHERE id = 1
// /*db_driver='knex:2.5.0',route='/users/:id',traceparent='00-abc123-def456-01'*/
```

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

### Go - Gorilla Mux Middleware Setup

Source: https://context7.com/google/sqlcommenter/llms.txt

Set up the SQLCommenter middleware for Gorilla Mux. Ensure OpenTelemetry middleware is applied before SQLCommenter for trace context propagation.

```go
package main

import (
    "context"
    "encoding/json"
    "log"
    "net/http"

    gosql "github.com/google/sqlcommenter/go/database/sql"
    sqlcommentercore "github.com/google/sqlcommenter/go/core"
    sqlcommentermux "github.com/google/sqlcommenter/go/gorrila/mux"
    "github.com/gorilla/mux"
    "go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/propagation"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    _ "github.com/lib/pq"
)

var db *sql.DB

func main() {
    // Initialize OpenTelemetry tracer
    tp := initTracer()
    defer tp.Shutdown(context.Background())

    // Initialize database with SQLCommenter
    var err error
    db, err = gosql.Open("postgres", "postgres://user:pass@localhost/mydb",
        sqlcommentercore.CommenterOptions{
            Config: sqlcommentercore.CommenterConfig{
                EnableDBDriver:    true,
                EnableTraceparent: true,
                EnableRoute:       true,
                EnableFramework:   true,
                EnableAction:      true,
            },
        },
    )
    if err != nil {
        log.Fatal(err)
    }

    // Setup router with SQLCommenter and OpenTelemetry middleware
    r := mux.NewRouter()
    r.Use(otelmux.Middleware("my-service"))       // OpenTelemetry first
    r.Use(sqlcommentermux.SQLCommenterMiddleware) // SQLCommenter second

    r.HandleFunc("/users/{id}", GetUser).Methods("GET")
    r.HandleFunc("/users", CreateUser).Methods("POST")

    log.Println("Server starting on :8080")
    http.ListenAndServe(":8080", r)
}

func GetUser(w http.ResponseWriter, r *http.Request) {
    vars := mux.Vars(r)
    id := vars["id"]

    // Pass request context to database query for full instrumentation
    row := db.QueryRowContext(r.Context(), "SELECT * FROM users WHERE id = $1", id)
    // Process result...
    json.NewEncoder(w).Encode(map[string]string{"id": id})
}

func initTracer() *sdktrace.TracerProvider {
    tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.AlwaysSample()))
    otel.SetTracerProvider(tp)
    otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
        propagation.TraceContext{}, propagation.Baggage{}))
    return tp
}

// Installation:
// go get -u github.com/google/sqlcommenter/go/gorrila/mux
// go get -u github.com/google/sqlcommenter/go/database/sql

// Resulting SQL in database logs:
// SELECT * FROM users WHERE id = $1
// /*action='main.GetUser',db_driver='postgres',framework='gorilla/mux',
// route='/users/{id}',traceparent='00-5bd66ef5095369c7b0d1f8f4bd33716a-c532cb4098ac3dd2-01'*/
```

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

### Install SQLCommenter Knex

Source: https://github.com/google/sqlcommenter/blob/master/nodejs/sqlcommenter-nodejs/packages/sqlcommenter-knex/README.md

Install the SQLCommenter Knex package using npm. This package is compatible with Node.js v6 and above.

```shell
npm install @google-cloud/sqlcommenter-knex
```

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

### Install gem dependencies

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/marginalia-opencensus/README.md

Execute this command in your terminal after updating your Gemfile to install the gem and its dependencies.

```bash
$ bundle
```

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

### Example SQL Log Output

Source: https://github.com/google/sqlcommenter/blob/master/java/sqlcommenter-java/README.md

Demonstrates how SQL queries appear in logs with SQLCommenter annotations, including action, controller, framework, and trace information.

```shell
SELECT * from USERS /*action='run+this+%26+that',
controller='foo%3BDROP+TABLE+BAR',framework='spring,
traceparent='00-9a4589fe88dd0fc911ff2233ffee7899-11fa8b00dd11eeff-01',
tracestate='rojo%253D00f067aa0ba902b7%2Ccongo%253Dt61rcWkgMzE''*/
```

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

### Build and Run Docker Compose

Source: https://github.com/google/sqlcommenter/blob/master/go/samples/http/README.md

Builds the Docker images and starts the application server along with MySQL and Postgres databases. The application defaults to connecting with Postgres.

```sh
docker compose build
docker compose up
```

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

### Django Query Log Example

Source: https://github.com/google/sqlcommenter/blob/master/python/sqlcommenter-python/README.md

Example of a SQL query log with SQLCommenter enabled for Django, showing added comment with controller, framework, and route information.

```shell
2019-05-28 11:54:50.780 PDT [64128] LOG:  statement: INSERT INTO "polls_question"
("question_text", "pub_date") VALUES
('Wassup?', '2019-05-28T18:54:50.767481+00:00'::timestamptz) RETURNING 
"polls_question"."id" /*controller='index',framework='django%3A2.2.1',route='%5Epolls/%24'*/
```

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

### Run Laravel Development Server

Source: https://github.com/google/sqlcommenter/blob/master/php/sqlcommenter-php/samples/sqlcommenter-laravel/README.md

Start the built-in PHP development server to run the application locally.

```shell
php artisan serve
```

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

### Install and Configure SQLCommenter for Laravel

Source: https://context7.com/google/sqlcommenter/llms.txt

Follow these steps to install the SQLCommenter Laravel package, publish its configuration, register the service provider, and configure options for adding SQL comments.

```php
// Step 1: Install via Composer
// composer require "google/sqlcommenter-laravel"

// Step 2: Publish the configuration file
// php artisan vendor:publish --provider="Google\GoogleSqlCommenterLaravel\GoogleSqlCommenterServiceProvider"

// Step 3: Register the service provider in config/app.php
// Add BEFORE Illuminate\Database\DatabaseServiceProvider::class

'providers' => [
    // ... other providers

    Google\GoogleSqlCommenterLaravel\Database\DatabaseServiceProvider::class,
    Illuminate\Database\DatabaseServiceProvider::class,

    // ... other providers
],

// Step 4: Configure options in config/google_sqlcommenter.php
return [
    'action' => true,        // Include controller action name
    'controller' => true,    // Include controller class name
    'db_driver' => true,     // Include database driver (mysql, pgsql, etc.)
    'framework' => true,     // Include "laravel" and version
    'route' => true,         // Include URL route pattern
    'traceparent' => true,   // Include OpenTelemetry traceparent
];
```

```php
// Example Controller (app/Http/Controllers/UserController.php)
namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function show($id)
    {
        // Query is automatically instrumented
        $user = User::find($id);
        return response()->json($user);
    }

    public function index()
    {
        $users = User::where('active', true)->get();
        return response()->json($users);
    }
}
```

```php
// routes/api.php
Route::get('/users/{id}', [UserController::class, 'show']);
Route::get('/users', [UserController::class, 'index']);
```

```sql
// Resulting SQL in database logs:
// SELECT * FROM `users` WHERE `id` = ?
// /*action='show',controller='UserController',db_driver='mysql',
// framework='laravel:10.0.0',route='/api/users/{id}',
// traceparent='00-5bd66ef5095369c7b0d1f8f4bd33716a-c532cb4098ac3dd2-01'*/
```

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

### Psycopg2 Query Log Example

Source: https://github.com/google/sqlcommenter/blob/master/python/sqlcommenter-python/README.md

Example of a SQL query log with SQLCommenter enabled for Psycopg2, showing extensive details including driver version, DBAPI level, thread safety, parameter style, libpq version, and trace information.

```shell
2019-05-28 02:33:25.287 PDT [57302] LOG:  statement: SELECT * FROM
polls_question /*db_driver='psycopg2%%3A2.8.2%%20(dt%%20dec%%20pq3%%20ext%%20lo64%%29',
dbapi_level='2.0',dbapi_threadsafety=2,driver_paramstyle='pyformat',
libpq_version=100001,traceparent='00-5bd66ef5095369c7b0d1f8f4bd33716a-c532cb4098ac3dd2-01',
tracestate='congo%%3Dt61rcWkgMzE%%2Crojo%%3D00f067aa0ba902b7'*/
```

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

### Create Post with SQL Comments

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/sqlcommenter_rails_demo/README.md

Example of creating a post using curl. The output shows the SQL query with added comments by SQLCommenter.

```bash
curl -X POST localhost:3000/posts -d 'title=my-post'
```

```sql
Post Create (0.2ms)  INSERT INTO "posts" ("title", "created_at", "updated_at") VALUES (?, ?, ?) /*action='create',application='SqlcommenterRailsDemo',controller='posts',db_driver='ActiveRecord::ConnectionAdapters::SQLite3Adapter',framework='rails_v6.0.0.rc1',route='/posts',traceparent='00-ff19308b1f17fedc5864e929bed1f44e-6ddace73a9debf63-01'*/  [["title", "my-post"], ["created_at", "2019-06-08 15:47:59.089692"], ["updated_at", "2019-06-08 15:47:59.089692"]]
```

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

### SQLAlchemy Query Log Example

Source: https://github.com/google/sqlcommenter/blob/master/python/sqlcommenter-python/README.md

Example of a SQL query log with SQLCommenter enabled for SQLAlchemy, showing added comment with database driver, framework, and trace information.

```shell
2019-05-28 11:52:06.527 PDT [64087] LOG:  statement: SELECT * FROM polls_question
/*db_driver='psycopg2',framework='sqlalchemy%3A1.3.4',
traceparent='00-5bd66ef5095369c7b0d1f8f4bd33716a-c532cb4098ac3dd2-01',
tracestate='congo%%3Dt61rcWkgMzE%%2Crojo%%3D00f067aa0ba902b7'*/
```

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

### Fetch Posts with SQL Comments

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/sqlcommenter_rails_demo/README.md

Example of fetching posts using curl. The output shows the SQL query with added comments by SQLCommenter.

```bash
curl localhost:3000/posts
```

```sql
Post Load (0.1ms)  SELECT "posts".* FROM "posts" /*action='index',application='SqlcommenterRailsDemo',controller='posts',db_driver='ActiveRecord::ConnectionAdapters::SQLite3Adapter',framework='rails_v6.0.0.rc1',route='/posts',traceparent='00-828f28f7fb3df3dd07ee6478b2016b2a-a52cad0a8d1425ab-01'*/
```

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

### Install Sqlcommenter-laravel using Composer

Source: https://github.com/google/sqlcommenter/blob/master/php/sqlcommenter-php/packages/sqlcommenter-laravel/README.md

Use this command to add the Sqlcommenter-laravel package to your project via Composer.

```shell
composer require "google/sqlcommenter-laravel"
```

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

### Node.js Sequelize Integration

Source: https://context7.com/google/sqlcommenter/llms.txt

Wraps Sequelize query execution to append SQL comments. Use the Express middleware for route context. Installation: npm install @google-cloud/sqlcommenter-sequelize.

```javascript
// Basic Sequelize setup
const { Sequelize, DataTypes } = require('sequelize');
const { wrapSequelize } = require('@google-cloud/sqlcommenter-sequelize');

const sequelize = new Sequelize('postgres://user:pass@localhost:5432/mydb');

// Wrap Sequelize with SQLCommenter
wrapSequelize(sequelize, {
    db_driver: true,
    client_timezone: true,
    traceparent: true,
    tracestate: true,
}, {
    TraceProvider: 'OpenTelemetry'  // or 'OpenCensus'
});

// Define a model
const User = sequelize.define('User', {
    name: DataTypes.STRING,
    email: DataTypes.STRING
});

// Execute queries - comments are automatically added
const users = await User.findAll({ where: { id: 1 } });

// Resulting SQL in database logs:
// SELECT * FROM "Users" WHERE "id" = 1
// /*client_timezone='UTC',db_driver='sequelize:6.32.0',traceparent='00-abc123-def456-01'*/
```

```javascript
// Express middleware setup for route context
const express = require('express');
const { Sequelize } = require('sequelize');
const { wrapSequelizeAsMiddleware } = require('@google-cloud/sqlcommenter-sequelize');

const app = express();
const sequelize = new Sequelize('postgres://user:pass@localhost:5432/mydb');

// Use as Express middleware to capture route information
app.use(wrapSequelizeAsMiddleware(sequelize, {
    db_driver: true,
    route: true,
    traceparent: true,
}, {
    TraceProvider: 'OpenTelemetry'
}));

app.get('/users/:id', async (req, res) => {
    const user = await User.findByPk(req.params.id);
    res.json(user);
});

// Installation: npm install @google-cloud/sqlcommenter-sequelize

// Resulting SQL with Express middleware:
// SELECT * FROM "Users" WHERE "id" = 1
// /*db_driver='sequelize:6.32.0',route='/users/:id',traceparent='00-abc123-def456-01'*/
```

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

### Psycopg2 Cursor Factory Setup

Source: https://github.com/google/sqlcommenter/blob/master/python/sqlcommenter-python/README.md

Use the CommenterCursorFactory with psycopg2 connections to add detailed comments to executed queries. Configure trace context and other database-specific attributes as needed.

```python
import psycopg2
from google.cloud.sqlcommenter.psycopg2.extension import CommenterCursorFactory

cursor_factory = CommenterCursorFactory(
    with_db_driver=True,
    with_dbapi_level=True,
    with_dbapi_threadsafety=True,
    with_driver_paramstyle=True,
    with_libpq_version=True,
    # you may use one of opencensus or opentelemetry
    with_opencensus=True,
    with_opentelemetry=True,
)
conn = psycopg2.connect(..., cursor_factory=cursor_factory)
cursor = conn.cursor()
cursor.execute(...) # comment will be added before execution
```

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

### SQLAlchemy Event Listener Setup

Source: https://github.com/google/sqlcommenter/blob/master/python/sqlcommenter-python/README.md

Attach the BeforeExecuteFactory listener to the 'before_cursor_execute' event for a SQLAlchemy engine to add comments to executed queries. Ensure trace context options are configured.

```python
import sqlalchemy
from google.cloud.sqlcommenter.sqlalchemy.executor import BeforeExecuteFactory

engine = sqlalchemy.create_engine(...)
listener = BeforeExecuteFactory(
    with_db_driver=True,
    with_db_framework=True,
    # you may use one of opencensus or opentelemetry
    with_opencensus=True,
    with_opentelemetry=True,
)
sqlalchemy.event.listen(engine, 'before_cursor_execute', listener, retval=True)
engine.execute(...) # comment will be added before execution
```

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

### Resulting SQL with Hibernate inspector and Spring interceptor

Source: https://context7.com/google/sqlcommenter/llms.txt

Example of SQL generated when both the Spring interceptor and Hibernate inspector are active. The comments include framework, controller, and trace context information.

```sql
SELECT * FROM users WHERE id = ?
/*action='findById',controller='User',framework='spring',
traceparent='00-5bd66ef5095369c7b0d1f8f4bd33716a-c532cb4098ac3dd2-01',
tracestate='congo%3Dt61rcWkgMzE%2Crojo%3D00f067aa0ba902b7'*/
```

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

### Apply Database Migrations

Source: https://github.com/google/sqlcommenter/blob/master/php/sqlcommenter-php/samples/sqlcommenter-laravel/README.md

Execute this command to create the necessary database tables for the application.

```shell
php artisan migrate
```

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

### Get Function Name (Go)

Source: https://context7.com/google/sqlcommenter/llms.txt

Gets the name of a function for use in action/controller tags.

```go
// GetFunctionName: Get the name of a function for use in action/controller tags
func ExampleGetFunctionName() {
    name := core.GetFunctionName(ExampleGetFunctionName)
    fmt.Println(name)
}
```

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

### Test Server with Curl and Observe Output

Source: https://github.com/google/sqlcommenter/blob/master/nodejs/sqlcommenter-nodejs/samples/express-opentelemetry/README.md

Send a request to the running server using `curl` and observe the application's output, including database query logs with trace information.

```bash
$ curl http://localhost:8000
{"todos":[{"id":11,"title":"Do dishes","description":null,"done":false,"createdAt":"2020-11-06T01:59:50.111Z","updatedAt":"2020-11-06T01:59:50.111Z"},{"id":12,"title":"Buy groceries","description":null,"done":false,"createdAt":"2020-11-06T01:59:50.111Z","updatedAt":"2020-11-06T01:59:50.111Z"},{"id":13,"title":"Do laundry","description":"Finish before Thursday!","done":false,"createdAt":"2020-11-06T01:59:50.111Z","updatedAt":"2020-11-06T01:59:50.111Z"},{"id":14,"title":"Clean room","description":null,"done":false,"createdAt":"2020-11-06T01:59:50.111Z","updatedAt":"2020-11-06T01:59:50.111Z"},{"id":15,"title":"Wash car","description":null,"done":false,"createdAt":"2020-11-06T01:59:50.112Z","updatedAt":"2020-11-06T01:59:50.112Z"}]}

# Original terminal will output
[server]: Server is running at https://localhost:8000
Google Cloud Trace export
Google Cloud Trace batch writing traces
Google Cloud Trace authenticating
Google Cloud Trace got authentication. Initializaing rpc client
batchWriteSpans successfully
Executing (default): SELECT "id", "title", "description", "done", "createdAt", "updatedAt" FROM "Todos" AS "Todo" LIMIT 20; /*client_timezone='%2B00%3A00',db_driver='sequelize%3A6.3.3',route='%2F',traceparent='00-3e2914ebce6af09508dd1ff1128493a8-81d09ab4d8cde7cf-01'*/
Executing (default): SELECT "done", COUNT("id") AS "count" FROM "Todos" AS "Todo" GROUP BY "done"; /*client_timezone='%2B00%3A00',db_driver='sequelize%3A6.3.3',route='%2F',traceparent='00-3e2914ebce6af09508dd1ff1128493a8-81d09ab4d8cde7cf-01'*/
Google Cloud Trace export
Google Cloud Trace batch writing traces
batchWriteSpans successfully
```

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

### Prepare SQLCommenterTags from HTTP Request

Source: https://github.com/google/sqlcommenter/blob/master/go/net/http/README.md

This code prepares SQLCommenterTags from an HTTP request and injects them into the context. It requires the 'github.com/google/sqlcommenter/go/net/http' package.

```go
import (
    sqlcommenterhttp "github.com/google/sqlcommenter/go/net/http"
)

requestTags := sqlcommenterhttp.NewHTTPRequestTags(framework string, route string, action string)
ctx := core.ContextInject(request.Context(), requestTags)
requestWithTags := request.WithContext(ctx)
```

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

### Run full test suite

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/marginalia-opencensus/README.md

Use this command to execute the entire test suite, including all supported Rails versions and rubocop checks.

```bash
bundle exec wwtd
```

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

### Basic SQLCommenter Middleware Integration

Source: https://github.com/google/sqlcommenter/blob/master/go/gorrila/mux/README.md

Integrate SQLCommenterMiddleware into a gorilla/mux router to automatically add SQL comment tags from HTTP requests.

```go
import (
    "net/http"

    sqlcommentermux "github.com/google/sqlcommenter/go/gorrila/mux"
    "github.com/gorilla/mux"
)

func runApp() {
    r := mux.NewRouter()
    r.Use(sqlcommentermux.SQLCommenterMiddleware)

    r.HandleFunc("/", ActionHome).Methods("GET")

    http.ListenAndServe(":8081", r)
}
```

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

### Run PHPUnit Tests

Source: https://github.com/google/sqlcommenter/blob/master/php/sqlcommenter-php/samples/sqlcommenter-laravel/README.md

Execute the project's test suite using the PHPUnit command-line tool.

```shell
./vendor/bin/phpunit tests
```

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

### SQLCommenter and OpenTelemetry Integration

Source: https://github.com/google/sqlcommenter/blob/master/go/gorrila/mux/README.md

Combine SQLCommenterMiddleware with otelmux middleware for comprehensive request tagging and tracing. Ensure OpenTelemetry is initialized.

```go
import (
    "context"
    "log"
    "net/http"

    sqlcommentermux "github.com/google/sqlcommenter/go/gorrila/mux"
    "github.com/gorilla/mux"
    "go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux"
    "go.opentelemetry.io/otel"
    stdout "go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
    "go.opentelemetry.io/otel/propagation"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
    tp, err := initTracer()
    if err != nil {
        log.Fatal(err)
    }
    defer func() {
        if err := tp.Shutdown(context.Background()); err != nil {
            log.Printf("Error shutting down tracer provider: %v", err)
        }
    }()

    r := mux.NewRouter()
    r.Use(otelmux.Middleware("sqlcommenter sample-server"), sqlcommentermux.SQLCommenterMiddleware)

    r.HandleFunc("/", ActionHome).Methods("GET")

    http.ListenAndServe(":8081", r)
}

func initTracer() (*sdktrace.TracerProvider, error) {
    exporter, err := stdout.New(stdout.WithPrettyPrint())
    if err != nil {
        return nil, err
    }
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.AlwaysSample()),
        sdktrace.WithBatcher(exporter),
    )
    otel.SetTracerProvider(tp)
    otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.Baggage{}))
    return tp, nil
}
```

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

### Spring Java Configuration (Spring 5+)

Source: https://github.com/google/sqlcommenter/blob/master/java/sqlcommenter-java/README.md

Integrates SpringSQLCommenterInterceptor using Java-based configuration for Spring 5 and later. Ensure SpringSQLCommenterInterceptor is imported.

```java
import com.google.cloud.sqlcommenter.interceptors.SpringSQLCommenterInterceptor;

@EnableWebMvc
@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Bean
    public SpringSQLCommenterInterceptor sqlInterceptor() {
         return new SpringSQLCommenterInterceptor();
    }
 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(sqlInterceptor());
    }
}
```

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

### Follow Postgres Logs

Source: https://github.com/google/sqlcommenter/blob/master/go/samples/http/README.md

Displays the logs for the Postgres container, allowing you to observe database activity.

```sh
docker logs --follow postgres
```

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

### Import SQLCommenter Knex

Source: https://github.com/google/sqlcommenter/blob/master/nodejs/sqlcommenter-nodejs/packages/sqlcommenter-knex/README.md

Import the SQLCommenter Knex wrapper into your Node.js project. This is the first step to using its features.

```javascript
const sknex = require('@google-cloud/sqlcommenter-knex');
```

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

### Open Database Connection with SQLCommenter

Source: https://github.com/google/sqlcommenter/blob/master/go/database/sql/README.md

Open a database connection using SQLCommenter's driver. It's recommended to use context-based methods like QueryContext for passing information. Configure options and static tags as needed.

```go
import (
    gosql "github.com/google/sqlcommenter/go/database/sql"
    sqlcommentercore "github.com/google/sqlcommenter/go/core"
    _ "github.com/lib/pq" // or any other database driver
)

db, err := gosql.Open("<driver>", "<connectionString>", sqlcommentercore.CommenterOptions{
    Config: sqlcommentercore.CommenterConfig{<flag>:bool}
    Tags  : sqlcommentercore.StaticTags{<tag>: string} // optional
})
```

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

### Configure SQLAlchemy with BeforeExecuteFactory

Source: https://context7.com/google/sqlcommenter/llms.txt

Use BeforeExecuteFactory to automatically add framework, controller, route, and OpenTelemetry information to SQL queries executed via SQLAlchemy.

```python
import sqlalchemy
from sqlcommenter.sqlalchemy.factory import BeforeExecuteFactory

engine = sqlalchemy.create_engine('postgresql://user:pass@localhost/mydb')
listener = BeforeExecuteFactory(
    with_framework=True,
    with_controller=True,
    with_route=True,
    with_opentelemetry=True,
)
saint.event.listen(engine, 'before_cursor_execute', listener, retval=True)

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    with engine.connect() as conn:
        result = conn.execute(
            sqlalchemy.text("SELECT * FROM users WHERE id = :id"),
            {"id": user_id}
        )
        return {"user": dict(result.fetchone())}

# Resulting SQL in database logs:
# SELECT * FROM users WHERE id = 1
# /*app_name='My API',controller='get_user',framework='fastapi%3A0.100.0',
# route='/users/{user_id}'*/
```

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

### Context Inject for Database Queries (Go)

Source: https://context7.com/google/sqlcommenter/llms.txt

Injects request tags into context for downstream database queries. Implements the RequestTagsProvider interface.

```go
// ContextInject: Inject request tags into context for downstream database queries
// Implements RequestTagsProvider interface

handler := func(w http.ResponseWriter, r *http.Request) {
    // Create request tags
    requestTags := &HTTPRequestTags{
        route:     "/users/{id}",
        action:    "GetUser",
        framework: "gorilla/mux",
    }

    // Inject tags into context
    ctx := core.ContextInject(r.Context(), requestTags)

    // Use the enriched context for database queries
    // The SQLCommenter driver will extract these tags automatically
    db.QueryContext(ctx, "SELECT * FROM users WHERE id = ?", 1)
}

// HTTPRequestTags implements core.RequestTagsProvider interface
type HTTPRequestTags struct {
    route     string
    action    string
    framework string
}

func (h *HTTPRequestTags) Route() string     { return h.route }
func (h *HTTPRequestTags) Action() string    { return h.action }
func (h *HTTPRequestTags) Framework() string { return h.framework }
```

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

### Set Environment Variables for Cloud SQL

Source: https://github.com/google/sqlcommenter/blob/master/nodejs/sqlcommenter-nodejs/samples/express-opentelemetry/README.md

Configure database connection details by setting these environment variables before running the application. Ensure correct values for hostname, username, password, and dialect.

```bash
# in this directory
$ export DBHOST="<hostname or unix socket path>"
$ export DBUSERNAME="<database user>"
$ export DBPASSWORD="<database password>"
$ export DBDIALECT="<postgres | mysql>"
$ npm install

# before the first run, create some data
$ npm run createTodos
```

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

### Register Sqlcommenter Database Service Provider

Source: https://github.com/google/sqlcommenter/blob/master/php/sqlcommenter-php/packages/sqlcommenter-laravel/README.md

Add the GoogleSqlCommenterLaravel Database Service Provider to your `config/app.php` file. It should be placed before the default Illuminate Database Service Provider.

```php
'providers' => [
    ...
    Google\GoogleSqlCommenterLaravel\Database\DatabaseServiceProvider::class,
    Illuminate\Database\DatabaseServiceProvider::class,
    ...
]
```

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

### Run tests with latest Rails

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/marginalia-opencensus/README.md

Execute this rake task to run the test suite against the latest release of Rails.

```bash
bundle exec rake
```

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

### Publish Sqlcommenter-laravel Configuration

Source: https://github.com/google/sqlcommenter/blob/master/php/sqlcommenter-php/packages/sqlcommenter-laravel/README.md

Run this Artisan command to publish the Sqlcommenter-laravel configuration file to your Laravel application.

```shell
php artisan vendor:publish --provider="Google\GoogleSqlCommenterLaravel\GoogleSqlCommenterServiceProvider"
```

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

### Import SQLCommenter Sequelize

Source: https://github.com/google/sqlcommenter/blob/master/nodejs/sqlcommenter-nodejs/packages/sqlcommenter-sequelize/README.md

Import the SQLCommenter Sequelize library in your Node.js project.

```javascript
const ssequelize = require('@google-cloud/sqlcommenter-sequelize');
```

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

### Convert Map to SQL Comment (Go)

Source: https://context7.com/google/sqlcommenter/llms.txt

Converts a map of tags to a SQL comment string. Keys are sorted alphabetically, and values are URL-encoded.

```go
package main

import (
    "context"
    "fmt"
    "net/http"

    "github.com/google/sqlcommenter/go/core"
)

func main() {
    // ConvertMapToComment: Convert a map of tags to a SQL comment string
    // Keys are sorted alphabetically, values are URL-encoded

    tags := map[string]string{
        "controller": "UserController",
        "action":     "create",
        "framework":  "gorilla/mux",
        "route":      "/users/{id}",
    }

    comment := core.ConvertMapToComment(tags)
    fmt.Println(comment)
```

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

### Monitor SQL Queries

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/sqlcommenter_rails_demo/README.md

Run this command in a separate terminal to monitor SQL queries logged by the application.

```bash
tail -f log/development.log | grep 'Post '
```

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

### Spring Java Configuration (Older Spring Versions)

Source: https://github.com/google/sqlcommenter/blob/master/java/sqlcommenter-java/README.md

Integrates SpringSQLCommenterInterceptor for older Spring versions by extending WebMvcConfigureAdapter. Ensure SpringSQLCommenterInterceptor is imported.

```java
import com.google.cloud.sqlcommenter.interceptors.SpringSQLCommenterInterceptor;

@EnableWebMvc
@Configuration
public class WebConfig extends WebMvcConfigureAdapter {

    @Bean
    public SpringSQLCommenterInterceptor sqlInterceptor() {
         return new SpringSQLCommenterInterceptor();
    }
 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(sqlInterceptor());
    }
}
```

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

### Define Commenter Configuration Options

Source: https://github.com/google/sqlcommenter/blob/master/go/core/README.md

Use CommenterConfig to control which application tags are appended to SQL statements. Set EnableDBDriver, EnableRoute, EnableFramework, EnableController, EnableAction, EnableTraceparent, and EnableApplication to true to include corresponding tags.

```go
type CommenterConfig struct {
    EnableDBDriver    bool
    EnableRoute       bool
    EnableFramework   bool
    EnableController  bool
    EnableAction      bool
    EnableTraceparent bool
    EnableApplication bool
}
```

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

### Define Static Tags for SQLCommenter

Source: https://github.com/google/sqlcommenter/blob/master/go/core/README.md

Use StaticTags to set static values for application and driver name tags. These values are applied directly to SQL statements.

```go
type StaticTags struct {
    Application string
    DriverName  string
}
```

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

### Integrate SQLCommenter with SQLAlchemy

Source: https://context7.com/google/sqlcommenter/llms.txt

Use an event listener factory with SQLAlchemy's 'before_cursor_execute' event to add SQL comments. Configure options like including database driver, framework version, controller, route, and tracing information.

```python
import sqlalchemy
from google.cloud.sqlcommenter.sqlalchemy.executor import BeforeExecuteFactory

# Create the SQLAlchemy engine
engine = sqlalchemy.create_engine('postgresql://user:pass@localhost/mydb')

# Create the BeforeExecuteFactory with desired options
listener = BeforeExecuteFactory(
    with_db_driver=True,       # Include database driver name
    with_db_framework=True,    # Include SQLAlchemy version
    with_framework=True,       # Include web framework (Flask/FastAPI) if detected
    with_controller=True,      # Include controller/endpoint name
    with_route=True,           # Include URL route pattern
    with_opentelemetry=True,   # Include OpenTelemetry trace context
    with_opencensus=False,     # Include OpenCensus trace context
)

# Attach the listener to the engine
ssqlalchemy.event.listen(engine, 'before_cursor_execute', listener, retval=True)

# Execute queries - comments are automatically added
with engine.connect() as conn:
    result = conn.execute(sqlalchemy.text("SELECT * FROM users WHERE id = :id"), {"id": 1})

# Resulting SQL in database logs:
# SELECT * FROM users WHERE id = 1
# /*db_driver='psycopg2',db_framework='sqlalchemy%3A2.0.0',framework='flask%3A2.3.0',
# controller='get_user',route='/users/<int:id>',
# traceparent='00-5bd66ef5095369c7b0d1f8f4bd33716a-c532cb4098ac3dd2-01'*/
```

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

### Spring XML Configuration (Specific Method Interceptor)

Source: https://github.com/google/sqlcommenter/blob/master/java/sqlcommenter-java/README.md

Configures SpringSQLCommenterInterceptor for a specific path using XML configuration.

```xml
<mvc:interceptors>
    <mvc:interceptor>
        <mvc:mapping path="/flights"></mvc:mapping>
        <bean class="com.google.cloud.sqlcommenter.interceptors.SpringSQLCommenterInterceptor"></bean>
    </mvc:interceptor>
</mvc:interceptors>
```

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

### Configure Django Middleware for SQLCommenter

Source: https://context7.com/google/sqlcommenter/llms.txt

Add the SqlCommenter middleware to your Django settings.py to automatically instrument database queries. Configure which attributes to include in SQL comments using provided boolean flags.

```python
# settings.py - Add the SqlCommenter middleware to your Django settings

MIDDLEWARE = [
    'google.cloud.sqlcommenter.django.middleware.SqlCommenter',
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    # ... other middleware
]

# Optional: Configure which attributes to include in SQL comments
SQLCOMMENTER_WITH_FRAMEWORK = True       # Include Django version (default: True)
SQLCOMMENTER_WITH_CONTROLLER = True      # Include view name (default: True)
SQLCOMMENTER_WITH_ROUTE = True           # Include URL route pattern (default: True)
SQLCOMMENTER_WITH_APP_NAME = False       # Include Django app name (default: False)
SQLCOMMENTER_WITH_DB_DRIVER = False      # Include database driver (default: False)
SQLCOMMENTER_WITH_OPENTELEMETRY = True   # Include OpenTelemetry trace context
SQLCOMMENTER_WITH_OPENCENSUS = False     # Include OpenCensus trace context (mutually exclusive with OpenTelemetry)

# Installation:
# pip install google-cloud-sqlcommenter
# pip install google-cloud-sqlcommenter[opentelemetry]  # For OpenTelemetry support

# Resulting SQL in database logs:
# SELECT * FROM "polls_question" WHERE id = 1
# /*controller='polls:index',framework='django%3A4.2.1',route='%5Epolls/%24',
# traceparent='00-5bd66ef5095369c7b0d1f8f4bd33716a-c532cb4098ac3dd2-01'*/
```

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

### Clone Marginalia Fork

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/sqlcommenter_rails_demo/README.md

Clone modulitos's fork of marginalia and checkout the formatting branch. This is a prerequisite for the demo.

```bash
git clone https://github.com/modulitos/marginalia.git ../marginalia
git -C ../marginalia checkout formatting
```

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

### Extract Traceparent (Go)

Source: https://context7.com/google/sqlcommenter/llms.txt

Extracts OpenTelemetry trace context from context.Context. In a real application, ctx would contain an active trace span.

```go
// ExtractTraceparent: Extract OpenTelemetry trace context from context.Context
ctx := context.Background()
// In a real application, ctx would contain active trace span
carrier := core.ExtractTraceparent(ctx)
if tp, ok := carrier["traceparent"]; ok {
    fmt.Println("Traceparent:", tp)
}
```

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

### FastAPI Middleware Integration

Source: https://github.com/google/sqlcommenter/blob/master/python/sqlcommenter-python/README.md

Add the SQLCommenterMiddleware to your FastAPI application to include framework, app_name, controller, and route information in SQL comments when using SQLAlchemy.

```python
from fastapi import FastAPI
from google.cloud.sqlcommenter.fastapi import SQLCommenterMiddleware

app = FastAPI()

app.add_middleware(SQLCommenterMiddleware)
```

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

### Implement FastAPI Middleware for SQLCommenter

Source: https://context7.com/google/sqlcommenter/llms.txt

Add the SQLCommenterMiddleware to your FastAPI application to capture request context. This context can then be used by SQLAlchemy integrations for generating SQL comments.

```python
from fastapi import FastAPI
from google.cloud.sqlcommenter.fastapi import SQLCommenterMiddleware
from google.cloud.sqlcommenter.sqlalchemy.executor import BeforeExecuteFactory
import sqlalchemy

app = FastAPI(title="My API")

# Add the SQLCommenter middleware to capture request context
app.add_middleware(SQLCommenterMiddleware)

```

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

### Generate SQL Comments with Python Core Functions

Source: https://context7.com/google/sqlcommenter/llms.txt

Utilize the `generate_sql_comment` function from the core Python module to programmatically create SQL comment strings from key-value pairs. Values are URL-encoded and sorted alphabetically by key.

```python
from google.cloud.sqlcommenter import generate_sql_comment, add_sql_comment

# generate_sql_comment: Create a SQL comment string from key-value pairs
# Values are URL-encoded and sorted alphabetically by key

comment = generate_sql_comment(
    controller='UserController',
    action='create',
    framework='django:4.2.0',
    route='/api/users/',
    traceparent='00-5bd66ef5095369c7b0d1f8f4bd33716a-c532cb4098ac3dd2-01'
)
print(comment)
# Output: /*action='create',controller='UserController',framework='django%3A4.2.0',
#          route='%2Fapi%2Fusers%2F',traceparent='00-5bd66ef5095369c7b0d1f8f4bd33716a-c532cb4098ac3dd2-01'*/
```

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

### Combine Configuration and Static Tags

Source: https://github.com/google/sqlcommenter/blob/master/go/core/README.md

The CommenterOptions struct combines CommenterConfig and StaticTags. This combined struct is used by the database/sql module for configuring SQL comment generation.

```go
type CommenterOptions struct {
    Config CommenterConfig
    Tags   StaticTags
}
```

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

### Psycopg2 Cursor Factory Integration

Source: https://context7.com/google/sqlcommenter/llms.txt

Utilize CommenterCursorFactory for psycopg2 to automatically append detailed database driver and API information to SQL queries.

```python
import psycopg2
from google.cloud.sqlcommenter.psycopg2.extension import CommenterCursorFactory

cursor_factory = CommenterCursorFactory(
    with_db_driver=True,
    with_dbapi_level=True,
    with_dbapi_threadsafety=True,
    with_driver_paramstyle=True,
    with_libpq_version=True,
    with_framework=True,
    with_controller=True,
    with_route=True,
    with_opentelemetry=True,
)

conn = psycopg2.connect(
    host='localhost',
    database='mydb',
    user='user',
    password='pass',
    cursor_factory=cursor_factory
)

cursor = conn.cursor()
cursor.execute("SELECT * FROM users WHERE id = %s", (1,))
user = cursor.fetchone()

# Resulting SQL in database logs:
# SELECT * FROM users WHERE id = 1
# /*db_driver='psycopg2%3A2.9.6%20%28dt%20dec%20pq3%20ext%20lo64%29',
# dbapi_level='2.0',dbapi_threadsafety=2,driver_paramstyle='pyformat',
# libpq_version=150001,traceparent='00-abc123-def456-01'*/
```

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

### Add SQLCommenter Gems to Gemfile

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/sqlcommenter_rails/README.md

Add the sqlcommenter_rails, marginalia, and marginalia-opencensus gems to your application's Gemfile, specifying their local paths.

```ruby
gem 'sqlcommenter_rails', path: '../sqlcommenter_rails'
gem 'marginalia', path: '../marginalia'
gem 'marginalia-opencensus', path: '../marginalia-opencensus'
```

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

### Add marginalia-opencensus to Gemfile

Source: https://github.com/google/sqlcommenter/blob/master/ruby/sqlcommenter-ruby/marginalia-opencensus/README.md

Include this line in your application's Gemfile to add the marginalia-opencensus gem as a dependency.

```ruby
gem 'marginalia-opencensus'
```