Initial Configuration v5

Before using the MongoDB Foreign Data Wrapper:

  1. Use the CREATE EXTENSION command to create the MongoDB Foreign Data Wrapper extension on the Postgres host.
  2. Use the CREATE SERVER command to define a connection to the MongoDB server.
  3. Use the CREATE USER MAPPING command to define a mapping that associates a Postgres role with the server.
  4. Use the CREATE FOREIGN TABLE command to define a table in the Postgres database that corresponds to a database that resides on the MongoDB cluster.

CREATE EXTENSION

Use the CREATE EXTENSION command to create the mongo_fdw extension. To invoke the command, use your client of choice (for example, psql) to connect to the Postgres database from which you want to query the MongoDB server, and invoke the command:

CREATE EXTENSION [IF NOT EXISTS] mongo_fdw [WITH] [SCHEMA schema_name];

Parameters

IF NOT EXISTS

Include the IF NOT EXISTS clause to instruct the server to issue a notice instead of returning an error if an extension with the same name already exists.

schema_name

Optionally specify the name of the schema in which to install the extension's objects.

Example

The following command installs the MongoDB foreign data wrapper:

CREATE EXTENSION mongo_fdw;

For more information about using the foreign data wrapper CREATE EXTENSION command, see the PostgreSQL documentation.

CREATE SERVER

Use the CREATE SERVER command to define a connection to a foreign server. The syntax is:

CREATE SERVER server_name FOREIGN DATA WRAPPER mongo_fdw
    [OPTIONS (option 'value' [, ...])]

The role that defines the server is the owner of the server. Use the ALTER SERVER command to reassign ownership of a foreign server. To create a foreign server, you must have USAGE privilege on the foreign-data wrapper specified in the CREATE SERVER command.

Parameters

server_name

Use server_name to specify a name for the foreign server. The server name must be unique in the database.

FOREIGN_DATA_WRAPPER

Include the FOREIGN_DATA_WRAPPER clause to specify for the server to use the mongo_fdw foreign data wrapper when connecting to the cluster.

OPTIONS

Use the OPTIONS clause of the CREATE SERVER command to specify connection information for the foreign server object. You can include these options.

OptionDescription
addressThe address or host name of the Mongo server. The default value is 127.0.0.1.
portThe port number of the Mongo server. Valid range is 0 to 65535. The default value is 27017.
authentication_databaseThe database against which the user is authenticated. This option is valid only with password-based authentication.
sslRequests an authenticated, encrypted SSL connection. By default, the value is set to false. Set the value to true to enable SSL. See mongoc_ssl_opt_t to understand the options.
pem_fileSSL option.
pem_pwdSSL option.
ca_fileSSL option.
ca_dirSSL option.
crl_fileSSL option.
weak_cert_validationSSL option. The default value is false.
enable_join_pushdownSimilar to the table-level option but configured at the server level. If true, pushes the join between two foreign tables from the same foreign server instead of fetching all the rows for both the tables and performing a join locally. You can also set this option for an individual table. In this case, if any of the tables involved in the join has the option set to false, then the join isn't pushed down. The table-level value of the option takes precedence over the server-level option value. Default is true.

Example

The following command creates a foreign server named mongo_server that uses the mongo_fdw foreign data wrapper to connect to a host with an IP address of 127.0.0.1:

CREATE SERVER mongo_server FOREIGN DATA WRAPPER mongo_fdw OPTIONS (host '127.0.0.1', port '27017');

The foreign server uses the default port (27017) for the connection to the client on the MongoDB cluster.

For more information about using the CREATE SERVER command, see the PostgreSQL documentation.

CREATE USER MAPPING

Use the CREATE USER MAPPING command to define a mapping that associates a Postgres role with a foreign server:

CREATE USER MAPPING FOR role_name SERVER server_name
       [OPTIONS (option 'value' [, ...])];

You must be the owner of the foreign server to create a user mapping for that server.

Parameters

role_name

Use role_name to specify the role to associate with the foreign server.

server_name

Use server_name to specify the name of the server that defines a connection to the MongoDB cluster.

OPTIONS

Use the OPTIONS clause to specify connection information for the foreign server.

username is the name of the user on the MongoDB server.

password is the password associated with the username.

Example

The following command creates a user mapping for a role named enterprisedb. The mapping is associated with a server named mongo_server.

CREATE USER MAPPING FOR enterprisedb SERVER mongo_server;

If the database host uses secure authentication, provide connection credentials when creating the user mapping:

CREATE USER MAPPING FOR enterprisedb SERVER mongo_server OPTIONS (username 'mongo_user', password 'mongo_pass');

The command creates a user mapping for a role named enterprisedb that is associated with a server named mongo_server. When connecting to the MongoDB server, the server authenticates as mongo_user and provides a password of mongo_pass.

For detailed information about the CREATE USER MAPPING command, see the PostgreSQL documentation.

CREATE FOREIGN TABLE

A foreign table is a pointer to a table that resides on the MongoDB host. Before creating a foreign table definition on the Postgres server, connect to the MongoDB server and create a collection. The columns in the table map to columns in a table on the Postgres server. Then, use the CREATE FOREIGN TABLE command to define a table on the Postgres server with columns that correspond to the collection that resides on the MongoDB host. The syntax is:

CREATE FOREIGN TABLE [ IF NOT EXISTS ] table_name ( [
  { column_name data_type [ OPTIONS ( option 'value' [, ... ] ) ] [ COLLATE collation ] [ column_constraint [ ... ] ]
    | table_constraint }
    [, ... ]
] )
[ INHERITS ( parent_table [, ... ] ) ]
  SERVER server_name [ OPTIONS ( option 'value' [, ... ] ) ]

column_constraint is:

[ CONSTRAINT constraint_name ]
{ NOT NULL | NULL | CHECK (expr) [ NO INHERIT ] | DEFAULT default_expr }

table_constraint is:

[ CONSTRAINT constraint_name ] CHECK (expr) [ NO INHERIT ]

Parameters

table_name

Specify the name of the foreign table. Include a schema name to specify the schema in which the foreign table resides.

IF NOT EXISTS

Include the IF NOT EXISTS clause to instruct the server to not return an error if a table with the same name already exists. If a table with the same name exists, the server issues a notice.

column_name

Specify the name of a column in the new table. Each column must correspond to a column described on the MongoDB server.

data_type

Specify the data type of the column. When possible, specify the same data type for each column on the Postgres server and the MongoDB server. If a data type with the same name isn't available, the Postgres server attempts to cast the data type to a type compatible with the MongoDB server. If the server can't identify a compatible data type, it returns an error.

COLLATE collation

Include the COLLATE clause to assign a collation to the column. If not specified, the column data type's default collation is used.

INHERITS (parent_table [, ... ])

Include the INHERITS clause to specify a list of tables from which the new foreign table inherits all columns. Parent tables can be plain tables or foreign tables.

CONSTRAINT constraint_name

Specify an optional name for a column or table constraint. If not specified, the server generates a constraint name.

NOT NULL

Include the NOT NULL keywords to indicate that the column isn't allowed to contain null values.

NULL

Include the NULL keywords to indicate that the column is allowed to contain null values. This is the default.

CHECK (expr) [NO INHERIT]

Use the CHECK clause to specify an expression that produces a Boolean result that each row in the table must satisfy. A check constraint specified as a column constraint must reference that column's value only, while an expression appearing in a table constraint can reference multiple columns.

A CHECK expression can't contain subqueries or refer to variables other than columns of the current row.

Include the NO INHERIT keywords to specify that a constraint can't propagate to child tables.

DEFAULT default_expr

Include the DEFAULT clause to specify a default data value for the column whose column definition it appears in. The data type of the default expression must match the data type of the column.

SERVER server_name [OPTIONS (option 'value' [, ... ] ) ]

To create a foreign table that allows you to query a table that resides on a MongoDB file system, include the SERVER clause and specify server_name for the foreign server that uses the MongoDB data adapter.

Use the OPTIONS clause to specify the following options and their corresponding values:

OptionValue
databaseThe name of the database to query. The default value is test.
collectionThe name of the collection to query. The default value is the foreign table name.
enable_join_pushdownSimilar to the server-level option but configured at table level. If true, pushes the join between two foreign tables from the same foreign server instead of fetching all the rows for both the tables and performing a join locally. You can also set this option for an individual table. In this case, if any of the tables involved in the join has set the option to false, then the join isn't pushed down. The table-level value of the option takes precedence over the server-level option value. Default is true.

Example

To use data that's stored on MongoDB server, you must create a table on the Postgres host that maps the columns of a MongoDB collection to the columns of a Postgres table. For example, for a MongoDB collection with the following definition:

db.warehouse.find
(
        {
                "warehouse_id" : 1
        }
).pretty()
{
        "_id" : ObjectId("53720b1904864dc1f5a571a0"),
        "warehouse_id" : 1,
        "warehouse_name" : "UPS",
        "warehouse_created" : ISODate("2014-12-12T07:12:10Z")
}

Execute a command on the Postgres server that creates a comparable table on the Postgres server:

CREATE FOREIGN TABLE warehouse
(
 _id               NAME,
 warehouse_id      INT,
 warehouse_name    TEXT,
 warehouse_created TIMESTAMPZ
)
SERVER mongo_server
OPTIONS (database 'db', collection 'warehouse');

The first column of the table must be _id of the type name.

Include the SERVER clause to specify the name of the database stored on the MongoDB server and the name of the table (warehouse) that corresponds to the table on the Postgres server.

For more information about using the CREATE FOREIGN TABLE command, see the PostgreSQL documentation.

Note

MongoDB Foreign Data Wrapper supports the write capability feature.

Data type mappings

When using the foreign data wrapper, you must create a table on the Postgres server that mirrors the table that resides on the MongoDB server. The MongoDB data wrapper converts the following MongoDB data types to the target Postgres type:

MongoDB (BSON Type)Postgres
ARRAYJSON
BOOLBOOL
BINARYBYTEA
DATE_TIMEDATE/TIMESTAMP/TIMESTAMPTZ
DOCUMENTJSON
DOUBLEFLOAT/FLOAT4/FLOAT8/DOUBLE PRECISION/NUMERIC
INT32SMALLINT/INT2/INT/INTEGER/INT4
INT64BIGINT/INT8
OIDNAME
UTF8BPCHAR/VARCHAR/CHARACTER VARYING/TEXT

DROP EXTENSION

Use the DROP EXTENSION command to remove an extension. To invoke the command, use your client of choice (for example, psql) to connect to the Postgres database from which you're dropping the MongoDB server, and run the command:

DROP EXTENSION [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ];

Parameters

IF EXISTS

Include the IF EXISTS clause to instruct the server to issue a notice instead of returning an error if an extension with the specified name doesn't exist.

name

Optionally, specify the name of the installed extension.

CASCADE

Drop objects that depend on the extension. It drops all the other dependent objects too.

RESTRICT

Don't allow to drop extension if any objects, other than its member objects and extensions listed in the same DROP command, depend on it.

Example

The following command removes the extension from the existing database:

DROP EXTENSION mongo_fdw;

For more information about using the foreign data wrapper DROP EXTENSION command, see the PostgreSQL documentation.

DROP SERVER

Use the DROP SERVER command to remove a connection to a foreign server. The syntax is:

DROP SERVER [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ]

The role that drops the server is the owner of the server. Use the ALTER SERVER command to reassign ownership of a foreign server. To drop a foreign server, you must have USAGE privilege on the foreign-data wrapper specified in the DROP SERVER command.

Parameters

IF EXISTS

Include the IF EXISTS clause to instruct the server to issue a notice instead of returning an error if a server with the specified name doesn't exist.

name

Optionally, specify the name of the installed server.

CASCADE

Drop objects that depend on the server. It drops all the other dependent objects too.

RESTRICT

Don't allow to drop the server if any objects depend on it.

Example

The following command removes a foreign server named mongo_server:

DROP SERVER mongo_server;

For more information about using the DROP SERVER command, see the PostgreSQL documentation.

DROP USER MAPPING

Use the DROP USER MAPPING command to remove a mapping that associates a Postgres role with a foreign server. You must be the owner of the foreign server to remove a user mapping for that server.

DROP USER MAPPING [ IF EXISTS ] FOR { user_name | USER | CURRENT_USER | PUBLIC } SERVER server_name;

Parameters

IF EXISTS

Include the IF EXISTS clause to instruct the server to issue a notice instead of returning an error if the user mapping doesn't exist.

user_name

Specify the user name of the mapping.

server_name

Specify the name of the server that defines a connection to the MongoDB cluster.

Example

The following command drops a user mapping for a role named enterprisedb. The mapping is associated with a server named mongo_server.

DROP USER MAPPING FOR enterprisedb SERVER mongo_server;

For detailed information about the DROP USER MAPPING command, see the PostgreSQL documentation.

DROP FOREIGN TABLE

A foreign table is a pointer to a table that resides on the MongoDB host. Use the DROP FOREIGN TABLE command to remove a foreign table. Only the owner of the foreign table can drop it.

DROP FOREIGN TABLE [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ]

Parameters

IF EXISTS

Include the IF EXISTS clause to instruct the server to issue a notice instead of returning an error if the foreign table with the specified name doesn't exist.

name

Specify the name of the foreign table.

CASCADE

Drop objects that depend on the foreign table. It drops all the other dependent objects too.

RESTRICT

Don't allow to drop foreign table if any objects depend on it.

Example

DROP FOREIGN TABLE warehouse;

For more information about using the DROP FOREIGN TABLE command, see the PostgreSQL documentation.