diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 2726666..eff3ebe 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-08T02:47:13","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-09T02:43:18","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index b9a9649..0125679 100644 --- a/dev/index.html +++ b/dev/index.html @@ -60,4 +60,4 @@ conn = DBInterface.connect(LibPQ.Connection, "dbname=postgres") res = DBInterface.execute(con, "SELECT * FROM table") -DBInterface.close!(conn) +DBInterface.close!(conn) diff --git a/dev/pages/api/index.html b/dev/pages/api/index.html index 965c526..274d586 100644 --- a/dev/pages/api/index.html +++ b/dev/pages/api/index.html @@ -39,4 +39,4 @@ true julia> pqv"9.2.5" == v"9.2.5" -truesource
LibPQ.string_parameters — Function
string_parameters(parameters::AbstractVector) -> Vector{Union{String, Missing}}

Convert parameters to strings which can be passed to libpq, propagating missing.

source
LibPQ.parameter_pointers — Function
parameter_pointers(parameters::AbstractVector{<:Parameter}) -> Vector{Ptr{UInt8}}

Given a vector of parameters, returns a vector of pointers to either the string bytes in the original or C_NULL if the element is missing.

source
LibPQ.unsafe_string_or_null — Function
unsafe_string_or_null(ptr::Cstring) -> Union{String, Missing}

Convert a Cstring to a Union{String, Missing}, returning missing if the pointer is C_NULL.

source
+truesource
LibPQ.string_parameters — Function
string_parameters(parameters::AbstractVector) -> Vector{Union{String, Missing}}

Convert parameters to strings which can be passed to libpq, propagating missing.

source
LibPQ.parameter_pointers — Function
parameter_pointers(parameters::AbstractVector{<:Parameter}) -> Vector{Ptr{UInt8}}

Given a vector of parameters, returns a vector of pointers to either the string bytes in the original or C_NULL if the element is missing.

source
LibPQ.unsafe_string_or_null — Function
unsafe_string_or_null(ptr::Cstring) -> Union{String, Missing}

Convert a Cstring to a Union{String, Missing}, returning missing if the pointer is C_NULL.

source
diff --git a/dev/pages/faq/index.html b/dev/pages/faq/index.html index e8c1d5f..b35c361 100644 --- a/dev/pages/faq/index.html +++ b/dev/pages/faq/index.html @@ -1,2 +1,2 @@ -FAQ · LibPQ.jl
GitHub

Frequently Asked Questions

Can I use LibPQ.jl with Amazon Redshift?

Yes. However, LibPQ.jl by default sets some client options to make interactions more reliable. Unsupported options must be disabled for Redshift to allow connections. To override all options, pass an empty Dict{String, String}:

conn = LibPQ.Connection("dbname=myredshift"; options=Dict{String, String}())

How do I test LibPQ.jl on my own computer?

To test LibPQ.jl you will need access to a PostgreSQL database server with a database called "postgres". The tests will not make any changes to the database that persist beyond the connection session, even if the tests encounter unforeseen exceptions. For this reason, it should be safe to use any existing database server. To set the database user used to connect to the database, use the LIBPQJL_DATABASE_USER environment variable.

A simple way to set up a server for testing is to use Docker:

docker run --detach --name test-libpqjl -e POSTGRES_HOST_AUTH_METHOD=trust -p 5432:5432 postgres

To set any other client options for connecting to the test database, use the PostgreSQL environment variables. You will likely need to set PGHOST=localhost to connect using the TCP socket instead of the UNIX domain socket.

+FAQ · LibPQ.jl
GitHub

Frequently Asked Questions

Can I use LibPQ.jl with Amazon Redshift?

Yes. However, LibPQ.jl by default sets some client options to make interactions more reliable. Unsupported options must be disabled for Redshift to allow connections. To override all options, pass an empty Dict{String, String}:

conn = LibPQ.Connection("dbname=myredshift"; options=Dict{String, String}())

How do I test LibPQ.jl on my own computer?

To test LibPQ.jl you will need access to a PostgreSQL database server with a database called "postgres". The tests will not make any changes to the database that persist beyond the connection session, even if the tests encounter unforeseen exceptions. For this reason, it should be safe to use any existing database server. To set the database user used to connect to the database, use the LIBPQJL_DATABASE_USER environment variable.

A simple way to set up a server for testing is to use Docker:

docker run --detach --name test-libpqjl -e POSTGRES_HOST_AUTH_METHOD=trust -p 5432:5432 postgres

To set any other client options for connecting to the test database, use the PostgreSQL environment variables. You will likely need to set PGHOST=localhost to connect using the TCP socket instead of the UNIX domain socket.

diff --git a/dev/pages/type-conversions/index.html b/dev/pages/type-conversions/index.html index 6522e29..887c0a2 100644 --- a/dev/pages/type-conversions/index.html +++ b/dev/pages/type-conversions/index.html @@ -8,4 +8,4 @@ 1×5 DataFrames.DataFrame │ Row │ int4 │ varchar │ float8 │ bool │ timestamp │ ├─────┼──────┼─────────┼─────────────────┼───────┼─────────────────────┤ -│ 1 │ 1 │ foo │ [1.0, 2.1, 3.3] │ false │ 2004-10-19T10:23:54 │

The column types in Julia for the above DataFrame are Int32, String, Vector{Float64}, Bool, and DateTime.

Any unknown or unsupported types are parsed as Strings by default.

NULL

The PostgreSQL NULL is handled with missing. By default, data streamed using the Tables interface is Union{T, Missing}, and columns are Vector{Union{T, Missing}}. While libpq does not provide an interface for checking whether a result column contains NULL, it's possible to assert that columns do not contain NULL using the not_null keyword argument to execute. This will result in data retrieved as T/Vector{T} instead. not_null accepts a list of column names or column positions, or a Bool asserting that all columns do or do not have the possibility of NULL.

The type-related interfaces described below only deal with the T part of the Union{T, Missing}, and there is currently no way to use an alternate NULL representation.

Overrides

It's possible to override the default type conversion behaviour in several places. Refer to the Implementation section for more detailed information.

Query-level

There are three arguments to execute for this:

Connection-level

LibPQ.Connection supports type_map and conversions arguments as well, which will apply to all queries run with the created connection. Query-level overrides will override connection-level overrides.

Global

To override behaviour for every query everywhere, add mappings to the global constants LibPQ.LIBPQ_TYPE_MAP and LibPQ.LIBPQ_CONVERSIONS. Connection-level overrides will override these global overrides.

Implementation

Flow

When a LibPQ.Result is created (as the result of running a query), the Julia types and conversion functions for each column are precalculated and stored within the Result. The types are chosen using these sources, in decreasing priority:

Using those types, the function for converting from PostgreSQL data to Julia data is selected, using these sources, in decreasing priority:

When fetching a particular value from a Result, that function is used to turn data wrapped by a PQValue to a Julia type. This operation always copies or parses data and never provides a view into the original Result.

Canonical PostgreSQL Type Names

While PostgreSQL allows many aliases for its types (e.g., double precision for float8 and character varying for varchar), there is one "canonical" name for the type stored in the pg_type table from PostgreSQL's catalog. You can find a list of these for all of PostgreSQL's default types in the keys of LibPQ.PQ_SYSTEM_TYPES.

+│ 1 │ 1 │ foo │ [1.0, 2.1, 3.3] │ false │ 2004-10-19T10:23:54 │

The column types in Julia for the above DataFrame are Int32, String, Vector{Float64}, Bool, and DateTime.

Any unknown or unsupported types are parsed as Strings by default.

NULL

The PostgreSQL NULL is handled with missing. By default, data streamed using the Tables interface is Union{T, Missing}, and columns are Vector{Union{T, Missing}}. While libpq does not provide an interface for checking whether a result column contains NULL, it's possible to assert that columns do not contain NULL using the not_null keyword argument to execute. This will result in data retrieved as T/Vector{T} instead. not_null accepts a list of column names or column positions, or a Bool asserting that all columns do or do not have the possibility of NULL.

The type-related interfaces described below only deal with the T part of the Union{T, Missing}, and there is currently no way to use an alternate NULL representation.

Overrides

It's possible to override the default type conversion behaviour in several places. Refer to the Implementation section for more detailed information.

Query-level

There are three arguments to execute for this:

Connection-level

LibPQ.Connection supports type_map and conversions arguments as well, which will apply to all queries run with the created connection. Query-level overrides will override connection-level overrides.

Global

To override behaviour for every query everywhere, add mappings to the global constants LibPQ.LIBPQ_TYPE_MAP and LibPQ.LIBPQ_CONVERSIONS. Connection-level overrides will override these global overrides.

Implementation

Flow

When a LibPQ.Result is created (as the result of running a query), the Julia types and conversion functions for each column are precalculated and stored within the Result. The types are chosen using these sources, in decreasing priority:

Using those types, the function for converting from PostgreSQL data to Julia data is selected, using these sources, in decreasing priority:

When fetching a particular value from a Result, that function is used to turn data wrapped by a PQValue to a Julia type. This operation always copies or parses data and never provides a view into the original Result.

Canonical PostgreSQL Type Names

While PostgreSQL allows many aliases for its types (e.g., double precision for float8 and character varying for varchar), there is one "canonical" name for the type stored in the pg_type table from PostgreSQL's catalog. You can find a list of these for all of PostgreSQL's default types in the keys of LibPQ.PQ_SYSTEM_TYPES.