Stay organized with collections
Save and categorize content based on your preferences.
The PostgreSQL interface for Spanner lets you take advantage of
Spanner's fully managed, scalable, and highly available
infrastructure using familiar PostgreSQL tools and syntax. This page
helps you understand the capabilities and limitations of the PostgreSQL
interface.
Benefits of the PostgreSQL interface
Portability: the PostgreSQL interface provides access to
the breadth of Spanner features, using schemas, queries, and
clients that are compatible with open source PostgreSQL. This
simplifies moving an application built on Spanner to another
PostgreSQL environment. This portability provides deployment
flexibility and supports disaster recovery scenarios, such as a stressed
exit.
Familiarity: if you already use PostgreSQL, you can quickly get
started with Spanner using many of the same PostgreSQL
statements and tools. Using PostgreSQL across your database
portfolio means fewer variations between specific products and a common set
of best practices.
Uncompromisingly Spanner: because it's built on
Spanner's existing foundation, the
PostgreSQL interface provides all of
Spanner's existing availability, consistency, and price-performance
benefits without having to compromise on any of the capabilities available
in the complementary GoogleSQL ecosystem.
Unsupported PostgreSQL features on Spanner
It's important to understand that the PostgreSQL interface
provides the capabilities of Spanner through schemas, types,
queries, and clients that are compatible with PostgreSQL. It doesn't
support all of the features of PostgreSQL. Migrating an existing
PostgreSQL application to Spanner, even using
the PostgreSQL interface for Spanner, likely requires some rework to accommodate
unsupported PostgreSQL capabilities or differences in behavior, like
query optimization or primary key design. However, once it's migrated, your
workloads can take advantage of Spanner's reliability and unique
multi-model capabilities.
The following list provides more information on supported and unsupported
PostgreSQL features:
Supported PostgreSQL functionality: the
PostgreSQL interface supports many of the most commonly used
features of PostgreSQL. This includes core parts of the schema and
type system, many common query shapes, a variety of functions and operators,
and the key aspects of PostgreSQL's system catalog. Applications
can use many PostgreSQL clients by connecting over
Spanner's implementation of the PostgreSQL wire protocol.
Some PostgreSQL language features aren't supported: extensions,
user-defined data types, user-defined stored procedures, and other features
aren't supported. For a complete list, see
The PostgreSQL language in Spanner.
There are also some features in PostgreSQL that behave differently
from open source PostgreSQL. For more information, see
Known issues in the PostgreSQL interface for Spanner.
Spanner and Spanner control plane: databases with
PostgreSQL interfaces use Spanner and Google Cloud
tools to provision, secure, monitor, and optimize instances.
Spanner doesn't support tools, such as pgAdmin for administrative
activities.
Client and wire protocol support: Spanner supports the core
query capabilities of the PostgreSQL wire protocol using
PGAdapter, a lightweight proxy that runs alongside your
application. This lets many Spanner clients work as-is with a
Spanner PostgreSQL interface database, while
leveraging Spanner's global endpoint and connection management and
IAM authentication. Google's internal benchmarking shows that
PGAdapter doesn't add any noticeable additional latency compared to
direct connection to Spanner's built-in endpoints.
Administration and Management
The PostgreSQL interface supports the administration and
management of your Spanner databases with the following features:
Unified experience: provision, manage, and monitor PostgreSQL
interface-enabled databases using Spanner's existing console,
APIs, and tools like Google Cloud CLI.
Flexible configuration: configure the
PostgreSQL interface per database at creation time. A single
Spanner instance can accommodate both
GoogleSQL and PostgreSQL interface databases.
Shared benefits: both database dialects share the same underlying
distributed database engine, ensuring consistent scalability, consistency,
performance, and security.
Features
Spanner's PostgreSQL interface offers two primary
features that enable integration with the PostgreSQL ecosystem:
PostgreSQL dialect support
Spanner provides a subset of the PostgreSQL SQL
dialect, including Data Query Language (DQL), Data Manipulation Language
(DML), and Data Definition Language (DDL). Additionally, it includes
extensions to support Spanner-specific features like
interleaved tables,
time to live (TTL), and query hints.
For detailed information on the supported PostgreSQL language
elements, see The PostgreSQL language in
Spanner. To
understand how to use Spanner features with the
PostgreSQL dialect, consult the documentation for the specific
feature.
PostgreSQL client support
Spanner lets you connect to databases from a variety of
clients:
psql command-line tool: the popular
psql interactive environment
is supported, letting you run queries, explore metadata, and load data
directly from your terminal.
PGAdapter: this lightweight proxy simplifies connection
management and authentication. For more details, refer to the
PGAdapter overview.
Spanner clients: Spanner provides
open source Spanner clients for various programming
languages (Java, Go, Python, Node.js, Ruby, PHP, C#, C++), along with a
Spanner JDBC driver
and a driver for Go's SQL package.
Spanner clients connect directly to
Spanner's global endpoint without a proxy. However,
Spanner clients don't offer compatibility with existing
PostgreSQL clients, ORMs, or tools.
Best practices for using the PostgreSQL interface
Use the following best practices when using the PostgreSQL interface:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# PostgreSQL interface\n\nThe PostgreSQL interface for Spanner lets you take advantage of\nSpanner's fully managed, scalable, and highly available\ninfrastructure using familiar PostgreSQL tools and syntax. This page\nhelps you understand the capabilities and limitations of the PostgreSQL\ninterface.\n\nBenefits of the PostgreSQL interface\n------------------------------------\n\n- **Portability**: the PostgreSQL interface provides access to the breadth of Spanner features, using schemas, queries, and clients that are compatible with open source PostgreSQL. This simplifies moving an application built on Spanner to another PostgreSQL environment. This portability provides deployment flexibility and supports disaster recovery scenarios, such as a stressed exit.\n- **Familiarity**: if you already use PostgreSQL, you can quickly get started with Spanner using many of the same PostgreSQL statements and tools. Using PostgreSQL across your database portfolio means fewer variations between specific products and a common set of best practices.\n- **Uncompromisingly Spanner**: because it's built on Spanner's existing foundation, the PostgreSQL interface provides all of Spanner's existing availability, consistency, and price-performance benefits without having to compromise on any of the capabilities available in the complementary GoogleSQL ecosystem.\n\nUnsupported PostgreSQL features on Spanner\n------------------------------------------\n\nIt's important to understand that the PostgreSQL interface\nprovides the capabilities of Spanner through schemas, types,\nqueries, and clients that are compatible with PostgreSQL. It doesn't\nsupport all of the features of PostgreSQL. Migrating an existing\nPostgreSQL application to Spanner, even using\nthe PostgreSQL interface for Spanner, likely requires some rework to accommodate\nunsupported PostgreSQL capabilities or differences in behavior, like\nquery optimization or primary key design. However, once it's migrated, your\nworkloads can take advantage of Spanner's reliability and unique\nmulti-model capabilities.\n\nThe following list provides more information on supported and unsupported\nPostgreSQL features:\n\n- **Supported PostgreSQL functionality**: the PostgreSQL interface supports many of the most commonly used features of PostgreSQL. This includes core parts of the schema and type system, many common query shapes, a variety of functions and operators, and the key aspects of PostgreSQL's system catalog. Applications can use many PostgreSQL clients by connecting over Spanner's implementation of the PostgreSQL wire protocol.\n- **Some PostgreSQL language features aren't supported** : extensions, user-defined data types, user-defined stored procedures, and other features aren't supported. For a complete list, see [The PostgreSQL language in Spanner](/spanner/docs/reference/postgresql/overview). There are also some features in PostgreSQL that behave differently from open source PostgreSQL. For more information, see [Known issues in the PostgreSQL interface for Spanner](/spanner/docs/reference/postgresql/known-issues-postgresql-interface).\n- **Spanner and Spanner control plane**: databases with PostgreSQL interfaces use Spanner and Google Cloud tools to provision, secure, monitor, and optimize instances. Spanner doesn't support tools, such as pgAdmin for administrative activities.\n- **Client and wire protocol support**: Spanner supports the core query capabilities of the PostgreSQL wire protocol using PGAdapter, a lightweight proxy that runs alongside your application. This lets many Spanner clients work as-is with a Spanner PostgreSQL interface database, while leveraging Spanner's global endpoint and connection management and IAM authentication. Google's internal benchmarking shows that PGAdapter doesn't add any noticeable additional latency compared to direct connection to Spanner's built-in endpoints.\n\nAdministration and Management\n-----------------------------\n\nThe PostgreSQL interface supports the administration and\nmanagement of your Spanner databases with the following features:\n\n- **Unified experience**: provision, manage, and monitor PostgreSQL interface-enabled databases using Spanner's existing console, APIs, and tools like Google Cloud CLI.\n- **Flexible configuration**: configure the PostgreSQL interface per database at creation time. A single Spanner instance can accommodate both GoogleSQL and PostgreSQL interface databases.\n- **Shared benefits**: both database dialects share the same underlying distributed database engine, ensuring consistent scalability, consistency, performance, and security.\n\nFeatures\n--------\n\nSpanner's PostgreSQL interface offers two primary\nfeatures that enable integration with the PostgreSQL ecosystem:\n\n- **PostgreSQL dialect support**\n\n Spanner provides a subset of the PostgreSQL SQL\n dialect, including Data Query Language (DQL), Data Manipulation Language\n (DML), and Data Definition Language (DDL). Additionally, it includes\n extensions to support Spanner-specific features like\n [interleaved tables](/spanner/docs/schema-and-data-model#parent-child),\n [time to live (TTL)](/spanner/docs/ttl), and [query hints](/spanner/docs/reference/postgresql/query-syntax#pg_extensions).\n\n For detailed information on the supported PostgreSQL language\n elements, see [The PostgreSQL language in\n Spanner](/spanner/docs/reference/postgresql/overview). To\n understand how to use Spanner features with the\n PostgreSQL dialect, consult the documentation for the specific\n feature.\n- **PostgreSQL client support**\n\n Spanner lets you connect to databases from a variety of\n clients:\n - **PostgreSQL ecosystem tools:** you can use familiar\n tools like the [PostgreSQL JDBC driver](/spanner/docs/pg-jdbc-connect)\n and [PostgreSQL pgx driver](https://github.com/jackc/pgx) to connect\n your applications to a PostgreSQL interface database. For\n a list of supported drivers, ORMs, and tools see\n [PostgreSQL drivers and ORMs](/spanner/docs/drivers-overview#postgresql-drivers-and-orms).\n\n - **psql command-line tool** : the popular\n [`psql` interactive environment](/spanner/docs/psql-commands)\n is supported, letting you run queries, explore metadata, and load data\n directly from your terminal.\n\n - **PGAdapter:** this lightweight proxy simplifies connection\n management and authentication. For more details, refer to the [PGAdapter overview](/spanner/docs/pgadapter).\n\n - **Spanner clients:** Spanner provides\n open source Spanner clients for various programming\n languages (Java, Go, Python, Node.js, Ruby, PHP, C#, C++), along with a\n [Spanner JDBC driver](https://github.com/googleapis/java-spanner-jdbc)\n and a [driver for Go's SQL package](https://github.com/googleapis/go-sql-spanner).\n Spanner clients connect directly to\n Spanner's global endpoint without a proxy. However,\n Spanner clients don't offer compatibility with existing\n PostgreSQL clients, ORMs, or tools.\n\nBest practices for using the PostgreSQL interface\n-------------------------------------------------\n\nUse the following best practices when using the PostgreSQL interface:\n\n1. **Connect your applications** : use the [set of supported PostgreSQL\n tools](#connect-pg) for efficient connectivity.\n2. **Interact with your database**: for interactive work, choose\n between the following:\n\n - The familiar [psql command-line tool](/spanner/docs/psql-connect) (using the [PGAdapter proxy](/spanner/docs/pgadapter-get))\n - The intuitive [Spanner Studio](/spanner/docs/manage-data-using-console) page within the Google Cloud console\n - IDEs, such [DBeaver](https://cloud.google.com/blog/topics/developers-practitioners/exploring-cloud-spanner-data-dbeaver/) and [Visual Studio Code](https://cloud.google.com/blog/topics/developers-practitioners/browse-and-query-cloud-spanner-databases-visual-studio-code), [JetBrains](https://cloud.google.com/blog/topics/developers-practitioners/cloud-spanner-connectivity-using-jetbrains-ides), and [IntelliJ](/spanner/docs/use-intellij)\n - The Spanner emulator which lets you emulate Spanner on your local machine. This is useful during the development and test process.\n\n### What's next\n\n- Learn how to [choose between PostgreSQL and\n GoogleSQL](/spanner/docs/choose-googlesql-or-postgres).\n- Follow the [quickstart](/spanner/docs/create-query-database-console) to create and interact with a PostgreSQL database.\n- Learn more about [Spanner's PostgreSQL language\n support](/spanner/docs/reference/postgresql/overview).\n- Learn about [PGAdapter](/spanner/docs/pgadapter).\n- Learn about the [PGAdapter GitHub\n repository](https://github.com/GoogleCloudPlatform/pgadapter).\n- Review [known issues](/spanner/docs/known-issues-postgresql-interface) in the PostgreSQL interface."]]