feat: add --sample-database flag for initializing embedded emulator with official samples (#472)

Adds the ability to initialize the embedded Spanner emulator with pre-populated official sample databases, streamlining development and testing workflows.

Key features:
- Adds --sample-database flag to load official Google samples (banking, finance, finance-graph, finance-pg, gaming)
- Adds --list-samples flag to show available sample databases
- Supports flexible URI-based loading (gs://, file://, https://) for extensibility
- Integrates with spanemuboost for DDL/DML initialization
- Handles both GoogleSQL and PostgreSQL dialects automatically

Implementation:
- Uses Go's native Cloud Storage client for GCS access
- Downloads schema and data files directly without caching
- Validates that --embedded-emulator is used with --sample-database
- Provides clear error messages and initialization feedback

This feature enables users to quickly start with realistic sample data for testing, demos, and learning Spanner capabilities without manual database setup.

Fixes #470

Author: apstndb

.gemini/styleguide.md

@@ -45,6 +45,38 @@ err3 := fmt.Errorf("first: %w, second: %w", err1, err2)                // Valid
 
 Reference: https://go.dev/doc/go1.20#errors
 
+### WaitGroup.Go Method (Go 1.25+)
+
+Since Go 1.25, `sync.WaitGroup` has a new `Go` method that simplifies concurrent task management:
+
+- **`WaitGroup.Go(f func())`** starts a goroutine and automatically manages Add/Done
+- Eliminates the need for manual `wg.Add(1)` and `defer wg.Done()` calls
+- Makes concurrent code cleaner and less error-prone
+
+**DO NOT** suggest that `sync.WaitGroup` doesn't have a `Go` method when reviewing Go 1.25+ code:
+
+```go
+// Go 1.25+ simplified pattern
+var wg sync.WaitGroup
+wg.Go(func() {
+    // Task executes in goroutine
+    // No need for Add(1) or defer Done()
+    doWork()
+})
+wg.Wait()
+
+// Old pattern (still valid but more verbose)
+var wg sync.WaitGroup
+wg.Add(1)
+go func() {
+    defer wg.Done()
+    doWork()
+}()
+wg.Wait()
+```
+
+Reference: https://pkg.go.dev/sync#WaitGroup.Go
+
 ### Other Go Best Practices
 
 - Follow standard Go idioms and conventions

CLAUDE.md

@@ -407,5 +407,9 @@ go tool cover -html=tmp/coverage.out         # Generate HTML coverage report (de
 - **Backward Compatibility**: Not required since spanner-mycli is not used as an external library
 - **No Future-Proofing**: Since spanner-mycli is not used as a library, don't add parameters or abstractions for potential future use. Only implement what's needed now.
 - **Issue Management**: All fixes must go through Pull Requests - never close issues manually
+- **License Headers**: 
+  - For new files created after the fork from spanner-cli: Use "Copyright [year] apstndb"
+  - For existing files that originated from spanner-cli: Keep "Copyright [year] Google LLC"
+  - This applies to all new logic and features added to spanner-mycli after forking
 
 For any detailed information not covered here, refer to the appropriate documentation in `dev-docs/` or `docs/`.

README.md

@@ -142,6 +142,8 @@ spanner:
       --embedded-emulator                                 Use embedded Cloud Spanner Emulator. --project, --instance, --database, --endpoint, --insecure will be automatically configured.
       --emulator-image=                                   container image for --embedded-emulator
       --emulator-platform=                                Container platform (e.g. linux/amd64, linux/arm64) for embedded emulator
+      --sample-database=                                  Initialize emulator with specified sample database (banking, finance, finance-graph, finance-pg, gaming). Requires --embedded-emulator.
+      --list-samples                                      List available sample databases and exit
       --output-template=                                  Filepath of output template. (EXPERIMENTAL)
       --log-level=
       --log-grpc                                          Show gRPC logs
@@ -1066,6 +1068,41 @@ emulator-project:emulator-instance:emulator-database
 Empty set (8.763167ms)
 ```
 
+#### Sample Databases
+
+You can initialize the emulator with Google's official sample databases using the `--sample-database` flag:
+
+```bash
+# List available sample databases
+$ spanner-mycli --list-samples
+Available sample databases:
+
+  banking        GoogleSQL    Banking application with accounts and transactions
+  finance        GoogleSQL    Finance application schema (GoogleSQL)
+  finance-graph  GoogleSQL    Finance application with graph features
+  finance-pg     PostgreSQL   Finance application (PostgreSQL dialect)
+  gaming         GoogleSQL    Gaming application with players and scores
+
+Usage: spanner-mycli --embedded-emulator --sample-database=<name>
+
+# Start with the banking sample database
+$ spanner-mycli --embedded-emulator --sample-database=banking
+emulator-project:emulator-instance:emulator-database
+> SELECT COUNT(*) AS count FROM Accounts;
++-------+
+| count |
+| INT64 |
++-------+
+| 10    |
++-------+
+1 rows in set (2.76 ms)
+
+# Use PostgreSQL sample
+$ spanner-mycli --embedded-emulator --sample-database=finance-pg
+```
+
+The sample databases are automatically downloaded from Google Cloud Storage and initialized when the emulator starts. This provides realistic test data for development and demonstrations.
+
 > [!NOTE]
 > The embedded emulator has the same limitations as the standalone emulator. See the warning in the [Using with the Cloud Spanner Emulator](#using-with-the-cloud-spanner-emulator) section above for details.
 

cli.go

@@ -263,32 +263,10 @@ func (c *Cli) updateSystemVariables(result *Result) {
 
 // executeSourceFile executes SQL statements from a file
 func (c *Cli) executeSourceFile(ctx context.Context, filePath string) error {
-	// Open the file to get a stable file handle
-	f, err := os.Open(filePath)
+	// Use common file safety checks (nil uses DefaultMaxFileSize - 100MB)
+	contents, err := SafeReadFile(filePath, nil)
 	if err != nil {
-		return fmt.Errorf("failed to open file %s: %w", filePath, err)
-	}
-	defer f.Close()
-
-	// Check if the file is a regular file to prevent DoS from special files
-	fi, err := f.Stat()
-	if err != nil {
-		return fmt.Errorf("failed to stat file %s: %w", filePath, err)
-	}
-	if !fi.Mode().IsRegular() {
-		return fmt.Errorf("sourcing from a non-regular file is not supported: %s", filePath)
-	}
-
-	// Add a check to prevent reading excessively large files.
-	const maxFileSize = 100 * 1024 * 1024 // 100MB
-	if fi.Size() > maxFileSize {
-		return fmt.Errorf("file %s is too large to be sourced (size: %d bytes, max: %d bytes)", filePath, fi.Size(), maxFileSize)
-	}
-
-	// Read the file contents from the opened handle
-	contents, err := io.ReadAll(f)
-	if err != nil {
-		return fmt.Errorf("failed to read file %s: %w", filePath, err)
+		return err
 	}
 
 	// Parse the contents using buildCommands (same as batch mode)

cli_test.go

@@ -1578,8 +1578,8 @@ func TestCli_executeSourceFile_NonExistentFile(t *testing.T) {
 	err := cli.executeSourceFile(context.Background(), "/non/existent/file.sql")
 	if err == nil {
 		t.Error("Expected error for non-existent file")
-	} else if !strings.Contains(err.Error(), "failed to open file") {
-		t.Errorf("Expected error to contain 'failed to open file', got: %v", err)
+	} else if !strings.Contains(err.Error(), "no such file or directory") {
+		t.Errorf("Expected error to contain 'no such file or directory', got: %v", err)
 	}
 }
 
@@ -1599,8 +1599,8 @@ func TestCli_executeSourceFile_NonRegularFile(t *testing.T) {
 	err := cli.executeSourceFile(context.Background(), "/dev/null")
 	if err == nil {
 		t.Error("Expected error for non-regular file")
-	} else if !strings.Contains(err.Error(), "sourcing from a non-regular file is not supported") {
-		t.Errorf("Expected error to contain 'sourcing from a non-regular file is not supported', got: %v", err)
+	} else if !strings.Contains(err.Error(), "cannot read") {
+		t.Errorf("Expected error to contain 'cannot read', got: %v", err)
 	}
 }
 
@@ -1636,7 +1636,7 @@ func TestCli_executeSourceFile_FileTooLarge(t *testing.T) {
 	err = cli.executeSourceFile(context.Background(), tmpFile.Name())
 	if err == nil {
 		t.Error("Expected error for file too large")
-	} else if !strings.Contains(err.Error(), "is too large to be sourced") {
-		t.Errorf("Expected error to contain 'is too large to be sourced', got: %v", err)
+	} else if !strings.Contains(err.Error(), "too large") {
+		t.Errorf("Expected error to contain 'too large', got: %v", err)
 	}
 }

file_safety.go

@@ -0,0 +1,92 @@
+//
+// Copyright 2025 apstndb
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+const (
+	// DefaultMaxFileSize is the default maximum file size for safety checks (100MB)
+	DefaultMaxFileSize = 100 * 1024 * 1024 // 100MB
+
+	// SampleDatabaseMaxFileSize is the maximum file size for sample database files (10MB)
+	// Sample databases should be smaller since they're downloaded from remote sources
+	SampleDatabaseMaxFileSize = 10 * 1024 * 1024 // 10MB
+)
+
+// FileSafetyOptions configures file safety checks
+type FileSafetyOptions struct {
+	// MaxSize is the maximum allowed file size (0 means use DefaultMaxFileSize)
+	MaxSize int64
+	// AllowNonRegular allows reading from non-regular files (not recommended)
+	AllowNonRegular bool
+}
+
+// ValidateFileSafety checks if a file is safe to read based on the given options
+func ValidateFileSafety(fi os.FileInfo, path string, opts *FileSafetyOptions) error {
+	if opts == nil {
+		opts = &FileSafetyOptions{}
+	}
+
+	maxSize := opts.MaxSize
+	if maxSize == 0 {
+		maxSize = DefaultMaxFileSize
+	}
+
+	// Check for special files (devices, named pipes, sockets, etc.)
+	if !opts.AllowNonRegular {
+		if !fi.Mode().IsRegular() {
+			// Check specific modes for better error messages
+			mode := fi.Mode()
+			switch {
+			case mode&os.ModeDevice != 0:
+				return fmt.Errorf("cannot read device file %s", path)
+			case mode&os.ModeNamedPipe != 0:
+				return fmt.Errorf("cannot read named pipe %s", path)
+			case mode&os.ModeSocket != 0:
+				return fmt.Errorf("cannot read socket file %s", path)
+			case mode&os.ModeCharDevice != 0:
+				return fmt.Errorf("cannot read character device %s", path)
+			default:
+				return fmt.Errorf("cannot read special file %s (mode: %v)", path, mode)
+			}
+		}
+	}
+
+	// Check file size
+	if fi.Size() > maxSize {
+		return fmt.Errorf("file %s too large: %d bytes (max %d)", path, fi.Size(), maxSize)
+	}
+
+	return nil
+}
+
+// SafeReadFile reads a file after performing safety checks
+func SafeReadFile(path string, opts *FileSafetyOptions) ([]byte, error) {
+	fi, err := os.Stat(path)
+	if err != nil {
+		return nil, fmt.Errorf("failed to stat file %s: %w", path, err)
+	}
+
+	if err := ValidateFileSafety(fi, path, opts); err != nil {
+		return nil, err
+	}
+
+	return os.ReadFile(path)
+}