4 SQL types and conversions

Connections automatically convert query results to appropriate Racket types. Likewise, query parameters are accepted as Racket values and converted to the appropriate SQL type.

Examples:

> (query-value pgc "select count(*) from the_numbers") 4 > (query-value pgc "select false") #f > (query-value pgc "select 1 + $1" 2) 3

If a query result contains a column with a SQL type not supported by this library, an exception is raised. As a workaround, cast the column to a supported type:

Examples:

> (query-value pgc "select inet '127.0.0.1'") query-value: unsupported type: inet (typeid 869) > (query-value pgc "select cast(inet '127.0.0.1' as varchar)") "127.0.0.1/32"

The exception for unsupported types in result columns is raised when the query is executed, not when it is prepared; for parameters it is raised when the parameter values are supplied. Thus even unexecutable prepared statements can be inspected using prepared-statement-parameter-types and prepared-statement-result-types.

4.1 SQL type conversions

This section describes the correspondences between SQL types and Racket types for the supported database systems.

4.1.1 PostgreSQL types

This section applies to connections created with postgresql-connect.

The following table lists the PostgreSQL types known to this library, along with their corresponding Racket representations.

PostgreSQL type		pg_type.typname		Racket type
'boolean		bool		boolean?
'char1		char		char?
'smallint		int2		exact-integer?
'integer		int4		exact-integer?
'bigint		int8		exact-integer?
'real		float4		real?
'double		float8		real?
'decimal		numeric		number?
'character		bpchar		string?
'varchar		varchar		string?
'text		text		string?
'bytea		bytea		bytes?
'date		date		sql-date?
'time		time		sql-time?
'timetz		timetz		sql-time?
'timestamp		timestamp		sql-timestamp?
'timestamptz		timestamptz		sql-timestamp?
'interval		interval		sql-interval?
'bit		bit		sql-bits?
'varbit		varbit		sql-bits?
'point		point		point?
'lseg		lseg		line?
'path		path		pg-path?
'box		box		pg-box?
'polygon		polygon		polygon?
'circle		circle		pg-circle?

The 'char1 type, written "char" in PostgreSQL’s SQL syntax (the quotation marks are significant), is one byte, essentially a tiny integer written as a character.

A SQL value of type decimal is converted to either an exact rational or +nan.0. When converting Scheme values to SQL decimal, exact rational values representable by finite decimal strings are converted without loss of precision. (Precision may be lost, of course, if the value is then stored in a database field of lower precision.) Other real values are converted to decimals with a loss of precision. In PostgreSQL, numeric and decimal refer to the same type.

Examples:

> (query-value pgc "select real '+Infinity'") +inf.0 > (query-value pgc "select numeric '12345678901234567890'") 12345678901234567890

The geometric types such as 'point are represented by structures defined in the (planet ryanc/db:1:4/util/geometry) and (planet ryanc/db:1:4/util/postgresql) modules.

PostgreSQL user-defined domains are supported in query results if the underlying type is supported. Recordset headers and prepared-statement-result-types report them in terms of the underlying type. Parameters with user-defined domain types are not currently supported. As a workaround, cast the parameter to the underlying type. For example, if the type of $1 is a domain whose underlying type is integer, then replace $1 with ($1::integer).

PostgreSQL defines many other types, such as network addresses, array types, and row types. These are currently not supported, but support may be added in future versions of this library.

4.1.2 MySQL types

This section applies to connections created with mysql-connect.

The following table lists the MySQL types known to this package, along with their corresponding Racket representations.

MySQL type		Racket type
'integer		exact-integer?
'tinyint		exact-integer?
'smallint		exact-integer?
'mediumint		exact-integer?
'bigint		exact-integer?
'real		real?
'double		real?
'decimal		exact?
'varchar		string?
'var-string		string? or bytes?, but see below
'date		sql-date?
'time		sql-time? or sql-day-time-interval?
'datetime		sql-timestamp?
'blob		bytes?
'tinyblob		bytes?
'mediumblob		bytes?
'longblob		bytes?
'bit		sql-bits?
'geometry		geometry2d?

MySQL does not report specific parameter types for prepared queries, instead assigning them the type var-string. Consequently, conversion of Racket values to var-string parameters accepts strings, numbers (rational?—no infinities or NaN), bytes, SQL date/time structures (sql-date?, sql-time?, sql-timestamp?, and sql-day-time-interval?), bits (sql-bits?), and geometric values (geometry2d?).

The MySQL time type represents time intervals, which may not correspond to times of day (for example, the interval may be negative or larger than 24 hours). In conversion from MySQL results to Racket values, those time values that represent times of day are converted to sql-time values; the rest are represented by sql-interval values.

The MySQL enum and set types are not supported. As a workaround, cast them to/from either integers or strings.

4.1.3 SQLite types

This section applies to connections created with sqlite3-connect.

The following table lists the SQLite types known to this package, along with their corresponding Racket representations.

Unlike PostgreSQL and MySQL, SQLite does not enforce declared type constraints (with the exception of integer primary key) on columns. Rather, every SQLite value has an associated “storage class”.

SQLite storage class		Racket type
integer		exact-integer?
real		real?
text		string?
blob		bytes?

SQLite does not report specific parameter and result types for prepared queries. Instead, they are assigned the pseudotype 'any. Conversion of Racket values to parameters accepts strings, bytes, and real numbers.

An exact integer that cannot be represented as a 64-bit signed integer is converted as real, not integer.

Examples:

> (expt 2 80) 1208925819614629174706176 > (query-value slc "select ?" (expt 2 80)) 1.2089258196146292e+24

4.1.4 ODBC types

This section applies to connections created with odbc-connect or odbc-driver-connect.

The following table lists the ODBC types known to this package, along with their corresponding Racket representations.

ODBC type		Racket type
'character		string?
'varchar		string?
'longvarchar		string?
'numeric		rational?
'decimal		rational?
'integer		exact-integer?
'tinyint		exact-integer?
'smallint		exact-integer?
'bigint		exact-integer?
'float		real?
'real		real?
'double		real?
'date		sql-date?
'time		sql-time?
'datetime		sql-timestamp?
'timestamp		sql-timestamp?
'binary		bytes?
'varbinary		bytes?
'longvarbinary		bytes?
'bit1		boolean?

Not all ODBC drivers provide specific parameter type information for prepared queries. Some omit parameter type information entirely or, worse, assign all parameters a single type such as varchar. To avoid enforcing irrelevant type constraints in the last case, connections only attempt to fetch and enforce parameter types when the connection is made using the #:strict-parameter-type? option. Otherwise, the connection assigns all parameters the type 'unknown. (The 'unknown type is also used when specific parameter types are requested but are not available.) Conversion of Racket values to 'unknown parameters accepts strings, bytes, numbers (rational?—no infinities or NaN), booleans, and SQL date/time structures (sql-date?, sql-time?, and sql-timestamp?).

The ODBC type 'bit1 represents a single bit, unlike the standard SQL bit(N) type.

Interval types are not currently supported on ODBC.

4.2 SQL data

This section describes data types for representing various SQL types that have no existing appropriate counterpart in Racket.

4.2.1 NULL

SQL NULL is translated into the unique sql-null value.

Example:

> (query-value c "select NULL") #<sql-null>

Examples:

> (sql-null->false "apple") "apple" > (sql-null->false sql-null) #f > (sql-null->false #f) #f

Examples:

> (false->sql-null "apple") "apple" > (false->sql-null #f) #<sql-null>

4.2.2 Dates and times

The DATE, TIME (WITH TIME ZONE and without), TIMESTAMP (WITH TIME ZONE and without), and INTERVAL SQL types are represented by the following structures.

Dates with zero-valued month or day components are a MySQL extension.

The tz field indicates the time zone offset as the number of seconds east of GMT (as in SRFI 19). If tz is #f, the time or timestamp does not carry time zone information.

The sql-time and sql-timestamp structures store fractional seconds to nanosecond precision for compatibility with SRFI 19. Note, however, that database systems generally do not support nanosecond precision; PostgreSQL, for example, only supports microsecond precision.

Examples:

> (query-value pgc "select date '25-dec-1980'") (sql-date 1980 12 25) > (query-value pgc "select time '7:30'") (sql-time 7 30 0 0 #f) > (query-value pgc "select timestamp 'epoch'") (sql-timestamp 1970 1 1 0 0 0 0 #f) > (query-value pgc "select timestamp with time zone 'epoch'") (sql-timestamp 1969 12 31 19 0 0 0 -18000)

Examples:

> (query-value myc "select date('1980-12-25')") (sql-date 1980 12 25) > (query-value myc "select time('7:30')") (sql-time 7 30 0 0 #f) > (query-value myc "select from_unixtime(0)") (sql-timestamp 1969 12 31 19 0 0 0 #f)

Examples:

> (sql-datetime->srfi-date    (query-value pgc "select time '7:30'")) (tm:date 0 0 30 7 0 0 0 0) > (sql-datetime->srfi-date    (query-value pgc "select date '25-dec-1980'")) (tm:date 0 0 0 0 25 12 1980 0) > (sql-datetime->srfi-date    (query-value pgc "select timestamp 'epoch'")) (tm:date 0 0 0 0 1 1 1970 0)

That is, an interval consists of two groups of components: year-month and day-time, and normalization is done only within groups. In fact, the SQL standard recognizes those two types of intervals separately (see sql-year-month-interval? and sql-day-time-interval?, below), and does not permit combining them. Intervals such as 1 month 3 days are a PostgreSQL extension.

If interval is out of range, the failure value is called, if it is a procedure, or returned, otherwise.

4.2.3 Bits

The BIT and BIT VARYING (VARBIT) SQL types are represented by sql-bits values.

Examples:

> (sql-bits->list (string->sql-bits "1011")) '(#t #f #t #t) > (sql-bits->string (query-value pgc "select B'010110111'")) "010110111"