Merge pull request #86 from nao1215/nchika/logger

Add logger adapter

Author: nao1215

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2025-12-18
+
+### Added
+- **Custom Logger Support**: Flexible logging system with slog integration
+  - **`Logger` interface**: Simple logging interface with `Debug`, `Info`, `Warn`, `Error`, and `With` methods
+  - **`ContextLogger` interface**: Extended logging interface with context-aware methods (`DebugContext`, `InfoContext`, `WarnContext`, `ErrorContext`)
+  - **`NewSlogAdapter()`**: Adapter to use standard library `slog.Logger` with filesql's `Logger` interface
+  - **`NewSlogContextAdapter()`**: Adapter for context-aware logging with `slog.Logger`
+  - **`WithLogger()`**: Builder method to inject custom logger into the build and open process
+  - **`nopLogger`**: Zero-overhead no-op logger implementation used as default (benchmarked at ~0.2 ns/op)
+  - Logging throughout build, validation, and database opening operations
+  - Comprehensive test coverage and benchmarks for all logger implementations
+
+### Changed
+- **Documentation Updates**: Added Custom Logger section to all README files (7 languages: EN, ES, FR, JA, KO, RU, ZH-CN)
+  - Usage examples with slog integration
+  - Logger and ContextLogger interface definitions
+  - Performance benchmark comparison table
+
 ## [0.9.0] - 2025-12-18
 
 ### Added
@@ -602,7 +621,8 @@ For users upgrading from v0.3.x:
 - Multi-language documentation (7 languages)
 - Standard database/sql interface implementation
 
-[Unreleased]: https://github.com/nao1215/filesql/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/nao1215/filesql/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/nao1215/filesql/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/nao1215/filesql/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/nao1215/filesql/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/nao1215/filesql/compare/v0.6.0...v0.7.0

README.md

@@ -318,6 +318,69 @@ parquetOptions := filesql.NewDumpOptions().
 // Note: Parquet export is implemented, but external compression is not supported (use Parquet's built-in compression)
 ```
 
+### Custom Logger
+
+filesql supports pluggable logging via the `Logger` interface. By default, a no-op logger is used with zero performance overhead. You can inject your own logger (e.g., `slog`) for debugging and monitoring.
+
+```go
+import (
+    "log/slog"
+    "os"
+    "github.com/nao1215/filesql"
+)
+
+// Create a slog logger
+slogLogger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+    Level: slog.LevelDebug,
+}))
+
+// Wrap it with SlogAdapter and pass to the builder
+logger := filesql.NewSlogAdapter(slogLogger)
+
+validatedBuilder, err := filesql.NewBuilder().
+    WithLogger(logger).
+    AddPath("data.csv").
+    Build(ctx)
+```
+
+#### Logger Interface
+
+```go
+type Logger interface {
+    Debug(msg string, args ...any)
+    Info(msg string, args ...any)
+    Warn(msg string, args ...any)
+    Error(msg string, args ...any)
+    With(args ...any) Logger
+}
+```
+
+#### Context-Aware Logger
+
+For context-aware logging, use `ContextLogger`:
+
+```go
+type ContextLogger interface {
+    Logger
+    DebugContext(ctx context.Context, msg string, args ...any)
+    InfoContext(ctx context.Context, msg string, args ...any)
+    WarnContext(ctx context.Context, msg string, args ...any)
+    ErrorContext(ctx context.Context, msg string, args ...any)
+}
+
+// Use SlogContextAdapter for context-aware logging
+logger := filesql.NewSlogContextAdapter(slogLogger)
+```
+
+#### Performance
+
+| Logger Type | Performance | Memory |
+|-------------|-------------|--------|
+| nopLogger (default) | ~0.2 ns/op | 0 B/op |
+| SlogAdapter | ~1000 ns/op | ~630 B/op |
+
+The default no-op logger has virtually zero overhead, making it safe to leave logging calls in production code.
+
 ## Table Naming Rules
 
 filesql automatically derives table names from file paths:

builder.go

@@ -53,6 +53,8 @@ type DBBuilder struct {
 	autoSaveConfig *autoSaveConfig
 	// defaultChunkSize is the default chunk size for reading large files (10MB)
 	defaultChunkSize int
+	// logger is the logger instance for internal logging
+	logger Logger
 
 	// Internal processors for handling different responsibilities
 	validator       *validator
@@ -93,6 +95,7 @@ func NewBuilder() *DBBuilder {
 		parsedTables:     make([]*table, 0),
 		autoSaveConfig:   nil, // Default: no auto-save
 		defaultChunkSize: chunkSize,
+		logger:           newNopLogger(), // Default: no-op logger
 
 		// Initialize internal processors
 		validator:       newValidator(),
@@ -164,6 +167,28 @@ func (b *DBBuilder) SetDefaultChunkSize(size int) *DBBuilder {
 	return b
 }
 
+// WithLogger sets a custom logger for internal operations.
+//
+// The logger interface is compatible with slog.Logger. You can use the provided
+// SlogAdapter to wrap an existing slog.Logger, or implement your own Logger.
+//
+// Examples:
+//
+//	// Using slog
+//	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+//	builder.WithLogger(filesql.NewSlogAdapter(logger))
+//
+//	// Using a custom logger
+//	builder.WithLogger(myCustomLogger)
+//
+// Returns self for chaining.
+func (b *DBBuilder) WithLogger(logger Logger) *DBBuilder {
+	if logger != nil {
+		b.logger = logger
+	}
+	return b
+}
+
 // AddFS adds files from an embedded filesystem (go:embed).
 //
 // Automatically finds all CSV, TSV, and LTSV files in the filesystem.
@@ -254,6 +279,8 @@ func (b *DBBuilder) DisableAutoSave() *DBBuilder {
 //
 // Returns the same builder instance for method chaining, or an error if validation fails.
 func (b *DBBuilder) Build(ctx context.Context) (*DBBuilder, error) {
+	b.logger.Debug("starting build", "paths", len(b.paths), "filesystems", len(b.filesystems), "readers", len(b.readers))
+
 	// Validate that we have at least one input
 	if len(b.paths) == 0 && len(b.filesystems) == 0 && len(b.readers) == 0 {
 		return nil, fmt.Errorf("%w: at least one path must be provided", ErrNoFiles)
@@ -290,6 +317,11 @@ func (b *DBBuilder) Build(ctx context.Context) (*DBBuilder, error) {
 		return nil, err
 	}
 
+	// Pass logger to internal processors
+	b.streamProcessor.setLogger(b.logger)
+	b.fileProcessor.setLogger(b.logger)
+
+	b.logger.Info("build completed", "collected_paths", len(b.collectedPaths), "readers", len(b.readers))
 	return b, nil
 }
 
@@ -311,6 +343,8 @@ func (b *DBBuilder) Build(ctx context.Context) (*DBBuilder, error) {
 //
 // Returns a *sql.DB connection or an error if the database cannot be created.
 func (b *DBBuilder) Open(ctx context.Context) (*sql.DB, error) {
+	b.logger.Debug("opening database")
+
 	// Use validator to validate inputs availability
 	if err := b.validator.validateInputsAvailable(b.collectedPaths, b.readers); err != nil {
 		return nil, err
@@ -319,18 +353,22 @@ func (b *DBBuilder) Open(ctx context.Context) (*sql.DB, error) {
 	// Use file processor to deduplicate compressed files
 	b.collectedPaths = b.fileProcessor.deduplicateCompressedFiles(b.collectedPaths)
 
+	b.logger.Debug("creating in-memory database")
 	db, err := b.createInMemoryDatabase()
 	if err != nil {
+		b.logger.Error("failed to create database", "error", err)
 		return nil, err
 	}
 
 	// Use stream processor for all streaming operations (now includes XLSX support)
 	if err := b.streamProcessor.streamAllFilesToDatabase(ctx, db, b.collectedPaths); err != nil {
+		b.logger.Error("failed to stream files", "error", err)
 		_ = db.Close() // Ignore close error during error handling
 		return nil, err
 	}
 
 	if err := b.streamProcessor.streamAllReadersToDatabase(ctx, db, b.readers); err != nil {
+		b.logger.Error("failed to stream readers", "error", err)
 		_ = db.Close() // Ignore close error during error handling
 		return nil, err
 	}
@@ -345,6 +383,7 @@ func (b *DBBuilder) Open(ctx context.Context) (*sql.DB, error) {
 		return nil, err
 	}
 
+	b.logger.Info("database opened successfully")
 	return db, nil
 }
 

doc/es/README.md

@@ -317,6 +317,69 @@ parquetOptions := filesql.NewDumpOptions().
 // Nota: La funcionalidad de exportación está implementada (compresión externa no soportada, use la compresión integrada de Parquet)
 ```
 
+### Logger Personalizado
+
+filesql soporta logging conectable a través de la interfaz `Logger`. Por defecto, se usa un logger no-op con cero sobrecarga de rendimiento. Puedes inyectar tu propio logger (por ejemplo, `slog`) para depuración y monitoreo.
+
+```go
+import (
+    "log/slog"
+    "os"
+    "github.com/nao1215/filesql"
+)
+
+// Crear un logger slog
+slogLogger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+    Level: slog.LevelDebug,
+}))
+
+// Envolverlo con SlogAdapter y pasarlo al builder
+logger := filesql.NewSlogAdapter(slogLogger)
+
+validatedBuilder, err := filesql.NewBuilder().
+    WithLogger(logger).
+    AddPath("data.csv").
+    Build(ctx)
+```
+
+#### Interfaz Logger
+
+```go
+type Logger interface {
+    Debug(msg string, args ...any)
+    Info(msg string, args ...any)
+    Warn(msg string, args ...any)
+    Error(msg string, args ...any)
+    With(args ...any) Logger
+}
+```
+
+#### Logger con Contexto
+
+Para logging con contexto, usa `ContextLogger`:
+
+```go
+type ContextLogger interface {
+    Logger
+    DebugContext(ctx context.Context, msg string, args ...any)
+    InfoContext(ctx context.Context, msg string, args ...any)
+    WarnContext(ctx context.Context, msg string, args ...any)
+    ErrorContext(ctx context.Context, msg string, args ...any)
+}
+
+// Usa SlogContextAdapter para logging con contexto
+logger := filesql.NewSlogContextAdapter(slogLogger)
+```
+
+#### Rendimiento
+
+| Tipo de Logger | Rendimiento | Memoria |
+|----------------|-------------|---------|
+| nopLogger (por defecto) | ~0.2 ns/op | 0 B/op |
+| SlogAdapter | ~1000 ns/op | ~630 B/op |
+
+El logger no-op por defecto tiene prácticamente cero sobrecarga, haciendo seguro dejar llamadas de logging en código de producción.
+
 ## Reglas de nomenclatura de tablas
 
 filesql deriva automáticamente los nombres de las tablas de las rutas de archivo:

doc/fr/README.md

@@ -317,6 +317,69 @@ parquetOptions := filesql.NewDumpOptions().
 // Note: L'exportation Parquet est implémentée (compression externe non supportée, utilisez la compression intégrée de Parquet)
 ```
 
+### Logger Personnalisé
+
+filesql supporte le logging modulaire via l'interface `Logger`. Par défaut, un logger no-op est utilisé avec zéro surcharge de performance. Vous pouvez injecter votre propre logger (par exemple, `slog`) pour le débogage et la surveillance.
+
+```go
+import (
+    "log/slog"
+    "os"
+    "github.com/nao1215/filesql"
+)
+
+// Créer un logger slog
+slogLogger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+    Level: slog.LevelDebug,
+}))
+
+// L'envelopper avec SlogAdapter et le passer au builder
+logger := filesql.NewSlogAdapter(slogLogger)
+
+validatedBuilder, err := filesql.NewBuilder().
+    WithLogger(logger).
+    AddPath("data.csv").
+    Build(ctx)
+```
+
+#### Interface Logger
+
+```go
+type Logger interface {
+    Debug(msg string, args ...any)
+    Info(msg string, args ...any)
+    Warn(msg string, args ...any)
+    Error(msg string, args ...any)
+    With(args ...any) Logger
+}
+```
+
+#### Logger avec Contexte
+
+Pour le logging avec contexte, utilisez `ContextLogger` :
+
+```go
+type ContextLogger interface {
+    Logger
+    DebugContext(ctx context.Context, msg string, args ...any)
+    InfoContext(ctx context.Context, msg string, args ...any)
+    WarnContext(ctx context.Context, msg string, args ...any)
+    ErrorContext(ctx context.Context, msg string, args ...any)
+}
+
+// Utilisez SlogContextAdapter pour le logging avec contexte
+logger := filesql.NewSlogContextAdapter(slogLogger)
+```
+
+#### Performance
+
+| Type de Logger | Performance | Mémoire |
+|----------------|-------------|---------|
+| nopLogger (par défaut) | ~0.2 ns/op | 0 B/op |
+| SlogAdapter | ~1000 ns/op | ~630 B/op |
+
+Le logger no-op par défaut a pratiquement zéro surcharge, rendant sûr de laisser les appels de logging dans le code de production.
+
 ## Règles de nommage des tables
 
 filesql dérive automatiquement les noms de tables des chemins de fichiers :