Deprecate generation from Information Schema

Generation from Information Schema in the Spanner Emulator does not maintain column order.
This makes it difficult to ensure consistent generation results.
Generating from DDL should be the primary choice considering development workflow and ease of use.
Ref: #154

Author: sinmetal

README.md

@@ -3,7 +3,11 @@
 `yo` is a command-line tool to generate Go code for [Google Cloud Spanner](https://cloud.google.com/spanner/),
 forked from [xo](https://github.com/xo/xo) :rose:.
 
-`yo` uses database schema to generate code by using [Information Schema](https://cloud.google.com/spanner/docs/information-schema). `yo` runs SQL queries against tables in `INFORMATION_SCHEMA` to fetch metadata for a database, and applies the metadata to Go templates to generate code/models to access Cloud Spanner.
+`yo` can generate code from database schema using either DDL files or [Information Schema](https://cloud.google.com/spanner/docs/information-schema).
+
+**⚠️ Note: Using Information Schema for code generation is now deprecated due to column ordering issues (see [#154](https://github.com/cloudspannerecosystem/yo/issues/154)). Please use DDL files for reliable code generation instead.**
+
+When using Information Schema, `yo` runs SQL queries against tables in `INFORMATION_SCHEMA` to fetch metadata for a database. When using DDL files (recommended), `yo` parses the DDL directly. In both cases, the metadata is applied to Go templates to generate code/models to access Cloud Spanner.
 
 Please feel free to report issues and send pull requests, but note that this
 application is not officially supported as part of the Cloud Spanner product.
@@ -24,14 +28,24 @@ go get -u go.mercari.io/yo
 
 The following is a quick overview of using `yo` on the command-line:
 
+**Recommended: Generate from DDL file**
 ```sh
 # change to project directory
 $ cd $GOPATH/src/path/to/project
 
 # make an output directory
 $ mkdir -p models
 
-# generate code for a schema
+# generate code from DDL file (recommended)
+$ yo generate schema.sql --from-ddl -o models
+```
+
+**⚠️ Deprecated: Generate from Information Schema**
+```sh
+# make an output directory
+$ mkdir -p models
+
+# generate code from Information Schema (deprecated - see issue #154)
 $ yo $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models
 ```
 
@@ -47,16 +61,16 @@ Usage:
   yo PROJECT_NAME INSTANCE_NAME DATABASE_NAME [flags]
 
 Examples:
-  # Generate models from DDL under the models directory
-  yo generate schame.sql --from-ddl -o models
-  
-  # Generate models from DDL under the models directory with custom types
-  yo generate schame.sql --from-ddl -o models --custom-types-file custom_column_types.yml
-  
-  # Generate models under models directory
+  # Generate models from DDL under the models directory (recommended)
+  yo generate schema.sql --from-ddl -o models
+
+  # Generate models from DDL under the models directory with custom types (recommended)
+  yo generate schema.sql --from-ddl -o models --custom-types-file custom_column_types.yml
+
+  # Generate models under models directory (deprecated - see issue #154)
   yo $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models
 
-  # Generate models under models directory with custom types
+  # Generate models under models directory with custom types (deprecated - see issue #154)
   yo $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models --custom-types-file custom_column_types.yml
 
 Flags:

cmd/generate.go

@@ -21,6 +21,7 @@ package cmd
 
 import (
 	"fmt"
+	"os"
 
 	"github.com/spf13/cobra"
 	"go.mercari.io/yo/generator"
@@ -39,16 +40,16 @@ var (
 			}
 			return nil
 		},
-		Example: `  # Generate models from ddl under models directory
+		Example: `  # Generate models from ddl under models directory (recommended)
   yo generate schema.sql --from-ddl -o models
 
-  # Generate models from ddl under models directory with custom types
+  # Generate models from ddl under models directory with custom types (recommended)
   yo generate schema.sql --from-ddl -o models --custom-types-file custom_column_types.yml
 
-  # Generate models under models directory
+  # Generate models under models directory (deprecated - see issue #154)
   yo generate $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models
 
-  # Generate models under models directory with custom types
+  # Generate models under models directory with custom types (deprecated - see issue #154)
   yo generate $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models --custom-types-file custom_column_types.yml
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -68,6 +69,7 @@ var (
 				}
 				loader = internal.NewTypeLoader(spannerLoader, inflector)
 			} else {
+				fmt.Fprintf(os.Stderr, "Warning: Using Information Schema for code generation is deprecated due to column ordering issues (see https://github.com/cloudspannerecosystem/yo/issues/154). Please use DDL files for reliable code generation instead.\n")
 				spannerClient, err := connectSpanner(&rootOpts)
 				if err != nil {
 					return fmt.Errorf("error: %v", err)

v2/README.md

@@ -3,7 +3,11 @@
 `yo` is a command-line tool to generate Go code for [Google Cloud Spanner](https://cloud.google.com/spanner/),
 forked from [xo](https://github.com/xo/xo) :rose:.
 
-`yo` uses database schema to generate code by using [Information Schema](https://cloud.google.com/spanner/docs/information-schema). `yo` runs SQL queries against tables in `INFORMATION_SCHEMA` to fetch metadata for a database and applies the metadata to Go templates to generate code/models to access Cloud Spanner.
+`yo` can generate code from database schema using either DDL files or [Information Schema](https://cloud.google.com/spanner/docs/information-schema).
+
+**⚠️ Note: Using Information Schema for code generation is now deprecated due to column ordering issues (see [#154](https://github.com/cloudspannerecosystem/yo/issues/154)). Please use DDL files for reliable code generation instead.**
+
+When using Information Schema, `yo` runs SQL queries against tables in `INFORMATION_SCHEMA` to fetch metadata for a database. When using DDL files (recommended), `yo` parses the DDL directly. In both cases, the metadata is applied to Go templates to generate code/models to access Cloud Spanner.
 
 Please feel free to report issues and send pull requests, but note that this
 application is not officially supported as part of the Cloud Spanner product.
@@ -18,14 +22,24 @@ $ go get -u go.mercari.io/yo/v2
 
 The following is a quick overview of using `yo` on the command line:
 
+**Recommended: Generate from DDL file**
 ```sh
 # change to the project directory
 $ cd $GOPATH/src/path/to/project
 
 # make an output directory
 $ mkdir -p models
 
-# generate code for a schema
+# generate code from DDL file (recommended)
+$ yo generate schema.sql --from-ddl -o models
+```
+
+**⚠️ Deprecated: Generate from Information Schema**
+```sh
+# make an output directory
+$ mkdir -p models
+
+# generate code from Information Schema (deprecated - see issue #154)
 $ yo generate $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models
 ```
 
@@ -38,17 +52,17 @@ The `generate` command generates the Go code from DDL.
 #### Examples
 
 ```sh
-# Generate models from DDL under the models directory
+# Generate models from DDL under the models directory (recommended)
 yo generate schema.sql --from-ddl -o models
 
-# Generate models from DDL under the models directory with custom types
-yo generate schema.sql --from-ddl -o models --custom-types-file custom_column_types.yml
+# Generate models from DDL under the models directory with custom types (recommended)
+yo generate schema.sql --from-ddl -o models --config config.yml
 
-# Generate models under the models directory
+# Generate models under the models directory (deprecated - see issue #154)
 yo generate $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models
 
-# Generate models under the models directory with custom types
-yo generate $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models --custom-types-file custom_column_types.yml
+# Generate models under the models directory with custom types (deprecated - see issue #154)
+yo generate $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models --config config.yml
 ```
 
 #### Flags

v2/cmd/generate.go

@@ -112,17 +112,17 @@ var (
 			}
 			return nil
 		},
-		Example: `  # Generate models from DDL under the models directory
+		Example: `  # Generate models from DDL under the models directory (recommended)
   yo generate schema.sql --from-ddl -o models
 
-  # Generate models from DDL under the models directory with custom types
-  yo generate schema.sql --from-ddl -o models --custom-types-file custom_column_types.yml
+  # Generate models from DDL under the models directory with custom types (recommended)
+  yo generate schema.sql --from-ddl -o models --config config.yml
 
-  # Generate models under the models directory
+  # Generate models under the models directory (deprecated - see issue #154)
   yo generate $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models
 
-  # Generate models under the models directory with custom types
-  yo generate $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models --custom-types-file custom_column_types.yml
+  # Generate models under the models directory with custom types (deprecated - see issue #154)
+  yo generate $SPANNER_PROJECT_NAME $SPANNER_INSTANCE_NAME $SPANNER_DATABASE_NAME -o models --config config.yml
 `,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
@@ -149,6 +149,7 @@ var (
 					return fmt.Errorf("failed to create spanner loader: %v", err)
 				}
 			} else {
+				fmt.Fprintf(os.Stderr, "Warning: Using Information Schema for code generation is deprecated due to column ordering issues (see https://github.com/cloudspannerecosystem/yo/issues/154). Please use DDL files for reliable code generation instead.\n")
 				spannerClient, err := connectSpanner(ctx, generateCmdOpts.Project, generateCmdOpts.Instance, generateCmdOpts.Database)
 				if err != nil {
 					return fmt.Errorf("failed to connect spanner: %v", err)