Todos os produtos
Search

Este produto

    PolarDB:oss_fdw (OSS foreign data wrapper)

    Central de documentação

    PolarDB:oss_fdw (OSS foreign data wrapper)

    Última atualização: Sep 02, 2026

    Este tópico descreve a extensão oss_fdw, incluindo visão geral, limitações e uso.

    Visão geral

    A extensão oss_fdw é um foreign data wrapper (FDW) para PolarDB for PostgreSQL. Ela mapeia dados do Alibaba Cloud Object Storage Service (OSS) para tabelas externas no banco de dados, permitindo leitura e escrita de dados do OSS por meio de SQL padrão.

    O Alibaba Cloud OSS é um service de armazenamento em cloud massivo, seguro, econômico e altamente confiável, com disponibilidade de service de até 99,995%. Ele oferece vários tipos de armazenamento para otimizar custos. Dados históricos, dados de arquivamento somente leitura e dados frios em bancos de dados são ideais para armazenamento no OSS, o que reduz os custos de armazenamento do banco de dados.

    Pré-requisitos

    • Ative o Alibaba Cloud OSS e crie um bucket. Para mais informações, consulte Alibaba Cloud OSS.

    • Versões compatíveis do PolarDB for PostgreSQL:

      • PostgreSQL 16 (versão de revisão 2.0.16.6.2.0 ou posterior)

      • PostgreSQL 14 (versão de revisão 2.0.14.5.3.0 ou posterior)

      • PostgreSQL 11 (versão de revisão 2.0.11.2.1.0 ou posterior)

      Nota

      Para verificar a versão, consulte a versão de revisão no console ou execute a instrução SHOW polardb_version;. Se a versão de revisão não atender aos requisitos, atualize a versão de revisão.

    • Versões compatíveis do :

      • (versão de revisão 2.0.14.5.3.0 ou posterior)

      • (versão de revisão 2.0.11.2.1.0 ou posterior)

      Nota

      Para verificar a versão, consulte a versão de revisão no console ou execute a instrução SHOW polardb_version;. Se a versão de revisão não atender aos requisitos, atualize a versão de revisão.

    Limitações

    As tabelas externas oss_fdw aceitam apenas operações SELECT, INSERT e TRUNCATE. Não há suporte para operações UPDATE e DELETE. Portanto, o oss_fdw é adequado apenas para cenários de arquivamento de dados: após a gravação no OSS, os dados tornam-se somente leitura e não sofrem atualizações.

    Uso

    Instale a extensão

    CREATE EXTENSION oss_fdw;

    Crie um servidor de dados externos

    Configure as informações de conexão do OSS e crie um mapeamento do PolarDB para um bucket do OSS.

    Exemplo:

    CREATE SERVER ossserver
FOREIGN DATA WRAPPER oss_fdw
OPTIONS (
    host 'oss-cn-xxx.aliyuncs.com',
    bucket 'mybucket',
    id 'xxx',
    key 'xxx'
);
    Nota

    Parâmetros:

    • host: o endpoint do OSS.

    • bucket: o nome do bucket do OSS.

    • id/key: o AccessKey ID e o AccessKey Secret da sua conta Alibaba Cloud.

    Mapeie uma tabela externa para um diretório do OSS

    1. Crie uma tabela externa do OSS no PolarDB e mapeie-a para um diretório da source de dados do OSS configurada em Create a foreign data server.

      CREATE FOREIGN TABLE t1_oss (
    id INT,
    f FLOAT,
    txt TEXT
)
SERVER ossserver
OPTIONS (dir 'archive/');

    2. Importe dados para a tabela externa do OSS.

      INSERT INTO t1_oss VALUES (generate_series(1,100), 0.1, 'hello');

      Os dados inseridos são gravados em arquivos no caminho archive/ no OSS. Consulte a tabela externa conforme o exemplo a seguir.

      • Saída:

        EXPLAIN SELECT COUNT(*) FROM t1_oss;
                                   QUERY PLAN
-----------------------------------------------------------------
 Aggregate  (cost=6.54..6.54 rows=1 width=8)
   ->  Foreign Scan on t1_oss  (cost=0.00..6.40 rows=54 width=0)
         Directory on OSS: archive/
         Number Of OSS file: 1
         Total size of OSS file: 1292 bytes
(5 rows)

      • Saída:

        SELECT COUNT(*) FROM t1_oss;
         count
-------
   100
(1 row)

      Ao executar INSERT na tabela novamente, o sistema cria um novo arquivo no mesmo caminho do OSS.

      • INSERT INTO t1_oss VALUES (generate_series(1,100), 0.1, 'hello');

      • Consulte os dados da tabela:

        • Saída:

          EXPLAIN SELECT COUNT(*) FROM t1_oss;
                                      QUERY PLAN
-------------------------------------------------------------------
 Aggregate  (cost=12.07..12.08 rows=1 width=8)
   ->  Foreign Scan on t1_oss  (cost=0.00..11.80 rows=108 width=0)
         Directory on OSS: archive/
         Number Of OSS file: 2
         Total size of OSS file: 2584 bytes
(5 rows)

        • Saída:

          SELECT COUNT(*) FROM t1_oss;
           count
-------
   200
(1 row)

      Ao executar o comando TRUNCATE na tabela, o sistema remove todos os arquivos mapeados no OSS.

      TRUNCATE t1_oss;

      Consulte os dados da tabela após a remoção.

      SELECT COUNT(*) FROM t1_oss;

      Saída:

      WARNING:  does not match any file in oss
 count
-------
     0
(1 row)

    Mapeie uma tabela externa para um prefixo de caminho

    1. Crie uma tabela externa com a opção prefix.

      CREATE FOREIGN TABLE t2_oss (
    id INT,
    f FLOAT,
    txt TEXT
)
SERVER ossserver
OPTIONS (prefix 'prefix/file_');

    2. Várias inserções nesta tabela externa produzem múltiplos arquivos com o mesmo prefixo.

      INSERT INTO t2_oss VALUES (generate_series(1,100), 0.1, 'hello');
INSERT INTO t2_oss VALUES (generate_series(1,100), 0.1, 'hello');

EXPLAIN SELECT COUNT(*) FROM t2_oss;

      Saída:

                                  QUERY PLAN
-------------------------------------------------------------------
 Aggregate  (cost=12.07..12.08 rows=1 width=8)
   ->  Foreign Scan on t2_oss  (cost=0.00..11.80 rows=108 width=0)
         Directory on OSS: prefix/file_
         Number Of OSS file: 2
         Total size of OSS file: 2584 bytes
(5 rows)

      Consulte os dados da tabela:

      SELECT COUNT(*) FROM t2_oss;

      Saída:

       count
-------
   200
(1 row)

    Formato de armazenamento de arquivos no OSS

    O oss_fdw permite definir o formato de armazenamento de dados no OSS. O valor padrão é CSV, mas você pode declarar explicitamente o formato desejado. Ao executar INSERT em uma tabela externa do OSS, o sistema grava os dados nos arquivos do OSS no formato CSV.

    CREATE FOREIGN TABLE t3_oss (
    id INT,
    f FLOAT,
    txt TEXT
)
SERVER ossserver
OPTIONS (dir 'archive_csv/', format 'csv');

    Visualize os arquivos correspondentes a uma tabela externa do OSS

    1. Crie uma tabela externa do OSS e execute três instruções INSERT. O sistema gravará três arquivos no OSS.

      CREATE FOREIGN TABLE t4_oss (
    id INT,
    f FLOAT,
    txt TEXT
)
SERVER ossserver
OPTIONS (dir 'archive_file_list/');

INSERT INTO t4_oss VALUES (generate_series(1,10000), 0.1, 'hello');
INSERT INTO t4_oss VALUES (generate_series(1,10000), 0.1, 'hello');
INSERT INTO t4_oss VALUES (generate_series(1,10000), 0.1, 'hello');

    2. Use a função a seguir para consultar os arquivos correspondentes à tabela externa do OSS. Especifique o nome da tabela e, opcionalmente, o nome do schema (o padrão é public).

      • Consulte os arquivos correspondentes à tabela externa do OSS usando o nome de schema padrão.

        SELECT * FROM oss_fdw_list_file('t4_oss');

        Saída:

                           name                    |  size
-------------------------------------------+--------
 archive_file_list/_t4_oss_783053364762580 | 148894
 archive_file_list/_t4_oss_783053364849053 | 148894
 archive_file_list/_t4_oss_783053366496328 | 148894
(3 rows)

      • Especifique um nome de schema para consultar os arquivos correspondentes à tabela externa do OSS.

        SELECT * FROM oss_fdw_list_file('t4_oss', 'public');

        Saída:

                           name                    |  size
-------------------------------------------+--------
 archive_file_list/_t4_oss_783053364762580 | 148894
 archive_file_list/_t4_oss_783053364849053 | 148894
 archive_file_list/_t4_oss_783053366496328 | 148894
(3 rows)

    Compressão de armazenamento no OSS

    Use o parâmetro compressiontype para especificar o algoritmo de compressão na gravação de arquivos do OSS. O valor padrão é vazio (sem compressão). Valores válidos: gzip ou zstd.

    Use o parâmetro compressionlevel para selecionar o nível de compressão. Níveis mais altos consomem mais cpu durante a compressão e descompressão, mas reduzem o tráfego de rede e o espaço de armazenamento usado pelos dados da tabela externa no OSS.

    Compressão Gzip

    O nível de compressão Gzip varia de 1 a 9, com padrão de 6.

    CREATE FOREIGN TABLE t5_oss (
    id INT,
    f FLOAT,
    txt TEXT
)
SERVER ossserver
OPTIONS (
    dir 'archive_file_compression/',
    compressiontype 'gzip',
    compressionlevel '9'
);

INSERT INTO t5_oss VALUES (generate_series(1,10000), 0.1, 'hello');
INSERT INTO t5_oss VALUES (generate_series(1,10000), 0.1, 'hello');
INSERT INTO t5_oss VALUES (generate_series(1,10000), 0.1, 'hello');

    Visualize os arquivos correspondentes à tabela externa do OSS. Observe que os tamanhos dos arquivos após a compressão Gzip são significativamente menores que os da tabela externa sem compressão.

    • Tamanhos de arquivos da tabela externa sem compressão Gzip:

      SELECT * FROM oss_fdw_list_file('t4_oss');

      Saída:

                         name                    |  size
-------------------------------------------+--------
 archive_file_list/_t4_oss_741147680906121 | 148894
 archive_file_list/_t4_oss_741147680965631 | 148894
 archive_file_list/_t4_oss_741147681201236 | 148894
(3 rows)

    • Tamanhos de arquivos da tabela externa após compressão Gzip:

      SELECT * FROM oss_fdw_list_file('t5_oss');

      Saída:

                              name                         | size
-----------------------------------------------------+-------
 archive_file_compression/_t5_oss_741147752563794.gz | 23654
 archive_file_compression/_t5_oss_741147752633713.gz | 23654
 archive_file_compression/_t5_oss_741147752828680.gz | 23654
(3 rows)

    Compressão Zstandard

    Nota

    A compressão Zstandard é compatível apenas com PostgreSQL 14 (versão de revisão 14.9.13.0 ou posterior).

    O nível de compressão Zstandard varia de -7 a 22, com padrão de 6.

    CREATE FOREIGN TABLE t6_oss (
    id INT,
    f FLOAT,
    txt TEXT
)
SERVER ossserver
OPTIONS (
    dir 'archive_file_zstd/',
    compressiontype 'zstd',
    compressionlevel '9'
);

INSERT INTO t6_oss VALUES (generate_series(1,10000), 0.1, 'hello');
INSERT INTO t6_oss VALUES (generate_series(1,10000), 0.1, 'hello');
INSERT INTO t6_oss VALUES (generate_series(1,10000), 0.1, 'hello');

    Visualize os arquivos correspondentes à tabela externa do OSS. Observe que os tamanhos dos arquivos após a compressão Zstandard são significativamente menores que os da tabela externa sem compressão.

    • Tamanhos de arquivos da tabela externa sem compressão Zstandard:

      SELECT * FROM oss_fdw_list_file('t4_oss');

      Saída:

                         name                    |  size
-------------------------------------------+--------
 archive_file_list/_t4_oss_741147680906121 | 148894
 archive_file_list/_t4_oss_741147680965631 | 148894
 archive_file_list/_t4_oss_741147681201236 | 148894
(3 rows)

    • Tamanhos de arquivos da tabela externa após compressão Zstandard:

      SELECT * FROM oss_fdw_list_file('t6_oss');

      Saída:

                           name                      | size
-----------------------------------------------+------
 archive_file_zstd/_t6_oss_748106174612293.zst | 6710
 archive_file_zstd/_t6_oss_748106174700206.zst | 6710
 archive_file_zstd/_t6_oss_748106174866829.zst | 6710
(3 rows)

    Remova a extensão

    DROP EXTENSION oss_fdw;