Forem: apstndb

Is Spanner Really That Expensive? The Surprising Break-Even Point with Firestore

apstndb — Mon, 14 Jul 2025 02:07:50 +0000

Note from the author: This article was originally written in Japanese for the community in Japan. The original version can be found here. Believing the content could be valuable to a global audience, I've translated it into English. The translation was performed with the assistance of Google's Gemini 2.5 Pro. I have reviewed and edited the translation for accuracy and clarity.

A recent article on the tech blog of KAUCHE, a Japanese e-commerce company, "Firestore → Cloud Spanner DB Cost Reduction of 93%! The Complete Record of a Year-Long Zero-Downtime Migration" (in Japanese), has been making waves.
Anyone who has used Firestore (or its predecessor, Datastore) knows that beyond a certain usage level, it can become more expensive than Spanner. However, database migrations are notoriously difficult, so many users likely remain on Firestore despite the cost. The fact that KAUCHE accomplished a zero-downtime migration from Firestore to Spanner is truly impressive.

Interestingly, looking at the reactions to this article, I noticed a common thread of surprise that migrating from Firestore to Spanner could actually reduce costs.

https://x.com/search?q=https%3A%2F%2Fzenn.dev%2Fkauche%2Farticles%2F1e733da3748ee1&src=typed_query&f=live

Why does this surprise exist, when there are options within Google Cloud like Firestore that can become significantly more expensive than Spanner? I believe it's because Firestore offers a generous daily free tier, making it easy to start small, while Spanner has no free tier and is plagued by a persistent preconception that it is "expensive."

This misconception can hinder optimal technology choices, leading to lost opportunities for developers, businesses, and even Google. It can cause tangible financial harm and create significant technical debt by forcing a difficult database migration in the future.

Google itself has been trying to dispel this myth, publishing articles like "Cloud Spanner myths busted" and holding sessions like the "Spanner: Database Unlimited Series" based on it.

Why did this "expensive" image stick?
As Google's article mentions, it's likely due to outdated impressions:

High minimum cost for production instances with an SLA: It used to require a minimum of 3 nodes, costing around $2,000/month even in the cheapest us-central1 region.

In September 2019, this was reduced to 1 node with an SLA, cutting the cost by two-thirds.

With granular instance sizing (GA in May 2022), it became possible to get an SLA with just 0.1 nodes (100 PUs), reducing the cost by another factor of 10.

The cost is now comparable to a Cloud SQL db-g1-small instance with an HA configuration.

No free development environment: Since it's not open-source, development environments incurred similar costs.

This has been addressed with the official Spanner emulator (GA in July 2020) and free trial instances (GA in September 2022).

Despite these efforts, the message may not have fully resonated without concrete numbers. And comparing it to competitor products is often frowned upon.

So, I thought, why not do a quantitative comparison between Google Cloud's own database offerings? There seems to be value in making that public.

Firestore vs. Spanner: A Price Comparison

In this article, I'll perform a price comparison between Firestore and Spanner, inspired by the cost issues highlighted by KAUCHE's experience.

A few notes on the comparison:

This is a simplified comparison focusing only on Firestore and Spanner among Google Cloud's database offerings.

I'll assume Firestore is used as a backend database. The differences between Native mode and Datastore mode are not critical to the conclusion.

I will not compare them with services from other cloud providers.

This is not a general SQL vs. NoSQL or SQL vs. Distributed SQL comparison.

The comparison is based solely on information from the official documentation.

No load testing is involved.

Since a key goal is to raise awareness, I will be direct about the cost challenges of Firestore, based on the data.

Extracting Relevant Values from Official Docs

All values are as of July 9, 2025.
The region is standardized to asia-northeast1 (Tokyo).
Currency is kept in USD to avoid exchange rate fluctuations.
Committed Use Discounts (CUDs) are omitted as they are the same for both Firestore and Spanner (20% for 1 year, 40% for 3 years) and don't affect the relative comparison.
Network egress fees are the same for both and are not included in this comparison's scope, though they can affect the total cost.

Firestore

Firestore is entirely pay-as-you-go, so all the pricing information is on one page.

Native mode and Datastore mode have slightly different terminology but the same pricing structure. I'll use the newer Native mode terms.

Firestore Native mode	Datastore mode	Free usage	Cost
Document reads	Entity reads	50,000 per day	$0.038 per 100,000 entities/documents
Document writes	Entity writes	20,000 per day	$0.115 per 100,000 entities/documents
Document/TTL deletes	Entity/TTL deletes	20,000 per day	$0.013 per 100,000 entities/documents
Stored data	Stored data	1 GiB	$0.115/GiB/month
PITR data	PITR data	N/A	$0.115/GiB/month
Backup data	Backup data	N/A	$0.038/GiB/month
Restore operation	Restore operation	N/A	$0.256/GiB
N/A	Small operations	50,000 per day	Free

Note: Firestore Native mode doesn't have "small operations." Index entry reads and aggregation queries are counted as one document read per 1,000 entries. Also, the Firestore editions overview states that the Standard edition uses Hybrid storage (SSD & HDD).

Spanner

Spanner is billed based on provisioned capacity in Processing Units (PUs). We need to look at two pages:

Compute Capacity

Edition	Cost per node (including all three replicas)
Standard	$1.17 per hour
Enterprise	$1.599 per hour
Enterprise Plus	$2.223 per hour

The features in the Standard edition are sufficient for this comparison, so I'll focus on that.

Database Storage

Storage Type	Cost per GB (including all three replicas)
SSD	$0.39 per GB per month
HDD	$0.078 per GB per month

I'll focus on SSD storage for this comparison.

Estimated Throughput from Docs

While database performance typically requires workload-specific benchmarks, Spanner provides estimated throughput for simple workloads in its documentation. This is a reasonable approximation for a comparison with Firestore, which is primarily used for key-based reads and writes without complex queries.

Read guidance is given per region (because reads can be served from any read-write or read-only region), while write guidance is for the entire configuration. Read guidance assumes you're reading single rows of 1KB. Write guidance assumes that you're writing single rows at 1KB of data per row.

Here is the estimated throughput for a regional configuration like asia-northeast1:

Performance for regional configurations
Each 1,000 processing units (1 node) of compute capacity can provide the following peak performance (at 100% CPU) in a regional instance configuration:

Peak reads (QPS per region)	Peak writes (QPS total)
SSD: 22,500 HDD: 1,500	or SSD: 3,500 HDD: 3,500

I'll use the highlighted SSD values.

(Note) This catalog spec has improved significantly. An announcement on October 11, 2023 detailed Performance and storage improvements, boosting typical throughput by 1.5x for both reads and writes and increasing the storage limit by 2.5x. If you want to verify these numbers, you can check the YCSB benchmark results in "Benchmarking Spanner's cost-performance for key-value workloads".

Spanner's Minimum Configuration: Price and Throughput

A Spanner instance can be created with as little as 100 Processing Units (PUs), which is 0.1 nodes. This configuration is production-ready and comes with an SLA. Here are the adjusted numbers for this minimum setup:

Item	Value
Standard edition cost (100 PU)	$0.117 per hour
Peak reads (QPS per region)	2,250
Peak writes (QPS total)	350

This is at 100% CPU utilization. However, the official documentation (Alerts for high CPU utilization) recommends keeping CPU utilization for high-priority tasks below 65% for regional instances. I will factor this into the comparison.

Why 65%? While not explicitly stated, this is likely to maintain service levels during a zonal failure. A regional Spanner instance has R/W replicas in three zones. If one zone goes down, you lose 1/3 of your capacity. To handle the same load, the remaining 2/3 of capacity (approx. 67%) must suffice. Staying at 65% ensures that a zone failure won't push CPU usage over 100%. This logic also explains the 45% recommendation for dual/multi-region instances, which have replicas in two R/W regions (losing one leaves 50% capacity).

The Comparison

Let's find the break-even point between the minimum Spanner configuration and Firestore.

I'll assume a steady workload of either 1KB reads only or 1KB writes only.
I'll assume the schema is well-designed to achieve theoretical performance.
I'll include Firestore's daily free tier.
I'll factor in Spanner's 65% recommended CPU utilization.

The break-even point is where Firestore Cost = Spanner Cost. We can find the number of daily operations, x, with the formula:

\frac{C_{\text{spanner}}}{P_{\text{firestore}}} + F_{\text{free}}

Variables:

$x$ = Number of operations per day (what we want to find)
$FfreeF_{\text{free}}$ = Firestore free tier operations (Reads: 50,000, Writes: 20,000)
$PfirestoreP_{\text{firestore}}$ = Firestore price per operation (Read: \$0.00000038/op, Write: \$0.00000115/op)
$CspannerC_{\text{spanner}}$ = Spanner daily cost (100 PU = \$0.117/hr * 24h = \$2.808/day)

To be more precise: The above formula is a simplification. To be perfectly accurate, you need to account for Firestore's 100,000-operation billing increments. The break-even point x is more accurately calculated with the following formula:

F_{\text{free}} + \lceil\frac{C_{\text{spanner}}/P_{\text{firestore}}}{100,000}\rceil \times 100,000

Here are the results, visualized with graphs. The plots are continuous approximations for simplicity, but the break-even point calculations are precise.

Reads

The break-even point for reads is 7,450,000 reads/day, which is about 86 reads/sec.
This is only 3.8% of the peak performance of a 100 PU Spanner instance.

If you utilize Spanner up to the recommended 65% of its theoretical throughput, it becomes 17 times cheaper than Firestore. This clearly shows how sticking with Firestore at scale can lead to massive cost increases.

Writes

The break-even point for writes is 2,520,000 writes/day, which is about 29 writes/sec.
This is about 8.1% of the peak performance of a 100 PU Spanner instance.

If you utilize Spanner up to the recommended 65% of its throughput, it is 8 times cheaper than Firestore.

Storage

A direct storage cost comparison is difficult because Firestore uses hybrid storage. However, we can get a rough idea. A 100 PU Spanner instance has a storage limit of 1024 GiB.

Service	Unit Price (per GiB per month)	Monthly Price (for 1024 GiB)
Spanner	$0.39	$399.36
Firestore	$0.115	$117.76
Ratio		339%
Diff		$281.6

While Spanner's storage unit price is higher, the difference is not the dominant factor. In a scenario where you are maxing out the read/write capacity of a 100 PU instance, the daily cost difference for operations is in the tens of dollars, which far outweighs the storage cost difference.

Analysis

The calculations show that while Spanner isn't always cheaper, it becomes significantly more cost-effective than Firestore beyond a certain scale. This isn't surprising. Both databases offer strong consistency and high availability through geographic distribution, making them comparable services. The main differences are the data model and the billing model.

Generally, provisioned capacity is discounted relative to on-demand, pay-per-operation pricing.

In fact, Firestore and Spanner are more than just similar. It has been suggested since Firestore's launch, and later confirmed in Google research papers, that Firestore is implemented on top of Spanner. The architecture of Firestore is detailed in the "Firestore: The NoSQL Serverless Database for the Application Developer" paper, and its implementation on Spanner is further described in "Transparent Migration of Datastore to Firestore".

In other words, Firestore is a high-value managed service that abstracts away complexities like query planning and capacity management by offering Spanner's powerful infrastructure on a multi-tenant basis, which provides an easy, free-to-start experience. The price difference at scale can be seen as the cost of this abstraction.

To Anyone Considering Firestore

If you're considering Firestore for your backend, keep these points in mind:

Firestore's cost advantage is limited to a relatively narrow range for a horizontally scaling database: from the free tier up to a few million operations per day.
Be aware that costs will scale with number of users × operations per user.
If your service has a fixed number of users (e.g., an internal tool), Firestore is likely a safe choice. Otherwise, always evaluate the possibility that Spanner will become cheaper.
If your service can justify the monthly cost of a 100 PU Spanner instance (approx. $85/month), choosing Spanner from the start might give you more peace of mind.

For real-time database use cases where clients connect directly, Firestore is often the right choice. Building the real-time capabilities yourself on top of Spanner would be a massive undertaking. In that case, the comparison should be against services like Firebase Realtime Database.

Conclusion

Firestore is often perceived as a cheap database, suitable for personal and small-scale projects. However, this analysis shows that the cost break-even point with Spanner's minimum configuration (approx. $85/month) is reached at less than 10% of that Spanner instance's capacity.

Beyond that point, Spanner becomes dramatically cheaper: up to 17 times cheaper for reads and 8 times cheaper for writes. An $85/month cost is not significantly higher than the minimum cost for other HA database configurations on Google Cloud.

So, is Spanner still "expensive"? If you hear someone say that, ask them under what conditions, compared to what, and which specific SKU they are talking about.

Appendix: Firestore Enterprise Edition

For those who think Firestore becomes too expensive, you might want to look at the new Firestore Enterprise edition, announced at Cloud Next 2025 and currently in preview.

While it currently only offers MongoDB compatibility, the Firestore editions overview states that Native mode support is planned for the future.

According to the Firestore Enterprise edition pricing, it has a pricing structure geared towards larger-scale users compared to the Standard edition.

	Standard edition	Enterprise edition	Ratio (Enterprise/Standard)
Read Units	$0.038 per 100,000 docs	$0.0642 per 1,000,000 units	16.9 %
Write Units	$0.115 per 100,000 docs	$0.3339 per 1,000,000 units	29 %
Stored Data	$0.115/GiB/month	$0.312/GiB/month	271 %

Note the change in billing unit from 100K to 1M operations. This makes read/write operations cheaper for small documents. However, units are calculated in 4 KiB increments for reads and 1 KiB for writes. This means documents larger than 24KB (for reads) or 4KB (for writes) could become more expensive than in the Standard edition.

Even with this new pricing, the fundamental trend of becoming more expensive than Spanner at scale seems to persist. It would be ideal if users who start small with Firestore didn't have to regret their choice later. A future where Firestore offers a provisioned capacity model, similar to Spanner, would be a welcome development, combining the ease of getting started with the cost-efficiency of Spanner at scale.

A spanner-cli Contributor's Perspective on the Official Spanner CLI

apstndb — Wed, 25 Jun 2025 08:30:36 +0000

Note: This article is an AI-assisted English translation of my original Japanese article. As the author, I wanted to share these insights about the official Spanner CLI release with the international developer community. The translation was performed using Claude to ensure technical accuracy while making the content accessible to a broader audience.

The official Spanner CLI has been released in preview.
https://cloud.google.com/spanner/docs/release-notes

You can directly connect and interact with your Spanner database using the Spanner CLI, an interactive shell for Spanner that is built into the Google Cloud CLI. You can use the Spanner CLI to start an interactive session and automate SQL executions from the shell or an input file. This feature is available in Preview. For more information, see Spanner CLI quickstart.

I'll share my observations about what this is, from the perspective of apstndb, an unemployed technology enthusiast who is a contributor to the OSS spanner-cli and the author of its fork spanner-mycli. For more about spanner-mycli, please read Why I Forked spanner-cli: Introducing spanner-mycli (Japanese article).

Note: This article describes what can be observed about gcloud alpha spanner cli, which is still in Preview, as of June 25, 2025. Please note that specifications may change at any time.

Key Points of This Article

Official Spanner CLI is derived from OSS spanner-cli v0.10.6
Technical evidence discovered through binary analysis
Unique evolution including introduction of meta-commands
Expectations for a healthy ecosystem through coexistence of official and OSS versions

The Importance of Interactive Tools

Interactive clients have been and continue to be essential for SQL databases.

Interactive clients for SQL databases have been recognized as essential tools since the era of SEQUEL: A structured English query language, SQL's predecessor, which made multiple references to interactive systems.
All major RDBMSs without exception provide first-party interactive clients:

MySQL's mysql
PostgreSQL's psql
Oracle's dbcli
SQL Server's mssql-cli, sqlcmd
- SQL Server seems to have a greater emphasis on the GUI tool SQL Server Management Studio compared to others.

How about Spanner? The officially provided interfaces that users could directly use were:

gcloud spanner subcommand within gcloud CLI
Spanner Studio within Cloud Console, Google Cloud's official Web UI

The gcloud spanner subcommand is not an interactive tool. It's a command that can execute SQL one-off from Bash or PowerShell, or be incorporated into scripts:

gcloud spanner databases execute-sql example-db \
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

Also, Spanner Studio is operated from a browser and doesn't run standalone locally.
The execution plan display is not suitable for sharing and cannot be used for automation.

Thus, Spanner lacked what other RDBMSs naturally provided.
Therefore, after spanner-cli developed by current Googler Yuki Furuyama was donated to the Cloud Spanner Ecosystem organization, it became the de facto standard tool for Spanner.

However, since spanner-cli was not part of Google's product, there was a disconnect between Spanner Studio used in official documentation and spanner-cli used primarily by the user community, without official documentation references.

Official Spanner CLI

After years of this situation, the official Spanner CLI was suddenly released. This happened on the morning of June 25, 2025 (JST) as I write this article.

Installation

As of June 25, 2025, the official documentation states that running gcloud alpha spanner cli will automatically install it:

The Spanner CLI is available in the gcloud CLI. When you run the gcloud alpha spanner cli command for the first time, gcloud CLI automatically installs the Spanner CLI component.

However, you currently cannot use the official Spanner CLI as described.

$ gcloud alpha spanner cli --project ${SPANNER_PROJECT_ID} --instance ${SPANNER_INSTANCE_ID} ${SPANNER_DATABASE_ID}  
Pausing command execution:

This command requires the `spannercli` component to be installed. Would you like to install the `spannercli` component to continue command execution? (Y/n)?  y

ERROR: (gcloud.alpha.spanner.cli) The following components are unknown [spannercli].

This is because the component it's trying to install called spannercli doesn't exist. What actually exists is spanner-cli.

$ gcloud components list | grep spanner

Your current Google Cloud CLI version is: 528.0.0
The latest available version is: 528.0.0

To install or remove components at your current SDK version [528.0.0], run:
  $ gcloud components install COMPONENT_ID
  $ gcloud components remove COMPONENT_ID

To update your SDK installation to the latest version [528.0.0], run:
  $ gcloud components update

│ Not Installed │ Spanner Cli                                          │ spanner-cli                  │  12.1 MiB │

So you need to install the spanner-cli component as follows:

$ gcloud components install --quiet spanner-cli

Your current Google Cloud CLI version is: 528.0.0
Installing components from version: 528.0.0

┌──────────────────────────────────────────────────────┐
│         These components will be installed.          │
├─────────────────────────────────┬─────────┬──────────┤
│               Name              │ Version │   Size   │
├─────────────────────────────────┼─────────┼──────────┤
│ Spanner Cli (Platform Specific) │   1.0.0 │ 12.1 MiB │
└─────────────────────────────────┴─────────┴──────────┘

For the latest full release notes, please visit:
  https://cloud.google.com/sdk/release_notes

Performing in place update...

╔════════════════════════════════════════════════════════════╗
╠═ Downloading: Spanner Cli                                 ═╣
╠════════════════════════════════════════════════════════════╣
╠═ Downloading: Spanner Cli (Platform Specific)             ═╣
╠════════════════════════════════════════════════════════════╣
╠═ Installing: Spanner Cli                                  ═╣
╠════════════════════════════════════════════════════════════╣
╠═ Installing: Spanner Cli (Platform Specific)              ═╣
╚════════════════════════════════════════════════════════════╝

Performing post processing steps...done.                                                                                                                                                                                                                                                                            

Google Cloud CLI works best with Python 3.12 and certain modules.

Setting up virtual environment
Updating modules...
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5.5/5.5 MB 31.2 MB/s eta 0:00:00
Modules updated.
Virtual env enabled.

Update done!

Once installed, you can use gcloud alpha spanner cli:

$ gcloud alpha spanner cli --project ${SPANNER_PROJECT_ID} --instance ${SPANNER_INSTANCE_ID} ${SPANNER_DATABASE_ID}
Welcome to Spanner-Cli Client.

Type 'help;' or '\h' for help.
Type 'exit;' or 'quit;' or '\q' to exit.

spanner-cli> DESCRIBE SELECT 1;
+-------------+-------------+
| Column_Name | Column_Type |
+-------------+-------------+
|             | INT64       |
+-------------+-------------+
1 rows in set (0.17 sec)

The official Spanner CLI can also be used directly without going through the gcloud command, as the google-cloud-sdk/bin/spannercli binary is available:

$ ~/google-cloud-sdk/bin/spannercli sql --help
Starts a SQL shell for a Spanner instance.

Usage:
  spanner sql --database=<database> [flags]

Examples:

# Start an interactive SQL shell for the 'my-database' database:
$ spanner sql --database my-database

# Execute a batch of SQL statements from the 'my-commands.sql' file:
$ spanner sql --database my-database --file my-commands.sql

# Execute a batch of SQL statements directly on the command line:
$ spanner sql --database my-database --execute "SELECT * FROM my-table; INSERT INTO my-table VALUES (1, 'apple');"

# SQL statements can be piped into the command:
$ spanner sql --database my-database < my-commands.sql
$ cat my-commands.sql | spanner sql --database my-database



Flags:
      --database string                The name of the database to start the sqlshell for. This flag is required.
      --delimiter string               The delimiter to use in the SQL shell.
      --deployment_endpoint string     The endpoint to use for the Spanner instance.
      --execute string                 The SQL commands to execute. This flag is mutually exclusive with the --source flag.
  -h, --help                           help for sql
      --history string                 The file to use for the SQL shell history.
      --html                           Show output in HTML format.
      --idle_transaction_timeout int   Idle transaction timeout. (default 60)
      --init-command string            The SQL command to execute before the SQL commands in the source file.
      --init-command-add string        The SQL command to execute after the SQL commands in the source file.
      --instance string                The instance ID of the Spanner instance.
      --project string                 The project ID of the Spanner instance.
      --prompt string                  The prompt to use in the SQL shell.
      --role string                    Role to use to connect to the Spanner instance.
      --skip-column-names              Show column names in the SQL shell.
      --skip-system-command            Allow system command in the SQL shell.
      --source string                  The file containing the SQL commands to execute. This flag is mutually exclusive with the --execute flag.
      --table                          Show output in Table format. (default true)
      --tee string                     The file to tee the SQL commands to.
      --xml                            Show output in XML format.

Evidence that Official Spanner CLI is a Derivative of OSS spanner-cli

The relationship between OSS spanner-cli and official Spanner CLI is not mentioned at all in the official Spanner CLI documentation.
However, I can say with confidence: The official Spanner CLI is a derivative of OSS spanner-cli.

Let me show you the evidence. Let's extract strings contained in the official Spanner CLI binary using the strings command and filter for a specific string (apstndb):

$ strings google-cloud-sdk/bin/spannercli | grep apstndb
Bgoogle3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.(*InputStatement).StripComments
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.SeparateInputString
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.SeparateInput
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.newSeparator
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.SeparateInputPreserveComments
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.(*separator).consumeRawString
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.(*separator).consumeBytesString
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.(*separator).consumeRawBytesString
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.(*separator).consumeString
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.(*separator).consumeStringContent
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.hasStringPrefix
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.hasPrefix
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.(*separator).consumeStringDelimiter
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.(*separator).skipComments
google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.(*separator).separate
type:.eq.google3/third_party/golang/github_com/apstndb/gsqlsep/v/v0/gsqlsep.InputStatement
third_party/golang/github_com/apstndb/gsqlsep/v/v0/separator.go

We found github.com/apstndb/gsqlsep, a third-party library vendored within Google's monorepo google3.
To tell the truth, this apstndb/gsqlsep is something I created by improving and turning into a library the statement splitting implementation that spanner-cli had, in order to fix comment handling bugs in spanner-cli with fix comment handling #150.
No software other than spanner-cli uses this library. This is highly reliable evidence that it's a derivative of spanner-cli.

https://pkg.go.dev/github.com/apstndb/gsqlsep?tab=importedby

Note

Currently, it's explicitly stated that the official Spanner CLI doesn't support Spanner PostgreSQL interface.

PostgreSQL interface note: For PostgreSQL-dialect databases, you can use the psql command-line tool. The examples in this document are intended for GoogleSQL-dialect databases.

Since apstndb/gsqlsep is an implementation based on GoogleSQL lexical structure, it cannot support Spanner PostgreSQL interface.
As Spanner-specific features that cannot be supported through PGAdapter are expected to continue increasing, I predict that at some point they will abandon the dependency on apstndb/gsqlsep and natively support both GoogleSQL/PostgreSQL dialects.

Note end

As for when exactly it was forked, since DESCRIBE that I implemented by October 2024 is available, we can narrow it down to being derived from v0.10.6 or later.

spanner-cli> DESCRIBE SELECT * FROM Singers;
+-------------+-------------+
| Column_Name | Column_Type |
+-------------+-------------+
| SingerId    | INT64       |
| FirstName   | STRING      |
| LastName    | STRING      |
| SingerInfo  | BYTES       |
| BirthDate   | DATE        |
+-------------+-------------+
5 rows in set (0.17 sec)

Also, since BEGIN RW ISOLATION LEVEL doesn't work, it's highly likely to be before v0.11.0.

spanner-cli> BEGIN RW ISOLATION LEVEL SERIALIZABLE;
ERROR: invalid statement

Note: While many spanner-cli features including DESCRIBE can still be used in the official Spanner CLI, they may be removed in future releases as they are not documented in the official documentation.

Organizing the Fork Relationships

Based on the investigation so far, the relationships between OSS spanner-cli, official Spanner CLI, and spanner-mycli can be organized as follows (as of June 25, 2025):

Thus, both official Spanner CLI and spanner-mycli were forked from spanner-cli v0.10.6, each evolving independently. As of June 25, 2025, OSS spanner-cli has progressed to v0.11.0, and spanner-mycli to v0.19.0.

New Features Added in Official Spanner CLI

The official Spanner CLI has significant changes from OSS spanner-cli even in this initial release.

Meta-commands

The biggest change is the introduction of meta-commands.

Command	Syntax	Description
?	`\?`	Displays help information. Same as `\h`.
Delimiter	`\d`	Sets the statement delimiter. The default delimiter is a semi-colon.
Exit	`\q`	Exits the Spanner CLI. Same as quit.
Go	`\g`	Sends and runs SQL statement in Spanner.
Help	`\h`	Displays help information. Same as `\?`.
Notee	`\t`	Turns off writing to the output file set by the `\T`.
Prompt	`\R`	Changes your prompt to a user prompt string.
Quit	`\q`	Quits Spanner CLI. Same as exit.
Source	`\.`	Executes SQL from an input file. Takes `[filename]` as an argument.
System	`\!`	Executes a system shell command.
Tee	`\T`	Appends command output to a specified `[filename]` along with the standard output.
Use	`\u`	Connects to another database. Takes the new database name as an argument.

This seems to be strongly influenced by PostgreSQL psql command's meta-commands.
Client-side features of Spanner CLI will likely be extended as meta-commands in the future.

Note: Features for interacting with Spanner that are not limited to the client side are still largely undocumented. My intuition is that since it's undesirable for Google's official tools to have inconsistent command systems, it will converge to the Spanner JDBC command system.

Changes in Command-line Options

Command-line options have also changed significantly. Comparing the initial release v1.0.0 of official Spanner CLI with the latest release v0.11.1 of OSS spanner-cli, the following differences appear:

gcloud spanner integration
- Connection specification is now common with gcloud spanner, supporting gcloud config set etc.
- Authentication: --credential is removed and integrated into gcloud credential
- However, I confirmed it doesn't work after gcloud auth application-default revoke, so it seems gcloud auth login alone isn't sufficient yet > Error: failed to create sql shell: credentials: could not find default credentials. See https://cloud.google.com/docs/authentication/external/set-up-adc for more information
- GCLOUD_WIDE_FLAG support - mentions support for other gcloud level flags like --impersonate-service-account
Single-letter short forms are removed except for -h corresponding to --help
--verbose(-v), which was almost default in spanner-cli, is removed
Changed from --file to --source
Connection API endpoint changes: from --endpoint to --deployment_endpoint, --host, --post
Output format: Added --html, --xml in addition to --table
Other options removed from OSS spanner-cli: --priority, --directed-read, --proto-descriptor-file, --skip-tls-verify
Other options added in official Spanner CLI: --init-command string, --init-command-add string --tee string, --idle-transaction-timeout int, --skip-column-names string, --skip-system-command string, --system-command string, --delimiter string

While functionality as a CLI tool is enhanced, some Spanner API-related parts seem to have been removed.

Note

Regarding command-line options, there seem to be differences in official Spanner CLI between launching as gcloud alpha spanner cli and as spannercli sql.
This is probably because gcloud alpha spanner cli as a wrapper adjusts for consistency with the gcloud spanner command. There's a possibility that spannercli sql may become unavailable in the future.

	`gcloud alpha spanner cli`	`spannercli sql`
Database ID	Positional parameter	`--database`
Role specification	`--database-role`	`--role`

Thoughts as a Spanner Interactive Tool Developer

The birth of official Spanner CLI is very welcome.
This is because, as official documentation is written using it going forward, both officials and the user community will use the same tool and be able to discuss operations and results in a shareable text format.
While EXPLAIN and EXPLAIN ANALYZE are not currently mentioned, I hope we'll be able to discuss execution plans using this tool as well.

My concern is that unlike OSS-developed spanner-cli, the official Spanner CLI's source is not public.
Being provided only as a compiled binary in the compiled language Go means it's impossible to investigate problems independently and apply patches, which may lead to continued inconvenience for users.

I think it would be preferable to become like gsutil, which is distributed by Google as one of the gcloud components but developed on GitHub.

With this, the official tool's future evolution is promised, but I intend to continue developing my spanner-mycli as the only actively developed OSS Spanner interactive client.

Acknowledgments

When I confirmed the relationship between this official Spanner CLI and OSS spanner-cli, I learned that they are considering putting spanner-cli into maintenance mode and archiving it after the official Spanner CLI goes GA.

https://github.com/cloudspannerecosystem/spanner-cli/issues/214

Today Google officially released the official Spanner CLI and it's basically equivalent (or superset) of OSS spanner-cli in terms of functionality.
To prevent confusion from having two separate CLIs, I'm considering to make OSS spanner-cli maintenance mode and archive this repository once the official Spanner CLI goes to GA.

I deeply thank Yuki Furuyama, the author and owner of spanner-cli, who has supported the Spanner community as an interactive client not provided by first-party Google itself for over six and a half years since v0.1.0 in October 2018.

(2025-06-26) Addendum

As described in spanner-cli's CONTRIBUTING.md, all contributions to projects under the Cloud Spanner Ecosystem organization are made under Google's Contributor License Agreement (CLA).
This means contributors have agreed to allow Google to freely use contributions to spanner-cli, so there are no licensing issues with it becoming closed source.

However, I think not explaining the relationship with spanner-cli, which is familiar to the Spanner community, will cause confusion. I hope this will be explained when it's announced in the official Google Cloud blog at GA.

Google's decision to maintain an interactive CLI as a first-party tool is definitely a good thing, and I hope it continues to evolve in a positive direction.