feat: initial implementation of sqlc-multi-db

Extracts the gen-db-wrappers tool from ncps into a standalone, reusable
repository with three improvements:

- Split into library (generator/) + thin CLI (main.go) so other programs
  can import the generator logic directly
- Remove hardcoded ncps import path: findImportBase() auto-detects the
  module name and relative path from the nearest go.mod
- Generate generated_errors.go (ErrNotFound, ErrMismatchedSlices) so
  these are never manually maintained

Also includes a complete example/ demonstrating a books+tags schema
across SQLite, PostgreSQL, and MySQL, exercising bulk inserts (@bulk-for),
nullable fields (sql.NullString), and MySQL Create/Update patterns.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kalbasit

example/db/migrations/mysql/20250101000000_create-books-and-tags.sql

@@ -0,0 +1,29 @@
+-- migrate:up
+CREATE TABLE books (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    title VARCHAR(255) NOT NULL,
+    author VARCHAR(255) NOT NULL,
+    description TEXT,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+CREATE TABLE tags (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    name VARCHAR(255) NOT NULL UNIQUE,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+CREATE TABLE book_tags (
+    book_id BIGINT NOT NULL,
+    tag_id BIGINT NOT NULL,
+    PRIMARY KEY (book_id, tag_id),
+    FOREIGN KEY (book_id) REFERENCES books(id) ON DELETE CASCADE,
+    FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE
+);
+
+-- migrate:down
+DROP TABLE book_tags;
+DROP TABLE tags;
+DROP TABLE books;

example/db/migrations/postgres/20250101000000_create-books-and-tags.sql

@@ -0,0 +1,27 @@
+-- migrate:up
+CREATE TABLE books (
+    id BIGSERIAL PRIMARY KEY,
+    title TEXT NOT NULL,
+    author TEXT NOT NULL,
+    description TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE tags (
+    id BIGSERIAL PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE book_tags (
+    book_id BIGINT NOT NULL REFERENCES books(id) ON DELETE CASCADE,
+    tag_id BIGINT NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
+    PRIMARY KEY (book_id, tag_id)
+);
+
+-- migrate:down
+DROP TABLE book_tags;
+DROP TABLE tags;
+DROP TABLE books;

example/db/migrations/sqlite/20250101000000_create-books-and-tags.sql

@@ -0,0 +1,27 @@
+-- migrate:up
+CREATE TABLE books (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    author TEXT NOT NULL,
+    description TEXT,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE tags (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL UNIQUE,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE book_tags (
+    book_id INTEGER NOT NULL REFERENCES books(id) ON DELETE CASCADE,
+    tag_id INTEGER NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
+    PRIMARY KEY (book_id, tag_id)
+);
+
+-- migrate:down
+DROP TABLE book_tags;
+DROP TABLE tags;
+DROP TABLE books;

example/db/query.mysql.sql

@@ -0,0 +1,65 @@
+-- name: GetBook :one
+-- SELECT `id`, `title`, `author`, `description`, `created_at`, `updated_at` FROM books WHERE id = ?
+SELECT `id`, `title`, `author`, `description`, `created_at`, `updated_at`
+FROM books
+WHERE id = ?;
+
+-- name: ListBooks :many
+-- SELECT `id`, `title`, `author`, `description`, `created_at`, `updated_at` FROM books ORDER BY title
+SELECT `id`, `title`, `author`, `description`, `created_at`, `updated_at`
+FROM books
+ORDER BY `title`;
+
+-- name: GetBooksByAuthor :many
+-- SELECT `id`, `title`, `author`, `description`, `created_at`, `updated_at` FROM books WHERE author = ?
+SELECT `id`, `title`, `author`, `description`, `created_at`, `updated_at`
+FROM books
+WHERE `author` = ?;
+
+-- name: CreateBook :execresult
+-- INSERT INTO books (`title`, `author`, `description`) VALUES (?, ?, ?)
+INSERT INTO books (`title`, `author`, `description`)
+VALUES (?, ?, ?);
+
+-- name: UpdateBook :execresult
+-- UPDATE books SET `title` = ?, `author` = ?, `description` = ?, `updated_at` = NOW() WHERE id = ?
+UPDATE books
+SET `title` = ?,
+    `author` = ?,
+    `description` = ?,
+    `updated_at` = NOW()
+WHERE id = ?;
+
+-- name: DeleteBook :exec
+-- DELETE FROM books WHERE id = ?
+DELETE FROM books
+WHERE id = ?;
+
+-- name: CreateTag :execresult
+-- INSERT INTO tags (`name`) VALUES (?)
+INSERT INTO tags (`name`)
+VALUES (?);
+
+-- name: GetTag :one
+-- SELECT `id`, `name`, `created_at`, `updated_at` FROM tags WHERE id = ?
+SELECT `id`, `name`, `created_at`, `updated_at`
+FROM tags
+WHERE id = ?;
+
+-- name: AddBookTag :exec
+-- INSERT INTO book_tags (`book_id`, `tag_id`) VALUES (?, ?)
+INSERT INTO book_tags (`book_id`, `tag_id`)
+VALUES (?, ?);
+
+-- name: AddBookTags :exec
+-- INSERT INTO book_tags (`book_id`, `tag_id`) VALUES (?, ?)
+-- @bulk-for AddBookTag
+INSERT INTO book_tags (`book_id`, `tag_id`)
+VALUES (?, ?);
+
+-- name: GetBookTags :many
+-- SELECT t.`id`, t.`name`, t.`created_at`, t.`updated_at` FROM tags t INNER JOIN book_tags bt ON t.id = bt.tag_id WHERE bt.book_id = ?
+SELECT t.`id`, t.`name`, t.`created_at`, t.`updated_at`
+FROM tags t
+INNER JOIN book_tags bt ON t.id = bt.tag_id
+WHERE bt.book_id = ?;

example/db/query.postgres.sql

@@ -0,0 +1,68 @@
+-- name: GetBook :one
+-- SELECT "id", "title", "author", "description", "created_at", "updated_at" FROM books WHERE id = $1
+SELECT "id", "title", "author", "description", "created_at", "updated_at"
+FROM books
+WHERE id = $1;
+
+-- name: ListBooks :many
+-- SELECT "id", "title", "author", "description", "created_at", "updated_at" FROM books ORDER BY title
+SELECT "id", "title", "author", "description", "created_at", "updated_at"
+FROM books
+ORDER BY title;
+
+-- name: GetBooksByAuthor :many
+-- SELECT "id", "title", "author", "description", "created_at", "updated_at" FROM books WHERE author = $1
+SELECT "id", "title", "author", "description", "created_at", "updated_at"
+FROM books
+WHERE author = $1;
+
+-- name: CreateBook :one
+-- INSERT INTO books ("title", "author", "description") VALUES ($1, $2, $3) RETURNING "id", "title", "author", "description", "created_at", "updated_at"
+INSERT INTO books ("title", "author", "description")
+VALUES ($1, $2, $3)
+RETURNING "id", "title", "author", "description", "created_at", "updated_at";
+
+-- name: UpdateBook :one
+-- UPDATE books SET "title" = $1, "author" = $2, "description" = $3, "updated_at" = NOW() WHERE id = $4 RETURNING "id", "title", "author", "description", "created_at", "updated_at"
+UPDATE books
+SET "title" = $1,
+    "author" = $2,
+    "description" = $3,
+    "updated_at" = NOW()
+WHERE id = $4
+RETURNING "id", "title", "author", "description", "created_at", "updated_at";
+
+-- name: DeleteBook :exec
+-- DELETE FROM books WHERE id = $1
+DELETE FROM books
+WHERE id = $1;
+
+-- name: CreateTag :one
+-- INSERT INTO tags ("name") VALUES ($1) RETURNING "id", "name", "created_at", "updated_at"
+INSERT INTO tags ("name")
+VALUES ($1)
+RETURNING "id", "name", "created_at", "updated_at";
+
+-- name: GetTag :one
+-- SELECT "id", "name", "created_at", "updated_at" FROM tags WHERE id = $1
+SELECT "id", "name", "created_at", "updated_at"
+FROM tags
+WHERE id = $1;
+
+-- name: AddBookTag :exec
+-- INSERT INTO book_tags ("book_id", "tag_id") VALUES ($1, $2)
+INSERT INTO book_tags ("book_id", "tag_id")
+VALUES ($1, $2);
+
+-- name: AddBookTags :exec
+-- INSERT INTO book_tags ("book_id", "tag_id") VALUES (unnest($1::bigint[]), unnest($2::bigint[]))
+-- @bulk-for AddBookTag
+INSERT INTO book_tags ("book_id", "tag_id")
+VALUES (unnest($1::bigint[]), unnest($2::bigint[]));
+
+-- name: GetBookTags :many
+-- SELECT t."id", t."name", t."created_at", t."updated_at" FROM tags t INNER JOIN book_tags bt ON t.id = bt.tag_id WHERE bt.book_id = $1
+SELECT t."id", t."name", t."created_at", t."updated_at"
+FROM tags t
+INNER JOIN book_tags bt ON t.id = bt.tag_id
+WHERE bt.book_id = $1;

example/db/query.sqlite.sql

@@ -0,0 +1,68 @@
+-- name: GetBook :one
+-- SELECT "id", "title", "author", "description", "created_at", "updated_at" FROM books WHERE id = ?
+SELECT "id", "title", "author", "description", "created_at", "updated_at"
+FROM books
+WHERE id = ?;
+
+-- name: ListBooks :many
+-- SELECT "id", "title", "author", "description", "created_at", "updated_at" FROM books ORDER BY title
+SELECT "id", "title", "author", "description", "created_at", "updated_at"
+FROM books
+ORDER BY title;
+
+-- name: GetBooksByAuthor :many
+-- SELECT "id", "title", "author", "description", "created_at", "updated_at" FROM books WHERE author = ?
+SELECT "id", "title", "author", "description", "created_at", "updated_at"
+FROM books
+WHERE author = ?;
+
+-- name: CreateBook :one
+-- INSERT INTO books ("title", "author", "description") VALUES (?, ?, ?) RETURNING "id", "title", "author", "description", "created_at", "updated_at"
+INSERT INTO books ("title", "author", "description")
+VALUES (?, ?, ?)
+RETURNING "id", "title", "author", "description", "created_at", "updated_at";
+
+-- name: UpdateBook :one
+-- UPDATE books SET "title" = ?, "author" = ?, "description" = ?, "updated_at" = CURRENT_TIMESTAMP WHERE id = ? RETURNING "id", "title", "author", "description", "created_at", "updated_at"
+UPDATE books
+SET "title" = ?,
+    "author" = ?,
+    "description" = ?,
+    "updated_at" = CURRENT_TIMESTAMP
+WHERE id = ?
+RETURNING "id", "title", "author", "description", "created_at", "updated_at";
+
+-- name: DeleteBook :exec
+-- DELETE FROM books WHERE id = ?
+DELETE FROM books
+WHERE id = ?;
+
+-- name: CreateTag :one
+-- INSERT INTO tags ("name") VALUES (?) RETURNING "id", "name", "created_at", "updated_at"
+INSERT INTO tags ("name")
+VALUES (?)
+RETURNING "id", "name", "created_at", "updated_at";
+
+-- name: GetTag :one
+-- SELECT "id", "name", "created_at", "updated_at" FROM tags WHERE id = ?
+SELECT "id", "name", "created_at", "updated_at"
+FROM tags
+WHERE id = ?;
+
+-- name: AddBookTag :exec
+-- INSERT INTO book_tags ("book_id", "tag_id") VALUES (?, ?)
+INSERT INTO book_tags ("book_id", "tag_id")
+VALUES (?, ?);
+
+-- name: AddBookTags :exec
+-- INSERT INTO book_tags ("book_id", "tag_id") VALUES (?, ?)
+-- @bulk-for AddBookTag
+INSERT INTO book_tags ("book_id", "tag_id")
+VALUES (?, ?);
+
+-- name: GetBookTags :many
+-- SELECT t."id", t."name", t."created_at", t."updated_at" FROM tags t INNER JOIN book_tags bt ON t.id = bt.tag_id WHERE bt.book_id = ?
+SELECT t."id", t."name", t."created_at", t."updated_at"
+FROM tags t
+INNER JOIN book_tags bt ON t.id = bt.tag_id
+WHERE bt.book_id = ?;

example/db/schema/mysql.sql

@@ -0,0 +1,23 @@
+CREATE TABLE books (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    title VARCHAR(255) NOT NULL,
+    author VARCHAR(255) NOT NULL,
+    description TEXT,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+CREATE TABLE tags (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    name VARCHAR(255) NOT NULL UNIQUE,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+CREATE TABLE book_tags (
+    book_id BIGINT NOT NULL,
+    tag_id BIGINT NOT NULL,
+    PRIMARY KEY (book_id, tag_id),
+    FOREIGN KEY (book_id) REFERENCES books(id) ON DELETE CASCADE,
+    FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE
+);

example/db/schema/postgres.sql

@@ -0,0 +1,21 @@
+CREATE TABLE books (
+    id BIGSERIAL PRIMARY KEY,
+    title TEXT NOT NULL,
+    author TEXT NOT NULL,
+    description TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE tags (
+    id BIGSERIAL PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE book_tags (
+    book_id BIGINT NOT NULL REFERENCES books(id) ON DELETE CASCADE,
+    tag_id BIGINT NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
+    PRIMARY KEY (book_id, tag_id)
+);

example/db/schema/sqlite.sql

@@ -0,0 +1,21 @@
+CREATE TABLE books (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    author TEXT NOT NULL,
+    description TEXT,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE tags (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL UNIQUE,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE book_tags (
+    book_id INTEGER NOT NULL REFERENCES books(id) ON DELETE CASCADE,
+    tag_id INTEGER NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
+    PRIMARY KEY (book_id, tag_id)
+);

example/go.mod

@@ -0,0 +1,29 @@
+module github.com/kalbasit/sqlc-multi-db/example
+
+go 1.25.5
+
+tool github.com/kalbasit/sqlc-multi-db
+
+require (
+	github.com/go-sql-driver/mysql v1.9.2
+	github.com/jackc/pgx/v5 v5.7.4
+	github.com/mattn/go-sqlite3 v1.14.28
+)
+
+require (
+	filippo.io/edwards25519 v1.1.0 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/kalbasit/sqlc-multi-db v0.0.0 // indirect
+	golang.org/x/crypto v0.31.0 // indirect
+	golang.org/x/mod v0.33.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/text v0.21.0 // indirect
+	golang.org/x/tools v0.42.0 // indirect
+	mvdan.cc/gofumpt v0.9.2 // indirect
+)
+
+replace github.com/kalbasit/sqlc-multi-db => ../