.gitignore + README

Author: asmyasnikov

.gitignore

@@ -9,3 +9,4 @@ __pycache__
 .devenv*
 devenv.local.nix
 
+/bin/sqlc

examples/plugin-based-codegen/README.md

@@ -59,6 +59,22 @@ SQLCDEBUG=processplugins=1 sqlc generate
 
 ## How It Works
 
+### Architecture Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  sqlc generate                                                  │
+│                                                                 │
+│  1. Read schema.sql & queries.sql                               │
+│  2. Send SQL to engine plugin (sqlc-engine-*)                   │
+│     └─> Parse SQL, return AST & Catalog                         │
+│  3. Analyze queries with AST & Catalog                          │
+│  4. Send queries + catalog to codegen plugin (sqlc-gen-*)       │
+│     └─> Generate code (Rust, Go, etc.)                          │
+│  5. Write generated files                                       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
 ### Database Engine Plugin (`sqlc-engine-sqlite3`)
 
 The engine plugin implements the `pkg/engine.Handler` interface:
@@ -98,6 +114,62 @@ func main() {
 
 Communication: **Protobuf over stdin/stdout**
 
+### Parameter Passing: `sql_package` Example
+
+For Go code generation, the `sql_package` parameter is passed to the codegen plugin:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  sqlc.yaml                                                      │
+│  ┌───────────────────────────────────────────────────────────┐ │
+│  │ gen:                                                       │ │
+│  │   go:                                                      │ │
+│  │     sql_package: "database/sql"  # or "pgx/v5"            │ │
+│  └───────────────────────────────────────────────────────────┘ │
+│                           │                                     │
+│                           ▼                                     │
+│  ┌───────────────────────────────────────────────────────────┐ │
+│  │ GenerateRequest (protobuf)                                 │ │
+│  │   Settings:                                                │ │
+│  │     Codegen:                                               │ │
+│  │       Options: []byte{                                     │ │
+│  │         "sql_package": "database/sql",  # JSON            │ │
+│  │         "package": "db",                                  │ │
+│  │         ...                                                │ │
+│  │       }                                                    │ │
+│  │   Queries: [...]                                           │ │
+│  │   Catalog: {...}                                           │ │
+│  └───────────────────────────────────────────────────────────┘ │
+│                           │                                     │
+│                           ▼                                     │
+│  ┌───────────────────────────────────────────────────────────┐ │
+│  │ Codegen Plugin (sqlc-gen-go or custom)                    │ │
+│  │   func generate(req *plugin.GenerateRequest) {            │ │
+│  │     var opts Options                                       │ │
+│  │     json.Unmarshal(req.PluginOptions, &opts)              │ │
+│  │     // opts.SqlPackage == "database/sql"                  │ │
+│  │     // Generate code using database/sql APIs              │ │
+│  │   }                                                        │ │
+│  └───────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Important Notes:**
+
+1. **Standard Go codegen** (`gen.go`) only supports:
+   - `database/sql` (stdlib)
+   - `pgx/v4` (PostgreSQL)
+   - `pgx/v5` (PostgreSQL)
+
+2. **Custom SQL packages** (e.g., `github.com/ydb-platform/ydb-go-sdk/v3`) require:
+   - A **custom codegen plugin** that reads `sql_package` from `PluginOptions`
+   - The plugin generates code using the specified package's APIs
+
+3. **Example**: For YDB native SDK, you would create `sqlc-gen-ydb-go` that:
+   - Reads `sql_package: "github.com/ydb-platform/ydb-go-sdk/v3"` from options
+   - Generates code using `ydb.Session` instead of `*sql.DB`
+   - Uses YDB-specific APIs for query execution
+
 ## Compatibility
 
 Both plugins import public packages from sqlc:
@@ -177,6 +249,64 @@ pub async fn create_user(pool: &SqlitePool, id: i32, name: String, email: String
 }
 ```
 
+## Example: Go Codegen with Custom `sql_package`
+
+For Go code generation, the standard `gen.go` only supports `database/sql`, `pgx/v4`, and `pgx/v5`. To use other SQL packages (e.g., `github.com/ydb-platform/ydb-go-sdk/v3`), you need a custom codegen plugin.
+
+**Example: `sqlc-gen-ydb-go` plugin**
+
+```go
+package main
+
+import (
+    "encoding/json"
+    "github.com/sqlc-dev/sqlc/pkg/plugin"
+)
+
+type Options struct {
+    Package    string `json:"package"`
+    SqlPackage string `json:"sql_package"`  // e.g., "github.com/ydb-platform/ydb-go-sdk/v3"
+    Out        string `json:"out"`
+}
+
+func generate(req *plugin.GenerateRequest) (*plugin.GenerateResponse, error) {
+    var opts Options
+    json.Unmarshal(req.PluginOptions, &opts)
+    
+    // opts.SqlPackage contains the value from sqlc.yaml
+    // Generate code using the specified package's APIs
+    if opts.SqlPackage == "github.com/ydb-platform/ydb-go-sdk/v3" {
+        // Generate YDB-specific code using ydb.Session
+    } else {
+        // Generate standard database/sql code
+    }
+    
+    return &plugin.GenerateResponse{
+        Files: []*plugin.File{...},
+    }, nil
+}
+```
+
+**Configuration:**
+
+```yaml
+plugins:
+  - name: ydb-go
+    process:
+      cmd: sqlc-gen-ydb-go
+
+sql:
+  - engine: ydb
+    schema: "schema.sql"
+    queries: "queries.sql"
+    codegen:
+      - plugin: ydb-go
+        out: db
+        options:
+          sql_package: "github.com/ydb-platform/ydb-go-sdk/v3"
+          package: "db"
+```
+
 ## See Also
 
 - [Engine Plugins Documentation](../../docs/howto/engine-plugins.md)