PostgreSQL Driver

Available for: C/C++, GLib/Ruby, Go, Python, R

The PostgreSQL driver provides access to any database that supports the PostgreSQL wire format. It wraps libpq, the client library for PostgreSQL. The project owes credit to 0x0L’s pgeon for the overall approach.

Note

This project is not affiliated with PostgreSQL in any way.

Note

The PostgreSQL driver is experimental. Performance/optimization and support for complex types and different ADBC features is still ongoing.

Installation

C/C++

For conda-forge users:

mamba install libadbc-driver-postgresql

Go

Install the C/C++ package and use the Go driver manager. Requires CGO.

go get github.com/apache/arrow-adbc/go/adbc/drivermgr

Python

# For conda-forge
mamba install adbc-driver-postgresql

# For pip
pip install adbc_driver_postgresql

R

# install.packages("pak")
pak::pak("apache/arrow-adbc/r/adbcpostgresql")

Usage

To connect to a database, supply the “uri” parameter when constructing the AdbcDatabase. This should be a connection URI.

C++

#include "adbc.h"

// Ignoring error handling
struct AdbcDatabase database;
AdbcDatabaseNew(&database, nullptr);
AdbcDatabaseSetOption(&database, "uri", "postgresql://localhost:5433", nullptr);
AdbcDatabaseInit(&database, nullptr);

Go

You must have libadbc_driver_postgresql.so on your LD_LIBRARY_PATH, or in the same directory as the executable when you run this. This requires CGO and loads the C++ ADBC postgresql driver.

import (
   "context"

   "github.com/apache/arrow-adbc/go/adbc"
   "github.com/apache/arrow-adbc/go/adbc/drivermgr"
)

func main() {
   var drv drivermgr.Driver
   db, err := drv.NewDatabase(map[string]string{
      "driver": "adbc_driver_postgresql",
      adbc.OptionKeyURI: "postgresql://user:pass@localhost:5433/postgres",
   })
   if err != nil {
      // handle error
   }

   cnxn, err := db.Open(context.Background())
   if err != nil {
      // handle error
   }
   defer cnxn.Close()
}

Python

import adbc_driver_postgresql.dbapi

uri = "postgresql://user:pass@localhost:5433/postgres"
with adbc_driver_postgresql.dbapi.connect(uri) as conn:
    pass

For more examples, see PostgreSQL Recipes.

R

library(adbcdrivermanager)

# Use the driver manager to connect to a database
uri <- Sys.getenv("ADBC_POSTGRESQL_TEST_URI")
db <- adbc_database_init(adbcpostgresql::adbcpostgresql(), uri = uri)
con <- adbc_connection_init(db)

Supported Features

The PostgreSQL driver mostly supports features defined in the ADBC API specification 1.0.0, but not all cases are fully implemented (particularly around bind parameters and prepared statements).

Bulk Ingestion

Bulk ingestion is supported. The mapping from Arrow types to PostgreSQL types is the same as below.

Partitioned Result Sets

Partitioned result sets are not supported.

Transactions

Transactions are supported.

Type Support

PostgreSQL allows defining new types at runtime, so the driver must build a mapping of available types. This is currently done once at startup.

Type support is currently limited. Parameter binding and bulk ingestion support int16, int32, int64, and string. Reading result sets is limited to int32, int64, float, double, and string.