How to fix Cross-database references are not implemented in PostgreSQL

PostgreSQLINTERMEDIATEMEDIUMUpdated Dec 29, 2025· 336 views

This error occurs when you try to reference a table from a different database using the three-part naming convention (database.schema.table). PostgreSQL does not support cross-database queries directly. Instead, use schemas within a single database or the postgres_fdw extension to connect to other PostgreSQL servers.

Quick fix

Fixes Cross-database references are not implemented

SELECT current_database();
  1. Understand the PostgreSQL connection model
  2. Remove the database name from your query
  3. Use schemas instead of multiple databases
  4. For genuinely remote databases, use postgres_fdw
postgresql — error
SELECT current_database();
Cross-database references are not implemented

What this error means

PostgreSQL has a different architecture than some other SQL databases (like SQL Server or MySQL). In PostgreSQL, you cannot reference tables in other databases the way you might in SQL Server using four-part naming (server.database.schema.table). PostgreSQL enforces that you must be connected to a specific database to query it. While you can use the three-part naming syntax (database.schema.table) for syntactic compliance with the SQL standard, PostgreSQL interprets it as a schema reference, not a database reference. If the database name does not match the currently connected database, PostgreSQL raises this error because the architecture does not support cross-database references at the query level.

Typical symptoms

  • Queries with three-part table names fail: "INSERT INTO myDatabase.public.product VALUES..."
  • SELECT statements referencing other databases fail with the error
  • Attempts to use linked server-style queries result in an error
  • Code migrated from SQL Server or MySQL fails with this error
  • Error occurs even when the table exists in another database on the same server

Common causes

  1. Using database.schema.table naming convention when PostgreSQL only supports schema.table within the current database
  2. Attempting to port SQL Server code that uses cross-database queries (four-part names)
  3. Misunderstanding PostgreSQL architecture: it does not have "linked servers" like SQL Server
  4. Code that was written for or migrated from MySQL/SQL Server without accounting for PostgreSQL differences
  5. Missing setup of postgres_fdw extension when genuinely needing to query remote PostgreSQL databases

How to fix "Cross-database references are not implemented"

1Understand the PostgreSQL connection model

PostgreSQL requires you to connect to a specific database. All queries in that connection operate on that database. Unlike SQL Server which allows cross-database queries in a single session, PostgreSQL does not have this feature.

You can verify your current database:

sql
SELECT current_database();

All queries must reference tables within this database.

2Remove the database name from your query

Change three-part table references to two-part references.

Wrong (causes the error):

sql
SELECT * FROM myDatabase.public.users;

Correct:

sql
SELECT * FROM public.users;

If you are already connected to myDatabase, you do not need to specify the database name. The public schema is the default schema in PostgreSQL.

3Use schemas instead of multiple databases

If you have been using multiple databases for organizational purposes (like in MySQL), migrate to using schemas within a single database.

Create separate schemas:

sql
CREATE SCHEMA app_schema;
CREATE SCHEMA archive_schema;

Reference tables with schema prefix:

sql
SELECT * FROM app_schema.users;
SELECT * FROM archive_schema.old_orders;

This gives you logical separation without requiring cross-database queries. You can even set your search_path to include multiple schemas:

sql
SET search_path TO app_schema, archive_schema, public;

Then reference tables by name alone (PostgreSQL searches the path in order).

4For genuinely remote databases, use postgres_fdw

If you need to query tables from a different PostgreSQL database (possibly on a different server), use the postgres_fdw (foreign data wrapper) extension.

Install the extension:

sql
CREATE EXTENSION postgres_fdw;

Create a foreign server connection:

sql
CREATE SERVER remote_db
  FOREIGN DATA WRAPPER postgres_fdw
  OPTIONS (host 'remote.example.com', dbname 'remote_database', port '5432');

Create a user mapping:

sql
CREATE USER MAPPING FOR postgres
  SERVER remote_db
  OPTIONS (user 'remote_user', password 'remote_password');

Import the remote schema:

sql
IMPORT FOREIGN SCHEMA public
  FROM SERVER remote_db
  INTO local_schema;

Query the remote tables:

sql
SELECT * FROM local_schema.remote_table;
5For legacy migration from SQL Server, refactor queries

If migrating code from SQL Server that uses cross-database references:

SQL Server (does not work in PostgreSQL):

sql
SELECT * FROM database1.dbo.table1
JOIN database2.dbo.table2 ON table1.id = table2.id;

PostgreSQL approach (one database, multiple schemas):

sql
SELECT * FROM db1_schema.table1
JOIN db2_schema.table2 ON table1.id = table2.id;

Or consolidate into a single schema if appropriate:

sql
SELECT * FROM public.table1
JOIN public.table2 ON table1.id = table2.id;

Update all your queries to use schema.table notation instead of database.schema.table.

Advanced notes

Performance considerations: postgres_fdw is useful for querying remote PostgreSQL databases but involves network overhead. For frequently accessed remote data, consider materializing views or replicating data to your primary database. Alternative solutions include using dblink (older method) or logical replication for keeping databases synchronized. If you are using a managed PostgreSQL service (AWS RDS, Google Cloud SQL, Azure), check if postgres_fdw is enabled; some services restrict or disable it for security reasons. For very large cross-database queries, consider redesigning your schema to use a single database with appropriate partitioning or sharding strategies.

Frequently asked questions

What does "Cross-database references are not implemented" mean?
PostgreSQL has a different architecture than some other SQL databases (like SQL Server or MySQL). table). PostgreSQL enforces that you must be connected to a specific database to query it.
How do I fix "Cross-database references are not implemented"?
This error occurs when you try to reference a table from a different database using the three-part naming convention (database.schema.table). PostgreSQL does not support cross-database queries directly. Instead, use schemas within a single database or the postgres_fdw extension to connect to other PostgreSQL servers.
What causes "Cross-database references are not implemented"?
Using database.schema.table naming convention when PostgreSQL only supports schema.table within the current database Attempting to port SQL Server code that uses cross-database queries (four-part names) Misunderstanding PostgreSQL architecture: it does not have "linked servers" like SQL Server
Is the "Cross-database references are not implemented" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading