DBI/0000755000176200001440000000000014627164412010657 5ustar liggesusersDBI/NAMESPACE0000644000176200001440000000632014602466070012075 0ustar liggesusers# Generated by roxygen2: do not edit by hand S3method("[",SQL) S3method("[[",SQL) S3method(toString,Id) export(.SQL92Keywords) export(ANSI) export(Id) export(SQL) export(SQLKeywords) export(dbAppendTable) export(dbAppendTableArrow) export(dbBegin) export(dbBind) export(dbBindArrow) export(dbBreak) export(dbCallProc) export(dbCanConnect) export(dbClearResult) export(dbColumnInfo) export(dbCommit) export(dbConnect) export(dbCreateTable) export(dbCreateTableArrow) export(dbDataType) export(dbDisconnect) export(dbDriver) export(dbExecute) export(dbExistsTable) export(dbFetch) export(dbFetchArrow) export(dbFetchArrowChunk) export(dbGetConnectArgs) export(dbGetDBIVersion) export(dbGetException) export(dbGetInfo) export(dbGetQuery) export(dbGetQueryArrow) export(dbGetRowCount) export(dbGetRowsAffected) export(dbGetStatement) export(dbHasCompleted) export(dbIsReadOnly) export(dbIsValid) export(dbListConnections) export(dbListFields) export(dbListObjects) export(dbListResults) export(dbListTables) export(dbQuoteIdentifier) export(dbQuoteLiteral) export(dbQuoteString) export(dbReadTable) export(dbReadTableArrow) export(dbRemoveTable) export(dbRollback) export(dbSendQuery) export(dbSendQueryArrow) export(dbSendStatement) export(dbSetDataMappings) export(dbUnloadDriver) export(dbUnquoteIdentifier) export(dbWithTransaction) export(dbWriteTable) export(dbWriteTableArrow) export(fetch) export(isSQLKeyword) export(isSQLKeyword.default) export(make.db.names) export(make.db.names.default) export(sqlAppendTable) export(sqlAppendTableTemplate) export(sqlColumnToRownames) export(sqlCommentSpec) export(sqlCreateTable) export(sqlData) export(sqlInterpolate) export(sqlParseVariables) export(sqlParseVariablesImpl) export(sqlQuoteSpec) export(sqlRownamesToColumn) exportClasses(DBIConnection) exportClasses(DBIConnector) exportClasses(DBIDriver) exportClasses(DBIObject) exportClasses(DBIResult) exportClasses(DBIResultArrow) exportClasses(DBIResultArrowDefault) exportClasses(SQL) exportMethods(dbAppendTable) exportMethods(dbAppendTableArrow) exportMethods(dbBind) exportMethods(dbBindArrow) exportMethods(dbCanConnect) exportMethods(dbClearResult) exportMethods(dbConnect) exportMethods(dbCreateTable) exportMethods(dbCreateTableArrow) exportMethods(dbDataType) exportMethods(dbExecute) exportMethods(dbExistsTable) exportMethods(dbFetch) exportMethods(dbFetchArrow) exportMethods(dbFetchArrowChunk) exportMethods(dbGetConnectArgs) exportMethods(dbGetInfo) exportMethods(dbGetQuery) exportMethods(dbGetQueryArrow) exportMethods(dbGetRowCount) exportMethods(dbGetRowsAffected) exportMethods(dbGetStatement) exportMethods(dbHasCompleted) exportMethods(dbIsValid) exportMethods(dbListFields) exportMethods(dbListObjects) exportMethods(dbQuoteIdentifier) exportMethods(dbQuoteLiteral) exportMethods(dbQuoteString) exportMethods(dbReadTable) exportMethods(dbReadTableArrow) exportMethods(dbRemoveTable) exportMethods(dbSendQueryArrow) exportMethods(dbSendStatement) exportMethods(dbUnquoteIdentifier) exportMethods(dbWithTransaction) exportMethods(dbWriteTable) exportMethods(dbWriteTableArrow) exportMethods(show) exportMethods(sqlAppendTable) exportMethods(sqlCreateTable) exportMethods(sqlData) exportMethods(sqlInterpolate) exportMethods(sqlParseVariables) import(methods) DBI/.Rinstignore0000644000176200001440000000002514350241735013155 0ustar liggesusersinst/doc/figure1.pdf DBI/README.md0000644000176200001440000001371414627140050012134 0ustar liggesusers # DBI [![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable) [![rcc](https://github.com/r-dbi/DBI/workflows/rcc/badge.svg)](https://github.com/r-dbi/DBI/actions) [![Coverage Status](https://codecov.io/gh/r-dbi/DBI/branch/main/graph/badge.svg)](https://app.codecov.io/github/r-dbi/DBI?branch=main) [![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/DBI)](https://cran.r-project.org/package=DBI) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1882/badge)](https://bestpractices.coreinfrastructure.org/projects/1882) The DBI package helps connecting R to database management systems (DBMS). DBI separates the connectivity to the DBMS into a “front-end” and a “back-end”. The package defines an interface that is implemented by *DBI backends* such as: - [RPostgres](https://rpostgres.r-dbi.org), - [RMariaDB](https://rmariadb.r-dbi.org), - [RSQLite](https://rsqlite.r-dbi.org), - [odbc](https://github.com/r-dbi/odbc), - [bigrquery](https://github.com/r-dbi/bigrquery), and many more, see the [list of backends](https://github.com/r-dbi/backends#readme). R scripts and packages use DBI to access various databases through their DBI backends. The interface defines a small set of classes and methods similar in spirit to Perl’s [DBI](https://dbi.perl.org/), Java’s JDBC, Python’s [DB-API](https://www.python.org/dev/peps/pep-0249/), and Microsoft’s [ODBC](https://en.wikipedia.org/wiki/ODBC). It supports the following operations: - connect/disconnect to the DBMS - create and execute statements in the DBMS - extract results/output from statements - error/exception handling - information (meta-data) from database objects - transaction management (optional) ## Installation Most users who want to access a database do not need to install DBI directly. It will be installed automatically when you install one of the database backends: - [RPostgres](https://rpostgres.r-dbi.org) for PostgreSQL, - [RMariaDB](https://rmariadb.r-dbi.org) for MariaDB or MySQL, - [RSQLite](https://rsqlite.r-dbi.org) for SQLite, - [odbc](https://github.com/r-dbi/odbc) for databases that you can access via [ODBC](https://en.wikipedia.org/wiki/Open_Database_Connectivity), - [bigrquery](https://github.com/r-dbi/bigrquery), - … . You can install the released version of DBI from [CRAN](https://CRAN.R-project.org) with: ``` r install.packages("DBI") ``` And the development version from [GitHub](https://github.com/) with: ``` r # install.packages("devtools") devtools::install_github("r-dbi/DBI") ``` ## Example The following example illustrates some of the DBI capabilities: ``` r library(DBI) # Create an ephemeral in-memory RSQLite database con <- dbConnect(RSQLite::SQLite(), dbname = ":memory:") dbListTables(con) #> character(0) dbWriteTable(con, "mtcars", mtcars) dbListTables(con) #> [1] "mtcars" dbListFields(con, "mtcars") #> [1] "mpg" "cyl" "disp" "hp" "drat" "wt" "qsec" "vs" "am" "gear" #> [11] "carb" dbReadTable(con, "mtcars") #> mpg cyl disp hp drat wt qsec vs am gear carb #> 1 21.0 6 160.0 110 3.90 2.620 16.46 0 1 4 4 #> 2 21.0 6 160.0 110 3.90 2.875 17.02 0 1 4 4 #> 3 22.8 4 108.0 93 3.85 2.320 18.61 1 1 4 1 #> 4 21.4 6 258.0 110 3.08 3.215 19.44 1 0 3 1 #> 5 18.7 8 360.0 175 3.15 3.440 17.02 0 0 3 2 #> 6 18.1 6 225.0 105 2.76 3.460 20.22 1 0 3 1 #> 7 14.3 8 360.0 245 3.21 3.570 15.84 0 0 3 4 #> 8 24.4 4 146.7 62 3.69 3.190 20.00 1 0 4 2 #> 9 22.8 4 140.8 95 3.92 3.150 22.90 1 0 4 2 #> [ reached 'max' / getOption("max.print") -- omitted 23 rows ] # You can fetch all results: res <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") dbFetch(res) #> mpg cyl disp hp drat wt qsec vs am gear carb #> 1 22.8 4 108.0 93 3.85 2.320 18.61 1 1 4 1 #> 2 24.4 4 146.7 62 3.69 3.190 20.00 1 0 4 2 #> 3 22.8 4 140.8 95 3.92 3.150 22.90 1 0 4 2 #> 4 32.4 4 78.7 66 4.08 2.200 19.47 1 1 4 1 #> 5 30.4 4 75.7 52 4.93 1.615 18.52 1 1 4 2 #> 6 33.9 4 71.1 65 4.22 1.835 19.90 1 1 4 1 #> 7 21.5 4 120.1 97 3.70 2.465 20.01 1 0 3 1 #> 8 27.3 4 79.0 66 4.08 1.935 18.90 1 1 4 1 #> 9 26.0 4 120.3 91 4.43 2.140 16.70 0 1 5 2 #> [ reached 'max' / getOption("max.print") -- omitted 2 rows ] dbClearResult(res) # Or a chunk at a time res <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") while (!dbHasCompleted(res)) { chunk <- dbFetch(res, n = 5) print(nrow(chunk)) } #> [1] 5 #> [1] 5 #> [1] 1 dbClearResult(res) dbDisconnect(con) ``` ## Class structure There are four main DBI classes. Three which are each extended by individual database backends: - `DBIObject`: a common base class for all DBI. - `DBIDriver`: a base class representing overall DBMS properties. Typically generator functions instantiate the driver objects like `RSQLite()`, `RPostgreSQL()`, `RMySQL()` etc. - `DBIConnection`: represents a connection to a specific database - `DBIResult`: the result of a DBMS query or statement. All classes are *virtual*: they cannot be instantiated directly and instead must be subclassed. ## Further Reading - [Databases using R](https://db.rstudio.com/) describes the tools and best practices in this ecosystem. - The [DBI project site](https://r-dbi.org/) hosts a blog where recent developments are presented. - [A history of DBI](https://dbi.r-dbi.org/articles/DBI-history.html) by David James, the driving force behind the development of DBI, and many of the packages that implement it. ------------------------------------------------------------------------ Please note that the *DBI* project is released with a [Contributor Code of Conduct](https://dbi.r-dbi.org/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. DBI/man/0000755000176200001440000000000014627140170011425 5ustar liggesusersDBI/man/dbQuoteLiteral.Rd0000644000176200001440000000562714602466070014651 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbQuoteLiteral.R \name{dbQuoteLiteral} \alias{dbQuoteLiteral} \title{Quote literal values} \usage{ dbQuoteLiteral(conn, x, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{x}{A vector to quote as string.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbQuoteLiteral()} returns an object that can be coerced to \link{character}, of the same length as the input. For an empty integer, numeric, character, logical, date, time, or blob vector, this function returns a length-0 object. When passing the returned object again to \code{dbQuoteLiteral()} as \code{x} argument, it is returned unchanged. Passing objects of class \link{SQL} should also return them unchanged. (For backends it may be most convenient to return \link{SQL} objects to achieve this behavior, but this is not required.) } \description{ Call these methods to generate a string that is suitable for use in a query as a literal value of the correct type, to make sure that you generate valid SQL and protect against SQL injection attacks. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbQuoteLiteral")} } \section{Failure modes}{ Passing a list for the \code{x} argument raises an error. } \section{Specification}{ The returned expression can be used in a \verb{SELECT ...} query, and the value of \code{dbGetQuery(paste0("SELECT ", dbQuoteLiteral(x)))[[1]]} must be equal to \code{x} for any scalar integer, numeric, string, and logical. If \code{x} is \code{NA}, the result must merely satisfy \code{\link[=is.na]{is.na()}}. The literals \code{"NA"} or \code{"NULL"} are not treated specially. \code{NA} should be translated to an unquoted SQL \code{NULL}, so that the query \verb{SELECT * FROM (SELECT 1) a WHERE ... IS NULL} returns one row. } \examples{ # Quoting ensures that arbitrary input is safe for use in a query name <- "Robert'); DROP TABLE Students;--" dbQuoteLiteral(ANSI(), name) # NAs become NULL dbQuoteLiteral(ANSI(), c(1:3, NA)) # Logicals become integers by default dbQuoteLiteral(ANSI(), c(TRUE, FALSE, NA)) # Raw vectors become hex strings by default dbQuoteLiteral(ANSI(), list(as.raw(1:3), NULL)) # SQL vectors are always passed through as is var_name <- SQL("select") var_name dbQuoteLiteral(ANSI(), var_name) # This mechanism is used to prevent double escaping dbQuoteLiteral(ANSI(), dbQuoteLiteral(ANSI(), name)) } \seealso{ Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteString}()} } \concept{DBIResult generics} DBI/man/sqlAppendTable.Rd0000644000176200001440000000531514350241735014621 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/sqlAppendTable.R, R/sqlAppendTableTemplate.R \name{sqlAppendTable} \alias{sqlAppendTable} \alias{sqlAppendTableTemplate} \title{Compose query to insert rows into a table} \usage{ sqlAppendTable(con, table, values, row.names = NA, ...) sqlAppendTableTemplate( con, table, values, row.names = NA, prefix = "?", ..., pattern = "" ) } \arguments{ \item{con}{A database connection.} \item{table}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{values}{A data frame. Factors will be converted to character vectors. Character vectors will be escaped with \code{\link[=dbQuoteString]{dbQuoteString()}}.} \item{row.names}{Either \code{TRUE}, \code{FALSE}, \code{NA} or a string. If \code{TRUE}, always translate row names to a column called "row_names". If \code{FALSE}, never translate row names. If \code{NA}, translate rownames only if they're a character vector. A string is equivalent to \code{TRUE}, but allows you to override the default name. For backward compatibility, \code{NULL} is equivalent to \code{FALSE}.} \item{...}{Other arguments used by individual methods.} \item{prefix}{Parameter prefix to use for placeholders.} \item{pattern}{Parameter pattern to use for placeholders: \itemize{ \item \code{""}: no pattern \item \code{"1"}: position \item anything else: field name }} } \description{ \code{sqlAppendTable()} generates a single SQL string that inserts a data frame into an existing table. \code{sqlAppendTableTemplate()} generates a template suitable for use with \code{\link[=dbBind]{dbBind()}}. The default methods are ANSI SQL 99 compliant. These methods are mostly useful for backend implementers. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("sqlAppendTable")} } \details{ The \code{row.names} argument must be passed explicitly in order to avoid a compatibility warning. The default will be changed in a later release. } \examples{ sqlAppendTable(ANSI(), "iris", head(iris)) sqlAppendTable(ANSI(), "mtcars", head(mtcars)) sqlAppendTable(ANSI(), "mtcars", head(mtcars), row.names = FALSE) sqlAppendTableTemplate(ANSI(), "iris", iris) sqlAppendTableTemplate(ANSI(), "mtcars", mtcars) sqlAppendTableTemplate(ANSI(), "mtcars", mtcars, row.names = FALSE) } \concept{SQL generation} DBI/man/SQL.Rd0000644000176200001440000000360414350241735012360 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/SQL.R \docType{class} \name{SQL} \alias{SQL} \alias{SQL-class} \title{SQL quoting} \usage{ SQL(x, ..., names = NULL) } \arguments{ \item{x}{A character vector to label as being escaped SQL.} \item{...}{Other arguments passed on to methods. Not otherwise used.} \item{names}{Names for the returned object, must have the same length as \code{x}.} } \value{ An object of class \code{SQL}. } \description{ This set of classes and generics make it possible to flexibly deal with SQL escaping needs. By default, any user supplied input to a query should be escaped using either \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or \code{\link[=dbQuoteString]{dbQuoteString()}} depending on whether it refers to a table or variable name, or is a literal string. These functions may return an object of the \code{SQL} class, which tells DBI functions that a character string does not need to be escaped anymore, to prevent double escaping. The \code{SQL} class has associated the \code{SQL()} constructor function. } \section{Implementation notes}{ DBI provides default generics for SQL-92 compatible quoting. If the database uses a different convention, you will need to provide your own methods. Note that because of the way that S4 dispatch finds methods and because SQL inherits from character, if you implement (e.g.) a method for \code{dbQuoteString(MyConnection, character)}, you will also need to implement \code{dbQuoteString(MyConnection, SQL)} - this should simply return \code{x} unchanged. } \examples{ dbQuoteIdentifier(ANSI(), "SELECT") dbQuoteString(ANSI(), "SELECT") # SQL vectors are always passed through as is var_name <- SQL("SELECT") var_name dbQuoteIdentifier(ANSI(), var_name) dbQuoteString(ANSI(), var_name) # This mechanism is used to prevent double escaping dbQuoteString(ANSI(), dbQuoteString(ANSI(), "SELECT")) } DBI/man/dbCanConnect.Rd0000644000176200001440000000337714602466070014252 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbCanConnect.R \name{dbCanConnect} \alias{dbCanConnect} \title{Check if a connection to a DBMS can be established} \usage{ dbCanConnect(drv, ...) } \arguments{ \item{drv}{an object that inherits from \linkS4class{DBIDriver}, or an existing \linkS4class{DBIConnection} object (in order to clone an existing connection).} \item{...}{authentication arguments needed by the DBMS instance; these typically include \code{user}, \code{password}, \code{host}, \code{port}, \code{dbname}, etc. For details see the appropriate \code{DBIDriver}.} } \value{ A scalar logical. If \code{FALSE}, the \code{"reason"} attribute indicates a reason for failure. } \description{ Like \code{\link[=dbConnect]{dbConnect()}}, but only checks validity without actually returning a connection object. The default implementation opens a connection and disconnects on success, but individual backends might implement a lighter-weight check. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbCanConnect")} } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} # SQLite only needs a path to the database. (Here, ":memory:" is a special # path that creates an in-memory database.) Other database drivers # will require more details (like user, password, host, port, etc.) dbCanConnect(RSQLite::SQLite(), ":memory:") \dontshow{\}) # examplesIf} } \seealso{ Other DBIDriver generics: \code{\link{DBIDriver-class}}, \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbDriver}()}, \code{\link{dbGetInfo}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListConnections}()} } \concept{DBIDriver generics} DBI/man/Id.Rd0000644000176200001440000000315014602466070012252 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/00-Id.R \docType{class} \name{Id-class} \alias{Id-class} \alias{Id} \title{Refer to a table nested in a hierarchy (e.g. within a schema)} \usage{ Id(...) } \arguments{ \item{...}{Components of the hierarchy, e.g. \code{cluster}, \code{catalog}, \code{schema}, or \code{table}, depending on the database backend. For more on these concepts, see \url{https://stackoverflow.com/questions/7022755/}} } \description{ Objects of class \code{Id} have a single slot \code{name}, which is a character vector. The \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} method converts \code{Id} objects to strings. Support for \code{Id} objects depends on the database backend. They can be used in the following methods as \code{name} or \code{table} argument: \itemize{ \item \code{\link[=dbCreateTable]{dbCreateTable()}} \item \code{\link[=dbAppendTable]{dbAppendTable()}} \item \code{\link[=dbReadTable]{dbReadTable()}} \item \code{\link[=dbWriteTable]{dbWriteTable()}} \item \code{\link[=dbExistsTable]{dbExistsTable()}} \item \code{\link[=dbRemoveTable]{dbRemoveTable()}} } Objects of this class are also returned from \code{\link[=dbListObjects]{dbListObjects()}}. } \examples{ # Identifies a table in a specific schema: Id("dbo", "Customer") # You can name the components if you want, but it's not needed Id(table = "Customer", schema = "dbo") # Create a SQL expression for an identifier: dbQuoteIdentifier(ANSI(), Id("nycflights13", "flights")) # Write a table in a specific schema: \dontrun{ dbWriteTable(con, Id("myschema", "mytable"), data.frame(a = 1)) } } DBI/man/dbGetException.Rd0000644000176200001440000000312314602466070014622 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbGetException.R \name{dbGetException} \alias{dbGetException} \title{Get DBMS exceptions} \usage{ dbGetException(conn, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{...}{Other parameters passed on to methods.} } \value{ a list with elements \code{errorNum} (an integer error number) and \code{errorMsg} (a character string) describing the last error in the connection \code{conn}. } \description{ DEPRECATED. Backends should use R's condition system to signal errors and warnings. } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} \keyword{internal} DBI/man/sqlCreateTable.Rd0000644000176200001440000000455314602466070014621 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/sqlCreateTable.R \name{sqlCreateTable} \alias{sqlCreateTable} \title{Compose query to create a simple table} \usage{ sqlCreateTable(con, table, fields, row.names = NA, temporary = FALSE, ...) } \arguments{ \item{con}{A database connection.} \item{table}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{fields}{Either a character vector or a data frame. A named character vector: Names are column names, values are types. Names are escaped with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Field types are unescaped. A data frame: field types are generated using \code{\link[=dbDataType]{dbDataType()}}.} \item{row.names}{Either \code{TRUE}, \code{FALSE}, \code{NA} or a string. If \code{TRUE}, always translate row names to a column called "row_names". If \code{FALSE}, never translate row names. If \code{NA}, translate rownames only if they're a character vector. A string is equivalent to \code{TRUE}, but allows you to override the default name. For backward compatibility, \code{NULL} is equivalent to \code{FALSE}.} \item{temporary}{If \code{TRUE}, will generate a temporary table.} \item{...}{Other arguments used by individual methods.} } \description{ Exposes an interface to simple \verb{CREATE TABLE} commands. The default method is ANSI SQL 99 compliant. This method is mostly useful for backend implementers. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("sqlCreateTable")} } \details{ The \code{row.names} argument must be passed explicitly in order to avoid a compatibility warning. The default will be changed in a later release. } \examples{ sqlCreateTable(ANSI(), "my-table", c(a = "integer", b = "text")) sqlCreateTable(ANSI(), "my-table", iris) # By default, character row names are converted to a row_names colum sqlCreateTable(ANSI(), "mtcars", mtcars[, 1:5]) sqlCreateTable(ANSI(), "mtcars", mtcars[, 1:5], row.names = FALSE) } DBI/man/sqlInterpolate.Rd0000644000176200001440000000641214350241735014727 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/sqlInterpolate.R \name{sqlInterpolate} \alias{sqlInterpolate} \title{Safely interpolate values into an SQL string} \usage{ sqlInterpolate(conn, sql, ..., .dots = list()) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{sql}{A SQL string containing variables to interpolate. Variables must start with a question mark and can be any valid R identifier, i.e. it must start with a letter or \code{.}, and be followed by a letter, digit, \code{.} or \verb{_}.} \item{..., .dots}{Values (for \code{...}) or a list (for \code{.dots}) to interpolate into a string. Names are required if \code{sql} uses the \code{?name} syntax for placeholders. All values will be first escaped with \code{\link[=dbQuoteLiteral]{dbQuoteLiteral()}} prior to interpolation to protect against SQL injection attacks. Arguments created by \code{\link[=SQL]{SQL()}} or \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} remain unchanged.} } \value{ The \code{sql} query with the values from \code{...} and \code{.dots} safely embedded. } \description{ Accepts a query string with placeholders for values, and returns a string with the values embedded. The function is careful to quote all of its inputs with \code{\link[=dbQuoteLiteral]{dbQuoteLiteral()}} to protect against SQL injection attacks. Placeholders can be specified with one of two syntaxes: \itemize{ \item \verb{?}: each occurrence of a standalone \verb{?} is replaced with a value \item \code{?name1}, \code{?name2}, ...: values are given as named arguments or a named list, the names are used to match the values } Mixing \verb{?} and \code{?name} syntaxes is an error. The number and names of values supplied must correspond to the placeholders used in the query. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("sqlInterpolate")} } \section{Backend authors}{ If you are implementing an SQL backend with non-ANSI quoting rules, you'll need to implement a method for \code{\link[=sqlParseVariables]{sqlParseVariables()}}. Failure to do so does not expose you to SQL injection attacks, but will (rarely) result in errors matching supplied and interpolated variables. } \examples{ sql <- "SELECT * FROM X WHERE name = ?name" sqlInterpolate(ANSI(), sql, name = "Hadley") # This is safe because the single quote has been double escaped sqlInterpolate(ANSI(), sql, name = "H'); DROP TABLE--;") # Using paste0() could lead to dangerous SQL with carefully crafted inputs # (SQL injection) name <- "H'); DROP TABLE--;" paste0("SELECT * FROM X WHERE name = '", name, "'") # Use SQL() or dbQuoteIdentifier() to avoid escaping sql2 <- "SELECT * FROM ?table WHERE name in ?names" sqlInterpolate(ANSI(), sql2, table = dbQuoteIdentifier(ANSI(), "X"), names = SQL("('a', 'b')") ) # Don't use SQL() to escape identifiers to avoid SQL injection sqlInterpolate(ANSI(), sql2, table = SQL("X; DELETE FROM X; SELECT * FROM X"), names = SQL("('a', 'b')") ) # Use dbGetQuery() or dbExecute() to process these queries: if (requireNamespace("RSQLite", quietly = TRUE)) { con <- dbConnect(RSQLite::SQLite()) sql <- "SELECT ?value AS value" query <- sqlInterpolate(con, sql, value = 3) print(dbGetQuery(con, query)) dbDisconnect(con) } } DBI/man/DBIResultArrow-class.Rd0000644000176200001440000000234614602466070015637 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/07-DBIResultArrow.R \docType{class} \name{DBIResultArrow-class} \alias{DBIResultArrow-class} \alias{DBIResultArrowDefault-class} \title{DBIResultArrow class} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} This virtual class describes the result and state of execution of a DBMS statement (any statement, query or non-query) for returning data as an Arrow object. } \section{Implementation notes}{ Individual drivers are free to allow single or multiple active results per connection. The default show method displays a summary of the query using other DBI generics. } \seealso{ Other DBI classes: \code{\link{DBIConnection-class}}, \code{\link{DBIConnector-class}}, \code{\link{DBIDriver-class}}, \code{\link{DBIObject-class}}, \code{\link{DBIResult-class}} Other DBIResultArrow generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsValid}()} } \concept{DBI classes} \concept{DBIResultArrow generics} DBI/man/sqlData.Rd0000644000176200001440000000336014602466070013312 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/sqlData.R \name{sqlData} \alias{sqlData} \title{Convert a data frame into form suitable for upload to an SQL database} \usage{ sqlData(con, value, row.names = NA, ...) } \arguments{ \item{con}{A database connection.} \item{value}{A data frame} \item{row.names}{Either \code{TRUE}, \code{FALSE}, \code{NA} or a string. If \code{TRUE}, always translate row names to a column called "row_names". If \code{FALSE}, never translate row names. If \code{NA}, translate rownames only if they're a character vector. A string is equivalent to \code{TRUE}, but allows you to override the default name. For backward compatibility, \code{NULL} is equivalent to \code{FALSE}.} \item{...}{Other arguments used by individual methods.} } \description{ This is a generic method that coerces R objects into vectors suitable for upload to the database. The output will vary a little from method to method depending on whether the main upload device is through a single SQL string or multiple parameterized queries. This method is mostly useful for backend implementers. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("sqlData")} } \details{ The default method: \itemize{ \item Converts factors to characters \item Quotes all strings with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} \item Converts all columns to strings with \code{\link[=dbQuoteLiteral]{dbQuoteLiteral()}} \item Replaces NA with NULL } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") sqlData(con, head(iris)) sqlData(con, head(mtcars)) dbDisconnect(con) \dontshow{\}) # examplesIf} } DBI/man/dbSendQuery.Rd0000644000176200001440000002214514614477037014160 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/14-dbSendQuery.R \name{dbSendQuery} \alias{dbSendQuery} \title{Execute a query on a given database connection} \usage{ dbSendQuery(conn, statement, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{statement}{a character string containing SQL.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbSendQuery()} returns an S4 object that inherits from \linkS4class{DBIResult}. The result set can be used with \code{\link[=dbFetch]{dbFetch()}} to extract records. Once you have finished using a result, make sure to clear it with \code{\link[=dbClearResult]{dbClearResult()}}. } \description{ The \code{dbSendQuery()} method only submits and synchronously executes the SQL query to the database engine. It does \emph{not} extract any records --- for that you need to use the \code{\link[=dbFetch]{dbFetch()}} method, and then you must call \code{\link[=dbClearResult]{dbClearResult()}} when you finish fetching the records you need. For interactive use, you should almost always prefer \code{\link[=dbGetQuery]{dbGetQuery()}}. Use \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}} or \code{\link[=dbGetQueryArrow]{dbGetQueryArrow()}} instead to retrieve the results as an Arrow object. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbSendQuery")} } \details{ This method is for \code{SELECT} queries only. Some backends may support data manipulation queries through this method for compatibility reasons. However, callers are strongly encouraged to use \code{\link[=dbSendStatement]{dbSendStatement()}} for data manipulation statements. The query is submitted to the database server and the DBMS executes it, possibly generating vast amounts of data. Where these data live is driver-specific: some drivers may choose to leave the output on the server and transfer them piecemeal to R, others may transfer all the data to the client -- but not necessarily to the memory that R manages. See individual drivers' \code{dbSendQuery()} documentation for details. } \section{The data retrieval flow}{ This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}, is implemented by \code{\link[=dbGetQuery]{dbGetQuery()}}, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendQuery]{dbSendQuery()}} to create a result set object of class \linkS4class{DBIResult}. \item Optionally, bind query parameters with \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Optionally, use \code{\link[=dbColumnInfo]{dbColumnInfo()}} to retrieve the structure of the result set without retrieving actual data. \item Use \code{\link[=dbFetch]{dbFetch()}} to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. \item Use \code{\link[=dbHasCompleted]{dbHasCompleted()}} to tell when you're done. This method returns \code{TRUE} if no more rows are available for fetching. \item Repeat the last four steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ An error is raised when issuing a query over a closed or invalid connection, or if the query is not a non-\code{NA} string. An error is also raised if the syntax of the query is invalid and all query parameters are given (by passing the \code{params} argument) or the \code{immediate} argument is set to \code{TRUE}. } \section{Additional arguments}{ The following arguments are not part of the \code{dbSendQuery()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{params} (default: \code{NULL}) \item \code{immediate} (default: \code{NULL}) } They must be provided as named arguments. See the "Specification" sections for details on their usage. } \section{Specification}{ No warnings occur under normal conditions. When done, the DBIResult object must be cleared with a call to \code{\link[=dbClearResult]{dbClearResult()}}. Failure to clear the result set leads to a warning when the connection is closed. If the backend supports only one open result set per connection, issuing a second query invalidates an already open result set and raises a warning. The newly opened result set is valid and must be cleared with \code{dbClearResult()}. The \code{param} argument allows passing query parameters, see \code{\link[=dbBind]{dbBind()}} for details. } \section{Specification for the \code{immediate} argument}{ The \code{immediate} argument supports distinguishing between "direct" and "prepared" APIs offered by many database drivers. Passing \code{immediate = TRUE} leads to immediate execution of the query or statement, via the "direct" API (if supported by the driver). The default \code{NULL} means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct \code{immediate} argument. Examples for possible behaviors: \enumerate{ \item DBI backend defaults to \code{immediate = TRUE} internally \enumerate{ \item A query without parameters is passed: query is executed \item A query with parameters is passed: \enumerate{ \item \code{params} not given: rejected immediately by the database because of a syntax error in the query, the backend tries \code{immediate = FALSE} (and gives a message) \item \code{params} given: query is executed using \code{immediate = FALSE} } } \item DBI backend defaults to \code{immediate = FALSE} internally \enumerate{ \item A query without parameters is passed: \enumerate{ \item simple query: query is executed \item "special" query (such as setting a config options): fails, the backend tries \code{immediate = TRUE} (and gives a message) } \item A query with parameters is passed: \enumerate{ \item \code{params} not given: waiting for parameters via \code{\link[=dbBind]{dbBind()}} \item \code{params} given: query is executed } } } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") dbFetch(rs) dbClearResult(rs) # Pass one set of values with the param argument: rs <- dbSendQuery( con, "SELECT * FROM mtcars WHERE cyl = ?", params = list(4L) ) dbFetch(rs) dbClearResult(rs) # Pass multiple sets of values with dbBind(): rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = ?") dbBind(rs, list(6L)) dbFetch(rs) dbBind(rs, list(8L)) dbFetch(rs) dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ For updates: \code{\link[=dbSendStatement]{dbSendStatement()}} and \code{\link[=dbExecute]{dbExecute()}}. Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} Other data retrieval generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetch}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbSendQueryArrow}()} } \concept{DBIConnection generics} \concept{data retrieval generics} DBI/man/dbCallProc.Rd0000644000176200001440000000125014350241735013721 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbCallProc.R \name{dbCallProc} \alias{dbCallProc} \title{Call an SQL stored procedure} \usage{ dbCallProc(conn, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{...}{Other parameters passed on to methods.} } \description{ \strong{Deprecated since 2014} } \details{ The recommended way of calling a stored procedure is now \enumerate{ \item{\code{\link{dbGetQuery}} if a result set is returned} \item{\code{\link{dbExecute}} for data manipulation and other cases where no result set is returned} } } \keyword{internal} DBI/man/dot-SQL92Keywords.Rd0000644000176200001440000000064114602466070015046 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/deprecated.R \docType{data} \name{.SQL92Keywords} \alias{.SQL92Keywords} \title{Keywords according to the SQL-92 standard} \format{ An object of class \code{character} of length 220. } \usage{ .SQL92Keywords } \description{ A character vector of SQL-92 keywords, uppercase. } \examples{ "SELECT" \%in\% .SQL92Keywords } \keyword{datasets} DBI/man/dbGetInfo.Rd0000644000176200001440000001057514614477037013600 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/04-DBIResult.R, R/dbGetInfo.R \name{dbGetInfo} \alias{dbGetInfo} \title{Get DBMS metadata} \usage{ dbGetInfo(dbObj, ...) } \arguments{ \item{dbObj}{An object inheriting from \linkS4class{DBIObject}, i.e. \linkS4class{DBIDriver}, \linkS4class{DBIConnection}, or a \linkS4class{DBIResult}} \item{...}{Other arguments to methods.} } \value{ For objects of class \linkS4class{DBIDriver}, \code{dbGetInfo()} returns a named list that contains at least the following components: \itemize{ \item \code{driver.version}: the package version of the DBI backend, \item \code{client.version}: the version of the DBMS client library. } For objects of class \linkS4class{DBIConnection}, \code{dbGetInfo()} returns a named list that contains at least the following components: \itemize{ \item \code{db.version}: version of the database server, \item \code{dbname}: database name, \item \code{username}: username to connect to the database, \item \code{host}: hostname of the database server, \item \code{port}: port on the database server. It must not contain a \code{password} component. Components that are not applicable should be set to \code{NA}. } For objects of class \linkS4class{DBIResult}, \code{dbGetInfo()} returns a named list that contains at least the following components: \itemize{ \item \code{statatment}: the statement used with \code{\link[=dbSendQuery]{dbSendQuery()}} or \code{\link[=dbExecute]{dbExecute()}}, as returned by \code{\link[=dbGetStatement]{dbGetStatement()}}, \item \code{row.count}: the number of rows fetched so far (for queries), as returned by \code{\link[=dbGetRowCount]{dbGetRowCount()}}, \item \code{rows.affected}: the number of rows affected (for statements), as returned by \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}} \item \code{has.completed}: a logical that indicates if the query or statement has completed, as returned by \code{\link[=dbHasCompleted]{dbHasCompleted()}}. } } \description{ Retrieves information on objects of class \linkS4class{DBIDriver}, \linkS4class{DBIConnection} or \linkS4class{DBIResult}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbGetInfo")} } \section{Implementation notes}{ The default implementation for \verb{DBIResult objects} constructs such a list from the return values of the corresponding methods, \code{\link[=dbGetStatement]{dbGetStatement()}}, \code{\link[=dbGetRowCount]{dbGetRowCount()}}, \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}}, and \code{\link[=dbHasCompleted]{dbHasCompleted()}}. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} dbGetInfo(RSQLite::SQLite()) \dontshow{\}) # examplesIf} } \seealso{ Other DBIDriver generics: \code{\link{DBIDriver-class}}, \code{\link{dbCanConnect}()}, \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbDriver}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListConnections}()} Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} } \concept{DBIConnection generics} \concept{DBIDriver generics} \concept{DBIResult generics} DBI/man/dbAppendTable.Rd0000644000176200001440000001471214602466070014411 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/11-dbAppendTable.R \name{dbAppendTable} \alias{dbAppendTable} \title{Insert rows into a table} \usage{ dbAppendTable(conn, name, value, ..., row.names = NULL) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{value}{A \link{data.frame} (or coercible to data.frame).} \item{...}{Other parameters passed on to methods.} \item{row.names}{Must be \code{NULL}.} } \value{ \code{dbAppendTable()} returns a scalar numeric. } \description{ The \code{dbAppendTable()} method assumes that the table has been created beforehand, e.g. with \code{\link[=dbCreateTable]{dbCreateTable()}}. The default implementation calls \code{\link[=sqlAppendTableTemplate]{sqlAppendTableTemplate()}} and then \code{\link[=dbExecute]{dbExecute()}} with the \code{param} argument. Use \code{\link[=dbAppendTableArrow]{dbAppendTableArrow()}} to append data from an Arrow stream. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbAppendTable")} } \details{ Backends compliant to ANSI SQL 99 which use \verb{?} as a placeholder for prepared queries don't need to override it. Backends with a different SQL syntax which use \verb{?} as a placeholder for prepared queries can override \code{\link[=sqlAppendTable]{sqlAppendTable()}}. Other backends (with different placeholders or with entirely different ways to create tables) need to override the \code{dbAppendTable()} method. The \code{row.names} argument is not supported by this method. Process the values with \code{\link[=sqlRownamesToColumn]{sqlRownamesToColumn()}} before calling this method. } \section{Failure modes}{ If the table does not exist, or the new data in \code{values} is not a data frame or has different column names, an error is raised; the remote table remains unchanged. An error is raised when calling this method for a closed or invalid connection. An error is also raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. Invalid values for the \code{row.names} argument (non-scalars, unsupported data types, \code{NA}) also raise an error. Passing a \code{value} argument different to \code{NULL} to the \code{row.names} argument (in particular \code{TRUE}, \code{NA}, and a string) raises an error. } \section{Specification}{ SQL keywords can be used freely in table names, column names, and data. Quotes, commas, spaces, and other special characters such as newlines and tabs, can also be used in the data, and, if the database supports non-syntactic identifiers, also for table names and column names. The following data types must be supported at least, and be read identically with \code{\link[=dbReadTable]{dbReadTable()}}: \itemize{ \item integer \item numeric (the behavior for \code{Inf} and \code{NaN} is not specified) \item logical \item \code{NA} as NULL \item 64-bit values (using \code{"bigint"} as field type); the result can be \itemize{ \item converted to a numeric, which may lose precision, \item converted a character vector, which gives the full decimal representation \item written to another table and read again unchanged } \item character (in both UTF-8 and native encodings), supporting empty strings (before and after non-empty strings) \item factor (returned as character, with a warning) \item list of raw (if supported by the database) \item objects of type \link[blob:blob]{blob::blob} (if supported by the database) \item date (if supported by the database; returned as \code{Date}) also for dates prior to 1970 or 1900 or after 2038 \item time (if supported by the database; returned as objects that inherit from \code{difftime}) \item timestamp (if supported by the database; returned as \code{POSIXct} respecting the time zone but not necessarily preserving the input time zone), also for timestamps prior to 1970 or 1900 or after 2038 respecting the time zone but not necessarily preserving the input time zone) } Mixing column types in the same table is supported. The \code{name} argument is processed as follows, to support databases that allow non-syntactic names for their objects: \itemize{ \item If an unquoted table name as string: \code{dbAppendTable()} will do the quoting, perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} \item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done to support databases that allow non-syntactic names for their objects: } The \code{row.names} argument must be \code{NULL}, the default value. Row names are ignored. The \code{value} argument must be a data frame with a subset of the columns of the existing table. The order of the columns does not matter. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbCreateTable(con, "iris", iris) dbAppendTable(con, "iris", iris) dbReadTable(con, "iris") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbCreateTable.Rd0000644000176200001440000001305614602466070014405 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/12-dbCreateTable.R \name{dbCreateTable} \alias{dbCreateTable} \title{Create a table in the database} \usage{ dbCreateTable(conn, name, fields, ..., row.names = NULL, temporary = FALSE) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{fields}{Either a character vector or a data frame. A named character vector: Names are column names, values are types. Names are escaped with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Field types are unescaped. A data frame: field types are generated using \code{\link[=dbDataType]{dbDataType()}}.} \item{...}{Other parameters passed on to methods.} \item{row.names}{Must be \code{NULL}.} \item{temporary}{If \code{TRUE}, will generate a temporary table.} } \value{ \code{dbCreateTable()} returns \code{TRUE}, invisibly. } \description{ The default \code{dbCreateTable()} method calls \code{\link[=sqlCreateTable]{sqlCreateTable()}} and \code{\link[=dbExecute]{dbExecute()}}. Use \code{\link[=dbCreateTableArrow]{dbCreateTableArrow()}} to create a table from an Arrow schema. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbCreateTable")} } \details{ Backends compliant to ANSI SQL 99 don't need to override it. Backends with a different SQL syntax can override \code{sqlCreateTable()}, backends with entirely different ways to create tables need to override this method. The \code{row.names} argument is not supported by this method. Process the values with \code{\link[=sqlRownamesToColumn]{sqlRownamesToColumn()}} before calling this method. The argument order is different from the \code{sqlCreateTable()} method, the latter will be adapted in a later release of DBI. } \section{Failure modes}{ If the table exists, an error is raised; the remote table remains unchanged. An error is raised when calling this method for a closed or invalid connection. An error is also raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. Invalid values for the \code{row.names} and \code{temporary} arguments (non-scalars, unsupported data types, \code{NA}, incompatible values, duplicate names) also raise an error. } \section{Additional arguments}{ The following arguments are not part of the \code{dbCreateTable()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{temporary} (default: \code{FALSE}) } They must be provided as named arguments. See the "Specification" and "Value" sections for details on their usage. } \section{Specification}{ The \code{name} argument is processed as follows, to support databases that allow non-syntactic names for their objects: \itemize{ \item If an unquoted table name as string: \code{dbCreateTable()} will do the quoting, perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} \item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done } The \code{value} argument can be: \itemize{ \item a data frame, \item a named list of SQL types } If the \code{temporary} argument is \code{TRUE}, the table is not available in a second connection and is gone after reconnecting. Not all backends support this argument. A regular, non-temporary table is visible in a second connection, in a pre-existing connection, and after reconnecting to the database. SQL keywords can be used freely in table names, column names, and data. Quotes, commas, and spaces can also be used for table names and column names, if the database supports non-syntactic identifiers. The \code{row.names} argument must be missing or \code{NULL}, the default value. All other values for the \code{row.names} argument (in particular \code{TRUE}, \code{NA}, and a string) raise an error. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbCreateTable(con, "iris", iris) dbReadTable(con, "iris") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/ANSI.Rd0000644000176200001440000000046314602466070012454 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/06-ANSI.R \name{ANSI} \alias{ANSI} \title{A dummy DBI connector that simulates ANSI-SQL compliance} \usage{ ANSI() } \description{ A dummy DBI connector that simulates ANSI-SQL compliance } \examples{ ANSI() } \keyword{internal} DBI/man/dbListResults.Rd0000644000176200001440000000316014602466070014522 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbListResults.R \name{dbListResults} \alias{dbListResults} \title{A list of all pending results} \usage{ dbListResults(conn, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{...}{Other parameters passed on to methods.} } \value{ a list. If no results are active, an empty list. If only a single result is active, a list with one element. } \description{ DEPRECATED. DBI currenty supports only one open result set per connection, you need to keep track of the result sets you open if you need this functionality. } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} \keyword{internal} DBI/man/dbGetQueryArrow.Rd0000644000176200001440000001503214602466070015006 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbGetQueryArrow.R \name{dbGetQueryArrow} \alias{dbGetQueryArrow} \title{Retrieve results from a query as an Arrow object} \usage{ dbGetQueryArrow(conn, statement, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{statement}{a character string containing SQL.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbGetQueryArrow()} always returns an object coercible to a \link{data.frame}, with as many rows as records were fetched and as many columns as fields in the result set, even if the result is a single value or has one or zero rows. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} Returns the result of a query as an Arrow object. \code{dbGetQueryArrow()} comes with a default implementation (which should work with most backends) that calls \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}}, then \code{\link[=dbFetchArrow]{dbFetchArrow()}}, ensuring that the result is always freed by \code{\link[=dbClearResult]{dbClearResult()}}. For passing query parameters, see \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}}, in particular the "The data retrieval flow for Arrow streams" section. For retrieving results as a data frame, see \code{\link[=dbGetQuery]{dbGetQuery()}}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbGetQueryArrow")} } \details{ This method is for \code{SELECT} queries only (incl. other SQL statements that return a \code{SELECT}-alike result, e.g., execution of a stored procedure or data manipulation queries like \verb{INSERT INTO ... RETURNING ...}). To execute a stored procedure that does not return a result set, use \code{\link[=dbExecute]{dbExecute()}}. Some backends may support data manipulation statements through this method. However, callers are strongly advised to use \code{\link[=dbExecute]{dbExecute()}} for data manipulation statements. } \section{Implementation notes}{ Subclasses should override this method only if they provide some sort of performance optimization. } \section{Failure modes}{ An error is raised when issuing a query over a closed or invalid connection, if the syntax of the query is invalid, or if the query is not a non-\code{NA} string. The object returned by \code{dbGetQueryArrow()} can also be passed to \code{\link[nanoarrow:as_nanoarrow_array_stream]{nanoarrow::as_nanoarrow_array_stream()}} to create a nanoarrow array stream object that can be used to read the result set in batches. The chunk size is implementation-specific. } \section{Additional arguments}{ The following arguments are not part of the \code{dbGetQueryArrow()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{params} (default: \code{NULL}) \item \code{immediate} (default: \code{NULL}) } They must be provided as named arguments. See the "Specification" and "Value" sections for details on their usage. The \code{param} argument allows passing query parameters, see \code{\link[=dbBind]{dbBind()}} for details. } \section{Specification for the \code{immediate} argument}{ The \code{immediate} argument supports distinguishing between "direct" and "prepared" APIs offered by many database drivers. Passing \code{immediate = TRUE} leads to immediate execution of the query or statement, via the "direct" API (if supported by the driver). The default \code{NULL} means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct \code{immediate} argument. Examples for possible behaviors: \enumerate{ \item DBI backend defaults to \code{immediate = TRUE} internally \enumerate{ \item A query without parameters is passed: query is executed \item A query with parameters is passed: \enumerate{ \item \code{params} not given: rejected immediately by the database because of a syntax error in the query, the backend tries \code{immediate = FALSE} (and gives a message) \item \code{params} given: query is executed using \code{immediate = FALSE} } } \item DBI backend defaults to \code{immediate = FALSE} internally \enumerate{ \item A query without parameters is passed: \enumerate{ \item simple query: query is executed \item "special" query (such as setting a config options): fails, the backend tries \code{immediate = TRUE} (and gives a message) } \item A query with parameters is passed: \enumerate{ \item \code{params} not given: waiting for parameters via \code{\link[=dbBind]{dbBind()}} \item \code{params} given: query is executed } } } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} # Retrieve data as arrow table con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) dbGetQueryArrow(con, "SELECT * FROM mtcars") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ For updates: \code{\link[=dbSendStatement]{dbSendStatement()}} and \code{\link[=dbExecute]{dbExecute()}}. Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} Other data retrieval generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetch}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbGetQuery}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()} } \concept{DBIConnection generics} \concept{data retrieval generics} DBI/man/dbExecute.Rd0000644000176200001440000001337614602466070013641 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbExecute.R \name{dbExecute} \alias{dbExecute} \title{Change database state} \usage{ dbExecute(conn, statement, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{statement}{a character string containing SQL.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbExecute()} always returns a scalar numeric that specifies the number of rows affected by the statement. } \description{ Executes a statement and returns the number of rows affected. \code{dbExecute()} comes with a default implementation (which should work with most backends) that calls \code{\link[=dbSendStatement]{dbSendStatement()}}, then \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}}, ensuring that the result is always freed by \code{\link[=dbClearResult]{dbClearResult()}}. For passing query parameters, see \code{\link[=dbBind]{dbBind()}}, in particular the "The command execution flow" section. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbExecute")} } \details{ You can also use \code{dbExecute()} to call a stored procedure that performs data manipulation or other actions that do not return a result set. To execute a stored procedure that returns a result set, or a data manipulation query that also returns a result set such as \verb{INSERT INTO ... RETURNING ...}, use \code{\link[=dbGetQuery]{dbGetQuery()}} instead. } \section{Implementation notes}{ Subclasses should override this method only if they provide some sort of performance optimization. } \section{Failure modes}{ An error is raised when issuing a statement over a closed or invalid connection, if the syntax of the statement is invalid, or if the statement is not a non-\code{NA} string. } \section{Additional arguments}{ The following arguments are not part of the \code{dbExecute()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{params} (default: \code{NULL}) \item \code{immediate} (default: \code{NULL}) } They must be provided as named arguments. See the "Specification" sections for details on their usage. } \section{Specification}{ The \code{param} argument allows passing query parameters, see \code{\link[=dbBind]{dbBind()}} for details. } \section{Specification for the \code{immediate} argument}{ The \code{immediate} argument supports distinguishing between "direct" and "prepared" APIs offered by many database drivers. Passing \code{immediate = TRUE} leads to immediate execution of the query or statement, via the "direct" API (if supported by the driver). The default \code{NULL} means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct \code{immediate} argument. Examples for possible behaviors: \enumerate{ \item DBI backend defaults to \code{immediate = TRUE} internally \enumerate{ \item A query without parameters is passed: query is executed \item A query with parameters is passed: \enumerate{ \item \code{params} not given: rejected immediately by the database because of a syntax error in the query, the backend tries \code{immediate = FALSE} (and gives a message) \item \code{params} given: query is executed using \code{immediate = FALSE} } } \item DBI backend defaults to \code{immediate = FALSE} internally \enumerate{ \item A query without parameters is passed: \enumerate{ \item simple query: query is executed \item "special" query (such as setting a config options): fails, the backend tries \code{immediate = TRUE} (and gives a message) } \item A query with parameters is passed: \enumerate{ \item \code{params} not given: waiting for parameters via \code{\link[=dbBind]{dbBind()}} \item \code{params} given: query is executed } } } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cars", head(cars, 3)) dbReadTable(con, "cars") # there are 3 rows dbExecute( con, "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)" ) dbReadTable(con, "cars") # there are now 6 rows # Pass values using the param argument: dbExecute( con, "INSERT INTO cars (speed, dist) VALUES (?, ?)", params = list(4:7, 5:8) ) dbReadTable(con, "cars") # there are now 10 rows dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ For queries: \code{\link[=dbSendQuery]{dbSendQuery()}} and \code{\link[=dbGetQuery]{dbGetQuery()}}. Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} Other command execution generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbSendStatement}()} } \concept{DBIConnection generics} \concept{command execution generics} DBI/man/DBIObject-class.Rd0000644000176200001440000000347714602466070014562 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/01-DBIObject.R \docType{class} \name{DBIObject-class} \alias{DBIObject-class} \title{DBIObject class} \description{ Base class for all other DBI classes (e.g., drivers, connections). This is a virtual Class: No objects may be created from it. } \details{ More generally, the DBI defines a very small set of classes and generics that allows users and applications access DBMS with a common interface. The virtual classes are \code{DBIDriver} that individual drivers extend, \code{DBIConnection} that represent instances of DBMS connections, and \code{DBIResult} that represent the result of a DBMS statement. These three classes extend the basic class of \code{DBIObject}, which serves as the root or parent of the class hierarchy. } \section{Implementation notes}{ An implementation MUST provide methods for the following generics: \itemize{ \item \code{\link[=dbGetInfo]{dbGetInfo()}}. } It MAY also provide methods for: \itemize{ \item \code{\link[=summary]{summary()}}. Print a concise description of the object. The default method invokes \code{dbGetInfo(dbObj)} and prints the name-value pairs one per line. Individual implementations may tailor this appropriately. } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} drv <- RSQLite::SQLite() con <- dbConnect(drv) rs <- dbSendQuery(con, "SELECT 1") is(drv, "DBIObject") ## True is(con, "DBIObject") ## True is(rs, "DBIObject") dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBI classes: \code{\link{DBIConnection-class}}, \code{\link{DBIConnector-class}}, \code{\link{DBIDriver-class}}, \code{\link{DBIResult-class}}, \code{\link{DBIResultArrow-class}} } \concept{DBI classes} DBI/man/dbIsValid.Rd0000644000176200001440000000772714602466070013575 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbIsValid.R \name{dbIsValid} \alias{dbIsValid} \title{Is this DBMS object still valid?} \usage{ dbIsValid(dbObj, ...) } \arguments{ \item{dbObj}{An object inheriting from \linkS4class{DBIObject}, i.e. \linkS4class{DBIDriver}, \linkS4class{DBIConnection}, or a \linkS4class{DBIResult}} \item{...}{Other arguments to methods.} } \value{ \code{dbIsValid()} returns a logical scalar, \code{TRUE} if the object specified by \code{dbObj} is valid, \code{FALSE} otherwise. A \linkS4class{DBIConnection} object is initially valid, and becomes invalid after disconnecting with \code{\link[=dbDisconnect]{dbDisconnect()}}. For an invalid connection object (e.g., for some drivers if the object is saved to a file and then restored), the method also returns \code{FALSE}. A \linkS4class{DBIResult} object is valid after a call to \code{\link[=dbSendQuery]{dbSendQuery()}}, and stays valid even after all rows have been fetched; only clearing it with \code{\link[=dbClearResult]{dbClearResult()}} invalidates it. A \linkS4class{DBIResult} object is also valid after a call to \code{\link[=dbSendStatement]{dbSendStatement()}}, and stays valid after querying the number of rows affected; only clearing it with \code{\link[=dbClearResult]{dbClearResult()}} invalidates it. If the connection to the database system is dropped (e.g., due to connectivity problems, server failure, etc.), \code{dbIsValid()} should return \code{FALSE}. This is not tested automatically. } \description{ This generic tests whether a database object is still valid (i.e. it hasn't been disconnected or cleared). \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbIsValid")} } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} dbIsValid(RSQLite::SQLite()) con <- dbConnect(RSQLite::SQLite(), ":memory:") dbIsValid(con) rs <- dbSendQuery(con, "SELECT 1") dbIsValid(rs) dbClearResult(rs) dbIsValid(rs) dbDisconnect(con) dbIsValid(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIDriver generics: \code{\link{DBIDriver-class}}, \code{\link{dbCanConnect}()}, \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbDriver}()}, \code{\link{dbGetInfo}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbListConnections}()} Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} Other DBIResultArrow generics: \code{\link{DBIResultArrow-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbHasCompleted}()} } \concept{DBIConnection generics} \concept{DBIDriver generics} \concept{DBIResult generics} \concept{DBIResultArrow generics} DBI/man/dbGetRowCount.Rd0000644000176200001440000000442214602466070014447 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbGetRowCount.R \name{dbGetRowCount} \alias{dbGetRowCount} \title{The number of rows fetched so far} \usage{ dbGetRowCount(res, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResult}.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbGetRowCount()} returns a scalar number (integer or numeric), the number of rows fetched so far. After calling \code{\link[=dbSendQuery]{dbSendQuery()}}, the row count is initially zero. After a call to \code{\link[=dbFetch]{dbFetch()}} without limit, the row count matches the total number of rows returned. Fetching a limited number of rows increases the number of rows by the number of rows returned, even if fetching past the end of the result set. For queries with an empty result set, zero is returned even after fetching. For data manipulation statements issued with \code{\link[=dbSendStatement]{dbSendStatement()}}, zero is returned before and after calling \code{dbFetch()}. } \description{ Returns the total number of rows actually fetched with calls to \code{\link[=dbFetch]{dbFetch()}} for this result set. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbGetRowCount")} } \section{Failure modes}{ Attempting to get the row count for a result set cleared with \code{\link[=dbClearResult]{dbClearResult()}} gives an error. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendQuery(con, "SELECT * FROM mtcars") dbGetRowCount(rs) ret1 <- dbFetch(rs, 10) dbGetRowCount(rs) ret2 <- dbFetch(rs) dbGetRowCount(rs) nrow(ret1) + nrow(ret2) dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} } \concept{DBIResult generics} DBI/man/dbReadTable.Rd0000644000176200001440000001214414602466070014052 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbReadTable.R \name{dbReadTable} \alias{dbReadTable} \title{Read database tables as data frames} \usage{ dbReadTable(conn, name, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbReadTable()} returns a data frame that contains the complete data from the remote table, effectively the result of calling \code{\link[=dbGetQuery]{dbGetQuery()}} with \verb{SELECT * FROM }. An empty table is returned as a data frame with zero rows. The presence of \link{rownames} depends on the \code{row.names} argument, see \code{\link[=sqlColumnToRownames]{sqlColumnToRownames()}} for details: \itemize{ \item If \code{FALSE} or \code{NULL}, the returned data frame doesn't have row names. \item If \code{TRUE}, a column named "row_names" is converted to row names. } \itemize{ \item If \code{NA}, a column named "row_names" is converted to row names if it exists, otherwise no translation occurs. \item If a string, this specifies the name of the column in the remote table that contains the row names. } The default is \code{row.names = FALSE}. If the database supports identifiers with special characters, the columns in the returned data frame are converted to valid R identifiers if the \code{check.names} argument is \code{TRUE}, If \code{check.names = FALSE}, the returned table has non-syntactic column names without quotes. } \description{ Reads a database table to a data frame, optionally converting a column to row names and converting the column names to valid R identifiers. Use \code{\link[=dbReadTableArrow]{dbReadTableArrow()}} instead to obtain an Arrow object. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbReadTable")} } \details{ This function returns a data frame. Use \code{\link[=dbReadTableArrow]{dbReadTableArrow()}} to obtain an Arrow object. } \section{Failure modes}{ An error is raised if the table does not exist. An error is raised if \code{row.names} is \code{TRUE} and no "row_names" column exists, An error is raised if \code{row.names} is set to a string and no corresponding column exists. An error is raised when calling this method for a closed or invalid connection. An error is raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. Unsupported values for \code{row.names} and \code{check.names} (non-scalars, unsupported data types, \code{NA} for \code{check.names}) also raise an error. } \section{Additional arguments}{ The following arguments are not part of the \code{dbReadTable()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{row.names} (default: \code{FALSE}) \item \code{check.names} } They must be provided as named arguments. See the "Value" section for details on their usage. } \section{Specification}{ The \code{name} argument is processed as follows, to support databases that allow non-syntactic names for their objects: \itemize{ \item If an unquoted table name as string: \code{dbReadTable()} will do the quoting, perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} \item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars[1:10, ]) dbReadTable(con, "mtcars") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbQuoteIdentifier.Rd0000644000176200001440000000752514602466070015336 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbQuoteIdentifier.R \name{dbQuoteIdentifier} \alias{dbQuoteIdentifier} \title{Quote identifiers} \usage{ dbQuoteIdentifier(conn, x, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{x}{A character vector, \link{SQL} or \link{Id} object to quote as identifier.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbQuoteIdentifier()} returns an object that can be coerced to \link{character}, of the same length as the input. For an empty character vector this function returns a length-0 object. The names of the input argument are preserved in the output. When passing the returned object again to \code{dbQuoteIdentifier()} as \code{x} argument, it is returned unchanged. Passing objects of class \link{SQL} should also return them unchanged. (For backends it may be most convenient to return \link{SQL} objects to achieve this behavior, but this is not required.) } \description{ Call this method to generate a string that is suitable for use in a query as a column or table name, to make sure that you generate valid SQL and protect against SQL injection attacks. The inverse operation is \code{\link[=dbUnquoteIdentifier]{dbUnquoteIdentifier()}}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbQuoteIdentifier")} } \section{Failure modes}{ An error is raised if the input contains \code{NA}, but not for an empty string. } \section{Specification}{ Calling \code{\link[=dbGetQuery]{dbGetQuery()}} for a query of the format \verb{SELECT 1 AS ...} returns a data frame with the identifier, unquoted, as column name. Quoted identifiers can be used as table and column names in SQL queries, in particular in queries like \verb{SELECT 1 AS ...} and \verb{SELECT * FROM (SELECT 1) ...}. The method must use a quoting mechanism that is unambiguously different from the quoting mechanism used for strings, so that a query like \verb{SELECT ... FROM (SELECT 1 AS ...)} throws an error if the column names do not match. The method can quote column names that contain special characters such as a space, a dot, a comma, or quotes used to mark strings or identifiers, if the database supports this. In any case, checking the validity of the identifier should be performed only when executing a query, and not by \code{dbQuoteIdentifier()}. } \examples{ # Quoting ensures that arbitrary input is safe for use in a query name <- "Robert'); DROP TABLE Students;--" dbQuoteIdentifier(ANSI(), name) # Use Id() to specify other components such as the schema id_name <- Id(schema = "schema_name", table = "table_name") id_name dbQuoteIdentifier(ANSI(), id_name) # SQL vectors are always passed through as is var_name <- SQL("select") var_name dbQuoteIdentifier(ANSI(), var_name) # This mechanism is used to prevent double escaping dbQuoteIdentifier(ANSI(), dbQuoteIdentifier(ANSI(), name)) } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbSendQueryArrow.Rd0000644000176200001440000002013414602466070015157 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/24-dbSendQueryArrow.R \name{dbSendQueryArrow} \alias{dbSendQueryArrow} \title{Execute a query on a given database connection for retrieval via Arrow} \usage{ dbSendQueryArrow(conn, statement, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{statement}{a character string containing SQL.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbSendQueryArrow()} returns an S4 object that inherits from \linkS4class{DBIResultArrow}. The result set can be used with \code{\link[=dbFetchArrow]{dbFetchArrow()}} to extract records. Once you have finished using a result, make sure to clear it with \code{\link[=dbClearResult]{dbClearResult()}}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} The \code{dbSendQueryArrow()} method only submits and synchronously executes the SQL query to the database engine. It does \emph{not} extract any records --- for that you need to use the \code{\link[=dbFetchArrow]{dbFetchArrow()}} method, and then you must call \code{\link[=dbClearResult]{dbClearResult()}} when you finish fetching the records you need. For interactive use, you should almost always prefer \code{\link[=dbGetQueryArrow]{dbGetQueryArrow()}}. Use \code{\link[=dbSendQuery]{dbSendQuery()}} or \code{\link[=dbGetQuery]{dbGetQuery()}} instead to retrieve the results as a data frame. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbSendQueryArrow")} } \details{ This method is for \code{SELECT} queries only. Some backends may support data manipulation queries through this method for compatibility reasons. However, callers are strongly encouraged to use \code{\link[=dbSendStatement]{dbSendStatement()}} for data manipulation statements. } \section{The data retrieval flow for Arrow streams}{ This section gives a complete overview over the flow for the execution of queries that return tabular data as an Arrow stream. Most of this flow, except repeated calling of \code{\link[=dbBindArrow]{dbBindArrow()}} or \code{\link[=dbBind]{dbBind()}}, is implemented by \code{\link[=dbGetQueryArrow]{dbGetQueryArrow()}}, which should be sufficient unless you have a parameterized query that you want to reuse. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}} to create a result set object of class \linkS4class{DBIResultArrow}. \item Optionally, bind query parameters with \code{\link[=dbBindArrow]{dbBindArrow()}} or \code{\link[=dbBind]{dbBind()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Use \code{\link[=dbFetchArrow]{dbFetchArrow()}} to get a data stream. \item Repeat the last two steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ An error is raised when issuing a query over a closed or invalid connection, or if the query is not a non-\code{NA} string. An error is also raised if the syntax of the query is invalid and all query parameters are given (by passing the \code{params} argument) or the \code{immediate} argument is set to \code{TRUE}. } \section{Additional arguments}{ The following arguments are not part of the \code{dbSendQueryArrow()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{params} (default: \code{NULL}) \item \code{immediate} (default: \code{NULL}) } They must be provided as named arguments. See the "Specification" sections for details on their usage. } \section{Specification}{ No warnings occur under normal conditions. When done, the DBIResult object must be cleared with a call to \code{\link[=dbClearResult]{dbClearResult()}}. Failure to clear the result set leads to a warning when the connection is closed. If the backend supports only one open result set per connection, issuing a second query invalidates an already open result set and raises a warning. The newly opened result set is valid and must be cleared with \code{dbClearResult()}. The \code{param} argument allows passing query parameters, see \code{\link[=dbBind]{dbBind()}} for details. } \section{Specification for the \code{immediate} argument}{ The \code{immediate} argument supports distinguishing between "direct" and "prepared" APIs offered by many database drivers. Passing \code{immediate = TRUE} leads to immediate execution of the query or statement, via the "direct" API (if supported by the driver). The default \code{NULL} means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct \code{immediate} argument. Examples for possible behaviors: \enumerate{ \item DBI backend defaults to \code{immediate = TRUE} internally \enumerate{ \item A query without parameters is passed: query is executed \item A query with parameters is passed: \enumerate{ \item \code{params} not given: rejected immediately by the database because of a syntax error in the query, the backend tries \code{immediate = FALSE} (and gives a message) \item \code{params} given: query is executed using \code{immediate = FALSE} } } \item DBI backend defaults to \code{immediate = FALSE} internally \enumerate{ \item A query without parameters is passed: \enumerate{ \item simple query: query is executed \item "special" query (such as setting a config options): fails, the backend tries \code{immediate = TRUE} (and gives a message) } \item A query with parameters is passed: \enumerate{ \item \code{params} not given: waiting for parameters via \code{\link[=dbBind]{dbBind()}} \item \code{params} given: query is executed } } } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} # Retrieve data as arrow table con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendQueryArrow(con, "SELECT * FROM mtcars WHERE cyl = 4") dbFetchArrow(rs) dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ For updates: \code{\link[=dbSendStatement]{dbSendStatement()}} and \code{\link[=dbExecute]{dbExecute()}}. Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} Other data retrieval generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetch}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbSendQuery}()} } \concept{DBIConnection generics} \concept{data retrieval generics} DBI/man/dbGetStatement.Rd0000644000176200001440000000327614602466070014641 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbGetStatement.R \name{dbGetStatement} \alias{dbGetStatement} \title{Get the statement associated with a result set} \usage{ dbGetStatement(res, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResult}.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbGetStatement()} returns a string, the query used in either \code{\link[=dbSendQuery]{dbSendQuery()}} or \code{\link[=dbSendStatement]{dbSendStatement()}}. } \description{ Returns the statement that was passed to \code{\link[=dbSendQuery]{dbSendQuery()}} or \code{\link[=dbSendStatement]{dbSendStatement()}}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbGetStatement")} } \section{Failure modes}{ Attempting to query the statement for a result set cleared with \code{\link[=dbClearResult]{dbClearResult()}} gives an error. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendQuery(con, "SELECT * FROM mtcars") dbGetStatement(rs) dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} } \concept{DBIResult generics} DBI/man/dbSetDataMappings.Rd0000644000176200001440000000165114350241735015253 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbSetDataMappings.R \name{dbSetDataMappings} \alias{dbSetDataMappings} \title{Set data mappings between an DBMS and R.} \usage{ dbSetDataMappings(res, flds, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResult}.} \item{flds}{a field description object as returned by \code{dbColumnInfo}.} \item{...}{Other arguments passed on to methods.} } \description{ This generic is deprecated since no working implementation was ever produced. } \details{ Sets one or more conversion functions to handle the translation of DBMS data types to R objects. This is only needed for non-primitive data, since all DBI drivers handle the common base types (integers, numeric, strings, etc.) The details on conversion functions (e.g., arguments, whether they can invoke initializers and/or destructors) have not been specified. } \keyword{internal} DBI/man/dbColumnInfo.Rd0000644000176200001440000001067414614477037014316 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbColumnInfo.R \name{dbColumnInfo} \alias{dbColumnInfo} \title{Information about result types} \usage{ dbColumnInfo(res, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResult}.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbColumnInfo()} returns a data frame with at least two columns \code{"name"} and \code{"type"} (in that order) (and optional columns that start with a dot). The \code{"name"} and \code{"type"} columns contain the names and types of the R columns of the data frame that is returned from \code{\link[=dbFetch]{dbFetch()}}. The \code{"type"} column is of type \code{character} and only for information. Do not compute on the \code{"type"} column, instead use \code{dbFetch(res, n = 0)} to create a zero-row data frame initialized with the correct data types. } \description{ Produces a data.frame that describes the output of a query. The data.frame should have as many rows as there are output fields in the result set, and each column in the data.frame describes an aspect of the result set field (field name, type, etc.) \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbColumnInfo")} } \section{The data retrieval flow}{ This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}, is implemented by \code{\link[=dbGetQuery]{dbGetQuery()}}, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendQuery]{dbSendQuery()}} to create a result set object of class \linkS4class{DBIResult}. \item Optionally, bind query parameters with \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Optionally, use \code{\link[=dbColumnInfo]{dbColumnInfo()}} to retrieve the structure of the result set without retrieving actual data. \item Use \code{\link[=dbFetch]{dbFetch()}} to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. \item Use \code{\link[=dbHasCompleted]{dbHasCompleted()}} to tell when you're done. This method returns \code{TRUE} if no more rows are available for fetching. \item Repeat the last four steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ An attempt to query columns for a closed result set raises an error. } \section{Specification}{ A column named \code{row_names} is treated like any other column. The column names are always consistent with the data returned by \code{dbFetch()}. If the query returns unnamed columns, non-empty and non-\code{NA} names are assigned. Column names that correspond to SQL or R keywords are left unchanged. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") rs <- dbSendQuery(con, "SELECT 1 AS a, 2 AS b") dbColumnInfo(rs) dbFetch(rs) dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} } \concept{DBIResult generics} DBI/man/dbListTables.Rd0000644000176200001440000000467614602466070014310 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbListTables.R \name{dbListTables} \alias{dbListTables} \title{List remote tables} \usage{ dbListTables(conn, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbListTables()} returns a character vector that enumerates all tables and views in the database. Tables added with \code{\link[=dbWriteTable]{dbWriteTable()}} are part of the list. As soon a table is removed from the database, it is also removed from the list of database tables. The same applies to temporary tables if supported by the database. The returned names are suitable for quoting with \code{dbQuoteIdentifier()}. } \description{ Returns the unquoted names of remote tables accessible through this connection. This should include views and temporary objects, but not all database backends (in particular \pkg{RMariaDB} and \pkg{RMySQL}) support this. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbListTables")} } \section{Failure modes}{ An error is raised when calling this method for a closed or invalid connection. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbListTables(con) dbWriteTable(con, "mtcars", mtcars) dbListTables(con) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/sqlParseVariables.Rd0000644000176200001440000000315414350241735015344 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/interpolate.R, R/sqlParseVariables.R \name{sqlCommentSpec} \alias{sqlCommentSpec} \alias{sqlQuoteSpec} \alias{sqlParseVariablesImpl} \alias{sqlParseVariables} \title{Parse interpolated variables from SQL.} \usage{ sqlCommentSpec(start, end, endRequired) sqlQuoteSpec(start, end, escape = "", doubleEscape = TRUE) sqlParseVariablesImpl(sql, quotes, comments) sqlParseVariables(conn, sql, ...) } \arguments{ \item{start, end}{Start and end characters for quotes and comments} \item{endRequired}{Is the ending character of a comment required?} \item{escape}{What character can be used to escape quoting characters? Defaults to \code{""}, i.e. nothing.} \item{doubleEscape}{Can quoting characters be escaped by doubling them? Defaults to \code{TRUE}.} \item{sql}{SQL to parse (a character string)} \item{quotes}{A list of \code{QuoteSpec} calls defining the quoting specification.} \item{comments}{A list of \code{CommentSpec} calls defining the commenting specification.} } \description{ If you're implementing a backend that uses non-ANSI quoting or commenting rules, you'll need to implement a method for \code{sqlParseVariables} that calls \code{sqlParseVariablesImpl} with the appropriate quote and comment specifications. } \examples{ # Use [] for quoting and no comments sqlParseVariablesImpl("[?a]", list(sqlQuoteSpec("[", "]", "\\\\", FALSE)), list() ) # Standard quotes, use # for commenting sqlParseVariablesImpl("# ?a\n?b", list(sqlQuoteSpec("'", "'"), sqlQuoteSpec('"', '"')), list(sqlCommentSpec("#", "\n", FALSE)) ) } \keyword{internal} DBI/man/dbDriver.Rd0000644000176200001440000000471314602466070013465 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbDriver.R, R/dbUnloadDriver.R \name{dbDriver} \alias{dbDriver} \alias{dbUnloadDriver} \title{Load and unload database drivers} \usage{ dbDriver(drvName, ...) dbUnloadDriver(drv, ...) } \arguments{ \item{drvName}{character name of the driver to instantiate.} \item{...}{any other arguments are passed to the driver \code{drvName}.} \item{drv}{an object that inherits from \code{DBIDriver} as created by \code{dbDriver}.} } \value{ In the case of \code{dbDriver}, an driver object whose class extends \code{DBIDriver}. This object may be used to create connections to the actual DBMS engine. In the case of \code{dbUnloadDriver}, a logical indicating whether the operation succeeded or not. } \description{ These methods are deprecated, please consult the documentation of the individual backends for the construction of driver instances. \code{dbDriver()} is a helper method used to create an new driver object given the name of a database or the corresponding R package. It works through convention: all DBI-extending packages should provide an exported object with the same name as the package. \code{dbDriver()} just looks for this object in the right places: if you know what database you are connecting to, you should call the function directly. \code{dbUnloadDriver()} is not implemented for modern backends. } \details{ The client part of the database communication is initialized (typically dynamically loading C code, etc.) but note that connecting to the database engine itself needs to be done through calls to \code{dbConnect}. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} # Create a RSQLite driver with a string d <- dbDriver("SQLite") d # But better, access the object directly RSQLite::SQLite() \dontshow{\}) # examplesIf} } \seealso{ Other DBIDriver generics: \code{\link{DBIDriver-class}}, \code{\link{dbCanConnect}()}, \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbGetInfo}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListConnections}()} Other DBIDriver generics: \code{\link{DBIDriver-class}}, \code{\link{dbCanConnect}()}, \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbGetInfo}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListConnections}()} } \concept{DBIDriver generics} \keyword{internal} DBI/man/dbDisconnect.Rd0000644000176200001440000000413414614477037014330 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbDisconnect.R \name{dbDisconnect} \alias{dbDisconnect} \title{Disconnect (close) a connection} \usage{ dbDisconnect(conn, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbDisconnect()} returns \code{TRUE}, invisibly. } \description{ This closes the connection, discards all pending work, and frees resources (e.g., memory, sockets). \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbDisconnect")} } \section{Failure modes}{ A warning is issued on garbage collection when a connection has been released without calling \code{dbDisconnect()}, but this cannot be tested automatically. At least one warning is issued immediately when calling \code{dbDisconnect()} on an already disconnected or invalid connection. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbClearResult.Rd0000644000176200001440000001453714614477037014474 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbClearResult.R \name{dbClearResult} \alias{dbClearResult} \title{Clear a result set} \usage{ dbClearResult(res, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResult}.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbClearResult()} returns \code{TRUE}, invisibly, for result sets obtained from \code{dbSendQuery()}, \code{dbSendStatement()}, or \code{dbSendQueryArrow()}, } \description{ Frees all resources (local and remote) associated with a result set. This step is mandatory for all objects obtained by calling \code{\link[=dbSendQuery]{dbSendQuery()}} or \code{\link[=dbSendStatement]{dbSendStatement()}}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbClearResult")} } \section{The data retrieval flow}{ This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}, is implemented by \code{\link[=dbGetQuery]{dbGetQuery()}}, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendQuery]{dbSendQuery()}} to create a result set object of class \linkS4class{DBIResult}. \item Optionally, bind query parameters with \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Optionally, use \code{\link[=dbColumnInfo]{dbColumnInfo()}} to retrieve the structure of the result set without retrieving actual data. \item Use \code{\link[=dbFetch]{dbFetch()}} to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. \item Use \code{\link[=dbHasCompleted]{dbHasCompleted()}} to tell when you're done. This method returns \code{TRUE} if no more rows are available for fetching. \item Repeat the last four steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{The command execution flow}{ This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of \code{\link[=dbBindArrow]{dbBindArrow()}}, is implemented by \code{\link[=dbExecute]{dbExecute()}}, which should be sufficient for non-parameterized queries. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendStatement]{dbSendStatement()}} to create a result set object of class \linkS4class{DBIResult}. For some queries you need to pass \code{immediate = TRUE}. \item Optionally, bind query parameters with\code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Optionally, use \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}} to retrieve the number of rows affected by the query. \item Repeat the last two steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ An attempt to close an already closed result set issues a warning for \code{dbSendQuery()}, \code{dbSendStatement()}, and \code{dbSendQueryArrow()}, } \section{Specification}{ \code{dbClearResult()} frees all resources associated with retrieving the result of a query or update operation. The DBI backend can expect a call to \code{dbClearResult()} for each \code{\link[=dbSendQuery]{dbSendQuery()}} or \code{\link[=dbSendStatement]{dbSendStatement()}} call. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") rs <- dbSendQuery(con, "SELECT 1") print(dbFetch(rs)) dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} Other DBIResultArrow generics: \code{\link{DBIResultArrow-class}}, \code{\link{dbBind}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsValid}()} Other data retrieval generics: \code{\link{dbBind}()}, \code{\link{dbFetch}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()} Other command execution generics: \code{\link{dbBind}()}, \code{\link{dbExecute}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbSendStatement}()} } \concept{DBIResult generics} \concept{DBIResultArrow generics} \concept{command execution generics} \concept{data retrieval generics} DBI/man/dbReadTableArrow.Rd0000644000176200001440000000745214602466070015073 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbReadTableArrow.R \name{dbReadTableArrow} \alias{dbReadTableArrow} \title{Read database tables as Arrow objects} \usage{ dbReadTableArrow(conn, name, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbReadTableArrow()} returns an Arrow object that contains the complete data from the remote table, effectively the result of calling \code{\link[=dbGetQueryArrow]{dbGetQueryArrow()}} with \verb{SELECT * FROM }. An empty table is returned as an Arrow object with zero rows. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} Reads a database table as an Arrow object. Use \code{\link[=dbReadTable]{dbReadTable()}} instead to obtain a data frame. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbReadTableArrow")} } \details{ This function returns an Arrow object. Convert it to a data frame with \code{\link[=as.data.frame]{as.data.frame()}} or use \code{\link[=dbReadTable]{dbReadTable()}} to obtain a data frame. } \section{Failure modes}{ An error is raised if the table does not exist. An error is raised when calling this method for a closed or invalid connection. An error is raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. } \section{Specification}{ The \code{name} argument is processed as follows, to support databases that allow non-syntactic names for their objects: \itemize{ \item If an unquoted table name as string: \code{dbReadTableArrow()} will do the quoting, perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} \item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} # Read data as Arrow table con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars[1:10, ]) dbReadTableArrow(con, "mtcars") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/DBI-package.Rd0000644000176200001440000000506214602466070013711 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/DBI-package.R \docType{package} \name{DBI-package} \alias{DBI} \alias{DBI-package} \title{DBI: R Database Interface} \description{ DBI defines an interface for communication between R and relational database management systems. All classes in this package are virtual and need to be extended by the various R/DBMS implementations (so-called \emph{DBI backends}). } \section{Definition}{ A DBI backend is an R package which imports the \pkg{DBI} and \pkg{methods} packages. For better or worse, the names of many existing backends start with \sQuote{R}, e.g., \pkg{RSQLite}, \pkg{RMySQL}, \pkg{RSQLServer}; it is up to the backend author to adopt this convention or not. } \section{DBI classes and methods}{ A backend defines three classes, which are subclasses of \linkS4class{DBIDriver}, \linkS4class{DBIConnection}, and \linkS4class{DBIResult}. The backend provides implementation for all methods of these base classes that are defined but not implemented by DBI. All methods defined in \pkg{DBI} are reexported (so that the package can be used without having to attach \pkg{DBI}), and have an ellipsis \code{...} in their formals for extensibility. } \section{Construction of the DBIDriver object}{ The backend must support creation of an instance of its \linkS4class{DBIDriver} subclass with a \dfn{constructor function}. By default, its name is the package name without the leading \sQuote{R} (if it exists), e.g., \code{SQLite} for the \pkg{RSQLite} package. However, backend authors may choose a different name. The constructor must be exported, and it must be a function that is callable without arguments. DBI recommends to define a constructor with an empty argument list. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} RSQLite::SQLite() \dontshow{\}) # examplesIf} } \seealso{ Important generics: \code{\link[=dbConnect]{dbConnect()}}, \code{\link[=dbGetQuery]{dbGetQuery()}}, \code{\link[=dbReadTable]{dbReadTable()}}, \code{\link[=dbWriteTable]{dbWriteTable()}}, \code{\link[=dbDisconnect]{dbDisconnect()}} Formal specification (currently work in progress and incomplete): \code{vignette("spec", package = "DBI")} } \author{ \strong{Maintainer}: Kirill Müller \email{kirill@cynkra.com} (\href{https://orcid.org/0000-0002-1416-3412}{ORCID}) Authors: \itemize{ \item R Special Interest Group on Databases (R-SIG-DB) \item Hadley Wickham } Other contributors: \itemize{ \item R Consortium [funder] } } DBI/man/dbWithTransaction.Rd0000644000176200001440000000664014627140170015351 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbWithTransaction.R, % R/dbWithTransaction_DBIConnection.R \name{dbWithTransaction} \alias{dbWithTransaction} \alias{dbBreak} \title{Self-contained SQL transactions} \usage{ dbWithTransaction(conn, code, ...) dbBreak() } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{code}{An arbitrary block of R code.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbWithTransaction()} returns the value of the executed code. } \description{ Given that \link{transactions} are implemented, this function allows you to pass in code that is run in a transaction. The default method of \code{dbWithTransaction()} calls \code{\link[=dbBegin]{dbBegin()}} before executing the code, and \code{\link[=dbCommit]{dbCommit()}} after successful completion, or \code{\link[=dbRollback]{dbRollback()}} in case of an error. The advantage is that you don't have to remember to do \code{dbBegin()} and \code{dbCommit()} or \code{dbRollback()} -- that is all taken care of. The special function \code{dbBreak()} allows an early exit with rollback, it can be called only inside \code{dbWithTransaction()}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbWithTransaction")} } \details{ DBI implements \code{dbWithTransaction()}, backends should need to override this generic only if they implement specialized handling. } \section{Failure modes}{ Failure to initiate the transaction (e.g., if the connection is closed or invalid of if \code{\link[=dbBegin]{dbBegin()}} has been called already) gives an error. } \section{Specification}{ \code{dbWithTransaction()} initiates a transaction with \code{dbBegin()}, executes the code given in the \code{code} argument, and commits the transaction with \code{\link[=dbCommit]{dbCommit()}}. If the code raises an error, the transaction is instead aborted with \code{\link[=dbRollback]{dbRollback()}}, and the error is propagated. If the code calls \code{dbBreak()}, execution of the code stops and the transaction is silently aborted. All side effects caused by the code (such as the creation of new variables) propagate to the calling environment. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cash", data.frame(amount = 100)) dbWriteTable(con, "account", data.frame(amount = 2000)) # All operations are carried out as logical unit: dbWithTransaction( con, { withdrawal <- 300 dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) } ) # The code is executed as if in the current environment: withdrawal # The changes are committed to the database after successful execution: dbReadTable(con, "cash") dbReadTable(con, "account") # Rolling back with dbBreak(): dbWithTransaction( con, { withdrawal <- 5000 dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) if (dbReadTable(con, "account")$amount < 0) { dbBreak() } } ) # These changes were not committed to the database: dbReadTable(con, "cash") dbReadTable(con, "account") dbDisconnect(con) \dontshow{\}) # examplesIf} } DBI/man/dbConnect.Rd0000644000176200001440000000751714602466070013630 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbConnect.R \name{dbConnect} \alias{dbConnect} \title{Create a connection to a DBMS} \usage{ dbConnect(drv, ...) } \arguments{ \item{drv}{an object that inherits from \linkS4class{DBIDriver}, or an existing \linkS4class{DBIConnection} object (in order to clone an existing connection).} \item{...}{authentication arguments needed by the DBMS instance; these typically include \code{user}, \code{password}, \code{host}, \code{port}, \code{dbname}, etc. For details see the appropriate \code{DBIDriver}.} } \value{ \code{dbConnect()} returns an S4 object that inherits from \linkS4class{DBIConnection}. This object is used to communicate with the database engine. A \code{\link[=format]{format()}} method is defined for the connection object. It returns a string that consists of a single line of text. } \description{ Connect to a DBMS going through the appropriate authentication procedure. Some implementations may allow you to have multiple connections open, so you may invoke this function repeatedly assigning its output to different objects. The authentication mechanism is left unspecified, so check the documentation of individual drivers for details. Use \code{\link[=dbCanConnect]{dbCanConnect()}} to check if a connection can be established. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbConnect")} } \section{Specification}{ DBI recommends using the following argument names for authentication parameters, with \code{NULL} default: \itemize{ \item \code{user} for the user name (default: current user) \item \code{password} for the password \item \code{host} for the host name (default: local connection) \item \code{port} for the port number (default: local connection) \item \code{dbname} for the name of the database on the host, or the database file name } The defaults should provide reasonable behavior, in particular a local connection for \code{host = NULL}. For some DBMS (e.g., PostgreSQL), this is different to a TCP/IP connection to \code{localhost}. In addition, DBI supports the \code{bigint} argument that governs how 64-bit integer data is returned. The following values are supported: \itemize{ \item \code{"integer"}: always return as \code{integer}, silently overflow \item \code{"numeric"}: always return as \code{numeric}, silently round \item \code{"character"}: always return the decimal representation as \code{character} \item \code{"integer64"}: return as a data type that can be coerced using \code{\link[=as.integer]{as.integer()}} (with warning on overflow), \code{\link[=as.numeric]{as.numeric()}} and \code{\link[=as.character]{as.character()}} } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} # SQLite only needs a path to the database. (Here, ":memory:" is a special # path that creates an in-memory database.) Other database drivers # will require more details (like user, password, host, port, etc.) con <- dbConnect(RSQLite::SQLite(), ":memory:") con dbListTables(con) dbDisconnect(con) # Bad, for subtle reasons: # This code fails when RSQLite isn't loaded yet, # because dbConnect() doesn't know yet about RSQLite. dbListTables(con <- dbConnect(RSQLite::SQLite(), ":memory:")) \dontshow{\}) # examplesIf} } \seealso{ \code{\link[=dbDisconnect]{dbDisconnect()}} to disconnect from a database. Other DBIDriver generics: \code{\link{DBIDriver-class}}, \code{\link{dbCanConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbDriver}()}, \code{\link{dbGetInfo}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListConnections}()} Other DBIConnector generics: \code{\link{DBIConnector-class}}, \code{\link{dbDataType}()}, \code{\link{dbGetConnectArgs}()}, \code{\link{dbIsReadOnly}()} } \concept{DBIConnector generics} \concept{DBIDriver generics} DBI/man/figures/0000755000176200001440000000000014602466070013074 5ustar liggesusersDBI/man/figures/lifecycle-defunct.svg0000644000176200001440000000242414602466070017204 0ustar liggesusers lifecycle: defunct lifecycle defunct DBI/man/figures/lifecycle-maturing.svg0000644000176200001440000000243014602466070017377 0ustar liggesusers lifecycle: maturing lifecycle maturing DBI/man/figures/lifecycle-archived.svg0000644000176200001440000000243014602466070017336 0ustar liggesusers lifecycle: archived lifecycle archived DBI/man/figures/lifecycle-soft-deprecated.svg0000644000176200001440000000246614602466070020633 0ustar liggesusers lifecycle: soft-deprecated lifecycle soft-deprecated DBI/man/figures/lifecycle-questioning.svg0000644000176200001440000000244414602466070020123 0ustar liggesusers lifecycle: questioning lifecycle questioning DBI/man/figures/lifecycle-superseded.svg0000644000176200001440000000244014602466070017715 0ustar liggesusers lifecycle: superseded lifecycle superseded DBI/man/figures/lifecycle-stable.svg0000644000176200001440000000247214602466070017031 0ustar liggesusers lifecycle: stable lifecycle stable DBI/man/figures/lifecycle-experimental.svg0000644000176200001440000000245014602466070020250 0ustar liggesusers lifecycle: experimental lifecycle experimental DBI/man/figures/lifecycle-deprecated.svg0000644000176200001440000000244014602466070017652 0ustar liggesusers lifecycle: deprecated lifecycle deprecated DBI/man/rownames.Rd0000644000176200001440000000267714350241735013565 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/rownames.R \name{rownames} \alias{rownames} \alias{sqlRownamesToColumn} \alias{sqlColumnToRownames} \title{Convert row names back and forth between columns} \usage{ sqlRownamesToColumn(df, row.names = NA) sqlColumnToRownames(df, row.names = NA) } \arguments{ \item{df}{A data frame} \item{row.names}{Either \code{TRUE}, \code{FALSE}, \code{NA} or a string. If \code{TRUE}, always translate row names to a column called "row_names". If \code{FALSE}, never translate row names. If \code{NA}, translate rownames only if they're a character vector. A string is equivalent to \code{TRUE}, but allows you to override the default name. For backward compatibility, \code{NULL} is equivalent to \code{FALSE}.} } \description{ These functions provide a reasonably automatic way of preserving the row names of data frame during back-and-forth translation to an SQL table. By default, row names will be converted to an explicit column called "row_names", and any query returning a column called "row_names" will have those automatically set as row names. These methods are mostly useful for backend implementers. } \examples{ # If have row names sqlRownamesToColumn(head(mtcars)) sqlRownamesToColumn(head(mtcars), FALSE) sqlRownamesToColumn(head(mtcars), "ROWNAMES") # If don't have sqlRownamesToColumn(head(iris)) sqlRownamesToColumn(head(iris), TRUE) sqlRownamesToColumn(head(iris), "ROWNAMES") } DBI/man/DBIResult-class.Rd0000644000176200001440000000257214602466070014625 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/04-DBIResult.R \docType{class} \name{DBIResult-class} \alias{DBIResult-class} \title{DBIResult class} \description{ This virtual class describes the result and state of execution of a DBMS statement (any statement, query or non-query). The result set keeps track of whether the statement produces output how many rows were affected by the operation, how many rows have been fetched (if statement is a query), whether there are more rows to fetch, etc. } \section{Implementation notes}{ Individual drivers are free to allow single or multiple active results per connection. The default show method displays a summary of the query using other DBI generics. } \seealso{ Other DBI classes: \code{\link{DBIConnection-class}}, \code{\link{DBIConnector-class}}, \code{\link{DBIDriver-class}}, \code{\link{DBIObject-class}}, \code{\link{DBIResultArrow-class}} Other DBIResult generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} } \concept{DBI classes} \concept{DBIResult generics} DBI/man/dbExistsTable.Rd0000644000176200001440000000641114602466070014456 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbExistsTable.R \name{dbExistsTable} \alias{dbExistsTable} \title{Does a table exist?} \usage{ dbExistsTable(conn, name, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbExistsTable()} returns a logical scalar, \code{TRUE} if the table or view specified by the \code{name} argument exists, \code{FALSE} otherwise. This includes temporary tables if supported by the database. } \description{ Returns if a table given by name exists in the database. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbExistsTable")} } \section{Failure modes}{ An error is raised when calling this method for a closed or invalid connection. An error is also raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. } \section{Specification}{ The \code{name} argument is processed as follows, to support databases that allow non-syntactic names for their objects: \itemize{ \item If an unquoted table name as string: \code{dbExistsTable()} will do the quoting, perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} \item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done } For all tables listed by \code{\link[=dbListTables]{dbListTables()}}, \code{dbExistsTable()} returns \code{TRUE}. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbExistsTable(con, "iris") dbWriteTable(con, "iris", iris) dbExistsTable(con, "iris") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbFetchArrowChunk.Rd0000644000176200001440000001046014602466070015263 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbFetchArrowChunk.R \name{dbFetchArrowChunk} \alias{dbFetchArrowChunk} \title{Fetch the next batch of records from a previously executed query as an Arrow object} \usage{ dbFetchArrowChunk(res, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResultArrow}, created by \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}}.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbFetchArrowChunk()} always returns an object coercible to a \link{data.frame} with as many rows as records were fetched and as many columns as fields in the result set, even if the result is a single value or has one or zero rows. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} Fetch the next chunk of the result set and return it as an Arrow object. The chunk size is implementation-specific. Use \code{\link[=dbFetchArrow]{dbFetchArrow()}} to fetch all results. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbFetchArrowChunk")} } \section{The data retrieval flow for Arrow streams}{ This section gives a complete overview over the flow for the execution of queries that return tabular data as an Arrow stream. Most of this flow, except repeated calling of \code{\link[=dbBindArrow]{dbBindArrow()}} or \code{\link[=dbBind]{dbBind()}}, is implemented by \code{\link[=dbGetQueryArrow]{dbGetQueryArrow()}}, which should be sufficient unless you have a parameterized query that you want to reuse. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}} to create a result set object of class \linkS4class{DBIResultArrow}. \item Optionally, bind query parameters with \code{\link[=dbBindArrow]{dbBindArrow()}} or \code{\link[=dbBind]{dbBind()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Use \code{\link[=dbFetchArrow]{dbFetchArrow()}} to get a data stream. \item Repeat the last two steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ An attempt to fetch from a closed result set raises an error. } \section{Specification}{ Fetching multi-row queries with one or more columns returns the next chunk. The size of the chunk is implementation-specific. The object returned by \code{dbFetchArrowChunk()} can also be passed to \code{\link[nanoarrow:as_nanoarrow_array]{nanoarrow::as_nanoarrow_array()}} to create a nanoarrow array object. The chunk size is implementation-specific. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) # Fetch all results rs <- dbSendQueryArrow(con, "SELECT * FROM mtcars WHERE cyl = 4") dbHasCompleted(rs) as.data.frame(dbFetchArrowChunk(rs)) dbHasCompleted(rs) as.data.frame(dbFetchArrowChunk(rs)) dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Close the result set with \code{\link[=dbClearResult]{dbClearResult()}} as soon as you finish retrieving the records you want. Other DBIResultArrow generics: \code{\link{DBIResultArrow-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsValid}()} Other data retrieval generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetch}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()} } \concept{DBIResultArrow generics} \concept{data retrieval generics} DBI/man/hidden_aliases.Rd0000644000176200001440000002737714602466070014673 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/06-ANSI.R, R/SQLKeywords_DBIObject.R, % R/SQLKeywords_missing.R, R/dbAppendTableArrow_DBIConnection.R, % R/dbAppendTable_DBIConnection.R, R/dbBindArrow_DBIResult.R, % R/dbBindArrow_DBIResultArrowDefault.R, R/dbBind_DBIResultArrow.R, % R/dbCanConnect_DBIDriver.R, R/dbClearResult_DBIResultArrow.R, % R/dbConnect_DBIConnector.R, R/dbCreateTableArrow_DBIConnection.R, % R/dbCreateTable_DBIConnection.R, R/dbDataType_DBIConnector.R, % R/dbDataType_DBIObject.R, R/dbDriver_character.R, % R/dbExecute_DBIConnection_character.R, R/dbExistsTable_DBIConnection_Id.R, % R/dbFetchArrowChunk_DBIResultArrow.R, R/dbFetchArrow_DBIResultArrow.R, % R/dbFetch_DBIResult.R, R/dbFetch_DBIResultArrow.R, % R/dbGetConnectArgs_DBIConnector.R, R/dbGetInfo_DBIResult.R, % R/dbGetInfo_DBIResultArrow.R, R/dbGetQueryArrow_DBIConnection.R, % R/dbGetQuery_DBIConnection_character.R, R/dbGetRowCount_DBIResultArrow.R, % R/dbGetRowsAffected_DBIResultArrow.R, R/dbGetStatement_DBIResultArrow.R, % R/dbHasCompleted_DBIResultArrow.R, R/dbIsReadOnly_DBIConnector.R, % R/dbIsReadOnly_DBIObject.R, R/dbIsValid_DBIResultArrowDefault.R, % R/dbListFields_DBIConnection_Id.R, R/dbListFields_DBIConnection_character.R, % R/dbListObjects_DBIConnection_ANY.R, R/dbQuoteIdentifier_DBIConnection.R, % R/dbQuoteLiteral_DBIConnection.R, R/dbQuoteString_DBIConnection.R, % R/dbReadTableArrow_DBIConnection.R, R/dbReadTable_DBIConnection_Id.R, % R/dbReadTable_DBIConnection_character.R, % R/dbRemoveTable_DBIConnection_Id.R, R/dbSendQueryArrow_DBIConnection.R, % R/dbSendStatement_DBIConnection_character.R, % R/dbUnquoteIdentifier_DBIConnection.R, R/dbWithTransaction_DBIConnection.R, % R/dbWriteTableArrow_DBIConnection.R, R/dbWriteTable_DBIConnection_Id_ANY.R, % R/isSQLKeyword_DBIObject_character.R, R/make.db.names_DBIObject_character.R, % R/show_AnsiConnection.R, R/show_DBIConnection.R, R/show_DBIConnector.R, % R/show_DBIDriver.R, R/show_DBIResult.R, R/show_Id.R, R/show_SQL.R, % R/sqlAppendTable_DBIConnection.R, R/sqlCreateTable_DBIConnection.R, % R/sqlData_DBIConnection.R, R/sqlInterpolate_DBIConnection.R, % R/sqlParseVariables_DBIConnection.R \docType{methods} \name{hidden_aliases} \alias{hidden_aliases} \alias{SQLKeywords_DBIObject} \alias{SQLKeywords,DBIObject-method} \alias{SQLKeywords_missing} \alias{SQLKeywords,missing-method} \alias{dbAppendTableArrow_DBIConnection} \alias{dbAppendTableArrow,DBIConnection-method} \alias{dbAppendTable_DBIConnection} \alias{dbAppendTable,DBIConnection-method} \alias{dbBindArrow_DBIResult} \alias{dbBindArrow,DBIResult-method} \alias{dbBindArrow_DBIResultArrowDefault} \alias{dbBindArrow,DBIResultArrowDefault-method} \alias{dbBind_DBIResultArrow} \alias{dbBind,DBIResultArrow-method} \alias{dbCanConnect_DBIDriver} \alias{dbCanConnect,DBIDriver-method} \alias{dbClearResult_DBIResultArrow} \alias{dbClearResult,DBIResultArrow-method} \alias{dbConnect_DBIConnector} \alias{dbConnect,DBIConnector-method} \alias{dbCreateTableArrow_DBIConnection} \alias{dbCreateTableArrow,DBIConnection-method} \alias{dbCreateTable_DBIConnection} \alias{dbCreateTable,DBIConnection-method} \alias{dbDataType_DBIConnector} \alias{dbDataType,DBIConnector-method} \alias{dbDataType_DBIObject} \alias{dbDataType,DBIObject-method} \alias{dbDriver_character} \alias{dbDriver,character-method} \alias{dbExecute_DBIConnection_character} \alias{dbExecute,DBIConnection,character-method} \alias{dbExistsTable_DBIConnection_Id} \alias{dbExistsTable,DBIConnection,Id-method} \alias{dbFetchArrowChunk_DBIResultArrow} \alias{dbFetchArrowChunk,DBIResultArrow-method} \alias{dbFetchArrow_DBIResultArrow} \alias{dbFetchArrow,DBIResultArrow-method} \alias{dbFetch_DBIResult} \alias{dbFetch,DBIResult-method} \alias{dbFetch_DBIResultArrow} \alias{dbFetch,DBIResultArrow-method} \alias{dbGetConnectArgs_DBIConnector} \alias{dbGetConnectArgs,DBIConnector-method} \alias{dbGetInfo_DBIResult} \alias{dbGetInfo,DBIResult-method} \alias{dbGetInfo_DBIResultArrow} \alias{dbGetInfo,DBIResultArrow-method} \alias{dbGetQueryArrow_DBIConnection_character} \alias{dbGetQueryArrow,DBIConnection-method} \alias{dbGetQuery_DBIConnection_character} \alias{dbGetQuery,DBIConnection,character-method} \alias{dbGetRowCount_DBIResultArrow} \alias{dbGetRowCount,DBIResultArrow-method} \alias{dbGetRowsAffected_DBIResultArrow} \alias{dbGetRowsAffected,DBIResultArrow-method} \alias{dbGetStatement_DBIResultArrow} \alias{dbGetStatement,DBIResultArrow-method} \alias{dbHasCompleted_DBIResultArrow} \alias{dbHasCompleted,DBIResultArrow-method} \alias{dbIsReadOnly_DBIConnector} \alias{dbIsReadOnly,DBIConnector-method} \alias{dbIsReadOnly_DBIObject} \alias{dbIsReadOnly,DBIObject-method} \alias{dbIsValid_DBIResultArrowDefault} \alias{dbIsValid,DBIResultArrowDefault-method} \alias{dbListFields_DBIConnection_Id} \alias{dbListFields,DBIConnection,Id-method} \alias{dbListFields_DBIConnection_character} \alias{dbListFields,DBIConnection,character-method} \alias{dbListObjects_DBIConnection_ANY} \alias{dbListObjects,DBIConnection-method} \alias{dbQuoteIdentifier_DBIConnection} \alias{dbQuoteIdentifier,DBIConnection,ANY-method} \alias{dbQuoteIdentifier,DBIConnection,character-method} \alias{dbQuoteIdentifier,DBIConnection,SQL-method} \alias{dbQuoteIdentifier,DBIConnection,Id-method} \alias{dbQuoteLiteral_DBIConnection} \alias{dbQuoteLiteral,DBIConnection-method} \alias{dbQuoteString_DBIConnection} \alias{dbQuoteString,DBIConnection,ANY-method} \alias{dbQuoteString,DBIConnection,character-method} \alias{dbQuoteString,DBIConnection,SQL-method} \alias{dbReadTableArrow_DBIConnection} \alias{dbReadTableArrow,DBIConnection-method} \alias{dbReadTable_DBIConnection_Id} \alias{dbReadTable,DBIConnection,Id-method} \alias{dbReadTable_DBIConnection_character} \alias{dbReadTable,DBIConnection,character-method} \alias{dbRemoveTable_DBIConnection_Id} \alias{dbRemoveTable,DBIConnection,Id-method} \alias{dbSendQueryArrow_DBIConnection} \alias{dbSendQueryArrow,DBIConnection-method} \alias{dbSendStatement_DBIConnection_character} \alias{dbSendStatement,DBIConnection,character-method} \alias{dbUnquoteIdentifier_DBIConnection} \alias{dbUnquoteIdentifier,DBIConnection-method} \alias{dbWithTransaction_DBIConnection} \alias{dbWithTransaction,DBIConnection-method} \alias{dbWriteTableArrow_DBIConnection} \alias{dbWriteTableArrow,DBIConnection-method} \alias{dbWriteTable_DBIConnection_Id_ANY} \alias{dbWriteTable,DBIConnection,Id-method} \alias{isSQLKeyword_DBIObject_character} \alias{isSQLKeyword,DBIObject,character-method} \alias{make.db.names_DBIObject_character} \alias{make.db.names,DBIObject,character-method} \alias{show_AnsiConnection} \alias{show,AnsiConnection-method} \alias{show_DBIConnection} \alias{show,DBIConnection-method} \alias{show_DBIConnector} \alias{show,DBIConnector-method} \alias{show_DBIDriver} \alias{show,DBIDriver-method} \alias{show_DBIResult} \alias{show,DBIResult-method} \alias{show_Id} \alias{show,Id-method} \alias{show_SQL} \alias{show,SQL-method} \alias{sqlAppendTable_DBIConnection} \alias{sqlAppendTable,DBIConnection-method} \alias{sqlCreateTable_DBIConnection} \alias{sqlCreateTable,DBIConnection-method} \alias{sqlData_DBIConnection} \alias{sqlData,DBIConnection-method} \alias{sqlInterpolate_DBIConnection} \alias{sqlInterpolate,DBIConnection-method} \alias{sqlParseVariables_DBIConnection} \alias{sqlParseVariables,DBIConnection-method} \title{Internal page for hidden aliases} \usage{ \S4method{SQLKeywords}{DBIObject}(dbObj, ...) \S4method{SQLKeywords}{missing}(dbObj, ...) \S4method{dbAppendTableArrow}{DBIConnection}(conn, name, value, ...) \S4method{dbAppendTable}{DBIConnection}(conn, name, value, ..., row.names = NULL) \S4method{dbBindArrow}{DBIResult}(res, params, ...) \S4method{dbBindArrow}{DBIResultArrowDefault}(res, params, ...) \S4method{dbBind}{DBIResultArrow}(res, params, ...) \S4method{dbCanConnect}{DBIDriver}(drv, ...) \S4method{dbClearResult}{DBIResultArrow}(res, ...) \S4method{dbConnect}{DBIConnector}(drv, ...) \S4method{dbCreateTableArrow}{DBIConnection}(conn, name, value, ..., temporary = FALSE) \S4method{dbCreateTable}{DBIConnection}(conn, name, fields, ..., row.names = NULL, temporary = FALSE) \S4method{dbDataType}{DBIConnector}(dbObj, obj, ...) \S4method{dbDataType}{DBIObject}(dbObj, obj, ...) \S4method{dbDriver}{character}(drvName, ...) \S4method{dbExecute}{DBIConnection,character}(conn, statement, ...) \S4method{dbExistsTable}{DBIConnection,Id}(conn, name, ...) \S4method{dbFetchArrowChunk}{DBIResultArrow}(res, ...) \S4method{dbFetchArrow}{DBIResultArrow}(res, ...) \S4method{dbFetch}{DBIResult}(res, n = -1, ...) \S4method{dbFetch}{DBIResultArrow}(res, n = -1, ...) \S4method{dbGetConnectArgs}{DBIConnector}(drv, eval = TRUE, ...) \S4method{dbGetInfo}{DBIResult}(dbObj, ...) \S4method{dbGetInfo}{DBIResultArrow}(dbObj, ...) \S4method{dbGetQueryArrow}{DBIConnection}(conn, statement, ...) \S4method{dbGetQuery}{DBIConnection,character}(conn, statement, ..., n = -1L) \S4method{dbGetRowCount}{DBIResultArrow}(res, ...) \S4method{dbGetRowsAffected}{DBIResultArrow}(res, ...) \S4method{dbGetStatement}{DBIResultArrow}(res, ...) \S4method{dbHasCompleted}{DBIResultArrow}(res, ...) \S4method{dbIsReadOnly}{DBIConnector}(dbObj, ...) \S4method{dbIsReadOnly}{DBIObject}(dbObj, ...) \S4method{dbIsValid}{DBIResultArrowDefault}(dbObj, ...) \S4method{dbListFields}{DBIConnection,Id}(conn, name, ...) \S4method{dbListFields}{DBIConnection,character}(conn, name, ...) \S4method{dbListObjects}{DBIConnection}(conn, prefix = NULL, ...) \S4method{dbQuoteIdentifier}{DBIConnection,ANY}(conn, x, ...) \S4method{dbQuoteIdentifier}{DBIConnection,character}(conn, x, ...) \S4method{dbQuoteIdentifier}{DBIConnection,SQL}(conn, x, ...) \S4method{dbQuoteIdentifier}{DBIConnection,Id}(conn, x, ...) \S4method{dbQuoteLiteral}{DBIConnection}(conn, x, ...) \S4method{dbQuoteString}{DBIConnection,ANY}(conn, x, ...) \S4method{dbQuoteString}{DBIConnection,character}(conn, x, ...) \S4method{dbQuoteString}{DBIConnection,SQL}(conn, x, ...) \S4method{dbReadTableArrow}{DBIConnection}(conn, name, ...) \S4method{dbReadTable}{DBIConnection,Id}(conn, name, ...) \S4method{dbReadTable}{DBIConnection,character}(conn, name, ..., row.names = FALSE, check.names = TRUE) \S4method{dbRemoveTable}{DBIConnection,Id}(conn, name, ...) \S4method{dbSendQueryArrow}{DBIConnection}(conn, statement, params = NULL, ...) \S4method{dbSendStatement}{DBIConnection,character}(conn, statement, ...) \S4method{dbUnquoteIdentifier}{DBIConnection}(conn, x, ...) \S4method{dbWithTransaction}{DBIConnection}(conn, code) \S4method{dbWriteTableArrow}{DBIConnection}( conn, name, value, append = FALSE, overwrite = FALSE, ..., temporary = FALSE ) \S4method{dbWriteTable}{DBIConnection,Id}(conn, name, value, ...) \S4method{isSQLKeyword}{DBIObject,character}( dbObj, name, keywords = .SQL92Keywords, case = c("lower", "upper", "any")[3], ... ) \S4method{make.db.names}{DBIObject,character}( dbObj, snames, keywords = .SQL92Keywords, unique = TRUE, allow.keywords = TRUE, ... ) \S4method{show}{AnsiConnection}(object) \S4method{show}{DBIConnection}(object) \S4method{show}{DBIConnector}(object) \S4method{show}{DBIDriver}(object) \S4method{show}{DBIResult}(object) \S4method{show}{Id}(object) \S4method{show}{SQL}(object) \S4method{sqlAppendTable}{DBIConnection}(con, table, values, row.names = NA, ...) \S4method{sqlCreateTable}{DBIConnection}(con, table, fields, row.names = NA, temporary = FALSE, ...) \S4method{sqlData}{DBIConnection}(con, value, row.names = NA, ...) \S4method{sqlInterpolate}{DBIConnection}(conn, sql, ..., .dots = list()) \S4method{sqlParseVariables}{DBIConnection}(conn, sql, ...) } \arguments{ \item{n}{Number of rows to fetch, default -1} \item{object}{Table object to print} } \description{ For S4 methods that require a documentation entry but only clutter the index. } \keyword{internal} DBI/man/make.db.names.Rd0000644000176200001440000000671014350241735014325 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/deprecated.R, R/isSQLKeyword.R, % R/make.db.names.R \name{make.db.names.default} \alias{make.db.names.default} \alias{isSQLKeyword.default} \alias{isSQLKeyword} \alias{make.db.names} \alias{SQLKeywords} \title{Make R identifiers into legal SQL identifiers} \usage{ make.db.names.default( snames, keywords = .SQL92Keywords, unique = TRUE, allow.keywords = TRUE ) isSQLKeyword.default( name, keywords = .SQL92Keywords, case = c("lower", "upper", "any")[3] ) isSQLKeyword( dbObj, name, keywords = .SQL92Keywords, case = c("lower", "upper", "any")[3], ... ) make.db.names( dbObj, snames, keywords = .SQL92Keywords, unique = TRUE, allow.keywords = TRUE, ... ) } \arguments{ \item{snames}{a character vector of R identifiers (symbols) from which we need to make SQL identifiers.} \item{keywords}{a character vector with SQL keywords, by default it's \code{.SQL92Keywords} defined by the DBI.} \item{unique}{logical describing whether the resulting set of SQL names should be unique. Its default is \code{TRUE}. Following the SQL 92 standard, uniqueness of SQL identifiers is determined regardless of whether letters are upper or lower case.} \item{allow.keywords}{logical describing whether SQL keywords should be allowed in the resulting set of SQL names. Its default is \code{TRUE}} \item{name}{a character vector with database identifier candidates we need to determine whether they are legal SQL identifiers or not.} \item{case}{a character string specifying whether to make the comparison as lower case, upper case, or any of the two. it defaults to \code{any}.} \item{dbObj}{any DBI object (e.g., \code{DBIDriver}).} \item{\dots}{any other argument are passed to the driver implementation.} } \value{ \code{make.db.names} returns a character vector of legal SQL identifiers corresponding to its \code{snames} argument. \code{SQLKeywords} returns a character vector of all known keywords for the database-engine associated with \code{dbObj}. \code{isSQLKeyword} returns a logical vector parallel to \code{name}. } \description{ These methods are DEPRECATED. Please use \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} (or possibly \code{\link[=dbQuoteString]{dbQuoteString()}}) instead. } \details{ The algorithm in \code{make.db.names} first invokes \code{make.names} and then replaces each occurrence of a dot \code{.} by an underscore \verb{_}. If \code{allow.keywords} is \code{FALSE} and identifiers collide with SQL keywords, a small integer is appended to the identifier in the form of \code{"_n"}. The set of SQL keywords is stored in the character vector \code{.SQL92Keywords} and reflects the SQL ANSI/ISO standard as documented in "X/Open SQL and RDA", 1994, ISBN 1-872630-68-8. Users can easily override or update this vector. } \section{Bugs}{ The current mapping is not guaranteed to be fully reversible: some SQL identifiers that get mapped into R identifiers with \code{make.names} and then back to SQL with \code{\link[=make.db.names]{make.db.names()}} will not be equal to the original SQL identifiers (e.g., compound SQL identifiers of the form \code{username.tablename} will loose the dot ``.''). } \references{ The set of SQL keywords is stored in the character vector \code{.SQL92Keywords} and reflects the SQL ANSI/ISO standard as documented in "X/Open SQL and RDA", 1994, ISBN 1-872630-68-8. Users can easily override or update this vector. } \keyword{internal} DBI/man/dbGetRowsAffected.Rd0000644000176200001440000000746414602466070015254 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbGetRowsAffected.R \name{dbGetRowsAffected} \alias{dbGetRowsAffected} \title{The number of rows affected} \usage{ dbGetRowsAffected(res, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResult}.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbGetRowsAffected()} returns a scalar number (integer or numeric), the number of rows affected by a data manipulation statement issued with \code{\link[=dbSendStatement]{dbSendStatement()}}. The value is available directly after the call and does not change after calling \code{\link[=dbFetch]{dbFetch()}}. \code{NA_integer_} or \code{NA_numeric_} are allowed if the number of rows affected is not known. For queries issued with \code{\link[=dbSendQuery]{dbSendQuery()}}, zero is returned before and after the call to \code{dbFetch()}. \code{NA} values are not allowed. } \description{ This method returns the number of rows that were added, deleted, or updated by a data manipulation statement. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbGetRowsAffected")} } \section{The command execution flow}{ This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of \code{\link[=dbBindArrow]{dbBindArrow()}}, is implemented by \code{\link[=dbExecute]{dbExecute()}}, which should be sufficient for non-parameterized queries. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendStatement]{dbSendStatement()}} to create a result set object of class \linkS4class{DBIResult}. For some queries you need to pass \code{immediate = TRUE}. \item Optionally, bind query parameters with\code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Optionally, use \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}} to retrieve the number of rows affected by the query. \item Repeat the last two steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ Attempting to get the rows affected for a result set cleared with \code{\link[=dbClearResult]{dbClearResult()}} gives an error. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendStatement(con, "DELETE FROM mtcars") dbGetRowsAffected(rs) nrow(mtcars) dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} Other command execution generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbExecute}()}, \code{\link{dbSendStatement}()} } \concept{DBIResult generics} \concept{command execution generics} DBI/man/dbListObjects.Rd0000644000176200001440000001072014602466070014452 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbListObjects.R \name{dbListObjects} \alias{dbListObjects} \title{List remote objects} \usage{ dbListObjects(conn, prefix = NULL, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{prefix}{A fully qualified path in the database's namespace, or \code{NULL}. This argument will be processed with \code{\link[=dbUnquoteIdentifier]{dbUnquoteIdentifier()}}. If given the method will return all objects accessible through this prefix.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbListObjects()} returns a data frame with columns \code{table} and \code{is_prefix} (in that order), optionally with other columns with a dot (\code{.}) prefix. The \code{table} column is of type list. Each object in this list is suitable for use as argument in \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. The \code{is_prefix} column is a logical. This data frame contains one row for each object (schema, table and view) accessible from the prefix (if passed) or from the global namespace (if prefix is omitted). Tables added with \code{\link[=dbWriteTable]{dbWriteTable()}} are part of the data frame. As soon a table is removed from the database, it is also removed from the data frame of database objects. The same applies to temporary objects if supported by the database. The returned names are suitable for quoting with \code{dbQuoteIdentifier()}. } \description{ Returns the names of remote objects accessible through this connection as a data frame. This should include temporary objects, but not all database backends (in particular \pkg{RMariaDB} and \pkg{RMySQL}) support this. Compared to \code{\link[=dbListTables]{dbListTables()}}, this method also enumerates tables and views in schemas, and returns fully qualified identifiers to access these objects. This allows exploration of all database objects available to the current user, including those that can only be accessed by giving the full namespace. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbListObjects")} } \section{Failure modes}{ An error is raised when calling this method for a closed or invalid connection. } \section{Specification}{ The \code{prefix} column indicates if the \code{table} value refers to a table or a prefix. For a call with the default \code{prefix = NULL}, the \code{table} values that have \code{is_prefix == FALSE} correspond to the tables returned from \code{\link[=dbListTables]{dbListTables()}}, The \code{table} object can be quoted with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. The result of quoting can be passed to \code{\link[=dbUnquoteIdentifier]{dbUnquoteIdentifier()}}. (For backends it may be convenient to use the \link{Id} class, but this is not required.) Values in \code{table} column that have \code{is_prefix == TRUE} can be passed as the \code{prefix} argument to another call to \code{dbListObjects()}. For the data frame returned from a \code{dbListObject()} call with the \code{prefix} argument set, all \code{table} values where \code{is_prefix} is \code{FALSE} can be used in a call to \code{\link[=dbExistsTable]{dbExistsTable()}} which returns \code{TRUE}. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbListObjects(con) dbWriteTable(con, "mtcars", mtcars) dbListObjects(con) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbListFields.Rd0000644000176200001440000000640114602466070014270 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbListFields.R \name{dbListFields} \alias{dbListFields} \title{List field names of a remote table} \usage{ dbListFields(conn, name, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbListFields()} returns a character vector that enumerates all fields in the table in the correct order. This also works for temporary tables if supported by the database. The returned names are suitable for quoting with \code{dbQuoteIdentifier()}. } \description{ Returns the field names of a remote table as a character vector. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbListFields")} } \section{Failure modes}{ If the table does not exist, an error is raised. Invalid types for the \code{name} argument (e.g., \code{character} of length not equal to one, or numeric) lead to an error. An error is also raised when calling this method for a closed or invalid connection. } \section{Specification}{ The \code{name} argument can be \itemize{ \item a string \item the return value of \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} \item a value from the \code{table} column from the return value of \code{\link[=dbListObjects]{dbListObjects()}} where \code{is_prefix} is \code{FALSE} } A column named \code{row_names} is treated like any other column. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) dbListFields(con, "mtcars") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ \code{\link[=dbColumnInfo]{dbColumnInfo()}} to get the type of the fields. Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbDataType.Rd0000644000176200001440000001200214602466070013733 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbDataType.R \name{dbDataType} \alias{dbDataType} \title{Determine the SQL data type of an object} \usage{ dbDataType(dbObj, obj, ...) } \arguments{ \item{dbObj}{A object inheriting from \linkS4class{DBIDriver} or \linkS4class{DBIConnection}} \item{obj}{An R object whose SQL type we want to determine.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbDataType()} returns the SQL type that corresponds to the \code{obj} argument as a non-empty character string. For data frames, a character vector with one element per column is returned. } \description{ Returns an SQL string that describes the SQL data type to be used for an object. The default implementation of this generic determines the SQL type of an R object according to the SQL 92 specification, which may serve as a starting point for driver implementations. DBI also provides an implementation for data.frame which will return a character vector giving the type for each column in the dataframe. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbDataType")} } \details{ The data types supported by databases are different than the data types in R, but the mapping between the primitive types is straightforward: \itemize{ \item Any of the many fixed and varying length character types are mapped to character vectors \item Fixed-precision (non-IEEE) numbers are mapped into either numeric or integer vectors. } Notice that many DBMS do not follow IEEE arithmetic, so there are potential problems with under/overflows and loss of precision. } \section{Failure modes}{ An error is raised for invalid values for the \code{obj} argument such as a \code{NULL} value. } \section{Specification}{ The backend can override the \code{\link[=dbDataType]{dbDataType()}} generic for its driver class. This generic expects an arbitrary object as second argument. To query the values returned by the default implementation, run \code{example(dbDataType, package = "DBI")}. If the backend needs to override this generic, it must accept all basic R data types as its second argument, namely \link{logical}, \link{integer}, \link{numeric}, \link{character}, dates (see \link{Dates}), date-time (see \link{DateTimeClasses}), and \link{difftime}. If the database supports blobs, this method also must accept lists of \link{raw} vectors, and \link[blob:blob]{blob::blob} objects. As-is objects (i.e., wrapped by \code{\link[=I]{I()}}) must be supported and return the same results as their unwrapped counterparts. The SQL data type for \link{factor} and \link{ordered} is the same as for character. The behavior for other object types is not specified. All data types returned by \code{dbDataType()} are usable in an SQL statement of the form \code{"CREATE TABLE test (a ...)"}. } \examples{ dbDataType(ANSI(), 1:5) dbDataType(ANSI(), 1) dbDataType(ANSI(), TRUE) dbDataType(ANSI(), Sys.Date()) dbDataType(ANSI(), Sys.time()) dbDataType(ANSI(), Sys.time() - as.POSIXct(Sys.Date())) dbDataType(ANSI(), c("x", "abc")) dbDataType(ANSI(), list(raw(10), raw(20))) dbDataType(ANSI(), I(3)) dbDataType(ANSI(), iris) \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbDataType(con, 1:5) dbDataType(con, 1) dbDataType(con, TRUE) dbDataType(con, Sys.Date()) dbDataType(con, Sys.time()) dbDataType(con, Sys.time() - as.POSIXct(Sys.Date())) dbDataType(con, c("x", "abc")) dbDataType(con, list(raw(10), raw(20))) dbDataType(con, I(3)) dbDataType(con, iris) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIDriver generics: \code{\link{DBIDriver-class}}, \code{\link{dbCanConnect}()}, \code{\link{dbConnect}()}, \code{\link{dbDriver}()}, \code{\link{dbGetInfo}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListConnections}()} Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} Other DBIConnector generics: \code{\link{DBIConnector-class}}, \code{\link{dbConnect}()}, \code{\link{dbGetConnectArgs}()}, \code{\link{dbIsReadOnly}()} } \concept{DBIConnection generics} \concept{DBIConnector generics} \concept{DBIDriver generics} DBI/man/dbRemoveTable.Rd0000644000176200001440000001036414602466070014436 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbRemoveTable.R \name{dbRemoveTable} \alias{dbRemoveTable} \title{Remove a table from the database} \usage{ dbRemoveTable(conn, name, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbRemoveTable()} returns \code{TRUE}, invisibly. } \description{ Remove a remote table (e.g., created by \code{\link[=dbWriteTable]{dbWriteTable()}}) from the database. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbRemoveTable")} } \section{Failure modes}{ If the table does not exist, an error is raised. An attempt to remove a view with this function may result in an error. An error is raised when calling this method for a closed or invalid connection. An error is also raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. } \section{Additional arguments}{ The following arguments are not part of the \code{dbRemoveTable()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{temporary} (default: \code{FALSE}) \item \code{fail_if_missing} (default: \code{TRUE}) } These arguments must be provided as named arguments. If \code{temporary} is \code{TRUE}, the call to \code{dbRemoveTable()} will consider only temporary tables. Not all backends support this argument. In particular, permanent tables of the same name are left untouched. If \code{fail_if_missing} is \code{FALSE}, the call to \code{dbRemoveTable()} succeeds if the table does not exist. } \section{Specification}{ A table removed by \code{dbRemoveTable()} doesn't appear in the list of tables returned by \code{\link[=dbListTables]{dbListTables()}}, and \code{\link[=dbExistsTable]{dbExistsTable()}} returns \code{FALSE}. The removal propagates immediately to other connections to the same database. This function can also be used to remove a temporary table. The \code{name} argument is processed as follows, to support databases that allow non-syntactic names for their objects: \itemize{ \item If an unquoted table name as string: \code{dbRemoveTable()} will do the quoting, perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} \item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbExistsTable(con, "iris") dbWriteTable(con, "iris", iris) dbExistsTable(con, "iris") dbRemoveTable(con, "iris") dbExistsTable(con, "iris") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbAppendTableArrow.Rd0000644000176200001440000001326014602466070015421 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/21-dbAppendTableArrow.R \name{dbAppendTableArrow} \alias{dbAppendTableArrow} \title{Insert rows into a table from an Arrow stream} \usage{ dbAppendTableArrow(conn, name, value, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{value}{An object coercible with \code{\link[nanoarrow:as_nanoarrow_array_stream]{nanoarrow::as_nanoarrow_array_stream()}}.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbAppendTableArrow()} returns a scalar numeric. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} The \code{dbAppendTableArrow()} method assumes that the table has been created beforehand, e.g. with \code{\link[=dbCreateTableArrow]{dbCreateTableArrow()}}. The default implementation calls \code{\link[=dbAppendTable]{dbAppendTable()}} for each chunk of the stream. Use \code{\link[=dbAppendTable]{dbAppendTable()}} to append data from a data.frame. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbAppendTableArrow")} } \section{Failure modes}{ If the table does not exist, or the new data in \code{values} is not a data frame or has different column names, an error is raised; the remote table remains unchanged. An error is raised when calling this method for a closed or invalid connection. An error is also raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. } \section{Specification}{ SQL keywords can be used freely in table names, column names, and data. Quotes, commas, spaces, and other special characters such as newlines and tabs, can also be used in the data, and, if the database supports non-syntactic identifiers, also for table names and column names. The following data types must be supported at least, and be read identically with \code{\link[=dbReadTable]{dbReadTable()}}: \itemize{ \item integer \item numeric (the behavior for \code{Inf} and \code{NaN} is not specified) \item logical \item \code{NA} as NULL \item 64-bit values (using \code{"bigint"} as field type); the result can be \itemize{ \item converted to a numeric, which may lose precision, \item converted a character vector, which gives the full decimal representation \item written to another table and read again unchanged } \item character (in both UTF-8 and native encodings), supporting empty strings (before and after non-empty strings) \item factor (possibly returned as character) \item objects of type \link[blob:blob]{blob::blob} (if supported by the database) \item date (if supported by the database; returned as \code{Date}) also for dates prior to 1970 or 1900 or after 2038 \item time (if supported by the database; returned as objects that inherit from \code{difftime}) \item timestamp (if supported by the database; returned as \code{POSIXct} respecting the time zone but not necessarily preserving the input time zone), also for timestamps prior to 1970 or 1900 or after 2038 respecting the time zone but not necessarily preserving the input time zone) } Mixing column types in the same table is supported. The \code{name} argument is processed as follows, to support databases that allow non-syntactic names for their objects: \itemize{ \item If an unquoted table name as string: \code{dbAppendTableArrow()} will do the quoting, perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} \item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done to support databases that allow non-syntactic names for their objects: } The \code{value} argument must be a data frame with a subset of the columns of the existing table. The order of the columns does not matter. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbCreateTableArrow(con, "iris", iris[0, ]) dbAppendTableArrow(con, "iris", iris[1:5, ]) dbReadTable(con, "iris") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbFetchArrow.Rd0000644000176200001440000001025414602466070014273 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbFetchArrow.R \name{dbFetchArrow} \alias{dbFetchArrow} \title{Fetch records from a previously executed query as an Arrow object} \usage{ dbFetchArrow(res, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResultArrow}, created by \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}}.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbFetchArrow()} always returns an object coercible to a \link{data.frame} with as many rows as records were fetched and as many columns as fields in the result set, even if the result is a single value or has one or zero rows. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} Fetch the result set and return it as an Arrow object. Use \code{\link[=dbFetchArrowChunk]{dbFetchArrowChunk()}} to fetch results in chunks. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbFetchArrow")} } \section{The data retrieval flow for Arrow streams}{ This section gives a complete overview over the flow for the execution of queries that return tabular data as an Arrow stream. Most of this flow, except repeated calling of \code{\link[=dbBindArrow]{dbBindArrow()}} or \code{\link[=dbBind]{dbBind()}}, is implemented by \code{\link[=dbGetQueryArrow]{dbGetQueryArrow()}}, which should be sufficient unless you have a parameterized query that you want to reuse. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}} to create a result set object of class \linkS4class{DBIResultArrow}. \item Optionally, bind query parameters with \code{\link[=dbBindArrow]{dbBindArrow()}} or \code{\link[=dbBind]{dbBind()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Use \code{\link[=dbFetchArrow]{dbFetchArrow()}} to get a data stream. \item Repeat the last two steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ An attempt to fetch from a closed result set raises an error. } \section{Specification}{ Fetching multi-row queries with one or more columns by default returns the entire result. The object returned by \code{dbFetchArrow()} can also be passed to \code{\link[nanoarrow:as_nanoarrow_array_stream]{nanoarrow::as_nanoarrow_array_stream()}} to create a nanoarrow array stream object that can be used to read the result set in batches. The chunk size is implementation-specific. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) # Fetch all results rs <- dbSendQueryArrow(con, "SELECT * FROM mtcars WHERE cyl = 4") as.data.frame(dbFetchArrow(rs)) dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Close the result set with \code{\link[=dbClearResult]{dbClearResult()}} as soon as you finish retrieving the records you want. Other DBIResultArrow generics: \code{\link{DBIResultArrow-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsValid}()} Other data retrieval generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetch}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()} } \concept{DBIResultArrow generics} \concept{data retrieval generics} DBI/man/dbBind.Rd0000644000176200001440000003765014614477037013124 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/15-dbBind.R, R/25-dbBindArrow.R \name{dbBind} \alias{dbBind} \alias{dbBindArrow} \title{Bind values to a parameterized/prepared statement} \usage{ dbBind(res, params, ...) dbBindArrow(res, params, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResult}.} \item{params}{For \code{dbBind()}, a list of values, named or unnamed, or a data frame, with one element/column per query parameter. For \code{dbBindArrow()}, values as a nanoarrow stream, with one column per query parameter.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbBind()} returns the result set, invisibly, for queries issued by \code{\link[=dbSendQuery]{dbSendQuery()}} or \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}} and also for data manipulation statements issued by \code{\link[=dbSendStatement]{dbSendStatement()}}. } \description{ For parametrized or prepared statements, the \code{\link[=dbSendQuery]{dbSendQuery()}}, \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}}, and \code{\link[=dbSendStatement]{dbSendStatement()}} functions can be called with statements that contain placeholders for values. The \code{dbBind()} and \code{dbBindArrow()} functions bind these placeholders to actual values, and are intended to be called on the result set before calling \code{\link[=dbFetch]{dbFetch()}} or \code{\link[=dbFetchArrow]{dbFetchArrow()}}. The values are passed to \code{dbBind()} as lists or data frames, and to \code{dbBindArrow()} as a stream created by \code{\link[nanoarrow:as_nanoarrow_array_stream]{nanoarrow::as_nanoarrow_array_stream()}}. \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} \code{dbBindArrow()} is experimental, as are the other \verb{*Arrow} functions. \code{dbSendQuery()} is compatible with \code{dbBindArrow()}, and \code{dbSendQueryArrow()} is compatible with \code{dbBind()}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbBind")} } \details{ \pkg{DBI} supports parametrized (or prepared) queries and statements via the \code{dbBind()} and \code{dbBindArrow()} generics. Parametrized queries are different from normal queries in that they allow an arbitrary number of placeholders, which are later substituted by actual values. Parametrized queries (and statements) serve two purposes: \itemize{ \item The same query can be executed more than once with different values. The DBMS may cache intermediate information for the query, such as the execution plan, and execute it faster. \item Separation of query syntax and parameters protects against SQL injection. } The placeholder format is currently not specified by \pkg{DBI}; in the future, a uniform placeholder syntax may be supported. Consult the backend documentation for the supported formats. For automated testing, backend authors specify the placeholder syntax with the \code{placeholder_pattern} tweak. Known examples are: \itemize{ \item \verb{?} (positional matching in order of appearance) in \pkg{RMariaDB} and \pkg{RSQLite} \item \verb{$1} (positional matching by index) in \pkg{RPostgres} and \pkg{RSQLite} \item \verb{:name} and \verb{$name} (named matching) in \pkg{RSQLite} } } \section{The data retrieval flow}{ This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}, is implemented by \code{\link[=dbGetQuery]{dbGetQuery()}}, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendQuery]{dbSendQuery()}} to create a result set object of class \linkS4class{DBIResult}. \item Optionally, bind query parameters with \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Optionally, use \code{\link[=dbColumnInfo]{dbColumnInfo()}} to retrieve the structure of the result set without retrieving actual data. \item Use \code{\link[=dbFetch]{dbFetch()}} to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. \item Use \code{\link[=dbHasCompleted]{dbHasCompleted()}} to tell when you're done. This method returns \code{TRUE} if no more rows are available for fetching. \item Repeat the last four steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{The data retrieval flow for Arrow streams}{ This section gives a complete overview over the flow for the execution of queries that return tabular data as an Arrow stream. Most of this flow, except repeated calling of \code{\link[=dbBindArrow]{dbBindArrow()}} or \code{\link[=dbBind]{dbBind()}}, is implemented by \code{\link[=dbGetQueryArrow]{dbGetQueryArrow()}}, which should be sufficient unless you have a parameterized query that you want to reuse. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}} to create a result set object of class \linkS4class{DBIResultArrow}. \item Optionally, bind query parameters with \code{\link[=dbBindArrow]{dbBindArrow()}} or \code{\link[=dbBind]{dbBind()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Use \code{\link[=dbFetchArrow]{dbFetchArrow()}} to get a data stream. \item Repeat the last two steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{The command execution flow}{ This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of \code{\link[=dbBindArrow]{dbBindArrow()}}, is implemented by \code{\link[=dbExecute]{dbExecute()}}, which should be sufficient for non-parameterized queries. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendStatement]{dbSendStatement()}} to create a result set object of class \linkS4class{DBIResult}. For some queries you need to pass \code{immediate = TRUE}. \item Optionally, bind query parameters with\code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Optionally, use \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}} to retrieve the number of rows affected by the query. \item Repeat the last two steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ Calling \code{dbBind()} for a query without parameters raises an error. Binding too many or not enough values, or parameters with wrong names or unequal length, also raises an error. If the placeholders in the query are named, all parameter values must have names (which must not be empty or \code{NA}), and vice versa, otherwise an error is raised. The behavior for mixing placeholders of different types (in particular mixing positional and named placeholders) is not specified. Calling \code{dbBind()} on a result set already cleared by \code{\link[=dbClearResult]{dbClearResult()}} also raises an error. } \section{Specification}{ \pkg{DBI} clients execute parametrized statements as follows: \enumerate{ \item Call \code{\link[=dbSendQuery]{dbSendQuery()}}, \code{\link[=dbSendQueryArrow]{dbSendQueryArrow()}} or \code{\link[=dbSendStatement]{dbSendStatement()}} with a query or statement that contains placeholders, store the returned \linkS4class{DBIResult} object in a variable. Mixing placeholders (in particular, named and unnamed ones) is not recommended. It is good practice to register a call to \code{\link[=dbClearResult]{dbClearResult()}} via \code{\link[=on.exit]{on.exit()}} right after calling \code{dbSendQuery()} or \code{dbSendStatement()} (see the last enumeration item). Until \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}} have been called, the returned result set object has the following behavior: \itemize{ \item \code{\link[=dbFetch]{dbFetch()}} raises an error (for \code{dbSendQuery()} and \code{dbSendQueryArrow()}) \item \code{\link[=dbGetRowCount]{dbGetRowCount()}} returns zero (for \code{dbSendQuery()} and \code{dbSendQueryArrow()}) \item \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}} returns an integer \code{NA} (for \code{dbSendStatement()}) \item \code{\link[=dbIsValid]{dbIsValid()}} returns \code{TRUE} \item \code{\link[=dbHasCompleted]{dbHasCompleted()}} returns \code{FALSE} } \item Call \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}: \itemize{ \item For \code{\link[=dbBind]{dbBind()}}, the \code{params} argument must be a list where all elements have the same lengths and contain values supported by the backend. A \link{data.frame} is internally stored as such a list. \item For \code{\link[=dbBindArrow]{dbBindArrow()}}, the \code{params} argument must be a nanoarrow array stream, with one column per query parameter. } \item Retrieve the data or the number of affected rows from the \code{DBIResult} object. \itemize{ \item For queries issued by \code{dbSendQuery()} or \code{dbSendQueryArrow()}, call \code{\link[=dbFetch]{dbFetch()}}. \item For statements issued by \code{dbSendStatements()}, call \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}}. (Execution begins immediately after the \code{\link[=dbBind]{dbBind()}} call, the statement is processed entirely before the function returns.) } \item Repeat 2. and 3. as necessary. \item Close the result set via \code{\link[=dbClearResult]{dbClearResult()}}. } The elements of the \code{params} argument do not need to be scalars, vectors of arbitrary length (including length 0) are supported. For queries, calling \code{dbFetch()} binding such parameters returns concatenated results, equivalent to binding and fetching for each set of values and connecting via \code{\link[=rbind]{rbind()}}. For data manipulation statements, \code{dbGetRowsAffected()} returns the total number of rows affected if binding non-scalar parameters. \code{dbBind()} also accepts repeated calls on the same result set for both queries and data manipulation statements, even if no results are fetched between calls to \code{dbBind()}, for both queries and data manipulation statements. If the placeholders in the query are named, their order in the \code{params} argument is not important. At least the following data types are accepted on input (including \link{NA}): \itemize{ \item \link{integer} \item \link{numeric} \item \link{logical} for Boolean values \item \link{character} (also with special characters such as spaces, newlines, quotes, and backslashes) \item \link{factor} (bound as character, with warning) \item \link{Date} (also when stored internally as integer) \item \link{POSIXct} timestamps \item \link{POSIXlt} timestamps \item \link{difftime} values (also with units other than seconds and with the value stored as integer) \item lists of \link{raw} for blobs (with \code{NULL} entries for SQL NULL values) \item objects of type \link[blob:blob]{blob::blob} } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} # Data frame flow: con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "iris", iris) # Using the same query for different values iris_result <- dbSendQuery(con, "SELECT * FROM iris WHERE [Petal.Width] > ?") dbBind(iris_result, list(2.3)) dbFetch(iris_result) dbBind(iris_result, list(3)) dbFetch(iris_result) dbClearResult(iris_result) # Executing the same statement with different values at once iris_result <- dbSendStatement(con, "DELETE FROM iris WHERE [Species] = $species") dbBind(iris_result, list(species = c("setosa", "versicolor", "unknown"))) dbGetRowsAffected(iris_result) dbClearResult(iris_result) nrow(dbReadTable(con, "iris")) dbDisconnect(con) \dontshow{\}) # examplesIf} \dontshow{if (requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} # Arrow flow: con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "iris", iris) # Using the same query for different values iris_result <- dbSendQueryArrow(con, "SELECT * FROM iris WHERE [Petal.Width] > ?") dbBindArrow( iris_result, nanoarrow::as_nanoarrow_array_stream(data.frame(2.3, fix.empty.names = FALSE)) ) as.data.frame(dbFetchArrow(iris_result)) dbBindArrow( iris_result, nanoarrow::as_nanoarrow_array_stream(data.frame(3, fix.empty.names = FALSE)) ) as.data.frame(dbFetchArrow(iris_result)) dbClearResult(iris_result) # Executing the same statement with different values at once iris_result <- dbSendStatement(con, "DELETE FROM iris WHERE [Species] = $species") dbBindArrow(iris_result, nanoarrow::as_nanoarrow_array_stream(data.frame( species = c("setosa", "versicolor", "unknown") ))) dbGetRowsAffected(iris_result) dbClearResult(iris_result) nrow(dbReadTable(con, "iris")) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} Other DBIResultArrow generics: \code{\link{DBIResultArrow-class}}, \code{\link{dbClearResult}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsValid}()} Other data retrieval generics: \code{\link{dbClearResult}()}, \code{\link{dbFetch}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()} Other command execution generics: \code{\link{dbClearResult}()}, \code{\link{dbExecute}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbSendStatement}()} } \concept{DBIResult generics} \concept{DBIResultArrow generics} \concept{command execution generics} \concept{data retrieval generics} DBI/man/dbGetConnectArgs.Rd0000644000176200001440000000252514602466070015077 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbGetConnectArgs.R \name{dbGetConnectArgs} \alias{dbGetConnectArgs} \title{Get connection arguments} \usage{ dbGetConnectArgs(drv, eval = TRUE, ...) } \arguments{ \item{drv}{A object inheriting from \linkS4class{DBIConnector}.} \item{eval}{Set to \code{FALSE} to return the functions that generate the argument instead of evaluating them.} \item{...}{Other arguments passed on to methods. Not otherwise used.} } \description{ Returns the arguments stored in a \linkS4class{DBIConnector} object for inspection, optionally evaluating them. This function is called by \code{\link[=dbConnect]{dbConnect()}} and usually does not need to be called directly. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbGetConnectArgs")} } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} cnr <- new("DBIConnector", .drv = RSQLite::SQLite(), .conn_args = list(dbname = ":memory:", password = function() "supersecret") ) dbGetConnectArgs(cnr) dbGetConnectArgs(cnr, eval = FALSE) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnector generics: \code{\link{DBIConnector-class}}, \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbIsReadOnly}()} } \concept{DBIConnector generics} DBI/man/DBIConnection-class.Rd0000644000176200001440000000371014627140170015436 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/03-DBIConnection.R \docType{class} \name{DBIConnection-class} \alias{DBIConnection-class} \title{DBIConnection class} \description{ This virtual class encapsulates the connection to a DBMS, and it provides access to dynamic queries, result sets, DBMS session management (transactions), etc. } \section{Implementation note}{ Individual drivers are free to implement single or multiple simultaneous connections. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") con dbDisconnect(con) \dontrun{ con <- dbConnect(RPostgreSQL::PostgreSQL(), "username", "password") con dbDisconnect(con) } \dontshow{\}) # examplesIf} } \seealso{ Other DBI classes: \code{\link{DBIConnector-class}}, \code{\link{DBIDriver-class}}, \code{\link{DBIObject-class}}, \code{\link{DBIResult-class}}, \code{\link{DBIResultArrow-class}} Other DBIConnection generics: \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBI classes} \concept{DBIConnection generics} DBI/man/dbFetch.Rd0000644000176200001440000002027614614477037013275 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbFetch.R, R/fetch.R \name{dbFetch} \alias{dbFetch} \alias{fetch} \title{Fetch records from a previously executed query} \usage{ dbFetch(res, n = -1, ...) fetch(res, n = -1, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResult}, created by \code{\link[=dbSendQuery]{dbSendQuery()}}.} \item{n}{maximum number of records to retrieve per fetch. Use \code{n = -1} or \code{n = Inf} to retrieve all pending records. Some implementations may recognize other special values.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbFetch()} always returns a \link{data.frame} with as many rows as records were fetched and as many columns as fields in the result set, even if the result is a single value or has one or zero rows. Passing \code{n = NA} is supported and returns an arbitrary number of rows (at least one) as specified by the driver, but at most the remaining rows in the result set. } \description{ Fetch the next \code{n} elements (rows) from the result set and return them as a data.frame. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbFetch")} } \details{ \code{fetch()} is provided for compatibility with older DBI clients - for all new code you are strongly encouraged to use \code{dbFetch()}. The default implementation for \code{dbFetch()} calls \code{fetch()} so that it is compatible with existing code. Modern backends should implement for \code{dbFetch()} only. } \section{The data retrieval flow}{ This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}, is implemented by \code{\link[=dbGetQuery]{dbGetQuery()}}, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendQuery]{dbSendQuery()}} to create a result set object of class \linkS4class{DBIResult}. \item Optionally, bind query parameters with \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Optionally, use \code{\link[=dbColumnInfo]{dbColumnInfo()}} to retrieve the structure of the result set without retrieving actual data. \item Use \code{\link[=dbFetch]{dbFetch()}} to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. \item Use \code{\link[=dbHasCompleted]{dbHasCompleted()}} to tell when you're done. This method returns \code{TRUE} if no more rows are available for fetching. \item Repeat the last four steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ An attempt to fetch from a closed result set raises an error. If the \code{n} argument is not an atomic whole number greater or equal to -1 or Inf, an error is raised, but a subsequent call to \code{dbFetch()} with proper \code{n} argument succeeds. Calling \code{dbFetch()} on a result set from a data manipulation query created by \code{\link[=dbSendStatement]{dbSendStatement()}} can be fetched and return an empty data frame, with a warning. } \section{Specification}{ Fetching multi-row queries with one or more columns by default returns the entire result. Multi-row queries can also be fetched progressively by passing a whole number (\link{integer} or \link{numeric}) as the \code{n} argument. A value of \link{Inf} for the \code{n} argument is supported and also returns the full result. If more rows than available are fetched, the result is returned in full without warning. If fewer rows than requested are returned, further fetches will return a data frame with zero rows. If zero rows are fetched, the columns of the data frame are still fully typed. Fetching fewer rows than available is permitted, no warning is issued when clearing the result set. A column named \code{row_names} is treated like any other column. The column types of the returned data frame depend on the data returned: \itemize{ \item \link{integer} (or coercible to an integer) for integer values between -2^31 and 2^31 - 1, with \link{NA} for SQL \code{NULL} values \item \link{numeric} for numbers with a fractional component, with NA for SQL \code{NULL} values \item \link{logical} for Boolean values (some backends may return an integer); with NA for SQL \code{NULL} values \item \link{character} for text, with NA for SQL \code{NULL} values \item lists of \link{raw} for blobs with \link{NULL} entries for SQL NULL values \item coercible using \code{\link[=as.Date]{as.Date()}} for dates, with NA for SQL \code{NULL} values (also applies to the return value of the SQL function \code{current_date}) \item coercible using \code{\link[hms:hms]{hms::as_hms()}} for times, with NA for SQL \code{NULL} values (also applies to the return value of the SQL function \code{current_time}) \item coercible using \code{\link[=as.POSIXct]{as.POSIXct()}} for timestamps, with NA for SQL \code{NULL} values (also applies to the return value of the SQL function \code{current_timestamp}) } If dates and timestamps are supported by the backend, the following R types are used: \itemize{ \item \link{Date} for dates (also applies to the return value of the SQL function \code{current_date}) \item \link{POSIXct} for timestamps (also applies to the return value of the SQL function \code{current_timestamp}) } R has no built-in type with lossless support for the full range of 64-bit or larger integers. If 64-bit integers are returned from a query, the following rules apply: \itemize{ \item Values are returned in a container with support for the full range of valid 64-bit values (such as the \code{integer64} class of the \pkg{bit64} package) \item Coercion to numeric always returns a number that is as close as possible to the true value \item Loss of precision when converting to numeric gives a warning \item Conversion to character always returns a lossless decimal representation of the data } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) # Fetch all results rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") dbFetch(rs) dbClearResult(rs) # Fetch in chunks rs <- dbSendQuery(con, "SELECT * FROM mtcars") while (!dbHasCompleted(rs)) { chunk <- dbFetch(rs, 10) print(nrow(chunk)) } dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Close the result set with \code{\link[=dbClearResult]{dbClearResult()}} as soon as you finish retrieving the records you want. Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} Other data retrieval generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()} } \concept{DBIResult generics} \concept{data retrieval generics} DBI/man/dbSendStatement.Rd0000644000176200001440000002031614602466070015005 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbSendStatement.R \name{dbSendStatement} \alias{dbSendStatement} \title{Execute a data manipulation statement on a given database connection} \usage{ dbSendStatement(conn, statement, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{statement}{a character string containing SQL.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbSendStatement()} returns an S4 object that inherits from \linkS4class{DBIResult}. The result set can be used with \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}} to determine the number of rows affected by the query. Once you have finished using a result, make sure to clear it with \code{\link[=dbClearResult]{dbClearResult()}}. } \description{ The \code{dbSendStatement()} method only submits and synchronously executes the SQL data manipulation statement (e.g., \code{UPDATE}, \code{DELETE}, \verb{INSERT INTO}, \verb{DROP TABLE}, ...) to the database engine. To query the number of affected rows, call \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}} on the returned result object. You must also call \code{\link[=dbClearResult]{dbClearResult()}} after that. For interactive use, you should almost always prefer \code{\link[=dbExecute]{dbExecute()}}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbSendStatement")} } \details{ \code{\link[=dbSendStatement]{dbSendStatement()}} comes with a default implementation that simply forwards to \code{\link[=dbSendQuery]{dbSendQuery()}}, to support backends that only implement the latter. } \section{The command execution flow}{ This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of \code{\link[=dbBindArrow]{dbBindArrow()}}, is implemented by \code{\link[=dbExecute]{dbExecute()}}, which should be sufficient for non-parameterized queries. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendStatement]{dbSendStatement()}} to create a result set object of class \linkS4class{DBIResult}. For some queries you need to pass \code{immediate = TRUE}. \item Optionally, bind query parameters with\code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Optionally, use \code{\link[=dbGetRowsAffected]{dbGetRowsAffected()}} to retrieve the number of rows affected by the query. \item Repeat the last two steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ An error is raised when issuing a statement over a closed or invalid connection, or if the statement is not a non-\code{NA} string. An error is also raised if the syntax of the query is invalid and all query parameters are given (by passing the \code{params} argument) or the \code{immediate} argument is set to \code{TRUE}. } \section{Additional arguments}{ The following arguments are not part of the \code{dbSendStatement()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{params} (default: \code{NULL}) \item \code{immediate} (default: \code{NULL}) } They must be provided as named arguments. See the "Specification" sections for details on their usage. } \section{Specification}{ No warnings occur under normal conditions. When done, the DBIResult object must be cleared with a call to \code{\link[=dbClearResult]{dbClearResult()}}. Failure to clear the result set leads to a warning when the connection is closed. If the backend supports only one open result set per connection, issuing a second query invalidates an already open result set and raises a warning. The newly opened result set is valid and must be cleared with \code{dbClearResult()}. The \code{param} argument allows passing query parameters, see \code{\link[=dbBind]{dbBind()}} for details. } \section{Specification for the \code{immediate} argument}{ The \code{immediate} argument supports distinguishing between "direct" and "prepared" APIs offered by many database drivers. Passing \code{immediate = TRUE} leads to immediate execution of the query or statement, via the "direct" API (if supported by the driver). The default \code{NULL} means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct \code{immediate} argument. Examples for possible behaviors: \enumerate{ \item DBI backend defaults to \code{immediate = TRUE} internally \enumerate{ \item A query without parameters is passed: query is executed \item A query with parameters is passed: \enumerate{ \item \code{params} not given: rejected immediately by the database because of a syntax error in the query, the backend tries \code{immediate = FALSE} (and gives a message) \item \code{params} given: query is executed using \code{immediate = FALSE} } } \item DBI backend defaults to \code{immediate = FALSE} internally \enumerate{ \item A query without parameters is passed: \enumerate{ \item simple query: query is executed \item "special" query (such as setting a config options): fails, the backend tries \code{immediate = TRUE} (and gives a message) } \item A query with parameters is passed: \enumerate{ \item \code{params} not given: waiting for parameters via \code{\link[=dbBind]{dbBind()}} \item \code{params} given: query is executed } } } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cars", head(cars, 3)) rs <- dbSendStatement( con, "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)" ) dbHasCompleted(rs) dbGetRowsAffected(rs) dbClearResult(rs) dbReadTable(con, "cars") # there are now 6 rows # Pass one set of values directly using the param argument: rs <- dbSendStatement( con, "INSERT INTO cars (speed, dist) VALUES (?, ?)", params = list(4L, 5L) ) dbClearResult(rs) # Pass multiple sets of values using dbBind(): rs <- dbSendStatement( con, "INSERT INTO cars (speed, dist) VALUES (?, ?)" ) dbBind(rs, list(5:6, 6:7)) dbBind(rs, list(7L, 8L)) dbClearResult(rs) dbReadTable(con, "cars") # there are now 10 rows dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ For queries: \code{\link[=dbSendQuery]{dbSendQuery()}} and \code{\link[=dbGetQuery]{dbGetQuery()}}. Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} Other command execution generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbExecute}()}, \code{\link{dbGetRowsAffected}()} } \concept{DBIConnection generics} \concept{command execution generics} DBI/man/dbCreateTableArrow.Rd0000644000176200001440000001233014602466070015412 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/22-dbCreateTableArrow.R \name{dbCreateTableArrow} \alias{dbCreateTableArrow} \title{Create a table in the database based on an Arrow object} \usage{ dbCreateTableArrow(conn, name, value, ..., temporary = FALSE) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{value}{An object for which a schema can be determined via \code{\link[nanoarrow:as_nanoarrow_schema]{nanoarrow::infer_nanoarrow_schema()}}.} \item{...}{Other parameters passed on to methods.} \item{temporary}{If \code{TRUE}, will generate a temporary table.} } \value{ \code{dbCreateTableArrow()} returns \code{TRUE}, invisibly. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} The default \code{dbCreateTableArrow()} method determines the R data types of the Arrow schema associated with the Arrow object, and calls \code{\link[=dbCreateTable]{dbCreateTable()}}. Backends that implement \code{\link[=dbAppendTableArrow]{dbAppendTableArrow()}} should typically also implement this generic. Use \code{\link[=dbCreateTable]{dbCreateTable()}} to create a table from the column types as defined in a data frame. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbCreateTableArrow")} } \section{Failure modes}{ If the table exists, an error is raised; the remote table remains unchanged. An error is raised when calling this method for a closed or invalid connection. An error is also raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. Invalid values for the \code{temporary} argument (non-scalars, unsupported data types, \code{NA}, incompatible values, duplicate names) also raise an error. } \section{Additional arguments}{ The following arguments are not part of the \code{dbCreateTableArrow()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{temporary} (default: \code{FALSE}) } They must be provided as named arguments. See the "Specification" and "Value" sections for details on their usage. } \section{Specification}{ The \code{name} argument is processed as follows, to support databases that allow non-syntactic names for their objects: \itemize{ \item If an unquoted table name as string: \code{dbCreateTableArrow()} will do the quoting, perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} \item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done } The \code{value} argument can be: \itemize{ \item a data frame, \item a nanoarrow array \item a nanoarrow array stream (which will still contain the data after the call) \item a nanoarrow schema } If the \code{temporary} argument is \code{TRUE}, the table is not available in a second connection and is gone after reconnecting. Not all backends support this argument. A regular, non-temporary table is visible in a second connection, in a pre-existing connection, and after reconnecting to the database. SQL keywords can be used freely in table names, column names, and data. Quotes, commas, and spaces can also be used for table names and column names, if the database supports non-syntactic identifiers. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") ptype <- data.frame(a = numeric()) dbCreateTableArrow(con, "df", nanoarrow::infer_nanoarrow_schema(ptype)) dbReadTable(con, "df") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/transactions.Rd0000644000176200001440000000766014602466070014440 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbBegin.R, R/dbCommit.R, R/dbRollback.R, % R/transactions.R \name{dbBegin} \alias{dbBegin} \alias{dbCommit} \alias{dbRollback} \alias{transactions} \title{Begin/commit/rollback SQL transactions} \usage{ dbBegin(conn, ...) dbCommit(conn, ...) dbRollback(conn, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbBegin()}, \code{dbCommit()} and \code{dbRollback()} return \code{TRUE}, invisibly. } \description{ A transaction encapsulates several SQL statements in an atomic unit. It is initiated with \code{dbBegin()} and either made persistent with \code{dbCommit()} or undone with \code{dbRollback()}. In any case, the DBMS guarantees that either all or none of the statements have a permanent effect. This helps ensuring consistency of write operations to multiple tables. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("transactions")} } \details{ Not all database engines implement transaction management, in which case these methods should not be implemented for the specific \linkS4class{DBIConnection} subclass. } \section{Failure modes}{ The implementations are expected to raise an error in case of failure, but this is not tested. In any way, all generics throw an error with a closed or invalid connection. In addition, a call to \code{dbCommit()} or \code{dbRollback()} without a prior call to \code{dbBegin()} raises an error. Nested transactions are not supported by DBI, an attempt to call \code{dbBegin()} twice yields an error. } \section{Specification}{ Actual support for transactions may vary between backends. A transaction is initiated by a call to \code{dbBegin()} and committed by a call to \code{dbCommit()}. Data written in a transaction must persist after the transaction is committed. For example, a record that is missing when the transaction is started but is created during the transaction must exist both during and after the transaction, and also in a new connection. A transaction can also be aborted with \code{dbRollback()}. All data written in such a transaction must be removed after the transaction is rolled back. For example, a record that is missing when the transaction is started but is created during the transaction must not exist anymore after the rollback. Disconnection from a connection with an open transaction effectively rolls back the transaction. All data written in such a transaction must be removed after the transaction is rolled back. The behavior is not specified if other arguments are passed to these functions. In particular, \pkg{RSQLite} issues named transactions with support for nesting if the \code{name} argument is set. The transaction isolation level is not specified by DBI. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cash", data.frame(amount = 100)) dbWriteTable(con, "account", data.frame(amount = 2000)) # All operations are carried out as logical unit: dbBegin(con) withdrawal <- 300 dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) dbCommit(con) dbReadTable(con, "cash") dbReadTable(con, "account") # Rolling back after detecting negative value on account: dbBegin(con) withdrawal <- 5000 dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) if (dbReadTable(con, "account")$amount >= 0) { dbCommit(con) } else { dbRollback(con) } dbReadTable(con, "cash") dbReadTable(con, "account") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Self-contained transactions: \code{\link[=dbWithTransaction]{dbWithTransaction()}} } DBI/man/dbUnquoteIdentifier.Rd0000644000176200001440000000733314602466070015676 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbUnquoteIdentifier.R \name{dbUnquoteIdentifier} \alias{dbUnquoteIdentifier} \title{Unquote identifiers} \usage{ dbUnquoteIdentifier(conn, x, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{x}{An \link{SQL} or \link{Id} object.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbUnquoteIdentifier()} returns a list of objects of the same length as the input. For an empty vector, this function returns a length-0 object. The names of the input argument are preserved in the output. If \code{x} is a value returned by \code{dbUnquoteIdentifier()}, calling \code{dbUnquoteIdentifier(..., dbQuoteIdentifier(..., x))} returns \code{list(x)}. If \code{x} is an object of class \link{Id}, calling \code{dbUnquoteIdentifier(..., x)} returns \code{list(x)}. (For backends it may be most convenient to return \link{Id} objects to achieve this behavior, but this is not required.) Plain character vectors can also be passed to \code{dbUnquoteIdentifier()}. } \description{ Call this method to convert a \link{SQL} object created by \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} back to a list of \link{Id} objects. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbUnquoteIdentifier")} } \section{Failure modes}{ An error is raised if a character vectors with a missing value is passed as the \code{x} argument. } \section{Specification}{ For any character vector of length one, quoting (with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}) then unquoting then quoting the first element is identical to just quoting. This is also true for strings that contain special characters such as a space, a dot, a comma, or quotes used to mark strings or identifiers, if the database supports this. Unquoting simple strings (consisting of only letters) wrapped with \code{\link[=SQL]{SQL()}} and then quoting via \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} gives the same result as just quoting the string. Similarly, unquoting expressions of the form \code{SQL("schema.table")} and then quoting gives the same result as quoting the identifier constructed by \code{Id("schema", "table")}. } \examples{ # Unquoting allows to understand the structure of a # possibly complex quoted identifier dbUnquoteIdentifier( ANSI(), SQL(c('"Catalog"."Schema"."Table"', '"Schema"."Table"', '"UnqualifiedTable"')) ) # The returned object is always a list, # also for Id objects dbUnquoteIdentifier(ANSI(), Id("Catalog", "Schema", "Table")) # Quoting and unquoting are inverses dbQuoteIdentifier( ANSI(), dbUnquoteIdentifier(ANSI(), SQL("UnqualifiedTable"))[[1]] ) dbQuoteIdentifier( ANSI(), dbUnquoteIdentifier(ANSI(), Id("Schema", "Table"))[[1]] ) } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbListConnections.Rd0000644000176200001440000000147714542245565015363 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbListConnections.R \name{dbListConnections} \alias{dbListConnections} \title{List currently open connections} \usage{ dbListConnections(drv, ...) } \arguments{ \item{drv}{A object inheriting from \linkS4class{DBIDriver}} \item{...}{Other arguments passed on to methods.} } \value{ a list } \description{ DEPRECATED, drivers are no longer required to implement this method. Keep track of the connections you opened if you require a list. } \seealso{ Other DBIDriver generics: \code{\link{DBIDriver-class}}, \code{\link{dbCanConnect}()}, \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbDriver}()}, \code{\link{dbGetInfo}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()} } \concept{DBIDriver generics} \keyword{internal} DBI/man/dbHasCompleted.Rd0000644000176200001440000001216114614477037014606 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbHasCompleted.R \name{dbHasCompleted} \alias{dbHasCompleted} \title{Completion status} \usage{ dbHasCompleted(res, ...) } \arguments{ \item{res}{An object inheriting from \linkS4class{DBIResult}.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbHasCompleted()} returns a logical scalar. For a query initiated by \code{\link[=dbSendQuery]{dbSendQuery()}} with non-empty result set, \code{dbHasCompleted()} returns \code{FALSE} initially and \code{TRUE} after calling \code{\link[=dbFetch]{dbFetch()}} without limit. For a query initiated by \code{\link[=dbSendStatement]{dbSendStatement()}}, \code{dbHasCompleted()} always returns \code{TRUE}. } \description{ This method returns if the operation has completed. A \code{SELECT} query is completed if all rows have been fetched. A data manipulation statement is always completed. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbHasCompleted")} } \section{The data retrieval flow}{ This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}, is implemented by \code{\link[=dbGetQuery]{dbGetQuery()}}, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by \code{\link[=dbConnect]{dbConnect()}}. See also \code{vignette("dbi-advanced")} for a walkthrough. \enumerate{ \item Use \code{\link[=dbSendQuery]{dbSendQuery()}} to create a result set object of class \linkS4class{DBIResult}. \item Optionally, bind query parameters with \code{\link[=dbBind]{dbBind()}} or \code{\link[=dbBindArrow]{dbBindArrow()}}. This is required only if the query contains placeholders such as \verb{?} or \verb{$1}, depending on the database backend. \item Optionally, use \code{\link[=dbColumnInfo]{dbColumnInfo()}} to retrieve the structure of the result set without retrieving actual data. \item Use \code{\link[=dbFetch]{dbFetch()}} to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. \item Use \code{\link[=dbHasCompleted]{dbHasCompleted()}} to tell when you're done. This method returns \code{TRUE} if no more rows are available for fetching. \item Repeat the last four steps as necessary. \item Use \code{\link[=dbClearResult]{dbClearResult()}} to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use \code{\link[=on.exit]{on.exit()}} or \code{\link[withr:defer]{withr::defer()}} to ensure that this step is always executed. } } \section{Failure modes}{ Attempting to query completion status for a result set cleared with \code{\link[=dbClearResult]{dbClearResult()}} gives an error. } \section{Specification}{ The completion status for a query is only guaranteed to be set to \code{FALSE} after attempting to fetch past the end of the entire result. Therefore, for a query with an empty result set, the initial return value is unspecified, but the result value is \code{TRUE} after trying to fetch only one row. Similarly, for a query with a result set of length n, the return value is unspecified after fetching n rows, but the result value is \code{TRUE} after trying to fetch only one more row. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendQuery(con, "SELECT * FROM mtcars") dbHasCompleted(rs) ret1 <- dbFetch(rs, 10) dbHasCompleted(rs) ret2 <- dbFetch(rs) dbHasCompleted(rs) dbClearResult(rs) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} Other DBIResultArrow generics: \code{\link{DBIResultArrow-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbIsValid}()} Other data retrieval generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetch}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()} } \concept{DBIResult generics} \concept{DBIResultArrow generics} \concept{data retrieval generics} DBI/man/dbGetDBIVersion.Rd0000644000176200001440000000045514350241735014634 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/deprecated.R \name{dbGetDBIVersion} \alias{dbGetDBIVersion} \title{Determine the current version of the package.} \usage{ dbGetDBIVersion() } \description{ Determine the current version of the package. } \keyword{internal} DBI/man/DBIConnector-class.Rd0000644000176200001440000000324014602466070015272 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/DBIConnector.R \docType{class} \name{DBIConnector-class} \alias{DBIConnector-class} \title{DBIConnector class} \description{ Wraps objects of the \linkS4class{DBIDriver} class to include connection options. The purpose of this class is to store both the driver and the connection options. A database connection can be established with a call to \code{\link[=dbConnect]{dbConnect()}}, passing only that object without additional arguments. } \details{ To prevent leakage of passwords and other credentials, this class supports delayed evaluation. All arguments can optionally be a function (callable without arguments). In such a case, the function is evaluated transparently when connecting in \code{\link[=dbGetConnectArgs]{dbGetConnectArgs()}}. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} # Create a connector: cnr <- new("DBIConnector", .drv = RSQLite::SQLite(), .conn_args = list(dbname = ":memory:") ) cnr # Establish a connection through this connector: con <- dbConnect(cnr) con # Access the database through this connection: dbGetQuery(con, "SELECT 1 AS a") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBI classes: \code{\link{DBIConnection-class}}, \code{\link{DBIDriver-class}}, \code{\link{DBIObject-class}}, \code{\link{DBIResult-class}}, \code{\link{DBIResultArrow-class}} Other DBIConnector generics: \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbGetConnectArgs}()}, \code{\link{dbIsReadOnly}()} } \concept{DBI classes} \concept{DBIConnector generics} DBI/man/dbQuoteString.Rd0000644000176200001440000000562514602466070014521 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbQuoteString.R \name{dbQuoteString} \alias{dbQuoteString} \title{Quote literal strings} \usage{ dbQuoteString(conn, x, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{x}{A character vector to quote as string.} \item{...}{Other arguments passed on to methods.} } \value{ \code{dbQuoteString()} returns an object that can be coerced to \link{character}, of the same length as the input. For an empty character vector this function returns a length-0 object. When passing the returned object again to \code{dbQuoteString()} as \code{x} argument, it is returned unchanged. Passing objects of class \link{SQL} should also return them unchanged. (For backends it may be most convenient to return \link{SQL} objects to achieve this behavior, but this is not required.) } \description{ Call this method to generate a string that is suitable for use in a query as a string literal, to make sure that you generate valid SQL and protect against SQL injection attacks. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbQuoteString")} } \section{Failure modes}{ Passing a numeric, integer, logical, or raw vector, or a list for the \code{x} argument raises an error. } \section{Specification}{ The returned expression can be used in a \verb{SELECT ...} query, and for any scalar character \code{x} the value of \code{dbGetQuery(paste0("SELECT ", dbQuoteString(x)))[[1]]} must be identical to \code{x}, even if \code{x} contains spaces, tabs, quotes (single or double), backticks, or newlines (in any combination) or is itself the result of a \code{dbQuoteString()} call coerced back to character (even repeatedly). If \code{x} is \code{NA}, the result must merely satisfy \code{\link[=is.na]{is.na()}}. The strings \code{"NA"} or \code{"NULL"} are not treated specially. \code{NA} should be translated to an unquoted SQL \code{NULL}, so that the query \verb{SELECT * FROM (SELECT 1) a WHERE ... IS NULL} returns one row. } \examples{ # Quoting ensures that arbitrary input is safe for use in a query name <- "Robert'); DROP TABLE Students;--" dbQuoteString(ANSI(), name) # NAs become NULL dbQuoteString(ANSI(), c("x", NA)) # SQL vectors are always passed through as is var_name <- SQL("select") var_name dbQuoteString(ANSI(), var_name) # This mechanism is used to prevent double escaping dbQuoteString(ANSI(), dbQuoteString(ANSI(), name)) } \seealso{ Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()} } \concept{DBIResult generics} DBI/man/dbWriteTable.Rd0000644000176200001440000002140614602466070014272 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/13-dbWriteTable.R \name{dbWriteTable} \alias{dbWriteTable} \title{Copy data frames to database tables} \usage{ dbWriteTable(conn, name, value, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{value}{A \link{data.frame} (or coercible to data.frame).} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbWriteTable()} returns \code{TRUE}, invisibly. } \description{ Writes, overwrites or appends a data frame to a database table, optionally converting row names to a column and specifying SQL data types for fields. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbWriteTable")} } \details{ This function expects a data frame. Use \code{\link[=dbWriteTableArrow]{dbWriteTableArrow()}} to write an Arrow object. This function is useful if you want to create and load a table at the same time. Use \code{\link[=dbAppendTable]{dbAppendTable()}} or \code{\link[=dbAppendTableArrow]{dbAppendTableArrow()}} for appending data to an existing table, \code{\link[=dbCreateTable]{dbCreateTable()}} or \code{\link[=dbCreateTableArrow]{dbCreateTableArrow()}} for creating a table, and \code{\link[=dbExistsTable]{dbExistsTable()}} and \code{\link[=dbRemoveTable]{dbRemoveTable()}} for overwriting tables. DBI only standardizes writing data frames with \code{dbWriteTable()}. Some backends might implement methods that can consume CSV files or other data formats. For details, see the documentation for the individual methods. } \section{Failure modes}{ If the table exists, and both \code{append} and \code{overwrite} arguments are unset, or \code{append = TRUE} and the data frame with the new data has different column names, an error is raised; the remote table remains unchanged. An error is raised when calling this method for a closed or invalid connection. An error is also raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. Invalid values for the additional arguments \code{row.names}, \code{overwrite}, \code{append}, \code{field.types}, and \code{temporary} (non-scalars, unsupported data types, \code{NA}, incompatible values, duplicate or missing names, incompatible columns) also raise an error. } \section{Additional arguments}{ The following arguments are not part of the \code{dbWriteTable()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{row.names} (default: \code{FALSE}) \item \code{overwrite} (default: \code{FALSE}) \item \code{append} (default: \code{FALSE}) \item \code{field.types} (default: \code{NULL}) \item \code{temporary} (default: \code{FALSE}) } They must be provided as named arguments. See the "Specification" and "Value" sections for details on their usage. } \section{Specification}{ The \code{name} argument is processed as follows, to support databases that allow non-syntactic names for their objects: \itemize{ \item If an unquoted table name as string: \code{dbWriteTable()} will do the quoting, perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} \item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done } The \code{value} argument must be a data frame with a subset of the columns of the existing table if \code{append = TRUE}. The order of the columns does not matter with \code{append = TRUE}. If the \code{overwrite} argument is \code{TRUE}, an existing table of the same name will be overwritten. This argument doesn't change behavior if the table does not exist yet. If the \code{append} argument is \code{TRUE}, the rows in an existing table are preserved, and the new data are appended. If the table doesn't exist yet, it is created. If the \code{temporary} argument is \code{TRUE}, the table is not available in a second connection and is gone after reconnecting. Not all backends support this argument. A regular, non-temporary table is visible in a second connection, in a pre-existing connection, and after reconnecting to the database. SQL keywords can be used freely in table names, column names, and data. Quotes, commas, spaces, and other special characters such as newlines and tabs, can also be used in the data, and, if the database supports non-syntactic identifiers, also for table names and column names. The following data types must be supported at least, and be read identically with \code{\link[=dbReadTable]{dbReadTable()}}: \itemize{ \item integer \item numeric (the behavior for \code{Inf} and \code{NaN} is not specified) \item logical \item \code{NA} as NULL \item 64-bit values (using \code{"bigint"} as field type); the result can be \itemize{ \item converted to a numeric, which may lose precision, \item converted a character vector, which gives the full decimal representation \item written to another table and read again unchanged } \item character (in both UTF-8 and native encodings), supporting empty strings before and after a non-empty string \item factor (returned as character) \item list of raw (if supported by the database) \item objects of type \link[blob:blob]{blob::blob} (if supported by the database) \item date (if supported by the database; returned as \code{Date}), also for dates prior to 1970 or 1900 or after 2038 \item time (if supported by the database; returned as objects that inherit from \code{difftime}) \item timestamp (if supported by the database; returned as \code{POSIXct} respecting the time zone but not necessarily preserving the input time zone), also for timestamps prior to 1970 or 1900 or after 2038 respecting the time zone but not necessarily preserving the input time zone) } Mixing column types in the same table is supported. The \code{field.types} argument must be a named character vector with at most one entry for each column. It indicates the SQL data type to be used for a new column. If a column is missed from \code{field.types}, the type is inferred from the input data with \code{\link[=dbDataType]{dbDataType()}}. The interpretation of \link{rownames} depends on the \code{row.names} argument, see \code{\link[=sqlRownamesToColumn]{sqlRownamesToColumn()}} for details: \itemize{ \item If \code{FALSE} or \code{NULL}, row names are ignored. \item If \code{TRUE}, row names are converted to a column named "row_names", even if the input data frame only has natural row names from 1 to \code{nrow(...)}. \item If \code{NA}, a column named "row_names" is created if the data has custom row names, no extra column is created in the case of natural row names. \item If a string, this specifies the name of the column in the remote table that contains the row names, even if the input data frame only has natural row names. } The default is \code{row.names = FALSE}. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars[1:5, ]) dbReadTable(con, "mtcars") dbWriteTable(con, "mtcars", mtcars[6:10, ], append = TRUE) dbReadTable(con, "mtcars") dbWriteTable(con, "mtcars", mtcars[1:10, ], overwrite = TRUE) dbReadTable(con, "mtcars") # No row names dbWriteTable(con, "mtcars", mtcars[1:10, ], overwrite = TRUE, row.names = FALSE) dbReadTable(con, "mtcars") \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTableArrow}()} } \concept{DBIConnection generics} DBI/man/dbWriteTableArrow.Rd0000644000176200001440000001660414602466070015311 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/23-dbWriteTableArrow.R \name{dbWriteTableArrow} \alias{dbWriteTableArrow} \title{Copy Arrow objects to database tables} \usage{ dbWriteTableArrow(conn, name, value, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{name}{The table name, passed on to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}. Options are: \itemize{ \item a character string with the unquoted DBMS table name, e.g. \code{"table_name"}, \item a call to \code{\link[=Id]{Id()}} with components to the fully qualified table name, e.g. \code{Id(schema = "my_schema", table = "table_name")} \item a call to \code{\link[=SQL]{SQL()}} with the quoted and fully qualified table name given verbatim, e.g. \code{SQL('"my_schema"."table_name"')} }} \item{value}{An nanoarray stream, or an object coercible to a nanoarray stream with \code{\link[nanoarrow:as_nanoarrow_array_stream]{nanoarrow::as_nanoarrow_array_stream()}}.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbWriteTableArrow()} returns \code{TRUE}, invisibly. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} Writes, overwrites or appends an Arrow object to a database table. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbWriteTableArrow")} } \details{ This function expects an Arrow object. Convert a data frame to an Arrow object with \code{\link[nanoarrow:as_nanoarrow_array_stream]{nanoarrow::as_nanoarrow_array_stream()}} or use \code{\link[=dbWriteTable]{dbWriteTable()}} to write a data frame. This function is useful if you want to create and load a table at the same time. Use \code{\link[=dbAppendTableArrow]{dbAppendTableArrow()}} for appending data to an existing table, \code{\link[=dbCreateTableArrow]{dbCreateTableArrow()}} for creating a table and specifying field types, and \code{\link[=dbRemoveTable]{dbRemoveTable()}} for overwriting tables. } \section{Failure modes}{ If the table exists, and both \code{append} and \code{overwrite} arguments are unset, or \code{append = TRUE} and the data frame with the new data has different column names, an error is raised; the remote table remains unchanged. An error is raised when calling this method for a closed or invalid connection. An error is also raised if \code{name} cannot be processed with \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}} or if this results in a non-scalar. Invalid values for the additional arguments \code{overwrite}, \code{append}, and \code{temporary} (non-scalars, unsupported data types, \code{NA}, incompatible values, incompatible columns) also raise an error. } \section{Additional arguments}{ The following arguments are not part of the \code{dbWriteTableArrow()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{overwrite} (default: \code{FALSE}) \item \code{append} (default: \code{FALSE}) \item \code{temporary} (default: \code{FALSE}) } They must be provided as named arguments. See the "Specification" and "Value" sections for details on their usage. } \section{Specification}{ The \code{name} argument is processed as follows, to support databases that allow non-syntactic names for their objects: \itemize{ \item If an unquoted table name as string: \code{dbWriteTableArrow()} will do the quoting, perhaps by calling \code{dbQuoteIdentifier(conn, x = name)} \item If the result of a call to \code{\link[=dbQuoteIdentifier]{dbQuoteIdentifier()}}: no more quoting is done } The \code{value} argument must be a data frame with a subset of the columns of the existing table if \code{append = TRUE}. The order of the columns does not matter with \code{append = TRUE}. If the \code{overwrite} argument is \code{TRUE}, an existing table of the same name will be overwritten. This argument doesn't change behavior if the table does not exist yet. If the \code{append} argument is \code{TRUE}, the rows in an existing table are preserved, and the new data are appended. If the table doesn't exist yet, it is created. If the \code{temporary} argument is \code{TRUE}, the table is not available in a second connection and is gone after reconnecting. Not all backends support this argument. A regular, non-temporary table is visible in a second connection, in a pre-existing connection, and after reconnecting to the database. SQL keywords can be used freely in table names, column names, and data. Quotes, commas, spaces, and other special characters such as newlines and tabs, can also be used in the data, and, if the database supports non-syntactic identifiers, also for table names and column names. The following data types must be supported at least, and be read identically with \code{\link[=dbReadTable]{dbReadTable()}}: \itemize{ \item integer \item numeric (the behavior for \code{Inf} and \code{NaN} is not specified) \item logical \item \code{NA} as NULL \item 64-bit values (using \code{"bigint"} as field type); the result can be \itemize{ \item converted to a numeric, which may lose precision, \item converted a character vector, which gives the full decimal representation \item written to another table and read again unchanged } \item character (in both UTF-8 and native encodings), supporting empty strings before and after a non-empty string \item factor (possibly returned as character) \item objects of type \link[blob:blob]{blob::blob} (if supported by the database) \item date (if supported by the database; returned as \code{Date}), also for dates prior to 1970 or 1900 or after 2038 \item time (if supported by the database; returned as objects that inherit from \code{difftime}) \item timestamp (if supported by the database; returned as \code{POSIXct} respecting the time zone but not necessarily preserving the input time zone), also for timestamps prior to 1970 or 1900 or after 2038 respecting the time zone but not necessarily preserving the input time zone) } Mixing column types in the same table is supported. } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTableArrow(con, "mtcars", nanoarrow::as_nanoarrow_array_stream(mtcars[1:5, ])) dbReadTable(con, "mtcars") dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()} } \concept{DBIConnection generics} DBI/man/dbGetQuery.Rd0000644000176200001440000001611214602466070013773 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbGetQuery.R \name{dbGetQuery} \alias{dbGetQuery} \title{Retrieve results from a query} \usage{ dbGetQuery(conn, statement, ...) } \arguments{ \item{conn}{A \linkS4class{DBIConnection} object, as returned by \code{\link[=dbConnect]{dbConnect()}}.} \item{statement}{a character string containing SQL.} \item{...}{Other parameters passed on to methods.} } \value{ \code{dbGetQuery()} always returns a \link{data.frame}, with as many rows as records were fetched and as many columns as fields in the result set, even if the result is a single value or has one or zero rows. } \description{ Returns the result of a query as a data frame. \code{dbGetQuery()} comes with a default implementation (which should work with most backends) that calls \code{\link[=dbSendQuery]{dbSendQuery()}}, then \code{\link[=dbFetch]{dbFetch()}}, ensuring that the result is always freed by \code{\link[=dbClearResult]{dbClearResult()}}. For retrieving chunked/paged results or for passing query parameters, see \code{\link[=dbSendQuery]{dbSendQuery()}}, in particular the "The data retrieval flow" section. For retrieving results as an Arrow object, see \code{\link[=dbGetQueryArrow]{dbGetQueryArrow()}}. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbGetQuery")} } \details{ This method is for \code{SELECT} queries only (incl. other SQL statements that return a \code{SELECT}-alike result, e.g., execution of a stored procedure or data manipulation queries like \verb{INSERT INTO ... RETURNING ...}). To execute a stored procedure that does not return a result set, use \code{\link[=dbExecute]{dbExecute()}}. Some backends may support data manipulation statements through this method for compatibility reasons. However, callers are strongly advised to use \code{\link[=dbExecute]{dbExecute()}} for data manipulation statements. } \section{Implementation notes}{ Subclasses should override this method only if they provide some sort of performance optimization. } \section{Failure modes}{ An error is raised when issuing a query over a closed or invalid connection, if the syntax of the query is invalid, or if the query is not a non-\code{NA} string. If the \code{n} argument is not an atomic whole number greater or equal to -1 or Inf, an error is raised, but a subsequent call to \code{dbGetQuery()} with proper \code{n} argument succeeds. } \section{Additional arguments}{ The following arguments are not part of the \code{dbGetQuery()} generic (to improve compatibility across backends) but are part of the DBI specification: \itemize{ \item \code{n} (default: -1) \item \code{params} (default: \code{NULL}) \item \code{immediate} (default: \code{NULL}) } They must be provided as named arguments. See the "Specification" and "Value" sections for details on their usage. } \section{Specification}{ A column named \code{row_names} is treated like any other column. The \code{n} argument specifies the number of rows to be fetched. If omitted, fetching multi-row queries with one or more columns returns the entire result. A value of \link{Inf} for the \code{n} argument is supported and also returns the full result. If more rows than available are fetched (by passing a too large value for \code{n}), the result is returned in full without warning. If zero rows are requested, the columns of the data frame are still fully typed. Fetching fewer rows than available is permitted, no warning is issued. The \code{param} argument allows passing query parameters, see \code{\link[=dbBind]{dbBind()}} for details. } \section{Specification for the \code{immediate} argument}{ The \code{immediate} argument supports distinguishing between "direct" and "prepared" APIs offered by many database drivers. Passing \code{immediate = TRUE} leads to immediate execution of the query or statement, via the "direct" API (if supported by the driver). The default \code{NULL} means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct \code{immediate} argument. Examples for possible behaviors: \enumerate{ \item DBI backend defaults to \code{immediate = TRUE} internally \enumerate{ \item A query without parameters is passed: query is executed \item A query with parameters is passed: \enumerate{ \item \code{params} not given: rejected immediately by the database because of a syntax error in the query, the backend tries \code{immediate = FALSE} (and gives a message) \item \code{params} given: query is executed using \code{immediate = FALSE} } } \item DBI backend defaults to \code{immediate = FALSE} internally \enumerate{ \item A query without parameters is passed: \enumerate{ \item simple query: query is executed \item "special" query (such as setting a config options): fails, the backend tries \code{immediate = TRUE} (and gives a message) } \item A query with parameters is passed: \enumerate{ \item \code{params} not given: waiting for parameters via \code{\link[=dbBind]{dbBind()}} \item \code{params} given: query is executed } } } } \examples{ \dontshow{if (requireNamespace("RSQLite", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) dbGetQuery(con, "SELECT * FROM mtcars") dbGetQuery(con, "SELECT * FROM mtcars", n = 6) # Pass values using the param argument: # (This query runs eight times, once for each different # parameter. The resulting rows are combined into a single # data frame.) dbGetQuery( con, "SELECT COUNT(*) FROM mtcars WHERE cyl = ?", params = list(1:8) ) dbDisconnect(con) \dontshow{\}) # examplesIf} } \seealso{ For updates: \code{\link[=dbSendStatement]{dbSendStatement()}} and \code{\link[=dbExecute]{dbExecute()}}. Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} Other data retrieval generics: \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbFetch}()}, \code{\link{dbFetchArrow}()}, \code{\link{dbFetchArrowChunk}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()} } \concept{DBIConnection generics} \concept{data retrieval generics} DBI/man/DBIDriver-class.Rd0000644000176200001440000000177114602466070014602 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/02-DBIDriver.R \docType{class} \name{DBIDriver-class} \alias{DBIDriver-class} \title{DBIDriver class} \description{ Base class for all DBMS drivers (e.g., RSQLite, MySQL, PostgreSQL). The virtual class \code{DBIDriver} defines the operations for creating connections and defining data type mappings. Actual driver classes, for instance \code{RPostgres}, \code{RMariaDB}, etc. implement these operations in a DBMS-specific manner. } \seealso{ Other DBI classes: \code{\link{DBIConnection-class}}, \code{\link{DBIConnector-class}}, \code{\link{DBIObject-class}}, \code{\link{DBIResult-class}}, \code{\link{DBIResultArrow-class}} Other DBIDriver generics: \code{\link{dbCanConnect}()}, \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbDriver}()}, \code{\link{dbGetInfo}()}, \code{\link{dbIsReadOnly}()}, \code{\link{dbIsValid}()}, \code{\link{dbListConnections}()} } \concept{DBI classes} \concept{DBIDriver generics} DBI/man/dbIsReadOnly.Rd0000644000176200001440000000464314602466070014245 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/dbIsReadOnly.R \name{dbIsReadOnly} \alias{dbIsReadOnly} \title{Is this DBMS object read only?} \usage{ dbIsReadOnly(dbObj, ...) } \arguments{ \item{dbObj}{An object inheriting from \linkS4class{DBIObject}, i.e. \linkS4class{DBIDriver}, \linkS4class{DBIConnection}, or a \linkS4class{DBIResult}} \item{...}{Other arguments to methods.} } \description{ This generic tests whether a database object is read only. \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbIsReadOnly")} } \examples{ dbIsReadOnly(ANSI()) } \seealso{ Other DBIDriver generics: \code{\link{DBIDriver-class}}, \code{\link{dbCanConnect}()}, \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbDriver}()}, \code{\link{dbGetInfo}()}, \code{\link{dbIsValid}()}, \code{\link{dbListConnections}()} Other DBIConnection generics: \code{\link{DBIConnection-class}}, \code{\link{dbAppendTable}()}, \code{\link{dbAppendTableArrow}()}, \code{\link{dbCreateTable}()}, \code{\link{dbCreateTableArrow}()}, \code{\link{dbDataType}()}, \code{\link{dbDisconnect}()}, \code{\link{dbExecute}()}, \code{\link{dbExistsTable}()}, \code{\link{dbGetException}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetQuery}()}, \code{\link{dbGetQueryArrow}()}, \code{\link{dbIsValid}()}, \code{\link{dbListFields}()}, \code{\link{dbListObjects}()}, \code{\link{dbListResults}()}, \code{\link{dbListTables}()}, \code{\link{dbQuoteIdentifier}()}, \code{\link{dbReadTable}()}, \code{\link{dbReadTableArrow}()}, \code{\link{dbRemoveTable}()}, \code{\link{dbSendQuery}()}, \code{\link{dbSendQueryArrow}()}, \code{\link{dbSendStatement}()}, \code{\link{dbUnquoteIdentifier}()}, \code{\link{dbWriteTable}()}, \code{\link{dbWriteTableArrow}()} Other DBIResult generics: \code{\link{DBIResult-class}}, \code{\link{dbBind}()}, \code{\link{dbClearResult}()}, \code{\link{dbColumnInfo}()}, \code{\link{dbFetch}()}, \code{\link{dbGetInfo}()}, \code{\link{dbGetRowCount}()}, \code{\link{dbGetRowsAffected}()}, \code{\link{dbGetStatement}()}, \code{\link{dbHasCompleted}()}, \code{\link{dbIsValid}()}, \code{\link{dbQuoteLiteral}()}, \code{\link{dbQuoteString}()} Other DBIConnector generics: \code{\link{DBIConnector-class}}, \code{\link{dbConnect}()}, \code{\link{dbDataType}()}, \code{\link{dbGetConnectArgs}()} } \concept{DBIConnection generics} \concept{DBIConnector generics} \concept{DBIDriver generics} \concept{DBIResult generics} DBI/DESCRIPTION0000644000176200001440000000347214627164412012373 0ustar liggesusersPackage: DBI Title: R Database Interface Version: 1.2.3 Date: 2024-06-02 Authors@R: c( person("R Special Interest Group on Databases (R-SIG-DB)", role = "aut"), person("Hadley", "Wickham", role = "aut"), person("Kirill", "Müller", , "kirill@cynkra.com", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-1416-3412")), person("R Consortium", role = "fnd") ) Description: A database interface definition for communication between R and relational database management systems. All classes in this package are virtual and need to be extended by the various R/DBMS implementations. License: LGPL (>= 2.1) URL: https://dbi.r-dbi.org, https://github.com/r-dbi/DBI BugReports: https://github.com/r-dbi/DBI/issues Depends: methods, R (>= 3.0.0) Suggests: arrow, blob, covr, DBItest, dbplyr, downlit, dplyr, glue, hms, knitr, magrittr, nanoarrow (>= 0.3.0.1), RMariaDB, rmarkdown, rprojroot, RSQLite (>= 1.1-2), testthat (>= 3.0.0), vctrs, xml2 VignetteBuilder: knitr Config/autostyle/scope: line_breaks Config/autostyle/strict: false Config/Needs/check: r-dbi/DBItest Encoding: UTF-8 RoxygenNote: 7.3.1 Config/Needs/website: r-dbi/DBItest, r-dbi/dbitemplate, adbi, AzureKusto, bigrquery, DatabaseConnector, dittodb, duckdb, implyr, lazysf, odbc, pool, RAthena, IMSMWU/RClickhouse, RH2, RJDBC, RMariaDB, RMySQL, RPostgres, RPostgreSQL, RPresto, RSQLite, sergeant, sparklyr, withr Config/testthat/edition: 3 NeedsCompilation: no Packaged: 2024-06-02 20:26:05 UTC; kirill Author: R Special Interest Group on Databases (R-SIG-DB) [aut], Hadley Wickham [aut], Kirill Müller [aut, cre] (), R Consortium [fnd] Maintainer: Kirill Müller Repository: CRAN Date/Publication: 2024-06-02 21:50:02 UTC DBI/build/0000755000176200001440000000000014627152535011761 5ustar liggesusersDBI/build/vignette.rds0000644000176200001440000000067614627152535014331 0ustar liggesusersSR0PœPtd8(3^CJ6$QIܔ^6ٷo!H=H-Ϡ[WWIf2N=E-p) HrUK ESG34|gginE c*i^ً#: 3EߘT xL-wDl.X$riSRN2La0Ɛ"Sfs>ek Ζ`[coMk8 J::K'[=VHJVÔRzҳ.,tN.尹FbM9Ghnt ݐ?^miƔu6-XOR7DF4{b9֭$l]#}^)U.#v"a,=Z?b>^3VDBI/build/DBI.pdf0000644000176200001440000153177314627152524013071 0ustar liggesusers%PDF-1.5 % 2 0 obj << /Type /ObjStm /N 100 /First 825 /Length 1431 /Filter /FlateDecode >> stream xڵXMoJW̲]4eJIܴV#Uv 1c 8;DR n—3sw>3i3kR0.pQLI#2 δGB0LHab2)Y`pQ,H02d&TLF (^3Jlhd 4 l\zC1xW AB0 ("g>/TP0!yqЇ@P)4*YH&q!~k }55\Ј{i5h]Cz`hqJyE Lr!!R5H ҅3g$F R#ʩTpEi|~GYRDXqAG+JTOH3i‘,E !ѐ#]ʗ|I!Ԁ#e*φRIȚ[E!' ::-!GG+A` 5@EkRԵ0 D}?".tѻw팽혽.lGl=W?d_8]C~/'R?;1 h7ۼNHtB7Oܸ?oԽrTEkS}u"Ϫ"ɖ'7MaنI3;ǡ8M8|›u`Żv^N{+,qp5pz(lĢ!>I~~ YK:U{Rn(+f'cjh~+_>sr)^7_|M endstream endobj 245 0 obj << /Length 954 /Filter /FlateDecode >> stream xڕVr8}W%tfw޴tNqʠ`m@x$6'sѕ{pO iU$ QD@v@A .v0 8‘B6%3lǴSq% W7]J|R #(I,θҢSBB r\VdlSURsI5!שs&'ОmWlP\1(n7KFoTUYRߎMJN@+5ZdQhS2i][riw} /5.҂iuC4{[pH}xr;L݋8'#2e9v6է&Dy(4ZX O,)4^TWtMeu` h| =e_pD 7,N7 nBHNqv{v()I {R[Ì^{N1 Xp廞ڸgdZeBNZl_x0C$j'kT!rwwۋ8A endstream endobj 276 0 obj << /Length 949 /Filter /FlateDecode >> stream xYKo8W(̇{#ɦbh+W~IKDv=0 ڞ7Ï#XK X7|0+ނx0Ț79C0@jd@H {A7Y"`<X!Y6M8Q^{qD,#]`g#O䙐\A~,xJeiuarG.٩a)wU?p5wrT BdSinȆdB,7^+RHƩdJVcA"5*@a*wBٲb:.`r H^(LJ.:WHd}ĔKږ܊Nrt6Fr 9?_I%D7óPI厖_>'.d{bc}1ɮfLMʎT`#{h!c_d1RB{@2UH?)'Za~REkD;o{5 uTqP|C<*BV2u74Y%s(mq f ~ 9G_@ߢ/ϐ|@dh~f')ܫ^L^>,f"+|̙zVmd~XTi'rA&h?%#?y zJ5J 2|_> }]Z-*$UU^}0ܴM"Mӓ.x5X endstream endobj 340 0 obj << /Length 1269 /Filter /FlateDecode >> stream xMw8,a$cqOLiMGBg*dmG{%އdpvG"M 1 "#ozw0\7q/gהnF EmXW ^Sq%S)~ͰAH8#uu "U)w!Wua^Qճ~C␟<kUUOAz紭1cd/{YFAƉS~ެ>嬑i"`&c܈F.V5ԙxSKq!rePz?ЉyY2YY\;u˭·5d;*g{/pc~ /24G| 1zo? 85/&\gA/na="TjQ|cˠfX@}gfԥN lu&T);'`okqas2;tO|1e 1GO,߮FSY4 |jg6}5b'xSMʴ@cS(T76]O8~m-M cڒ5ԹE`'ۺcYʉr3ɾ{f%iێs,͊ܛ[N%mjx9m ZJsf$_ v-aϕ .{H┣ۮ)Jr`fv0L}Bfx!:mKr>Yooԣ z8"1?_. oݚEbyclu~%>nn+ajYJ.v 5o $by!BcVa;߀ޞǷ'l?y؛-w_bμP=?wbaAD1jM= ߺEu_]!"6 SQKs*t.f;{ pBi#k$$4B$&Y-\ m%TN7]SO0Y۷_{i^Vڬ\,VE6&ѡy0GL9dVՓ+7BjTLBP׮P5 0F.H[I m6!dS;}j>Qe65FgWwu#;=to[$Q@@]3WTfKsTozTg ]ߨrQE endstream endobj 393 0 obj << /Length 1802 /Filter /FlateDecode >> stream xڥXYo8~ϯ0 D]44[u )LȒ!Iw,)ʁ, r43ߌL'7:8:ǓdqO櫉O) Y$0QJ01r-|D=5uǦAD{X\SRɪH03O fC}rēyK󜙇3Xܯe6tVgZ{'X}Գ3#Iچ51aQx6Be3"+L e㳖7lbñyUmJ8hn 3F'Y4bG teH؛)Yb'ꍡ4ȹjm~:R 9m m}]}[*1r)u|c"B#iF0D>{FAt_("> ܑcH,e<0 IaE&>͵AZ [>7_V[꼇UuŴepY)2 -ICoasgO'{_Sq2p1N ޫu-YZ0^xk;al,I'5f7<W`Es@{\G#xX`7 qڪ eAo9=5{q?GRBs endstream endobj 203 0 obj << /Type /ObjStm /N 100 /First 887 /Length 2415 /Filter /FlateDecode >> stream xڽZQs~@Gqg˝u@IWSTH:q}=BǓ#"̃vw8e3GFdz>( }Rϊ"9 3H̸f]T,(CVqk"eA%($[J ƙVY~p :IYb <0a%Ġlk["̉Ps\/ Qn*$Y\d0*2OSh)G,O1Cv%13g q(?18Bzt@Y`&g#'Jf6 XNqa<.+[?Jf9 8ԋ_?&Bys_nO͠D ke\ߠŻG7p~^,_Yg>oODΗ~}r |TzT/md?ks5&$FuKrr2W{¢ DMY}Z_! ?Y_>w"-X%ySA"Knrwtم7w= a{Za s;^r)uA’gVb9|d)`ŧ-dvv'' vZv?ޜ߳/]ws]?ÅL=Wz~tW]w{gr%5E]l> ȩ_V9k=f_~<4j7;־~+Mjȧr ,)ΐ0Ou?W=-rJuo/=˽މߺwnH:CI""<."X"/._z9pq` "oA,;:;;KR5 K@#b 6HF \k~`g=!2GCOć!F֏#6wN ֶQgl+=D9Qo=Oz K}@8;8 if-*Wc0pI0G +!X4'9!ǐ#f*ʵ6Z=CY0ʥBRj1pҡP~[X ePIj-,N'‘ވ~Qݚ'eѡFQ`_Hn ӱJ{0M?.|塀v@*gv($^jޖޕ/}(=>>~D"yȳE-lg<["ysE+\A>co|{eh*ۧ#&@ ,ўaW#8U }J8(Ckwه@Fdh1؁;\ r9UR< S @&:$⪶8I'J0P{ c<T0>C0:zpJ"c{hy;b=j=SrBԡ} A(@f nOg49MnO l ʇ @!U&<}`+Dw; c;[ٚ~kz1w>hz"~0S[l+A3? }q)ME֩V~j?x?P=GwJ,"wB{"@VdLK:Mrs:¦9 +A3TvP/ ^g6 e8a~(Xr=Ʌ endstream endobj 425 0 obj << /Length 1502 /Filter /FlateDecode >> stream xڵXmo6_!(&1KR$%致M.(dY#uw|lJ"o-@'/w=w4 'TxӅG0F^(0sﳏn>^KnLƄw1~QΫo8؁aBAa)#nGDY/FbozIFL @/4Bb~ 4S% kU%e"ؿǡUy"]~aHVq'*w* ^, Gν0:*Rա(US/UǶtC%z(:N?a;tfV]u\9:: ކ Q@ffZzeeJq?D,d]S/f@G`!{\^_'cY?RO:f I&-Q D,. &4 |: rC%a L]'%88"!7YO0R P٪%DrOn қeY!mIRK f++ɢ,2}.X0z+e~Q=bs[8SNr@ʾ??]_pJvMEzrZGZ@)hX>~y f> Sp]R*Im+x@SJwXJg.KR 5MjD M]hqۮ{8Н-E!"U@$CLYm TvB)|}_!EC˖[ajS/~M8jS[2]g;gf77"l> stream xڽY[۶~Ҍo:Nw&ܗ H|r}wxx|,v V`W?^}>IVɄ'aQJłvuߧh2&1CYnk4Ny}`ܭ)v?^U78Z`"eچE??0Xf˅\\oj}#5ݱ̏ԼtNEMed݉JC&re,(JTnƹgvnل0 45L1툧"\70^?mBSoٳ6L[ PX(Æn5°׽[axǔ,&Z Fk#X&T*3U ~c٪EQnrL'iGe1x=q?>i*YxkDAG4SCJAgV#)U0Mܖ&%QjXДad\m]w(<~gn H'h#dU\xڔqٓM"O2ӳ4 inq0ebغmXN[.Zh-Y7MۣfuOF:^~i\wm ^;s]󷦺@x+xDȧ֬u6.-rF6g<34s#9`jY*x`'I܋hCG6YAOKۗQuSom܈@nMan9DуSV,JY)7$գąȃ_g%L7an0hZu~/D iF^3#:GL K=x0~K 8>Bް5u|15c4EUAC MǶ :t4&q,͐?53ĐRM&N|z3&* ![$) !U*&bJkl ]tXN6-\`a!`@P:< mQSW}A"ƄE,zsp 'LfA<15LSZ_ b;'㡩ƨkq+ ǖg^:[qu+ IG"cer*OkDCP8GRȢ$x:m9xݭng h-H(G^ՆC:/ 1䐮=P"g |jx7_(aYrnZ'Sr5~".lJ>RL"<^y^4{,V({AGRO<&v_ZLؗ5p4.Yb}y n)r&p.{U &.Kh*$xݒGuܼ\5)mpw| XP:Ț؆ԛNp+OI8*Ma1nKfv9\ʆ_8IU\pB5Cxzז}ejG! ^OԳvG)Py~4R7rȗmFEQUS3x.Q͌cN:wvQԡoCR]qB\ts95<496GXt֎.ۧuAsp~7HX)~0=,i`(|YT#L߼(\a[hWv[hm"4z Ţ:cG?$QS~t"L`Sz{;,i@-%c;==O@/OQE%w ?:6\=8iؖ BOΠ?AC L,T2{_k endstream endobj 496 0 obj << /Length 2012 /Filter /FlateDecode >> stream xY[sۺ~䉚\xuۇ;iNۙVqRZ۳WYcaggΩ T(F:oYe8J$ |@W8o@: Iw̻=~!y4_fZ3燋 HHcN)x|~U2kUqP }jní/ep$|l~<ٗ)ǟ/7\>rma`uN|' Aj^kXFV&1eV|?+S̖eBe0l7nh>MӎIc>ˇlSF$L0:%8fDª*_hӻ汘 ~)n8fۑ8 ־sRQЅ _< (#P,9Dq|V!Z2eBAn.)~^r~[-q請$zxM]ӑKݵKUWi1Sģ1;Ӓ[U.o8c6Xē/+&޽Ȍ80n>}A(`)aQxЅ8OR_wnN;Osrd#^Ш}a* Hf/#0p{G"R7AJ6mk"hk"[@sa3)+$6J.8.ILёX;/N4_jN"k`IZ*Xf>%wBi[6,_8}HŘ7[['-_9loOY "KyBkӾKmhhq*Igw}k:r/CM5m۵ !;&iQ endstream endobj 528 0 obj << /Length 2387 /Filter /FlateDecode >> stream xڭYm۸_aKm f$Ræi[e(p)Zje'npHƛ+_gf2n~x˷QJYhu[|c"VqPmuluop4Qp41zJ>Uno-wnf=} a1vv{A}7Y>}6ƇA~¢dM]wG,ML?,Y?l떇뛿Le3l&4?k>s}"B?yǔ n)MliȄ^HKjyPwW_Ƨ&J0XeY:< 0n&)R , Flxه#XJjj-8xj h'ùCo~ꭳle֫>-;jߗZ=Sכh&ش@z|hÃzg\fO}#eqx1SYxK^*s'5X7%F>K|gM Þc sqjvUiP' nD:H ,ӟ>/[hlDɥaj,ţ'Z8V?T1 R>5AO`;eSM줏lJt]iתAhwrK&i˃1W,Bv6:el=v?FEMyQ*]6~shr}Em'#ǖ/o@+3!ĺigkE* VY/DLnP!Uv$)^^V~%/ ;%֛0;٩pZ]`!M%ËM],=pE.˂%^91~g M 5)쉡j=L#4Z>dݻ<= bad=ߕw]KpK??ƽʇEW; UZi}Ai/ϔͫsT {WRې# I`dGN=s󎞿8+!Ja͹{73 >=;`}[:\FynzV/ϣ(f>_E#tOtڻXܾ&I4jk@T59D]1 qs8Ԥ̎w W6EOS; $x#Q3#I\`EH 0G&Ǧʝ͢'x v'#)%fwu.G6kXQfAb멯kd PTB{-|mSz +C [ʤiB 7BpE"|tM<4?=j?7{[L pr`-Dٗn{zw'mY@L6msXzN.eQ.> stream xZr7}W1y0@wRJb[R%ҤBR{zHx5*3F(qJ2&p;dDc1P>A" D4i}cg+7 쟭&YsxtyX>olrn狟{> 3>#oS+`V_ 9Hoӗ *  wP^w*8)d`}rԎOƧv@0Y یU;0K4A t;Ns#2X)p?N?'ȿfp@/a_.ZE[m'Ϧ)sW/Z%^P!)3\TG111q}J4t0h#5 8+}(0.૎B9_gt⢝cIb pF,VpJP;;ΏLE rB19x5 g[ XMCܤfWP]!]|x>y J@u(\FͼrjV&'bHWB’϶(/:<xj©GŽ7{g25i$b"k;o%{>/ cCPOXy0JzY;NFO.S8䀅Tc1MJs@hhdmȣZ-~&T~*kC< PxiV^NAc AYC <5o3Đ|zi6``Cu`M]jKL|18 &BѮ8e`J0S ΀Z|f?iz/sasSv[}wp$P?a*,f0髰 M翌RR)Ttu+kuk5ZZŪ/V}KU_R՗T/U}FNzr՗\/W}U_.F_8Ňk|?ڹϨ ˝̴Eu֭ )ZmvYaۢxHL;k.A\}5mӷC:@Y2M T&ݸ^#9+$͡U0XLDP'r֭ I*IuY{h.CֺmR~|@$)ڨS e m]9 JQCro,G"Z1\*`0ݖ6@K?̦GkbҩhX|-/d\Ft1@դ%uXLJK!•|L zz@8]p"A:Whj%8;,y@fH;(y7: U`{N`~XfY^ t($훤^>@\hӇޜWUt_dAD x kkxOT,$xnʏ_vVh (W " Du|aPƂ|ZⓔyAq"]ab NZOQϗw 9D('(M"7ekU^'[>~Q;&AOk)q67voeSB|dnbzG^u#uG>QYo&KHqñ ͱmvxlٿ;96@#Ӄabd[J:6Qc(cQul! endstream endobj 570 0 obj << /Length 1935 /Filter /FlateDecode >> stream xn8=_!IbF$uIY(ih$%vlH`<б-|t>::xV"hbaAwG5J;;u; 'Z%G` iCHk!;.y^~qi35#Xnz5gb>U$!P`Ev9 P[ sA"V phs^ԀPYU\!YVg?c9uz a@SV}p(X546S@wRiB `AH)U9ǵ8 Sz*xEwCq lF6+t;/Fr[hɥB@Ṉ,(fHFr*8FK59AfFC ьWS63Zz;uE n!߉d_KQ\%`!$啤:.XI7Fʧa o? eϡboإ]q1j=YL7#LR?ZRwo$5}-Ax0KE.!uik2Uig&e l//)mGaW/P@׿>V˨Ȅ_MDZK`:Ɖ'DV!jc =; s13L7R7šǴVXphXf3ʂ:R!!Wh0t>X0렬pxah-gu g## 6 >rCo,e07RaP€TGpfPyZzJ6DEtz Dеu%[BmࢀNJG`##⑾ PgDIp-.򺒸WAֳj/BAԩ4<D~y۠}=ۗ2h2y} {`CNr廐ȇ3:I"9` }}=,Vdr8E74SʳDې{@?o:[{{oT.NU[둯9`sV(.oA^pX#/%bi)C}c*؄$/ !T=zP{ju WvE!^*?E(ڀ|S])CuըU#Ts @/,1-Mtj.ɺ궡X/psW MSjvHT|0ٿs-mO7m6-o2A];Hp[ܦN`Rq~tӱ"֣Z[.xOJˬۣzUH]l E.+z1 ȊI\yZT׳,x@iEI%1L=:݇{ťBdY\Un[ = w6U@16uvm^1g\ӄ\Xe|Пb!Y[s2S0h+zƝp% ^fD$9Kx% @o ظslh[QH+Vi Sp݌w6_/]N"׾*4Bb&cb0wq֔[r9J\S쥄-;(r,Gj@;]K L߃$Ӭ`PC>&:,zۣilb^غJq#NQgf 03:P tu_N%ϵ."9B 7xn/u%n t:4έľrtlK"c)+>Č+^ϫB+{}> stream xڥXYoF~ ]4ZN-!ÊZYD)Ra3;\[_|>F^XRE 7zHk7pDlj+^йK$,O챕&֭ʋfrp``XM"R˕D* VjMۺtCp,A|U٨ͫT@:oa/3%yick+}eA;-MÐ-p6^']UӤ9,$,j4Mo?\,>w?P[ M 4.t.8Fl?3 9x$D(O3Md D1i :3Cor;SFn۪(6*3l#Hۮ.g8{%Ғo%aå 2Cqά{ tЃ|K/t |z)!suN[#x+ f쨚Xpi`;mEcF3uu6\KD!;ՎR "q6KO8]9@cDd>p(I˹M@Gdl$;ӽ.ugFB2 {%]'8ӦHX"qSǬR6m)utcޠL p}u*tL}LXhܡ;lNI4-_H$C|"[HN 1 {/4,~&f hKa;g5t1iFGj0@*i *g?lpjd&caW@10O1@0ƬŀiO <}DPc ,zi2dB5&` Uljfʷf̢:o<]]hsN@}!h#>@Pۻ~[=Vr=NJu6;yй/Ğ|Z:sZmܟ;fAblj.0Jn[lN,M.᳜r6ܬ/m endstream endobj 601 0 obj << /Length 1815 /Filter /FlateDecode >> stream xڥk۶~‘$]V>DB'/N{vS;^23b\qVﶫwb7ːk{85ScofpOt^g~(|,ku={aGI^=n%=7g5:jcu]x]4R2Nr\}:)Q&ȹ7GGzR;W?wQ8]MC`B E9G8#}Ά nJZ-'U]y>xntWקJkZu}dkē,K4b$撝ĹOuRe&+F)lb۷(`Y]e5NwRn'o ]nھ XTwN ~~a\鷖Hwu|VXHa{g%]1۪* KC\u^BAc>\F !<E'"Jq w{hi#4XhTfrCx~G_8\-yDp! K7xZѿ;chnD3VMNa9D氤U% =b@a*K(+NDvNIl,#116\JA̩i0MCܽ B!`IKTǝbK ɓc3Y(|QE,2'UF݀t2rSZǭɂ"#bSlEq=1f%h|MVG63  U yzF_/zB.IǽIaHA\dlO7cS%cY }+ku0\`J9Ef Yo.U];#cOLI5t%$ ˒3\pD/tW,Ѱb6[o:?y#뵓َp ~D۰x&M0moY7`טl Klwi V&`16 ެŞ'0̛lw}wF) 8y*uz[=ݿa!8+ &RiUy|"9 w@ExxkxXv(XM 63/ax@R2*Isd]xөfrFOawPۙn;bDﯙmX}^0 O 8ԙuwR~2? cX0miG 1[&:tqLځ@z0С׊]Tz~Q;O>2!Ǔ-%:%!=WM{>&kΦ'ƍ݃Ec1ן"qyKu'']}E64XCm8թuf6Bn)2 endstream endobj 637 0 obj << /Length 2851 /Filter /FlateDecode >> stream xYmܶ_T dJDP8u[#/qQp%]i;_~}g8Vʎz@Q8Rp^튯qu7qJYf9g"W2,&_7+E ǬɷWE~'GlDY&H?A4z{&ܻ&ר*iszG'9QUm۽{*3C-/v veK;$Cz}^d0 Rj iDe ʮ-Hvoq}CMiұ*˪:nZ݁uyl|)'Xx듪UL$C٪O𭣆󭄧ju'u )Ʋǿ:m Vie`Q0#,@CNiJ: !Eиh7j=椳l?j/x^/ KvGzNx0o;X3S v Q6Y҂!#v ,K'NB> S33y/Q]@ F&rh<ȍK1CnV4MGL"KV5JB 0??s&,X3Ȁ3%God,j{xM5kj38ui 7jL6;uZw:c`#޻͗ȕ,>GN6cCшE:Mc))`# ` ppW Xkfuf;X/[pp94py{S-)-Um18ms\ϔ q脬@Q8F>ʒSKj @3$SIF8;.$%F am:>q!Q nBxzE>O )&׻^_ /L'!1$N #3+%YA+PcC㇪qXh#eR2}^8[.qR`xBz{@w SaXjnfu^H!]ʈ$Cwյ+jmg;Tsh.Fۊ =)Tl˯E税$Kr *!fϿ !AO%}Uw|dRlS+QpxCBk3|V[rT&k;{>A5q뫷״X 8jUgp't/ qL <K9>" ],g #7tj*v~g*2t&;lS7\ài5R?]Z/%ϚQq$2Re!ܪ> Z1}j2u 2fCw,ߖjqȀ%v! gB ZiZ嶄<6 R (W bEUHʡU -1ОeE,MqtR/bjc0g 8>њ.ҀkUfDλB9 ٘{-cUeO>X5fzە G3ؐ߇dS.L"O0~2;]/PPl:Ҷ5fFEs-uE+5MOd϶/}> stream xZms_ EɌ-Gg҉#M[(\I;:ǐ;-Ph_Њm1e#(=%&>2}49]#t!N6cfFw,x)񁔆gNa1^OAJ4`(HF0L`,$`B"`9`΁DÄ/,0l1bXDg8d8ә`A"Ct&Jӳ,u k) O<+3>~qQ):|oEEEnƠÀ+{ P"&`11g)K&b,~rNoHg–h*GM> LJ QIatpN%d=h<`3&:Qg}Z8K&sT0% 'g a1"Xʐ)=CbSbQb1%CuJI~5䨧:r*C|*@br1iϣ2Bi~ >\ֻٮadhw:^N>a2=w/b+l9u4o {h<0gfLN_jZ6oGG=X^Л{ݦ_| PdUq9%HHl R)ZoG=?b̻njmAbvVU6dgI%un6>;[v 9*t%X{6hs+H_ؼLBm,CWh @zbfNa` 6wq6"f 6a>Yvrdxqg'0qxz|P"Tr0 7}Y?f>˛tn2=ư-o?v}9ﶽ_/fL۰c3t  佼l1:PshsmIZm-Vj[qǕ_]&u]am'T~RI'T~_b+XŁF L|,nm/a\ o6zc8CՃͷ+GO f+XWt>۾vY%2b݉l~nq QGhD W& yzԆ V OwCzᾄ$Npt J!Cu|9:"MOzuꋳZ `a]`!k1ulz4`жJN`K-a"B.eeu^!ݡl>yW9~!N{QcF-<gnX$"#1k3H?H4E2I=ZpMJD=*_j:|uR[M ǐ ћk,N>w0 DuD{<6Aṇ#cqlK{l$tm1]Ј]ua,I_cDNoa fn1ÂRGd0Y$TlܵOnh8p`ݐQHz1gh}mCmRXT\ajzgh+?_W~_dW ML4D!Ɨg= FhQ7 A/ߑN4FR*i}R(hP- #OGhKQFj\g=/ӳ; #+ǎ[;,KIF^6)̓Yݖʝ`ty`y}R# OOF h^rl(uFO[A]^Y5>XZKdt(++JU޵!϶7oݮē7/fzu Do`nt!z$aUC:l/zew! mW84ls8~[^oݫns= endstream endobj 686 0 obj << /Length 2674 /Filter /FlateDecode >> stream xZK6W44zX,lm8")AbOk:zx뷊E5;؃abT,V}Ui_{o`$fϤ WQ@M62ކh9beqSV{2RL`jg/ūGy6hy3%C|N/뺺>efHrj-:m5SzԺ銖ڍj/u}H GsⴿzmDVDϴԳB gӆŢylL* /{Ah!l*Anh>oG Vr_^UB9[e※ZwZ[mUe`w(8`AMp5]4lӼlױHz_i5\c_/f~4cUEq/{ [xN\)/ommIkn̍V@DMV>vE ֹ̽u:^T px䐾`aLϦv Lۙ(\=rcӛyz&?|LJ>uӚ$ƌXR!*괤fw6Jb'A+hGC-sHK }jһ+5Hp[3RVIȒXY iQq+[!Q 6@7%wj'i0j U;j.!c]=[޷VmUٕumVcc(ԝslKJ?'ݷBaŋLt}˹ jl|Z'-O6׿ZMˏyҚHā=I~7η rr|_V]cY Kˏ"- `fO$b\s^4QvQֆB"9C6!ߤ B%e߲U6(͋CCMpx8KgZb#^BյJij7کj Ad92Ԫ.j~- ěDMwFEG8!JԪ+b SJ pGvo%cSٓIkɟa[P^҈G g-3/ + *Cg H BI40ŧ>j.H/hP@SԘz (}yvW4=e9BA5:Jq\Ms?[tKC& rj }8j; ke5uW6ȯ(K3[ @3x7^ e 6Y/#_{f#3ar9WOy(>dN }pߦ̲{0/( ~_|9C"]QɄ:(,yS P@C:`dɫR4Orcqs~p̒m ݶ^p>+1  -ۀ K*~?-1} ڹe)8W&O lo‰0N&6a+GU&fI nWjR8h싅~C䱀A<6BӷyL̇Δ[4d3LԘl_JEC5=K 3 \*b:e,2L#-viP]&=.?c/pb,CQɲ;:z(ܦ6?y \]Tĥ8Yٍ,~3܁r>g=`u_g] Ѳ/,B塘POB3"pbxw+'j-Zywy@H,> stream xڽZr8}WQ0@DO2T=[[5YܡHx۸)F/`ۻ7~B _l8 "b,n6?8<ޓ4&( (1l|{8hQB+I+-+ {bS7U_wvZm X@H!Ly+TuSي`)s:lyJk AQR[Jk-Du۹V準ګof$?IOp`hA!¯h?eβ36,jcRW!_}_e?djfA*`ANܧ/׏+ }wX X^,s3K1b swFCпgxފ8@.xQݜUylG G1 NS& 0( |~/띚 }d)DSXFΣ復̈/H퍻*{-f2.3,j#)ܪhv<"$LN#'97vy-^<# ny $6CQB{kV42 K@A:|y%ږNپ-!nͪ.VioqIv,mQ&,ޭRɽ.wv!^RdUTh3ѨMg- b::W.SnC vvT[y_z[C[-ɲ;lǶ, 7Aa>_ _-? LjxXg]oT9Ӫj@6 :C~]{nÁ7LXL=JqZBJ0|9|RuUI!wQ\O t9XkM{`_嬞8v/c|CY ~M&ME-豶>5Ca&r[1gA7| O[TP@dSP*ni鷱VpP}!|6ybfarY4q`{9|;JV ѥ"m'JB|#HͦpVTcx.-:qg*OP̔,-qk0Lw $Wݦn b1CN׃~4 |SMJYZ;*LYVXGXH]YӺ4%G|rBQ 9W54Walm0Zx6 <.R2$;QWuxE#x~\]Eyr+ly RQTH\~@"@GZ.b(u`@N0[7M[cV( #z`}ʮ@AHگqR.͖빇*Q9of)(˽CIdz+SuFb4A18 5 Zfv.Kl ҆fa,ƌ1֓yljڛ]衩] ԉ?\kS5dVN$Q9@ҠR\s7LM)0) a<2@ EՃua08(Ǯ6h FZ/`ByO#ƺ\Cuk;F!T-VRɺJJddoHp+LaD]-+ws_s6ꮞlMUDg0hȝY+, p87;ӵݗ#f2l|RN }x5eo&ℵ@/_t NXw=aF}sZ=q .3TKo!i//_ o* 0bQ8> stream xZ[o7~ׯcBCA\6ݭMXE*dI}oD9Iזf7#h:!q&K1>zՈ(xŤj&GxS<k@o@0P$VH5jJ%B(Uu& T!Uj\Et?S5f4TP(oY,ͺ?[r0Szd_&ӳbm^m|}L6R5XZOنX<~lfLήj{7@`TKA3R!5[Gh0~Vlj=<oS( 6]|y\,@s(ͫ rL׿M6@ Gx|P~q~{bH1T-ðQ.šƁkp\@&9hh(b f㟾r5E&5 D Aؼ z!4LO0ӗǵyRv)m-7p=6vu[wy={hzeO5YKpAP $e7lΘJH 11nFDۨ͘m,m|flrF/7zˍ^nFO=mFO=mk`z$7` jn N`ԌP;y< ;D1;[}?=6={v9yg/泛!xCX{}+qPu.aA ,# ͶjD>}/q,A dT?tJ0%ܮlVNyo!08ևra# OLp~z費V~c. eJȽ#&:`rsHRɶBHPw_>vnDA fh jIbK[ f]CƇr$h>۔=q|=[w ilC!wpkCP!BѼp:[VcdB6jke1ŲPcZlt6.p)~@eQ!R8ZT؇QK.B (CPhK IyB4'xDY1FۂA"l`N?iCr("> U: `)"Pil]I:s'8P,E3߱1B} cĦ"*J`K[x`ط_I qV}DBU ϖ$4mJ6=l1JP-(-Z)%FhU[+@oG0e"("(I<(lA\~eVg /ZgSWt?K.],"6q ̤5&3Q c#CI#`cG⥓ )N%'#+[5kR2{PZvp2~ѱ2s$ფ՛q-ľL6V}@u?$"b/-k$vo 1TKRi}8(Ksϑn˃0˷`m/TŪVy)ТŻj'rѸb (0W<)yYG_J+hw<"%'+e;Q@| -H|@w} J+6ʏףf%ضF> fYu!n}6Isy9X Lb`%vo71;6{0R}~1?b'XJ:T>_‰?r~~qZsN`nm|xXݝˎloK JoQ@?FX;8Z Y~$&[H, RG, NV+s2Ю+nw欛]x0iقA`=w endstream endobj 788 0 obj << /Length 983 /Filter /FlateDecode >> stream xWmO8ί=oޜ^Bjo۞I\]^8ۥo)MЮI+D$y<:uv;<TL,rM}[-OP>9e ~LQ%t`|T-Ҝ$J/!_cR`o1IiJ SHEӺ6 Vrrxa~Q;:C0V,;EO ~cǞ& 0^rNŗel? +讷C |{]J7'4ޅ;<v FYnT,wQe*!L> 4Z՞- uҶߪh'AC 1bOf3u#fݐ "hFozM0 T>m,A딬]!t0geהҌVbZ,K"4@$-_t5<K7Ɠ/áWaF={+wv "UdpnJn0&,j"6W$U"x޿e%Qr$0y? :Df*6BQW 'Ex:U0䍒.?PWRARtbU-[Y%LLH^ސly]Em7txP::"NrL|/JTkEm)uE`e&;%WU ?qS* ő|TwOO"-Xiy{fR#rrk|3$n-16Y£rVm;RR%5xyI-Cu/ȶ:qMMNH%! FIV2*{qU+ogٝxD9k&b6oAQtGזjO7 L?wc_:*=#nu j;9/~ ӣ>/O endstream endobj 806 0 obj << /Length 1478 /Filter /FlateDecode >> stream xڽXYs6~ׯ/L>'3dbyq3$Dʴ-;p{`rZG'E[b?&3s].ߚ֭oOI9D>`3Jxzah@HA9~6%uYF.\#ۥ{$RM#dG5ńNK˼N29@X3rm'#(\ۘ%3E/G\Yj=4GVy$ cc{0MKгbE5z>RcߵƎ6ܘWBsSGj3W Vw{U\4)H?EԉW_ d|IӴSaWK@h_ R5 Ř4#VzS$_u- Iln0\#^i_ǙoSޏu)$51ZVsD(ZrlrI5|!ܸkjL!cw0iHFU%lCih]Kn&X!1Pg.ټ\KL%!Aǥc`P܁$lϙz[.υgA6(s$ $s xUWq":#I77yY})fկBl@w ߏ_ {y$_Am+ <,nS3 8'B7 | q_K8þE)Ê =æRň^`-ٲGz|Պ mWlMRtNpVcfdWjbS/K=KCZmomP; ;etd_1Sl0t}\k鱅?yKd// endstream endobj 836 0 obj << /Length 2324 /Filter /FlateDecode >> stream xڭYK6ϯV l+g. ۉ0bsqrPڨ6%d뷊E=[ck*RdUꫯ49:ysq^ȹ=8>c"' O~~/l6(0ߋѬc\r?|a؞s/|wagfĹ7+NÞq|nkL >wbx?bB8 ͽ4;c[-яވإms-iE;4">PcPt' g֠e35"?q><2{f+feI-k꼓BV<3`~U#aַ׵ʋvhNvx woymȅ{{*Au#/4" spX(@҃`,aHƨdtjdE~U%>:(bA}V~EwGǃeP zS?4ܳ5''p 6liS#`ZΎr1#k,& 1NNLz3آ:pG^T] a@ѸNR y>huu:̪_]FS~k?j)khDybn-3T:f%ymIU5414M0J@֖\^ZEZtL%DWԨ˗E_S&%M{|xU< fɍGP`La[b$/ HPf5k S/v<[< 'ՖX>I+kxp {t`!~i7K꼋*$/\T'ocЩ/V<Oݸ@Oc)q$Ƶj߷Z}2O,S^u{>$jźS hٞA {M a 28MD,&?t6g _\@hdmEW"L9/(HmDZsG :ςkU)7IGWu]U1hvtJO @6"xSy* .2@x6L? _cc'KVt;N>LA89-(3J/;y  |oZYet'(̣zڜ;f)ӦVv3D *7GK[,4 R +DjVБ\l X_u `0BR )~: 0Ft."x3`2TEH0D@o5ajm 5t6vQ){EcӘ%ItG{P',Wp"{yz%> stream xZo_!}]~-Es.R}}E,6qܿ3;KAZ~.~zp;qz\px|q-~X?J/p^. 7RE_P6pmkvuWM^uj\aD`@h$ `‰]#EdJb>_d%|h%4 HU_rgh٘Mq4t}_NT}暾>N$ʲQV3Hn3A@Rn%w 73Ӓkde +3զj%zTThlWWZ70=+/y- $h͒&1i͒Y%D1]sۊjm,0?*pbP ]rcݦ/})*KROshF6)>|NM]g$m$L,\ hv]>,ѱ(m*P2H@})!.=X wIlpo(;w3a-PV[I 37<1ǪXJi"&ߝlP8!Vf>w7?_͘K&:fA f"J|?j}4,jÂClNpG5;ۻ$a8x E{ {5xgUU&;pMMp\̳&n̥HR(59CbX1XDğ0 [0?2q]r .Jψdejep62ZXu'T1yaƑü!ljJGmݮdmT6[(N#xПUN&vC:T#w>qT*e%xmH8أPcIIvG_*Aw1 Ԕ/>iZVL dt |M߲"C'%VAi\Gp-4[&IPHY$,e֦i[z00CP &0:C׍90v_UƜ.sEC'(*5?ȁz̐1@pE&ײ>θ9Q',m}.W{V7TUchƅ$ cVC )”J 8$^zo0e8NZ52( T!Q>) +zCɨ7Uo~0*#5IzBAy'雹3p 9 78?,=n׍]A|k!8G0j_k,L))r߻K=vѰB|s< a4.d/ݖ:x;|1:;{]Cr']wAY1\W]Vmٜ3ڤ ;hNtkuȋqӉLҜ)_&E~,u姶j䇼P_6 ;~@ ɣy?7yF CvI:,hQ_=&а'~i/9pЗGA>y>ئϼQRk|e3&;UqF!^0|˹3|*O`JgIeO'Пy8%)w}Oս~+̏U΍_L V߯7ۇ*? k7;'3"'vͯR4,͟m~Kqs 3 v/r[ՏO09cpuyG6:Atg͘ج/k|lcҽ> stream xZn[7}W}HA޴ۦyPF#Igr6 |H_CgxfJWsp1g%(˙Pc)([jbPQ)I- ~mRT"p]Xc@T*h#&7y2 pЋKY!1Ă]:8 rbџ>eIhR[pTtt̕$'jfLZL$FB.'̩EJeZ).׈A[uY207q 08&9aPf]PQPA6Tл&|pM$DP$BW-h 'Į,`օVȕ &Rt( JZW2$ce~]%&Vt@g`+F^mt ;2arT` oU(Э"-! 7>  64%r-Dk _ȵMFJ EN0k/1Z#EnAkY00HXbHK1=f k15-k;>ɣG?bLWo6''yz`ѫ3tg*q:?OP%򪝘sHh=z䦧nM7' 槫{>t'?$;<9OP@<|xpWS Q9~[_]nV|~.gKW]cW]vxp24&+|Q i9{/xhb`F)dzOwn0GobM-@}!8[-qmO_!XX-(U-*M/ -./_-1 7:q~ ΰA9W)ccvŦ_öӊ36g <ړX-N;hM_?uӗ݇{}[/fuF5Oju֭{>ww>=Y~pf` Ɓ% ʫҪmXmF+ږde,V<6yz$"xjp# L*kR~)C{CNn^~8HIp#'8B8FYO`-AQQK;!܁nUsD( { L,#+Ux8?Yd+M^2y%GaN0DvCˇDmкa=KӤ__Ms0Ȃ(_N<?kz ay>5!U"w,ӓ|W+782a<Gv,8Ҙf@ĶSgwyaTU ~g(6V %p#T[QjX@+A[c-R"%m#a8pmfFa|,DΝ{yn12q8#~Ԧ1e 6MK+MSiQsb ^̪?L62bM =; n0o}Q`"N^s|`݇um]Lλn7~iLA_S?㚔߶_ k^xXc.h\ڰ1ԁ3)e6P0U6.5ahc'Ji` ëmVx#" $0ɠLlRbbbbbbbbRL=@b+&b+&jɫ&jɫ&jLr[<1ybg"&OL^5|T`xE/Aߦf^T}-u(\>qb6'QfWb QYÒP4e^_ʡ}uYH]Q?|Xa}u}`L5pD߰yR*DpaA_Z׸/cTvܗfF_>Q0ɨ/'wĨ> l endstream endobj 924 0 obj << /Length 2694 /Filter /FlateDecode >> stream xڭZێ6}V I5bK8{/<%δ6jMIL~XE]zd[ HbթS[w^_=U;'a\8{"J4Xu|tËN͛vdM^fp+UM K)NW:q+Ϝ;3DL h_.f Q4B{I8yIoa/>< fp>ɾj>}WڡމUP{V{uIxQ=%kǓ$)RuF֦-.+Ȝ}}r(@#WCwI?ʞZY`GE_]io}%TruI܅y.I6(`=0LѶ-cX0-hDguB_c[ve?bP(r}$D]yTOZɮ'QՒ"/4 v'^OVT2W⥳0<=|iuK/ Z@do 0&[FmKGo`CHaynW}\'t2'fO]M/ R T#YQvhPD2 {q9|AYx[ЊW\;^ 8/FyC_:TA両X'h}vlĘ{eq8J-m^}o{Z_Ӵ=5Aч#AدZ'3Y)EstЭ- 1M0z_,d`7 J+`r4`0&_~AKm< {esJݵ+-ҘmT+\Iy,BO˂07rB)qԿGe% :g.F}4Nm7H j!:Q!=^ W{PP}AH͙Ssj\{ CE-F3c!#p Pe%DdGn˂ FEL^1#֍r^ԲPǶ.>Cqs T'5RҌNZ0cKs r`M9޽ws&xd;<| jhb׊0|ss]}3dp ԖTz(`ǚFm3s}ZX \HdXɲlsyak DQ,XwJ9&{k03ؙ@dt7!`8a& %4V'?rcfc'k62Zh4F1FٵY 5C;tk0Vkibŕ_67D4]쎹˪}5COpeMI3|P @!X;CUl 3@iؖj/yod7w~Z"ֈ%qt;V1Ϡl9=2.S"xYՒ aK7o8azL{j6+ QρC$Oq{O`j%5M-?Yd)243=)uE"'A!\:ԲlZrwz>> stream xr6]_5!/lrd: Ih(B@+.J$C˖I#{/v~:Y uG }Ϻ/?:[~V Şp.$1{̤94b^HYxl7_N-7Ղ@9ӗ{p\\a;Һ*|ץp04S;?@e|Jכ&"~?~}UN q?y F(Tgo_YIJ mM~GfPJ#?T'wX$Stڭfҏko,}Bʻ5x:D*^u9Tvvdž)۝j Ttg*ne#q^z8130^wyޡ:f5o%ܗx]K`ڀG\1o[zc H&V"(d$ltU'׭/(pO Qyǻ83ec?em4"ٺt ;}ya\!O\@{#Ql^R5IHj25̊zՉ͆ #JijJ5qQ3{F*uJ({$+K*z]U6(84:`N1 =RC5I5$V@M="I#u˥ ZOl"Zljy$vARf`@4W\[c8H!d: os\H5ܐW82hE2v2zz jn" E H3#oMy@?I],2R*bӐw[ypU ~;=hxg7-2stØqWIy\27 "jL%~~{<;ɮ`& MȽI_*[OO"jJ~d݄naTФЉ#b}Tg`J1\5ӿ.q*ӎ((t"Uj((+'&%p1Z/aI󢞾QxC7g%Ǯ0.{ܞ.9F B/A1zG6@,YR 拼 ߷\?E%͛`کev׵ۇA N~s)AiL endstream endobj 905 0 obj << /Type /ObjStm /N 100 /First 901 /Length 2363 /Filter /FlateDecode >> stream xZmo7_3LHKKpwi>(1J$_gVrҞ-R8\Fyrj*.#QWq5'1a$ adW(b_]U1&Gqɳ fb#)\LV*3ւvL%: qY-ؒ}Uu"cQ]LV.fV 5h uVE8qŶmfIb(8/Mx0`k ~joԥ q!j#)F<0 %N5DN$#.CuIͬ.V)OްbBb93DEr.Fdթ@j4Օic%29LQGF0K!bFB7 GLMO n&qF%{F7BT{~BxR f6Ghʦfa$ejWPf'!_Thfd{f5*A0;-6MJ!cʡ$/5 8۷.B #S٣G_roﮗ?OVn*RWϻ˭{%Q|Ct CbBs=vzrK[^}ۭ} :X ] >@=$U`.r;MãD_19{=}lb_,6`EE{X1{<^^MC/#D`Gqnn^>_]MF8G[P8Y|7!<$z*n;-OF 1 1ԛag)4{#sϦ68obnBfM0!\tnB(9BE,bnr2մ| ҽ6OݫU_sтDEjqۛR;bA©8KFb8W.F4"kn%N6ÔK#/r&b.c1n{Vmϲv왝>dSQS_W_<}/[S~ϰl~nYݮ/M4ܿ{wuxzO *T S8eGۉAXqNw# #cF4|4G|4|TG"۹{B_,O"<LIvY/vk;kt9EėG{JZ.;T(?IO;H~8m8& j Y$\Nk<5 aqDFKOKL1!al70P-;mNgldz#[aĭݽ|:KJ=T8NwC\]&CR/TLzQu[B$"uە8CWBcO^Z _xdy]}v/nޙՄplW P3䈃յY-}zR8[; ȝw믾vZ|B"#g%J#1 ։Soߛ*Km#\3+bnlv[g;\kd3)REmȗ$Q#1=ӂR棂dSILJCRCRCeo0q(]d(]d(]d(]doتс)㤥н2JdŸ{ck8X#!$L 8ŬӏeJ58o `I,}#Y"ih@}㵖վ17Z}c4o4A:bƈgl8#}0#o$ y߾dx̑7F(}a(mxn߰lUҧ\b],'?Fh@_}Jb*@I`>]_['K(oF`Yϟ57Xth^|L{g1Ŀ endstream endobj 985 0 obj << /Length 2025 /Filter /FlateDecode >> stream xr۸_>To!7;nDBx=8ɔ"i; sCaL_Y\z&u`=>Y_mY*gZջ eaI+>9,/OeS}؍X10,A.ٜTYOQHW%btVJhQj9u8b fsb>foWrUv')7sD5Hse[6"KdLzmWRY˥MY& x{YxjWȁ%~0<6pUKUDVzxB6 + ,Nݪ49EGUxhUYUr5\A>MZ@T􏚑?}̉\ y {xt'٨"2zbUy9>HMMvY;-FUyMv3bm lu<#QcۦHΛcj5s|^C&b Z6 3=ދ$fV&B0:`6:mE eqNV=JJHZҧT:A 7p! 7Y1)0, Z]#Zk`]7!s8msƔQk+ɲ> 8Bs(\a35uEμPƾ^nԦO=:ށ\8Q6}dLa.[FfBLڮp]i.Y^u:ȳޕ4Mz$FVZ:a[쳓$D'k[l)amU In7MLQh-\5K.dL lqHgޞU;h8{as&NOX&K؁'UtwG^DZ{ӟ.8FGbR1[Q>,R,]=PNs}{CG;yʍn endstream endobj 1011 0 obj << /Length 2169 /Filter /FlateDecode >> stream xڭY[o6~ϯRY)&Rtڸ{iAiG,,ͿMeő(LQy{;~9{<{u͘-}̋h@2#dݫV4@<ưZY-ERd əoZ};k}wgb]Ͼ{x΃W1ҽb0qݞ}l*E° O⁐r5A1o{[΃h&/OQ47Swfbۤҧt㧨EGŢfu)ui;Jvʺ>sĸz)U1 s 6Y8dÄ?bٯ>?_9gE 1د+6ue!;?2/(ݨ=qSJsh܊GcDKwnIEݩB4\"FG~Q)In+R Xoboޙ =j}' 2BpUz܈=uYnSm*2#0*{LGg۫^kh /JIf/:qMb< sbHXy_.ܼ=,̂b7<7.o)F?OɝQҏ_}]Kc ( | cDzy{oI(,'X܊[K|lZl BRrEbP.Yd@x*)k׭ Ġ"jӘJ_Fyb.)u-JXe!ɿI] _,ІCkHڡBB0Vw/F Z8!TTP4Ojȏ7)^$q*s] 1M=&үOO5#-qBňZNYG؋_z|kz{8q2n\Euqa' *)o|0&1rR 5i%G)bOjrʊәKP NO8:'@gL'^ѿ>?:LTwgؚR2y@4rH8r]~pc9=0υZ|K@Wem܉ XiJos(ųw"ky0G1H5ԏ fC+[/Vj*:LEbqv-iD2=hr#6B Ũ^T;b'rQ&5KSz7":\K8f͑M9n-jlNKDZb:pԯܪҙ> stream xYo6_aIbԷ!m!CТ={%:&K(';%Kn`ɻ>)툏xfE,m4qQs9hZm%ZN!Y.O|;].XW}vp+nޮ<ё4,|<=SnW YԪǭõ@پC wr0́W7lmE<p8 èt.ඵX)ċ k&-KeJXX "2Eu# B&'7}O0>2W(J&QyY9u:=G)YEӕo%38Lpowl pCfSfSRX,H417A"%0pEK,VҜiBQ., ȧ߷ArPSsV@C ZZzAJ[QT]A #ၶ~tpY趁9 JK͝U du/-t&1*grE}L'e 3YIY# Ӏ`4JSM Z<+ E3kL. / Yz'g ,5x(r)_gPa %)(`Cde!M͒am5א`O\kLΚɭ89O >78i+43eOWTMĵ} 1 "L >CRffF]P1"Hm[{̙P: cXpK%li޷ aoA32z *n9V t*!\2Cy#*-.G|\؉ac.bfclLe@# !i)-PD+NIY0Ekfܼ28SJ*'\w4n2'dXgNUAy]S/;dh{IJ=:}Xy|%TiaӖXk]*LpQn d&.woG%y8ArBkwh/bA?L}p; xɪ>Q/1˝?sqoy>qY$ZIz|boD!XZ"_@]/q/`+S+ &)񑾒GS `yLܡcĉ|Evm88@ρ¢/Tn;4m}_ yTআ6S,:Q lL EA~\ _UV?+^6#aWxΪFZCS!1|S'&4ۄZsT~vFc)m=9[@pW볓'HBў^NΪL?pGÆ8?yes;?/48P endstream endobj 1068 0 obj << /Length 2132 /Filter /FlateDecode >> stream xڥY[o8~ϯ6pDRԥyHtڸ) Ymʒ+!y[ DQw.{]~z^BjQ'<([ _V>ń1kZ\-c yUՒŽ{7ogGX@|xo|Jb,{$ 8 Cwi8 !G'a@I 1j2:VX}[/yۗLP8ÉK}YZ H[ ?BJ(̉r(Ł1-@uONyXH[;RC!5D?" īSt^(\wձ*-.Ң쇞dݩ~L;,>S!菋="HiV#h+'w8UZ$Bp,!wpH|@JXhS{Irj)&YT>t<YU,%iqtcBZ?TuZ?_w7XyZ yt?k 6)\=cgw׷oL)Xe{;u^1&no?K"z|/]#8hU.̃ƢyNBH$X6Q%S$= `f`w wՕ zUz2_eZVR޼QF_ )FJ!G@@8 .?kuh iyq}Bv2;K|a\8rt{eF&T cInjdr2 nj/V}lf5|)IA%hh0y9DpAsSU!w(} $ηIeFֿU6Na+ aWa:U.;D[L[x+y+Ҏwgr0Ԗzڵ0xcO]UYQuO #BKDH`w4at3`fyHgioYLU&*_P, ocY6r`ͱhEUeU^6Դ^ twq`o*csGSG^Z}&3 {ADDM?ZޥEԓo(ޛδPm`:34;wDj3 J+fq0/XxPYoS6҅YZ쥞 f@ ) TP o N%f ;~e%mmW+6͵ P]W*"8Z@fu4޷{u J.ij%]AsIT@r]>AE?QLT9yg|nyTN[O5e4BzS<"rl|jX8ݩ8nA7)G6iN V08K7xKJqs;UcZi!{hF {QߏHffu7! endstream endobj 965 0 obj << /Type /ObjStm /N 100 /First 963 /Length 2611 /Filter /FlateDecode >> stream xZr7}Wq*Wl)*[%JʤCR{PIǐ/"fiitcJqH0\LqD2~bp,SµXE;*(:Oy7^2IX# %,2a `tN4K:*XXlHtT E`q%{C ;@/9 sƠS0.s;lXxǭ]X X‬h sЙ/,^GdDr/0#)Dd (uL$   aA/4`dBtǽ( `TH+"' #\R|9uB "aø1HwTzW*wc5,|Du%uMV ɉyQʙS3/eoli,./_}ݭ9Uc-C]&2/®>xܚ1̖c , i M+ M~Z.[L~:yl&fΗ ,Gfuoj:-V Y%V!Bx7r5*$o~{_? 'wyi7hJ#ww>@y49:Mֳ{9 ([%lKs6J"oa䙙D[&谻ydx9فˊ+k k 㺢_WX B6Hm{V T@PGȁA"ĪbQL7\[#zI53;jۓFlzy J1f׫:ͩymW2o,Q0eugXL[t:$ϮV{jѓj) E1{*AK}Ӎz"HCDuWb2QTHZ7g?t2-S ,}l `sT[MA) ut{ٿ^:%zCrIیNn ߖ7ͲneN{}O[`.z"0|8yOj(}cvT&-(F G7$iOaì} ᮍ(g<741ZA9K5CF$(u6q7R. (i#Bfk4gA4g ƝsUY$*%@:o2zW#mA[2*MޤxoFo_.נPa%7?֋)600Ĉj[)4ޟ|d#lFf؈nۢnÞįyIk$Ik$H Nlwbk-Z[k)${A\^O*-tW$J{8!sw*zX?dKLZE RJY ! ?A6`3 R?KgRȆR9δ?=gB5f;ECc_ endstream endobj 1110 0 obj << /Length 2093 /Filter /FlateDecode >> stream x]o8= ĪH}mȡ"],hugK^JN3Ra"v~?uvSR7x4-F\?Fq乡G|E#fsv9s*'RAǑi*M t84h &ʪԻYSdfn)`4S7 #s0$֛,S+T9bz4nDk{NBs.(HQR-V@V*֍*9Qk|3AzgVbɋb"ryexZ>Q`6R-ư6ߑxcF}FX S7=WvH(B,IB NJf1<a@LBGzjͤE2Е?7)DIkdo&tѽHiF A1O|u V ڼ*f?p4-;zikԙs򔉌婷P 1w,\(+.b#X) K>Z~YdK4Χ.x@#`su T?kΖr-h uc1zƀ5pvCalx3!~Ϗчp†i3b(Asg:} ݖRܡ.D jj ʩ 'bL@zώt XވLg<8U]QOSwHY͚b8 XKꙆ ^eء'%Rծq^(#k9iA,^hTEfIx{H'J yLJN;b1U:7=E܎"{w^oLaq #G@O_NAf(Aip"KNsWw\M|\XT7!'oZKq˅-VE bC L|ϏHZWވw1+9rF4Ƨl>?Kݜѡ(x -Jrn ;6lh摁2L]8O ?|+2xN;҄uUi =A9[wL^y ֛èTYK0 +f W:uLk g}:rzNkpn;O F?t r+%Lc4_2tZ jr"\~`FSz(y|1ڢ3wk縟?Qsdt!ף<+5W'm7, ؈s)%8-Q6RR}Lի {e!;vyʏх9zdp nٯ3UlN}Vii$&qȨOO5ɹ 0.#EZctU A|dk~F1TX$4P+0 l8VYlX}4AߢJG6dwʲJ/ff֔W{˺9bZzXWwX84NoyaVgCgS& c*N8M5X}/MMD*\wW-c0M})hw'eKDfH5-eg$ͬ),ESpaHxg"< endstream endobj 1171 0 obj << /Length 2314 /Filter /FlateDecode >> stream xYIs:Wr,TK2,Σ @n,bJ]@lݰ;/'g'h:iDl1\hGd4G?${ϏWqؚGCQsl5'" vة)]wٮߏWA8M<( |u4t1߶ǁAO[U8۝6+Vr~"V/ФIby6P̲ZjDQ՝^2?' W7o~Y/D1! Ltt0xF缪@Wy`j,zy+QNOqo7Q#ãYSsUQ1# H 0J0R]k*%ˍeUW<B@FiQҽ=\Ζ+?M9\l%ʏRwzEz;rD*6`߱^6=5&o]`441˥Z+6hb0[ .4rD{]< j? w I /zJh{LM֗-YmAֲH^M-z˴S.w[WwWQ},+daь\jz}yyVV՜}zՔu@P݀1 O^%ND뵎/>n\W ^^}z ~^-20l&Qs54Kz}j:5RKE&)rÞCO^;n"+ئQʞċ {ey5G5r\ub+τ>O3ZZ՟sZ׏b $ B v(p-5;OWL=p}M+,=\.b6 ŒUe@{? Wrc/2q{&v[h OˏeѡK?w &3 Ťf?Ex5f4|7qHvn6FI'hŜfcdH2j;Y;ȾAdK8"`KwjBfWRBeCQ7͖Hi*>@a{$, 6(a8CW$q¤DZHM|W1 xP{rE{WiZ4Zp};!Ux1 lkͯ"4P}x%+2t^NxpL:B90GP}&Vn4: c§OЦ|> #J4ɩ2#z0!^rG8X~N`NB(לjjU IWf@R* }zQ $K^T['B '5ʗN 4-"~I*tPzDb\ lQh2D!sΖ_ ~6f)KۏRO hTYLrݯ0gFeFي$J{NS~&;~4-o$RTգ R )+kK,gL|'m緗gK T?LuvɺyZ0y0`^5\7PMjN7f&9C|Am^tUuC~:{Ii11Ug%(9 @ r-9咵N⽂/-L^0_m^>4_?%@"C'H{dZFy1ͦ (g?TLب%L~i`%ąSS\0-/rD Ye!},mh' :zN> L\>`;-J"z';B4G' &y\N^CeK"ὼU\C*¿ׅ7g{~k wNmxͮs8*!wsG endstream endobj 1075 0 obj << /Type /ObjStm /N 100 /First 999 /Length 2642 /Filter /FlateDecode >> stream x[[s[~ׯcz<8L:qdI"l4T~ 5L8zdjyb Y2ʚ^Q78DcY> "|腰cXeMd8p*$Y d'DI(p,2JVDV(R6B"k,n"r$׀S4(䄊B{( TƳ9Ql|<+2Ã{d WsnPY8gƔgI9)d @Z e Pi kX(a$(TgjR.WW7 /jfan燋zzx3_Z}~>.%a9 b:Z^^x ă. J~?M1v؜|Аjr`4X+mW !m5{*n\m3A`w?Y.6e7a g04,~îoX27`>zZN '5zzD6]}:~5΁:.@/^ޮ&z˵*볇QWSR>DxkܿDNU;"JJP%sS+\99WιrΕss+,rGJP%[/;9&KSeZHh!$nN^o=̗f{L&T(IFl%cL9aII!%;dqfX&$ {p x5l&(HˆR!v-B= 7"{ 7ùpO@.8=@Yʏrnn6Q4I3:(<ܶ^Q8FwMY'NKDs |yXޑxR6o` oe ɭ-9ghK$z/rճa{A(x,p|)!,dŋ6B_b?-M0('*{X!hsG`MNj3SE tMo(i Pb.q($.vHx~dǑGl HEbgGn!L aÒjӹ2S'): Et{Ip[H%Zv~S4}9uhXt=3rR怉axQL'죤rbsY1sOҬrdsCP9SLC Y+'(}BaO=҄o$GS*r7A=-A%;E$XQt9~I&px^f32Mh:'՞Ѧ.|~5o١!kMhM :Mo}_d9OAKC9oΑ'h}hur(mv%> stream xڽWs8DfbU-[fB4Ms dڙV`i+[߮KؚZغ|w}5~q=0bƱuߋ'4Q~}׻OWq1A>a#lD`Lj[RO+5¦^ފ0[0#[x. ̹<v*쁔s <@ gD[}PK4Ylkztӯdezva`HFyH6@\| dm"0C"d OE&yk?; 8(SK#&]|~,SZfV"2Tp:sVY7י@0==RDnT0T:O_۬6b Cyw8 ը^v(]# f0G 0>?`:GSo.&-#Z>Q7ṽpPs RQU?fB[ooG endstream endobj 1231 0 obj << /Length 2023 /Filter /FlateDecode >> stream xn۸=_!I֬DK&E-{mѱR*J Iɒc{$Ha"pnzέ9^q$$;{ BD#,M\(%!a/6$ 'yqw't.#ౣ ID_EU#(H$LCٮuk EW D-wcgX@}q, =sǜZ֡O'](Ky2@D+_r?`5tߍV3| :/wL_ ;:U&T?y>k=D>rOP/MYTu 䞚@ ]C9o;ܣ}zg&7?'|7u/%I!%75| ?Io%dc= ‹Ol| gtSap%Q0,\@eo)y5c{-Z.+-*2m*ilDYj ;ו݁ ƴ놑Rv>.(*FcͮL#(ڕSĻuV QaFh US. t+^G!矱Ŵiru-| y8PY|=O;u UK 1r endstream endobj 1246 0 obj << /Length 2040 /Filter /FlateDecode >> stream xYK8W}XCQ{`A"eZۜCJbQ=Nc_XRTWU [=Wo^}>W'dɒ( kƩ ?c:D'kt;Y?ԇrNzc8Nہ֞YڟmQ c<qRZ]šSݞB:{tPUװ]|ɭMZSHZ(^:FeLGbD=NSKE{QֽR:b{YMa&y/V9B|u&/1*مx$S_bl $Bbxn6,p,s 0p?Át̼Hأ/{(vmU.߁$l ;Y:x!3}bT!oᮮHJm}l۪JuGwBiCh+_М)Uɚxk(1sq9iVA0? wp 3?J, *,-1jq)na `~MBF`Ru-K%{<Ϝ c?g9cEī{7H$ʤFD~Q),>KI/mᆻȹ#!tRwb G⊿ K%x73%^.KPY8*ap.2CFJ~> 6zLd~cڦ-ߦm*Z/xV@F[hDA7 7T#]#8;EAHvlJGp,D?<`̝M=FiNl\@ѸI>g>B~RgOg1|njD3app0g%Cjg>9|RK i%7ZbY3ٴv,u 6 BQX&~1N'zo{Q5N4~AȮswXM';w0GiQDh‹lXq `It.ϲ_ & \wKEѢ;uTgGyہ,In8=/Khtw endstream endobj 1305 0 obj << /Length 1585 /Filter /FlateDecode >> stream xYs8_LP$N6M}h; cay$8M'"K߾56&6>> k痶mxȳm m86F̤005L1a&c0>rNp} y6lF\,a-׶-AbyEnt,)-/))-"ǵ&a$UL< y֌rTQd_;[oh,cln jb?Kl:Z'>?X,Z$&OaSw!n\|}L☏a QuIV;.1m"?˞4-/>;\6Xuf3pe C_Ux'M xTuZw%c,c9?/9^ */l\pu}#LF37RVqg2TP@ XًIu墫F 5hye_( Z(Rx?C]< ߿~uӽ":p"^y8߮dW=PW=}>M~괳TE}EoEMs8M!ަx.Y#q߿8 %{aC5`ny8JSq?V?hqܝѲk-|*5ˎO_#U{s[?y:1ToT!$CCܶqc#Kџ6T8qk$a`,ujןm5=SS)TtٮRBF,iڑfu| cz,l \m]\qg\~Nq}'% D> stream xZr#}W1yƭQ*)J9JdrCR4Ȗf, gspF_0ޗj>W33F&TlrI"TþCD﮲Hx?WOsq2jnzl"$Cp6sj0U\ ڙzC%kPR<$,@(`Q 5dB`cBqP cLGmfG09g"ɛ ;21IpHDQdb&e<#H_* MTRI2e3c"TɞHdMJ&Gߞ&1V+a(r)^ւțBEy#L]IDєQ2e T`=ˆ IplB07 &d8,<^kSφK$4n Am&b2ӨbTbSc  f0F L~$4Aj(xZ<ȸʮ=!ڞ<ި*cc16$ #6|22YDdbΥ/&ͅ ifq~w{ob6/^ VK=vSHȜm.@F&K.1q:L~|}b&oksû?L&00_1lX-Wjޟ⽹.&KX r}K@f@/6[j[V`VNT*$9+rVdV|rݮhr Oɫ .dRm -lPb%Z(Yx2ۢw7 E.φv,8T8 v^+frx|R Xl]~Yoyv,j$l 09泟xDpeJٚ>\F^&`c8 "uBl.>z>ոb6s`st:77rDہd{NUnN[ެG7m2[ 3cӗ %$Z!{]MJ_"́Xڳt/{u;]F?0c-5lv%6E*X 5tPnXo/qr"eDLeYq'ӕČ{;e_6!1\dR;Lf1? %Y*Pd,j_1?$}`#B'9ʚ!:B xmψfIk22?ofeS_R<5'VSUs٪lfRnT*$ EVA"{E+Wd^"{E&E&E&E&E&E&E&E&E&3GyjL5؀ v%;%h3"EmvyHبQ+1s5G09lbxe>}|N׋dgT'Ge=P^|g}[рp{OuAY;V6 XۛJ@2X}r3VcxS{6Mw@xZF ]Zb9|OG2iijGJ e-l~:TJmIjӚm9%ԁ2:\Yhy.3+#m40:PYhy7v̽9P[ N 5+!5& {RfnR6+6ff]#~bUDOoF[𷂅#leĚO 3\)my'Wt cY0C;輼1"Tz3!G}̔ǬĴǼ)S=-W=O\di-*bg*6ک[ܠO;DZDCh_-@RgTV|*4cQSҦg ^IlIwU Al;lD>aC&THn@#%=> stream xYO:_QrSxc;1m0q4v5ĥJ.I8vҦh BȎs;NfG}{DRP1LGc11FܣI<'IYq:U'?bc#Z&y-fT $<_o5?(wc`5v)N)vܒ F6Ϡ cQk89d[ZTLf]R͌L ~-Jf1b8]ʬZic컪W. dLs;&Qyi\APKyd~ 2Nq3Slx0tĐ HCp0_,Vd8s0V==CzoC[_]1",@Je\33fy\ZÊͰp%C!ͷN.U/ַ&hFg1͹ m|)k4+T,2G!o@fa1f91 &&_Oz8R( Q25\L40 t(;T.TX^jL'#h@XyN6PrDuFЪgyN^ȓ-Uv AYYb1dQ}|aڜ Ԍr$U놴vLv6R5jZg$]ֶs-N?j;joBcpNQh{L:ZKTIYz~7SP$1լ!6fSsR񬩢4oj^%mKĖ02U *[Z0L˺|Ɣz'5|)5 ,EuՌ` kY|} Y O*v)nGkE̋.*iՂ׌si\t"'PuU{(έ43+XnR,\U%aOq @s+6 %Zluo,ř &n5x {`s,s0$}SSASL +M6y )Hcڅ.M.Z+QS@F)Yq 2X}@,wQYH{-csv`DxS-$beul Llk"G[u7nT$j3.HΡnB˾;8xPYƽRCnh`yO}@\zkz Vo\A74xWtzͷ!E++6{" ޯunv@SaQ>/G.F梉i;JkFXuyuqА!A# ICzxw^__2d3IFT endstream endobj 1369 0 obj << /Length 2282 /Filter /FlateDecode >> stream xڭXK6ϯ`@UEyHmٛT%ij89P$4"e>f,F|h8ƫnpۛ׷7߼c/ei,bv3ƞ9n /yHR!c78忿x@{KǛp=VSEHхF+ÅQHNwy[L,"A"؈1p#MSO(a*I5XlX+}uo!Gm6":hx@iC[S܍u+>c6;jf#MB&ۊqam?]vW1|R/0Fj7ۈ>c ނC5.ωܿV;_p¥s{e}mٗ hEk<_8_*y'wg<_ˉq㐩Hbb xM1KtIׁy>^&үNnmڐd}}[j{tnMғkmz g0cP}(Puk+J p:t`@i9 <Ϫ . Dю.'b <ͺϚ QK=IeV96jYGjfb/}a%VDdzlY9?i6=*q!eH%r!ʪ{"ج%d^% N$cN5ɜJ@>ِ0kwefi 1iΛh5oq 'f} tsV5p3gcK֏+ltB蘕HE(~lbVQWp5WC@S` *8.rԚ𯔠]n dQtIXuE& &/Fo9XDDŽXNCpQftǗ֮V'aҾa4![ 7Hbkv> 2GA>ٲ8lL j/s.(J-SG;jU&$zMU 0vB-JfD;me(/)PWmQlPuC(L,ǡVQN6KW<DokORb Р7MV$>|.H ͌#B],Ŧ i,R J^[q(ɂI -*b˛%O ɖE[]e+`i8ORwVuJ9K˻Z=6U+Yqչ.z" `<M"遍?pwXcbŢr$62+pP_L`f8[A7.aKTXrIb͓/P+#)K:2i Y} LO/"}b_H]GcQXFhRk@`CהP9{V\# P4a#BEG93<`7+<#e~T>uia:z={\g*f(]}sq(re-v!dz YGؒ Xڦ]ͲB% endstream endobj 1311 0 obj << /Type /ObjStm /N 100 /First 1011 /Length 2580 /Filter /FlateDecode >> stream x[Ys~ׯcݍʵU>7rjm9]~QD&j} ލavFJF_3b2>%(F$H΄\ odrNGt^#; D{RR(g}- rNߐ!/32DEgd6$J)w~ ;Wf>ԹŰ~oo8N-l8GE_vE%AQTL+lR Ed] o*Ire/`J%PlpYd UL%; `fN2馰UD(ѝ &Fs}41:.X*$Mr|1ɫĘvr&V3^bLlR ^)1);XflRd}l 91corN"S\]%^0S$o)(gN$3bɹR`lJPΩT@+'~dRR2ޤpԱlU+tYWr]l^ȕ['_yp]jRI ަS"r:/ /͉61MUW[Ϟ<9sg&OlryqS_<<[fñ>L~79<䢻ژ$F± YZv*qO͓'fri&/-¾xv|X|f^|zh Uw{Ǡ>>[M?t렊 K8 jpfV3[zd +;nK'K? 1nālpT= (6,Beښڀs/%.yGѼ7ug[n ?m$>nppdph/BflPFx^Pv` Q +O2y[#(EM|}Mg?,n&3B|6=bG #?5ռt &; X~h~pr AȉBz¹ַ7CA"h`SAfs MΖG8oo|-6y^%ٚ$8bHV"R Oh7,H,)X>oۄ!BcΧ忇5iP#}\":U!ǷN?Bu8<YC!?rlk'Y5 v?,53tF=O qiqAnnK'#Y%R5Jx'wH!+${R88qojE#p$I= 2X~z} Flh=24CU N5hMZfQ}9 4tZUl*3~G tZԌT7 km@+M~q3fՔbR`︸޹hajbT&=Gk⮕L^-+"F*i"=6C|V[off+3yṁuoְtzyۺvl>}3UBzdAQOo+0z5mW]AjbGp#eGkoDL358SL358s̍378s̍378s̍48vP6@v ORʑ_}=dޑ!Y6m}}Q: @cC+ǰ|PV Gc֮zH/^}^8N*BJk#Gu(Z<8X]~ZUじOzo0?s endstream endobj 1402 0 obj << /Length 2864 /Filter /FlateDecode >> stream xڵZے۸}W-T K\xsfRnbRN\H'_n4ƞk`ӧ!/%W}&UBRnw߼nM+(8)q 4ڊW5RϠRB_ު|zGL%Fޝn{ADm^vh;hEKIpJ4}[;I\cyyG_Z}rl;aM9KTQx"/oHMES4$omk?kxhM[wYVn4mX [^wi`_G ;SBzqkٟoֲX"@PzG#, G&S2~-50824tAtSUz$}=Tuڭel,vSM6˫na ICN -31Jҵau७&6~w73pT 2'f,~1џuu3}qX0;K5]d*RD <wv X!臻o}i-nKv.'~%p|)ϱa >鴵9iJ] b.m24io6?]iMjjv]GUuuM_&ޮN*|LCkظu#K=e@-8 UPq m5@z0fЂ8"ms7F lf:;d ^-L6sr4cG K8!QR)'L@MyRmcPzZ)ɽ?,"#c>Oh#*`cc090[A %LxM@UEw,oHl|QxAׅ $\1,"/bg$AÖkP(p~ \~ULY#qL`qi:áG9rٚvyv=X6> IdžY2YLjgL1aR + OfEIϱ}t |(6Y>6uRX~!%qL8!>T76 өC v&| C=0n`+$/Ke4\`Dhᣄ4;PZ HsG:фq6*&٠&/8aq!*iW {3+aܨb硑Ģ(0,@J]ѥOɺA͌ͅl-D ^<^;QH-4x c>A!Hmߡ̿P4'XYJ1oԴY&yt. #~l_HɀIrY(/yeg0t76GX#8Ӥ# )P8!"?0 LltExԲiXd8mv}{ኌkU OeO;`zwFJs!ܛL  =V _Q,Y籒C`[TTw9ԃghPU ^w2NPJ}liΰu +CJ %Dyڸ!E -P(d+qm`7@ u ۢڎ򋓺g_%܂guu6D{p]!]'´a?B~S|k#I1Pq%X XXMVbXxz:2D@7i p,f7izj1tߕntp̅w~Bc-l.HX4 b(x2<F_˗i @$ğ)F@s&b$0@cKQL&W0 130oFP?# ]ً712Wӳ`D  W#h@QWP 7Ϯ sQ"mz<D'jp.Ee.CWDF0Q2LT`ҐT%jv0+6&Ȼ"Z1cX̱C؎aIrkTlIitcBlcY׾* Y /5_lhYbF02VvXz Vh gAl,hXcAe JP'Oyь/P endstream endobj 1443 0 obj << /Length 1732 /Filter /FlateDecode >> stream xr8_e_,,Y20M <\GI8vlBfg}.vl7&[$+:Ωk-zu٩[|[3 .oG˩ue{tͳӀunzCahԕ),Fk p21 @iCB^BoB#uUNjzN;+ȸ0^4p 6L8bW:שm ОRSK0FYQĘ wk%כWu\ך[ "oY՝s5* aaQ|EF!aka8vp͂cRUZU57Fid'(xkߤq[O-\:Y(a *Q95$ C&s{NLd0]>aҀ;ܠU|$}C9{ L"7z%/ĸL6./oD9E#ZYXWz6̚@T 4x֡6֬}ID}[ *yVJz@کy*w:+s =6 3%QEq\ZԺ!*ŎU!>w&?8X*IGBƈlgb<ѽBp&>8y]Tm jX& (LçʝMG橠v_q^GZ1ǭmc~Z!]Nj:EQU'|@ĂCkEP+ CUi~]tD"ӥ{,(v6(7,>m,jpQ5o;zLEsIۿkO>4r> stream xڽYY8~ϯ0֌CG,v6, %v[Yϯ*)Kj'FETUX`qo_}&Vw0"__tUW\-~MA-/yq>y\ߚk'_ϟ/oKqEΙ#& Zq,LѸ6):% _~޴}M4HF제,R=_0U4{d[~IʢHz lum%/V!RO;]?wH:M۵S;ݶ^ t:o3X B/uٛYDqTϦK4Gxu}SM6MVKC+[siv譙Y]},#DP-N02v1YY+wUk4(i . pf-!xpȲVtoAMhZlM"`iP$my!.^Kϖ-0);:@̚]{`znA7pimze5N-k8:x{5=X *i $j+B%/mGO,xn+< r_Qt!jt&k'?lk Cdf`@G)2@YnDC\7[oE 8UiږFmЌN#ƒ˦˪f4$c,p;YmAʐ61}k*}:S 'I ̡}>P沺;?Hii&X#c W .Bd"VDf|!9PKzJ N[uU!SP(Lз .B]u|Pl2'm.:?P? f1d 18,BvPnZgᓹrTNV<l>[AH[y*;ʎp2մpGަ@3%P) gfv4iU7֟g fٚz݆LpJ0a ~GOxl"%lIVpR>K TepSM/-p)X)x8Y@OcK3X ,I XbinoM˼oȽ`,&wM pn sbky`cY7[ ¡QWYt2f q|N{ܙT's6U7;\}l@*4S43|Z({*X]EiԶn;8܍++t4sitњYIHF|w}ؙUdzM^,V4?0[Ok{5e`yI0){@Xtۡ)<Rt dL#V >3k?d57b(We;-ZlY3C]}BYuhdV5Jt}ۏG) ⚨, SX55=<+_ (g'cǮJD6`VHs)w;0(<%8bRʚڝg\ ) 5uU;8ieW;׻ RXp^ҟ&obeʵ0!V!~"F!9SG@-ȕXf8M\?LevTEY{}Fx ᷢ ոN<^BΣCb~2_T ѼVcbzPZ] J*RΛrN>e0e*_keqCT(cohWAR7Z9P_Z|%nw+>bha!O''3ϛ@1a?Nf endstream endobj 1380 0 obj << /Type /ObjStm /N 100 /First 991 /Length 2714 /Filter /FlateDecode >> stream x[]}_EZ*X*nBv,{lӪ"L)=զAImrR'bmB:6IX㝠-p*VY1lγY?؎o(_3+KJhQ=$Ed 8%9$J\)DP£Caj' \U*쳰gN=%h)P0@0N,]E=BBg8޳Aa6*$h= ':C X\xLQghU!>!^qPr}"bJIE"C**֞{A 0Y2DŒ_OmΫ$瀖AHQPJk-Y UaNGlhZH1DT*->ko`vO*Kpi:r7*P0BS(0xq Fjb>`LQ%zϩ g%xUvά_[⥦ڴL :ËhS&ULV}ĵH:q iv5lZB]YDĵXgO?=R/,קQgj+v$N dz7<ݭcg$ݳ5dL^!X0^ZÆ4]X|:ak-9k8m{1lTcXc/ soV08f7z6]wKB=zFϻKywwb;t[NFgbv7+WW?U/x#W`:xx%XXx0Π*V "+!&H\|SyTjBnBY 4i.MsiK\44e#V;u2:{Ooݼy9idt &͠ V;h8{>Sήnyq=t0 !"&|v04|tv[vCҥ8%2:1v9t9 nV1f( F)mE3̀8fa?Y^ݻ쮺pprẚhӘtM/ϗew 0 xRr} Lh |n> 8@f)jDam7dL ay"u0m7'ӫ܉ 9|u"9qZL@3~/`0,b$@rq Y{-m2+?(|k|ZCHkxXo߷B*4FC#~hC4Ǧ96ͱin[mhZhcӜ495ͩiNMsjSQ.H,’,q?0Ec &vHǗv`Dfn\VQ܎hv-{raL$\-;1{С&#%ـ dBX Sv07=~byu,~6IQ΂t ۀ#@vx*2ףbb-0 "x\З1< x#ڋym%d[5!Wcfx XR;H4㉛sF 6\6nj\b8Qñ>eN9!mrp6Q7njdvDt6l67w*-n|;j{36#oT1G*MVC [9ؼ4np ז86 u48,S:)=cTia\+> stream xڭX[s۸~ׯ}:+$^2t6;C6 [l(R!H;_sp@䬝d\xw>syx^"'eiD=0rc:w>᪅gςWv ].ݾTzU: ,ByEIH{eu\ s6߼JeooTKjq HN'Q8q,S}m`ZnJNL6i6!!c;ʲNtW_{,)jf7w9f \tzM<֏j‰%2 R\6rgL1  dyudsmn{?o7Ύ>n/\/>/|X9"XN[|99|MOYrf2m)p(!R&?I)&~BWXz !m:ZQnDYUYm\m [h=E@tʺV4R=pes ϭ7/}5\?<5V X /bI7JgMo: # WMSU+ˏtHċ 6W#`2D(37]tDZَk5 ֞` 0XnjTv;h9oʊݸ dpK{3 }TᜆIw ~i<,1b?y[qXܲ*l~V&++olDa-fevkw @ՍR2w+{'=N܋ՠ^Lȃ>iզ0Uz*8~㢢֔ܗ á +Vhalݜi<.%q_46TRA9jl|dO6Sp:ЮlPmS0dLk+B<-m&wjli\a鑆-L"8~ykfkXmPϿ(](z[%D,En lUk3+7HLa?zw+ꑅlPL{\k41z4UL@Ծ%Fm5M2'ɥ`4*U!JX$nq.N}ʉp?Ǐw}Z9ѣy^ endstream endobj 1544 0 obj << /Length 1777 /Filter /FlateDecode >> stream xXo6_!t/Peli:u!-YcmRSߑGʒd[`0;wG[Z/ϞΞ]8pk+ (]ǚe֍_, ՈE}*:{=Hj%gT2_kqoPn魶n>oxRƎOzɑX% ݍK!jH& r!j; |{Zc8B^DV%g.#ˌbœjE?R\^F\)R lA:h7qF"Q{Aʌ"KFGo1(fkE)%q1>JZr睼(ȡߖ֊"{ys ^KpYd!'z*3TfkӴ*YS-ΠO*aT@׵>_ v[J:Oet/5 e\Y5?^H\m7Vdwy&/xu9d֨ T@m\IV} VqiiS0 1c~r\I7JUd]f\ #XF$d!v^h뚯7FrDMVZO*40>D䂛\i}c54H&u^w%5@8) r%&K@,8+ɭ9PijօMU2 nkeS hs)@/M \VN;_oV|͋Z]XLC&r!8 ]Ϸh>RY@"hu` )]< p^Siy&YRR l!HKxb8g R$EHa'DOxN 2H.b^`8y@H֦&eYsm !/_c\ZVEMBx>(Qp Sר?-/ br{.{'ߍSHcWK9-&#>Dy ?PDط8!yEә"á|AvL!_%⢔AX 9i#gw o*?8Hڡ Ȩ:8Tt1w]H`2`E;GuPDžŸ jd84NNh7"D5/cmw}2%'p~t59dxmJ$c+ i_RM߽k>>9T#p:?ToWj3p3{uT:\Cj&y-F(xNt*1Ԭo@חo./fGp׮|Hxu9D2j1~Ə׻0}v&ׇ,dmou_= ㇭_"9m&}9;|Xt l>D &P«}-(۠Aje]{ K:x) X:.PSWH8]40ojm#$P{J`_EP#:j"ͩiHMVRs.t^eNF-Ax>k;r޴ $PM87/d)U;K-.m ԦXH)d_ cֶM1MlUo`N?Ց>ԑ:Lg1zBp+M'(k27rnٜ!ˡWZ`^"??{i*T_tP_~M_9BȽ3_@r@ endstream endobj 1571 0 obj << /Length 1409 /Filter /FlateDecode >> stream xX[S6~ϯ`eɒiز0teh_؝c+MmʿNdIv: ؖ;G& ɻ3Ƽ,dAegHd픈ٗߝhM-e{Q.+E: wL~բa=g8ޭWl}|wF6XX ~j߶3|2(Vo2m{^~u^ $Z5WVS*KRՎzPxŜX!)7Z*49"GA!DʑGA iluie.6ʦ[O;Y:i>dJ^6L2Q-Sh$W=?  8 ds4busBtF۶YOFf6J 2ϕlVYf>U)y#='Ibj 1̺\'ES̑a"wkp<X/OHs/$H>eisc=_+EQ@7%Ǫf BoL6O6yU_4WAerz Uw/xuLDF`69) yQ:#mM¦*ޚG1o|nmF@`c˜?qDy*lQ&+lWrUOs@T>?VuPuwmnd 5oeqYZj%w E;6j];Y7&X;a.t5xlVDb=jҕGr'^ =C3=8 ǧ;|!>Eu/}aM2ȼ"-fhD5bn+l:W{%:GSt#DzW3X*(]X':z62 3.J69 KnIid.7:0T/`H @bϩ$fΜ^Sƥ,|J4GKBlQBGcCF:pg8Ts˔q?4/F]׼0/ SKٱk A&EzIX~ʼNL'LˆE=>d i5jqdPdԫWLAls'MbADPۛDվ a> caޖ7;DXD d1 Iwnd-Laa|{ Ŏx!]hsD"` @ROﴪ^g>٘`y! endstream endobj 1493 0 obj << /Type /ObjStm /N 100 /First 989 /Length 2419 /Filter /FlateDecode >> stream xZ[o[7~cBs% $1EN4J|֕ I&~D1rdE 9~C(9?l rT/섲5iJP䊪5?#tA+Wku-mbDS GmU`=*HbcdH=Ԁ妪@MNd8IkG)VuEmȀdq =BG롁s( uBk%Ǚt5C%q报J Z?شDB֪hԕfi  [Q!6c]T9lrNE>ZےH۸.Rq)ַ1` DlPLL.e2pTڊ1#;'7, +ܸ,ao hKlVY&&u *+ktE 2Tu1DK"C=5k6jlxrUlbMStTbNB3Q LA,CjnbBihϫh ?>fOhݦ}ףtX~={ۗ~Pa P(zU8ᇈa/!=~f륛N>,g|u2/7߻~8¿oÉ}Sw84at@$zy'H OV>^,~R#`y1UnAŰ2c~xُLIN* Ftwf,r|3V߆ (H/>%[5X-ݲ:OS/ vRvQG3*/ ⭀"τ$Ƙ`ĺ$D:lb."jZ퇍I@ڃ$K5x˵;@JR{Gj x3$ْ|,{ j +Q`{rS%oZ[i4a&~UZcq+5UiFJ[F:v#JŃҊܧc$,35z@X!V6*%{{cvR7:ENHRꄔ:!]u=pܩ.w5s]3w5s]I-#B/Z\C>bӥD%~}t#&AĞ+]{E> m>=:> _ W9!vd *X)8ܲ-6Gkrq~KP >J;Q@`}Hm(:}b;%oG(=AN; [Iގa_0p!"~1d1rpQcv!lml,J|0X-Q4bٔP}7+~#*CnӺ/_]'p0i3ُ07` WpxfkU"L]aݡn9. }Bsc276!`W;@vCЁRLEޭ# ƆSte-+w3Ҟ`$"';ٗp+؝+-W::路 18ƻwZQ:$-J"J#$NR)[=4NZ1)֑$Ƨ2N:"T*kgS9~YeR\{^ok۩WwOOOO]sS\kHaf{ "pC} K@b1­Žc֖S.DiL0VG"]sEr3)cŵA8 o3cm9܁Ykٙ endstream endobj 1649 0 obj << /Length 2377 /Filter /FlateDecode >> stream x]s8=³OLK"շ6ms&vu+K('Ϳ?dIqr:ɘH@|#: "<,FR"d8R!%ࣛx~)M8揷aZ!)#JT3Z!GSb4 W8:^H&2lm=!I&S+3-`ml'k ƦH:~!DDr4e!QtntGϝzaТ9m`L&S)/Wk[}%˫,8ؓ!SEB5D>|9Q']t4ylq)̘2F e\zE%O)Bdߦt:m#jro РlG'iEf_)8!pZY ~x*MuZvW$R@w.EٖYQr]dS{@=$MPCpE+TSjSE-4'<?$wpƻbntþn ".)[a(WmD`qMkک[jJ%R._b(z|M6w-^:! +E|O3[f$ X p!~^[jN>NQH(^ޅ,Eن핂Ee|=4,_oWIES0H-XW3@Vxia6SVzA4l؏󆰟+-:q;Eϱ_(E4>`%bVl%!sgm>Uwp(J%e}_mt+矑+,*-AKy, bw$4ֿHp9ߖ]˸ZPWz\;QGhC$88?b{^#nHv\-x‡PM1L7SѰ,d.evғ{(򕇕5^x3NN3>*Ѱ'pHQ  Zr*$B59 Ed~,/~L,I(vq`6ߝ`D/%1RnJ4^*=x|  X}dxr> jof9w5Nz(و)ᨚ<2P~B6Dt1@58GHn԰irwH{/EA$Q;]W&ǡ2{"md>TG*GiP lDx *{!͇=h[ILl.#l]Ρ} ru<% A7T^-{1BN)Mdubg9%}8N fPT7A@tn bO?gٲd#xSKvGz`z7,/G@~B~"1ܞbS))=Ry#rrgt+ݗu^9d" +37vo͆! "׾}(U~ZNS9ZGSxZ_(2 P}x"r`A>T ?DШ[ i.D(B=Ea+odCў&.]#*).8䚨S<(Oz7ԯ+oOi_ȞhߩMI/ y/.B~guYT-4/`=P))||m:>U>M]DhKdлw)|9qܞY9%',У_t4KDGnj$AēϾ> stream xڽXKs8 Wxrg֬HzI6;t{%֮,4 l98d&?ĝ\I@r]y~0 IOLӿJ/̏#cdK|nU}kO\{4vDNVj qޡ]UY1Iut4jcӵLg"2)wUQ%P9f0`q$:i>JCh%.n *;@LZYl4UwQBX#Vs|&`Dž翌ʯBp !V'gd28iJmU7!'p~f]WjuN {p7lA"/<JtUCd,?Ν?=:DN=ϗNVsUp37tADBHį3QĄǻoхF}@ײ8dgG3}IV=BY?%9 8;YgÇwQc:H.‰Dm.xJG@=\S3۹S&aztmu. 6w"vSabu*2˻xƞ \9 2.)YºS*f~fݳj- Xߵd^,ܶEjb3c:Vge/"9Ho4H2h:{j[Tىmo9H^PDESeG0NpN:'_+0׺5)'4Xfd^Lh"-*+;I%үuN}`x3q]ܦM~YQK4!C|T%`I8%]$1V\-{Rp' o8 C8e^6yJcwPrB=l7pX[Kl~㻢f|HWIl[_ --fY@  ܇y|&8< & lrPu{d/@cBｂvnTG.A[Te9SgɟŐu\2 ZՕ}526(EPc64dh}y(/Y V÷R%T) cnU`Ni]imCQ vπF#ڒkݕV9yZ_b,2؏nAlwC24Io92S@ABu=, ^A^?H0,ǏcL MC&?E7#X{ϝ  e[ߴڄ wF2FL*έțqz;SON9ӐV҈_BSpevp^wrRl'+ endstream endobj 1712 0 obj << /Length 2522 /Filter /FlateDecode >> stream xZs6_=dfIo2M8C{sCI+E*.hGRTF@؏'٫g?\p$j9MT0wo1{_6;?~ sbN<}&O1Zq/i`}o>M[psI[ME{2߬ jJ/]){Kg Uy/iX ڙ}J5l;y=M8wGU-$&Sc&1 E_VaX-FXTLVg<7+]@Xi$ O(6e咞Uy&BﶙZSz3b^iҭ)WY xd5[m:]i3PF,!J%aHg m*+7B4ԩt;_fz p'LtV?O*4:j~xlsY,xf˟C(k+1Q"웹z]VȮ'Lb(@ Π '"&Acsju#, :q.pD#,Og7m9?ПQ{CVbw벤~$vGgEُdI}̛  "N P NVx;ZГrˍ[tVЊG8m+.RĐO0tV2XJT"S` z`ԙ5SQ['wsgTPc` *`8s׺ #}G ׼B P4q1b}=ϻB`|эk]4`~Yv>alX^emt; Z@n- /t :0xE` HlwY-A.VL~țA;(haL!b*}< YGXpk8Nq ΘV&<_@镅cl<_WC/Ӵ/ )jp=R,i@HopR@^_p!bO ,v .%dzrWRVՇOoBxl6=೷򧑓L gabWY&M $x@h֨)KŽ/YJ/h'h! ѫۄkXQ } PhK _4vpp5>{7A T;iS &2g%jB96GA8]{~Sh#ؾAutQ+lRP 0iEAMGĿ(r7vsFF۴١?ӢMI,+Ȑ4NBK!ڬ5M%=YPS69f3kc 4%q_[&m)u0nJXf6B ĖI)82y5]s8iǺ(Coo(gee^S)|-!YD9}WnÁxպQSl',+ũubu%/J44t'3dm:8L t/I !\Rx zWQ0.cq`HĐrƶ2|&ac%wXb`QZ)ﺇK7qg6 I^yi: ]Q_iHW9B',S+(^l񎩷@7bam_8fܱ`<Or} :ŦpHk2SCeo_PsiGAwe=njFoD+{NP?!õuAVaW"6S|6Ua<>#dh{kge-@buK2 _ .hR&{" @&>~l }kb .AfXn|ۇj(Չ[F@a|{O5OlP{]ZXǡk]*"1.`w`<W~D _OV|M];! y}m 6qRTA0lTB lbY^OXO$[r0aJE' 9# O܁!FOA93y,Bcq·|Wo/ Y,C/OB~?b@/.ȣX5ͳX;0L s豓>m[=r~%ODbΣ/֗ #2!aDܡcB,~0fal[_>ªTjG$?#L%Ty;Ѯ}?.cVegE?,,{C *Ugj\!?A봢a{sYNEP39U})<4fW#/˱ZS=5K߹v¿с+>!o~ճ]  endstream endobj 1580 0 obj << /Type /ObjStm /N 100 /First 1007 /Length 2750 /Filter /FlateDecode >> stream xZMs7W{hUTr*[I$J%ܥI/I%ο 8J@3F7|8S&ClcS)Xm2lBl xQL WO }*@YhJCpvsbI?U:*ȑTӮRyh&P: JHzDXd³&clH + T>Ig;vPCa XŊ(7KN]pPueQ{WLU}xgey= F> Y ?k2pplRaXp}gp& ȘY(L&FC lrnߋ̥Sv\B5sEp)W vI{c4%GᇿRڻd 7F W7t^nQx!7daJҹF|//<"ubK|Kmʒ$' fP1u7LySCx=BT {|}×4?^Hjab!D_}i,\ژטBLh,o-Wy/qU~yX>#]h\k*d#BIZj1#[mٚŊ:d`rk<1 ^H] D8>yt >.|^\ [L{~a&/w[s/o0a8a݈c6YݭoΛۻ y%V{!oK}k *kt\ia^h(7Q R#jd58uoT"WE\*rUUYBj5FRj5+Wd^"{E+WA"E9(rPA"GE9*rTQ"GE&E&E&E&E򯼷9z۞/s6yZφuQzo7X~=@j>+?mLZ\,?].g/,[{9n~7fgYk]XR,wٝ-ÿcxNl5/DŃ `}d|7m~T 7V*MհNĥ|"v/,yYѶPy]W:D6K BKazGlgc䓷8`8l(}=ݜ޼] ](CD7ȃCʐ"Rǟ܁ wXJU:$th6p  K>2Z&1?2O/mBNM_O4EtO+#.":Fkv}>]"[#mFl#6qJB-q*ϧ۩ݕQ*cJ^"Jcأ"zȕwӑH{&rξ].:Ԧ69-ożF1`}fj3D,$ "1(==!%Gͮ}z31 derMbt^cGmv,xrdd>Ns) *#8͑  Dz%5h*g*PJ%QT7xj8 ,B9g_J4"^"v Ǧs0-%Fe"DP齴SWC(rr#"@&c5%~LT'erua1t_KQ L=jo MIQ2C WN]@&F)hzXpˁ E#|`[ma{DrHz?8%[qBOHi\ |\s Jg2R,ΣY; D1lNrDP[Uz E '*ɑNIG<&x§H.{uVTSNظy%"͒s%A&Fz K#LLVч!Ys]`Qa;jvlyFDiHa.y/z7B=kZܽYXޮ/ubK"@$ ^ ˭<ǎ!I#trfT|Anwۓz ڙr,b\KQdMg|ϋB28U=ZA^~Xz+r ٚPW&q\r־z$~(C|_ bM"jSDe*RK_KS➺Ⱥ\¬/y$O@<xL1j'J"A[M$(<(~$V]{gDT$[vi`9u"L\~n𛐘#B5ZdW)HQVG,ʸ$ƶvq> stream xڵWr6}Wp)!$NbN:!EA[T@ʲX"eɕ;x,,@\vv.lkauݤE>rl ׷fdf}|}ۛkg>zlz-O*U ⢞msګ!p6=īu&c+׵BXZ:!s#J|0lsTl}VZ5M=;_Upab`$fz1V]UI3ӥ^{fbBW\ooylj~?O,I4LRU"1VJ!hd M$MneXVt%Kc@'y8YWHsg֚J*FIm&T-ǩXM\ΨUa&PdstY\sԁvzCН;\~.a}/G㑱1ɯgHYZ0tƸݏeZ&pMz?z-37 Lz_ >¦LDSW8H̺}:;4zZ *c`>Qg=gQT:JPݮ^XQ/Ƅ1ZPA/R =-J%ށT9 r)D*v>DDsCs_GkR$8Ny D vrN,Ŝژ14.B #:ϝ١8 un9{ @]I65gr>p> ,X8`W˸")BK-Z_ [5l|vЁ,b@"rӵfuMd,OVďX "rtjnIQƴm!2G36WMsμ |X,jH|WDCQ5d>rG w!mR(&e<_0)RrUl-DALgzByQ2=o-j-nY) )rM}⬯v/}0j&Pzu轈g 8="8&:q !<&t`7/ODFJLLT(*NU3pU1zxe}+ -[`XE.K feuGAh%C{Z nC^S`IٷȳGЙ<%_rHh\A/S҅7Mm.UG*mg)DC WU Mcټ/ق"dCٺ46 nZmg*jQZylۭA;`6}U(yrKƣ͇SMA$Wnl B0 d#;@txЭc+ <٪tjqS Ir߅bU's@"&:r/,4I(7u*䯿BOl *6eIuunOe)}V!itU?[w7$[䋬~ӆjN{w͍ kW1ʅPx? HT]X endstream endobj 1755 0 obj << /Length 2389 /Filter /FlateDecode >> stream xYێ8}W$1 CYIϼL-mȒWq~X-8ްL*b)V|ū?UHFJp Zg/WW/߾:ݜ^{\vDdik>NyN0wMeu*=UvzrSCaHX, f& Ӵ7Sk8Gz㧾k**YKMVlKMm:?4?}NUخQM ShN3;9fjVw, C:Yq"Gݠ*3pWFNEwӱ!&S@дN[}ͮn 2^P|Qoe׬asοSw+@_Q cd{&t+$V$Iޥ^de oةZ_`{U0| cxAa S#Pg = /Qt0nAp$F% ɫ3zB`a<@ހq`d!r'Q=-m,àW{=nGbĺajm51rD_3 EP *U MU 'VC;ouufu+:Kop3zH&d2'1jIj" :)T{(0'aQ`F_wvщkg8Y sYE&{pzuA!XnM"˒.B+TS,t R$}3!X +턫}fx4!G((zQ ʚڸ"UT]ƚD5+~Xqϯ`as*$|1)ܱ Rg5XDu0 n%!SY1~pA~@ K CZ(ڤ1 E;T:/%8w|gG!Ky.'1.Cg Ʉ$#H$" |G΍[\97ސP64qg )sG1Kӳ;شp3Aar8Ͼ,MY<.8:?xR=>! sү[ݘ. vcϷ*Mc z~<2 Ƴ+%-;aA+[;56},@FZ785xrzzEj =ڣ$Bz]4iI/r4P;Ǎ.XUc1)bpSQCC29ԈE8 !sSO"ǖ=YHԃ92m̮+i,ljSӑØXrʠJfvZwڴKe`iY`.e-2vZ27@rdG]2LWH2?ucX"a#s>mB>!jH#g 5ON.XߋWHjUqqXA4qs)C=! 蹘\o&s010DrrmV^gLL|=ǡe Ǔ{puK%XǍd dvDO[(4Es! %5EOjpnz/RI`a|x{a)sD*귛:ݭr %Ɂm;?i1ŞS>+uD+=yrJCq3"]wπ0cFtCdv5dI2JbJlX`* 4aO/l Rۖ6 E޺9"D: YN@?(S$ɿ 6"&R \qh67`r3EW|;C./C endstream endobj 1729 0 obj << /Type /ObjStm /N 100 /First 991 /Length 2270 /Filter /FlateDecode >> stream xZr7}W1yF \(QUHޫ㇑8^sC^Ad%.YjrAR1$ >)LqEhr$%ܹ:^\l<| L2ĤC3W9J9_ِAh%CL:sC1Y2@:5r1Yg)P:K&xRL J0}}&lg)qL\)1a7KIQaҭ RpLQ)I? 3RlE=էDJ~'^qW,1g1KQN$ngb#E@/&y=4O: O!')L znB $.a cTQt]=x .'CGd[Wphs}:sHF(1!bʆQٗ|!L2N9S=Cubbk,u rf1Y<krɫt3,$&SBqS2A0"mXTWp %UHTqX#a]C:kd#F:k~KI:Ba8uZsQ^N7gWf|Xn&gWɋjگ^;fdrbc^H6V6Ba[,N lͳgfrf&?._-|sva/f3 $jbr),Ҟ Ͱy~LXވuq/gn_xl@!8 %ُզ GՕ[u&9p䁈ʝP^. 1[.[nQ{mVkJiqnbbx8Cr%> jۋUGF3[.:\PKQ} 08#j0_tm:]{D,m S6C/62ù dftGlZ;(le֛j3)I .GNc[<9Y]%9IRz6(^c[wt}?iMY?;4w܄/|6bXDϰY?Ƿ(?aݕ=P~9X?Bځl__DŽChsmRMp[?=pz'Sȳ~5&3*|#-I BWMlj2$͈\#"Aʥ͊D?Q[-whCVY5@mk ަ2AqK7QA!24 58\y2uB>\@!=ǽ^])ޠ @?ծ'M 5vն\ )ejrT݋pwmTo8jso.ލh.Y08|f c;lvMLځ{wWw99V{8%WrbY=RN~@?uyǴA*] (j/G'הu뜚I0D6*fq5;决c 6%ZV$ ʬ`#7w#+4VU$}\hҌUb#GDUܔQVqr9߹McFuرv> O0br8ayfL^6g09JHZW]/Vz{[VS?u/L5Xk e$f*k_V4a x @ȕx3K*mѻ_k,HWHwMRNaOC,tArGI|{ mKC 9,W8rTuB^JdɏWwvH[T#k`٦-"d|(bmFmW+zgJ-l(ޛ ~HJnˏ {r9&65%Vnmf.wBA 6u Cm "e.(y ov+ *`vFُLnٷrL;D]r1oIMaZKĢ[,;&}׭ TRͪ.owqv 0?8[û8^J#?}ʼ߁Ɲ$Ν#OחȍRq!Vww+x]Vfum"i=})jVDn֗X|+ L"nh`j=J52?f endstream endobj 1834 0 obj << /Length 1910 /Filter /FlateDecode >> stream xZIs6Wpҋԉxzq;u'm%=9PdH㸿 W-#k2 Ax0hdzw׮k(pkmP\1Xu@wkt(EzltH2-!نpiGēa"5>rOb6H3MXBsC $=(mcQϩzA%O6/Ք lEռ~i!>\E^@˭H.b} ϭXp7iDO=gѴ0_nM0w PRVn~?[8 NjNbb?6Q_dYC @r_];p2'2DA^.‡PUY<=(jr,-1s{%BVK^!#$l0,s4c=.|lz4~mMcy*PXG 4l I>Xg[MiI^u[w)a1I)d}It(=\}_&CY^Ͼa.j.SWYo5(rzRK,|<*q$`wB = }NoL{Ak7ixaZIpYN )O~SC0QS=д$f,ϧYٳ( R!+">m"У)( G:qfv9C5/?Edtzϐ glچyǥ w78T $2! .q)/!\n&{n3\$#TwBrHDɣ,]8iZD ui~#NXm L&LW&TS0K'Nos"&!uB_[SYsm9Q*8VSGW0.&8 ̬$%Kx{f2j49B4V4`I c,D+ Iq6>o(ݐ!h0v\hdSGKSQAg) V:ay8FXOAG0!#Tf0B:^h y+ _sPvULq1Z15g`0J&}IYNL E4a.t<* J:r,g-|gFP+?6C@0#UշLMZL( endstream endobj 1851 0 obj << /Length 1472 /Filter /FlateDecode >> stream xڽXYs6~ׯj#8:&cIML!-E:$T]IbO,~]y񜷃918Ӆ=4pC'4qndVq1$̽j\ݫ 0FaI+ldG$TkD0=Ϫwå++|0(W|o^_Eɤ\\:lENX1amOp4xUmU+($K  su'=1<;(bb/2K?EY8AvЏCȏ1"8#QXŕ P"{y~k=`D=f"y\(>R>ɥXʫb}Ӭ毫<{!qO)C1lx&?&l )ާR<1GdKDi|Dz/ bxG0[MQ[ymi/0:#"_6xx l+X*0.KwЁR6Z[eaF΀MЧaL\m(*ѠZ4F ՜g\YC@۲^,bl5<4oJVK.2ZPZ͠/,6`>o)UQt]7 :aM?p}VQ̇ij{i #%T"Dh/!>3ġד Y^HKRX:Ǹ,V?tyUB;~!pE#]=AX[n8갳A8;^ s! 4D4Å!z`h*n7&m4">qeQkeF"Bw&^hSMGabb\bU2r (OE? Rlk'|le5 endstream endobj 1889 0 obj << /Length 2202 /Filter /FlateDecode >> stream xYYoH~}l^ 9l>ٲ# 8_?U]M$j;y{짫 ,D0[L2O0p]:`ݿ JO̗>c֤󷺾U:qkYs&BwK= ubVyJU'M9us]ryMfeSsaH8ղhV躑̵ku$Ch0p:[ߨROmwn%X. sΪtb"Vtcruaji؀G,b_+R|V[6ժ*%gvӗ>5y:f*rp`\tFK7Hj̚!^Esdр񘹡a>Zi滮 `v].(daЉ[d0)b0ԬjB2p4hTU @L\ջ:rgZ$ ,֚N.@nqydҏECq1L 7B:kfF| |c.!Z@}c`ni{ >Z\6~Qԏ`CV/pG5)t;{9$ % =xgU+lAv"|7Nf嵂ne,VUkSl}1`"pwF؇QI!f穉msNmvJ@$-c.g-YiAg< MP\`68drQ꺤ltzț\VS h%-Gـ;n qor oL5:2TzSug.U%xEV%a!7F zi$F rj6*@B׆نrS[H$t@,lAyA(,$zV1iXF Zi8uBRD;" +HY]$MIPY Y `#0[Rޔ%z_zQ>*.`9_Y(wN=W^\z˃L0MZu^Azj]jGԊjjLذ.J! L Au\zڑVM9Q H" EKhכCV{=ƒoo]o.gTҞ>Z;7𮔧F6Jm#- >LJl%:/m%q-|-c~{dtuYjR]acbawଟNWQ?}q8E0`S z1dud{p$bլw8vЋN >bV8*WF#E)c #EϢ yĥ" p.>}BMX"i)&/1}!Q,1G)j>QxSqy&y0?<}Ξs>%(!Ԍ_p 'ڬ171G鎏P9v.*Dn|Ep` 'GY ֏?w{s{vqA-/hZ*^`LxSx;d}ww$ʼ8<%Zjr{ve!`C۝Z>TEzP j:zi͸ wbwbB[gy[ Eƍ}|Jۂj{?kDuЛ-l2:ַ j"d|\~Խ>5_Ic;췿` endstream endobj 1775 0 obj << /Type /ObjStm /N 100 /First 1009 /Length 2743 /Filter /FlateDecode >> stream x[ے7}cB xKRK*[Il<ӎK^I; ǻQϺ5~Aw$]pTctMD.SV]xRJv'6ZR9!U%r#AIA#8~/9i͎c>jq,EImKB;,\ .RJtsP--XKANBT9$j5h9B{I8\ Q%*QR ]uIR\JM5SpĤTKC}SПCJ.KRv95탊˥KZ@Vi^Bf1B,ØQ$]/r+1* ~+{>?I8FMa%wffWYrtU?Whjc0TjFQrs hB SRǮe Uj"ZC}Y2DQ S YӆVZS!&UDubOH,r8?VҿB"]5$Y?IGr谠v~8蝩(]}3zgɽ#].}L3|vjuwC c hΘ=X2C/lzudغgnデntxuH?̀_}4,-fj}>lviX޹g}jɳz!_s7_C Jj'ͽPL&P zk4ALH&jifinfin׬i/ lB4ALH&d LL3f2d4i&L;a }fO^lg{ŰϾ=FBMEyp^){ig4m}zr/œayd;a5_NK GXKX|ʟ_7E#tŋo`ڞ_\N8RbI- zv:Lp9{t\-D| =PD3x|b 1>:Ӄv}O%o E8{PRИc30{ a@ JifڌKP M>TE4oޝo!Nha>zhr5!R]}Nu.&N^ 췶1hx_Mkx@L4_..&\M\H/q̸|p1\^l_K I>  5uih$<}&f##t7%JĦK4fh~ZmG Ƌa=KH3 Qje "]'c9{cLiXinq%?oS>nXr@?4YMr8$72DI'*!ɫu$f1y=:Zu'зxݢ_Z 4<1!e(a '0T DQnf#RM0.A*ŠYRҽbpU=i&3sXq/z> X0dGy8l_MCՒ Ջ27ߣIWW_7x-dDoJjDŗn5]ʞB9`)cnzrS. pDAN8{MLk8#N-"rqV8kZ]y Fw.4T0ưh4XV9qm%FPXFzxѢ+ c"OZC+0cηO4Ji!B#ȫ'BJP?w5])K-nyuy)]k[Zg9|"y4]ƺ &alkː~_3La#5S4SƟV@)S ZUتlU@* [ VdUliYLf1͒,"28-h=1xA$Bރ㨦N|ղ):$)hLu08 1ypVWnoSBB:V1Rcc@8%H0 ݗ/hJN~()yQH%<iriCiᜢr(|'Q/fYpQ~I\E tz8}b;S`xl׋/'H \i>Ba(WæQAKϐ,VBCUNf)( zOqW]P $8反,u.":h['Ff籭Y< #4 7?9MR Ð%bIXeٲlDl"[6-Ȗd"[4g\Ls14\Ls1v޴yjM7v޴yjM7v޴I3 zZ B|G)ǒϾ!#4:Ȥ>\#n%9k7b A=Q0]lL|4 tJDDV~Km!5ētAE0_ endstream endobj 1924 0 obj << /Length 1522 /Filter /FlateDecode >> stream xXKs6Wp|:^JI'cIIiPG]."eɑOG&ŷ$BJ›<1LxSߛGޗa%,}K}3a $,0K1]cxfnGFe۽|3a+/" iݕ3HI2}O,8Ntq<8v8}?ԫ޽Js`v>v GZB+a!PâoYef]eQ/{QJ D>? J>u9+RÏ"IWQ.e Q}e9?_568OF:]@x+E45fň(f8K e$@>i<+0N: ,W6K$ߦOoEԝcR4L˚P&]`0o\{}WMc Znjo1 @Cоf2)S.{r)EZPϖ H(b4h4m TgMPx㘷qgUHrl;pW*KMzx *_|LA>7GAF.w',Kt='슿 ipUp^jCpF cSFԨW/z0R,؍sя>%;mC\b\BGσ`@Q4 4cU}$F֘>IҳdY#>pp4z_ERonM ̽ڷ.@i;2bܾdߺLqy Պ]\,6a烿"TrD e؋#ETI^dULv'lp{uӹ803Q!O7秊7=UjCA9AZo>2".y|_r:Y 53۶|Wvbj8a.t B6ǵΌ.j-qi ˵e2L;g;?#;$]*8BBkΕ(VNFaچMU3' \L염OE׻gn׉ W<B˰ߡy"^e7F]@l jA450+`nu,(NL"fyglrlSplXx<>DfE"5nk ,۲A놹^(q=%0xR)y o+z58AjODF{C^ mAc*MHÍuP|51e!}_f`děPtB>PdE"|9% RmIOzI(unw(Sʑ_yD!OJ)X endstream endobj 1979 0 obj << /Length 2701 /Filter /FlateDecode >> stream xZݏ۸_a Tb(KWח>2m%>;!eIvzؾǐÙ|l3g^{xMA8{Xϸ3!YL`xH!B1}+ʷ\p\iVUڦԪW:Bxڼ*eGyN2{."Vv;0 I=Div0t]MG)Lκ6s6&jM#~4qҖZnڞM"Q2 ,QR/ܴ{];ݰ~ZDbjHbDEB彞/P/޷4{^E(rC]"]!xV R/RE&Lv:./Wʇ>չHbݼe9dd#b/GҊ%Ook!8j$&׻۟@KٝJX6϶f[u-o-[]åY{'jWiTux4놴-fY?TnԼgJtX^g { CHg1{")ZY$RB\;)h;unnh`O4 vpp $ぐZlP'G.MK>̡*KJ' X7`ElLj/QUX{bu&'MybvZ4?$s)ujdj/;| A|C9m(>ۺ6[6>~1+hH +>>Bsl=cpFp,ڍjo.^۹E q_ђ{S% caߚSpRjO{KGl)gK迌5 8P8@gT|Շʣt`Uœ_co]䤋Pm֟4۪XQ}:󏍔*$_Nbh,cyEI1cK } + .Ceطe}B)GsFA8OkEx%LFC-]y[s# X!?@~Dr b^Bho$ct6cL>2)O"%t؅kk҄'/dq[8uQ3!@|)>ңg΄V账,3#&1D&f'.ysH}Hq.TqSIeMl@Pb,QIYV IȒXua$iD[jg?biMbjjikE*˺= `Đ޵Q5Xݶv}MUYSL]I5A|FU2%ot"Wكc͛^@*DJML+oe!ݙYAUDSX4*^BhsZG xƴ".i]EeJ[} U(CS 0I%L?mP4Rzq4pyYr,Bi]ғIY;& V,7EUR.)Hcr01;cXV x_@JnPfMypٚ >siQDZzzyI {H׭v;hӐA4r&J&8~}30P&&}C( %J -1ʉRz8bF ¾m!6r os^h.~"AW6NoL0ib8SN:ayxMd3N,aݛM'r<|_C|1O}H(y_Mw)H$P^ ^i79 ˁ!.o.O]s{ADEǗz}R_}kG\AѼnt.&,:@__i*,Pԍs4gn@bKwczw+_O2oޮאKKt>,s{7KogtejIj}rK%6L|2ڗăj9x^DIL߷-}}Jex2cV_M$>EK;$af=})4ai#HRp%G2xO/##Fq?*ck] ! eM̯*cU1 8/.8]IKo!̿%0ٵ?<v endstream endobj 1901 0 obj << /Type /ObjStm /N 100 /First 998 /Length 2428 /Filter /FlateDecode >> stream x[n}WU]}3DI!H"&GjX.a}w3Hf@TQG57G1A(q*֟ O*QTHBvDT%p Zb$O-5:*yDr18&KyjSh8w%9GUנt Jj[$'+&] ;\$@R5\Fw5a.%F$NUA$z8OT' 9) (I%Hk:/aI?A%JDg"怑RMCPXLI%ss0,\2R9w~Yqq~JLPW8CeŲ [-"lTB遺5cc#'{ vZ)Q_bvXlq߫rs4Wul7ÖWݰt lj)k`KsSj2엖Bk/kVE5fHhS;V}0H:AoHR0ːut1<߭RAJ5Jae҉hLWJ yz^ov'_wOV6a6 wWVR8Y;6(>o3$B°:s6o6n}s~/}v} #``}Ǝz8ߞ7׻H'8<f>4DC'I<*vf}m8cakRqd7J ɳX5|7|fSC#<ɄUnѯ uR9/<QIxOEsa,?*TlbHXn!F| ?]=RB9\}BlZ6'Hq.6Mpn`7KQB *?0IH&_PH;GOnѣ5Q grpRO7J\gN#~bZD۞I` DZ;u_H}D &-}o8:Kfh"F'fhJA''&9Od2&Hqϩ]"q!T_nֻm_f̞Ȝ.`&NdBѴ^o7g|ŭ^xVoO;K{}pzi 7<>^v^ 7pyuluDŽѽUJ2AG[{;M w Մv(@&f2d4i&LL3fk~7Slk_ jVD,x٫}7͜a)hr ^-(=%+||ܘ.p7 L"-d"% |mwD}jFu؅ &Qo@EfqiiZ0FiX04hY@y r`4q,Fi!9P,i*Ms{(I=#wdtF!-l}lxC2ςF9zs6TG6 qP%7 n*.VC ~?VƔ=6/ڢBTg"ѕCTVO'4B|~SOzK*k;/UT9bTm}Yi8q2^-(~h|hXPi4W/{ms~p6zbzho7Z+ub]XW-YLf1b4'ӜLs24'ӜLs24'ӜLs64gӜMs64gӜMs64\Ls14\Lssʍ2@DJ-Xp4v%XF zCz(<ؗd9j==@j1'd GYbF(;n ӑizbb@Ky10 ^`KBēu^]#Z!Gԉ8f$jvBo|_<5aG;XS;x Eʑ߽i1A0nGo)ғ )#p話IaB Ug}fOWsX?@F8 䏫݇w]/팾JH,3 |=>c:G=c0=D߁Sc q8% ,SekNYcr`q,!9Ɠ,cY56HO᝱ƆXq< TkLPYcXq(˲ƆXxfg8%$ aAk> stream xX[s6~Wxr^ɖoL_rNNyPlcl"\}WMlIL(L',[ɸu4pmGc: #:`d[1i$<Ȣ41sq*z7Zt]UsZĦ˚рRav."u M:]] o 6]]DSM?9KzS>Ms@M*kkJ=KܘĹ0,`B`۾V#䲍#Ws.ӱ~E?ח_ o mC xFm,b92i̙rg=d"0,}6Ȃ!6ňb֏GP,3S~F.`\i\!Pbئ7iXtHIȚtkڸbBwx{*(3[:e Yn*/pj]!~D6g~o:-xl;x1ba% ',L?N$KLOD!6VԊH;|N4 =9@2 ?mJLg_j,('\lה%l§<)$Tf%ȢF(ѵKt^aPHid/Yo-Ů0yp=QBTи*wj #9J{ dKRQD"Ywt^h]Jcn%$P{6n9y|<{YS5<9U~"[3=.ow?5Ϫ||,D>*"W5&<4I5bdB]x6#fjvek4H6^ ǧ>|ބSYCm$5+6 Y@ 26~5#u;ny?`5r6߷L*y Ft:&G8Uz;mr~C—MQx[,L禄Q "ruKKr+#t#wz=N!ppn#|`tt ٧(״;yݬp[ٷ0qQ (Lm[{_Wయ ?:F$.2)oLEG,oUêW)Ek? ~qAwՋ@ _~H3= GLe6^% J`T[0vRzySֿiD endstream endobj 2062 0 obj << /Length 1523 /Filter /FlateDecode >> stream xڵX[o6~XRwCҤE]{芁[,i~ɢ,N/rx9< vv.WoPw(c'1Yg7/$шPG\^܏܇9\>vB3lD^-f Cv|e/)`[Q+viU&$Q'lPuS,>%ؚY,@l=?ä}q!?}}:4DhGF&r^]Ԗ;CG2>&ns7O[1~PoΜϊ0cM foYզ`zkJ;&^<+CnxeiX;i⁇M@$4qn%GV EF¢Jlacr?7hGxHNkWXBo"$c!6lS==2aQbA .n^$fd}WkbWr@ MH,ŔA{P~- Gզ,YǧI"D2oYg/1)f($2@)h1y%oG&(H%q=oM-P =+t7?s@F%+b`f[j-9EtwZQ5Պcf(akZ{ 5_/HMI?`6F.j.Vc2#5I'/Mm  gd6X!8xN|*X g!dqU4=^4o)/ C+Ud]dHR^}kv} s"8 H] endstream endobj 2077 0 obj << /Length 1603 /Filter /FlateDecode >> stream xn6_!/2DR%M"E7`hHtMG hB? M}--.ym$py2#G$SUzuQ.RF";se.Z}g(b?b3 Ylʟc#aBI}cavi)nTE>$B6N~q *g#)$ӧ00g.J9VnW!A?5*gR:q5jm !LCU>O !"hp>)vSޛoI09MPC[d"h?ɖO_|'u&΍9tX:fݥs>~C7N>u:NA_5&6 f4&:43DcO$TD#=%āUԝ a,Rc03 h}+%el: c%RXׅjDRL@B_k+q1i,4\[tͅ2%E+sUUJ*Hȣέ(6> HQowQK4lh[D k[5Ktodzύo`#uBX,SkwXvW l ժ,1;g#&$Q #h^Rͧdib";1jL H@(y&4t9 dOZ{r "׼^rڰiJ*N_6:a%!Prd#+MAU&& l^cGl3ĻC|?&P}yCnc>n_Yr :8|B[ڄS)ֻJKX[GLH vH) `E;"r(1>QTXŔcx 6:ީEUF#Jsv\&PUA!o #DO?Y}T-ifuXvQVyZyD4$poB3D*p¢dgL2wd8T z\ vl=z5pЗYYtoKn0 i >'췄 z`R-x9L4j|`fp\zN/ 0tZ64 1aQuVP\]u03m,*+Tpla`U'Ba_h0Җw׌u)_+S>p2EҤpt?zPulxJbQ{ 7Ŏ Eeء'D񨆾|ogJM T=qȈ5j cR48,lccXt w endstream endobj 1992 0 obj << /Type /ObjStm /N 100 /First 1000 /Length 2477 /Filter /FlateDecode >> stream x[]s[}ׯc]|x2#KQtHnZ(KR{$h;㑖bq.v8%qƗB2!gT(F"AH$U&W!Çb>$0f ˘+51>q*)X5IT*%NJ#D%sip(&x#$\ Pa8B>r!JlBOVĐی`sdD8I}R EsPv7T.v~GXD *a@Jpp)NŲzXwWGxg$x^`D09$~FR)&1O&|6E-gbdE)W)H])b.I0I` D@*<=ϣIpYKuQ#f f)9SCLd3P4Y'Z&Gzwp.u^(<F? Jb!~E"0a᝺*U'">oZC+'# ic=;a4B<ҽZ 9T2`ࢫa*UQyN#Ձ| tͺ~~6`|r{=trbm^q6no +,fwh=3s3nra&Ogoɰxw\.g7hTV@lVƣaOX HXtrD(D6E&xi7DQS-򐫞c@xm(a<VW [B)lC2`ml8;[4mHLVʓQ`i\xwaqD(9Xa &n(#;+$oS;<2;ˑs4~ OVK^@93Op-X__]WFiF>d) ^>mltjKS> ceNm iS!{a H ' Uub#3&pL|5'fr6oo_fr N#^^ OuM/>Y pl./KQnVV  [AyZzl߄j7A,f7˾YͲo}e,f7ˡYrhC就zl^{eIb3:(ޛ"氰XڳꝽV#f-P쐡pIaOhC(FREZAÛ~P1G1@5wrRtZMlmB"Ibmx)#mnP(8߿Irj1#{à 8cs`P ^0)t`:Z0`/@b5iSHԇfl $1HT3[MXB2[]l2YhaCϪ|a^( A՞Qj9.d GCpP8}bx-(nT#JM)=Rǝ.FDPcPR A _wz+Ry {}0a~q> fF"rzFY0gH> Ws/q"#ԧGlXJhF:Ά{ɵ8[8D8"w©IxL/HCm=b=^n 1{>, JqHóB^Y.Ͳvσv m<4giՀ0@`HppMt5Ho[Gr,ד7x6zi9" Ҟ޲?]>Aoc껵5}(sas/zЩMH%svN}oz1> çM> \mt;OOOOOOOOOY8fN mzE)|~6b}£(>Dn AQA)2s)|I>qcx7'Icx4'IcxҸ4,K7}\͕\͕x;W<$gxeD?}@9ᨗCZO=A%Ċx@xHBJɎw<$. R 1,zC> stream xX[o8~W'˴Ѯ)h_}0ĔlC8I=f2[Ujwރ٨2 =xHCo4g71 |b˧AS(yL[YTiyTޣAwٟ(vxGoE5M杻{Ń&yKu1BЀPNajͯX/8@nqXxp."/X4B J!f$ز aHwNbEY5F^pR~4K p? O*+#-(nl0,gU"(E)-Z쑠]xjzq1\fnqE?oh@A`)})JI7˳1T>\N+б5>J(TbZr&!zi򸚘U\̞ 0mPݥTҖTۧrRZ'mR Sԍ+LSkDz2+2,'3 PzimhP%gkf`$uQԅy^֞NlQ{rDbA8,ܞY^␃tʼnv)+beM&ؠ4URI4] I.jbR6\|vv`:<`OOkT|ՊYӥ9,SIHsMusa_JP(Gf纭T[xTɤi!u O"?dn;t(ԃWo6A:mi=~re EH_rODN`qNAp6_Unө}vw8w`JvG8u{O^]Jd.:h X{HxSp7D_KE5nCG"193{?~>Ƿ!5CC^Rr2mÑw endstream endobj 2188 0 obj << /Length 1447 /Filter /FlateDecode >> stream xZ[s8~m홢J肴/;sYw4vw}FI`H';N" 8߹HGظ3q;_PH K[`(-02v96R7 dK iJޏ!6ȚEҘ/z_aÅ x񔽺07&+zUE  F  .{_>fL~rO|ξy@x d([")T3)6C A*g\{H0 f8" (DyaJ;ț8)ursę9JI-if xnTLٱ$b6;wzr=!Wb1#`a4 B]|oxa0'J'*{ZD ^w(\I#3Uu~6ΉT({HT,7xq@xaN( `kn(Ej R\p6O^]B&1Lz\WC#0 x+Pu.ia@.آl1V6]xnU89Gs߉:c^*sg#'(|0iPW-DoAjG>:@ж Fŭ"-8` I:p˯;8 ۪+F;'$jEFSl@nlK&dEd5_gxNj☮4|xЁ;uf~蚋^FQԂP: *ZJx38GP_%DwR? LMh/w[zL1 dHQFi2K Oȷps} Ney&zλZ‡v Wm W޷buR/!OULkw;%Si>e`@o#C$h/X)'{ۺICi,Q3 ϼMq@;m9x|"hYvބtDt}"$Rv)Ao§Q /F9x|L!v\UHy 2!*`Q̯*U*NZK-05A$?nZ O{'~KA:`fM] 2q b&uxk endstream endobj 2084 0 obj << /Type /ObjStm /N 100 /First 1004 /Length 2604 /Filter /FlateDecode >> stream x[ߏI~^*뗄VaENwx3͒!AIs%hNiΰ꯾]]ĐCJ],YD~\n !WWE͵wHo+(v): ;JEJL1-ժ:j #~DET:^VfE 0$JLc~>SQ?uZjsYǬC#08wѹ5qܲےЪJau$ŨRssGNj*& Rt)+;NпBv)sP(.8X@)Dg#rYAjHy*!6@Su셲6W8 aIΈ:> @t1%El ]$ ߿lT)j9f^L u&1ܤjHpL#%u %>{l=\.W۳ً7~llh֯Ax=qtvbܺWW ><셛zr/ovS}}='ln޿'u,+ֱ|ՄђG$ǏZ_\7|3=#85M ֧aƵ4j48]< -:.41()k>gxzۧ=|]?/ך"<;OF-ДF΂h$YQތђBF3̆gF?Y-ݴOtozDKIc Ef׫͞?~f/[>2ͰrRꈛr߆뾛FtN|v,7okVjB -@&D1!`͐!=ndM`ĄdB6PM0d2d2d2d2d!2Hm|ϐ|%N|%#-K>#h߀8iR}ߟryf$5߻xmHNgjGezn>I=`Fm <ίz [*vt{݄:itľ|"#<Fģ[+%&DNզ Ȯbfr}*|+ص4۷\M#e88ы|;T[:Ȉ8ä\EBɍbkN(ٻ;r4ZF'R]L࿨&?߬óvXϯQp>:΋zeݜ D:o9 Dfxj.#Gh@A DʌN-d8o3U׮hX,Ne_qtg5Q)i@Ǩ#rWz9$N^{3GTЋnƪ/ {1]|,?6}VߝV">\FNUG3|XN2*SjcGCFGh0S];;-O5#xk~MQZpZyZyZyZylfv-xPe J{Y u֩XqhUV=J.>q3D壇5ZlʐLZ--M3B;_M9x`#,>Sfj*ZV=$82"kȠz^ӣ0둴VQg\N\vتsAg &Lg}17Ô-Y_3H endstream endobj 2262 0 obj << /Length 2087 /Filter /FlateDecode >> stream xZ[s~ϯp]4K&TMM1'Z0K qT*ZO- !x^ɴ,Zݻ755FW߭:!ޗġgTeoKe>y\ 6ŻguOo!Mp88q$:,XIO|[A2%*KSP%=d[xH$87wX'̋cB k 0q\Jjv23ϕ,YT C63*P\M ]cQ4XEm%D.uΔ106<8yJ08JE\؎ )0IkcN&yuI "jj= C<٧ZbV'OI zXoA-A/B`k3e̓(VBmq\HfnWF0j_ QAhpd;mLЀ li Xs>6]d}^|[0bIOK\UCBЖ7)Icx$Al o.hΒ>Kc/~S @4`q2VK A_)d>8h_u)O?bø:"]Cl1NdF w |w}#}=r \EX&Qqa #.R8WfNo묔Lxʅ*Qs?l'!^_ -%z{{ +ԇ}ea)|\_/EAqhx_*!wm)k:Q54D^c1Nq(|ϒ*홌Nݨ;>GD ?ﲧlE\wG@!_UzLdm(Xty?|K@g_ ar9؆/[(QƓTR Ilt> stream xŚmoSeLJ>Fي.bKnv=߹wwBnpmV8I,geC`9)Y"J\QY$:.h(FhHVD%:esv";\#zy 1clHM1ג7FHFyK/Y]rsP\Rl c=㪕S \ƃe<XEm0<3^>Q %uK'A團$1X(()5V,7CKTLV^!CCG#v1Fqb/U ɩ`ɫRF*` TDR(% Bʘb lɩ,Z,\g"cXV!rU3T"_7 RJhvNecy-T3` 8d&'o7r2&8'U..<lCǙ`(kȉr̕5e'Pxvoc69mepn -.`:,Y-~ab7;cXcƫYO^0  HVsQB@ۻ c4o0pb`G1:{lOZo6P~\m{xwۂy~qx֖g#4cf}ڈ c˞0;WϞōZ|}U }{}ܽYޮo9ÿ8hl[Bsm_?t_۱xlꀍ v4Ĥe?DNi"ay>vC;-nڔuOYs#<a{zv }~JIG3ڗ=&# D؉ІȨ37X_t:SSWa}On [PT(I}C XPn@Da4Njuj} Racl7W&II-pew!G:GvN;06C#Š"a08 'y__l?~ZwMSd|'Ĭ\\ZĨ-r FR?UŽ$j8(issح6 b;Ir t#R / tlw3M#Yrڕin.PBdԵZ_FA ]uׄ뛇ݟl wH;nL?zz7^Ja$mTݲY%bN%Dfr9ߺ.u~9z@n{wťZ>Ի߯WN{@TQ&Ka}u_-o?z8#aA%1RƪxAr],=/G]UNcR)g\`@U****TͶjUmlf[5۪VͶjU]fW5UͮjvU]f_5W;jU}f_5SLU3UT5SLU3UT5SLU3W\5sU3W\5sU3Wk~*%dM4pdcA@L:j4b:Nح~fJeh+JY XCt\m7Yfx#\4"H#'&3P|YVa#MSy }UkC0(hP`|,Zg(BH+H|a X+N4抑~9/{<GORF>%)/}]X#x 08-WNzSKgb9}9~S>F+*+V0ۄkĒ2|=+-7`!)4QHQ Vz|{}E]s(JM؈i!O i|HGD\uOFoyg[{q1/N3* =Q=!h$aO?I>mka e~N|uœplpufn3F>J1$؍2y3iSnd!$i2CO>k9aS r]YvXI(xXR^ZjKCR8|} l1 AO͑gOh/U'i$Ѹ\ur*Q u`6Jj!J 0. pN_L"FLvi8ekqMO#N1ZPĤGa$YU3:j3bIbl K>]4cWI:+9dJT:'ՙY:IVW_B ]fhjWShʵ`!YTuucWIy:4Ό]!h>vu"GG;e@jWI:+I꜂2cW3vuNęs@: 9]'yꔵPDVLI3}z}MaI1xfNv#6n*ON5ҞQΰ$r vq>1A endstream endobj 2307 0 obj << /Length 1650 /Filter /FlateDecode >> stream xڝXKo8W ,z,t)(xlѶR;CRe+]3߼>FgWב < fˀQJ (D ̲8:EVO޿ý=2pV EF_v61b0۝aL7d>$& Ep;ԝwߚ P 0*MIo3'IZcpdfQ]atSLD4֛I煶&$, B%c]/L~Uٳwgwχ,(dnglMml<puOjNMhqMESRcl)*)8QwuC88REUY^N:#Ů̄jeS?Sy7&s[B6Z(80~~7 X߼ Ta1cA{РPUa6#-O$n+9]3"rta@ߝl}8Os@b#7DH̵9DBad* >oS^p$ICcCfY7&/Wn7k7E7G8R>ds0]wb㨄DQłJ+B&E>éRvJd8Z_̺nsQmV>mQNe&p(rVʓ\|,ݢ0t|B7O8Z(`f'P&.~8I lj?V|C cH$/hŧ-qBa-?ȭ$"z?b[CG4z "eW;LD19D$K7*ݬƍt ĤFT9?6/ݲx{ oE׵ɴwS)$=0Se%FC}4yɑ~D\B ,]iעVzQo4TFXG;rHh  .9DDQ?0yRқ*< n5U4* LU4OmTQyc,l kCLC2"r"My|o/p{=ZNN2̨I-<XY/.9cuǗLIA&,qv '5 7c0c7_`N3nBqŁ.W9E vCqpk`1nW:}ծ(=SNz W߼Pbzr$I>JhL\7U9~Q'I{Ȼ>-[ݽO&U$4OAw3 {d4- HvN~9||GUݔTHgxB; |/E&ef(u{a~Znpv> stream xYo8_ad `!mE+ŁXwI!)YrNA  㘎nFt/`8h1J/QP"}>G_=ˇP(})I$|ch泏iUW'u'  &ZKgU1|?J2~4iȚU~/϶o?w[ ҍ^:%WQu6M, ge h{]`ҍu&ՙSMs$TU=X@ "ikϧj8xٷ ?/ x&`w H,eqV~%C?Uxj59\I/ :G@=_ŝNmÙ%$C~M&moK#SD#@EGxqViT.T{KpTJJ_'aQA3l5=oVٛV}8Aʃ vU'޸0 NKɇ/ͻW`ݗbz턙cd]SC@猏׿h/)htkHW#F6>s2æF" я"a< rD6zvorM60XURv/JMW ~ rnRY5]3QI*@wLʢYԑK'c gS-5Վ%@`޴R-&wK{idܜA^*S{j_ƜzMm'yQ[evUJJ7=!W=:uZu4I; @Cڕի2U0@wpc=U.NP"V5X lǡ9-0y;{W`sz^G4$b$=շ} ;'XV^N'=I3y%]GU[lrG=c.[G(,іQ^)qR_J dp2#LM5+#Ƕ%bn.B yH#umc Dwuh 946 4S6aXp,ҘISOs/oܷˢU/$QR{戬Ar8MJ}G;udJ4U1JËc^)q宭R/;;}Ǐ-!du=/14* ?`.?Ve =#eGa6?">\:2l3-!Oiya?S#\ Qp)~K(ε7ec)=Wz:'? } cm]n·!YwuFPX\ʺM!L~@h2qL8Tt 6x>\d9 { K,F5܇4 {i!i$;c՚ &J:DG'I/wK_LeBBXvnMX/q-k|e"[&»Ɋb9,i]umB@GP% )|nR,{/'] endstream endobj 2365 0 obj << /Length 2206 /Filter /FlateDecode >> stream xZKs8Wr" \gbTleڢH8D*$~%Qh-ﯻɷ | 2QYަzݎI^l{>MN̼m1e± V'j]A0I jgY@E-sjuSDiYn8ZTzZU<ўx7 5DGQUjyy6&٨8R7𝧈2`QAB1ͦP9'e8_mנ$z ]Se$D_j 'z\AWOz*.0 K c "{kGP8[ uws Li^F[fA#1k&n ]UrnOU[/WWaȈF@Ⲏ|_%dD+"`"X4#fu`^oZ3湮w0t@W=2qoG(򭥋a,3&w6-TBj=V?Nc @mfnQ"8\]bTYJGPj~e\"e7"ڍXʚ!&D@B_QEX|ۮCm!\ 3Lv[*>ԅW]n>'%[葐Ɏ{ۭЖpa+i+i`~o`чVMz]ơK)ZJqT 1l4y\pqha#u#"!hm/g O! Ѷnn;sH`P;5~?fC3ƲČ̭-pu}{ܥ< nn4 ?lhq@pUg)mll_;dI|x[Xo*SE#R'ؕuJoљN.V~F:G|[8l $9r)3hFp u'o+CI/w'NKۨ |*VKWPn<J ׋:fo6@=Q _fX{W?PU+8|Mzl }OVQ)[=B] RX^jcϗ_뮽|Dnļw6?$T;A hJAOz_TVk:7P'<2pSA~@@Fjݽ]l֍҅$e@c\^%~{y~7'f&&`Ep=kVoASScf~?01u} x?=55o7kMw3|@) x)rtU{k/s}n`g Ff͗.OM' > stream xZnG}WK|^ĖW8^sC^:,J,qdfS}5h>&C! UbؓĄ>I$69Mq^d !)O@8SgX~< &<3Nxeo( T0KP(M|œH 6I^(A(r)X@",^ <s{$'<.s(xL$o i.&p)^](ބ)7 gK41a */pf C(T:) J&^ڛLQlB"M,IpD6b$@UxwTΤ(G&ey N˖QH"h2J&shЎ\Lξݫ&" #쀱-"E Jr"/ZpJg ܫm=x#T ZX%rA PFrY(2ճb*\B0O`IMj!DS 'HdsXڱG& TiJEfVO$o 2lB)3d+ARḭ&@}[²ݼgy Db'L^3j{2zmO˟O&VY~ ܫɏ.N&ּ 1Z׌ و7%eXmAD y,tQXj`BHɶD7@W QL =o?l~եPo,>xuOV\[ @s5(*b|r52w\!xSՈFZogo% @!?d8%P_|}q*' =Y!h+Š!D%sQE9\sUU9W\sUU9W\ssnO^Ğs{")(J!C>g̈́YRt8ߙϯWg7aNBI,Zl%NP10X>p(1ӕLS{ K,ѥrW%!˫vU S:@IBj3M*Cs9Umpٽ8{vyp<T&Erۼ")n뀖q) {@H +Yɰ{9ۜwOŀa(jzt1 oIH }pJR륁OJZή: 2 !#p%ٔLG8(˵"@)$$BP-e`%w_PY1{02 CF~CGgbjx%BeK(sjGkv"RQ)(烗/YD`p`6@h@ *]jxJ_9F@ S6&&ZZjn3lbRFzkzNj#?:yiKq\wsQV ;+~=8T7GfuoVje׌ BAAAAAAAAƬY9rfʙ3+gVάY9GsTQ9GsTQ9GsRI9'?FWu?$CeWk/Z` >$f_;$&TА ؐhEy"e_l*͖dF1ψsA1M:lN7p9F0+!ȅ!!?EG. GG.3ȅ)Y'ﶮɿE^pF(&4EG.=8r9ُ\mPtx#FIZѡK/< ]N]zAiXtHc81.F/}Ќ3x շ|uPrSy :y5U@c~O4#L^nⲇum|Tt@ÁڇnRD'# endstream endobj 2408 0 obj << /Length 1635 /Filter /FlateDecode >> stream xYKs:W0]ᙠemNt&]]PbZ Mb{LI !HOlY28E КZ.B+ 1"gM3MgiIFSXGd7˪a+'Ť֪@O{c;^$"xr:vgA6;7FalfUYW95I, 5zbn9^[#cюy"{&- ?[G'XM^uWo<fͲ.Yz7=z>"l.Bk9hGQ|Au E3IIYjn!hm*Ղܬ8 H`|SNvf \{KmS;QM:F ݿcذ'7QOI"=Xfz=b?41%0- AthEeV;2~`?p"a }yd`!fvR3e QTjDlcbO?-,ԫ\l^MP;ۺ+1is@!/A7=)qJN8+ɋ%ϫɤ[dkAL|0cZ0ÿH33*)EIFI90@PRt]!i'|h'ٻ_+Yd@b(;΢NZ@ٗg8:\-d7o 8Y,X+ze{U (d NC;0\_2jbD endstream endobj 2453 0 obj << /Length 2424 /Filter /FlateDecode >> stream xZs6Bpҍ^?(MZ7~hon HB~I3e{d b@F#kIbN0/Ge1 Fa`1uFt8]|J"?-; RϲYj#Ɂ9mTOhɬYoߝx^[hȎXĴQRy{[0`qIghT :1u|kS$UVtw/<.-EUHkq{o$Lo f)vLgf-GuhɊ<jbc('5>zX_>*|xi}s4UA7p@Yо;b=^[gʨԣjh˥4Xud߈jUixRX}$v|]A/D޾DF]q,9 yN׽DMx!@!ϯ-47uw\,(6|{k_V+-4F:ԶAںj:,L# &؊Ͷn\e&o0UڴyQdJPZ 8aOPk+-ΦHNg:c,ʮ%ϚĒ-A4CT/ qQ|E^ *4ŐU-M*/ذmY^W[ ;C^/>:s!lѮ8$/(oScϬ%MD.|l68D q,Dyq|2!K.LҏqNoJJ(u)QDC0]YƯl2 K{5sRMN$0X3=%&L* \T|z0KP0WʀVrʒzUq@ 3Cߊ9='Fsbv؜kt gſ99?z ]Ş۹nl3wTEJRJT&7&}q*9[.˺ZgP,E٤eY4;c oAȟCaL*hcoaT I6ߡ{/"b^L :ohhw &;ӄjUk%ΩC6ujEݚNٹvenɊ5n]ֵ&X.*A}SckV%Jq4,1u1U^#dE=.ujVD`9f(-f`)Ip*\ZR=T+4,nGT7F-Rz-JUczx% i`Ӝh@PGKOWr7VvYgi29LN"PSMU V.r0q8&PWU]0K>ca7 ^NW .B +'T.A/TjRq=ޝvi:N7Az8z<[ˆf-\-搭EnB΋2AC8f.!D!o')"|!oޏY/: A搧C7z> l{Ιk!n>b{P$b;~~~}4_{M oXs3Lp7]^1$T{GgM4\zVUo;D.ivxH$;?꭪ (  ~ ࢂ*O1Wz]@+z݀y0eGN;C`=simAu5KA=TGzjTWs ozFL=EU#V!6 8v0XvÃ!uQi@^h#R+&f[Ng)6f[d%6|HY&I"5%r"L=Vz; ;UعRKc-2__[=h> stream x͛[o[)ؾP @@Rlb uuRIn߾k,luωH3s9!8C $B6Ԅj6ə xcxF*dLPIAGNɐ=diBA?!G.qN2 abEC}8TᐛDCrپ # .HL׎BRMHmƪ3PZLtGeL@r &TLMHGMߞ&(XRTMreI>&1e$@bOF/E|mj PD£ `  f{A^'IHYzdr[LK;R#)PhWSvJbn̤`<` S&ESɷvTNMK65&SS>`5WؙZYfӹ} ved+@ C`޽KDL˥=SuMޥ0xO =, aaTz-u 䱀n|8(h O6Q(d&oavr'/^3j{2ڶon:ZÁ>0;ۇEw5@cA}@;ll*^/̾[_٩ŧ]\]tm{7'a0C &GօGm(ez{}'\,@B?#b( FBs-Oȩ y*_tov|KN<*FGMr):;_̆ixyk?G :z3|g u\8cj<gdIHFQ2qCSu7ݒ|MÈ/Bݎy~W]vLF\0N۹=w0ҞQ3fs=!@s?1$21~cZ%& v3M8[P6|_r x>ç1y(32|i5" iža(c⡳߳%,cGp({ 8NR7~y; @Ք=Mh=Bb AGG`)Oݚonf; IRa= E|Ohy=cb q nGu< ,1y7UC./)hk4].3x2 1DB4].Si4yf\h.rJ2M˔[(sa7se*2;KJØ"P<sH]5JvpAcM&f }$C[#XaDZG m`Z - %#HlMViZ&?t>#݇yߟgw}HFewIJOnIR)]BQAsQ(inXUH T3fVͬY5jf̪U3fVͬj9栚j9栚j;%wLކJti:`ʄkҵ SGkzݛ1/;3l*aLJ G̛+;1Q1pt{|=ގtT2bE#)G'kTKT̋$jW˗xAH!Lf|PsB28j[(T(*M\P-T3M{eW`"7  p&*T(*3MWPP1eB/TP(Z2]B,޾PpiGM[P-T ♦P(Z2QBYP1eB/TP4ZB3MBnn $g*T(*LVP-T ÙP8pywN;7[1Yvi5Č;i> stream xڽY[s۶~ׯ/R'BH vOXJf@$$Hgo2+[N ^vƲwɛk߷8>rloMKelO}{y˛V&a@A^>y%oJ"U'9͵Y!l=qT@I_EL M87̪d7 ٜv+CjPp'D9?6)qVdIi.e*羐_pyJ%e}mGkLk̛\-'_&k[N9h7l[1|ňC^>86i|^I|F,"e^FްT~ XwY44'ѣTfj[vnLB5H}] N4Nn_pd,X<qĹH"3tV&Dg4Z6d XwJ*x#[t:k-$(ZО۳wvsoe:)bTjgàcw7lUC8omO6QvH0&xKR܀Ocv ds nv72$y.=&kQ K(\c6%q:|V: -ՂTr[dq3ԗ8Ale8v7m@Tm螾OsF'ޘ-bˡLm+IkC,_Aq-~HqGIt>{f?#DRʆFLՒE26eQmH-8ߨBTYUtQقwN5J1Fqrl!ۮ 4l:j4HnMvظWF9FAc~}hy4lpì'$NE4PiȣY#A.z SQ)K/Wz <5q H6`U8(X<*̂'2qY%N(kEF WD=lשr6յ%dU>ӧ :}iM2.Pߖ; h+F@)an먼Qp|䂤Ԍzʳ,69+:Ɉ2TՎVXy*DVZ熝 Kՙ˘,> u<2 kX A}@UHfO l w6F?q_??_]u7 |* hvT"Wtӥ{! JZ~gVMo1IT u.Z~8~)8"}I߾N.;e*Ea|!/e7:?l>w9nF`Wײg()/#vƙoyA=Xv!<3/*>~|?2Sy/>^? 1o;)Yz87uou8qjta' endstream endobj 2500 0 obj << /Length 1562 /Filter /FlateDecode >> stream xڭXYs6~ׯf,IN:>DAAǿ.HZ,oOжlћeX KB7fK˱m6 <ך-禬u-b56evâ4*AMwl O{<4}+á.tEx)"Fj!^-5yVK.2+ lŗBϖԓFȉc$H4oį=\s!km #%=> ekOz6;3Y^O&' ${N wBtϴ*dKuXD=8'EZLCV9/ޙ{",JH y}!qv֗닗wzr+ҺQeL Ϫx$#w~GAtāw6d,՚6l[.~Lp/b>DtQvMQ3Ϙa6c#5/j/)͎zIY6(*[*?Em.fږ6?XEV}f[ 01/;%|)Gpuu0 }򃐅vtt:@N,Sթ 0 I4}(vN8D}lP{ޔٶbT֠G>c %mD.[q% 5W\9gFMd5WA+p+zt;JC2tMcbs݆;mDCԸEk/i8{(=Ef T'HI _A:+zO<+!tk~pzGXmı]8禜ӁHDFgN##fAS2'lkd wӌhhSL]yaߑ\M~rIlxn!Ic 6D MǦ_t.|5GUg]>>Zzz 0a4CO9Miz74oBԳ[oٳhnU_'Oיu?)b.`ʀ'`6ǽޗ6cQMI0ڑ=R}Qhq'<+1BVfy(AAz06L%ݹGqrWq@{*"GPlY%:(%\{ތ/a endstream endobj 2529 0 obj << /Length 2076 /Filter /FlateDecode >> stream xڽ]s6ݿB{(ձP$AqZw")wNQ+E*]HV%7$XP~aw9$fu]|r[ٯ?g@F,)a:bI?q-`>8'G,ot-DTiwηtD#ꇆ^GN)M˅! u)B["49s{djԢseosDb6yqB ~G€0kY>yF[ˢ.i5ϲZJ*b뜞u1)*94C'oo/=ݯ6rZt!*mUHQx|GF@9%=ednyIȋ"wy%\ip$T٣ԩļ,*M2i}`]=Ԣ=4?j"5by|^X\$2L^ 5[OoB=J OW"8wH|n0H Y&:a07&di`(ZJ.2mJ@X iת w/̊\g +ϘK6>YdA+"AeU!+y^r ]·̚G~rЃԤYҀjjjWDPƂE^Jbː+(ZVSi3UdAyw~5q;2Mԏ$s<$J'a7Ƒ[y M |ݓ=H!l/2)Jù;_f_<&y_*?BҰ$pNwP{|Γ{r)̵  ^ƻrvdDi{dur,Gxq4xԨ91>)DwV@':ĞY"4f2J̅ytl/@~Pڣ y j3\e#a8e~7b:Һ:W`@.)$տ% ڙHi{H.қ\~9R{~A ~Fv!&<cby NeSw>)yD;(jwexȴ#7%Us+so®HhP?, wC;Iĝ> stream xY[o6~ϯEubwuq&}iFxH]=md{}Y)"yn]ݯWo_}& W1'V.B[moNSI]KIvZsӷo}ES^fۮ6^,t"fp2&taǮ&EA2U{ɁXF@On?l4L^=TSUmsP{PwEH]R\S5erTqrj,n҃:&8&bXY4od:Wik1[cCA^F@H*`h*/mjhAiv>3!7we(j4j5=F] gq2:W:{}c]tҬRM !Y{҃6%+?l{RYDvF+svHiDN+joR}85|_!6f^`L,>?lx/3qLf|27Ve^s>bt |ZaOCyK i8U zȁyЧ\HKLFG3x2LFh%;m) QP9 8L7)SS%= )tMa}]>?+4g3HImr6`ƬMf.MX %QO&[` jҗ+, X>^tKH%e3g lDUi! PJA33AKjNGڨ{VXe꫊mB!T(fg옳F{н ^̋z y,>81R1R#Ƿ ntL(kOfL0׋%+IJfd sPF85]V^Hl$,15•j$+cGJPEQTИ4vL؃)MOph Oo@.ܓL |JU#k]+]A??B#:j]^ *_HdZW] ˗;,-!Iѳ>;"#LuWՕǥبnxxlŸ~BTP\`xsxc5` fu9zeoى8qPy5ɽb{}_Q.o endstream endobj 2590 0 obj << /Length 1812 /Filter /FlateDecode >> stream xYO8篈xV"^ۉ{`w=!{UH )MIm@ &|1,jyq|ዔV@ɥ5qIJíĺHwx=OltHXKqBЧ&Qy f$욆=)]UGagiԾeP TĮ9#i838' VIa>dn1Si99wq<"UjAh^fIG?(3R,,7T&aބ2iX:rf],282@\k8#c$E/*a?Ũ <\sќte J@wa"Jw8(82@w*(Il&5 XKp^৛%΍lC43I4ܜkO' mr-g8h(j%Wjߕ]ltQCxUHJca1Akffg5I|4 B6u(ptW m 3r#B IOy%\O, Ȟ#H珧#:TT8ZLObto$,ugA͎sbhHXy.2} ".h\z' 6? "|-fQ^+]s OT({ 6kpx+]!ʓHͷj'){&`f}w_?p>_|_>$}y9BNgi|;- xg\}+ޗX%ϰ~F3 wb^ܮUa[jA\~r;a.,^%|}{E಄ZA>N@p`dϋgk, ]\y8p,9.T2{_ ~|qc]aa^wعP@A8®ź\u+{Xե I+nﯻk> stream xZo[~_ǻYEml:5 .}p՘kom(8z mP(ǣ9gBd6o2l$Fa8TOUJ,2xO"C%DyVP12$|;WB{jYj;APq)a2b$2)yL3w0f"CJR eמ削kO`削_+$*<@Œch.\VeQ6O$g1CU<Zb!߳^Kذ')AZ ÙZ,l8ɴr5\eI.bIL~%d!EĘgbTjpԞ-,j2Ɋ1 T99c2ɵY"$;_& Jh$I&L!L2b$%Z$~!)CUdDwIa#K3 ھ 4NŽIOjfSɵQ1$m 35i#j)2Yxо*1&K1S７h/6YMŋks AK3Ylw+cvVO;d+Og\_آ6! ic,]|m^0)Iu&~-ַC"G>[K3]tPvJGnY^uM i}MW?̥` !m0x #H>n_ ܤhRV* IBQnT*嬖Zj9嬖Zjl,?m Gtb9 ҷ+xU1`b8uCHj{ qg18?_/C=2 $x[QW#`NՇq$I7zXFNOHjN~P/nC|'UCC^^_P78 նBB`]H "9Bx` Roxu? xJ>}O;9 /q$ ƳdȢ2^LT=Yr:pQ(ONebO\0.i_ۑ 6 H|?mx'ۥ *Xv!nb>,}W˓X|UZUVUUktJA<*1Q Ly>hQGzxCUӗR-J[*sWR)0-D ZK;v0(J~$8dK;Zzj{!ZQv'||+ηv0mWI|+x BTUH*eZj9堖Zq$OzDOJF<ց&71=wہ%"ol^Km[P>Tj;( m;qжѶC8k;p'dv@ pmm;q-mۡõ9`A!iۡ9hہB5XJ_`́ .=Û)lȝ-(iHn/7=Uu/zh=̘1zF)2}= j|F.y&[sE.s^qKw)Fi3o,V iڀ JC}nNm$3ҥx.L$a'JsVPCwHN`CQǀE{b8?N<"b'p BP|sIFGؠ8䜒yӗ8*JC*R5EM. &C,8M!%T6P$I"Y60ࠂh7윭I>$`)>OWPWS4iOn=؇xPwډbDX?kg95'q%X/^PczA5 jX/^PczA5 jX/qQE-\rQ˅mЅF SșY"ܰ[=\ endstream endobj 2632 0 obj << /Length 1672 /Filter /FlateDecode >> stream xY[o6~ϯ0yYۀ4M&^AX,y;$dvRj(<\H}ޟ^HB{Ѵ(%|ѤŚoE4jETKk=>~2@\o\";X59($-Zʈ$,)3k23-)ʥSk%t>G%\Xӡ>s-!K!)27yD%2 !)g'fxpa]e3.(ˏ#PJ_O3- ˗!Q#A)m]eHhoR1_ՔyPec?1A@l{07Pc'$..vF@Z q),Py>r-H,7TR0naI.pGB1)Jch}fzlf"36t9E9qPb:{HYէ2aFL:yvXtLe ;9qX 8jӍѪ ǢЭ0ʡq=YL! B u$L/>˳Adu%--D|Ǒ.{4;|:a=밎Zq`MFyb@SK\,rTTG]\h:vAp]3B 5T [18`zn#`rnz_tf,ľZ_t~,-J ;WI8ݿ6s}9 OS:aBI Y !gv6VF<>[*`9~41 L/l Po;λhΩ\.q@CC%QvU MLLpZ a@Ri6n2,ֻue0S"20|< 6AFE^!.mBd&6Pd=dC|uXwݶuΔm'B'2DATjEyѾNs/E,; >ݗ }p7pLl'X,کx#lՑo;  Ndw]|' ,wtRt?<^4?(x.; sn9Ram;O^v1}2+S9wu͹ZywN`y&]-] m/v7~A(HCsG4ˤ{}D ~>`h.)'6[Hg31ss&3Cs_r5R&iò^o)T_|JۻOáyV 6K_ %j&kj，#YW řoMMwl}Z)wn=T! 5 endstream endobj 2651 0 obj << /Length 1871 /Filter /FlateDecode >> stream xڥX[o6~ϯ2Y"u)tm݊6,ю6YJE)YyHYPC>u6;{<{yNLrxK|8aSg9_gA0|2=I"q9Z&[}jٽO,;KVP[\sُ30tﮓ{yТ[y ¹>ԝ717sI<'t9qW^,#n FzH4ѝ݋r?}9jkntL"IS@@ <"Al}#dZwM^Sw&# r^L"mn]R#0rW 9ǯi-Fdeht$rcb0zW73uy# bݭt8`,"s*A}FL¹ШPTfUYrugefHS'UUnڭ(TS<p _G]WZuA]JhUCYb(Il!onqsW %oo^~mH5@t&8Z^7j r؀v`L]Fb6Q2nUvG"HtggZmR u[8&EuE4=NvqZVl% !Y hwW}q/VCh,q<6$|kG*$,C_)o,)34RsGi-Z1'=KJf&㨚nFSNR̷dW%Mʋy44NҺM$G!*L^9tDkHfZXÁ&i6b Y@Orȹ UuR?N B]2-|50=]^|;6O|=Zj m&_ls)U,'vTK!X?]H^3lOtU&TaU1pYQ@=z=@{csg@{?xSK5^Xkm::7C.UbYPOoP`&;8Tmm0\z%U"Ueb- &hҺ.`¢ 5Uv#XuSmjMN$or>*j3(D@Ns٦w y喼*g+og endstream endobj 2597 0 obj << /Type /ObjStm /N 100 /First 1010 /Length 2371 /Filter /FlateDecode >> stream x[]o\ }cI}Xo NwyxnZL:3nik[kXr%\(g81 p*}T!LB69UrӢ3D:7D2%AbCޫSQJT`(:ʝb2LF 3J"ÉgƒN :#\hK e#Eb$G}tLSx&_Ƈ2씘]|&s.[0 S ț$ d]W,RW`uf}!"Fɺ'5Wص>ґZ"D$21cn_tbb7:#DJ$_@ҍ/U&sI13r&eXȤt X0;uHb2Kɒ`r( "`\%xWuF1ũ# QX`KѷJbJu7%*Sw'u 0c_d;]PGϊtyt jH>8ح+NźpPXE6"_ME*@)2xQ*C śa<8,|X<]W\µB"389[=_0}Vv9[l!6/$Eb#bs(]R9_ sv̸*$E=b݌JDX-h~>>iB Z5<T8]xNV#B(Bl#.(/#KZAxu/2r8ePB@ds:?./G4G¾ Vk=h~_^,ƏPghqS,J ˖ ߂%b\l<M(TuT' ZF E_#^1Hpp\>85oƭX3M gK1v8Y Ňa=/`Jv*8PUmF kIYga ?.wцF<ܙ{М>{Bd!2_6*"?w:ۢ<wߓ>6|[laQ\p%AE44"^hFT/d7]+KP{[!Ϙ^{\Y$qn5! BB26]p{yAqXT-~`3W8݃+"VL;-7_Nc"HxwNF3֦ R7³/xM!>5?ghRB2˫w7&vڻIsxmBӌٝ:G3jd 4j{xvӎ:@mXmBh٫l٫ff5vW G3&nUY]χͮ[~X\̟>겡h\FQ/d W5;_ 6wBMؽXj7A4SLM354SLM354SLM374sM374sM34هl\ 2Q1|obDDˮ]bFL prU +h{?AbKVI J"ϊ1(W:v;+i2[J]Fmbڥi˽LChR _nuIi.305nL. ˞v2!r]F3Ҡ4ڥtw0JȏF4hˋy_v|gIoCN6^W: ^1^uH74s^-[ez6}km[k1J;2ՎO$eltxAɳxA9XxwAӎ&UeiG'xH^VّF^ai<۩s/cB/! "#9k?鱥qR,iFG_"^s4c|Sײv8 endstream endobj 2698 0 obj << /Length 2090 /Filter /FlateDecode >> stream x]O_Q 7F݇}H*u:q:ϱ4 -41BDZ}?|tr?N;p&w ^0 J|O7' }Yjs>\AgG #8O B\rB-X=~jOysfJwJyy){;ta28E$ SSNf0J,S;?̢yB8 )ԧv$`U %u"6J$byq`^+G?$T 3A(aaL|C' Q]J4I3\36#1IKd6+T̶H]>V arnv0l]]|!5*r:.sP.ᾓ*W)L(!ʗK^lD]JqeRJ:vf(" CV SG%K;PD @e̕0_K}yK;H U̞VD8헾Q}vX*6C4P b*r)YH­9Hb9a^+J0RH]GSO`y*s'(J̓:Ù_zS]"9vAr6N[`W^FyO'%`5{s}:8-G:kc]֚v ?HTUW?% #Z䵞!/ (+-6 "Y)i1{R`7,فy; C>ExF?ǿF 0Nxčӭ!VBx3 >nEܗ(=l ,V:qY)ID9 |Fda@2>6?l}RTy!`JUޡӴH:ogGݭ. L[@#!SUU> ƣ?CS~#:bDz>B۬Cvo:W6\v_>t]"doA㦞0fCKԗX=#m~=#pzF$gYl~]&EM= {7sEǯ6)~_ r1TKW\4n?m {<#x+!>zCJGආTOWF:>CjG =Nq)]3W=QrҸ|LkԨEpbWD왳RVy $ȈOy6/ܛ75cY^ yFFAmL۵ϾxG{8fS^bŌ˻'L+k el.OC'|CuA/]NCI1=W?t_-M\'4¸wut @?4${_B뷶f-g pǰD8$ Pi-#Z<[^QbrGj=[`ndJYUP` QױQ>jbk7++,jE 6;tyK]s@C]OqFܠuwElh$'XS2e|<4#,Lﶰ SrmucҕqxpAb֑!J/$<2iZTc?YnaYK#]p=yc T&?hxXh{$ZQ)s0os)|hGxݭ(l:Łs֢d!jA퉶9t Mw9kYKR,˦pI6FV)́0^fiW5F9 o_ZzPmC:%,{J%4x\n\]墧O4OkȮl }{7{qx7H `ޠ ޾B-r.*T\!|>U|9xgcM38Kk]1%>NAdtИ!>a/Hlv^ea([$ՄmveI.wϣfyJd[RlhAhjU*o,MSdA endstream endobj 2725 0 obj << /Length 2875 /Filter /FlateDecode >> stream xڭZY6~h D 䗅f>VQJokNavSU㫢*Xͳ \Dbu_AljXIinvw2pƩ4y,n{ݿzeYKQ7lI$7+ L0`CC?Hy͡jכ8֡w;$r'dA_76[-PgNW)^N7Zޤi]룢E: <Y@]m:iuWtES*P[ vڄaGa t>iSB On>`mUWUia"ʽ:J{ޭSfsb,ZFQ [7USwiD*_g+K+|t\]ѩjAphӛ$pVQб5:RZ7? ؄?r{EDG9^XvxxᑣspmW.ݔ&xk")dd˾C-Kwϑ1Nmm;U2p斾fZ8ΌyzOOlx9({@mjdVը6Wd;SM5* M{Re1zdkn<NVVN:]7=#[Svس-1ft WiSr$SJЕO{pN<,l.0*&}n:zUExۢ,!ktGٶj$fgZӨ7՗ԏ~64xzj [%lU(ƶ}G;\7|pkO2?J2'; @?`TU72צTD=5stLMlﾵ%Q@-(SWnі"ZU"U'Jknyė5tbpQdۅۉ?~IX@SNQvU?! y8(.&p!nc 1AgM3ٚZ[ s{-ڥ8*"[ԧu> @hM45S>KN1uRE)8 %s挭xmltj5gQ r"UY{!8(R܌/S8V-OԍyE8 eATj Ir3}M@HD#}h7bgѢ:8ME%A$ĭ`bo'gOtRn)\E˄]e=VZD74؁e6g6G: }[€TdH}ȄfS[G$/T[-KnSkj홦,H[>9GdI;fPs`2<>V{1u0IEy#64tR4rEnCS(U sŭ\[GRC-G9 &M)X NC F&ϳdS/Fty[e5&XGGO(;ԂDb7˲7I7N4'񢭞wM_XOXrJu:$8 ?_} co_ 'pyb\(_Q(hpU;Z;tgd5mUig>(R$ywޙ_ vLQq%\8l{۞A ,9PI#<5ϖzJ >ǒS+^j,L<*0v5!"eݞ}ȮzFml?b/! 3A AɻTr"K@h Dmtsbõװ1TI^̡ N&?`Yh!wGf"`]="?Bas5D˱ZjW!0z܉LךPΕ0k!4t2,> stream xZs6_5 3}pҤ̵ׇ(yG*AX"eږOr7]o`zg?y|H"-73sp@̖/[]2GcH(~vn7IC 7y!"ђ,˛*b{i=wnu٘ס>0c卞/86UQTsۼ&2{䦗UC]ZQg,֥ ODp?a0f\RદqW_p]mwi"o/Jȗ`%Jt]WƐ9W?hPPX:kq]:¹Xf~8eB|BȊ1a?A5f  Es> dӧ > aꏷH"uCU ۭS@fOXs0W !۶ߏ&Jy3e%R4N*6_({WZKAj9gD6zMUӲL7i^8jUx |kk͜1F Bf(q~xUu b"jnkzٖZVv{os]xh*7EYU@̆4H@@8 G+x9sXN$[EA#2aF+ޣDRpz2,W%G0pvkagHqvn23\M|Ƚg ))]\#,wp.*3qK̰B/1nWXxuUD;j~@}q!.aꙖS'McO[-9/CYydR*EEH$rI?xZq6͍6=@+AuH[kLC1q'&"_Át ,AvYrʇB=OݐQ4!ڢ8 !<I|]9Uuc(6GT]k}<qB9л̎ |_,p .ł$\6tMz>cD#OUQ=tBM;?@!&\rӀP [iβ 9W6pps䌦]ziMe-ј?6CvBHo  XHUpumW[ (b' %%LCKYH>L%'d[HW3POss ѝnR,{&US&!G-N)H Jq2B*8&_zk!Q1ѮINE;ǜj1}HD=c~Vz q7[d":qe ×ש u p3spX0>B@Uwo w> 1\RyəRxm@iZ`Hz=uRs%!{ GBEsCu>lë)qɽ~ uܗMzG$]ה f8aUq}eC=HDlxj*cՙNЂα)=RM-C/?q? >@P T*=c b};dÆ`Q ǀOX_ 2La'^æB^:zu𽦡tz@5-vZ [ѾA5 , ňK&hٶx (G8uiX0IK{};u<78axgg8Kw|ꪙGpaEa|ͲWڝ;? :(\ 0׎C4!pgwT%&MJ~4oOlQ{˵$}")}.S'b%S|ো> stream xZKsGW14@?RTUJb{4^sW!UQ~hڎQw7GJ~PIzW0 rvt:J" q5 W!ŪY^v5W ER *1GRoj pMT*֕U[O_.B+*k=pܟZǗpG2HE>K=a58` BB0P6RXk;QʰU9@aX]0%"+S݂ۉKQ!()-B}m1zr{ nCL_?rIӱd/ާݻfjiWǶrَY&鿀ٰq/Gn|޸{v?NfaXn.U>2{:\g>4/V&o*%DmB/+0} -!mG`HFbD68g㜍s18\s18\s18W\s58W\s58W\s387܌srSvi̞]߿[,}2{Zٷ'/ =Ap`^ZbLpu3;Y=_9O_/W嗪p{̭BA !=`_e3LTQ\BoΏWxBbRg>`qpE퓐=x3_bOoro}E(3hLR;o#T ArMnzeB& QGƒzabPC8#40>"Kkf\auG\Kh &T[;p^3h_gW) Y"@rm&.I`m>TEW<7V9!4 @O.{E?$Qh2XOoO@P TwHpq>e:`Mء9i$_ \&;TH8.$ é7p4!3u֬F7#%˦(ihG閖8)ejS)Dl5v =`ȵJAt=Cv_!X>-3u.:ϑ:VЎ㪁}LSРoʻ}km_J\o45 †Dy:C64_Ɲ c16OQ7yob(S;)Q>s"m7)(FT#v02"`#3g2d8GsSvKY'ONXQJT r:m]%A^gKEm$<;#m0w/w)XC Fm]g )d| (&2N['G@cjdpgzz4,( $iD:(tQF#ظ0BgBA6{"P#PײP Al3 L$xC`]!0**KK5+?f[`Z<䩭e:FՆk_񺲔$\ڟA^\c:ys=PF&#`"s:@M됾VO(/~~{1l)[Rբ7u,1~p\:$t҄ID$dUDO7z1ej[|IؼYzXO_~X"<-ZP{:m,L4tj[ᱧ3Ѽ#瑧uWѧ9hXM(u[k*~w V5vsj0S> stream xr8_d_NP7teMN>#bHN#pg[]]"j, j^L<I1Ϙ Rp=J\btmw;&__,Xb(!s;uj@5- F>| 9o ۩ZW5DDlᄵԥÖ,^H|'<':)u=K!">S[/y)"+y"x98 nn6 ]fRDq>jϠ-muz0'2 [W|vx IN z5O6^|1 ]|.' ph:E%(ѲCjQ!THJ^/Jqz!2Q$39:yHq=:<;! \x=KET`c"ٲYI<ݾ^rT]ϖ߾y}Rpl{7oe;{|5a[Mv|xɳ|uRv>Oe\@ M9,r+**g9kgC˥DeP*..!ΎF8֜֓ b3:<0PϮYT_M46 M!wyjt||6ŏq\~IƗcg?q'Yl+>ToHHjL Eg8FZ]wID7QZU'sA(g2UYw%lLQlFnVp$<ĈX wk/\BmU6yt0؃na7=A뭃t}`W>8vHl7foԈa' j}ʒԸ\+NH!^ۆx$?l!`t8u NBnjp^2S%"zFUב'~y^B1t|KgU>ӷ2jZ[5:b]S өh)aE㳖ŸU~#Hn*y*fNh#926@E(QBk>d RҪq]>d#Ǻ׷ݰ:Jwޡ&ϴq=_񥮣jj%B(M{ Dlal xkHӔe\\$[*;\mL+rLR(HW^ `S1r(]*xhCVFM!ۗCn_r$o!Q>rpӒDzRDq;5lurqW͡ hb: |Bވ5W;t~au$7GMyzP endstream endobj 2833 0 obj << /Length 2512 /Filter /FlateDecode >> stream xڵYKs6W\{Te` eKNloR޸bɹ9pHh9Cn4!)JR6^F W^E’P7 ‹(:7Wuslz%wop479bXL8yۭ`xhe⾷ś s %BY]UǜF!Kb8C Π懷.X {?GXSg]QOWyI[z6J9>@dJ(a?TdfC'۬EH/d< hJۥ;8_)1ۥMu׶kjkKjx &1}sZ޶Z>ͳ vu2M VI\岺{/nؘ&J/;w^0G)7oBp Y횺`ŜVVDœbV(H}NۺZ"Ex+.==0EK/K\;NLM P77Ͻm Moҭ\N }Ϸ]6畳s,8 6@$LͮWfɉJ~@wؙOkvD @ 1JU@OQh`#jQ%s/ 6۾&kۨ25טGm#K+Rd{opf`#]%X$ȿ]'N0C&BA8[K?WXإ+[!'UܡP; ΛEQT?mjm_`S@:]t| DB|$.H~Og5J2?Y LbO3ҿEQ%u,e;zAUt W3`t EH YtmqBGۏk Ad6z$:i(x)@YzX74bN4>+,5ݠ8ժm+)쑄AlXc^nѿ% :'hN T?,Ӈ5sZ}Ϗ℩` *?˜EݯgUb3ha' 0ոݠp@-=4hbj, 罭BiM p[ƶumw>`B[dz)w "χ쯮\uA4N:#pBӼ||$N6W')3M b38}9E&oPҢ)kթ:_^>O4l 4iAEtz۞ ^R<PfIyv5Z ónu UD`)34F:s.mUW%3b"Ȏ=I$Yn"EAi 9"w G⟩];!#>DKbý*(K69 @sKhNǕʕT9 F6bd,evoR)ʘ&Ec;{$~c/e55!8\B=Z!}ָBk_6Ҕ)G$cˊD#Qb(0qleC*T~M rYTcь<}X۸"~x È3k궽P']jќ=X!!4jAgZ/! oq1 § 3\((׏=hU>K)> t {&L{K|W;'53D#[ =ENեfs<102ؖSxd#Sj9ωlKvU2rPMňWQ,g6jV,; endstream endobj 2889 0 obj << /Length 2486 /Filter /FlateDecode >> stream xZs6_3J?@ūDbAhG}M'%bit;G?yw懋0%, E8@( &E_7"RAбkɵ.k]ݟWUy*w/`>nEDz/iE@POx41 csy:I̹UgWN^LW4[{~N"ˑacp׹.hSV-Lʫ~|wyzQ;iMkFh/tZɗs<i9K"S+o.4Kţ @+ԅ](bcȑW>62,jw%W)/J3Ӹ{W9]h7uU!;6rVH% )@@W~b_8$k2Fgիbqђ, }G8$kYVeUz]{s,&WR8؈ Ya}it5TOȳfKP$5h&q#LשeohУc ލlc,[mJdm6q&"[=w A\ 4h%[~8*?N"d<8 2Sq_U`h$h! &ĖL.c1١i䛕n&U54B0 Sz#;4Z -w(c ic*9"d_.\cU%W*F"5IkqKgUwpu|8@ vRiHkbbk0D!xf^n<4:GslDV38XDOwa @E@].iѦХoJ/jڂ'^ $rwF"DMYմd!b֘tlqaԤSM$Ɣ~.XzҺw&f}{M=P$XPI)8\1pPȇorN6{JipL<=PeezhiGJX%ĉv{kUFN*wN!Wb H$@,.y :pݙwu]cs:}Бz oQäO9*>m'}LH+̀}Ҫ/n;[Q4^٨ތ7N`]E OHQKf|Du4\+"C"SPyox[m飾}qzȹcxkîAgؔv].Pj۵w0}D)w̻g0CU J|~هzA6GE|6Wc>>#e<ÎORQHٲT@0'r6 ,?nikM).6bl062x#_2DupɶɫPgE8 8B(LKrD.ju[mʩee΀{t:}_*= GQk ^k Sj(m֝o @=t^M1!`N{7}*iF-Oti7\;u ]C4E \ZOɏ Hn·L;V`/4}m>> s p*34x+)(EDOG ܯ9[m s2<At,9E3pMm^ƐXluPOmW;_(#Ŭ> stream xZ[s[~ׯc-Ɍ-Gg҉cM[x\I[Du-B#3ўCŇށc0΄x&!؄C#) MvDfSMUNR)Z b#/*, 3_<$`.| B0'( TIKTfQ0$_Ƕ9R}ޮn`XTnYLF6Q !dKѣfxXnN&|r5V{=nlrʷɋrc^y-㽳;KN789ac葙ɷ˗K3yjxfagon.r}:།)Ń$.ϳśP[Io@-LʏP֓caIjxس%XPNЛ0Q<\ =Z*ԅ/ӫPbsLZ-f,#:-^twn;F}8CxdB{Gc#}]%ѽ ,iA,s+6^ء::GH;GC$+d4ݍ2ԋ9 }kris[v 2)}/ XL,L?=3ƼmϧN&iXl֒$4brXoSOl>}1̟OW`ȂQ֘%["9%A RJ$%9)笜2ʰ*ê 2ʰ*úc(yJ%H Vb8u!PdZ/iCmRõ~?_ol=d"g}`~'jf[EC-N41Ѡ* {؄Kh^N/pSLD`G4?^/7óxf>FT_D%3#J 1Aҕ&dsKHPcX=gX)=1T9I!xf|X$׍Pp"K't3:.Z xU$8^롌+dCK|OftAq   Ed%HN1t?TNա*="Y@t *ŒĻmG[y`t]&JRNMGwQjHx=%e9d 32> stream xڭX[o6~$5G7l2gx(}%V<J;q€%~(q~9ywp#brmؖ\7buej|5ս(:N~og,aM%(2.n=APv. Ϝ[ReXƫ\fq+)3nYծNJ^&@=`mGL%I3zQ|-}?4w]߉|1)nElϫ>"B6yTԱYdM&B$̗ofXEw9lnwHaenJtgx6Ds=7'*] t+|6|ygӥ A4(ę)әkGfL4..}uVC Pw7s=*zer߬s@}֗]]?=+e޼qKz Zke8279͜3r{>\3dbPrL*+6z,8+6ϫ7htNw{Z=@TmKنE$<OdYEOvX\^/<?Ӥ!}#⛍G* DjMU1%w]V}U*i./hǍ[w@r"cFeUҋ?PuRgH'sE+"X4Pv gq 5Oɯ{$5hŧk{&p>m8fGVO!Ա PR CabXbJzߤUoEQm */N */J !*aP|![Q!y$1vZafSbqfwv>av3(N8R&ĖzIpM]VطDbx=rHV R׋9-O O=MeB$/':n1ZpS_2టPv?kzSȳo$TU"x!@W'-zq u>+ kKlkIw̵: nm#.qa"9]ŜPרCK2:aTez6bl&0$U/k W[UBFTc|dbLwί|7[npj[2<٦:SqJW,Nb8ҫ3vf;]RDp7`f`۶*vHa Gm$h5 /_ܽg@=I Z.Ńeeةp3y8rs ޗ.\oD7l,D Z*ךw:D)qX.lrϗc endstream endobj 2944 0 obj << /Length 2672 /Filter /FlateDecode >> stream xYoܸ_0 1O$i(69A.}J\Zi ԗ@[R9oF~o~~Oh4ndmgbq8Y)|?:fMKu71wq֕ ͕q6ۺ*}Ǯlꬪ/{{y%ۖuWLg)C-EcF#a"KA0~4Ї>clqF#a:H'hg<!\888g6nNei̸!.t.EZH[vvK>Vf "d7py,r.`U[M=N*Wm:?\=K%9k2}ھT04%p9 RӰ?ү czhZX&8ҡ9d5X}50="i$""N'>hU ijzS]7ӍI<3HAӎVky)tkrdxCFGݠ\=>veiG]3Fn*"1L}/Ry3)+$ bׅ)} 6뮬C$lG*t?٣SFy=WH¤~.}@3ʪחk9Y9CvpwP#\qEIi#1*3"kiNZZE 4rr?X^L#F[^J9L1Ђ9ܖUY;PEi8Y}\ƶn7 h22mvo,WlU`:.(5Ē zE5 .ZG.hͯ[zؾVtVT"4P%((HjZ]Pʧr23(JbA6K Wb޼Ma WwI @G*\_1 [FSU1JѥbrISs#XӔ-n@5DF)BTf#y+)&<3FkM_qoe!-5!#2-=RH@@-3e1EM_0c*f,G2ӓ!чL#MCbuq`bXK:0cGKIO&"AКϱ+ry~B$Rؙc+ Gy-|y 4n(X)ɐW|?Ts5jpn !&ax%jh$` @Ξ֯t'@!Pe[h]פD_w+'6G./<g ZTO.s;Aszc5~%U5bMs#yֻjƁakeð q܇≽nyp˚'TL;n*Dם~ W+J%G{43 LI—$cp;OD7إum ׿{ lN endstream endobj 2907 0 obj << /Type /ObjStm /N 100 /First 998 /Length 2354 /Filter /FlateDecode >> stream xZnG}Wc쪾F[YđW4Zs#YZ;49RkwTjtTh8%#  d6!*bkTS@H( y'S4*dS6RKʢTKJX1Fhkd^֬df^dJ6>HqK@qk_P)jn kZH%+hB J ۔ ΄\A + 5=6,FH1aL׮nKhWHmwaQy9H\:1{p[(n!+FQֈa$+Vc$0 ~'b/5)HɛڶK0ΣR^UI& J6Y܈\AyE*5}<ήGzQN⃧ +K_%.%j +.+&R0r6qr6UwUF:Z)vJwg,2E}ic&C,:Ef3z]hۂ%rPуG2r==zm_,>=Zχ L^ξ=hv:m lyQl+$e(=433v|efK{x=̷KGKM62`V{wp^wfwGv+kO%[{,AGe9[-02KƄ =ͻj;ᾄZld<f邲l7S>A(T 95݀aͻb:h(3/yXM%9|jnGF+(+#m*X&4A(@Ub'a~r ȽGGf`}]h2\OO-\fpyF!Xh46h~x/Xf}d 鰹w8-}pZ 3@= ߊǫvxr>,Űޗ%Z}`[般|2nݔh.eL dۛ7LE= Yɳay>q u}L*m%El V^<;oف/ (^R^s7jWg ]H6h-md< 'p!qrGժtm[q_\MYzd؞0q8n SPaN{F41!;9~}y#+njV8ABG|M !uC:z=w/v82 Y ҁ磥1Y3f LTO*s;mdTiԎ*^$%!!CAJvAWD=uk{ҍDrmө}I^bt#AŹq\O[ۻxjmse'}@-0~|?JٳAjfOּ09͎XچY]φn޾p?Z3-#ʡ[2%嫈5poIe3 j$vQQQF!B< e-hYG˺r:Rhpo<ݣ+՛ M~2jE}5P2WI"8%FQDk&> 'ǻbk{v9l|400!oz?-h[8~)'KhD[`siJ)M's7KDM.>'xG\ ]X4]s>|KO/|Μ[#FH ls@VOL;+6}8ōi;p 1o"q~󎁠Zkޡc y|84Fx|,ȂiЭN4ۚ IyE;|v(Nmm8ԧ퓂]*Vu5V>ҒNe߶nהC>?CEߓ{~[:Rn)ۏLۏLۏL;L;ȤsF}v^I‘*6p$1ǡj2zRg]L!L4?ŤL R; X=D]4)"K,nZ/Y^yؾ^p1/<(/m,l5Ja?W`TG 9Rww+_ Fh|L+I*`jk;&oVo6޻ݶl^c+-i \o $ endstream endobj 2999 0 obj << /Length 1472 /Filter /FlateDecode >> stream xY[s8~ϯ/0-_le'l >`lAklj\Y6`cR2aw'3G򝋤f>O\: [O51296Fih@ &7<n2/sg?ǿm3w,Ir )iWG GnU!Pkt 狈tK>{IZyXˌUvi:Rd̎Xp?t%bߪ/nlޜg<U/H- ZpIVW~iޠMrb)l/Ik _M/*,M0䬽 :6nUρ`rr8*Ćg{/Ə6WsѡUnp=\!m3%$"q:qeP,>ϯcm1y&R4i ?=8B E5?#qx^p:ᵘĻ y¯'AH#.ѱN!>/xnr-N^tZ?|m˾ .Jv jψϓcݳV/Ȼ/(Ր_N!`.YGnPwo x/Sdbq'y%O^"-6rEĽT -]nl^Mpn_i՘ԒKujp>hll7m@3tմqcE>2dW]%Zn>_Aj,=UqڃD݀jA\AZR)>± kŒ)Yb+[}U+t*&vd [{Z\ ? Fcoi|fR#5˻ ΃B#~gW_7k"\7Q[77>RlHdT@|IM[ nC~l uYz$Ol5@M1P]vYϊhEKi)~rRRT+A(=do)^ۭ䓁9l a}3`/1XңV.VS{pʨppAl q;O0 endstream endobj 3050 0 obj << /Length 2224 /Filter /FlateDecode >> stream xZ[o۸~1/[m,IEfʲ+m I]Q\$Qɹ3Äz>~]~9WʋI-nMѩ;%=a~Z/ÞcGPˡa/x8"4RIo_rҼYUʿXsH*=#BElt L=G; :ǫ[ > w?j [%{Bb̸vGV{rVX [F_/Ùqx6>K]oߦ#S@v? an%2 'Ofu#t[~V.TA%\[sWFWMRU]!vGc,,[}$$'`Q؋aRI[=S9E(x27 dTΝWef FKsp!)J&D@BlHkCsm8f[4ol؇eoN[EsN@.qa.uHxFVmJ]2l6v'|tڪȿX]PBC~im"w J7rI [mgzoF$J젟 hgh*!JA "R9P@ǜ՞mGN6HqTXiE8Pljg;܅]1-QGa;pwIlfvbAs0{Y n=uݔ1߶YmgLBZI`zIZ7lwhI^|yTv1aAx &h9Ήaz>7[zIgNz]r2Z)GYaU[nn VEձ'l㱟w3zi @ DGx{>TW0/8^Ԏǜ2 %`Ď-wE[қՆWaE645Z!\} )*DdYkW-(v%]- Ƕňo`P%u-j_mSEelkQe|$)Ga3\ÉtZ%nd3`ښ .*)u7rfsrc'eR'In6벮:&xUڍ[5N~[FZÉeeZ |΋-|CqI Gz>zB%gƆ%˗(+q[f]~6mj vK jk;N2I8 do1!vQYA$]j=l* SB?/?w?&p,`r 7o)"<:)\O:R+ Σ鶞$PITqs!%$36Nݟt>՛{w ˕/(_nuߐ~ďQ}3֬p՟I-_s%|Cg:_VS叏vThSqw<8a_ZjA 0¾ȟ[ړ %~ܜ Gi^"U zWf+#p7>vx"~\׉? endstream endobj 2961 0 obj << /Type /ObjStm /N 100 /First 1008 /Length 2448 /Filter /FlateDecode >> stream x[r }Wcl}rm/덪6kɹ@tDK:$}d2#= 39} [*.8nos7GR!DvT#w2BLWcR!䈘O eG\+"Q9*Ayjҙ 9jK @q̥|fL0[ AiNE/Τ9C$uUN(Ӛs"2EW\L}5r"*$qk1IQZrI`tJB!2^TC $TJ* PZOH]/b:$FpD̵)2+tUu>.2TaPPT\QSu`>cWS9ө]K5}-H5:k\85ŃB0ɤb. $qG$Bi͆H (T1̏B 1mQ 6pDItBGl0wE慎oD0&]"3X'J CxR1>eUyXuQ)UK}֤ޘc{b:_ qُr޸ُ/^ǝAˇ%~cy2{V=?2;[nכvUGFƪ7xUtZ>*CB4!M(&TA(2!C.\ r1bՐ!WC\ r5jՐ!7Cn r3fm*=_/W>=[oM_v0Iū!õzv?:#i/ᖓR8:\2 ºqA:KBr{wY`|8Q̷׻1 ukAT.f|p6K^r;4bA9 !<؃tL2r=qpd=KKQQr*#GLc| ||NgՈʉIfO& HTD 9 {V~//W혻 O4p7ѭrD r8GWcґZUk7I|KCz[.p|܌oMҚYNBcoP'3ơFB5я+r, I%0Y`L"!CLp‹vnLx8 R}x-F//"[.."\*>lRn> Ep+HȽ8h<1[rT#AS Љ]+nk$ &B?ogkkh[%ڢ;Bo nPьszCGemGgQb-eq˰)4e߯?kV-ai[{IiF^`& фdB6`dllllllllllbbbbbbbbbbѐ!GC 9r4XƬsUŸ3bHo"- D՜m5WߏKEk>74j; R-$EO(.Ƭ`ՓY6YӪCx!dI=9]Wdj1_FT H}1%bWѯ"6TtMk9Uw`G Έ v߱Se\`_#HrEALt!CEÙaM\H!@1b>BPӏZvuQgtw/:I7bؙzW屺}Fƺ}3Q8Y8}@en C8ɺ}Fź}CL#ZMpFGk 3MϨXo~:~ùL!th'4eXoiz~$tt=?Sy06љgt7T=?cc l׏8G(M?b]{pg7Dm?b}T&;NfShs#woug#\BS4/rF&v/6Yz9 q>|ۘ6d|HCѩзLXEt;S endstream endobj 3067 0 obj << /Length 1608 /Filter /FlateDecode >> stream xڭWKo8WCm fDc6E]q4Zmmd)_3|Rb;ζSp8oϣ"{qѮf07R"k~?༧ h;EF=dM4XߗR 6=`K`3gzEB}nt6F?Z}mQ-ͣ(Qu[MF4 64^Xh0>Itp}T1/SV;?!E.X٥+e'͏|-C^_w]_3" { 8Iԥ흑Ė;ъ^l%31/ݔrh;t6ub@^H&ل%f2kU'fu§!K Oa޻π 6?2k-N+G,T{zDl}-,.'7@q _t`o]ݣ V.ܫK8*$LQ=F(V\]v"JR{z1$VmtB{,N&I]r1. 7hܩUi5'0Mhh (U/u s1 !4!aZUGYznȻ)k'tuݝiEtբp'sSž2 -6ɉ1 zTXj#~/T-Y˞Z2ͦ]Q@EvTF йVɔ'ØsPMٵlWun0^ pu\҄ngP\-l\!%$s ]C$⇆FdlZ-jB}zv R_SGqCC^1D;mdTj)iCL5n,~r.cLQ  M l/ƀIRIpg֍ZJNXKmY]M*w%6_(\6w?!);IH[ÈP v6 ~Ӈ;gZa>׋ ąV& .q+A\}IW SC6FˬyxqILG1wDJϱTk ޟRW~Ɔ@w~U!#a #5DNs]iJl #7P)d]+1pUa} Ww sDun&qÌ4z(C/DruCs7]n0/?Nrvrj0!# wE§$ >wӏj)>tAu=N$rWYyHcb^ٝ-b`bB/9^4xgUlGa|vV׏&Rg`;^c s$\ժޔYWRڕȤ6 ߀㥬dSdVP"p R# rkIm"ſ.C+% odgd+v endstream endobj 3079 0 obj << /Length 1319 /Filter /FlateDecode >> stream xVKo6Wi26RlQIѢ6qCZmbeɠMb{g$KΣ"pHy|͐8u;A,֎OFģa,VnX:=03УdVfqE]BJV,oDU3b U2U:-TDQԙ7Ѕ{B | ,0H޴gr=8 E->Խ0c$| 4A6+Jد[?7TD{[9We{yQ~+D҂lM|祎f0 0I:1H)|#![@ċSe4ֻKKAV6!a#0*0̜RB씺OMCmvs gR |!CZ:`!ԛlнZ {1},i@qWtqHDIOP5}IH f 7펗 d]xWh 2~d|=~B(+"wdNzPWw_kga&qg5eLURtXf@Gx*Lue lYI qehd!iMUKx468T êl3.^qpNÈǰ;S|/ʢ^U@Э 4<,|'KddMa(Ń^<*DBmQhZX#|Yo[>tV122춆5ͷ_9hwMi)زuשy5JcKQnLUx7=d7OAYy<@\ uh-.*pynɆ]-$< ٜsXykvJlWzG"[2=R@ƦTD6SIRQk LJTRŒXQm@/Z/O5k &4 'y87K$nXL;su.#۷+tճ۫xq+=|mTZ1s?aܚ̭L=RH+ C~o}2YVJnCLGJe冏H [ڬغRO缮m.n?UN1%N1=> TL=7LܿӿY-[fxyToLMO&qTO=UwxY5/+G_vC endstream endobj 3101 0 obj << /Length 2311 /Filter /FlateDecode >> stream xڭY[oܸ~R0[.Ob3Du}M;[("w.C?[Β@4Xi$"4e9 j_:M4"Y2SΨu9Mc9p%En]UWP%|X};`)D^T0Bywg_~A/ȃ=uso۳^U"`(I(HD21G|ftלGI(w5]XV٧S )iz)H[c\vݔ#G`('in0k;S̓~ϳnrWUaJsq@d|Ufr;jvhށ'ЕսYY>I3t=Hܺv˪0vݣ]Z{;ciREKyed5Vޫ86ؕz=gP1r{pcB;?Ya^e)1إ $ ?t|X_yoevB'jTwh*eͼz|fB)' K}OmמP.I&J`"!2@/&,f@CGoZW^C<_Gx$>N"]9xȂϹlԟf]0H%S1lSmFj?ƌ: Rw 8t@R*roOCI2ݛq6$<9T愊|VX5$^bYD=z+MN1wM8vRg~dn,$FWaovo.΋30ޏX$N٦fLAŝf ƶBMP Evh O}1؄ʼqz%&)x$]6xRohP ?X)r u2,$lGoᐉlL`:2_C#&)$Z'"uu~P㕕Ψd霐 ظ[W*}yLKFa"s:YnW$MCe Ds(ullܪhke"lF"M'.5W\.m">>G6ðC5;s}6b:)n֍|M=8ҎQ`$Rc 1pӾ-Vi-`x-5AouJG̶zU{ L4`z-@Z+.ϵ|5HiP?@ Ts j 1UdS:%Ƹ0N4`^s#`CևiDWy)Ha c;RNi%*B8#bI@BbH~e)mU'~ meNZ&zI42. sr?, yg endstream endobj 3114 0 obj << /Length 2330 /Filter /FlateDecode >> stream xYK8W}Y9g{`'^ L9L@K]YROԫNA4EY~[Vo~Ç(Z,x߯|c"VqP}uxÇ8a̸3'$ZJ+xvdtny$}mQWlyRIU wT-eYox~,Fv6dcWuKlZ^i=*DL,% _Ѓ>6OzT"mpU[?\?tm+ʢld4L>!IYSkM?hPUF7[wi=[t-uYeWDxh p%"|ԪӹndsTKC85 S<S4`UN#RS8 3Kge%An w٩*É&놆sʢ4AZNz,vZvC\v Yd{\s 9}W_"/o4=.uh ҋ ؆nzhh^Evm }$Ľ>9@doY$!':wc_ H0V ;<6߻}0 ] SL䱃H@1! ]PCPE-2 鍄CvzWI' c, 8&͟j*GB%3w?0Й{FB}$iϵq)о< cD6nXx:I1}cn:QLo`!4PFoeG&$`x Z=pLi #煈xpR#4˜zu!Xw9oRÉ8Gc[wly!9MQv_i?Jjv}I!XG\eq?JO IewPDL_DɵZ#L?{x +@Ey>^e;S^UjSr`#LE,{ɻkrzs?Z| EhY0:m繻Kp XZm ܃̣Q9BBJF=8/ >ͮ8@l,1(qF V/LIO8H?&ef*ɞ2&j[֓'{,r< QJ!f1>wr:ಯL(9W㬬+q(0he߹;5qHO^)SBU[> stream xY[s۶~ϯФ/Ҍ>s:t:HJP}~Iɉ.=1A` n{닟/^’{y㜉 E!gR?*5ļNj_߿ƾ{,{H[1؋Џp'}"}J/5`KxӳzX)K ,f+RMd4]ƸKY~zZef:yb fiNR`OLor ``#M$0Mba0 KU˜~A4\1?~Af`KG: ]yQ:(MUѬW q9z/ V10D$4W$p}.6fØaUF:Ơ?kYxK5]K+e@yY,wOƽA(sV٭ղЖ@`@2R􎠎"AFh9 ȏ,Rz`0ͻ+"kX0)L,Z S)sHk44--3m{Hޮ_1].Ygݠ0kRUYn4x &=Wt]/s'Pn1iw+w( 5Q@Rɶ!vUZeENs}B0D'ݢ3RL[q;bP,>m Y fERc-C&j⺠WڒIjPvG?d1 d;=V}/ Lj^_\@ ZaԩZ.#!(޼jggVc.sJ yQڬ<""x>:M_GeTYSY87 6RW&!rKO8G lKb4p$ 3nTY׹"w5y fu69˳]x^9D$FcC7,hVi܇<8"9ߡ5 .`a0k-Ѥ)5Ti(Ʉ+%w(-7f%jyAs *[8UVjg4>}K/HXˀBU M2F Rۄ~?ȹu{jhTXfRm0gygTˢR{nz#;>{~Dܝ)83!:5`'({'7L5xEU{vHHnS'z.E6{~8]{]ON?? k??yAJCwLMvГ_T^e>C[amv?`C0NϷs7=p9\} &o|-ɐljrSAi~xGA o$?)ˋt&ǞF1ZaP4#0ﾫ?a8'=Fo]=gDr*F/߰x}c:9ninﲚ.I;GAd+渥Kt.NL??~;UmKUH{gdk)mےZ< dbbQ endstream endobj 3169 0 obj << /Length 2026 /Filter /FlateDecode >> stream xڭY[o8~ϯ26Psx%}H"ڦ3m0k!K$7?7IY("wn #$H$4"1bq F:,2vw)dsǬolN]/3lzIAz݁o/_ gQHEŗo8$,F1!(Ň~(cFILLjPV/g(#) (zRx_.ck}ZNVY}`k"1JZX0)" RQ)v]QW,ZQpN5VU,YDъ(RhA$|CoSvݤz8aFphGAEN1+[ ?^*?}N4=_1뺪@{[?dc,$ z, ^5?#iiĦؗn)CYG~@/'e#ͱ@:77s % |vbpcMǬa2Zt7c:ڡ#dzgH pSW9P+Ts ""@8Bdŀf]QB(JJ)_SXod#םjk5EuoEN%oo^-@ӅB|hWFb&vqҴDeB0*`ޗSY *?Ŋ }3๮2!|/˃~˲15h]oV@D j U ?-^l7v틗G׌ Iv(T49TJI4DK'eIg(=ʈ6>BMo+Kremkzp+OWl 14Pjv@1 N0;4S8֤z~t@Pet/.4@7Ke-\-IoZxC &i6|izyn3fgkLM_02f *U](򌺙'PQa0>OA^c^49ЫA A;襶B4{K$_v}/79Y]藰`նq9[Td: }KAG4ݣ~:htRDX_ogfC`/l.ZHe$ zw:TCC-\ֹ:/9P 0[7%YX}4X悊嶶LPJze`ITү J,7A3ޛKd퇑R=`*s9vx"x7TB`ThӲـ3ȥgSW~]\~?3ܩF錠wY~[aoc@JM`s < K)[wNb8@2^_:z8P̍z `6-ݖ0mb[Yg.kQqUp?(Sɲ팓s12$k$'4a=ֲj}s V箩Uz^eFյ'F C& Fb Q7>Z`PpQC*v5Mp!D5{s3gvfdڜtA,1ЕC{RD49n$){6Q,8~$RRڧNmwu#Üpwc1jbu΀ط `K_c93zr?ߗs TRazZCN[X7Է ÿX|cvw endstream endobj 3058 0 obj << /Type /ObjStm /N 100 /First 995 /Length 2566 /Filter /FlateDecode >> stream xZ[s[~ׯc-Ɍ-[fI,M[(8eCIοu',ɋ<gaw(2AYO |VX) F^"[!HTVFGGIYgق+K& sFD !:P E&֧FØ!gby6'/TP:6\@(/Q(VY#|O 0u 9 Ϭy@e2N8cB(e/0!3cb*+4T`qr re@a[@$kTPrA ~.Yo˶XLעF@2IPBN go&|a) *D2 Br2ø,KH(RE%qCTe6H:&_b۬%yFF%W0UeE^R(rSb9 E,rf ]lYeElTi6Ɋ \B5#q!b6ǔ08s C.OPM~ZabCD-, lXb L^V'0 K?Rh4ajgH[(r:we|R/^Zrtq8lh+Œ?` F?.gJя}y6SS㟻>f8Q_.κg'WD 6W`[/g9}*>'l%\%\[P ~;7z5_w|ut8?凬 4fheI`1e}??Wز}b<[Vl *8H/Q{Ds~y2kBgVyd~q1Y5%葰$Gt|K;,ΰ6X`B Y[ lA$_„f]Q}t>^GM˖zN=0RWlWAvJqJ!\9OQL%IwWGd6oFP#8F㩖2l4RMih " #\+&76|q8Xb|r8ܻ+Z|欑 @BHĕ=\Kz^Ht$$ j_Ɋ@H{ɬ#kD`|~-q>xotIgGC )ўηȐT!CRsCzr~GcnZY HZZZZZ+\99]3(P٬?C`j`D(qwF2*2-H]W9gq-z*_p$TRrb"A@-D JNțr|v>kA ޶*9M4;4jfr:ΌWcq1bAAYDF"d\i1Yuǧb1_;HLQ А!/Oy԰0rĤBwjI6 CX@)uiDyEwB_t~n\/AA%][59R#:d$$lS7'ղMacCpxYs]kaY_Ȏ Bɦ];8 1*s yFdBr"0(. ! S2KET@ڵaPrk'åT"?̦ Ir _^iM !*J2%$oanzl`Mr#G> stream x]o6}C^@K;[rE9ipH}Eņ!9|Pb?B0q(Y0X<߼bkSq\] zd@ 9K3nvf!.y`] Rі(۲~ b8Yr۞jڀ򌥡 ;=ݻBYGP)n 8BH֣hxp1w'5'~>#5H$nVU)s: w5]8Gٖ+$LX2圉8&r_/VySkMZA骪f]wjV )O?*/~KTH] (̏2 '2iƢ3I5(9KYn%ʬPdM팲„w>} bOd%2h,m|+y^dE{"Qlj= #4z&}Hmkwn*{wbD,'F;ZDZ$Oem"N?_T˺㕆  Kes ϫ7HQo2Ro4xFiǩ^!D!Z<.t5 `J5q kYo*ҹ8 F kX@7Jx9CW"gϻoZX}f4l;P+PSU4J2 sM8.g(*&ܘB(GڂvSzb0g9bvWZPZݹs =,|O+EĬ2*uIFH8be =M֦.cC*S yʟϿ|H{F򬦙(Zd 6R&+$ iIO #ϔuAͺ t`sNһy0e\]JA'lk$biM(L#uMmYT3*p&;[N}Zr(._Wy}5*1e}? ^N Ts/p XV0` ?,-?_>~lA:&jJ4^'=Lܬ-X\MΠHEﺨ.4 =/}3BrQ7>!a-B3z`}]iil.B!}crtuŊLkN(%9]㪼]a2ac[1*=^T `5'^b^bUU۸M4St<<]d#.NunԏR:?Wu yg/$aHثQӤ3LӔFsp/k!CImFfyGã!:v@胂1.kUSG{jLN_ehl'7c.lj˾^)aǂ'e#:7nwl߁hs ^^Rd]JI>iYӲ-:}teߚ epO[υcg(mPf_I~~|_ endstream endobj 3225 0 obj << /Length 1964 /Filter /FlateDecode >> stream xko8{~O6P1|/mY\mQ(mN\Qn;)YRN0`Q9 t۫3sBzs19`ԹJO?_,Ldq)` ypǥ3>Q*zxRk9uOXtaje%z}kʮM*y-e-fu̳+l*3J,S(a 4pEMh, Q Hx }.] <Ḅ<l'J{"OH`ڈ&"aTdJ&T{$>%?>߬+ڀh|i`["hMɶ2yQC BP(X*icdda|SCs%LjZᕓI|XUfLO"LoLdY-ab4ّPrwn%ͻh AO0ѓFf#;sq$jsP{ +.:0n7R5TkjZP7=( /F+ꀸbz&+\ R屚YCSjfxVyHPp HsfyrUK!pШt݇B,n O˱rX\+eTD?_ _+Z'@ؘ=@΂#](Ax ̩sY!z=:A ah|Q+~x[Y޾7~.d 8\eir!;KecϿF~nkg?h4 K!Ýz-*9Od^ӇM H|h~ @-cĞ .Tu A|M\Vp ;#@OğezX߫*`wQm߳*oLk +5O(Lnɺ=gCkl U^8nk;lf!Ry^5EK/e]L؍5. wb8 m:zBj퓶YN>; |sS/];<ڦ3^խ~´]Yj}B:;{Br(Lx?<ˠ^"]{ ::G3ǴփY?[p}ϛ@_ P.f\)HtW_M.%#vFvx'i%U17TU@*r7(.֧_P@:N}L/G endstream endobj 3235 0 obj << /Length 1599 /Filter /FlateDecode >> stream xڭXoH_܇b), ti.9˩ԫN1*IB%iˋY6 }~5{w{Fh c1۶\. _ؖ2c_̪\0ϼ+\֋?ޝ 18m`IfCKMd>ё(eĻ?FW /ǷDכҳmM*4QG*>dQfUz`+d XZ_H4'.y{|$j"kSAq4']<-ݑjv3sm8=yµ|q>6-7 ;E4q5(h(8HpWt@rAf d [YY3;z!njo - q͝eEw\n PQ^Spف0.:]58ӫ!]KM;#gBiFnBe-G`oR۴w*4a. y\ڊ*jߖ5UTYtEh6%}@B)EEd-i/eP!s,^e\ޥYF֒vblFH8gSNAڸD]%^GYF|9ך+8*CധVVzYɦ 2*0 \6š!{iٖ^yQR6[MρoC-#4\Ӥ&Quº*N L ,KRirh/45&!ATG#УXd5d@Y6~=;b*;/b#+tu)6;ΝC6@0@p [jK:}OS@#[}t:1i@2#:`Çj r?*H&T[G Z4:ܲ酃ȁ;=1[q!p-\kӆ0a$yN( ҅cJ 56ѷxUQP9 q+ LZ%wT̔sN%oڔ\?QC0χa8pp&jސ2iICRՋ|0CRr+gȪ+@lJTU :fd;uTB;}2&uK^wG~o[7{=uzoen@yGU}xe)+?ǿ>_yzy的 >!C3pu7EU~@xN{d+ endstream endobj 3247 0 obj << /Length 1673 /Filter /FlateDecode >> stream xڥXYoF~  6<>88p]VŊ\Il)Rᒶ;H0vʱ֖c}<{8{! %Z:yhE߳Ŏٷŧ7`OG*G~Ux1:{ko "^ M 27bu;:r8Ya0`X a"L:/qùEʟˡF^b8s e8T׉=\nw(8E{3]8`fИQAvģ-i,S壮 \Ѭ P%hUjah4L3 ́FjQУITP)8㩚*|}ITFRl";2YFx ڌC,Wr5`Hct> stream xZmsG_1tOJ !*67^]D$k}`\U{W=t<=B4x ɐ/*dYT(FC *IT`S*Go}>!*YK"!x B*ф[)Jd(WuJxDtL➧jo"A!鈡pUHYȰY{fZb9/\pDw*ᱜ]q_ศN)lZ.ވT1"-H"D#NLM R3X*!c7!KQ .)H Ez/(TlbP?3\1șE 2IGM$aI!fAѤɤ٤RdDzיW~&,Y as|s )FR꽌 V!lks%$ԛ+tRC1%x|5-zI+Țtԛ&^,t,JkM*ؕsȬ )֩!:A:N.t߽Mw4/ٺ^??.Cp/t/^t'ڼ!ٌ(X #sxhSx0#s^}a7b+)_W,!TvyvX|=}5BmH Q1OFBG+ߊbLɲzg1I,%LڭN=$ojG("Qaٺ|1Y.>x0Yٓ; ]Ve?y˽_:8Q"|`+jokQ/ 5! q-p;R>9#'T]:T5k% Go H=7bB  w^]SMZ8hdD`,pF=%R؁ؓ[Z f:`iU?Deq .! =er1vYAjCmV7,TtmtylqA=tzr]y[!Pс[sFHr->7CʗfH-UrK\6BqM&p| riK\6ono4!4!6!5!7YfejYfejYfenYf}DDAGwn1_o=֣Ǜ&kۓ7{>V#\HLq MSnk \Ѯ4p78c3<d 2Z0CwxJ6`u`QΩ;wB3w'OCz4YOt3-((LWce[$ qo)U2IjH( $z5vo q_,MuU$hio7Z 5(wAx|K_-F́P!_1@9Mc<UFw%ABrxtlDnЩ٠ >X 4̦S( m01]i?X:!@(7`8 0sD[x\ Dn~98YYk5x5.ng&% qzI7>,>G7^}D^a\c{3bEü-F(BXySW)apk3`*,zeE=VJ5k֘&Yxca+="&9SRE0`WZ*!oR qz-r=@ nˇ7F֝P8;g_{h`vz~S'ǚs{vEb'==^#lGGİ83TOu`mc;C duÓXoK ym^QwtxXG_w|rm~zuwijӞ/^w\+U^u1 W,ΏNHdH_WӬG7!];h;2L@5>!͒ɵc>:9:w;:anx%޼(!zTڏ6m!Yj Ph*7ׯG;̻q=NJ0V%|V^;ciGT.EZG$Ǯe`qK endstream endobj 3262 0 obj << /Length 1837 /Filter /FlateDecode >> stream xڥX_8ODڸS=mvӧHpt@ͷ&eU6fl73q.M/^_H0Lu]q%ǜi|Vdy20er}ܥ$ȅk^t5xt|guV:r֙swἭu \AX*bh8uFZuMQјa+.ӼeraX{&6WWED`3}^F)e"h@׀3ago j,,Z9A;ڎcm}*Oz>} ]am ڦzoQHV+.GB\:vPXٻ4Oݑ܋Hbx22&r1Rf=/$4]ke*ƥJNoHQ9$Uy \W[}p]Tu`6C"JRpy-ʸ(c _x){e^䗣0qy(GC@W&fb"$/E>Fm#pJsy{oJHuNY5x4`lu5MJ<˭ h$[ 0m f1!sS 1߯|_R9dkP˖!5i[&TD<)tK)o:.#E63l}b mERk zU+6P$绿4ZZCl(ɲ07=З{ G$c^ (J"OE?`l,6 Nl&sl3|?cQ%[i7 0xyiD\bVq3CG=*eW81 =c°c"ۮs$),a 끹i&@y"]6r^5)x/B-ƽի}$(r]`.̕wF꓉U攁T04H2}O&8|1|ؚ40&C1 oaWl qf&+y{ otFD> stream xڭYo6_!e2P%@6:dڸO00%G?dQ{y<,V~|XL^ű,fJI^SC-rﻟJ20E>):w=jNcgv%8y|(8`șz %)zAjȡ"5"6Z%$=hA꯶kYu㩿޶jwRlD\4ߛX]sE,Fsj"?u)EwEYngXjE0Vkos1dX$~[*Ti|J@T@\a#K)ZI?XL(ԧ^-֛RO[)0ާ 4Cj*_`8on?/ LgRh|럫i/$8y^k\]Zwy8nb8 @=h|z9,$RIr+(^N R]](x C$s3 ukq+jPna#g'ҐG#Hs#QeSlb j Y FKh \2:(:Iԣǯt_?\_ԇ8"A絨`T:\e-;:ןE0k=eɃ ˱:}8`ЗpխB߶~k`6~'rf' l0o\+y:ƿS70חueYũ̏qb5M ZJǫ+. 83l *!g, LkՍud/"zjz kV~}n0L`NlN~xL,Ts$o \LFs8g)#1ˌmL1}WQdKjRuCv 4`zTtzԡpQ\}!Іġ5$e$+2P,$}o}6.F^'1%#Bى* lgx5$SFdvޞxurP 1[Q?(e:ޙRY {aͳ|4fYJ85^u*(WLW1UI;Ҿj_#'-q(sDʔ䪘2"RJ/Nu%]6>x!}S F8EÆly5dјBe `8:{UЂ~j/;1.5%S4+` K_۩{F xg.mv]Ya نnؗAjZ1TڥJ"]+tԥeqH8s0c>wǎXJ6fٶXNi@x X1X-eۜqqxʆ4k뷱B c)6 hr2( YdIRV-&h h1~Ќ(=c"m~ڵzkDՖf*'fyEVGbfB&Z@U!{GuFaETJ 9b6P ֔|(^eEQߪ/j- u*/{A=U~w=Q=n om#î޺&5d гgԪ/x`A]!M<?viGs=I'ͷ뱀|WFIx)K>ɨ{o G۷-n8^ &ԭj&!t`nhw0w;>k9ןK\.&ru endstream endobj 3283 0 obj << /Length 1662 /Filter /FlateDecode >> stream xڥXo6_!d{Hddh>@KMJJ;HUJiP:Q}hl1{=O"'#Yrx $$ |gY87ns[Z6yC$Y/ˌ;0 ?Qkw2Q6}óu(ݞb%J1sN6dȚ,∄ #Y_kS^%R;u-6<5RT%kQ_J^rpb5 8Գol/t”8샙  9d=罙/"JݓaѪ'f!W ZҲ_[=Q"՟'E(2{"Bf(чZ/O`$˵++d޺UAT*~߃]y]vWL6<|1o޻+oz$Ӌ3{l9yu'I;nv:|MIνf9!O@ӓy!r0`ozNB!F!rI6,,|yң.F깅Ra ؏5kõ:Z"˚H}OHVPx2/X?m'uzK`_ꞥv )~1:?T?ke A?">kJǶyDT] .q4YL.?_\L%,Լ'O94 _VϷB9p`{s^ @E1sdzNBlþ>3x7x/yn`o%~> stream xڥX[o8~ee fE%"ݶ v6ۗv%:ю,ͿsxHYręa"yHwx^z}z.ǃ2(`*M}`/j2TKU 5u{h׸~S)QnDDG?TQ>־z'q$ͥocGʛzQAuCmGS:*?^_^RC˽7O87Nq KvGʶpJ>ȋ훲ˏ@-]Y}]q<>1 W`Oݬ{sqQ[Ol$PgAK cz#T6dCIoqi$e\ȗ\D-R)<ۿ]ޖ[S7CMX^\zdPF~FAԵ|ޡr}Tn-im-odv1VC[OZ޾ӧѷouQ肍qrTHPF׻c(b-UVٹfg {KYև%IczS; i۬rJPӭ.yo}ug$Q:C\He_mc(ψƲJչ3uK]Ѐ!ڮAqb_suXsr&L*ct/B)Ĝ0%NH1wn% n]5χu~r̹6pV!Cfy$ ;Qd==q4d6\Ōs%gdSg{.)R$㲋FA#V1y%%|3Q9*5OakXOaGR<-ʮ$4?t@a&,zg.TMT ^UyD`)IYcLh% WMtR}[ݶ Tj[od"lXzۺŅ$b%w7U-~0 zyN!%1SɉCS[qZExm>YL,BH<3Lh4A ]vǂg9/=+4ka&\x]g*vAtac+68nϾ< }'Pī #){*nDXy\DxX ,APC}&jl[Fo>9Ց@+k{ڂrfK \sAB0l^h Yh -4N 2J5e&J] fxP@`DN79{c캬IVU1>D'Pe~1G=*ıU`y[!5"xJPb(![4#A QښvLH<($ 1k6"6sEOs\N8/g YhUȑ2"aePƸRtݒ!,I,fAhO̍ v&J2NòwELYGYݸTPjbHjMxzXј鸪<tNu BΕvY9N lQ#%;Th_`^]$SuSo~xM_4n `ڄ| 1x pYDg{ "(8yE<1߲ӟ^<$(wNp? ԺiH#CY&L [օKq!ڮ8~zg )S U?(MiMHX SeFf?QP endstream endobj 3311 0 obj << /Length 871 /Filter /FlateDecode >> stream xWO0_e5I)01mА= Bώ/5)*b*҃H7 ;TECݔ,SP\_eDP!$hiol5/]Q5!ss[e&=ElBm; @wq^S"p{c]Fi,H/qfetG-ihOBxaNW`g.S 'rAbnt(~PRވ> stream xZ[OH~WHws! }p uv=mmv0B39߹ȺuvS,Z-M(`6x8mÝoN </B֔!BKۏMK5'apY&j=}j;6eԚw͒8NǸ"fnlc#N@0dG5$u)hG_}*@KZkxgdsv&AevuxYC# _H!KWyF47)S)CAc4VWOd_;~5A]Z>d!D{o:^ݾߗ 1_z%T&rY5:U)D; 9u='b endstream endobj 3255 0 obj << /Type /ObjStm /N 100 /First 981 /Length 2399 /Filter /FlateDecode >> stream xZn\ }cDJ`inm<8֨1jc'o|:(*T v2كClO8p"i@B1I1衳,HZȩ0j(%a90fRlz#cl6[0ζ+٨uZ`1CCmz(9 r $ cd;hC/&a 1cژ1IF`TTl$X:%ۏB8ۧbH&uhXϔ b@mz絘gU|вM5GlF/ͶDdz>%pfӸ0˰Sǡ14m4-VAF# LlM8NZ(/0ɘ`~QF8r9jx<2evCwrJj0Heؒ9ػQ둅ljϞ-/;HMX2Hx~%-~0;/_³ga[jzi!|?li1-8x /ꏫ[~_VOXv4R` g[??#h X |y#z}w24nF/4 ѧWק,/NVC~OTM#"urF2~v> ˿=8?uO>"rDg Bd{zu2l:&fZRW_^ϨhdP'f5f8%(8"~d.N׿Tgzׁsun ;+HK7Ϟv*m_[*QYf~}w1^|dK< P򣙰96'v iN&qkLvT;RP5wT~OGA(cG!O@bAqW薩 NI~c!ATZWVjQ*MhؖER@7wOuaTIWF=tʨ7F~҄ d3I O<)ΐ:+C3hq )1Z&:.i ndlE&YRJOVgQp;!qaK՛4E}5)֖t}xW~k%xxy|a>ʨˬj͞11ʎf'oGvb̸f}.h{{k u|sr|r_Ub96j'Yتb˸Vʓ58#|f4RuD$R^dׁQTկp4Qj jT;)FQ/{ָ\V3]-ϤDJFkvjeOiBKlDS$ߜr6!=7-`{;g“>C!N:}n$v{0rjmn#G.\/MvՑ#WG\:ߛߛߛSu͑#7Gn////HYYYYYYYY9RGVGVGVGVGVGVGVGVGVG-BA=$U$HjjȁINÿ#*#료TQ4*:naѹ4_fXc(H37oJ5Z uB|%k%DkJ}n3vQ)v^R!kGoãH3hbGhV((q@XR_9PP$ؗ.jF-'t(e~C5+8lILUxFK] ,m\E&9O:@kbv^Э *s%} G!p *:_2Zk',Q$Vd-Iwˌ-"r˗}5O%JrUR̅v]6P~jaDR.)®4SE,S)ᆨ(^zMFs:l[@bNJXD-))ʮ2M-bþg/u%aS1+O0(RBeaDMƛ6'E]v ]Fdxhl> stream x]ێ6}߯c tN-\h@$}PJbt^&ʶlJkD&(vőHΜ93ѫg/@qG#|$x0GчGxO}BOZ"g?~Iig/Ddttn~ӫ8ys/~=^Ξbo_]>\b>"J+AKO) >@BlWhy5FA!2 JBgM[R=@ {FZq/RCt",A b(p,cl(q\GQF ޽]륍 fگ+F2(k2d8Pm-hMx1da/%IT^aJNFTmFo{\'/H*(IFi IoiW馳$W}kWnfb:9R\Jn柞mʰ`r\8@@ZMJh:۟hep|g u/}:Fvfԕ g%#Nò_F%po2q0&hU+evx掊v8%G 0`kV֮yZA@!.**]gx*n-J\D:i f0$w7U_)_`Mk z{t61_l50KatqU?R'|D>M'v 0u=a4uÞ{]dfBc 2i;8X:@ܮ,/LyraK(=(7P ã}"ev![(r--ՁiwűB1ܣ6YԾ!\ϻ@m?I XXMOQH̱t侧ǭzZmX^t>YOv>hn ~D|gK0|!̬,^1t]LہU '"XIoݠ1@~-рxQaFCnjK >̲ePYt9Юh@lSV="8sC_:4u(}yس0<  h,< RVW?b_ ^{xrp`J-9eMH{~ gjA9I]dYI]vXEA8*DT>p:$کay[COf&2tfUKLR[/,Υ^`UѳiԖp _Sf]Ş夶8p'U0ả<ܣ ;2N&_r[%N7 5!!8"|o +<~w!LT6 vZBuC  z5m;LX+5 PZ:8@{'ǫ3 79]{U?$ ;HqcQ~"jZߺFqg a#wH!x `Xa0 }JUe}$&,$teYHMx > stream xڽK>ɥG?$@I {1$Cۧ;Y 2@8kއ.4j&U{\tSGlM[mj}'/Ogo޼}_~?߾7k?>oË>~~(kOk3N)[_K|8O?򻟾cO_$eF %3F%Ix;/該FeT%Ɵ荏'(kBյYԑ A^6{a( ?D2FL)-M[IșqC\_p1" r2GSr#1y}<%Q1 ie?c>)1iyJN +cŠؠ!b(KCri0ZźBˈ5IʸX0D2i1yX4DRAe}l\{C[ ՓވY=DYЖnEsYrauS5"*"\$ŒXH`Y#wcnEW~/p5X+Z:;#Uopeu34H1mfJc( Q;DL#v;I ^ꚃĒ{ SΟ4b3T.sFVbS!bSua"mŚwΈq$Ӯ8cԊ}r Q*c;b!,!!bD_x)bs}rZ^%=q퍦VFG7.!Mrx;dw!qCFA k~w ,Gmhé"[tbo 6|5yAMrw<;vjM^Zyw^eutw`IY2YVΜܢ{qxÙhho/vkeD_亮;1g|ņ_{}5SLqMN퇈zO<6ޫH/K=ys~eF?wۿ.[J (tQg]ɯ[߾˴/.OhBrP9htr`8DDDDDDDDDDDnDnDnDnDnDnDnDnDnDnDDDDDDDDDDDDDDDDDDDDD" Bd!Y,D" Jd%YDV"+Jd#وlD6"Fd#ىDv";Nd'ىDDDU"O"O"O"cp`P0( A`P0( A`P0( A`P0( A`P0( A`P0( A`P0( A`P0( A`P0( A`P0( A`P0( A`P0( A`P0( AŠbP1T *AŠbP1T *AŠbP1T *AŠbP1T *AŠbP1T *AŠbP1T *AŠbP1T *AŠbP1T *AŠbP1T *AŠbP1T *AŠbP1T *AŠbP1T *AŠb0h4  Aàa0h4  Aàa0h4  Aàa0h4  Aàa0h4  Aàa0h4  Aàa0h4  Aàa0h4  Aàa0h4  Aàa0h4  Aàa0h4  Aàa0h4  Aàa0h4 AǠc1t :AǠc1t :AǠc1t :AǠc1t :AǠc1t :AǠc1t :AǠc1t :AǠc1t :AǠc1t :AǠc1t :AǠc1t :AǠc1t :AǠcpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbpbp^ >aX`d(>y:P/U[~aX#}yͳjcYrigXgZ,k_lϙZ97; vͱ(X;-ak˶FI[Sŧ?fҒludiBk%׸)e̮( 5c49;)1h.a uF $ $?s]\ǝQ|''rhIu{A8~2VTYh1R;4ȁ1 3+e:a겔!(.psch՟K2Z}S@IpKM^&7Ey_$Μ3Z/ycD_'v8qӺ+yM"押u|ĉTts]6<%l9|[lH*>s~NBb78u'uD>ֻOC<~F«)+#. dpYad0_^ Z?q}MᲸ>JA_Z_S,R8s=߲xN!չN/L>g1WbgNW3EM5|\(z!|x=S[% RS#)\nR'1I\$n%I%ag_qMr'qJ)/ endstream endobj 3979 0 obj << /Type /ObjStm /N 100 /First 1014 /Length 1881 /Filter /FlateDecode >> stream xڽ͊dZ"f`lm3ƋcoLE.QU]]}BG'K!\ʬU*~=D j&-ph-k!>f(ծd"^QZ Ik4 $Zih@3L5Z e֨sZ \SG6}EF/MYkio:^>׵y>jS}}BhcIP>B̒Bm(`Y8/flZ*h]&6JІPYB1Rm\:`&ZR2JhL2jh蜖Zh ӗ]t22BBOkBġSM񒚖J5jZJ]#c>'Au+$WtAtP UGR|J5F $<9Z0YʌGeachUΈӤV1?H߄iD;5e0(ZD')2?!e&[P((DtPDk4,kқ CF2Zij 4;!fёi !n 0Xh>x,ZIۇop/_n?_~~c2tiv| K'b5K\*>|n?%~Okm7Prb5ver!F*ctDO+FcC,'}GeXMyT#wFZ"vCk|@m$A '.C 0,QvFÐ8)82 ;rH).6u$LKKIZL$E΅)`i mDa t҇ .t! 4T Vå> 4K,}q@- RKbgιC#XU)1#L,=q@+aؚrT^ K*=z@)ch.tf`:1F(a1q"cr  akka  DZ-)fu2u=CO1t^ڻu[-O@ι(IHLFn:с0BLAtx-wm׎.N0OD޺kDG\2C,υعm0RqF' velKH3䉸[r7Ѱoq R?i3 gr 0K4r^ɭLGH<R<7^ #"CwyqR.By)R ¼ !A,/A4y)bR RC?prKԂ0/BqA qF#/j/d(;Ǧ}{}_i@:{C^tNgbYJTrWZ;%>`2#dBDG8!wD{%wK }z@ <<.qt /Y8r~xI ʾ4%]v\n!@zR $҅$X"BfJ*FFAw-DmJok}\ݠ0 endstream endobj 3980 0 obj << /Type /ObjStm /N 100 /First 1014 /Length 1983 /Filter /FlateDecode >> stream xڽK4+rY!1BiaTnY8-z|{&#U[*Iz"h&hThPܢj):okRޖ=pJZz1D4ZբʼnzhIb841vDM,-0K\c kխ'nm;8_% .,CJ\%.l;,:8}+[?b.݂ hJ%Fk=)K%XT{$i4{keT sA.U+0K•3f#Y:5蒬s2ޮ3ٮ[2m1fV{̃JIhQj$%Z&+8&!ZZdhYjZ  ԭ_ON=QI.Ѣbђ-d{Ѩ&ԉ1WF [?O]|S1ԭhL bјSpz*E2ZPv[TQwe@Q}cGY sDG]La(aqh@S4&:EqLbAD=cѸ1YE%8ď&FVb*K Vb1Ե7on?׻tn?wŇ{g(?ݾ}{-mn߿czy+3:傋c ͛t!ݾt*}ϿCOg=.C;!pQ%{9 ,]١)C]X ώ2j &8g Urk$jy`ЅlaK,Z4Y2&5 ɱ4\4gpc>pc3ԕ  *`h 5I `1eXX5ubd%¢KNHRt=xFp9,,$7Ɇ5*s$WxgS .8#w=*& ɀ04GP&s+|r@F9 rN9|S*zUWN  Y![N!Z-ns.ˋ-d/ʶ2--w{nDm }5gۭao!o}w\S;brM!d5zKLk'&=<Jn$;=OMy0 A4uGYjd HRS IF"9ꎰ$7Rԝ`d 2a$B[F)x 0~C\!jd]H/b)_^v^ 2FzA,d12 FzAh ^~Ar`,:̰r}DzAv Fx1wagabCQTW9jAz@pA~b彳㭁A .E_K 3YMPfyNe`zBue5ص> stream xڽ\ )l6gDJ%0$@[:;$5"oߟ.g!aؚ')ҪJ=QakM|=5(I!kpjZ$5 ֐DKKD6 W9d`-'R%'pZILl t6mzbfaJ1TS Z)>zt0d]zUP5GTQF\m5NJ>[j+gl6J$t(pF$<T6> D9s6$(s1$rŵ#3s61F?f֢@2VSVM @kIu[Ҟ ZȰ+ S/ezm9uf jF_L[4):84ĢIaM@âI Ne2*[>"|s;bUFg3R r7jAaQXNyW Qk$ Q;\a`=7tk kEVXBYakX b`U|&6o kU0k+a?n>}_O{}C2vt~x_҇ >UǑ-snқ7>co?w]F=2B(-zd<'8< - JCU>í D[1 Bb]1(&~zyz<ô=4~A1Vq cU+˱r5`d bA`;c-Tb^($SDATxBBTD%2 BAbBU!$,GAܼfѱyaY7!1wІ5{W!xblػw u wcwE0BQmw ĥ\FmK~ ,e\z3ƆT<Տ ZݐO+!d\"ri*Vytbl r1(oKgp !d\:e6ȥC\F˥3\ u}!!SB^aBe.8”Ϣk#I#*fs)TȰJP.W %(=)1SbC 3 VVB] 3!p !v(CTFA*2dء12d!jB j9!. V\|h>'U2dp4\+C 7KR1膋%gp dRNʐʉ:!,-w]''ÔaGWQ9 1,^ Ɔxp{K CjAI)Q:lvް֐jm ֟9@D L!aP Q69<!d1 1/yCüwp9=-Z| ؆}Cb;!< vdm(S[d&l&gl&b٭Cl&d(NOB8NAf9!\B•*bhސ\B W+UrWbR9+UİHĕ!R A*h+'u^A /JF%#s/A-elRO:"8D%%m-Ki1ғrPJPv9>.1ܩg endstream endobj 3982 0 obj << /Type /ObjStm /N 100 /First 1014 /Length 1812 /Filter /FlateDecode >> stream xڽn7 ~ -Q.i j (q}Clbt857sbȍ{Lڐ*Q4mP(YjMȡAS::@$!]В@LD[t搈8zm-!6!6zH~:rԔa_eG?OGr s蔢CST&S=UGD5+Uρ-܇={ % Ռ9`g=Nc< J 'XPE&5 K * c(=6C$Ԯc -- hRWCD8juJY[5awpի;X#>H>C !R:Ade!DnGJ- @ԅ%P erBxL&eq!COG4]BY=unC0m0 VwL*6#-s@$p\ڗ!hal}0NF͇X-O@T \^ .ъϰ2| Fpī_rABU_Kۂ|_K#!8VB ܮ ٽ61X*1ȆLdmC1ؾB AؾA,-Y&aIe2 .8O].Cp2;v]'sﰏ<#d8E!< OboBB!< Obi Oc8e!< )<} &Ùu}6c͸uë 'w<*ܕo˲0t!,C:cG7)j^;U<!b$87ɞjᬥ e})}2tO2:R5,G} :;dRMJ2As&Brل0 v ’JaCl2XRBȆ , ʆ' ’J'`I˰„8JA6$`Im2K*OTe\&9?\b'v┩1Zz 4eZiC `R1 Ji )`B!A/Qt&]AS}F(Ws0ytAƟ yW} endstream endobj 3983 0 obj << /Type /ObjStm /N 100 /First 1014 /Length 1863 /Filter /FlateDecode >> stream xڽ7 *F+RW'bwF\ `SS;=M-G#~#(͜B4GP8(*Y AԤ e7r(~%I_ 6P5=T1B-Y NW`jbLg*MGZOkB+R`}sZj &'.ڢЩM'[am+܍V jOhuDF׎0& - )# Q@ĂL9':0ԍh2V pF,A*( 3La&D[qJd蝡:`SE誓90"8ig=J2t0i8 |֜!8MXJ/Q&KL ˰Ʃ kLCFI XI!ָ NI!ģ(>˚xO/^<]]z~<.|ǻOo!r۷4<]~~Yǧ R" ^/u|͇p.|?._/gBi|C1:8VUTcB^byCJcp1!u!p̚mDI%zXnj9H"C]N ! "#5.DGV3we^r[nV"aBuPM4.QeXTcĄ΅(^Xr0J׿Ateu`0*)C0rz2)"e Q./(C0zZ/Qp(+ȑu u`EJQFRxBĬ:be^$6?Q@|E %m6`(Dmw@\%D8J|b<`| ˂3;rYr,,tbzzKg[Xoԝ71m`'Gg!*<TDX!cG%B9 Rg4Xd45)lnl0v!6f{llC0~(iAf}firwjqj ᔌMkA+l0 VnN> L]ai ӅNNcC,fB!S%a"Ҩ110&;Vڌ>i3 !q@(>t!,_;)]DYy(؎zG\.PvYHȈ"weߐP(}|FN@UaB p!Ɔ0 biiga.D]`2 EsT4P=S`P6T)`Cǃ)a+VJeY8w.XQ8 6bxVԦ{ XDdd*k 3aL}}LGTKOQy2q2 ON#&!?b<AXc&6|TrzAmlº7!.l1/<*OyV#g'qVCg'qVCg'qVB ҇ kT[=晣'QZK6KaG1c V̸1+f<3aŌ Q3`Ō63q3.Æ7N>t}7 jQ3DNgb#у\ɥ !07 OKnK0t!4Kbz4K+ɚ-OZ4e#9(eKM̊9p endstream endobj 4612 0 obj << /Length 2738 /Filter /FlateDecode >> stream x]oH#'Q} \O:tCڸU$ߟSzcw6@f&< go|@Ec>8< yo`{$2Si;O߫=׍q$ߧ qb9bˬ1s-wVO8¼0M{04U`=6'Ҹ Z /0saܱeqޅ]0r] J#PKZa1 EQ4}Ͼ,NLƶ^1dD*1ҌHKf_OڞL{,$ !9KZsO!M0/ÈSL<9.)% 3ƒ#x+LQ>!^P.2o SOzUxP+k~"a1Dd|S#&`&U y!(*@.'~"Դrd#4[5_Y#5Nk(AC҈v Vos 6'wsIgeA&* int9=JaR `E%$$-f@~L<W,ՉI &*]u>[pas?.+]Pna^z]D_Zſgp|k /49-鈟e-++Wq@#pP#cU 0:TAwJK<,+2}WG XE^0ab&4f1r~43)j̿of߾O"g@F3zs#藆໠IZ?x[\M=^U6`x XsQuwsB q:;BNUhu#A[씶s}xuh{ |oOwsU IN&at6s6us9il:MԵP*2L4!Zs]?8 ’G*1M[l^r,=h4+xςCCl>]`xp-Dmh x}Z.lW/!rU\ÍkwbȁZplLlĬqldJWUsZcUyr>4`j8{ςx=_(7Eٷ _nj4kx?? PXT݆ux,,Px1 qy󐢂|O"p~AA"{}M,js;!hY* Gd \m)S= wdݞ> 2Nln[ϞCd¹v9(u2}N~(bϼ؊` !Jap8Lû@rļ6uΗz(Hniv )EL3 :PbSjFɕGdz 2k>S;p2aLq2B"}.DӾ!KdY ˺x9meYP.غP\z6U)\Njʇb-fd#끁R}8G9TD|2G8sHu$AHڙG_UBuPq5xP;|T \< }`ꜙ:?0;9I)$y6@4̋ϸ;eCSb>k57/"c.n{9\Fm3?O 3Ͼ`a>KcykaNy yyu=c@B8U&ܺD;j}G l+K&aDIC*|z-Q2]n! .`6aBM0Nrkz5J@Y6(6@mLP {%. $;V_p(%آfH:dE_Q/E 3W;42 -DR GH Xs~).d>Zushf9HjbќN_scgJwgcڿ.3pDO+/>/X;LXܹ"֚r +>3\0 I!wV/A<_,{la,a_6hCӥz>h^ x%;}S.s/$>**Kug5Ջfn_'㩮 72ʌI$cY6]S7Al){|NOXݒ^T3d{s`T~Pׯ=MaA]ߕX$}9J}KsfꝞtZkJp |",J"E!/dη endstream endobj 3984 0 obj << /Type /ObjStm /N 100 /First 1056 /Length 3384 /Filter /FlateDecode >> stream xڽMF} /ay)B"DH E$ EHZDߞSn=ɂT/`zn]˾wu1hqZ@m l}c_"[EQRϲ^/lTc$]q\mj(ȢlŖ-ȤMg4wKY}-~\_Z+#iݖx=U.6TjK_s/2lTidq\+K}/}yZmd_E6 |_cxrXUs,([J{\R}2s6\-Ŋ|rIa&]b s6ݼ=0gSi2~aΦ{M#ߊlZe?6gXٴqlQE:9Y-6e⣘lV^l.}!e/l.umͳJm:έ2ElyQWs6'Esrr^,g +ctyp (:3Cs0q1qMRNΖHCOsml*G2J^W%}lKc\C/ly-^QsZ%}I7~_"9[w#y~H}Ib}Iw:!K"O>yx?-}/~כ?<~ݷOڲl}%o+W]e,l4'~vyl_i7y\?2x:ϠۅBq2M#ȅJ]e8<2ԾnM"}}n qa^׽%>gȞתIr]+cͷղZOI Yd]}4B'!Bu BdZGfVWݘ Wi0ti;:%!h.׷J2+^IYN3%薳!7t#.!~n|6גh ގze]J[ǃƳ]橒{?D%!4•M"{bS.XՏ 4Pѓ|3r'X73qu eGHZYǍW^[vBWʯiN6S|~ 4ĕdTsv~r'=qel഼ly2j +ʦ%'5_eQrSY7F}ﲝݒUcdMCyz&l!3ı!My=pwdMmH$p&E{,"pў.ڄANC -qizC$]r⎇8,Õg$roʜ!fI4D]FZgjG gn9Kp'g,y endstream endobj 4614 0 obj << /Type /ObjStm /N 100 /First 1014 /Length 1868 /Filter /FlateDecode >> stream xڽK\7+L6jTz`pHYޙ,B8Rԫty!5F=sRԑCf(baiTzFs9VitWC v4#Z}BK鼠s(,ꨒt[ƣ7FS;jr11* #XOøXjs读&-r)WEjҖ\j)aqӥGIznqDZgWף!JzrrE]zAGLGL1d.i蘋uYc A\q ѕ$'<]~~{r>Jz 9]޸~pW{ 60;O"C} Ho !od7/C݈7BW !+}1kS 5ʍeL=5n\J2#b) S\9I؂( { 6BN*IwB (FRtH`B@wqJ6C) : k3lJ,Fbة @'R5֬|M)h-,H٬PVc*J @Rf} e>TJpB KRxJzJ00M |U*t6D9`+bJT0 7;;[x@-'U,M> @b(VNJaLT!#3"g~H`;zv5R&D Dv2,wO-?z.wjMZ!_퀿V5> 2öR8B- jխhX݇B\@P-вZ7LzbOeMvb+Zl bY[!6VN;,B6!j-sqpdbyҥ1°='uYmsQ_a. a{.0sk=n>DMÂF*J7tN8&!ONЍ ot{O17:&YscC&a1̍JXscC*TsJY}dʔIos`rLGs sc3weXFb(FPur&ÉHQtv[L?Ѯ9Vʩ Z9-vp*Nakֺ Z7 {MEвi!ʠUb8<#U5U)> stream xڽM\ Whn4")`p )UEAPgLJgBah!#R/1RJ%FOdVkԸ[cV%֠4ٞTF{Aa?ڎ~=O)FQs3\Kbf-Jլ('aVT7b zkU~xIG?B Z36JZJSŬ I2*peY֥c-y؊X Xn&b&'t3SSR@I@̖Z2{jV4>+ŐLmb+^Z:[ phIpVMբx>&-t<1Ń1L&DZ<Gqn`UtV#@QԬPO:iH=4Vf+sIC-C݀;8I2+N~-Z=ҳZKziriN5<-ASAFӲWp0Tjj9mqcD!TF?*R ز+Xs7jW$L [mxCb`c %1\ Ї1x1x6,1N@ r2D\.C rA(mB6ȥC\;VuqeȠ\.CA.2A.2e(6 R EO{`UR 1!?ti ec})VDZ؆KcVP0p3(1(fX &E;y"2pY&\0?|bem!LHbS!vzA`9irnz{^rE/O׼3tD^A-!nNdt++Ӯ:T02X~:^Ix9YB)q!<!ĎBŔ;Deڐ43u#x .G!Ȇu2\+b rE sCr/\ ^"l9a?ٮ_pI.p(Fp~!C!Қu]P Q!D.p( K [a ƃoe2*[-f[V!m} C8+W ;' E%g=(ccq_in B-]sYu`gq1e#d e!l}}ٸ βCw ķ;aWE.N!w yC.1C- C[ucylX:Tİ"*2l<. :\Bu2" u"BE uB .P!C] g6|E0]%VvM&CA&u2t!\(#!. !xR:KeQ7HCZ2 Z .!nKp !tB`I'I"5\œlptAkO@,*|9D-5K"^fyg Y+rAURb#ʚgW9h1 q2xBD? endstream endobj 4616 0 obj << /Type /ObjStm /N 100 /First 1014 /Length 1820 /Filter /FlateDecode >> stream xڽ;7*FGƐ $TI:"B)g-fѮuGg4-YJHd@Z!תx - LZVSShCT #k%|Aѐ' MKn2ɸhZ::AiC2e(dB)]{k>Z-ܺ0V0$W+=0:̤z \Du ,]o>zDtmH{Z\  AH@!kt0i 9Hb&BsC>0"l RTY420ŅS 5rpPsZʡ2V%Rz`NBmj@(R-HVFh8Vz0Qh"ZCmUġq0& ]& =]-Y7ꡗ~2B`zLr#3:D#lwՀn= pvjo1t=ij:YEJ9iME3@4/,.36pjfU[)cUtcq"a%,jՎtJs M('=\޲Rr7LS~87Q&leI Z}z /޽{㿿~w=ݾ|oy`w퇷}oJjQGڨkӈ[nqTB/«Wc}u_x~^~¿ 9G= K!^7BpoAFk1I\P[T9.6Je =$0JLj'B6BSoKI=yLl<\s;˭R>lpk!G,lȑU aa0]҅(tiKB L.DۯKc0] . bc(t@`t!]NKbe;.VKEg-_ tB~] `t!.҃i.҅uL.Cٯ1u2~].ӥ .]G.+3n. b҇S>C=Kct!:ХAL]-8Q1Rr>-?A;UEg>RLX4Kp2Qa{@!A8^s IC^b3 _Q}:I,'_%e1K"[ :,`x@0֧:a…8 ڇ0>C?p6kaCݺ^ü^tz=!zC^sXiǡu6^zB-]4ӥ!'tiKХA.]ٯKc0] . beti Kx5KB282uɸqwK0]z t24ӥ !tiKХA.=2S`tNDywe+Vzl1yWI`P3M 0 !dlJ}]ؔ$bo".Yp<= R$\y|uxī]ϣw~={3/DO@/ؗ;/ 2j铜'?(A|AX &^ӖaAe(b BA|AX &^3/ .Dqyy0s`9 <r ^T<2ݪ=&[4Ko` bghti S.o .}|@1uC"Z S> ]G] -KOn]'6ͱGCMt@88Z,-a`i˰? ^3 vN b>ā4xA4؇X>_$ endstream endobj 4617 0 obj << /Type /ObjStm /N 100 /First 1014 /Length 1815 /Filter /FlateDecode >> stream xڽ͋'WxL.GI m!Ceww4mqgY>V\*r)ZhZBEF%kABkBKi9(JY%F74Br!wZ!=5 YD)P&9US2^U"Uz Q#v !U^q'F Y9`ZoP@Z>]Y#bw̎PBS5rcmEwKkb'% RI Zj֮֐jO&r" ĜRh9rhTXK\PbL_9:&ЩdDCK#IB'-ư:laW-!za1 1 Ϩoa$5؃hъHǁѫ֣Pc3MRzp5b88 9J-H?zpQ8?MjTKjIpX9q2p(vNrا Ӓ2˜8QAK2}nH82zEoQQ9lh3eL Q=`Lr-O/w\y ʐ~p||\~sxϵG *QԧDXH4b6<l&Č\gTg &.oPKQ!:Q 8`Fu0:7Du%$dI1'aI]!N9 S.[")74SKn`b! Zi,ܤL*=ڠ`J1Bi&†G'Iain2i&Îͻ9a+"!әz!zr]G0X uKcO,] O, a6djqINiΪqtmm;'Cddۅq$ds{; u~6ۻ=6l17o6` -7Lʋ*DAa!Q!Slc˼Cnb)҆X,r o)A6R`g ?! endstream endobj 4618 0 obj << /Type /ObjStm /N 100 /First 1014 /Length 1859 /Filter /FlateDecode >> stream xڽMe +L6l $ҳkfWͦKbUIև}[JjM$Q%Ľ`3 4 ()Opm^'n4F=#jh1Oy$&6YuѨ dZU$Ӡ@阇W(bTcJ󘧩VfImDʴySd0!c6SQDF5X qE`roFe/)')iMBt-I-UZ5iړ0] 2ISbcMPSRR6Թ6qjǨǞ0j0X>`(zSy#b2Ӡ~imQ"ǫr^K1A ?I"z*#ji4;4l)LiNS1-fK( l.yI4#iFi6U5KCbhZ3kJ5fNpAi>mZe1xpx .ՎD'&>,Z1idciԻlBoli\1Ҙ^ ĵi❉!v*i[qOO>|~r|o~_~Wʿowt|x_;.ۋ·̇ 'fI6}ӧ}N}vUK6ѲšVJ,߆^1F!f8h !s!C/Z4 xrďΙk߆9GN2V eKtOR^`!k8[#~A4Kr QWC8#^ e2a###!f C sAs1hL #yIͳ˕*R^9y9ębH1lI^*P5]2nEb8C"^rh*oy<|s/o/!tC-sBmhCt!چJ!J" CD\$$bpD7TpV1? p? !VW{py+UWt!Ć&p1 W7KpBȆp.Cˈa鱈K8e6"BQn;^} n tц^ӡOB]:~FK[??B6g16g17gN?ϐ6THj_q} **Xz%*dqZ ^P|AxAA,mr/B~ !΂*d 3xA,B6KlT3yLR]7KpA{' endstream endobj 4910 0 obj << /Length 2106 /Filter /FlateDecode >> stream x]n8}W lTNwxQ춍[]-'l9dKYk*u%N1,rHgΙ2bN>y1{`(d u]<-&_N|ox/S9BvR,7kտ]GNǷIwꠅ‘`|Dђ+<i<SGV-MIt>wk\w!\.|,zr"}fq~懋~ymn TZ(Gplo6!^1&b"om-%JO&e6q3)A6 xߛջP*n2 ?یPf;v 渍)xx\ &E42y2m^jG5I VRkȗbX^a?JpN;4|S#R<+&mpx(ܵjѦ ДC0@VՏHVDb/~,Xr5qiQTyO_"/z8؄NI=Q"eȵ ?W~\ZycRgL@'~,H1>҅bĺcƺu_@V&hH++ł.Duf؅L@?o{G{KQaeJvc",HfGZ$l&Cd~lX&C7o L\ U ,q. JfH]Y?̭΂'8Hf<Uh.Mlrh7ФGI\oOO7jcL^4;cjP),nahtQd3{I~|Q԰hJ͘$4|mEaS 8b{iS@T~66dyxxA‡cD}~6x V)ԑC4m]R?# qKSQ˾p=v9QX~5?y:g}.YI\z6[*Uɸ|^Lixwi p%M~ذVJ=?!JƑmK`ծAKHT4 K#n"EM˔?~tM$Ͼ__sJo6(ݩv}zrhےRLx`>>|W&t[rnzp#rƙc5UI1j"ECëp ßZ%:tZhGsF>y &ݨWr",)K8}R` \T;ZlCMxb C% >6هw`xpzn'^iǡIl~@{0>4<pWqԢ"(mZPTYb8ܾ QxuM2Ǻz~u凋ch OxOs5p毯V^ёU05WƊB;:3a_#0oŕ^Er^G8( klF)/;%Ǩr|pRs뿌|G6/BW^u*J4ju[ \HhEAL[;UT;UL!olosx97B<yzE?s/>< 1?=],T3ӳ ƔݕX\4ٕEuDUWKqė_Zo<$[|̖f(\g__Ϟ& endstream endobj 4619 0 obj << /Type /ObjStm /N 100 /First 1033 /Length 2763 /Filter /FlateDecode >> stream xڽO)xL.|l& -( CAE^F]CZηOhj}Y.̷5yR %{ܛ74aްЊxc =FARw!trVu?xZ=H_h.-2i YGW 979bOKchu>ܝ =%X(bX V Q/ʡx?Ha10d} hn0ث tV>F-7Je8mZhVoZ6F@B$ޒs)ʡ.%:-kym"0jr|躩0=al[GLWG R0%s*vV[(zuMTl%3JC"Vu&Ҽzh{h(L/}` )Y_z F˸h'M5ob-[afS)/n6{*5߲_Puz+F+jF+Ch5M UbZc4TZ/zVW0fM/n71Zuz[_ֶJ@Vy܆˷ww77_}Ow|wO"dpsCxWF T#x+}^72*.ÃD[h"$R# &BEcF&f&Lh9^==M=ԕ%tFj$(KiR{d6BD&2Wڙ [ GA]z*DE]>虝-Q8*#NE1ŘPMї2F,D"VGAO(rnVމ/P۝+V{P~Bqxl<&cpL̃&&Zeqаnjjbdt[ UWfjLd/Oogɾo?_vh1kV%xD~ng}趶FclcoĆ٠rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrRYTV*+JeRYlT6*FeQ٨lT6**********]YSbCl6*ΆalPY,T* BePY,T&J *T2dPɠA%J *T2dPɠA%J *T2dPɠA%J *T2dPɠA%J *T2dPɠA%J *T2dPɠA%J *T2dPɠA%J *T2dPɠA%J *T2dPɠA%J *T2dPɠA#F 42hdȠA#F 42hdȠA#F 42hdȠA#F 42hdȠA#F 42hdȠA#F 42hdȠA#F 42hdȠA#F 42hdȠA#F 42hdȠA#F 42hdȠA#F 42hdȠA#F 42hdȠA#F dpAdpA5{|)8j#& j*3=J(8L >I&/%ЩϏpB&p(ͩN ^\@.NMoGe-z M,|"EO܈vBIF_He.Q#gy_T8z pzXL&wX4;|և s ̥D)&&s+X"COяs+gGÄعlpLXer4uYXX?iԄ4sj~&sj~ϩ =a}zXnT%N֢?IXJnHK ~PezB]dg-џ& qٞ0K{\zK¸rٞʸ-. qI {\NM suYxbo2GK>*X*!#F}gTV& "mvAdghH*dD_߳Man敇qd.1x׹~Yj}ź!4x=o2KgFsjba-pS7p}X? W endstream endobj 4912 0 obj << /Type /ObjStm /N 100 /First 1014 /Length 1799 /Filter /FlateDecode >> stream xڽMe%+XKEA2ďDM\ ?&Ƙ3.ESqaW/t'u[US[Bm-*Y2~aPB㡆q##PKR iLyeKJ ڙ@uh@iFHD]9l7B.]2S@[0AU-L!Us(Եt_ ^$ZuCaPyPze1 !ڋΙH{ We`":.N;EfH1GI)0 =rZU3V <yZ-U &iZ#3*! mgXV ijqߕZ,ʂ'z.#Bm(=5I/WCBL.s湇e>t9r`dCÎ2C:s:Z0dh1TO fH ztULfq*O;J'pe#l Nc|tXGMltYjb4N+KPtN9gba̶-MQ\41Z湃Ѳ-VsPGF+ëWm}|w<>ׯoz ׷on_p/›L%lv-f,>hbhYx*ܾ>ܾ oo#O!CrsEBQ]f3HS <AJT cgŅ@e an8LXj?DIBpuw"=.Dh#>bB^c#lqC+Wb 28J~DhR) HA,t4J4KPcT%GN v@ Q\q@ ʃhR) jAlr!R)!RR*!P*c0r!N(AR@^gy%QR}eN  52BN8PyGDsJnCJKxJ$hRD eyĕZUpDkCTh qeZqDǝjDzr+Q<6ge)ןP- "K~l%4b&4>B>+!fCƅ4] AXBB~}B!VBC и B'4a%4>D9sT"-VO\=PX#B"X#BXqE"XQ%As!"cM2%?pr37 !A2q,nxWV;n daY q ͮ#R^~C<.`jB arA4-.ā arBxsjC,t9L.=vNbC\|\nKBȥX mi6*M. bʥȥ!,!\ĒKarCriK.]K_y7zG! HO<>P~..Á/ch'bx.B?.!3xwBG/Vg\ T endstream endobj 4913 0 obj << /Type /ObjStm /N 100 /First 1014 /Length 2126 /Filter /FlateDecode >> stream xڽZˎ%9Wx _K3Z!uF͂DV:7\JpU'N<2UJ%iH(j,4IodXԺSgEOTcJ"Hm ž&=M5Ӛ%ro+O̶>/:pZ}Ή>tP,BNiIT6$)=I8$;W-DaX:?J"V⼎yvy)ɨV6'ÁdV}X.XT `婲HzSIU;lDTXI޷}pE܆oT6q>OlqI`F<<p2~i8q<5ܒ7};^(NNtO8u o9) fS`UMkR)-c 2+)[gܣoP/+8-n%0#=D=_؈l:(GT[f,p*nÃ#n$K X͹*<b܋!n&۹Hq)o>=~ϟϟ|}{~~??// Ho?a;TMD٪bÇ!=~/ǧ \! : p8KЕB, l!sC B&9$Q-7@B&d5 eU $Lތ3 ZL ,O=HS.)]i\B3BЅ X /X)$IKUZRREu9@(4!l7X!ّP R-!TQ ].VRIQ ny+g RB5=j7.S\@r\C. Ar9a71r .3 N70r J#N T=ʂF!aRQ3DtTAJ)A&ݝR53qA7Ua YBa*'f ZѢ1G('6' <δ> :|>7Xba} YgHh@chc6S3+՞ 'Edt<@ R@Lg[OtOW -''k_/S S bOs+PeC]Nra`i+WE nZ֕3 Ԕd1KX9TzF˺P Pn˕E6C|KHv \n3 &2?#{[?8@l39;$8ǛC+j/ʟ{Moc=A t;)AKtZ䤥luН;-g{q@[)؝;@ŏD  ޝ1pVDIkגn;Hy@X ų$/Y;{y؛)/XZn Ќ؈ۑ5"ˋڮ1فaM1-]Of de7:"tPCv?3&BM\~M,ڲ e5*!(d l^ŷpxPYH}Qֶcl[ V/霥B"z1SY9KD/ Cވ"ab%.@,^J N!s * ٱVRT'-5fz+T ;i1C \Y(ohCD]T(!sᓖCvGDE;Gƭ>q 1h} 1Ǡ7xl ͩflwlryG-q^i \TUԙ(/5*:R h>}a)+GMCK)[@߄'E $L^x#nP ?Rc& 9A@%QpARn۰pЂ W[snG|_ˆ{N1TZ=B $ M endstream endobj 4926 0 obj << /Length1 2976 /Length2 21931 /Length3 0 /Length 23401 /Filter /FlateDecode >> stream xڜzP]۶%wwwwwn $'@Np}7*1ה1mMU(HDMn ,̼3GWG;7kvU tGAnf(4.֎당M@q7;` `aprXYx P62ԬL\pbN.֖Vnf4 CfN5+=@ :Àhg׃= 搅/ foFG%/SRPۻA՜hN5yk3+`t,@}%)@P)ހ_M rssebegՂD*=`nm0ZZ;1r 0ZL\ž,_??Ja`[]T\3E+:z| ,\\f7NMoC Gɛ;;@ӕ]g`6ߌѿec?Z{t~2a/.{&Iw;M!͟ ?B/#?UJo\ `ab K+;kqnemftu?H؛[;XX98&..&p̠efA@/Pl&FG7 TA_[`% qD#.o `xL#.fo`XLҿI7E@#Pt]7EWq+F*(o#E7q@\#HoZҁšy3(n9Km}abk76s ߌI *ߐ TsG_o  o ?r:wv {M^@Ųaa_ǎX:-S@Ev:YAmvA'0v9dz]1ZEvp7 \I|:aJ1( gg/?tݛrKf:ٹ H;_ko쿄OS? A?J[Pj@{ /M9q}+dcPsRܬ\LLn|^ P^\]5@a?$Wf.θKt@ nqь/̦!Nߓag_c5/@s).(lƶΑWI3uɣ3:kd!&ԑsN9I&<$+aϿ3Ad,F)gB_ 2'p,dY&G͢4Iע$s̑褫w_9PX%v*0- ˴[=,-}(Åtd jV& XDZ̠C6AJ5ϏM/xԌ"NLk%R7uȘ Ӈ#O;Kt䑁/Ly,B IcTːRl]ʎίZz uZ.Eڵxb$oFY^݁ Lj L+GS"B / u.jx}XcɝG4Fok'gX::" 0.g~Ə~i&}z|om;/EH~WSuzu0k9߿"yQnja jy׬0d#9BSFt3hr䃭 =}g=Dc t>n>$GU(*Z7mD Yd" Q7^eRɏ{ἣZMsëۨ-Il"̺»[ٻ;!(.{P}[pbK;5bbU_:wIl]P b? 8i'hcM3HMMOM>-,!] QlJ>g>:J8OĎY6_&/mol.m2{ sImëZ9ȯ\xx|_:It#+aBQlk#׸#bQXzo.U=8bZkRu C`֩Lz!.ڌxN2p jq$9tHZ  stWs$KЕbҔ>8JIgXIpi-.8\ wc}h]ΥⒽ6W:K{Qàu^Hl~Iĺk*ym1)\J+Ivx?kҟfuooGYzB+2kfwYr2-JH(yL=_p~5ϡZz.#cְj;$Z]s>X'fV9NNv([坡t4\|)GϱjLׅjbO uq&P/Ψw@~DGue/{`vHbZ9eHSX GZ -K5r+Mm]= m'UR|;W]E0QOͥH$)ЩX sz!p3EMBejZ? a>ΐ|!xDaDCU FRs Lz>Ӊt%V/HyHo7iH9.UvL @z:\P?n9:6@_(8lXj^f@3O@ 2/2uU@>H>nF?[ϰ`F쩢i(iUwz?\hv{) > Rk#jaCYhHfTNQ \w7ԥs{h[ a2iMhx%'/&a97۪hَ:YN).PK un|nOC3˹"`XޚJ8 T$AV?ĕxi*6wclj8``^)-SUg8@qKO [he?.' ډ4ܸDaQws8=WLJenM⮜-ɭ{$77-[ uIzzkΖI*~ħ^;7GX 3W9*V4Ŕ9b:oF&7yM~ 0yI2ެ?>Bճ3 ܇GFi366_, cy'H Q-| εh3,V`ʥ ~_FrCd㈋W7N"Eݐđ}5DP}IS$უq#r? ڮ?ù0:'L6:thcJϰ>p@eJ_xi ]]@ \QnAx?y%14: ˧ \e{j%gd&j>#-5+B]w"-I( 0nx "ѩ|;B 4 bze^<ۍ&jgN;,gnK)zN9ZرpQt c>!!g~+f.,o>["w볲Γ4)dʡسȧAg^' =tArH䎗'/ҠOb !էW,#%ôSgWd ޑ8?_ 'uݮ緶]< qУ?v !0ڋqj"ĝ~7V<vpoׯ@?1[=4Q6ˈ42Yar|fp %8L]`IF)2 ‚Sl6&Xu KKSZWxNN%z@ƪ` 6PZہ2#n.npKٖ@0fk`Fg]3DpuXI bnz^ ofr=أ/ 0nX/sRy|w(&_-Ė%~3*Qh[@wb<5.'-:(E*hك[bFltΖ: %)&6L22a`%e8-碷4_/ƍ |E?*LV9 cұXԅ9i#hI2'L*ivUL,oZ۔uxCY(Ymd ir*:lj?t٠̚ (uuy\X40Vi%/w67(ZG0نS_8mc,Od$)O>tR'J\?E͕me1@[ 6GM݄pq Yy2rt0F#9lЏ|x t11>c*㾆`uב4zLj_GM_wK^oiM.w6z`~iT]y N\U*F톀pom91|fu$+ | ,$9ף~$r$j0YeuPOzv$51kQ4o.^qσS h]xs.xh(!&ATwsq_sWLwZJ:)2$ u?s=1fPw>k"F6aSR]s]sg!>C6LYd? iJٗ*` OUU +۪On=ц?_U}Ft= 1s Z@岙­[pիƲkLx}Pktۙ.jS-FrM9iry`_v:/L]0#>5o9q +fxFWj} * 8pb9!(ݘ&ӥfK4\75(;=w/"M8u uʴ KjWrt$l» uÛ.ч'͹̛ӑlA&lZ>gZe g 9"+͌V%%*N FXq=o# P&Ǩ~z ,?nd$Mk9)<Иe0ϭ|g~zbIK@C? 4k3mjWh1,ߢIYA]es`TBȰ]-v>LWۿǘJA~sPRGl ͧ]qięߡrTAtw$0!N +::jD|& Bl':QnTSG\pb1Z&ëz&<X*Tc[ /7~U|xzBi!#D6w:z5 m֢/`cٸ|V \*- [V\ *WFRF' gP3Mg*= $ͤJZ:AYѧrB)T?y(`cFD^)ruఖ8]+ݰ3͡[N7%zi 1hz{m5,YÛ{Њ x ,Κ>g n=a_۬M 0*v!ಸe=DKӀŲȡK"+f) ]\Yk8X 4n}2pMg -lj:duX8Ls(: )ɖY>˓UM38QorfH3j-ׂ=Y&r]n^'HM[rӘb%-Jމ|qQvz377tPώa [`s= G d {~Vs%z'¤cE}L`jz(XS>̮RRmLuI݊P ^dLF%q) Ktx_ .5XO>TVڛ~Ww1\f%V% Ciu/<4Ao5 , MR@fʡ̹u.(s~jGVT+d[^&/*|[XA+q+T;=gԅ8 +,iu{C""ـpc YS[I̕'Ts㠑c+r#.~ݳP#훣Â#l!w>;%pYqkLEs '- (#StҐTVĬ^-d1bF3zzqe{3bP,b2Nav$ k8sr t/ pZno[r.1%/]Y[OLw 1Q[^wN;Fi{cv0ETאX3HJ`ks3+} jKZʔ52Y<黌3~]8S ,K e"X˅ŵ'v+%nbD4e^Ij㥼Mt`F Fel"DώEkj?Ry^}Bze8+u&%dQxuCKF.uü^cL 8 7(͟ݕn.z4;.063Ye ӡL9qk^;z]Wdѕ~:A&o|y놨ZBYdS¨Ž``99DOݾPuڎͥGyK~Kڷ^R r+QR)*ӪnYɆ2}2y:‡;52"j>Mo:/i$vґzp| iif9nQ|RϪd`~279ōڅesnIᬉa? ٘c!`6:py|;|v(4g>,8YFY0rּ#{Ut<@7`ApNiWIdOu|&U su>^p{BdTvd,X S= :_w9j^_ gؾ+]-c 3@AYbo+?\H A,a?~\$&qI>S\ Z@ޒ:hml.@H<}2:]cGEȢ1)C.ks O<ڹd<ϗ\!|@Oe"l RY7amR=_}pÈ;w[eDqX8 &]U%.;#od!RhΠķ$>k t"%4O-0)z>0LP1hGqy76rtG> vH5q;hP|qF(HZ(Rg:|Kb9E82-{mq0X>!ݍqpUz~j#e^Ḇ%n%~BdhvXuW\( ×})#νd2rSjɄI\ɹ^ˆWi}=aU7;BޛѩT1tzs6Rb*>싰A>`PY1B;xL% ?pDQ[yؒU4u!ļ=AvEW5[ҸOq3{ Y-߾*cAV"}EYCLN_djo\S՜vRw*4E+hQ:5?f#"dpe# Cwމ'7aUaw)?LQ4"L6rlynnb(`a0^d5 aWUpjM@n| ,]r",p9SnH/+`kP [= ؔbC$UȺiHD1x1'vűwWS3%We#>Ia}F-/WiUVZe[>>Z*jP!Q>g*XKLAv`jNT! ~ {ۀPWv|,MQB-udŻiQ3NASN b ?;[ dW~! `-1S-zvD`,川ɣ:d /d {ٺBs9n d mܲ)[ʪsgzuPw*&,lk<#gx容OZ,oj xˆ[OUP?K߾UlXQВ^Lg'״>3^p+p:rBs[N]t:a4w, Ѓ/=CDOc̚2GaπJ5y"uu TwXLT 븻+~8TRgpL)^|3jj]rK;\.W3c(K6E< ? w_uҡŏNº0D]0N"DIZۮm"Ri_Ȭ),=V c1RZ+Dg1DX`yD?]Mg]61 39rn :}^ec^)wU[c\f3Aqݜ7qxd}^-4o˶i (K:tEYfhLN/ˌw!mmnT,TrBM|c>]e ."`08H7KP̖1o{B~aCV|2ipӦithR=fK-FnZ\2bjnyc%9Ou3{T3᳇'uN T 9W:"sqv"T,3u(|}ŹUб9ڴ#>9 InG8f59ۇ)lK~לHf2>L pW؇s1@e߫Q\#itY@c9OM?,{}]Ivt8Ep ȳ☛0̮~{x 1-g 8fSy]I7KMMOnjxT\Q`J2AejKj>§`9\ i=wmBԧO3^xaV?Gn0SfSP]( ԮGWFu4;/YfJf7w{1ֽ@ uʾd'Β<2|IdrZ49_7bSfפrq!Vp^v5%s9ڇ|qJ6%wO5E6Qw}s 5N%rX7[:߈y?7 F;SyrPaT68*ϱV;E՘].Ezs FwkS4` $oE.t*eO}~Ez3rK[u]X_v}1(ya=+f% ߡ.74qbzLZ)EN}Y;$q;W_jw^i;leac<no_ԤŌ>{BgЁ>;J:GaWY1{>֮7dA؂Gɸ&P*Y$,i;lE~[})kvY½6<̨հ< o5UΚYݬ!] >pR%^M 7X(Ϙ+4'F*^i DapI<GBJOiu/U$StNq꾯vHNZܐbњgE6}-ܽC`G^QHGt4aӏDkcZ9n&:v9np;ڊ˔JR6BV e'5= 6]-g!muu ߳y?fs/j*-UD\" kFS3:R;u51jOBSk^joB}%a`yGs3l1G>c?p>!" }ѓ..yz=y9M>_$R[^be7v* ݦ}g_JExgZ$62۴S4z"ZG,^?-Fc/j>zOPOЩ@3$2n@vZ1YOBNU.ɋ~i^@x|eY*b~9QB 1*V.ӓ e}'aRt3mG'قYC1Sf)qE:p-Vīk+ow+)~f){ KH _xYqDI K`dL{M##ͦX3D= %Cr)D\ja*W2}᪆O3Ѣ-}Ly"XXHk<^ᨦ{T *zYb[B8%d#1eNA҆U|n1R9@kۼNe Y5/=3l1'-O_=܉#p,mwQfFu ek4\h{)#U~9olqrĄՏ?, Cd .F3S,hQO;`<'r&cKXxmwm?MCVDFeb-M9ZK\l)\f9=~Es1I-PK`ĩLdo F^cok! %lG%2ֱݙJAZQ)zl-);%Y۟ VF~LC<LJte7m4έ)!aoHCFmNNό?<ӫ&:q)n6LPɭ Z{)׃mϡՒ6qRW:+:SE*irJ/aZ_"1PTO_ Xldjk7GXZ8xdҷ9ۓfk[+Nrԝ'8ٱ_z ?=pٌZR)ac^ް]NߣD0=\z .TobZRx\#Pv%۪D}w9+k˵Q;YFDl~x7jJ=_Qc,2FFd="Ӂ{*X| |mO<8HA#YRTD|z -^cV7lY#S&pQJ]̕$wGTcc1ZC¥U̮k]ۙQح>.=OGd|y-WL lk"̏ yP(&8-Le [,d,-̑?E$F.'}yg$~"њO G1^m {e7ScUiۻ2TL~c,RSbo+vahйτ nܠ tə]VcU|!G׉J/JCkTQ_rX#,'&!w%?5%X6l>YDdH!TI"3rUԧ5'&v9f6\n5%.]ʽp-nqU8]+S9HoEg; 2"=.MZBaV\a ,A6D}PH=0>)B6׫ìWeR,r4˳+i[ۿF<ݫp5S'k9:u=N-!U.B7?F{ uxb1U.ݪvdfNYUNȟ&hELj,eX垹;J 5Pas)ҌNGUJ#wC}a6-uK(+Exf#aBS<c,*Gʇ##M3x'C&S Yh_s*Hlպn8SUH`.P\܆%ʹЖ16晙cԾLA5CS2#Qxy(K(cbX99#8"a)p|VoG "_DJD N kE߶kSZ%<[WNݰrgS#T+4Bt6"e\(Ә/!%0*8^[ȾӼ"FĂ@\&(enDZ3c[9nђdOzك'¨F#4̴P_F:k~ `HBnAU=*WM3$ ,TPqAǢ(xӜ_vmm/-0kwkM0)if<]7pgU*CϪ)xF\dž ֊Z*%h5__ ɨiNp걆R 5m{wi]ʽ'V_ rK]Zϼퟓٝ  ve _d([ azȚxf:?6֤!t)3=U۩ςc&eN>bO)+WJhϿ4u,)s1ԥW߶4i8q8b{4,= &[?i> j2'{Q `.Oľf;Ȁ溜iP{@ &E<}+|1h+ԧEu3GQ AKf9rdu Z\TGfTAM4:Cjsà=TNH5Bf$-6M{QE';wsOS>H^Tl P}Vo:!{B`'/h^JGɲYI\ذS0UomWWul1uy@7Ox 0 Wb/wYڛtprf@/71hpAk){!G -ݒ(Sn1)k"Y G~y;6ld`=%&< f)'^b\:n!3ue)[,{sMs^('u,5֋kt|gG!A|sj1%ƑcF#RۇPXf1e ΐ4\*JMcA`%U ?rcM"2YU\l!T/ 5#yKM\Ss+Ɉ2[ƛUZt_1a#@bgS,q54_^E՞>ChklUW[eҹ )P3';Cg'K}uEͲ@-p\iz9׭4*Dj*ϰ<00^1V:8+0"NccK\O).'3%?cjuHH@j zaIJ9i7ay8LJ w<}f9_RJ%Lm˹|NܙG@NCzc9AFΧ%Q'[/^,%UG9p\X2/`B ሩ:7]Ae|:hah5^ƽyygGT)Xh;U } =|␆Q{~::RtjMςae"Cxn=NjGLu0m̐QuB0KcPP6ђOut9{ W5:w e;|4F8I뒉|87؇<7uufޜ/mqJ,yX(ݒ`LՐK&q/R@Ɲw<*[sRfYsT.$ Qڝ_ ƃ?l^> m`M]qSe0as x_AQ*$bmgӵOH\@@6NH=5&- ./_/\.x\mIР&'g몤M͇~vy3ck|sۙkC[Q!5n/!2weqs/Y~.po,p݉4l|+\& l%0,="| uj~x$5vMxdy>d?FMo$$uv8MA6f* t߮im!F#vu~# H~yD-*x_$~0055d-#iJiJ'A22G*ܒY?"gفSUul#+GLO8E/)ThYq Vl {)@]*[^J] NzaWnPȉ"a(:NnCB ^9 VeJa.aP_eU\mk'Feocyb"oQxuu[T!(VëK9p75` w.` KY/usD5dBPu, ,U4􋛱̏l˂]"-yA7'Cl螕 Z;A-U`Y` 젇şR F3lў dl/,,hwz`S6K?J^n?;{ω6(u 2^]{)EQ ` W჻Z1kުײ-!O>g|S]D\= ;,l\}y.Jğ9]!w/2N'TWkA8qVA4YآViicvImKYm,+C BwTrg2 [x")Ff6)T B^-׷-%Œc<)o;6l n~ hoc'Z}tOrnRJRTRxqJ35)9Zc jD^m7Z3p( $4L⩭oeFa0$ TL ~C@/ 9x&RyrmHⓡ䳸w)O%S痆~]Ȯ S?xWnY?k1+*DwSk< `#Sw^P/ y+mP०p|Lhȁ̏('ǩC=(D-EVzTer&$Nm}$h+֒FNlAPٽfZjK^q)CEI4)_u|Xz\v ҶzN"k/ݼ#{|^LByً\mhTUCKS{wꓒmU0Z7wdwN\dr^12W¡1G2tIȩٞA ߢVh F>ʘWIJf-ǐkJxO̪ZXaWϛl?)lqgIv3ʖ`ԋ☬C1`q~ZSGM|;0~JX k/e0k`B̽?5SSE9L#IL|ˊ.' epè +Ģ>`jTљ2\qZ- z$P&3F{q>䪋S O Ƶ X )YK.`4+ 9/lj~!쳤Ove bjXbw#$=(u˸0M}Npm ߳y8*aH"@brsC`eYjM*Si3t5l^$v*:!NJw<8$]ͧ+K( \.b]Ȑ00մ5S ZIBR ?5Z/ڶ"hZ.JOef׶O|ٙk-v6TjQC[.AY@ ٽeyN'Ŗ3I'YeW љC`Bx_i vV ݠ.'8Sa*]fבLPbARb{j'W|̢;U<)~,wxˮv3|Ȼ e1@vzZzՇxcjC|{o6bAz ʞD|ŀŒ@caդ">m lV1˦vhw#^E"> stream xڍxTSۺ5Ҥ#H7 & wAjHB$t^7J](]zQA^x}kk͹d30T`($F$[ PT!4c$f04 T,PD@4HBRQU C!ahN% III(<0 8ܰ!`0H#K {{{ B('y^7 0a^0(=hB$g8/1 C!H(0Ðul$W?ѿ#p #H/ Fa^`8n PW2 cBh8׌¿`Y UA4ɯT0v}+{GBt6Ex´T`&ۜ`PJ\\ =| ¿ ~;31`pG 0@tsEps#Ik9ƞ`0( 7 iݷ43(@PJ@ 1@?X-# W}e?#^?s顰̅xMtk;_YWwGo?_v#| `UjPs_ՅAn€jPB:a-+Vp /e77 3@0( |XA\w4]0YW AAMDL`|~ ,Da!쌁GɯؙhW98rLV{[0 B2?Ȅ8UbP欁gՈ" zX]tQeg: MqDmLПg'Dl* XG.d44Zxzl.˞#wN+-n"7Z^w D8N$Ytfom%7k2SiCu&'NwiW`O4(4zgGl)ð {x1)QMmX㸅ȣc7RՙݵwۍF=UsRպ\RfAd'dPYcBA{hۊQK,Uw ^4mu gxš? D?|p{jn+Aݥң"ę7Ej:"v"7[Q$[>S 7;<Qdnef&NJ[DVҡ5r=gUw8(BJ3{9Πsuwo!!|_mTEQkWM%i݈{1:O;̴LVAOE;747LE?!һ$}MaR4͕zWd'~ 3C?~ՖSv[&-Nn䃼@jie5{左[F׽Ts UIȧFr):]JZY4%P!M?WșhϏ$ءaSzGQ4cQ˚]WV?X[t8 4"Se =y<#0lZp\7.E{:pU"U^hzzIǶHaITX>oxYPb'yq)F~Oi7&lT?ˮge(l~90qV9]\|>\*Zdxv]W}[?+gM)e Pjo}q}G.Aj`{ƴ5=G3WC*IDzZ3+W- u˳m7fHqw0LgJ+hR7RI[<]6C3WILggdgltyͱJR%5j0[0r'm>8i(s>{meǏlp|in|;ԙvgn]I0S? !0j)n-R}E:/!#G㨛U9:o۴?5f>b?^\sNMܥb=!ڌ8wnc\6΂'2,Uϼr`}Ʀk^%]q[9NJ [x;N&"- 5z.6B<{5B޾K~'\}BЄeG4lz}]g$-!JXo*T2.?`gl`)V !d~oѣnW?wݑH ]@ O7}oz]y)1X R|[727r4UE]zaEi-U'U7yYhc-b0kx'8tx.Dѳkx%{@! f njuɁby蕋Iv|Ho J8 3$%ͽl˾&wIbpa[rfR cG(]S6!bs~P^Ξ}<ѐ&A$㰓[v²s&>'+Su oR!Oωm") gK[A!ţըC~moC| [P輱:Rǯ.n"cd67wK6Ù_'Sp|,F|a.2))9 \++ĺ| ,"bBnUhME3ƢQ/~;XT悔 MqwQ,;[П!%7QM9J0XHtvdK.8JpS\dYiہQļ J)N|[!=͚QbY%F~=Q?cґF՛^gl᦭*Ҫd_-Ei;·'Mc]L]ecgz z 6R kSHXܕj^TQ J̐e4>c V/cbje`rbqؙaΌ O`kn_EkV2BDKW i7Y͎rK%ȑ/ɷkhԵW{|Czn,)v_-vwı{ e yѼ5OR d;, ]kA\8]vn>&אY8Ca"r7q֚啢s;<5 Ll@.Or%Ռǣ==+䂓6sS/n2~ }URڈV0fo0pj22fm˨@.g^pdt,Pb쎆DY0g+*mռ?sngS~)nFXN`fLe鳨N}t2m `^uyu'cS]0 `%O)Ĕ J(RK0)a䫌  "MO-5Y@+횃-aF $O8fh1*N>niȩ.38Ep:Z=g\P_kn+:Xh߄oqʑxXv:#-"]SY 4{r#}1E(BuY0ՊcyOB4/rky8H»rCo 27n'EPf^X|;8Ԃ&Q`YKFY4@F3nfyXܤE)b /c=u1r5|!*x]m:1LJukgsC:!a\ ݅xVfO^z3z:G/NT+t kNQg7ʯ62OWNm7w|PlU((?=$F_d2R^_EU\UE"||wp_*IA؅ӊ)AĨq\ݱD?jTI?"+!r S ;/B،1ПKfv#{POlduk"'r OP5KֺAyY9XbiD*NQz)hrM3Sv{COEW=U#sSc/$.gK!Aj Cb%\cV 1B&m.T 2@"fUR_B>kqQy'E w؋,%t=/齗AA]ޣߑRFɓfab<Șp[Ci$q6qnyQ 7(%CYFXfr9bR3ȓPW@яPHVrJU͋7p,lk_*Oh}'yIk|N-LKR}şua sjR8Ė8w_noUmNf S`{*js,W|ƩI)i"flvX=5S]j}1w,oPN5b* ]*"KzKM%)։u.MCI.LDb#P3pAk˪kSE]u.z_|>M`qX>u"9=zڳaz s}%p^5`,hoN~Jxd~;B jwgTFCVclSd,iRоTsIXa-s*:EG-t>ğJX"[ss=d_SK hǧ'y~{j2K` ÍexlTI&yʞZԁ~᪸ nUmV}BWQ9MD`Ͼqn /ο`i$TעKr3ݬk-=mxA] Hb`#b\ ^y)Dgw06|bNmP`f&2E%{ E{S0d3)Fy!Pש݆mO/O&h@*-.>͍$lmKPYg5PCk-Ǧ *\Z&_&FLX?o-X=8~8 .+"=`Yδߜ7W@Ce+37q㼮Tw;?Fz0| /|;ܘ:o) Ds =K-a鴨\gWE > stream xuSyQa"AXHx\dDg"B+1+|&WY#]AĆ#t rt&TA>Z4s:¢gBvP#X4L,SB ]3i̜!>@͝[q?,fδ6Ptw'alPXp+c62@gH4Lx`Ѹp;џb B;E`B !@5|SGa5 V ku^(o>H0fn_T06x)"o1WB;Blľ  îWALd3Ep?5wO-47˝dq\xӽsiiWsYw! 10uL 2)5,fμ87 `px.1"`P @7C0sN0aB0 Q̯4xf.=eςAp+P/AIg'ϐc0nYXm,Zn+t^fD6r)m`9o9L{c" j湥i0=gCT~Ф5EkcϝWFWO;T&#񺓛Qz|%1͏(u#%[҅S.x^Ѡ[ꨂJvU}E*&6޼d(۴dzt̬]ӣ뫻5S^ّX}Dkm60dx0t~zli^Kɚv󶞆{k'֩#%ILf=?x$6wjVurhu(237k<]iu4Mтָ'" ^&?S^PZo#fn=q-ޞ'IS 6Ɖg'v5+:+E-%F#/7삯O$1w_H\W8PAݓҨ@BT9>2hZJ?U7[qf*L&\꺪#oXl-Aih\Fѹw)}ʭDءx5{b 2+: M%w:~uxe[ؤ=j*/ާ z:V]q[e"Y)sa@&YDtd[~Lwp[:eMY1uX|ƹڪ~9qluL,a$+o[{$mr>[4|x~p7>Qi\XZT< 0\8e@<2}llDUޭ\Q=D-)p#1ve9k|U\3)J)}AؾގWuЉ<گ4kli3[}!FW7=81&A[%E R9etI犓%?Hd)g֍{}:drވ>~s@ҞhReQ? {#nq69WxKKԇn7r겜p=*VmI.xu$ #c|?M>ՙe:Y`{Yt2C eͺiۍ{6i8U捞5 K֭^]%+ ڍ#VE\~E"Pk~%lLs+ęyoj UVHF`iͶ8QO 6kKZ$M sSC] ąhv~B1Ja:`:>LcKRa-4&w([nR(UK}5*a㧬'R4>o R:`4V̷(2語rnxjo \s͓T҅ اPPhy`#qRãvEjA fR[SiNuC%eNy՝թsG9޷h{cdE>!Gm,)hi|-M7Q21dՈDZêhEm 쩒\h endstream endobj 4914 0 obj << /Type /ObjStm /N 100 /First 967 /Length 2558 /Filter /FlateDecode >> stream xZYs8~ׯL}T*xƻI&kgrL*Ȓ#̯߯!eJ`6 )RP0a +LL8tb q )"DJ:P*()5 :P.)PA[PP)YJZ! ]% m"NKeQ " <"HQ^ y\EV7A$b 5) 7謯g=FlXmް bR܈$+4I)Uu옧ӄ)+%-Lyu^N`c2 Aa>-#,( XŔLP.4(yx|b)w ;ya * zM&(;h=9x+9Fc% Dxg}t|́f9x<8Bd 9X+w*Ѳ8h! < &dOqlgGO&v@⛞ͭ0y ld-EpZ!1O1g(~V8>@qY ŗZЃttOz8.ѯtDުq=Z&킬3)UZCXTeb&jx^W(~i=prb>f\|A1x`@H|u;#+ i!D[YmcкG! [A@X+6@n o+zBe8A:UGFCnj=x#*7niO@xr҂q=)B%C-cOIWRoIS[ UsD ɻ>Saڀ9,G[AA\a%RC3]"S">+ ED+ ºJ:J"A ZW+ 3iO.њC*#WMg<Ѫ`` 窈BA=)98Y>9[)yU:u6(OPTG Le]uz^ KdW%E8SMTVgDe gr ٻBbe.Mo`ި[k(OƶHI$%ĭqRU.=ah.*D,rTbD[Ȟ5X4Yr>c¢RPN8*D6Q5ب1ï ݱW犲9M:kU9r )ݱc}c )1>R )0yo7 Jv "Z%ClO-$0}YB_"KH_> d q~iBEL[h ނhADsߊԵ[A9ׂh {̯dǂ^Ch=G݂&wel̓"1t͆mwV,KRo^_bu E o" vv)SqWnl_7+M_Ƹn7m]ڼ5xq!xۨ ٩NbT֝s W7 %m\(F_i)C))/pJqdAvEuRr~͵oi~L1kTʐN˯+[7wJed6Y>>j9φ|}q{GlM_c{p\&C8/]?@//p0& ^j= ~5p2=Oj,˗ǀ^7í xb8#zL?!O'oAtB/wzI5! z>^|Nt>ՓrMyL~-ƈFlC:SMW ՟G%O5tNzu.\]S?MhR/tIS5MW|1>Ҍf`\p^O3L\s_dz3>r |We}v:Y1z sZТXԟd1LpqAKZ^뚖hEf>џ_|‡cX&v].Gyuӓ7J2:wɊ__tټ7>d;ρ}츏Q])p9\^|%XO{oG/OWI%Ti+FD"n+Vn#Ӧ+u,R endstream endobj 4932 0 obj << /Length1 1626 /Length2 13710 /Length3 0 /Length 14558 /Filter /FlateDecode >> stream xڭwUT]-]7-H%;l=!]tqnߗaY55w#[cQ[  #3@QZ֖[A!瀧r0yjFacC++ dk`njP(S ?56ʏgc+[;kcG1hf 012kHȊdUb6Vy'+sC1 `?b}w ?܌] R?S}GsC+'|Mld`aa&ot4t0> 'LWnG5鯒}m@cW_ FvVn?9 ƦFVƎa>b՝ oYma0:[0³~4~65gkV$lLl,9Q534 lmF&Lˌ> [Gr.}ТNVVX26=h/}ks+ӿZѿ$-ncA 3#?探F@C3G;XwK ,S637mUgWUU߆CTv0/\6v @,<]Zu3]<ez/UAZ 1/tRi0"z~`CBPEO_18=~[,^LNoNq\0\'6]nI@'#狣XD2T`٩Ť,LP6hވ ]PVZǰ # Gx)ԣ -e6!s׽!9W.Yq6Jpr$W GNwǁ(u｡*]FCJ%Ic >W0{{g)Q¸/Yi`xqk{E/뽗,]?Zi z\gQOs@=*_1.r`f ,gs~[%^@>p Ke@֞ wW- kcobi/y@Yd`Yb|flA.sgzw|sMɾaFgZkO*U /vDdzz?Daǚڏr~ 'Ov=: o-8Fd]|]h?[S4*B޽8ez׭Tc^]vYX2џA0ol6o%Z-e4J}'9'ggx Z1'گ-)B#Ff\ۓdxת , L.$Rx țc"eh ݒ8/ ^)R4 {J+w3{|<uN=” RߺR% ̣SkZ!B#hlݲO 1ؒ\yGHYrbwFJ"ǦIfp4n8CԸY8sڭU ΁hjG`;LKeaET<tJg_,\R/SǗ +v" H\MbSEz9 7utӉS EpUd423tU&:  /v[m%<@?ȊɵJvd5BL*q-sf1$)LM^bǹ|鳼Z櫲{ Qɕk}~Vb`5vP;feL[>σK=כ7\ttKi|$Qspg}.0smGlB\ ;5vUR)j¶htiqhZ"MQ$R(msĵ7'2%oD s?Q;pZFUt YC.Z 1ͬ ALfKHg""ZhȴQ1I,XfL!dg }޺iM'3z!؏?g{163ߝ"N'= l%M$bIjϛqfChntjBAh? X^Cy@, PY{w# OYk%Ot'hX#b}sYg}HTVlaiWMƦyRS@J+@rb3"wִx ~yuq{ڙ/ʞu'EudՙU,.#&/ռ{V DSPE՚yl~0T\B_<=+2]V#Ik6F>ˈL^-b'[w7>7"-ntTkg}gljmJIM,Ó=R{Ww',~&^x%Oͤ)&926- ԯp]CԠ/suK6?LD0k' u"IɹIx$vk$.@S='"WǤ~zhٝޜ~O[$sUI3lZCSa,n[[̈́MZ< er_I,EzJۑ"\HTi"8: %a5@h=)63fLcAʰXÍMh4ȣ Y!fjIP췖2,kNSlP.8Hh%=:4ISοg%{JyկRSmmDk TapӥKUYDj% wB )g'aAKL3R-Q W2Th*[XV_#yE'q|Qݫt>o_+g%4q9a%t®`T|S7EȺ?c5s&* x]d!ɛ  {_m"DS+-5rj)CR]YXAW0g| fyӂ:~O dcrDS&i _Yk0#Ze4_*&tRސNeKx}5KKJZkF\gb>><ܼ}THzӁy0i'R{Hz;F ISiʸƒJ =3ݶyb 녟8kY2;!be #mv(4+TP[.`8صKr J#9N6U% Hx ZJ!3 `w*L653u͙'8ʗT;9_=Ӹp2Z |'#i0j26)'Tz&(DG>|"{B=l؍cJ7J}&hخv~|FwX%"؏xP55}7&.Gah΁xQ:"nѪ]IerjgF('Irbz&/"d-7m_m'h"qO&^‹dP^l\ROȰߒp+|o;? _^Q1Fkw~7kIH$xb4@RډȦ_w+c4f;QDQ-ocĻw ݕ-EېukE{ .kgsNDŽIɶvsjj_d^˨P'G^)9aT .A?|X} jkt\  kNx!4jfط_8\ uz)!#:NfcBc/}i- z6C<y5ǿYc 1 Dq=DÐ?`6rqgMWmlΑ@?w?R6Z4H)wsIUcn9EY"F~g`g]]G4!*FsRYW6?'|*5_1Upvr)"[\,X7GN7xl f? AbDihIlqsLa>RHtqqf[3UYH7ntPiulҖ.8'%D:'ۡК)dA:4sd)`YIA ]Z$rsaX"nBEy4%up&b6yF [V9Wz_ =-sEnIYg!fY+W? 8]ԥ>*%ImV2'vU,)U^W}j0A_Am JPɝ(ڠIjbɈ+X|UL&mMP섛3.VR笇 J 8:I9;4tL<걼A5x05! D\I<3EVƴѾfm+7}GJ3nh~ndE=1i>VN#tFYy~l e&b-㇬2EX8*R,ko//~_$ꑴ7GAAsٟ 3 #%|5 Łfa@/1 klF ʔ ?8 = j#=D ^i#Dv6eY؅WՂo¡3.L;YEHS%\3 re8°JG v7Ï|ʫdcaqy ѧj)ݜ NKK k 09SjzG//Ic9=V||n;,q== 0f{<&3VN-.1>'pjsX#НK.S3wb J1v93ZZR+nT>d2jٺRf56Em6s m6=⯖cH5*M*{|-#Kzv# -Җ!'aXCdo83$nE4%s>MtQ<7)i N\F0AqAH`RG};(U_OϑE[Vtа,r?j@-m|sLH!Oj_OG֡P"Q)PiIw2y>rr+%*0^^|.4[y8 :R&3QY:NFKvˬ+a-g#0;8Z^'3F>K9dsfv$%ǼnED-ATiXjzKvֲ#٭bLֻ1IɃa?Y.Aށ -a{vĢ‰%xdOd/2 a<8J +VX⹄[>|3)cGS9i(;$6ŷyQOZQGqtܒV[U&V"0uv~:< ! _K^CsOBܧXjcLT߆rܧs&hPP]4߉cw+k6J_MĪ'?С!$MT$=&yD-}57,nWdH:T`pǐWftڽ!AYj+@ܙG!2t‹<4 %aQ:! WjV?:6q% UM'9aǎTB~4] eCH 篴qC-+"YD4c*yP1ǩVKh{þ˨EeF/Yը-v{ eLvږ]#F9O[.m nb Ŧz1e.{OfĤn߉Du&W^'d(ǽ &'~RE[QPuUq/5 ,+Ƅg~/G ?s]RNҗ #&u'/uNj)O(o Ai(2 ed?lf]-,NOf mY"wLf9k>2&h!-Gl<oI=~ȧ1I(~u13s|Ǩ}y`=[(a 2H#m:Gv뛖pQN 7~E)"i~۫q1,*s;Pu+* %Pw~g7GD.^r΋kF%QnC 9EHZ(Df~Zv1'Id׬Kv3s-L1Fچ={yWơ%aTDYGJdA ʤ!mz#jΰ-S,3h]*>ů~S߉z\[Su';?$CXY-AxF3z# `>UrgkH/yWK2 {{Y٣L?_Hy a^ G,MtN'Ȩ:=~!e0nG İ%8 MWW%4[*BfK#m=XYR~윏#LlJyKl|r|?ºl&#7S ZLod;P@tDfDLةp7v&!l ӄQ뀇us.Ƃ-|dbB`ҽ?K4S$AxC&-MxRiIch1-6AOnua՝_etɯshPQw0Xc.=={s_Uvqu*v-<[툧O/g2GbXpýʮ vPPCFϲAyʸ #}NQ٩ ~ELmGX :Q vYg5x64͉ u!r XI^ r/;jIkʂ &սQx?z>!=bp`ިdM\_8`W WBqL5J=. 1">³:(++m8;[ܲ[  1y]42sy'leXD 6 'b5j0O,]nIYL-~]?<{vzT uB{4"I.Ydښ*^)o&XiI~,/?f(?OgQ O@Y949rx8]e>p`C<)㣎!F;G/7P4<ϝק}R[37DYE4byidŔm=j+ aLk.M y#*"Ԝ}+8*]i%})wZ+waMƎ5?0v3Vȟ ̬$RW[/^hZ>zlBZ9ڴ9G/[N=ilYnLQB }_GjYX_-Dם vJj!X1{_Iz5  Z? j,$6%he_$ЮW/}G["sdhzMVd oÂ`Ǵ/TZ8L@\i\uܣYȅ\E5GNDKjeWG)vtaDܱz2i1<˿k2XR4K}a^~o*]4P̋`*kL//w & +\Dt}"p/Ip=8kv9|8vFza#cD2VAgxÕI&>R!8uG?,4-Z% %0B}sfoꅊ84[K  7rj^By$Fe{0Lk#$WkUdDW!աϡ۔D &$s4 >!k>s,5[rר:Ů OKqݰ(~[Vw4ʐ)jq-r ~Wl}#$rS\%:WH;E\eMa3OV%-4c#FGBN` 78xxKa7GW(A!Xp7a瘘yf7?#^hT,Q'43sk:iN)bTY41=.+]]1foT_qe<)GHHaiS(mݫ8 YD0ƼoB XվR\`辢xX&uD vި֡yWf |c䢟fnBTavZ4]|1]U w9=_74X V̗H2&$C *M!bˡU+Vq\Afڹ[Hλ JʗQ0޺3B%²|=6@K> stream xڬeT%; nEpwwwww/(Cpo>}z1es\*r%Uza3ޅ`mgSqѫ[E̍]Ab.<Ms3)͍@9x:Y[ZU4iiS ?,#-?́ ;s{ׁ+s5 - TPHۛ;J&@kS95[ͬi͙/3`nj77`dlw. )-@* /7Ŀt2v'_3d dOKku1w{`f4/pu NNf@sg0 _7vpz+/Y9ЂoNS-i{ z3W;k@T "@@OoJ }$7PB oWG++`lw}c=94@c_5_5]LX-Rowfҫۛ;r虙Mm27_3jio.G7 )#"x3spYqoR ?eyc'k߾_`MAfm̦NNI{sssSe)oMzVKvn/3pÏF€Pz.w[m(C4Gҩ h/'m(rƙfբޤA t#u[aW?ӴxN&03ᡞ?}~)$.FNw/nUK٭5hI^ˮdqDLB&aq,ʼnt3j2g =ՒfZCR %r9bvvaen_ X-wZb_n/5a@GZ+ @+A^<$*W?^ٳ:{Xc{oX +2}- TCハ) ջo;;/[ YThEYM7b6c&߆_X}-%Z'[|:uk7GC -.;GI3 bX/?{.,0ђ( _*˽xMSWgا*Yԙ99x 7 ĿKe5NS:b2ol6eBBEFֱӲ֌93fEwyh*u8e@CGyNRr /̧OH]v Жr5I*"|)eaڜC 3^/ޯuvlh.^#GW4[:.) ]zo\t5@sSպ0]vѮ&yNY==O;~ջ#Zk'$֛ah*k4Zh[6Χ1-i]2_ʝrq2@(#8OTe!w{rn=äcpj2m;#u'eS2Y:Qi24Ke]+&5!&|kJ{_1kǡΨi>ˠ6B+J0mbÈ}hJ{;ۼK>i%Ia&K(5goJMZz dkh6B9iՑ߶$}ҍɫTR|u[nYlB»t3e][õ4= R $'1 ּOGXUW8!B u^E|6Č #[/m ok$Zm6d{ɀ061C?N6 %w ʨ5 Y~Q%=XZHKb Wqp _&9* Ԡز>D3K$0 %0KZKG}.LD4nn4$vxYh.Ě:8<=#% 8B0nlN&UӁ9M!*2;ȌAIRw8,`U:3-X##;s 9/_+;`3]Cu *m)8J濾{WJܩnUgIvu%ٯGʬFؓ"Müjx)Ko9 y#8Cܤoezü5A|MsdW+|A}X* *OPYڃMOҵ6$NlZ_q-,>d/o>r?0Iw)r':={7Z~i7e}m(]X6t,=y!%V:)x 5/)L+q"/(d[ՏiGiMoY {^GQT䦘fd \L@XxqnȭyV\ǣfԟ& Ujf8Xn@$Q=omh e҂?D4j\9RrPW\1k_|9A(/KбFze! ® }!Wf`G$ b[OȊGĉ?S+Փ4LKZ5"Y͌IEOrE~}|xd_hIRؓҩNk@ED O-}-9[ H<8o8un1L4/CU- k38'EC%m-gD{Pr?58LQK~:4ÿ9dMHGl_;?yPt?pcwbyjҽPbaB~'/pEElPU' o#hd/.1OU;A@Gp'4 SYQkˍ*7Rb&" dE 3QsS$jFێu0C!4Yu) 8. R8k֟f/Vgϵ-0T(WUr#%WWsώjʾޮ~}bٹ}p}ngl|1j&] g6Nu%sN [^C3Jn~dzֻT(@P ף NPcO~uk U _ZwaQ9| zˤ07CIf䄍,N%l~8o",[{A!ufW`$$uV5.:L>u͑7E, D<}㱩k2|j$rӤAK#Akn~tETQ!d\km;bxD 9 @*OYQ7jK/88GUb+GB@/mKt*\)#2dewHVk+3QX3Eã^KRNjEMݾD!lBaAMݝmUB͹9 F {mIx~yo'ŬV7֔,0nN}k_AV\,FdV{wc7/A4Cz^LV{\=V^x~F8DLMܠt;.7XV/EKかR]%?M$xZ3=91x_j=,8mZ_wp=Xڑ9"_x]\1G~:1ɏkYg?`9?ׇS SbPeu{$=Ke+0^$ ݦo&9JkV Q$UQ2r~rPt6q<5zND !u~IlFc VAaAꬨ=Q_X^oq7ԉֆKn.DnPZ DE :4*>WmN? ނ;EӬJo_r]d˩v Ί$zb?R7WRg/HU.Dx Kiu8je\$zC21N|ddhHƷ z?SgT2.l~0*lh]xZN.9;gɜrf\ƴ/Lm.wD# ʆ8jɑMܓkK&(+}+Y_ XINJrkR+h ӔE ~j4ja;5E`D1ؚ?kLoinT7Ш5Ȳf|_@ \MYzf4hh~ˡ.CG.5w,vP"xù6#}á8o(ꖭ=:uȗC"ղ2t (7tKuO(Z*`өM~ҵhv^V/4טFXah)3p~_Cwÿ<6)J_B݅F.zbY%sT$[QdWV7VT%J<ȯ?j? S1#iaͪ Ɍ^}h;U|OH\5h#mN[$Rn6)r0'uxwOUw'K4QW78"gT)]Uf?\jPeET{^Z&`6NZPf jN{;Apw X'a2t7$}p7GzCPV ]׵/)Arsym,w%Wb/:{{SZEK 2 1rU&h( ->Ѽ ]Fmڂui:(z^ss!dyaq1'&IHȳpƘr(Й֞]/2 qyhHJjTU}*ݣbTЕK@R a}40ThUן%&WL扂"xVJ2]AUB|QQ;ՈM;ӑk+ XO1L ċ0Etr*No͉Vk0Ԣqwo\Ҝ_¾] B"ćֈl+?(cT")v%'Vd76C?AY%њC׾T(wUrQ$DfK߸N&hrXз11T Kx*j&J'nr GXFN{c30Y2[ќ}<*DHVI%wLw y# 203t=] XsVKq)e5Uعlr26|}AR`N{ѝl$_/=A`$o؟  p*KE#*47-cީsŗ8sJ|-MP*\Gf> u`K7Fn5]7}HS %rӥgX7,ߝ]X>Qe1Rmf#D\k@ \WxR%s?-;4=WVz2GD;;uYdHz𻖽j2/Cpi#+]|a,/66`}Ĕw(v"L>/j̇6qkW($#I⧱hm/ 9R=IcQmc*fcMeY3ąMnwvtks?W[FMJ-2~[a^`IJwsm'CGFY|GWyj|_v~igO^qTpHme<^1z?iE;*X"Qe$w8*i]u0ZY>5`ZN!䃕lpF3X\%"H9GvFH|LM-Oi0N-lfjA3qL V:腥^KX_d}d-"C\GgpmY ꎴ9w6X=]:FׄqAi1fSw)XrԘbJ>LV›^́s @)~fr K(_yAsr阭"R *̛\MT }lʘ0|M\BhӛN\} Ȍ-+H*ﳵN'`* V.dZ3~tT ʥ]Ly2+N"wMڔ!5샳@d8vlx/mpCY=Sw l \QNQ</|o ׫Pfmz1♲Ԏդ׳6c|52Vȅ%y v2dC({r/!}nw9izUeHbܓǘUh #O0[Dm#;dlq=+7Aރ4C$Tg:aE0 ;J^Z4VvQPR'zHeX$zꅀ}ct687̐V䨿  BS}J+z T[P_ |&t->sLR"ҜoŞE"(+vk~Ii(T.L;etX0_ɐ=Qͼ@7&0p=$k!fFwzެNbר|2 k=&xk 3WU>C}Y#ay^I ȝ7gʦG# gۡÑH{GPJC|oBH,z}ɞ \ f^@VG* t vk!gN-y~!=*4ї@s ^}I/4 ML (,hke!~;^SQ&$\R_p?yL NGr4,^mw9+K\T!޷e}o_C_ tQ>aTUߒ`N9wccǧY_ԗG(-1CC5'F ۪2["ZpRU;kʡP$ŧO2Q:Jt*QvY2А7u}H"<2 -I- 4TЕ@+)mcВC.Ax?'l6x00Z1XLL$+Pqji*LuM$D|-8rX,MTvSO )wg\ .`- _ jS-%APi~6.` r˘}aV=:oim#zʾ!*EN{ 6˓V ŝSkO QLkMLl_9@増k\|ri,Zt :nG 뙔,]|F[W U; c, wd( /?F i) N9dQbKtxs9'/^ã[Nв"^, q=qZXO~L|_C^ mЎL)gJR0noa֮qˮ[P!J7|iY^G6"TWp:s+D)eq`#qѡ)ZȴCwbUҬ@d{Ȧ8DS"$*  @ũr@{,\[}HJ/0KD^?o,{1zx RnL&#m2DV2xyZ ש 8RIYyZWK@,QMٳ[a ^ Z\AZj,$Bs8&PIg.gUUH*x I t($z-ة |iښ|2mL2ْҤBbr͝hNsĿK\[[Yи;"PK8Хָ8dD,ühIH+Z7bАahALXGV[i1\mF8eWK EeE%Ƶ )NuԀx#/t˂.Eg 'LnD۸2-*}3>AS>H0zBe@=290KQ%Ω. t+]˒ "Q0{D4$ھE,&?kshB]aQ*Rx `8w*I`NYneSĻPPOXss dG#/ݕ $ö`M, !ǖEBZ0D+?D|^DD%2Ue@-wByD,uBc*odMz,^R(N:v0jWx| \9Jd팬/c2x jv6wt1CLyӛܗ4"o <䐵IQer=8];Ygh~O>c`] oXgn-5^F.*Zm gVU dIiQV6GV%.NT[՘(yފ9_2֭1X::l{'?@C=h_kā~N?TFБ,9\x8-F w5 *aX99p9g F81R`N.֯9YC5TRX b>-ʸF9ydz 0,qpÏ/SM"aO.zGsț z9Oqk-9r тL#I\\;(kaN$ݓ19iX#𱥈/c0TczRM;N0YbIh28iHST=-KΝD Fm#m4!Y5cz%y-〟Ӄ)ư~]U60Dvk#{~ 4`Cp"yDY`JSthОCNg̓Y^;C$;uyP9Gi=g+*((7cD6g`šm6op3+ڳܻmA$'wƉE2RSfg:uͬbmjlděYnB sW{¶9վV>?cC2b7Oʒk&C!F_g !՗SZNN=PLΟ{:˧~ (e%S | ZbfIF?120."̶3s {ـIJhcq*8 z_-3HCʇM 4EZ_RZ…%!eWl Đ~,` B#w3CkU'l>}BlNQ[|keQc~ҍ^,uk  *hJ?46r)$+$dFJ@QUmFktЁ_m~tb1. {'*]qw-H8ngGjzG9MGgf(svɼODuf|Hb9bޫG۵lsJrWzs]&<_d%GlɹT5W)Bf_z{x@rHXF1(9SoArDSSɁ25lW >7vd_3qJh̦#" Ky>_M4T㣑[F}11L" )#Y -sTB[,X$h=i@Q#,eb"zhSC}eRb<ϷרWaƷWRE4|xtT'g:">PJ|C}5 D0SɅ?^}PjĂۿm=9$Bzcťcw{Ri5 Q84d$\ӺgdbZ!S#=ᖬU_$ؓsWB\Mtt^,svpvhl% _(0=q5\;ȭ?>z#K7mUnGivAwmzfH[c&[)eQy{`aX ;b1ʹr x_ ȷc4  -S \ *i]}9A'*p}p9ڟhxmTas#C9DI3R'Y v:oRWYoYAgΚ%}qϓVUr,M~dZjLirQ R0\^e Vq!pD0 _ݮu~w(;mq_SQؘN{鋳Ô֍ab=2+4p-`k^d5PѪXgh[$T&ZۚAUŠ!⌓%$HEKvgLRɉ= ])1a6 l7;7{ 'bGlJ=H6r]dg$;@&SwfQy=ܞ8{(ED*),ga,cg3.h,G@|(421dUEyv:!-]J5&~vM{E 4br~r d]EW @c| Ƕ.˺H=wI)w,2 g\ַ7C#؂ky+ͽ^~Ӿwdl`BmMxȘ`p,[ı-R %[5=Vϱ(L.: wJ7o Ti6'ъtւTntQ_]KGWo&,#g [ߌ䮐|v>^4\T|W JpyLb~.ɢ. 6TH$߻tdocnq+s?~ ^ 4=60Q%rB _DZjdaTv3CYnʝZ!N!. :䯨#QAj=;gJ{AߨdVDETR&^%[&k櫮TJNOk( ۡvTY8a\~ pmŕ:U͹9EB|aUI\nvP yd%Xx.z#PQK꓈$S;j9YIEOa7*ҋ+Bٛ~\#u+VWh]^A?"CT'EηXz_LI\^ԋǝ$Liωᚰov^љ YOAC0dCBAQGvhvr9ۻlG]~Xz]B /N|\ue&iYX)nSe[U1]BKFOX;$jS.pqI0ӆj>֌oO*-K D3J#}Cot 1KdE#a0I4f9/8\ѵ"E з}r3ɶ⏝vPLS!ZxnНǗq:1Wo3 "VveZq7A14mcPܥk_7/\P.vOf$tlO ekQ+*H-rּGYƞ3_[*zk!^}:JNRa&PS2 ?"J'>R eigkC^ە~2|#t#7]ȼDGTQD)ohHp]*Fdc?)$s=dmu|.3Sx_=^M!WcޓeH(0jtͣUxG|_*H ۻŒ`8]xfNSt؁IGޯt;b|7~@=s.w1jrd2߃pGthoWI8M+-mDVsgOVXn{ˢ֦E1/9fz \vp'ZѼ`=bJΗH͎LѪ$jP5eo*abt>hp]:|lıCsyԹƩm{y8M:\gB687#m]Do\mO#^ɓVv{kL9C-UY~)8S\6NHlؽ<{:| >pH6JӐ408lMĊ]ak(4kV @9i>RYE,X1t#].i5%b;-sgѦCqmrSRbFX'wr1jodUXm y-ؼx!i?wM:hJUO8b9q7y BcսW7r漏ނikқo u5nv8#*dܜE61%5O}K"Q;D* D誈$fb[=#O^VjgT .LPݚ~$&͸@afFVz\(3Zfs &+>>! [VUĐJ+yqQV߷\o=ojS'IQ6n/%iko19\l*3],YTa0}Lm/XQ}x}o`#܂;8Fج:iժuQ`.)zy~3dy`J"QݧK2q1e0PY'ts GcwI\V;i(NO=.PR׎-W>#.SٵC: 'GGSTF:2Q7ʁʑȚo%Lx.=i舖pK%t*`׉AmMJRt5p"j+ջ7AUq2O4H9vycVl׼}ɛ :oi'Ҧ)Cסcܤ}),x<FlƝ.BL,aK` yP d~l_% WS -U( Xg^ѝگ?DÍ@ ‰$M]HJUQp\!wE춿q|ud`۪},3"jkHS")3:ٔ{[FH voB{Ϡl:Cӗf툣'qAϪ5&;lIJd 'ƭ+ m~5(֐G$i endstream endobj 4937 0 obj << /Length1 1644 /Length2 14112 /Length3 0 /Length 14971 /Filter /FlateDecode >> stream xڭUX]%{ЅK [pw%CpwwO7}gYd,JR%UFQS{c7{;FV&>= iDXۉ]@|M)@d`c"P;x:Y[hU4iD>=-T?n {['*p,m@J Iu$(X,M@v Z?93}r:gp9Z:;,N@;,Ll\MInf?o~bdJ.&N.ϨJΖ0󦩽?% D]v?ASKggO2'lig0@@'S''?:K@y` 1cB`eiY3n?17ӿD~&4]>ChTfA[j<_(m?;dv=hlN_okLQ;Oiy8xXx X:*YX̀6}]dci_0L!8 Lkfq 9Y}2|!+]>EiۛB11{7#+5~_Dy8YztYXXX?I? B#agbo L?g? &NNk|?z aeބ?*=+åЄn/+Pjm ?5LS|<NeFzql{RA}TA?34~mAphL(!`wz w+xt@3IDkè-<=J:~z5:<4sݷO@OK9%Mv4ro0 \ݢYEJBɚqNl! "h'~V(@2uZMƠsQlk^/:k71jQ2s/ԯY:a R,oQdl=bRM 6)ԥ$CPCzQ.[y$G/CS%iJ^5/U_,#^ifVjQ笁P. hBG(|"Äd7U3 U0SXjxLTd̫z߿cw6؉[3곢:W.|˗&U= ջ#h=? -[+|foN9?)+ź&զt;{lE`So)F%˟2H<%,@X2O?&jś~JoS?y9&yMVZmesNV$Urs\ƽKe5M:ceBB~"d>SIiLՙr!TL7 h)| kf|G5KE B/kU`͖$ľF`AӲgh0>\{d~c3 B4u=gB71k߅H>Z0ҡ 'JgNbny UA0Zv=(L#?`Hb1+cIh _YRCK5a>*׋S87oQ~"[j86ym(AXZ`M` I`3:_*QCޓ6\X_ԋ-Y< &I2yrjr,+U}MqEc45"orGi RD~A}< ]t$= ~>yU2+>d౾G`$i(WضuE0(Feɩ =uQ<n%4Sg\1L:Ee <u=wlL\!W 蚍5b꠽~FXK޽bڧ2"-Fq`Ct ר9.$PSpan)#j-Q|hSti*սOtn CP G;AH7] qC=( ݽ6]8R_LeskJCioc rUZ4*v_ێY<؉fRi2z"OZd~ dpxc(6j*Ղ.Aq!)cs?FΎŜ~ {]8Kjb=FU zX8\?2ЭnG|U,Y""IFt%5ѽL8LW̻T^\;r&*a.ΎA1ǝw]/^)Vz@DUcMyӋsdYy+La$InF=9 7M7mcYLy TjZ($3N+NpK10 6K`X˒Z`8#67 8&FhF/^:4N(zA~˯ )]}|1%YMn`N3=ۧ4dٞڲ!-ͬwzz$z-l1?veOʌ ]'r*a9 s= o}r$&*"8:<(owX/FJ raUMշFFT)W[fʵ& k.۴z3É Lh&5ב '𿩔-?r&Vx ^5/ ,JH5x+SR}h\xXyE=-ռQB_3^y!3@䭆߸[Bұ] EF-rE tA]sM;iW2W$ fTٖZ%1{ U B. 11rʬӺ7:fIɑ06}E94|b3Ȇ+\`%* K;00"*N=SDk)e(aiEO e~{ T%ckP`74Ԑd-J(alH3\\*Q^Tn'/Xu@hZ;EO7{.o`^{gV/(m>+*'o2ꏕkF_p6>Z BQ~B> ^f"YiܭI՜evʘ$6x qrݸցK݆`иTq(\ي5~r#3kU;.&e$mG3DׇM7. .g+B+@V0r@*K4]WɍHxJ-MVoKgn!tܤWXd3N&`z 9|ct[>/:`G/ zą@CW)5@G`r t5 #Nl;؊c:H~g:g+WZ.0r(m̲F"?YI"̝M =Kk0rn+iL)lUϐ1nI);)g wvm[ädv^GZJU,*6ͽ.g6qS;;B}hpu&;^Z c;Qcྼu%* '_"5+BvѪۑ[Ğz]Fm j&CㄕA#zMI,:qzU! $r_ U9u~FFju#g}C+ƹ7w^biYi\5X3D~*џ5$ ִ |TnbfcM 7~6"FYF5%R$t*;WR,xfnvSW1LA{u=38#:xz¥5D1fMڣgd+4x4AtN'r[0瞷0Y1H>l'nO _9N6; ?YJ/5!w`a&︾3]ɜ@obfd1>Th QH]m^B{ҖC.+\ 6Ē46]NeiJk1đQ{98DF1#.tI5cNthMuwg3ħW'A :6R𚠦͵??6 7X7v⥍Bha#AD 2|oO/隉S Ow VC_1c Ƌ$LkG?v@_F APD""e8w*IUe33b)cHߋZ.zb 9 *!|xՏOˌ&~DVDU ? ׵{זLd9ld:K<_6~SļѐDFuV0\7aĢY|& 5G0 e)c4VKA ZT;uy~]4N P7<ʳxF5#ڥ~ԣ9OUMV%nΘ@[o_9Q|%u gPd$FafӯY#-&SBn\NbI4OZle;(/$Mn so+K|@ 8S -1zu2aoE̚#Ezys)j8Uba8٨aI蠌^,!@vW e C}ICն|[ =3ߓwZ#p~,uco)!wIS)*jŏ1k`\Y ŭDp&%`dŏ)_L5cpZ 噽C`vOk:|'VM0u쭯!lp|;DtКbiSjd#OhFp^8L)f&Hq]3lOUbfx5d6r.l؊rcj\ 4xj琠߂O|^X_ov/BT h΅M&)vT /\N|#3kL?A@5jRiu ;+ XI9z]Yq{[:2Qh[" m-u|kw0XG?+ĺʬuEl3P"&)߈Y,V&=28㶱R]ʸNRՏjY6W! OmwxWI8;-:fes5/ǎ3qx8011/L%(3ܧڨwE JJ)^ox"K]Tzxw.5{gq7w#}/XJ8GbEלN 7a7̒l3%6"34b(ԃcȋ({.W5ݎ_&$7| j /*?M_G@@_w@>kIݹU{Lp# X:'w\^3147HEkUFPpW7-\lhaJG_M>Q&;C0hWL;S#slou#4"璟s ݉:AUK8xEJ"L Gvo$5 1MK>x_i f\뷂^z}9#QsoQaokSN)zE+P\^-׹nY<ҹOL$jeY>85tXKny*k'&Rd]~3q⒦m%?Q!#Ȣ֒jQTY6rUu>uؗvJl!ķVO,c J3SsH8;ivk\(XF;c=e* 1X zfuyΊ,g5&\_$iOc]U#;,~RmbjA>Z:ˆqFL?z]vd&|Ȕ>(& hzkDTjǛ)#R.xEC9fc7N)\Eoaa42.KQ^#Ur]Yj%4zCo>BĊ=ZYz+fw RBFyeXC rt|wmڰ^)KDɲ>pgn]}C ^22|;p_ IRI}Oy16b_|lb- L9݂Ԅs>4Oj*ĎWl`#b^?(HUh;:b~+da)E5ưv;&2Q|;)hz摣+Kg+>~pSd2y8 }?\a|5vϺVNex.nڼ Z[J~mcO'C0RKVVytGbVjmnG>GL5DGc3?Uga"h0A{Yɕ.#Hޡ ͊>պyW]tZRf3B/AnD[̱QwKlv6Q)nbqcdbh 'ԋwn|M(Ρq+HUad ~%aM ).!!YhRHqi^'4 ~9#;CXz.cˊO.iY ܟ:X( F),^Wpe{Q>B,O>a4{5s$\]]|-iXFpZ4JgkEX"mn`¨Ci޵:[%m<,<^̨{(N;%u u:f-:o]Z%fdi[:0>i6Vr@-F0a^?Qw>B5c"6m;y*; /D`iw5wILk1hF)d](?n1*Wۢ_fOY@0;1(57IMvpm3S,Jd<gLھqnI(Z@ j` _+gIRcL<ZԶ n7Gd rXN^:ynɕ r1"m_%]|8jrpse+z8t5h8$<`F0kaXrȈ~nH\FX_b7`0ւ/=I>r(|̀ /[՘Gs|)d]9 <ҍpg,3uۇ@ ?w/FF@fV)OieȲAj, KkĸGNn{ QVlRT7&ön{9BCbE`Aӟ];h!?_ 0{OT͑IM]>jEc:uѫ_- Qr rt ŸvU 2^лsJ[F3όP C wcmLxnj`ӞT5"$-_wˍ>^+{hs伏50JCա.zlVCdoL$u9>t;g&jOtY' J>;plAdM*piJIWN{ T^k}*zϽ pv|^S>37 Jz2/Koլ81*+7@ɔU}of̍?*} q;|e %۲#at}e͊GI ׯ4)~6cҰ~}G anF8%k{mhjBO:%ZEk@f[/4w\JDlqNk7ߡG=b7ih6V2/D"Ө.S86;^NoVqxF"'۫kaDd)v_i@(Tl6~&%~a548{]k?Ӽ1E#gzf (?:,/t!+YkJ{_aNG<5 ,  Ua:(2󳗂IR>N=FfJ%l>g >12ƿ}1(\v%.0z>\/XEBFWMW]ge389.XAW=>O?.9WJ~m#+E8ˇRٳ" N0VluӬDHT@<kVa,cEB8/>sBB-{9+$.+i9Ւ,DiYpB5ב Dcg5"!m4Gtd6K Ŝ ڲB;¶ǿF<IE>| .qW)aEr(ñCbFmܯW%j8nڼQ̮[̒zi~Ipڢ'yGJ<謅D^FTn}m0j.V:m4L@p#+ǔJ>>}!};ATv=Z ҘU˓70wZ!DdodnN,ٕ5''#)pӥo_h4{|Ⱥ)p${RE#^1g)z9DA"gTVUl4pPeoWd5ٚo%Mag#.Qg%<*(aHkg b߬5튇ҔD+(_F#j-=Jw'F61| @%Oelk 8jui2Wlwzi >V^Y,B%80VMo~^KzRܚ%4W̻zv ZnUjIQ&'/ ̌늸?-*, gkd 0}3ͮw@%ͩqB06B W׉FiqpnS59^\)]UX/[Xo 1āGηlhZT&./Ve. endstream endobj 4939 0 obj << /Length1 1647 /Length2 15181 /Length3 0 /Length 16035 /Filter /FlateDecode >> stream xڭcxm&c;pEtl۶m۶m۶:m۞<;{q_uVUuc*P X;RQӲͬmm$L,4 ;@ hdбAllLLdJ*)((S @?oK3kg#K[+#kokC## #&&- VY'!oif430v0 0X064'5o.>`kdoe 0sY;~߁ 6 [&qpt07u|{wzv06ߚ6N/u3v8:K`h`k_a89Yg{#={CK#oon?oZ_Z+3G#Kcjh:o߾M̬i1kcN9AX[ im]LWo5߆u+w{5{$,K={? cgef2*FrW.M+DEDo)X%W6446.ۈ`fTߐnʀFYQX]Bm,nFIEqxP1Yh{?Rzf ZjZZ:|_h l #G=k_`'{k|g ʢGyJzc FиF_ݏ zł<*nmr IVSۏ}q=薤IF8^D{6~PhåDz\Kn3*kN3C^=%rE%~6HA@lB?=H:02<4}ֻME¡xJk_o 灒DgMb#P>BK^|0ɟPb@~5to*E zOc!6Fx@IܤWJtV}_N!cH;sQSe4m^%_MQxwk:B8>;_]'[_h-Dw-QT%:꺪h q!T3}/Y]Nq*­_^Q?0 )YcH.34L[oh<90V_ԈBtfL4-h5 ܗEnv<no}x1@Nu;`}ԝL80YU%m_4T}wbIx|@'@ VÂU=^K8n7DžnR.plX de2WSȍ jHz2'' IxX#ZŽ n,sHNs)*j]Ѱ #r4;KipnF[uKJf]nNՒT, ^) mk|'}NxsGay Lf`^GK8#"M)tّ`BwX2/>|0O.IAaoCgZy_}a3{ѬаގM=wc6 Y`Xv\8GVc.Օw`pѳZԨN~m(*I ˞`WW9F,Izf1hOnޞ Q=+pPXWC>RJ?XjP&ؖI-M)>-[.2:L!ؙ]w:5wooK?ȩ?!=o$b3j\TZE Z^E~5@CmBU]1zT8h!2\ *d- 1fl3# }T hnKM6,% YQ)VWC@mO?)XQrL/B(.\zXRPjdeLI!1XMuZ%ⶒzj ܗJ"+ ^n%0spvF -T#ۇ‹qQsHx G-2sW5ta˼,B~T L 6DDȵnV%@'a<'jG1a ܳ,סzC4=?@ reE].FyT!uy녫M" 5/sI`WG3"sBȪ N<5^rz &L|KNYUX0В(R4S$k.[>J.#2+>ua0IS`Idp@9flhJfqwI֓׃ANR^<-!7Yϐ@dIxx"+PѸAH&hrv1<ٞg3zOy<^8N{C m@mrdۄt UA )>嶫76/n, vکnK2|e=Ƙ@> .9Q2 r}) 2#E(5ó+L CM="}W_pb1zۛS_z 8Sѯg@`syXBҼd!Jz8q]xxR Tee`qN[.z!xĈ6 'c6˨ŋorSA V+A G9$8;h9%SV!aMr@?:4:kJgn\es2;yUA /iHf9y(K,# Ap8En`BG9^+϶ ؂ f*'cQdJnL2}T5 ]mu'{:Q! Nq(qZ[xH"]z:$+U GKh ‹@.2ŹSzCڲOLk "#gSR `B E;1CtWQx%H1%C8BQj$ d; z`5;(ؐNtIdZ8lP:F8`GoS*wLdjQLX|Uq63 W?~E04jg!e!Xo u2<v6(oh՝gEN/֘|] wyaO('AJ> [t=c}Շm݀`d-]q$1 Ό&rM@![[N[IsehA~ _1υ2~c#xť`NK]'y܄~ř ῰93K 9#n^}7Yh; вʪܩ-I+[Nj5<7|핪u7$~ n~1>1LOsެZ=P3/D):р0n\nKD%q.zgvn*#@SC1ߪAgb/AONΣ߭x+E%޺!wmp8+J'An0E^\Z Lɳ)lmic=N㔞c{ NWGo 5mǒz%P\*c#bƬ(Z]*0=Yȿ w 1B/eS*՛&=<:dadi׌.}&!$yIvt-d̘.z& -XZojrwCTKu]{qX㮾, x}Tbi?NwDGdz,[6 Ӻ,'MŌ?s` Buh5z/ߌ}2JD<^IK6[ ?7e^*߷9{/D@"y67xz C7 @哷ּ"Չ7x*Y ">ܯOrGk_ %n`kBiwa/ ?FTj_Sv6<^=K`=2 ʬqa66v@,FB͔Wx|M{C&#mVI9˧3*;|:؃vwTO7ơJ_sz ¨tV4.0cs đmۚ"iiA|A[\#l)@aGS\+ԭ0W2"+χᯬ˂d՝@Yr!&:;DĤ|vk^C1*Y z>aJF=:_aGcח/T!- cB-/ i2 vJX &k5k&@R|O.x9*(*W=aqA%*9CSxkKO඼nJ/O͖{,.HB@'\t3I6V6;6EM)|=Lo@ޟo~=.O%jo:׹m}zht^X1&‚:]V[!HO U=  3[x5I*hBu|8[v GJ %WDpGę^w#9-ǒ0i6qŘwcytBoI^NL 4XW}z<E=8N6 TCOQqW LQ$Oܶb͐M|[t& 'k<)<>n[iXl-<=փ ZLoWcW/fdo٧ }bEY+:Y __BIe"gR(Slgw0%1HS*~Iz!Les[g٩-19I8~Y +潿YC&Yύi%*ܬq09+}hc ǷldKDq`@c z1 ;G4}hz邂 !?ܓ2(a[7h;jTUVOq9<)LueXtt!4:v$Pj@X&ĶA ~d}y[e_X*;dt&xE̩-E M[NݞLHvRz&t+Ko E™v+ֈ؝6+oͲėj~|7#L+ RKهSޢ8KTdwW+O+LJa(QN\>D.Ȕnk.E PVL?֟%ɳRqtŹuHD0ژXI ;ީ_9S5Idal#~l{=FPJLU~oc ݋8"?罘H`U/3Y1q'Ctut(p@Buxh8Wa? _iHpT%:xE-UZLB-o)h w*?6Y4%q6^SV-?5y# :[w:tB06v'³=SS7+f-"ޛɮzMI^lzn='y#L[&kY/'bjPl) +o "5&4h{򆻐nfO?H8zfzﴪN0/-֩nBȊLVeޒ8VX(sX]uѕa.dz@l$?d5dkPBv9F3Ҳ:}KSCUV7.m0*,: m.t;I6i{ L6{Ww(s_U"P$恺@cD,fc 2B`<^M6u?0y;HS[a|wD~lygvh(n&T>* Xå-61_t_Qh۷Kzpy4qYsl@ZC># h*zP%y23S2bfIЀoM3h$Flv$-BmT>e7J鞱-ǁ=f. 7vceB^^h;ˀ}S,LߕL(Y{0D\ 7f~2ߵcɝTgyjEMOu-wMj+n ΝQa*n࣎_w ܶq/T?.Lidq^}ʖƹhmdN0! 5Kt.,PtiQ9_@VGX t*v@laP)3!5}jgqjo\9Gm;:O8{VE+.]cֺԺrtݖ~$錍sL0¯KbDRFך_=VC [Y"wM=ulSpYlAZHWlTpwN䲼7Y6nyBD2aie}-,LWƎrvJ$D_5ח1#)|drkܝrf= Qac/gC4A K>Y/qq|yDcj0k^- f dž:5s^bތ"*%e֭Þ}|3#>-ƹ1 z 3,*X{S&O) ˯2{W3Q=6KRg@sȃ#F*D]c/Ի9?Tp刳VNqߏьgfz@Pmbf^bt.Zd)3f { T#| 7_]m_oK܎3XzGtn*~3f$ ;S7G.W*ADB<(LeDGfޏwc3lյ`m t;8BfUb[a ospKf5FwoZޑ)T|uFP7/JL?AMܢ1! >ſtt#ƥ^6y\^U>T/#MGuy#[ 3SI`=}Ip t`HmC"qt]px ׋P5ա6f@)hp 9Uxghmzd̷ji($!a[bz 8w'8lSkAMAP$XXW3dgOJyBS1ؒͣP8Q̪[9{<rT; zyRk0{f%k-*WEsG[l}JE,"F#"U }1㋡nTbpNOΡ\"d ۹֜V`s(Dd!7{@ӶT-䱣5H)I0PTb;#/ln,R.C +L&r0hq"d`C=nexBmbޭӜfNhe)@qZ{J Y/G~[ב/zl?A2JBgu?s(fW~ 2p^zf^ g/Ş}f/>fncHDG@V`qX H1y$ Zd[J(H@vr\erxr H~ {jQM,j^<W}ҐlEEQL23 o@*o(!EdZ~ f"'e{t*W1qH> |zaQ. C+덍.JI0޸ 3+xkAVK1 0 f]:Xnz}Ĉ0&`RñjisN `D[L %v2>TF`[Skи󩂩Yc,Z߶'<'_o; i< ؑN"L,5@8Ynmpsy>Ty+_-4:ܧxskkhTݴt|J䪽6N#vRO=N_GzC'9o&~[?(Eosgu3|琯 :#ŕo!+lquFͱbHpoNJl0}y'L>QEBltR yF)[5HG$RGE*M] ȋ0lhsJi:{2D|R4C- fNTsLfu]Jb#;%Ux+:g\f <:,O <6bFY\>e-b}1@-6#?и\]WC03^?b̈9ߜ(~!oMx=XR-ߺoޔh;fD+4i)Q=W|o/0Dž^uH5IF~nTN^c24CS2Q#hbӥȲ_rn>e.X c=Pa M0uqvu=v;w1D8, Xb 93_L?)KkF лȏK~.=R&l\=.a  Y4˵Szw42smuXLgZ6R j9=cqUl}.Dˣ箜c eYf9l^OC|9Bk-1RiB߫7n0թw!]' |z0ÚAҩ=o::&4? 5{eg{wh% 3E* i%Z5~ &:S(NJ2ap4-bje=K55 'v+ω4wGBIKaY"A_!G+YzN?֗ NHsAnf~ i*CF^j-E_bYّF*fo*0Dm[sD GGeiEsyՇeG\~// s."nJ0?2qy"`)QIuXFKC3\= 効Vį'@N`$sʏ>ZpuaF#>6m_tKݝ3,y-r+is^` #qOzRHʸRG1g|h[|3qOg><ٯ33Ix54ԉ%ewAppғȰA%hw)]x ya<{"S\2 YғiZr\=KO/>=Ik>ɒ80ґE $JZɦ'WkB-9cR(Ҥ r& U\'&PNsI<_ i!i{ o!|]]~ABd TBXG٥Ώ,yEZ![FFMYhF6q!ph,?Q8|g#[^* *e/ԩLܨz֙YtG'D-ŽsSFDfNߍ샽0G\-U~";Z rfcٗJ6D'ǩ4f3PxtU495q=B LF9\JvW~&7Pȁҡ]" $Yk 32s<LR$ujX3緎 |ؤVV;@-T$*'X%q?ec.!%TvtKMbj0 '8!5 zn)ER6|lAla* %j7vAagdy}{c"d!cqA L^]9KBsM vSx5S1+\Mp̌k[yLJ@IXO]juȘ@䢚/kKR,/M=Ԝ\rf^RTp69M3: j1:I$I Qf^q/UG= )Tse`2YM.n ȼ`1^۟Uc20Eq'] 4`'C$*X pxkg)^x:V2WJ n@$yDU5j;QW-ZJd}mhaݕ^wf͒<;Nd LڙlcH޶X"ld͆jCBT|~2J[P fLoϊ)AJ5A'yWC8o˘-}z.lP:&ZD FK/ȮjoC9钾&Lkj)I#,@=ߊu,QP*UϏ-g[E>?<Yv1Orm$p h;X%e[z$[w3dCFzSLXNU;Gݷr\hmTHޛ1 -v ٦"9?b蝤CP@Y IļD+ E|bܧf޻dTk1N9 mk!<4Ǡ}' glS*|o n1^X-24Eu55e_Q0\.H|"bCREDIA0uwlt+Ef}vuBߌnel8RE7k"bŕyC֬mwXru8|Bw#/0!Gca\$#-)՛H-. "LZί  V-9ni?d;3 RiN+/`28JJ8~A຅^Q4\K28˲n3g.Je7l- KZ _P5;;:og#!nʥSUKs~ SD`]bz3 tg]Xi͞v'7 'Tj$H Ymoqz)]lZLb JEX7q-7nQٰ N0m)健Y:\dFY٭0|&{k]+sq CXkX<=g. #+Jx Ն(eNlz$s&YgTZ2Ƀ| 3>jNo6v5e@蓑c|&A@vbZ@jj+߫'\n%%05S9O ?rt<|6c;6?~XE.NlGLY7=(OLhD/yZo&Dtk/×__A*d4I=`T5 K .%I:x- ɍD = N)+aIVXMװunpI;즚nӶް 麾qu|[1e xMX1=tBc"/qȿBUu&>]Ųp_f ß..E=MSd)EqXTn:J8ؾ pS?}X^{#_ȸ?csBo,5ԣe_>u1n>b`+f;P^]LmPB湪]pRjQOO[ a4NJ 6:?f}~2"c=vjU*7ʘ`wxvs £oޓx=OŽ=#sCPffBs >eBr_}ݯ[X xDvnOK-krD-ˉ^tRGGNm*0yϨ7),A*r_+˜"O !9i'x}!|T>̌qUprZeSOUW`@ JQJ0&PH\Ǵ惂J2tx(搘,AGFɹ[Sυ #fz. W<w_33[85}nBo>a#@IFߌUHN/H-Ѹ׾w1`.Y]BAJ) *tzֺ /A'efӜvroY9ZIaI;}q} W;c[9-V-0'>"dtAGL@u "CKpcҭG!z0rWF1DdۏLP}3_otцհ/H*J)gk=%@'۸|Մ [HSJ ǙtݑdXτfm0׎+׀(9%؟qg8ř30)y?ih( M_*Nom qтz;hǴcG$ )¨dRp>.G^tUVGn{=t0 TT]c۠Wk69mݣ`Z<;B5Y_yŠUn 94+7b8M3\^Y@tFKxkG%Atxʬw;D,J|aV>_LI0dM{40a#p~|bW}i Gt|.(JzXp~_(PyE"ErYWmօ"lC%?קk>FwL;8c)bبRx Z1)( bl;<_Cɛt\Y"%sM:+8EtʧB-f憘 .hpIjˊlؗRbLa{d!p,@h֬SCZzJY8WR$u󻨾%Eժ?=^sM-;a~0QPc@>xsbZmj@s [pΆmH-W2׺> stream xmUMo:W5?$R. d9M eCkmCp;;w~>|3E_?O]5߶w]Occ]=~?}Oyh9%?۹׬B|Ɯ>);vw%g43>\ 6 EJ78 1{~`W(-;]%=xe_,b+-O;q\L}UI--=BKE1p[! Mߊyu>.N5K)Wb٬8i[_uʕMzQ)V(Txޢjy!Z2P="Zd0\ÃGR\).2*Шa!U,H`+j.5Nα@VK-x%3%AYӀzΚ>kP#5m0Woþj.ZT$X/)n)#Wo(oRZ $Kp4Z-b\1ܰJ P"GXQi/8k^Zq:Zs9dB )sL-7xJ`aɽ)f$1 dъcCZC<73JgznHȰYɚTa,_-O87}KԴܗLloK+gJ.GZyVc48Wt]:P~`rZq.n1] S/Pu7Ue:?&?!d&1yHn5)yғBx#1ޞ]Go׏M?X endstream endobj 4942 0 obj << /Length 700 /Filter /FlateDecode >> stream xmTn0CƆ@LE"jD;oƤjgy_xN{qV'wC&]\]]u>t\qxں7ŦmN7isƬ'k~G]?ߓ` 4;RV_n86]{̭֚u[sfߴ L:?v>4|`0nhWu}QE KU=5Yw߇l?N6jwwv Z/բ,ko{&PaffIq XMJ0LfhrdĥP> stream xmTn0CƆ@LE"j.RC~8iZ)Ayo7?nkNy$냛G׎ծU[7|SlfM[kwʽ5g x=i6;RV׵_n85]֚̽u[OsE͡i P{ LՑ @4=tb/yVvL MnݞArjwf4P׏ީFT]Nrî}sBZ2pmmR?\rs<, X#.KIɌCH'hjmJIQ09da"2rG~\5hגQv]`n @v)(A'b}qHI($ux-JBJ!^I :ggM597F7FN}Y{}&Ff.pdk_ ΜN0VG9ʱwDK4X=CaCɁg2)4X(rb0/s4lƵǮb]ˌ[r> stream xmTn0CƆ@LE"h.RC~8iZ)Ayo7?^$ŝPIs77EW]}==硫nTشxGɛz?{k۝=` 4vN߷u8NM>(s&`ywS0jzQshz+&TuS~Hxqq`P<+ OC톦}SWUn}@`T;P3qtj}w*5UWSܰo\ze \[3. 9ff ؤdF@!i @F\ ` H sn4ȶ` $(Ng 2R0zd9#Cb.k(@.0[Czr aà8SuX$Q:\CAfpGR~m%^!N%$h&՚R #ƿp'XϾ>AI }3Nh25gNE'bkkؿs %|V !3?fc91ӊ9|u 6ZcWCab d1׮eF-9Ag깐3Z=I= 6-7p?)pegT> stream xmTn0CƆ@LE"j.RC~8M])A̼7W?^$PIsWWEW]}~{SCWmݨMi7mv9I+ڴg{ҏÄ~F )P ǦkZn;@1zz5= 7m=x Fgu P}?i]X<;k C톦}UYoO} A`TS7~wpjmS!詺]]ꂅK(ew&97\=̒5⒁yAa>:M1ȈK,x΍t,@F*&" C,zdWXPv-hakH/]d"btv"gg?|2JB^G5kdwt,uVT Jb9;kBX!00a0bw3W M";\88̿9Earʱs ށ?c>+q p~PrL  hi˜c>:q-+01~k2#Ϡ3\OLqRυ>¹M \)s9O \Y!O>\\/Au*[ӺkzT%C0t endstream endobj 4946 0 obj << /Length 700 /Filter /FlateDecode >> stream xmTn0CƆ@LE"j.RC~8M])A̼7W?^$PIsWWEW]}~{SCWmݨMi7mv9I+ڴg{ҏÄ~F )P ǦkZn;@1zz5= 7m=x Fgu P}?i]X<;k C톦}UYoO} A`TS7~wpjmS!詺]]ꂅK(ew&97\=̒5⒁yAa>:M1ȈK,x΍t,@F*&" C,zdWXPv-hakH/]d"btv"gg?|2JB^G5kdwt,uVT Jb9;kBX!00a0bw3W M";\88̿9Earʱs ށ?c>+q p~PrL  hi˜c>:q-+01~k2#Ϡ3\OLqRυ>¹M \)s9O \Y!O>\\/Au*[ӺkzT%C2t endstream endobj 4947 0 obj << /Length 814 /Filter /FlateDecode >> stream xuUn@Cx ,ei#$JW)R w8`x3f_,Y}..=pF=Lc겺oxķCvYQ_s9;~1_B4-辒O~:p̵:롫9Dsg~&1^`32(WB0(~z?v؎r8ӫh~?u~Wu]t<(V4dqy5jޫ kOGKWj4?L%/۳v _NU4(61ȘH`Zp0aASgAQ@Q LE)58ZP\RC%4k(4mA%MJ$*C6TQ.c3p4ct| 1v9y\;摴.y.i*OYIa%a2A{&cxs4c̲ lcw36av7fgΘ4aʒOg[2O[1[3K?mgS- }3 O3ev/Nz}\-!={3pII)dKdgI$[d$[HI$[$[$[d$[/¿l᳔l1l/%[K~Jɖj%[^JlIo$,v)%sRJxʚ>fT+cVS߰n$7G"=MS8鬧'k?G}&馿r endstream endobj 4948 0 obj << /Length 550 /Filter /FlateDecode >> stream xmSˎ0+$1$#8h@Bܰp`~ +8*=SJ]sCM&ESݮ`w z\ħmbo'ޚr028~}uHXz_z.XA_`1o"xR:bct\$7҈٘TmH@ ]W0ywznͩV+1r]oś}X 6g1ͭnm{!^ ' bނP48YhC`୤\UY=0ZĎiơ 7([4r;"A"e"qDgs"2dK$#В%#KDDNs5&]J[/G endstream endobj 4934 0 obj << /Type /ObjStm /N 100 /First 912 /Length 2983 /Filter /FlateDecode >> stream xZَ}W1F0A7- MLh%קؔ(f#6]uN[# b 4 AS7Q-`e 1R4qna@Lg b"f0IB".,dnE\ R<*86 ($HP%&0ÔDGJ$&r5Rr$Q $#cD}p+)4\JFJ[r&/$`R$ U'"!a!&iFJw((rHH=a"% PYV2 X,JkMR/) e"4RHRO(\h]JP0!ψ*X, > +qB!5X@Ֆe CXb2gP A6M,,C Őfmܧ`( !@ 8\[DY,ePe:]J\L ,9ur4B΀ZWGqWN.|M<^G-C#EI. BCBb'-`}!&?n~\t]~Λӟ_u7?oKU{Ys#V?z~;rq.BU?b uD&qsc]^K;u3͓u;?j/!(ظjV'}G1~gįkǧglLo׳b=Wr\svqW_tb/Wÿ^t/5nV`rI? +?x??׃g Ao|;rѓOwxy^n*03Ĉm2^$B^"!Zjvvݴ[M7eg٬MMy۹g1ifs;r6@{U(Ѽv٬B~;־ bZm,y׮ھfqޮrujS.6_d, ީr\ݸ٭׳|Y%:昩oF}ٯ/p(]yU6˫ZW*:>pbvuнm5n~' ۧ8 ;?[t1]wKH]wq[k1m{ ۽obfI7F:@>\4`B*}v[bҐTpb7P8=tjG&P aWjF2m^v{d y:N C[ d+cf †Wgڛ}^M<㜓Ww؉>~c藳f|G+^n9p3V/qtlMsp\nr+/&oEwGtӾm vOwr"l0.CH}y> TwsLp &83$?Cdws Y '0,JIHu1axaG ʉ+.b \E81#Im\IA?ѧуѹqe ؤVb$5#ѡ< V#cQ * 9z0 8])mFLa܎+W(ƒM[Q*=\qǁfNԄWc f33 5W+Eic w=,qW.~6|A~ K{?NcّGN(aW #5_)l@PUleX&2O \x@#ٶG;xH(xzj?'HKBcl 'Cdfd׍ѱ1fKp?`l8Ec`z)όђD@2h uHF-@Ս1R"f96V Z1#%c<#Ucƌ 8scnU7&2cdL&cnlLsX"@ *3& t"@ ,3V"@'tKD2tPuTF*NP%d"@ DL:"#@Q'@d" Q"@$x JD3DuXF/N%X" `DK:4#Z'f4@Z"$H@KD@]i&c[I23.Ғ&o&%M[WLxKd47In]q3-mۺfb[$ǘIf*lIc6ؒ&yk&%mMZWLXKd45Ij]Q3A-iӺfbZ$u%̈́IF*hIC4В~&g&%LibJou5~*iKSD!go~3.-VB;?[P~rztnV7v}'_"YQ?dz9Ge7;Om̮s*~. (?g9 kcř`Zo"KKRr $e0'9粠)sH`H* J?g9L#fp|:>a:i-3|L#y |"wAu߸Q endstream endobj 4960 0 obj << /Type /ObjStm /N 100 /First 1042 /Length 4915 /Filter /FlateDecode >> stream xڝ\][}ׯc&7JJ]ժXR䁚H\p[~K4I\Vi|@A_BYM+_Y3߯b#W~H+cʸ !%M "Ivḙ씸W:nKZWX{+ZMS⧼92TVntiL!e2!OnRA)uo IL]5Kd@VVN*[=#(vrŭDD9za%cE%P/x*LyiZDӓYi*doFOn=)')$~"o0Dp'=UaWd?Y %dl ydMz$L!sOcrxzuy*cGSXa߻ȟ4 &4#m&Dڈ1c 6H,Ǐ -iAJlȬ͒6saI-[j%mrgTd\͑6W,##'}HHK=h5̃#m>VAB#i VS$m亞4qDȼ__Oڢ-eH[<&ObΨ@=iaHl%3)q$MACf3i4ae@hp4xLKLuLѼo__9n_3nhfVgY$YvRXF̴ mefio/~v=Js:݄>ӰH ,, Y,Q2KLFAc$t2Agp?7MHoЅ[oy)ʘo>@,B0fB7ނ ނ72 e " / x <(CL̝ s}Rq3 [( "&X"̣M8ܬyGGD-aIl1O{a)jZn:"[" w?6k?S{*4ʞhW*++ }9n&d3of>STj.@ 7wvν69k٩-vL]*bz}67}{JiB[hMdM.H."7*ׇuċsEw'Q7j+3GAn5wϏ;nLJ^Djhoo6}|fwaک&j֢&*a.2^Cmo6UHNIQYtvG, 1 ]ϴHp`Io?(}ޝ3/PYYk"M ʰ` nÁ>=wȂx8+L~P `*Jݶ9~(B I[E؍~ٷw4S =6XiVYL%Y n] , Sȹ ~|N}3^rL=rbO;޺(eh)<'K6w mnĵi?n?Q!Eus}a1LVnaC/5I H^?lXuk Q zqS?(C(:fAZ̞+Tթ+_ַ? wSV[ҧ۟xo6Xfc#֎)ݲ4.F{94BzF5mfiqDը'Ϳl?׻,/W^2J^jҧcI:gOکbvq78 5bac}7׾?^? a۬këWt}_o*N-doi{֞bwӚ̚f דO#ku|.MO=:bK4'3ؒȹLN~ε861($Z8ŖjNdr)OFaCӹ[Am 8(j}49Ѫfr5YLZ}hJ+vq|ԩ9L.#Gק4Z2Z̈*%1=9ɉ3tsK6`d ./:rႄ*Po~jf/l`Ox..Rx.6E+7nIrKR F&,*}/u1iWt}BE\~6F!^aб^^г>nar Aps#o p#PAopA#O$H\rr\rzL =T)/n?p $FB| 1*_NHn|ĸ,yqQoR ޯQ0犌z+k9^n0,n?ֻ%z Lt-l6BldFEwu^j\WMVN~ 7[`q.)5q8+0@&,{@j8[1fEbssJBZ0B,-ΘY=,Θ-F^Xi3);SO)x}7øKf0*AY2Ţ^X8˂b sX#Vj`]\5X0Ϙ8c=\PQg~=igr=EzSCФ)jy\Ǥy9,M 'vPȤ 1=/L՘ůLu/LzmLy~jd(W3_Bfȕsdc\>,j22kr5n]dms_-Z>*ZS|U%3fEs5#8/jRD}D`r#i{e|[/+gE_sY>+ZgTۏw3g4rĜk):;j>9ۏ3&u8Ǘ3WJ^-8>M /.좒\.#`G6XKfp$â,_PIn?i.M( endstream endobj 5135 0 obj << /Producer (pdfTeX-1.40.26) /Author(\376\377\000R\000\040\000S\000p\000e\000c\000i\000a\000l\000\040\000I\000n\000t\000e\000r\000e\000s\000t\000\040\000G\000r\000o\000u\000p\000\040\000o\000n\000\040\000D\000a\000t\000a\000b\000a\000s\000e\000s\000\040\000\050\000R\000-\000S\000I\000G\000-\000D\000B\000\051\000;\000\040\000H\000a\000d\000l\000e\000y\000\040\000W\000i\000c\000k\000h\000a\000m\000;\000\040\000K\000i\000r\000i\000l\000l\000\040\000M\000\374\000l\000l\000e\000r)/Title(\376\377\000D\000B\000I\000:\000\040\000R\000\040\000D\000a\000t\000a\000b\000a\000s\000e\000\040\000I\000n\000t\000e\000r\000f\000a\000c\000e)/Subject()/Creator(LaTeX with hyperref)/Keywords() /CreationDate (D:20240602222556+02'00') /ModDate (D:20240602222556+02'00') /Trapped /False /PTEX.Fullbanner (This is pdfTeX, Version 3.141592653-2.6-1.40.26 (TeX Live 2024) kpathsea version 6.4.0) >> endobj 5061 0 obj << /Type /ObjStm /N 74 /First 745 /Length 2744 /Filter /FlateDecode >> stream xڥZ]kI}ϯƭ`X~ e<+W!}OwaؗP9*Uۖ%D"6(HAMii#= F"bƉ6Dmt%啎Hٰ2u[mNQMu[x[t,VE 5_S)͟[OHmCE9U TK5Oڪ (מ[TtR|eue[OtUm.%ٞ:,%,ӫkms52X42zEҲDXVMZJ<&6j]Zz|H\8qWIҒx6qfӏ('A%E_G5 Yޝг_^} ] !i`\xv|^g]<ݔ$Fk+.93sٹ|NZ'}e(\nx(QpB[xޥ`~qhZ+ pΎw- ;2Ƅ: 4@Qv8+^38kW> ZB'h$$F&F#\@lœv2&$k.mvͮ5#cXg 3×C8|4#o'TFm k=aB"A,+ARXG)9R\<zŒi>xqh&J]ixTrD:!W&$i>2hUqjsH5nj]_xg 34 \sLm4gJˎCZqLH*0!Lsyk#8CiW'V.&Lht9ۿv\08M<ɓýN}Z~t\ jϠ.u@f:ۺx H1϶{0`4぀ j'!,*.XЬcjSqqtw8΀T.&hl5kpRQ.ޤ?r&$k/jv;>w|57{0QLs5|@k>p jq&bW3.93z3zCQKк>;eU){kk^Döâ8lNqœU"g=[O0 \y atV|+597;ί:; &\Y:³;Sk@yg[ƴjαa:!8qbj&^o}Yj&% ĺLd(8Fֻ֑xmqk.ΣKzz0u7P \Y;)pQdͤ'k%&-|K::>V ͘k!_nek Tph@nFK&X0 <0FB8D2E0920F66A1BFC3F10D6661911B>] /Length 11668 /Filter /FlateDecode >> stream xy~ygI}9v}='Xi[[T6 ZSTKT (B`FT* \,(Mfufy2|X$?> K729̈́s9ͤ{طne޺BV:v߱7nfdXc\-kfzr3+k;K7%'8 ѱI6ώu9-ձ=us8cv# wrc<,GfǺkueq {ͼ?-7OI.;vSrzvpuc<'ֱkn^sU]u\vcW E.>3ov,|X7E7}G(/黎nlH&od w7<Y7L0sՀԱc ܱ0\KI7`vXxPϦ=U f8!fgJjNY~۱DV8Wg}tc"%¹S|volNq>wcjd,qct9139pf'dy8 '>7샕s̹0pfV89d`8es4l]xrb6&o5|$|#NqvtnCឆo!|oFxx<T[Ԏpׂt,;xisxHy;"w=]g5r'%47<gL g)4pn t'i:p 'S61i55p2 < BO'2D;p <5O'i0Ơ('Cf?OϾ˒nzr;.=}3.3O-+'rչrT;aw'aI'Mg{UR8rSG9 HI2_ .iBbY#Dsٟ %BVJ7V.EsWO7ؽ7R>bd%\'elMY!9,du4&e][> Op_noyHޓ@rLNhЯ{\rKc匜sr^.E$\kr])ܑrOy(CA©3Â|-=$Jܖ;򭼓FfOx^=Hy*乼J^(x)iBT1MT1MT1MT_____Y!%#%SW1uSW1uSW1uSW1uSW1uSW1uFsm{++++++++++G9|, I1?UKżTWWWWWWTEst++++++wT vxVVVVVVVJ存 ^|_ wTA-v8ƼǼǼǼǼ~dcc /&1ܯ5@@tP?_]Z#3=s3=s3=s3=s3=s3=':aaaokgzgzgz9{9虃9虃9虃9虃9虃99{t C0 C0 CtttDsc#3*=3*= ~6=#9$H~cKe$$h7qbd$8Z}"+ke7HxqxmlSvn#{erPNI(Zq-|G刄 rF99/\rM )ܑrOy(^$??؜׳RY& dh2,R2JVZY'elMYV&v!;e=W~ na#8#y) 9)䴜rN΋W\KrYU&x--wܓR^sIF_>GXIxgxNo坼Q>g)z_ttt7!$ŨtqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwqwO)o~~~7OKKKKKKKKKK{6ƅIwwwwwwwwwu vGѯ\ twwwÛk^c>a|/}!kh&k"&KKKKKKK M{ݯPG󉻾LLLLLLLLLLLLLLLLLLLOOOOOZZ. IxY;qNL$_a =L L SƄԄd6 y?|R'LPPPPPPPPP|D2/ D2IH,IIIZ Y)*Y-$𼎢PV:Y/dlͲEo!|n#{erPa9"G%,9!a)7dg4KZ^sbQrE;!ܒr+<#y,O33x1*d^d,:-g%#%#%#%#%#%#%#%#%#a #E߇--------------- - -ƍ-- l}Il}Il}Il}IlaG<0 hυ||||SS#######F#Fy95r^######################3JG? g(22y7?????"8:χgF`D%GGGGGGGGGGGGGGGGGGGGGGG_-HeARY& %ݏOKIZ YOVz el-b oF)d쑽O9(kn㒓$&eM4 )rJN9+\rCn--wܓEƏݰ3 y)aMky#o%,{'|OYEJDSX¼ͼͼͼͼ,7=K"ېېېې+%#dmmmmmmmmm8߄Ƽͼͼͼͼͼ׿ay&666666ho>)66v|ۧQm ·ͷm,WĨJyyyyyyyy^^hL42ms6~;,"'&&&&~(ymmmmz$|ɯI$ Kd,Ēe00#du^6F$elmlS1 h_pw+''+$/9!'唜3rVy \+rUu!7ܖ;rWIX-@#y#H4@Z%d^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^b^ķķķdii..%%o}S29%%])lz wyyyyyyyyyyyyyyyyyҩhaXFdJFdJFdJKKKKKKLI)]]]] azX[%%cwc y<|lJP11111111111q}- .vg?????Kqqqei?F;F;=-:>a11111111111111111qؼs!Z8—??????6HcOcs06cs06cccccc㯖fI$ Kd,beUZHV:Y/dlͲE6F)A}P>ݲG>/rD19.9K!ZxW ug䬜rA.%,]*ܐLOF ' ݑrOy(a)\x\^Ky%%I>[Vމ%öbb/bc{s ZeZ Oonj@@@@@@@@@@@˷2-#2-#2-#bbbbbbbbZ-{oZFeZFeZFeZFuBioooooooooooooooM>amz$DLNLN@@+iOl ~Ǽżżż|:-Ň~jN))))߷-eSSSSSSSSSlcOOOOOqOqOqOqOqOqOqOqOqOqOqONNNME \j||bZSoy yrvz:Z OOO SSSSSSSSSSSSSӰq4Hc{vz)ZS+qSӰfH 3J؎0KgRXY~UZ W~"A\n/?$e|#e][znr@!9,aQ 㒓&Nߝ3rVI-vA.%,W\Hf֝ --w',E"%gHeARY& %))IrY!+%#du^6F$elmlSvn#{erPa9"G '䤜rF99/\rE5.7ܒrG=//rD19.9KANI9%匜sr^.E$\kr]nM%ܕ{r_Cy$g)) y6z9|̹@rDk\W71ĺwsNK\ 9(ȹPrQr.>]\:yw.G9W_ιXs.s \R-j9YY6s鵜\-g7ys."B2J^k%s?{/.sy䜋\8˹/Ryyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy慰yyyyyyyyyyyyy!\1yyyyyyy!\yyyyyyyy!\0yyyyyy!g^v a^`^`^`^`^`^'%ђ?Wg޿th.Zz߆cZW,+%\cZ(FK %ZꟅ*EKBҫwÛsѲ׿1B?t;k>Z? -g/r?˝,mG>ߞكsۃs;\݃sۃs;\<\[mҷIgA,"""""""""""""""""""""""";*行/:ŋNS/:ŋNS/:ŋNS/:ŋNS/:ŋNS/:ŋNS/:ŋNS/:ŋNS/:ŋNS/:ŋNS/:ŋh0fh&fh{3}]g?f]0zx̺N`uuf]'0:Y ̺N`uuf]'0:Y ̺N`օ. ua fÅ]@0"Y̺`E.uf]0"Y̺`Eul?pf]0"Y̺`=u%+f] 0JYW̺`֕u%+f] 0JYW̺`֕݋9{Pi/ endstream endobj startxref 427362 %%EOF DBI/build/stage23.rdb0000644000176200001440000106365314627152521013733 0ustar liggesusers |}&$@HHA@M$x*QHV 3b"" U:\:lْYU%˒lG[/nޙٙggfwvzzzww?̗LߑMd&{߻74Mk֭]5%s[cP55:mSmoeu/ϙ =fyNkںnN?b7޺_eMf&B ?)>E,WXY30i[WT_9]rҖ=W6Lg7^-o& o,F[O mn/rCwnߛz#iѯf#%q+5={13}c6kNgUR_5s  w,dӦ덥[:>}>~j~o/<=rbpߜ=vl_ȝ6WټMN?q'N8=vHYT!^ZfJ771Ǥs'!? ۢ(RLը=:}5`oVUt3`ː1Tcon-Bn1UXH `9e{ 6Z&UaCOa&T|#cuzD0G0^˷\g Fah'[n߈$< B5=cV~VүLZM# Zeg#.nRMɬ i*֗1j inE]+t/do(@m7p"y&kOǨV!邵Swf RcX7<5kO^/Je[kN"8 6Op¾)eV6 FN.Zk4MC-Zz2^+5Q.>bT ]3G[PoKr? ilF (uX,"_Y D05ܟ7zjaփ*x[znͩiV2] U 왚Tț\ƾ}r}'a_WR>0Ac؏Qvza-o; A:oc1d =5oF7]]˞ӗ,^Z)o?r֯\yxӮJ_o΍T"JcqsJO(eqA;}i3vg Vw)9 "taw'W 6 m 2y-_7nQ?pln;vr*-OIkM [帡JmcETO9 9:FIZL>]֟,21 QYQ};0*/5o.޿$C0R/KVDz3px 3 I@~3o(1UUC-lX7aJ N luUK,k6>\"``U Nl߄4s֢i닦;k°.l0; $״+>*cbm&pr7pPͧ:r<[f?n'Y(za`W)!720n`7$6'iHk3>\F#YzRZ+ nUV5 ͸3>>}5>p֥ܫ:n02ݔE-c+&q<\N$'_$Mc'R T1kGGyAsgM7 W0~3HzkV;iOfGj.QG? it#b7vq-j*6o=_5uV.]ʚuOTtl^wA:{a #A1U.0? Eo4cs J6wkT}thi#⻉+Ug z"%[hN<T \""k-KY%ӇJvsKd%׵RttP ˸P 3(zEYc}BOk=Fi7Ag;a߅rA7g>7Sy @Vh`b#0GGM ?cETԙ^vI34wSND&Mh[%Q1ECJj^2w-wE8{LNR6u zdL7mx..QȎ< ѸƠFuBQr x$i{ ?qr ֽZ:ݵ'vw~'}k$ [o)/N B}Vn=;=+tnay\5`Xu+n,zzPÏ)kf}(yabKrx2ZJ`X} Vb1`-ƪ r7t6nJ,w!~-(QS4UOʹ\O3pllȕܭn]:cf=u {\qjܟVPDt76a[^x>Oc3\sGò==o {o@wg4 rYQM52~qE"K]NBz*xSLT7;c+ !2GelYA;Fr ӵVF$r 3j]LT-Z!{br,}gM=M8 IW+pX%Sa j%'` /}1 lqWGҲ^t'x"g`Q=ː μ] GrN`qh&Zo5ܺȫd:l[5 7$K U [(TDwC<1k m4^Whcx 8LiIăܗUcU-ĥ v Pv;¥;=Z\q?+2{T D"SO%MӰ'6e\+#{ώ\ކ};̹N{v.-oIi F+9T>j(Clݪ,ߟ~pW.Dry_$-7& &AAhW^F`נFBY M@u-t7]HBuwwo a:F~mEg< Kg I@⩱{93ee!p*MMvĐl.$qȬ${p}O)WSsyqaYܤkҶ?U=.]By>ހyK͝p"d`T w{T>l5Oy:VeKYɷxZIy|^ʖp' <<7LJE WxTxon:)*,&'L8{\~4!K !T7NjdKwY{\a'_1NV:K4V9A8nz4~ N{(ggiF%B3E(=mtVQ; [8:I2/^ j=$wkKǒܷʒW`Hd'ZobP?ѪJՏ6}ߜ372k|E3iR -VTYk.;`^n7 l6$HAM CR^ECo gFQib0QBe*-`ˢNPHĸ?R ƲN't(\P,2< [lPeVvI78E/)qԣ{}z:HnG/JAkyAyI!) [a~B:KÒkh:H4MÛpј3,x7* vod:GēpśT8L@f_9͛<2O_' v1zQwU Fdcgg.elo^Vʂa.iz"z,E#.T l]uf6zŒ-7}CoE%õE6Q9H/ʺ\f]<_w2k,HvҔLyЧ9w=CZXͅKWiAӣqΙ*.;S|h4uf'&x h٪*+B҂{` UWxnx^rp֡pIo@l-y:K2DKfh,7ެN\w[U 6`ljL`'l>P[c \Z[FGOEGu>=[|bks$TYwe2ZF"Qa /ByӵN~US'3oUEtFa}UEOx_USN!Bu%9,o,x}O _>'P}{So|޲Ml` |eܵa] ⑤q5i3Òئ>;I .ᒍ/$B&.Z ?ip!l.tB\{դ`L.c?Pr] nSVݬV> Zo`O4>QMji='Nt< -Z^>y%<[3*? 1IN??_wu)$*-ԾoC[aJ@蟴G+< QG^ZbBccx  -7LsihP$_l-Nc[˾rи_PLh|BL/2xVZE /Ծ!wwuKZJQ&]oKa.m[t獠? ľ `hR|XOe[[ij8. vpsW,x"!TWEqI;LY 2a&aW&ңZ\1+~yor|'@nP?4Su`vD(xy#Pr iR 7O30$zvM]pD vV*>L-14pgf 'Q5פuNSs6FМYsvЪDb!:]}cS;UR"/; X,x8qin}&w[aoΔ/{9r\p 48g=3QuLx6~"Tq4i-g]q}?* lsUŇppUQ\=*]xg ֩ @AeӋҩZIU1QTq/Z:,o-j)<`7AVp0L?O|hHIs?htNzpH?7=?Ʃk(2XeMo*Ûċ~ecL0byg5Ldj|A<<[?;g/GA"'&"']诺*o!>,M{O5 ߌ/XZ%FشbOvEo۷b82,8vמbynWV~rHUjݰWpEb-ݏ#ģ, ̩kOk70("Nu-ZQ|vmʥ˅9Ӧh,ބK7]}u#UjF7hCoh(*r @m1o"+5S~ay4TG{I3uy~ [{u|>D(\zJC!C/^d}Hƚ!O½*iKIoA]:v| -]@{[P%a:(`TBE*߆4[K"mH:WD@&X6IXϊkW6Q7/xk߁$ ;`w^IvVp_D`'K8'߁$ a+hEIw//&l '߅(Ӣ B ]4BV .r[K$ZB a@P@7g>7SB;P$;jοEveI:;a,UwH. J':7Pp~0*-{"ä߃*OKt{Piu&0aA&^`VaҖuӿ蔝q8>I`P$a]x" L}(M<֮o y7o˜~IPKtCHZ?,%:!$CB)2`h@iNI O]i@)dhm;[!DI$Bud"'$$ti{hd4'?" IX(&#(=P ]4>oXnJkV QV+,C|c'֮lz;:IO?O:ς 'ZUVY?2 Z͂BaL^Q Tz+GP叒U菠Y?*TSבx%aBչS?mSVFM6NПA-ڵ**3(ϐ:©#R"5>IXX4N$مO$ [rI}.`7lkUwIBugIwzWVF"a9hjbUD#qGRD(C:l"%{D, {P%aUuDv-=% *3Ȫ߇& l>4IXftl>467|A"_@%Zy" L P̓=5HoR02N ]&u/˿u/QHRKt_Bw_V˭#ҳ +-h m&MAV "LtW&l9})%v\@ NK=&8} JzNߓ`M5Z eV{"ԵĦ$T7}3GSQ'Q* RZ^:;*Ǹ(?<4=Dm:FV8qg?B!qhat^['}т_i#:;|߂=(j6;͚~f>iGfO}n7fK?gSCJ>X1_\K3^J|+ YW` %Xc F ٺӂ;i+*H n8;^~(m>7/4-wxسA _\_%+73T1/39TΕ̊יִ2޲3]3(Ċmw0F<+aƷYeIt*heWO!#k<*ө(jYCm.fIw M;%EnKʻloAƼ۠L٩Z^]^ʵfWoq3U3/[V>x/W-)V3_x`]cռ i(zZ)H~YUōe/T|9ɻ*+teWM̔eYR^^X{+ZriU&9$weM .}Gt* _vZmyj./9nZ,j&a]V+cK:_cE[XތuJre_s ly}~fV e.Zw% {wUYUڟ)\[[s+k G R羹\8aLH= Z+lTW\iS-BJ{|;!ԛtÞ[}z' }H/"bv8cGZwW<mt7C*k.ӟWͅ ÆXwnߛz#bSñ֬kc?ƦG3F%o]8y|lڌnơ7\sl:=3Ǽe/hFosr4!cAe,-?w>?d?Y~̷9|1u8o?6/N+taSO=y']4U` Wʊ|.i!yΖ 1>{rgzpHEu@fga3W^x¢Jq|yѝ/A?4x'?#;{NP޺35QV_s&0}/z+i$I,k/O_`Up~yyccۣ#A*QǝC94r߻+c&3ěo*y堣^/FݕSANު oBxaVaF)|??sb8z2kb[ߒM3ABVz #]~n+v޻<=u[jB pH ]OtEtU$y$F ߾oL8{FI}K{@%pV-f`_8o(/BBT؇7'LN+ˆ\I?48c{五x7ʹf.Pê/lYqx~Xi}vYws}tBO;fV7ުyAxP+WSX|0ajcE6S.-BS~0'gbkwᙑ:N*3O=2R)K̨Fӑ܏3G=LN_oF"pUVt Ur &w-L*]}2!ģ({Flt\wt#\ϸ΂nze绦I}=r8 s}"#'#s /J ȂH&ˡjupİ>::}k#2C  Sj R&-Q6HYT##p2kFJm~f![/|Z[`oQVgl18{PY*[B8{H`ԝ0`ݰnxkyǃ'Va_ʶ*'kׇ8 bopcwo.6Mh nvh+^ˍ*L*L 0Ac؏Qv ל`/kylD&x֨Ȍ%ny5RԄeK?AN+nc(޴ke,כs:'HXsJO(eq1:}i3vg Vwos %`M;4O+'S늺3*!~kHr$Mc'R TkGGyA3~1BjzEw;@zΠȾz+Q!OfGj.QG? Eo_bMxxku ĈG4Cl72(UR^a$(]隌Z5Y 瑢m[nfn_DIB^./HVyU̦0ʏ qAj *z-7X|WVJ70(WHZ4 V\@_.j}8`AʘTuGlp}+o,< sSRU_zպ 4rxzq=Q&oB7䁷2dU_UVVt|KIaEO˰YZRY4SJw?yGO߇ *:^!&?`O41iѮON&N{D-R ]irO:c ᇫ^ּ鳦ioйy^e[xmiդsX }2ZaڽVczJnm+ -t/oQH:7aߔuކ-_P63F>.o9cC0rZRs1"wxJ)RĶLP > <[h!/o9_bv[PR[M#5S޲e1ҬZLF f~&Vحw9ۥV2N`}86ri]; p8[<[htQ֔0JQ@\FþnBvP@jx, :L7oO uţ +wM}!('E-4: mM1 "k#p=FTӋ=<(h2 ]8hKQo:'1JKtUJrU+lU'L7v_ar֥3nE1f8hz h6)meKyh^6`=ny1¬||ڰuu3\sFԼaϙina莰uj+Q_7:|`ޑFe:QP&=.MA1z8;Pq&xҵ4x tqq0"dI[ketN"L56ġxPUbl j]u-HgIwPlgM=:)3~'2]NZb8 [&0_> VDC}1 lHVGҲ^t'xi~$_;(苦nlo*#Tï Գ3r2,^VzJ]^U,E뇠GȜM+-CzƠO9gf BN=\jzCij!ӑȠϬs vP6i:G`Q8YejSHZsplX㰵GaM%X|0Ƴ%(\}?r\+(=o1 [(4G~%6mb?6f{RQJTUmlvy] |_L.cmHT<=Һ`0j;2~0:2~8Ĩv1#ȇ9ڒTe. UVFuc_ P]e[2ʲM#\?+6҉Cgު>^-i"'`Jx7ra0֗"_>H ,Aܾ7F[櫖mb [+ [( b$I{+舯4=6ټnM:hVvYE| P!sA -;P-4v4mqUN^ KORs`=Tm5*m۔U7s\7 Xur iQMji='Etgm< }-Y^>l I'`czA) 6 |WU$~Qin}r U:O>*?&<>*Mzxij,[x$+jMˍ܇!h9 قӢ@1&-Rrи_msU~hsBLg -͹fΟ^A#r7 t.vKm;r ]ynmnkm &݁!gW BunɈ_1iE"a 56DGa%`?}&wJ {" uFӎ=?A^`>}O?*Q!J=g5r: % I"R :\/)!2(^^C\[k_!JgJ_qT`c*ȵ`I<0q3MI:/c8lq2EnZ iqӦ[κy}?{Hxq'}QrT.7o,侁:D (TQ6(䧴bVFtgy5oQ| O߻{#j;Cʯۆ4 鴚?8gӋKszCa|yɹVPq̈́ KCAMdeKT7>"C4m :7x$cH8rl숞V&&"'`h<_uY*@}X WoP\ dKa?0)alJG&Nq xƴb,8vמby`N}da+[?9$U}^:nBi#1k_ QqTiRkG70(ޑR 짴h+F/Ӿ+..$LΦ{:// `Is%tGRY㽃觵hOh(*c @^O#+f?m^"h" ~b -b g n7f.n vOJ{}+Ut9)~b "Tz+PU/Y_*XSK%HKآ̾Li~ (<2%:pl6O_4 aAW+\ӮXMH9Zg!IB' $g!In Zny]@FdUynf'J8DsȜM0 @9QT9(;Z"a{9c0J{U)={W=m_C;`悔:$-Tk˪twVY:H. J':7Pp~0*-{"ä_*AKt P/hu&0a/@&^`VaҖuӿ蔝q8"I`P$a]x" LE(M<֮o y7o˜I~EKtH+Z_,%: $@)2U "Z4UHFᴑ(J b4U蒰XON_JM$ӔGnYJ J'~ $$&8K%a='LSC#k92I`Hº@@'0/C쁒n`zAykt .A_>Q~Ms5dsO_( Y}`ϖH?*?P,PZBj$j:Uסʯ'ЯC_BU~=Y~zu5U(pW߀( lQ~Cs# oh6߀(շ 7Z6m6~PlԮTQ@iNI>I,WLz'ofq&4I(uM> M-v[>@ʵ*&4I8>nRSd[ES"oAB4 'H@/P3'oA:l"%{k1Z6E U&8ZU%" hWJz/P~T3ϴ"߆& l Mֵ']oC̓6}4ah3kiun@/0f LB]_3Ok̷F"I8I~$Lpwhu:hnt[G2[GgDDž睾 m~WK4wjdu]dTe§B{tJާ\ӳqA N$8}O N$=t(P.C%:}Pku'}@]KlסLBuܱ}?x=-5鞷  /@}>~j~o/<=rbpߜ=vl_ȝ6WټMN?q'N8<[#s4΍qB\M!7k)Ijx~ g]rPڎN8[L[>}0o67^}[TP=X qVjFpqg?l\Q:A bsLH„t0-bCBEPfGCM6g/Yv_xvr(bE}_Q\P0'sOO5 όvRay#l,[;rb$ΆG?t/AxNOrA<4*DK8բ'f؛E8U:\v 0nZrA``{Q:U1Lt7 (QU]jmUyly2j1^ؽ V3*FjV8e70Glm#H^R߂,k#'Z[F+A|l?e\gA>\q"7Euh}FY)NS;t_}?,emT &ģlRfUf}.7IciDw8 {T_-4+](SaRC*bpxem/?%Ї'ܶIk(<|2\(-ay|T~[=dY0l+F LS˚ \zoE w}1crCwJ9΅0E1gQ1ǔpީʸP9" ʍҡHb -^~~dkm3y;P{ѐn l*ݴ{z!%ؗ5Rχ_:!\Kҵ'N[ݰkr .iPGy%CTva+|x$tR!Z+|b$cIܭ;qžMu(Px BDZ+r;0;UG6Ӱuhɿ H^DQn.07162fj95Gݑ5;sc[xco̙(̀<{\855YWP}**]g2\ޭT_K Kݶ/KKjŸ4SJw?y4p=Wׁ:W֫&l>~Wē4Hon-9d d2Ìny:[ gSO)˻ E\s˰6WɳEӝ4 lŵ$1 ʂѻ˪ad SaN+, ߚ͚ :gf l lu[Vͬ!Y![vI%ؗeϋo{[5o~+< |! x$il/#Qn(P$9֊kݚ`>~?BjU; AĨT: yTg"lI^ʵQ=H2F(.0DA<},ZnbgmQXB+{=4?,&{t);{\q@YAPX78[*y3(2*oq2t+ǐǴ0n҈N+vG훴cPa'lK&NnBg_j0 N1cN0ҹ\ADh-4*!t[*V&cAEw%R ]rf.1٘vt nFFD pdG$s9pWIB%ysHN6& ?hum?1kܭ΢(4rb{4Β$\6s̘3ג $.ٶլROFLkeGQ^s*iF x*i]#p& 9dz3AkЦ;n:]2r93ec!{k}^YmiqCʼpG]ބ}S: &ʼn-4ie8=JEǰ'+O`?I~GaORu(Cc] {pVģPWٓF`VH27*W޲s:GxQeisw /Լ&!oǀa_ON.VNjts%~1gOR+Q6X2T[(KU[h2/ހn$ބ-?-2b(fa?OF'-ؖ2Ѿ\h~OZ 2O43@\xMGv9={nl!fSv"o}!CJ bPoDaK gXxN>e2V [ƈ!}5=O_vaz;EU ф9iྻ>Dдyc aq|rg_55짧ֳ݀GI0lL/Dd-o^|„rVӳ#U | TMo.Vsa gi l` #c؏ylguI!J &؛J֜m9؟F"mdJW+BU7n> N ~2k–6=lv?:yn!\ʷSS&kQѪS7\Bu˫&7l-@8j>VE ݯI_l} k-vft0n0,FTYaUʥ+'7hkaey9aU [>vJ} Norh #GWѢs2Uد&S; Ε TǁVnPb&wʉM8nFT>WNԞ`/%כ+'n^˯VxhT}M>yI0Deu+S _I]vT>B-?S1f Շ>|E4ZģLUM֥>&mO( a ,ϗ!;={3d߰6s0k$W8]^%ؗ?9Du=㶒qFMue'_ݱ nGaOc22=$ʭj߳ w֌DU(ؿvI\NKT/mض4p6SFw8*3!'pIXY' nT^8{(H'({Bm־"wCn7/IޣT ͙QS cWUH*w~$ͻs]s!PE wܾ_ K3]'dFCp}2x^7!|+;gAef&xԭt4e8"nx_RQJ["S`Hܼ'mgwp)~\+vftol1m²=OӢQ$Qp/$?}5 $.22:I܃kO)Dk*V*(@ńiB{1QDm-'(Q=bDm d:2;5הPl ~X1[/=#o gVz|;(G'<Іm+,pr2R)H!nW^ڊj~wxYu>(lv/w/T"E/Ö_Uaw D(7!~z TE79!E0K~l"FxSS}0E4#c>C &~KYO F."wM+r1G.';I-Vc‘>yKЧݖv&XgrqxVmNµ_n-Tr =)Z0"&lSYHD֢E` u+z@F'ݰKv2vorO _@F?l͉Wa {篬eĉ*l{_>|["Az܍'P9E+:'Nr% E3's ʤjN { [h*^)"?>JEǥ2 F+xIJr ֺĠ 22" 2"w;=KȈ(/i2l!y nb n{~1B!-,sޝBg+r8Mf [:!!HހEQ]Zq|_rTGK#>4j3Ҟ$rӛD&bMr |Oo͟JQ\ )%|)Oo~_ӛD(crz47 $w=I &&q{ 9Ilo՞ޤ_L&$218QqWE$ N'}x%j7᥿X"^:F%@9M7S_kMjѰp$OȳC6~$?Nyy49 K晊5ݽ4%ALgKpj3yV:j&*ٗA lkvx Ff:6-3]?\'pd4}APn;9顀W0/ 0cv;x_IC#:WpdM)WQi*/>;JƀꎡD"o߄4}C]yQjN^6m}AB+r$&6)Zϰ$Q; [hc >؎=%Q~XnQ״#W75G<*5>z#%pMRr⋄ #wM11r߀r  nE[t^<(}!=LuN~Bs 8[RmZ5ZA9byRbl*+Zt.v3rJ.].]bb-5*!ÖoEZ~ _DA<ʤ]\ܪ%1h -.`-`R$KZ--uJ:BCU`Βw1#p++<Po}r}㰅I૰Nk;;WnfMli.>->"B>NTNBݗ\}]$.GK!4)K{H~NCmZbD]3>$J O?D=*E!/&pH7@<$ E%ZGCDu8<$JL( !Qb0 D[!Qb{(u`DE(!GE"#2lC_<o`$X x@ b!іkT%'բ"al9#] I:2+:xG8 /3}N{zN+hr [~g-Z%dU <[~GmC>mے/_?T@)6*N2/??TI '?x}Mal)Ӿ[y|% 1&- gy#gM{ΟN?Bń9S~>?RSvӇn̾#@Q.SOpNA}A#]#ʉ@Hz`5 Qٞ5us!s8`O9VYWENi6n}'ܭn-v$Chn&,bP{+|?DIVNP+KA5Zڧ=mTO}"+4&5 QuzN i+1].\WXƄa m/] nT>k;mIakPBC aKӧ8 Tz93ee,QnO:o _-i&8%wƷ{i^ɩ5#Fz9\0vÝ3Oh{Q5@_>-Zh/_VҴa -}bK1CT7N1 7ozKr i/1h^ԝILyaXDXS1&bDAPt"| x% 9CkߐCa_/ZoI# og`=P `%YуoDPؖaWeh{`Vݵ}P͛[k'JotUw4 =Ln [(Zyh6ɠ L8r? I{=,F54 >DYg۷'#5*n+Ecy|M`,Ob KIKI [8Ƌmr[~_HK ` k˓]ށ}'$'a +a]wA4iincPN@4a %Δҭ{OO[,5nQ QNH*|d[XVc#HG* RPr32ģzF1~kE[ mnJjD~k_#FB ,Ofv4=lP%7%NWw4-*uxPY6F3 |[h>Qr/ªYhöɢׁlG:Ґg5i!ֱ O˰6M`kx@G`I!2YB]6[W/>ZK`ۆNgP[H&Mo&Wׁo~>m!Qx-$b wVpww[HrwgY!ֱ-ʰ6mDpx2|pz" |_nNVJ!&w3d^h1e(۰o+vbNa ˡ;7`!C:*Mc؏J(2yd pbZB|[Ej i!ֱ%eX9=;=4 HCi& Ho-|iҊ_n-琯ВF!؇պ 08lHԺNvXrxd2<oeJ/0'?r1:Vy֦2ݚ}.; )2 v{` mN`?~%]6QGk䑻f1&ź"8pxV!2Wa_M&_&` 6V:PI۰Jd@5MpMca8ʱ͠/zt{p[wK$l)6G_5o`ORM?Ûk*DוZ4H_ tdt3 RS3/(hU+HxWV"; G]7Ѹ |vjQ/,Ƅ'9 ?WZ:~)UV0 m^ݭxX񶀚D܀j̔XQxlkHJ\I-,ζF69V.k!J勾5[_ΙQuՂnsy_gf`9_d^P<_ |-RV> V) ގleuN95NE4 3? I# jnlvF\&QIJfc}XniRZ l0!s#Xu欔 LP!̍J=\8A1īՍ* * [MRTM`MP&dL&XuJv$_gEIwù03S G 0ghom.Dֳ|#7oz\(Bޅ&WᾹ% vL pj׾5nCq֡:y; V7ql!%opm˞.@`-PқXj2T\])lcb܊⳵ŧŇ G~ـBecHBk5oq8C&q"b-TZ᾵UQܾ7FGHPe[  9 1#[p)BH[ѭRFy(dZ jt+4Vhtk}4uѶRTэi+,` O脄"?ǰQpXt{"[p4^f-:χqb;ʹZ& - ( M'-i>A!{ Q]o dnj8c;q_UY_C"PC?Ηpw6z`(el*o=qZJUBTkAdP-Dd+gU+)ݽS[I&LnQ-m]q`Gd NJWAJAN* ;*W;G#[,ܼd ?VQ)DyY%Gͮ0 E95HNԨZY𼳾ЅN <Ͻ(?u@?*E+t5oȞ9(g~vY!}ŜO/jpH?7=?.}'z/MCܠ; o"B"~D@Y4vlߛ"Yz 3gj'UEI+]6Id{02Cl嶄=={9:<QNLD884O, <_Xvhu^蕮pOt{ R15 r-/(:huH.QQr <^8A M._}Z*=L0-'8eb(]q}~m0_:}U׭?H?(>x)[x[/Շsj̻ S-GG KB(X08C&BTĥj >p>k4Sj!K]CB#337FEu䀎plY QNW뎝zB; 'pb%ZюJP޿GLQ;E@MzoFxo&6~jzLҩ~za>dΒ?$Pi  'Y4G*hCT4>Fp(x*>lq&=;mTՍOqXijgXa<ѝ(h]QAW~pIK37;SCC1 ?p1~qTTmNOOmà}yz {j`X {j`wO-bTZ &Aڅbbf`hBg9#(>_% ̩Ip_hwՒ"J^,Z(t`ߕKSQ#ϙ6E&t^m굑#U[Zthul%Y4U;9F#[aizud P!CȖQ4Z$\Aat^o@PKSCACQ8PPuVP5UfZz);p2|% &pMMFr!+7.5w Q_oF#^^mĬ"'Mㅼm"M"bWIȯMقujιԜoCok||[SgS@oGq'娢ηη5ªS'J5f/;y9hv>gΝϙ(KBL9ֳI{|*}jM.>>J!e5ўJEkGP)tOTJMX[B 99>D !QuU%%O HD"ZE!(kQn>F },[B?Jek'd%}Ro>D$+':K $ݜh1]dJD;(a]'މ d N4w靨 0uu0O:  ;7P8 Q-]ŸܷBZ-,$:չ' (a=[xԵZ-=ߵ9N)(4%:ߔBSZRQ1T7q$IE#IFIzن,MMjZڒA΀i(SBA&܃B-4=W2~Kj{ k^-saAXڞ&XA\] >[[8C 8CZg棒b3V`X6V$^ZZ_Tjiu^"}@]Kl˂J E5]X[x%Lp]H3D`70w!w<l S0ۧP'a]n@'0ۧP'a)"O4H Y:뫻&]hd%frAS1PQlk*mf[&8 z*/OըRp?m&݁6 vhGwMzG';]Zx МGiu gx> ;OOyp')4D'vGYEy3 DůMb:O)Ͻ@1~Ə$hm#,,vZ7H-D qa FR(Є]Zb(Єu]  .o,C\ @죖ң&'N߃: ;:.N`KA]PP N )(Ckyu-Rz~`["s4 - O@uDT&CLp'DdzGoLzN˫s''dپ20'OiQOx6)-y)3Wn;> EY'O#>"ԤUϥO#յuܹD?r؛O QBM2wF2p/2J윜TF}EUũPN >H8}\dSo5LW[ 4F ~=-wc#&/mrt w,dӦ덥[:>}>~j~o/<=rbpߜ=vl_ȝ6WټMN?q'N8<3cA6ݥ4@o!6;d4ON*`guyzmʹA]YEqo߼yVѱJw٧mwWuܿ6r:pÏ˸6(Wq3f#1 a4~L~ ݹ}oꍔ1_rgxaBF4 T+ TcP2V\+j0G|^ۧɚgFL;('QGo,\Rb`K>q$M#Qjt8Q#PIm-#t[hFp OM3]ò2_yU_M6þ.r.`.R|9y1uy[%uyj'jwtw-BJPy=?tM涥i+I\Ќ-uHa8 {N2< r2xfV͑S Bs 9rx܁|NžT#9ʑ+밅*y9|+uʑ)૰_U#ҳj< |a2yuدKInQxci2`H6}zga_\'Z[W& +xaosA<ma 5.w1G7|oki2$ ,ӚthA5Ku/GuhD5SR.Y._xU+ޢCJE:ipdpix/3cO&3CSOI}ךeiJx6Q: |٦Cz&dJ5Pb\ٮu̢Wʮvڡյ ʵMt(0G2U߰r.̊0/QT>/d 3A\ƺi@[t;p]WfW -NtrX\ݱz6x"ŵe}C#)bms8iWJ6D+MA~͌AGn,TrL+&;Q@ M촞<н|*ez^?".Z Y#ԴӞ`3o&]`ߥMvzxȒ UZ2Q4Ob(l1bO?:4ҿ3EMFżOsYϤq|_UET7@Z7ͤxF+\~gjWͬe$(<à0֚5F~'TlE21)~LlJG$kOIU]t ;9AZ)8]bU eIgN֓^{wݩ u*eעi1L]KeE0grWh-PJ6hVpcF`(\D6v{xL/)ػPm)WtRiB sV;1Ds;RNH sV" iIb)RgSzJg N ;J!ɃZAV6Z $yPx@b<YVWHy9An-tO HJthyR'C!MD*8Bou-uӟ3'a(rXKe":P尖hΌڲCk7ӵӦmg9@#Zj%rDx]ZrA@G J !(j+bT>5OV>GHºVD`9 Eֳ$UmAcZ`̵RIثƜJ@PVcJǠLBf1EE}?x*nÙXz:SVپrj hVt+AUc>յD{#+j MDuG1+\521ϑ G~Zr1zv'%~d_ ihb% ~<`778@Gb 8*X!`RCw0XcF[(*z}$r E9Nv{+_FaA<:t.F+TM֌O4PrhwTRb'WÔ-fZk/D("ZlHf/i%A+cģ_,:H='L:4줌ND\s!=9)+\2%S!90$૜?oy9:oNW>n_4t;fu X.麆3Hk4UP'd@9 UB-md n 7'^IZWlL!BҡG`ί&FpL2:YF^p 2>(~,n0V+K]D[!ML壐Y#.Eso)uXB /ŒKAƸۉ>'[S1QM)}Rep=Hʜ0oqrfS7FWsw k_a)l8 0>To(L*}Ar7 f]2.ʥeSQ~^7O2h?Z-e} {9N߃{*OHhځBhBW$۵BZqQR"fSO%S'X` T.iاk_]|8qi KVj^|6{LJYa!}5=O_vaCihܣs(uǍe^lhJu}i%ƢN XRW|9ꈳyF 6 i8iC 1M/Dd-o^c>-T"v췒oM W7a u+9۰߮} HNg` KK΅Gǰd73:"9g?J &؛J֜m9؟F"]|V. T.U 7|Zt*IњfPig󮓟1 C[l:no2<̠Y j>UF-ps`>xܗ 2I@)_[&jG` y݊-x_[qDD< hkr <j #l9=<"8mB@Tmъ!qh+z@Cѫb@ S+- xZ |ot԰>k0LuwRΕWaL,8WNL'`_PR1/[*q|G7` MKϕ;Ԣ7!>WNԞ`/%כ+'畉us*V]2:4E=ߗ1N&TR:ʄxQrl鹬2X=0gJ7z<-saƧ՝B[s*JF+xI{tg {k]cb[Nh{D Cv+Dzeΐ}zp ]r-Y|%wuD{`_Jg<eszm%=<, GM43^fsw,QyXLx`)Yh`_}ςŻ/ S#zU ˺whL^DɾaҔ !6Sѝa=]7Fe&D\4u5cvҳL?5]xd -@S+ƚ j!6ABgj!r <ZR-4gfWۧ80vP{0lұ?5!UDᨔnN(X":!YZ90kYށ}Gef> *G䒴&SM{phq0@^RQJ["!!&2xBKE*!gk,tCqa%ܠu^XGAµ/2`eJƢ5Gk.4POqf(I$sw$lMϾbxq$J) ml,.Pd< ;8[~nWx9KMu?އ}_"QbIQD`>ܠ^+dhXYA([lJ8 k2ၨ5:u8[ ]q(` xUk9rؒYg& /(Zp'&ftp\2mXue-OlKZ' <ui{4+uf.BT[&""N(ÚfL;V;ēt(J 3U%PoK(r4. bOBuS(@W&@4#dCG43'\Nf9H$%TwLhF DPpY૙ }&dhQSQ/uh*L7'xɴdٴLɽT} R xp;_w p'ƿbv$ k$=k/M ߳ +M"P_>|an :ldMoJ3C]yQjN^6~m}A‘Wr$&6)͚7D4>l>؎=2v%#UWP}dļ¯i/i"v sT&~0013L |=L M7I[  C/Wb43$;3AUfs %[ nmq4J9N~Bs 8[RmZ5ZUbyRbE!b;܎^%z!;]Lk4,@y$XyiD_Z fn'u}DkxvpP,"?<[-5 Ak`!δ0ah!bu 8{*f^0]hqǕ1 ;1[csE ;0kEX`MsQ(D@ Nw} *'!K>z꣡D%G!ч M.^G 4)^g=$J?VDp'P!Q6I-Cr%CoD(Du /!ѷ@%<$J?&D pLSyH~!Qr[+}!Qb0 Db!Qby(u`DE(!ѷ"b҇Do N}x%jD/7cN91jD[VBPxhH_HE6ňFxθwY1I\Ji\h 9?9A6g]H/GfmãKKkyc /$RN:XII|KnN"NNB{zn=p'ҙfwaw+˚X[5{석@4gM',IKgO7 lD*/L^}KUfn*[(ܭ_oW K@1 7ܝ'6'Y.}u#bQ'^LY+e3) ( "bD:uEfX'?4$ֲY- u} b׈*$1פ~6K'O礬0Fxyk.ެ$kI>,19`m \ 89 $-p%(ӕKSvyNaqRApl5)&j8;Xn? lXM9OHx^}U*(:ZFx5kw&UF l/.]'`ɏVAV[hOB+{(O`O)q#؏(1m FFH<HLna MexNj~ecLڱ}o>>g`v\5 > !]ʱ#z1~b"ab\p!ny$a؇|Jn+v RW/׏~-,񅩮792!LMfKjA(Pa;lO@`w]gv ,}9[&-]e5inL6`Og h f_\( `wCD *@?Q-TeK {a*h#a> =b?X-ƧBa&-Ti#($;]Lմ)X Ps~rES۴UQAU im:?E~X# 9unTñ:[xV6و/? e$E4TPO"e5ўJCkҟ2 S~lT%T莄, a*џ, w( 쁭VOAQn>IЏ+w֢_,DY~dd% u /TӳS޴ioeN? Q&8%a]'@70(ZDni xϟ"  IX<&8(y `>hߤFEZ-!/junn`-!Kzkj[ {>K%0/A_<%/i7} r{ ɗP@bURPi,R F5{,Yx,?f:l]4WβОע`"ʔPFBS|ePۓ^BUkv-=-uO LpO/@I;5n嗵D Qutj2DIXϩTC+X/L_]E(:{>%P&a=׽?^ _, r dIX)"W KzN9>jAxP$as_" :gK: ~$T7g=' I/!bT:@7yt/[I_ӢKp5:$ہ 's8I;N @zPKtZwM~%CC;?& Z@:Du-ѩC_~$aϽ@0'iQ͢@rni\ii9ĺw@P.xujQ%l[ wk5 s]wk)={5i.V!K'=|I[hERXOұ!~$LpסLºN>%6qP&a='?vǭrUtZ3s]uf 743s]er3G= ?MMe';~3*Y#XFfEь wVW<7Sfίy P"1w(ʠ*G8IrP[Bumw.~(ʥnN!-$sgo#s;'Q~xT*[>9Irw/NAQ8UVtkk@LhoWڣB.ѭ??RPOkr˹bЕ[4ܱM7~wly%g狩si!wڜ_1ƦgV6}:uѓN8qXΌUXɵ%qFqo P\-_ש\.|9(hG'ێi˧捪~o߼yV%1fO`8n.FNGnqw ql$fa|:L!~;McQ?T:^ȈU;=*qEj Uʚ|EqC9= 8*}@24L -[+ ~631iG3GpW/U`V؄EUB1Z!^O*_vBUF6B T#k^kaTƐ Q1!BTNޏs&ot=p} ʷl2C䳊``V5(v1LN,jGGG/pkDFaKVvDZ,yϘ$ߨt( GP,d鄵4xĵUnֺuJ$r -4hfzY0zzut` }׀ Sp>mW.gNxY6* Qֵ|s5s%_Ӑ IF3R Fzw&h8QImԊ՟\ SNh_#p炢b;;iOr.bFxD2G7J;IOթЂ"\GM>mdPYhjQ&pZTYn:wIe `$]Ӎ(E5L^j[*[P놯|Z0]rTONIzC?-4S3<[ll[NKlV-4!-ǀaN&[FǥM|P7mUeUدJ$892R|i!QأҜݟ7yLw觚[aoz`; b-z'^&ݟLt`Hg˾BN9ou\09irM_4q'.P_CQdyzW |"JCXïDkXuU?Ww7꯸3v8o DTo¾)Jy/_ Fr7| [ onA3uiADMZP4jn=P] oT "I*ˤMy5R!1ǒɧ}㰏KӮt첞q\*.ro"vxmiWX)g!p^wD (pO'"=fo~8АFZ{Bٴx(b6m;1ᢴOꇹ' y]wɳq4i<,$#Icwc#(݆:#t([[Fz/#CxRҺl]c1 )S2s̢W-XEr ҶQNR&F<ISf<=ʌҦrY ފ?} F毙9a5دɿ7i}X ʋ/6m_^[xefӞ2ny?L> 1[Hva*fa2tux߄9]}EM#yfփfj${@v_D/\ǨVg!OR*xUg"]U*3J(]&A(50(Wӿx);L,w,$ZjҊN1qn)vDcA?!ͣ=h, .'H!k⢴훻$aR`J$5O '}!CJ b4Omq֗ԼYS򙌕A16||E7R)K8d9cee^C(zAJuN^g_5>k"~ h=[.f"z6FF "7/TaSjUfښ2[v-WMoVw~mo׾$w3l!a?Y-=LLh Xjv.Zs`z1ҋ2ՊPa|l]|!wMZdfmw(A}ϻN~n[Fhx؁CʷSS&{3rjT3̧Q`7bt[ }#$7va+iۀGa}B` *IA݅P\Y;=<[ĉq۰mǴhvscѫ(AWAwպ=W'TWq&5OlaI]5ѩh2GMwM֥>fF6MeG2du̐=oXO`tn(pFiwuD{`_Jg|,Jz1[hԴj♬(2%2YB]x'p/lO xWx &kӽa?He[|خ]ĉi۰Ŷ)YV": ^ma՟5 t;2ŅȌ$X}on`J]ZHM]@ˡU%̢ll* ,9E9Ŕ%"d(69Ql3uI<-ԚV~.sZˑoqYg& /(Zp'&ftp\2mXue-OlKZ' <ui{4+uf.BT[@SE4cb cq&<F޲SS8NxYfyM$ԁ`_J^ h0&vAX/z)`^>2$vxB pØ<'Bw}Ǫei>V)n lM!0l;C("F5Em{|*?} ~ێ=B#'7vp"o""]nBEhm]BOwQ9xKۛPGjJ۵lNgW?x9޻{ 㦣̚?(yÞHҷeJ:I߆N߂ɝ侁: !bN(uc-L#Eqb2ffpY]'uڧ64ҿ3EA &c?s-ͬJCܠݘT7 ?±i&ؾ7_z 3?S;Ye$xA?;!'&"']zEU >\3;F5a׋Rk*H ]q}~n G goTg&_[ɱS6mҼ6 Ͱ")̈́(tHe@P{_F!X)ICRmThvV7YGbȒ4 eIgN4q }mQѡ#M L]9B9}δMJy:/Ȫ]utIҥ-]HV^(Zʐ$Uf5=Қ*` K46j[ a D|X &5sD`;pH[h}XRNl98aC]jP$-"P" XxNUjC</vgXD z$X5ƧMz$[|6`ljOH0.6N`&b67wDA9Lm(EE!$7>uȜV*ULr$]G$:Nm۟AϴDgP3m3d am3m;֮mo]dh t\-ŧRt27YB^{P&{R-J*~x'G$솭rHz%.ӵ%=U* K^ (DP$JGIT"YJԇ,zKԇ,d%C~%C~M%9=;MFbq2C;a.Th$삭`/P" / 4QQ&h}`I`/l)xE(0"IX<&8_" 9' nMYNK咖h Y.iunn`-dIXuV-| $zϧEC 7=*kuoz"\Kt9T\S9Ľ9 HWpnR< K/봧g9*W#XBKfm4Ӣ=AM@vU<rg{( 1jNW>^[&}т_in ݺGM}唿=sE7 w,]6~wly%g狩si!wڜ_1ƦgV6}:uѓN8qXP& {<CXl!õH1 ӯS  .|9(gG'ێi˧捪/߾yJc%Xq&jFyÏ˸6(W8{60a>&LwDНH&?j*w￐ yvZ(U25WyA7J^7Y˨|rbVJRBģ(Wz.wTU3ʥ8GWaNT~ k )rA<9tY7 b#,ۋ>::w]R1WI)qZ6LJ)-`hS)d鄽; bT\85A"M !?x|ig؈`{zutpEt=kD$s pq@ CK7UxEiSwNRQ> [Yy7PB.@8{(14a-ZW"$q6KT rf37+Tq[ʂrgO4ɼ;6A狓M 52Bg?OF?uÝ /fhbd"ho=߰S+M-e밯KtW& ,Z@&am  @lVxB!)L*#)PUںv-]eҵ=wg;3=3߽33O_S_Od2eΒ*yL9y~Kg1X^mb\_Wj6j6Jp]2jWmeUf+K+Ȇ_ S28[jL:(QSA#W}i7pz@ N9!zwZ91( zF#MJ]*7ⵣ霄}x$&U:Iv7l 'nN߹Q9i,Z^x ҏ`D/}N%Uj؋vhfY&Q oPp*!R#,<8܂R Vm>*cŖq-RӋUyQ l)2F#[=X"=[7m،'a%n!ٍ: uľ!m#Kve>]H=*FXM=aRjMYm\TK+ܛƊjWt^dhx.$BzV.LmXarr ;ts5ߢL\]^}~jWxKʖ ~Sk0&*jc.qڵZgNJb6k-"h;|c!=KLjQ0*/BQ3wjL{6 BI\xtUD(n Ņ5&*R@(%E|YTXҐBYJe]; lQE9? >]z,Ypl};jYp;l %G!U<@|Z嶔'e9,-6X I/؎tJI ܡdE< 5Xf5; !">T~R\qao8hKxd< '+eWƒK!a]0KX.,9_ri_C: R2|!#kb xXOE@#uCPWx&4E87 nMcjLd'Ǽyk3gEq逤t1k}àN8{B5/I*HR˯F7q&3FvÖn?7̂M-[sÃ얟@sub?kT,Z1.{ԭe2> VuHP dzQGaK-u-7*>?ED'N嘙$AXy<5ͽ"8x윱WԔ/<[d 1>೰OY s9-w /þLC36m(Xs~׎/ըVw+坞ZV$=+#X&TƖ+WN 1FG*N` I&F1rw(o'lႊsD$*l7"0cL0^z#ʦTzttABZ;Vr{r /),mQq-9A<.eB)e:l}{W+-C_O\ۍd9 u40Ĩc!w@}Z1ÁR¾pEڱܴ ʙvv0T;AMoY*&`K^#CWUi[u PY+~ |<aǦl]|KrF`_T@Wb6دha'`?)AQeDKPqwRS72b]3c]J 8lĶܭv r?!Moڒ(! -! ≛y@ҩQ#<;&|@GP>\@ D(8]4ˆ!M]E{E۵nɼSwn٩Ab(8;}or`1gT_P8K>6.N tK,ht^@'f=1XojV4. ߂±Ayq ko~~\5 >!EaaV]?V!M:ΩX:Z5Rc ւ.hd&fVͳAu!;kzq]6G;7.鿠[^}N2_F9]\㗧,œiYQn9iiDxM`W@?:W|Ѵ#=3g"Œ?JUP%=H^uw$j=3s wiן^eFMb\Yxx]%%jO2Nڹ]0XEL!j&Xrg)2<gRǍcY~;P`YǤtB5yWBn"{،6Tyf ?uV3NME5a㰥f+ȟ]XD 26 ܰfuۛJ]Ƴ ;$EJ<]іQrk5t=(oPCLSCsM\9YQ}nއP`h͇Wf.K_nr'}hKQl3 $9<,wD%MV @jjgҥ0lѬ7D RjujEDuAIrHȒвm#p{ @[j:r ^: 3Tk5Yp,RKJt2@[*Wf-Dv QlT@_Fy1T6h_ݥ|j{$QyIv–ZX*O"[||Ũ8H>vy]jS$a=N!$Ӽ$I:cX|`P_).N-WHV0u="XSCȇ΍5|U>L:ee"·PC|d:BJ kzNyӖ. 2||Ո*DpUʫ9$&W!J$XF}3k:נHkP$atc AIO _No1CaӫcP&a/lR"dYU1(p7/<4JS≛PmoiQC ;s;Vj6m8 -< 4k9J#'l@')r>`(0a @0q,I&9 Fw7 9i@pDCaZ`"RLI[\H@/Pa2#JwCUf!Jf!JD觺18B[C=2S=},sa*!&0Upa/l} Bsi+_y TV#r8ģ)W.wg#SwBV B`!=*EjT:^0$}c͗VۺG7G2rͣ/]`,ȬX7y}di)ѓS'^[zF!'QݑB5jLldǏv]f`'K~!;<29fe}0ojE7^yjjg\G9hC+j{w/ ?|˸6(9bss@̂T0?Znݼ3b 2B; ]iJRNlZ'J(T~{(VCY=!(ߔ|G[Y¬αC冸l@p①QbފdE*a-+OOF| k`o?cv|2"6R)T3̬mV_튬vwF\9C;8ģ)gz|a&+عԂ\#{ާ1 v![qgw8ǝUx$igxY!dVQi\n0CjV6 Ax8:!f.pyڝI q]Bng6=s¢Q[aB]pЁUQA &hg0Z|oIinW|JQ.#V;G9ی]mF^8ɂ931HGiF7w>Q JVTn Ar{V*[ K%H̢^ˍjL#L plvOe8H5N)n޾aqՍ侟C+hÄFyhÄj!*av3, K/.^6D& H,r`#%3YV\:^:8kF37d«9%vmr+_Ow2A*vӱTJQ*jeq>:} 3;`P7.`h.`[ -Z &*`f6+Qo#upMR} WZyC,{}uj-sJ=wr~ȋN-fK썢RF W`\hBaTyykd,Z/AGUjDx 1ciUQ +n6UQspM&-ku>a =@i*; ,n p(hݦQ- %/)>g/Z9h3f^d2@qrZ2v/jp=A,w`Kl1ՑirT g8ģW Ls!tì-?q@ DXg¹{AnfhHN6-l=vuݐ71ELE"f o3$[jy&*"Xp{ clq!|dfAO8AKoYkyi3SPe 9Ɛt< |s3է^1Ǵ:{~^cԨQ2 ZlT9(\u 7yL?,A +PƄ rV;y5hmGM'f,\ƥ\iԕ=I8 {X{hj.xIQ#g1iӸN}br%B0_9+ծdW085H~WYu ZV0 xч>]â`(ao,'?<&oR$[^oNƓ <P͐oa_Jx⦱)a}&]^ Z&l&hm^ tv`.CWZ_KյFR:ף֨]70HT=7=%)Z$jeP~=HJJYq˒JN2 Bmv V"t!h!*;{Ev`>e 2"+m ED c R^& /_Ehz;[e#^;Z60r!"|w0s6p(ϰZioXkf0jXzO(Je#v3yL0F'\l@2Àa[[={&$<~JT}B[J< ݩQpIF7pZU ?RB|D_>a 5د)x=-d {Dc vnL>łlV&%H; {1uIոY|R7&$y rܡA ζZzu%hDx xJ%o-]W&֗Ӱח\XX  rK< OC(bP=?9ģIc2v|}JDo7:(5p۪JgDG(?t~d2^1-kӉw؝ةS,X΢-s-׵3 p+.Bd{vr-M \|wreaCuJ\TKN¾ZZNRop oz$-qnBUԵKKWї>5>%m#(1:B=:dr 4o}blb߂֣bkr D-,btl;.V4<[:i}{ط )EXbMݶ~3<tv׹loo6^$}RKǍ~x Dr {،53lTQ`LN`E2ʤ7cm[qN"ae@(l*&wrwxyLl)DuET&a_Wd ˘y??a,݈)\, *B.NUdig-]ZKp@ 鿮z e?~(]-ؗƵ)F48wq I,\JlP]+x4`w뜠nqM۳2oւD_L;b.=o$vϝk^˄S<\G'eOMHDxUk`[w:?Qj\~'-ҽ,]:a[8/d|ҝwH`QvP'^m/FZܚM.l1J׻E[a*gI7 Ro^z-wrw)+j:'ǀaK:-^EVUl (@d=Vh/9ܐw+\qL"ݰUjS0|FDo29V,7J;-nrx`-La˙j-A!8G#8:CU0jpcBTԐhn-ELSxw7*l0onIv;G#̂M]vP}[2|NtP)ռAp -)V+[MjI^u ~@TJ7çk,:o7T=%oO4n""OhMd26凙e\>5[Fy{`05"C}L\6`K /[ {r;ť%ܽ">[)),R>گ.U1wivhASYpl(d鰠5Mvj` !k{As6 V 6y;侁Ä)hZ`F؍ڪ| -5.V N"[*.%rhp/rH|,pp<8{D9sRFk8d.v6Coþg7fΆADfa؇ypzx/-*l]0$ zaOùbtePrw*`+2E;ߣ7`w*p,a/^ue~WFDF'(aQ2EPO=ǎKgwVYעs /OKxˮU$NxBn Ʈ &yy3m%^0%+[}'x›o*Q{BQM٥!;eAK`Kx5q01O;1g0ƣz6Cьlmdn'^ہð'|Bo@+u8CRl1b;7Pr[a*gy3E G;[ j]~ npV;vM膰 vG 쇭jB"wʹT=!G`(ﷴhf> |r^cȮ֭'*.R2'OB*CT 'p]rDbCpL0  7ޘ@~& Akwq|A [ܬ[-0y}f:տoQ侁CΞ( zM[`{\g-ojV4><52NGWXpȕzr$ xy;323!~dX,5`-8XfȯI H2QأʴwW_gi+@onrO23ӖYRPڞd{=&~ dakOmo(/a -<_Bb3AwqG[DSh˂7p(߲ 6#_~w3tabyrxcLW]}utY=3kF85m%ZW^>m#f^~ YA^pl1El=*D>o22K6@[L a6@ [À#"4"#߆* {`$P -j)B2~:8duHHFQ)`ݰ"Li`) [~*2v[7 o+o@HZ߀4Li~#a~F]ewG͂yw)/Z$Qy~$섭UBD` N y~$솝 T}%f~D o!sZ -[E.T-([ȝnCr4DL߂(a@T@7ff&XbA4|E|$0t'N" [g鬡wHB}$@a*6PFww{"kcͿ U&ٛ'>^0$m%:{|ZiՊD߃,߃*  }|Z%1Yg^!. MBգ%:u}$6IhO:1V߆" 7~U|SEZI~LjH;F@1bl;%a:meyʌ~.Ȗ!1~.ҦQ:m5JzJX1~$-S(g@!dh\V4~$q{%aLD J$LS}oT@1@$LJ:1@$LJk.V6#X! #WCb>DId$=ϖP7Ó)( (Ɏ$35 Nw R||?^UB߇*ߏWC'PT<@?( c?(?0?@ Hse[ s)5TC(HFQT)2Ca2EL?2 \^OS-N$#hԸ>M-UIݰu珠IB}{IwzWfN2?0 -޶X 1Q:qEJzJ11$dY"%)ةzgђ ?* c-$LDvc-$LD{Jê;V.#3+$aBVD c5V|I2O!̟V?0j$\^`O!LBf$W͓UmĤE tIґA?3^:3.t3#٥#?CQϥ#[335ǝ~m܈4C?7OSPϑAJDL?6 V?U\/p}uڜy R=_@1$2'Q&9|O{u/ TIK(F2i$<|ÖmP&{}C<ޞj*O ld)]^:;q%߃< - Ds5@f8 gD[TVtk2o7Z+Zok#/g8#y^;#;2d3d^Yt}ԉǹזQ-<:tbzg.7rwd?iM箚#3E;9>z#';6:○37RqpyJ4})#|k_} +W2t7s7^yjbSp9=0A?[wg~;a㊂9+;7WΟ ,HO e*l^;S/ (-i+)eǦ_~~藮Y59P~q'OɅحEw83&9|xZ  O>HOqGQ'/TGw4 ?=@أ5.]G&w(nvJ^y`fmڱ S6ƕ=~'x4eω0s}֌/Â{(Yy zYg5a.d7sş,b]Y`ps`x d;7kw&ŏ24F9WMSQ`Q6J(ޫT#⑗Q#ғ &hg0Z|iIin[*$V;GWxoP.X;Pc 2cU((*pbu8{B)j5Y ]{Gsux`@ 1+~^QcpwSOYk%u?xW5 I`n$≛F3R Bªub{ZP zHN\Q[yv# =ew # > >8 +Z0(!Ä~U9 {3]kL4 \ mZM⑤cVma9 +f fƷ``<ʰKchڵqxea&He3nr:V] R5JT,G/5;awֿopl]u .`.`[ -Z &*`f6+Qo#upMR})3evښ~~C{QQGøvNoy$Yf{hfQi?د$Se!@_`qZXz- R#WQ*5k " <T{4x(gV7(߹}M<[*T}t{ 6RU/va,YblQrCv=!ZAK_Rf}^rlrĝ0dmap;JeV\}1W b 8[*`uOÖ ?!Mo!WKֲ22jmӝܯO4:g@y}0Q/H;zPZґجvzo]=6slb` 6M-ڦhvBaؓ3sIK#ܬVp87`߈AS~[&027a߬%[ACt*O#w'Ӱxх>{:U5(^7]Ggr*ۼd87>TEs@ð/%rC}N ]l6h%ͥEAS4?-K,p /_Ehz;{p#^P-JI@8#YdCEt򫶫EmUVo PqՎlWDFD%X.13m/lB=Qy8 {8=1--ڞ=]-EDex!gp'+J/4rZLPGZ"#IBVY!BncBhv|FF^Jw(k ;܈l/ވW0,of$ovsQGxԈSZw镆x"좶jcf0~IT[ڢLY{V 3.h m ]eI-ϢL(??И'^urs5Pc|eZbX#CCJ-z7] la{1X*)`3+,-OTUİ<留wffksఓj~S5nRMܛh-8h+ZH[EoI}LcXeuq i([ъ㰥t$$]mRSO)qL?r Qf lphS _L>ݧlVc:z<%kJORc_ހ}ŋuo¾,v;lj[j Єm* RV>ЏrF b(S\wϳ x'NhUDn7p U*`o07Gaֿ̓C+y&ӕ' ͺBЂM;BNM4_2]G=`%YZ  V98p: uڴyh*2v|ӔPC*FX~zHu&sٴEb ~=;d(ԺTSl8≻ @&4 4 ףZi\ G-o=7HGY~{e~5mʜZ N!/X17ssVF8k^-{PKp=5"y+-Z"mt%J(ޗ$E3kgXt:p!h}vʎ6A/ L`QvP^j *+rLadd!hnΒuVrݴ『XuV5ȩ6`?l| [jxMp(a_K_>̟Ud=|1yU [},f=Vh/ܐw+\qKEQ~z6*-X.5lq's+jR+klk{X`4f>Ģ!CՇDZr'Yigzy_,4Xf7Fc[ 7&DL;v`KSi;FsI"[jofs;G'oavBtKinƪWpZAp -)V\:UY95ń:BnnUt{Tƨ0W侁CR MŠQ5P6qSHB}a0 $ޣ'>-ڎbi*TV;seDz1-7TB–&=G8{DcVW, kOF8L? Rm<CuOj.ĝqȬƺNgrW5 De$XܭnSΓ=:VW%`{aV&zct(3]LH̪_;<~=h3KY`7Ha/:,Ml.Y)L: bᳰc6J$Gr7 [j|"E:s2N4l?ׄ (g`K\ɔy3ﱙGAb/Bܹ{R 'l<("11xMOn3Jx-'_@] M4,}SK6UD.u\Dzx9Y+~xorއ}_Yc~-8nޠh ߗ@^a%jÁC칑M@u ;g׬&`lX%w끛aoVΔr2`8'\~'R x›o*Q{BQMtۥiEp9%Ȉ[\GߪZ7pP @jƞzf 5¡hj/`FvT)`wBUc8ۿz??`b*L/W`;;RGs?&'~NbД?0IGJzS!h+Md\9]z Oaitjxy vfef.͌~hel,A[wi,Us̩&p2=yڍ*;7iYdvt8"r㫶JO̬_> M%^g@Yҙ`{{ FNj\=48' C][|n{s@).a#O\BbWL<]іQԨ?n$ڲ" ʷHct>aӉO-^0u<]%.>}JźҠ C鉞 nE|D[dA,/ Z`3nk \ [n0?[ޒh8W_'!.]'!nC_WLvzOB={P(`ڮ|ç Oc2)eJp7l&&OA)ةdJ–[%^P%aP%aH? U&H/~w$I[~ yIvVKȓvY-J{VۺG7H@=eq?Y6k/ɑEuF2,?:>zrkK(:d1=3;2]XȟsW͑院͜L=vǎȂYyxpyJ\})7|k).>v I7,1y䗶ct+k`e}0oj-nxY`$(+~E5p塓zws2 vnIY0 GˤЭw^L"eZ(Prg-CMJٰi^$*Ÿh5Ek֦vxͯh Y ' xON_k67!k]{KB9ēxP[*yz}恙jgCV3Wє-.9+.. v{` (#3`zd(3d5<-}gQL]2ݟ9 e ݴVmtFY1EϜ6`Tnƥ a>pYwSP1UCQ-T#H "!{ e&ּ'n_u&A~mq{(䷶'GQg`TQa_Y(X븢"fm\3PHZ*$mM(uv65omv_$C]mG#g`KE~5Qs'nHm),H znkD7z,_+ÜIz*;Or3ph݆l#<[$rC<޾A)j4ה:/Q"L)vkzjiV/Kt{ԘTn6NH̵ E7Ǝ:0oXq];t1.E 8{B[.X5\m6Xk!_X%ũIMLu^@|DJ3| j `V7\JNF[`/wv0'<["N 䚶 3lZifh r}jU&U:C<25KX &cyiמ*t?).d,))jYVKq[f1[`6|Xkvntb]RfD_ 1qofo|d8%3/oY;߳l\b.Z,Ґ;q3 7rޡ۔IÙ`wY>ytMbx#|uLpoK^}Y]Ϣ E?Yժ9{1,V7 LϋR/^:ʯV2#>x7J}FS\Gj3VgN]@󃰦N_QQBT|9zTЦ&(zAW3GQeZ.D?Uk"3B@o)XǖRλ]kG"Ӟ/fDb7T$FU7ӦjB!:FvqHBn=b^eaE۳_f.Mw9k>[ sKJ]pDaW}˫jOW?RPc,p95/˔CyojzԒ+.XnEv;Yv0&W4)8|5W`VA$+Һƪ^79kZ}?=kl1r|D[15p vA- ՜"w#O*g޶TK#y"F`U)ղhݍ{׮-l45yt%'*ц חĢ̵pjS5+?y;Y-} eO "ϲ;T EkM@#]&z8̊0!V=49cY~!M{^kg,i"bj"UL1<Ɗ|2H4Wa}xQY+~y/"l}5+jr 7FEhLVhZ/ 6 "‘8\G''yMw.Tp 5S,h|W8saoٙADg+ZD9kl΁9C:un1wBn>^I)_,WRY҅T_OBT7aKdB[1JۊAXx!e#SPԂYVjkFK' $Im%1m )Τ:4V]lݪ^&Eۀao֗'$u p)<|p\B>\O`R$a2VU(p/WU|p}I(WcA&S>ZRI` [*ܭ IH ve hkc3Ygs !͔YNpߋ^!Xa#y{(گMk]Sl"2=RQأy8=H ։!6QWL rq/2L~pxAH= AX=l n(xfITܖ&Hڔ)B"txx0>%Av8 [zl{/G–z|Q,1RkM+ @XcXx}NϕB3t--lsQAK;\r+nr}vŗ鸻b3r7PmZxf֤ƀ` v "r {r6'*(ÖVu܌ZARpȏ0A[P%A>Z[*f^40*\ĉ\p2b!k\}v `Q`˺aW.a#Lh,p}7YV;'Y~_!H>HV;V1R*ER!R1A)GvaKM+!6Gw1+ TTXnx e4QF/@=q3uqzr$;q$+X~ ?O E#| w]aDy(a ,S%{{aKƗJƪ^W[^V侁Crzт ? --5!OB ]ՇnN:E ~#.O|1$/]UKc<>En-5df^}#mPgϢb*,I [*lV~$ { x9@zJ0Hy: R_0bm%*V]#$}Y%I<Ňpl=D>o2wi; ߄`KUbM\ToBIN%^`Q Nn4W<i~[ ɶLi~(<2% TD!MlL& ]ϓUH $L4oAIR k *Hi~Ɉ5~ p % c Id %{ 6A_( c2DIe$8K1~$Lr:;J WHpE&:K:1~$삭t w7BTeڡ_*j*TU#vW51C U&%C[O_Y~ ZiՊDY~ h4t ͯA+d"&ѯA_,ZW%5H +YP$aUoCVDcP$aU<֯o ynuHINuHPDN y~:tCV'b:$uHb}#,ϯCJ͛UV 7on t Cq[F@P+o@}~j% 4VU߄( cd&DI 8M0A& *oA1@E&%[߂" ln`]Y*˶͈&z|Lj5|Qc$>ACb}$L2|`gK(Л]+߅*5b}|Hx](]#QwwdGA߅2 zBE%߃*ߋWA%U{P{ +=*|0$*oC1V߆(m$\%F!oVFQJ~Kfv)XS+W S\A߁2cĺW;Pw> 3b۫(0? Mh.4I [v.4I$]@b.4I/q}]@Uӧx a-VC߃0iNE^RcLL߃0 lHn` vikYZ];P%a߁* -{KU&["@a+>4Ic5}h0jtcM~H'uKa#jca2#j֯o Ez'P%aKGއ.7^:> FKGއ.7]:>F=l˽4 @*dR0&귂ON33/~B1$2'Q&9|O{u/ TI#(GF?2d$<|ÖmGP&{3}Cb_9:r5@f ™DwsGS&mڙ+ a/l}=Wȗ_:مWHLZ*.{2) zráR_L?6 OhoWÿօ?o?ym#y_fY4ݑY'\o$S'N<νBnѡOӣ?s#ӅIk:w)c9yرL,uQ.C+q8\ʾBJ*T> Ybd/eXa9]\]o^>y,c$( ~EC'2+Jdo~ٹrl fA|*H-`CBz;Rd5-wOXʈM˿rP)/T6MC9=!(?#F[YP']%fIJslz2'΄#Gy ' 4ON_la0iʙ :Mkx%¸oG _(nn-@U>ڦW6r)1~;x4eL_9[X:x3YԽ$C~yU jh=d^5<-@ "ģ,;O8Ȇ5"7whTK3窩%7 ղ!T3t8!y:ҋ &hg0Z||uIin[*$Ö@U6#wr+`'[ 2cU(O'*pbu8{B)jl@EpG[˻M3֛P;,^ˍjLL p}"^3,9ģ킵PDo`Ks(ߒRьPZo= kAy {tpAVt>kr=pG7=0ݹ`ȨZݪ,c$hEP'LZ'88%j ї`K>U~FO71,t{ajˢuwMd>`?l}-U38[i2ܢ3٥aC9<x-VK6rh4# E3{(ycF7482~|3݌lѥvn=vG~O-aey 5l'tkyNM/o m]d~dasCWťB.Hk, ,iS q]reEYTI4)|!J EZ=˦-[kU'4T-5(! bTaBwF(ՁyŰ38g3 ,>rSHl،eD_;"k Q*]Lgc ,W_feO $} R 8[jX+uG8 {X9ė(Qe3Z A,Vł`lҒxK!޸?9Q`$_R*^X2YKa,`LxɏJA R`_A wa_WFp %7waU&̺Y aXQj} Nǥ~-](UDŒaTT&'\^i?CF;9OzVKr|XSL sOKfh9MwYZom׺a.X^L[;+5O_u3F`_YE|A,udhj hlMd޵sfe=:~|l M͊&>?:ݧ‚NA1@OA@@'0)(0(֯kWl[ٌZ1r̈5|AcFs 2Cb( X fpJBOCXGAOCGAOCXGAOCdGAOC}FFAi+fz<B@gVL =UIXg3uU(*`IT%a8D9n$\ɏV帑l%?2nԳߒtY(Qz,y֨zm|*%}@f(L,Izo} 4Lǟ& ;aK4I(>@ι<MT&O 4aWo)3^ 3be>ܧ8ģ JzNWxNa*!RtvT?J5y6:[:|hY kqΤ)wj?^ې'}c]VۺG7H@=eq?Y6?`FC'ߗgRebǮP2 u,8.^?7sr:#"DhC+*{w/g~;ar9;7WΞ ,HO e"l^;S/ &-ivR.lZ맅J(S~^+#exl\z+ eIWA` ZmZ$-v HNͯ5V&a6Z5z9sZCo-2bm?0L![8ētP [*uz}恙j置CN3%Rvhʕ:ob`PhHXz .ػ4P.d*qd5<-g.R2YXڹP)T7 ac]qPVM3窩&7U{qfC%\֫TFU:A C<"z: &hg0Z|8hIin[*$r'k*R@ݝ+`( 6 2]A/NT!'ꔋr_jwޣ-Q̦m -cAbWrQѨ8Q99j n 3tbHvH5.Loޞ #1"BLpy;=ϼyͰǎ(x6cY7Kw{ CmՆ,!o5Zj=ABjk*pmYtcń _=Oak.AY|0볆d8~:e{ǡ(BݮRHnIUj @8Liձim")?,[}䩙Rd/PTQ&`;KT33>4;d=)Ƿbnd<j'.L"FG]z\ >ɉ"W`_QoZwyc=cg3ӮyѢBDef@/]̤1Q@PmC9E5|7x31jJ !wxje0 h I+jպ^l7J]tyPnrlbض1&9یm: ^oܻvM&ka;VfլGUv.i1A=h\q! ޠ^X2vVԨE:u7HQ^iDQZ G֤՗ ?=7jwF%Y# ≛%@zR][(>G+К:5SD ק[;~DzF}ߢ/-Q032o. NQ~ˠMuyxهWĕruA\4i^B؂iQ#0/I48w=̊0!_kҸ׵XwW|PN[co}ЃmM6mo푻Ͱ7+gHf& {zw-s)]tsR.:bz 8 {Z_ |a<>|ʪnx:0 [j+Z*5ꞃ[7pP6R B=huT4JLQLh+Jl7DP3;=:S"wF'aK*(hi]LEP wqi!ln-5%Kz6۔3Hy-x,c{^yjXǖcUvJTQDx; lt @*Z~ʤĭ)9f`ʷd\{C7^>}-qټw%n.6Nߛ-D mkscYx,X^Kԉpᆨ"^2J+Rv*h6QhZ* ߞyXJa./A//L5Et S@S#*[;kvV_-XfU&E |ɉ>[t G8880ӳrUD`p+Zf0 .N1}W?hz\OA뿐Y}f6tbx`_P~q(&:NoXs8+Y^<Xq)C&T$ېF`U$@@RCR"!"[;aT&{I~ּh&,k\^bҊp7lK,?f\j5UTc ԷZ+X U+h019-OSh}EVُ͙٬mq8pt>)_1a̅*ZN큰@G;=3EB}6 2ZSooEUO:фp8{@:ZUUoAƬYլ|^x; h2$W϶ۍVԷZPk^rc~Jv4$6%+c3VڤcYBnF`^+AQO |ĵ;͖yH԰ѡ;S蕻«TpH|Fz&VxFXra̭ޜ=-PpPؤoE#`#]D^-j7ᑭe"2-v#-r7uxlA],(*Z(qۀcu#V/Fɽ :벌WE1AN_R#C^0KdZ1YrfkN *xmM[Di}mZ$Xk/%KxL?l||F'JFUԞH6~iaB&R B_[N:uўeFv~;˛i?5}5*d040l蟳 ӴT;;RGnD];W`V6ܠ?UU{jV4>'| [ 'W5\ r$ xy;323:cc! ؂Kc#g5iIF8 {4{ #23/~*5gV~bM μefdGӍZ~7̴kIے\#u\Vg@p2ivaF M'i#I35| a7*`,_FJ9ee}ĵ{wXAv/a#$ΚkpJCCk6Vo3~Rsr%7A0 /wzbF٢-ZYЃ/m29^o"!woK`A|2 0>dRĿ_ZY8of}GN cc'#WAvw!kpN/yFbo-!w\1מd{P7;ao.W!mIeNazoioDSO!TimyW !lݢTߜc2r~Q:7.2m< {, x v |]+8]"'a㷚j33Wh?cvxi4{h6 vy#? _z徛 A.L],]]H$ b}tYM;FXg~D[d~h_` +wޭ^Jp=hb?c R.@.@ [C_Q" GM~$ݓB/| Nn}j߃4-3k{<ɣ(S"aKE41~$LN% SzҋebQ@1߁*  D`'0@;P%aH9C7b ߇4o$HHi&H`iSfY0.E I IB{TIv`Ej$98ay@JdUy6J ߇(G- }}QV} ymHN }}c0J{kN>'!TpC(#ֆPF L5D[q'i+/q!B+-Z!Bn !KV+b!dCb!$CHf%1Tn#(p;W珠HRM_UuN:85#( &:7Pa]$ɉC?6b"pǐ反XH?$l$E1dIX.R[Y2L?.-eHL?.iNER7AL?. `˵4JPiúSˊ߅( c.DIh7tc.DId7׍HofmѳD~ E)Ih tcl$LJk.V6#gόX ʟ ϟ!W~CbDId$=@oM 9Ts#QПC?79s#QПC?79Igk iU/_ī_@HZ*BU"aE]J>G/!J+_B4K#J/d+_Ҩg%%3s+س +Pl1ΥP鯠_!uSGQD 1 $Lr=O~[AJwI/'v9[CM,O 4ջ>7s}!߇0(8"%@ƘH$dY"%)ةzgQjy@1$LDvc-TIdo U[$Ch0jtcC#jֵ/S#X?0H'?0 \5OwWͷ"S0 E'HK1tFKG䏍X1tFKGe䏍z.ٚ{CiO?1b=QO?1OTP N$[nGM/pl#>l| ?( cSHptcS0{}Y2M?2̈uϠ?3'}@f6|gP&{C}C-VحɊ j`lQۀ 8 2cU(K'*pbu8{B)jl@ ߥFWwvޣ-VKiD[t Xq {1N]&1*Fdkat!moo$z_7~M)|Ka:-|jf-(Q=V'[ƨ@ؾN&A5zʨ9n]qp%|xoQǁW`_ Ga?&<|!m N1р@p'j}6qG!ZY0@'E'k ˼kc0O޳b".]~Qigɯ熙 HXu@*H(RV Y¿w(gNz-l03˷p|TF&F)>Rv{:=bݧ_PneTT0FIjb6(Yj+eTb|+aYP=0*/=o-l^ %5U_͚H7O>Us8{,"?!* w4|EF*wn_) U5źq ʹT~kXr8[}xE@ծ'D 8=| KʬًV-ZYL-PVa8 \O]1R[Lux\?'hz A`Z6)V3pn`7ğ'nH3vxXt)^cĪf͛3 U(w2 gGȚ ɅdbD}8~)#MLw.XXmw#^{`@x$KS*7.{4d+A<(X@ֲΜR2\F"t=cIugR3ISP]p <"n8{B9[a6KGMTDʔ6|G5Fl[h $vd{e:,ң"Vׁ9J\>-5CR})ȣ@ -Q,Ёē1{o>Yu5a]?Y"ѴcgX8NdX,5`}H2Qأ $PO۹g?l$R"X;8KF`TBNդքeP33lk)'Oxs@)_5N [01Xq5a]J_# ̩ܠמ*ZVoP1HSNF(?~#`)`tCΟ5#\{ D[dpָڒ5lV~5d4pS5g\fkjP1v+n0C "#;UnBC={P(+n֤ Nnxj7 bT\M[/ހ4o yGQDwÖhb2i`) {o=E2sx$1ބ*  D`'0@z$L2^`])P@z ҼeHoA)`-H0@JH23̂yw)/EoC=O/ې$!w\$;]u"5y$Ŋ]'PYUx irbHn4D9 ]4BUFc8i6*ʼn] [\UKW һEn(Evڪ$uEvP:IJsUuffX'i+/.dyZ s 5%ziNE]R1ޅ, {a.5> @}NfAzH=(0J:1{P$aw@u.Z }#}Hp>dy߈{to$=Y֯{V "[4tҦQ:m5JzJ]1]K@> ?M[ff.+D_( c¿Q&څ'/BIv])>~'H%(0KP$a-P" Id wm]lFt)Fee#2re%a>[B  TT+P+FS@NſUb$; Igk* O+|B@VA }U>HXuUh†%aCp%%k%|h$[?DyhԳߢz˫P櫠bKWW:ҩR"ddJ_2 \^OS-ߔ&5A4I$]n:zk5hPߞ2q}]@Uӧx ̏a-VC0?iNE^RcLL0 lHn` vikYZZoB1L0 dBI/P~X5edfgIh0jtcg#jֵ/SOCi#j> ay" OCH'B)$. c\:.3FKG2($#֥#2c$t$21tdkf^xmZF)XЦe(S DLtjA{`ˍONcB1B]FSg!J$zu/ TI:eAsFDȌ؆LB}<x4=jŮUoJօ?G)s!^qFw$GMwdf,ɼ>4ɩs-=z[xt\nta!Қ]5Ggv6s2}GN;vlt/# fn(#DhRFRX} +7Γ%{`+cy3WkpśׯOި=.6׈F:roW^:~̯q?l\Q0's~a aL ݺygt!e5-w֔l<ش/O "\Q"5kSW4!DEwlL %q-tH) Mq691ǔ '"?! ժFU-R'/T!ۚ-[dHh/\v vkYB8ēlPl-6U>f#_!!!H'R"ģ)OJza3rb*j9BUVUsd8(#̵Ҏج,0]kv^vY#43.cb+؅l՚a{x$nҩ9Ј,bt#7rl dgo@^VU;j.cVS25;4gU+VIk+r!bQNsGL@^ϵ(QB { kBf>pŶ[Knɑuxim9s;}3(AN Q`O)SuU-·1Rh';T<.\JXerN_nט 5&^1{@H׃5z Y_OAM )|aqMNfH֎-Of,.Xtmkbypd,& Mj8 ۨS$9?З|b\"+-aȍiF#ic*7+*-PJ[nn"BnӵGf쎳`1n* {l\ 2?n1nA}vݨHڼ,[4EޕfmdKI[Mc[$#mHSUT/'/Lt4ޝrrT/Xy'#,h =ZAoG}(~%MJyUw3^CYJIЁ"!ԪJ64mP~1ipr)_qj ~U\JWܛL0` vJ[65ê90,v.$6U< y5Xdә7pt^>+L֊rGu$\CJYO LT C[\5R(zw K)wQqfdcV8'*ye} *+5VubRӦ=܎L~<:#YӦyh*2vm¦jJ78QOZLWuM>gC,-Dvyj ]gMY'vfva)胳`tavp٬h6 RʽA91tcKNoZ+q\bV.]sÊSHk*#>GQՔ!zuݥ5k89RgWTN$vz!&`r |jdi?y2y(^pBLOZ.3O>3}sV ѼjZRcD/(\B6V~ODf q23˂fDx6'|THkvЖwv$U7/oU.]3xuB} " sQe^u!49Dˎ`<,CX91}^K`_< |y V_;-3VN oUքX9Q{| q| ٱr8{^h_>s`.^J*"~'y l/Jkf}avry,5|x(|x HqA6gP5jѩq2h6i/ZL aoN$-m6TV͏$2d'ʥ̐=oe"'HIfF,kGDxZlP_xKEXbo9;`KVmW3m: vq4,ZyG`hiYCq#<|[8[j-LEUzHe+tZ*)~7h'99eAo)"L D<l_lK„GM'8ߨ釮7_nxBцd(AiT_yn(D6~aBsVx]V1UYRCwCeޝX[y8p_ KJgd`#ME -ط]Ln%Pd2/Xy6sV?<-{ -l/ޤn>6 -R `%g^fWBtLP{Ar2_d=[4g.s4Bz9r9 q5%á֯993s.b?HU cZ6^]y'plŪI1o$w`]YxQq?WO''.?ajضŬe U+ ;{aR/n}m-ȚtoS9NJ矅˕81< |2%SNwwE Xq(ka) lYlnt l:]ti"5StV:ZV:rQU[`Ss߾ɻu mItu5GNnzb:uCڃ!68Ri_NOÎ(r xQ2`xybm wl,cZb_GBo ׁ/:/_Ö^Q$& Vr:xT;O~r { |5먅ap:Ъ^X嚅jx5r!MI?9J&mt Fc)|jvQeRYZC'H ;`wP uOwaB28;cf`-A&#zcc<OXӰc%w3~ӂjwD [jK,ޑ-,;b v}R L0}zjwYgNY R-kwqqhtr6j4 f--#J'0Hb06@`|{ &5m$N p;lEb!5;`w(gʦpDMGD:aKuʹ@1>2!3HCL>]Bg!B}!emI ,m۴tkލFD:;`KmDj `wij3YgFXD AAS֬h([Q3 jD97ެ'="ؠU5"፨m_[nCW nIl<,hz×̂%,cc:kv8HKPT =㰏׿B:'`錟◷Pm~!~D .۵n 0v-Tk3|*((kFR-!zQM&tDxT\L0WS[DixN1m)Sʹ)-?|%r͉/B 9_se~3|nRAI:BY&w?`hiQ/O>U2L:cYҢnQ˰/'ޢPn6>-Bvآ w[ɷ(.l-/AGulQP1Qآ w'I(sZ_?B-/sXE׿uԋi#È(4lcvx=!RaUxԱ]bŘuakoQQ0- sx[_ @D+3[n 0eUPb ߲ʢ8:;[=7/M-طYaZ |b0Y侁C;>93̚.l=T08Vq:[tiIpE ﱳOԣpGw@P-:v##&v?W+NK;i|Aejբ$?k/ۯLTdJy&wHgݰvT]B}hN|G_CʹY+$E`ӖE}!̞(M`K{}4Wysի%(I"y3ȜF ?KB}A9v1էs9}np %#7hQhrÛo*O;:ha[׏叵fYv b޵ҶG-Z9{\Q$1a˭JŸ ~PZy(+-+KKϐzsdxp}hrC}%;#X"U a7>} P:5jCKLxys} /ʧΧSQK#+#Bߝjzjs o}B?1^ؽ$w0 ;4*fDO34s? ; p;lS*}&Oᜰv5y3PSQd%Kq82BXPۛJ]invH5H B}^\x%A95z/IxЀ7pGRTF84i`*&sBPfȖUU ''z%}T_ $1Lv,49Np)2bsY9ۛ׶77dM(fn1WLPOy3>҅9+G_%n躂jh*Q V9WF>_d, M+6wW, @G !2`IK4\sAn* l-FSĿ –Z^55MP" åkH_C;&-u lQi vWoJnrMME]c$L2x^`g3cѭSYG_@2"[_\4ʖ UJ_@݆FE D(kd˅@/ Cvw5n\ P$a'[(u{:@'PS翅" `k($@aiEK# /ʿ4YCcP%a<֯)ԛKWP_!ZdKLeR1(ҿB2ج*+(p7 {`_RKĴ` YvyV ;Ȓp'l$ ]:h ;Ȓ"*,QdB 0#95dJ!˿NZ Yuk_C]W)o237s%A$3!JD;DcgCH3O{uOyis EؙP$ay" 3H$;Xμ_.:VG?F5<%a5<2^5| $zڹ9AU87P 7 7 T7&$a"LPzgB 33Bi/r+O#,Fl+]#0ѕ D`0ƕ 'd@[C[P!ʅUX'0ъX'0ɉ 3r!4Zfv-DFƒF Q`ߢQ-@/n0AF3oF3oDȌf3IO7̼[UHTHL$ݙ<`l/$V 5y@FΪl+S5b]_j(W(*tb%alF?-73w%aYߡAg$;nw("gsxw" Mv–oߠI9Iݰuo$$JsU}n)SwawĥH;ߑ8҉(R" 3\D!LB)!MoO'AZtJ+^&t, gm‚o#xmÐ F ~=[+m] ~[Coc]{,X#;2d3d^Yt}ԉǹזQ-<:tbzg.7rwd?iM箚#tMdǏNeCilrqXJ_n(LTXHH )Dia_JUe(RYzqU{_q=vqwv[==s3wOp_T,C.h ㋼w@ZC0gx2Kaˮ{P -6]A\0mݚa˺K3s nv\}.HQ&}IB[BL o-VeƆGa%8Sg70(;,K V0 C+h:ƻMTDȜᡡ5c %s(YӃ;;d7Ƭ 0M W>_-ahOx^J,Ao!1++FcNyo!O2fي[!S_ Ds%ؿ$-U"PU_U':qВU5_S8(_%/I _r ɚF;R F5-hY,G0,sw[pS"$905f_b4X\u{-do=Mw{`_˛`S, sn=< l^3a[ʾbq+YӦU1(ՖGE+VGKHPBu$}v|\I쾩(?S `5=A4y tkr 'v{dShfOօTBbi8Ϝ&PHԜBvZ0ij` aχKt{4Ko܉R;3<+x ~oLWJ=poۯ&pE vh]vtf g .=\2;-E\kZw#FcXZb>%f*%i.h`&͑~ ٴJGtsl`/^-Tr8{DZ#fΌ}-Єm*k3 h6½u>@>! Y'wUZӮeq~7\4J~}ڲQPud;udp`9RsDul*k9q; -POVHPO2[()l9q6!lAe*sĪ \^ĉ,p2U!Krh3ǰ?q>[xfrcQPpl߰lO/9?>/MW)R8'c`@Qwo$: {6(N'{{.01[]2d/U ifn`'N 9ԯr0N :Dh 4E6 O# jv=c^LoŎ 1^< [(t?yDZ0<(Ux ( rs9UiH궍&(fi7Lp?:VveD$Օ>}"V{% E'H!͂yĝZ'dY&$ՀV\]#ӰJuDN"<:~q 3ׁ.t$mʶ^)n:7` 0;B`$3sqIrzILUq[n<]i_BfE{N͈ D(u]IQT5د?\$w{3L/&:1m}WMDjx ɻ=ۆkÆJtK<|tȁJ|i}U|;H! ]gWSWD! ,MbXYp kPN+Q) XXHRBfL$[A )q(^){3Sgϧ]Jno$a<=$ nuٍmYr @is)gۋIբe(L}Ś{1oze`LL޿efOɶLSÇ_VAK.fMbt@}ਫ਼>ZkپNNbX?O * oCJ~7M{s&U x$H8Vpl‾|6Z_71p]d`!&;FEnJSt 2Hy`^Pt"?&AP@?ɦ;F5IE5J8(7C خiӫQN6oLܽ~}lbL/, @x 7|SKkK>~o[ٲr_HYyd[`PV²$uC!= TwguZ#v=$;!ģ, Ik?R*Z.:o`P|@="K}-Zdt\ݙ"?@N}4/QSsL` 0" x Ux I0cGo¾)-ts-duZuWUe[\U;ޏ߈9SzbFD:˺ \Ǩ֣MWgMt74PdkOV`i0i-fQϭVm?`yAGZ=Ab[H Bg Pa l2" PN;峆5;}i GVB;@$Iۀ{`Q.fI$lݞBP%alNB^`Z* ;awPݭ\;doD2L,\|*5L)ӨT!aԄ2 YH:J_7k鄷, ;`zJ dID;a, , `+(_D ]S[FU,IʎX:gHV :b$m@:gHvB+>`O41*oL|3B'^30$k:$'? O6K:|Uf8|U:${'@y'[Kk<و$'HP5ƧH mVB6K#y9m=vbT:L :L\:@7P2똇2 =:/gCUV" !I6 *~y=@ZO6$I(KCN/P<}@6k*\HԨ]:HFᴑ(vi-iԁ. au4Ju~bUyzeȒ02dYr..LːeYw"RҜ.l=$4I[G$b3$*g>?& "'*ks[.av%A."qGRD حI̶ԅ0 uغs/' Qt$֤ u<9mtUEښ&P7߽)skrj*ւC ;4]4TphiygKO>'=]( &9s~X©'Μ _:P#CM*V0ޑ<] ىaf9#qE۷ԓӂ23Q֯jL8}5W1;h-{v9{60a&LkDнXjukx576~azXUe1([3V\+kSbCI,:J5nPn}J*!pxK1G0^NdAx$eߪZ5~}pp?A#r 7Ob*1[O1qo GfZ!+lxA}A<q;z$rzcԎZ\0qX] <~i"negW`_QVԶ3ü.p=IE^ǁ #Y2eUL$YEז`#T֥]# Îe Ê_n}Ba$Loz:m-_ Ǡ@bOy{澳MrA6-jpd*Un`OIކ0o<>-4[q#v)_kƗ*"/=&P|IIj2Kaˮ9ǽ˰u67( F} JWn忓fH2~IB[BL7,;n * œKh Wk70(E"K V鼢m:ϗ8& 3'_k22eoxhd͘BtJo y1kz6̧eӵEWKXBއ}?W먾y[X]Q6$tʴ ({c P} ؿi|4cVz 9"_T' T6/%iI])%ׁ_Uyc&8e`M|$1`]:ggO4ڑ1ikk}X[fY&0G$Ij"@ 3uN&*k&z` zvՊE\z#լV/nT" 5n=plۖBfn.SDW(D1ZYҢI(RԖGE+V9ᦲ8DL7jS' Qj`Pn42裶@L)hg~6FnuеꑀpI\ iMMqAR4 y@uR悮 gD^/ำ,e.F5#R?4KoKí?>AWmӕql2*&ܭA?9E0s 1x#(?Ha:$g9R^ڧ|a$-Y AqAna о[KSO߂VHr7|~Uj }l=kvcBzl8"ߒmض2N`/e#GgIK" (wa Wr;*)rx "E`Iػ8gtoΩtW VPx 27KՋ%"HR.^t՜`AYNˎ/Ȋnx&w /$gl|[u7NB J7'Ta³*6/ߵ[{ZZk }xm%Q=B9 ܝ>-vB@ǦI3#J[zh [j,XfoOq0 ]0=IE(qk"G kά]LTڥ'TfeDa_ηCs!Qa rǴ|J=2'B%i.H7`&͑"wxlZ%EĹ xpmw/*V| ="^Ft]jgFvby h6rGiPwudT4Kv2'K[6xN:kFԯO[v< <djo5Ԝ8Q{8[h>e-3'Ntcul [ĉA<+ 4ĉU{1 ΉY/MWTɆ9tT_hItm Q&ӝNp \jab .ep@ֹ7" -yra~hqb!:G[H)޴Qx|].UW9Ĝ'*N0DnbvxP ~nb<(Ux  r[9UH6MGYdнXl-: FŊKLJP;π,a{ S B_1#$7UmrA_auG@Zr/pZ~xZ^-"`xZ2p )!pl6y ||8{.ю-ؖhwA#Ic M۫fgaΊys7Y""BQ5=2|xG5q.r EI@7\Rx|`/pѸQ<5:|ðJT惪&5MVح"N1 3ncN2חҸ4je;S(~ \m : ޗ5; \(UExWK侁īHS'XΔHCUblvs#bIcp=p]Kzp@`GȜd:ND!6+qW79$!SHa,Ҽۈ7F ,tg #Bwwu>}\>Ƣ3#fwx%5)3z]*^m؎AY7ja[2410w\ǘݖ,侁w1 -Z^NbzWVTcģ5bcF환͞j~iIѧ&뫿^:V>\̚Ăz{K#zS=}ax;eײ}~@7TȽT"o(+MO\~7I q}72<ao_3CMw eX~pDM1"MwjlFm`Mnj@pl W]/* 5gN|5vmJ?ߘ{Ę^X*)^}UEAw "*|l+d7|LoV>~5T`?T|~b}"\x,׉B|1nyCu 2K'Pݝ}E6t>@bZįA<ʒ ΜcŇ%G3Z#TF+[Ek)C.=D,p ,lBd6_7`P$ n/&rN'0<'!a6BFl^ [>je[\<_8F1#T]3:F5h2>kڦkaeuغiJL<fJ[:l!ϭVm?D^Vy~I~͐' ڬ)mr7Х ͚*$A.t"mFRD(Uiԅ. a4Ju~B){%a3di9{(#LYzZ39S9UIЇ& ` |I=&7$IځU}$$RsM}naVYS;ϒ YA4 'H@[hi$aϽ@3Gig"80 QѪ"BZ[8mr+:l!$R fOX7P*}xTR’'ɧșS|s)r&F\bKxmMFfJKw[^~tԹ5x9o ]k͡*~84'.CSC|9an MLWR\gN;}7U(DU3# %Sk7lDLt)(l'ێE˧kwoSOL3Rڿ8'nԍsч_ÝqUv޲gh#1  a4~F ݻ;9N_Zg;ÉugjfltRWcPfW> sg*{%nt Yt jݲչ&_;wS 0RYRI.{E ڪ=P/.nz ?묺e7~x^u# P"Qzd_EY'*RCģ(sY9U;;VBn 3ɷR\ToU& ֌u93E$(~dA`v8{DY9NNbN~x %6(ģp_S!^}%܏2'k1׼k1RɌJk\QV20j4ûH5슔R59h`.(auviHS)Q0rL;^t,>2扱=)|e{i)p:ɽb1[3S؏լnU3naڗUD ilE ĘNJO$M*CBW- 3N;9EoPC\<,u6d%!s5E"7ģWF[Q,bmmCzx$SgcPy!(T:'a잗bTC/LՐ/Jߞx,:CW#p 4}NҪ>/C&oxas܋ [YvThͰVm <[h\ТriJ[t/8㢤Wr2KvAW`_ɾu# 7b۪%^n9tJWr)k(X!urKVQME[r}ej]33s4KU3k&#).]V`=l'ߘȐHzO`]JnLoQaN@&/ Z<8M;8?-_{P,:n1븣R .ċށ}Gt9alurY~r Dȴْ#W]'Gx@8Qa3N4bf7.&/kokh*ܽ$r\/I΁GX_0UѮ͢D*$;hRe+؛]U.%"wnj?G{`!AD^Cu %a&V\h ѕ:Cqߞ:NEl*N_7|cjlr;I0IKG #Z&dyD$-y$huCd&#%a&久NF]Zd7]/TZՖwȶkB@e'^(W@ sdPxH]kk>r.EŪrÅڂnQ-6vV]Q a7l\{A 8VsN Ta N'gWo^Kү!td2xh$ hYmZuO(? {{Bw0'Lan-:u!xXrH oa\Ad_=I I="c8e;侃-8sAzgXdi)Yi9ga9ANc,,t~X {v3"Դzv[G`Qb!OZ峰ga%ًՖj*a+HXo :a2 B\b+@ ΝڊΔu})ЉHtU!%3yyίŔZ?sfP7<9d? 4R(>INA(>;M}A TAN5?'efݫψLj'kr}\gkOܤ:[ٗ%l-sVa؇ӗVd֩eӳۤ+ g]t;T3}#hяGqJ]LǛ`Y3H^[?Ke婠.i^}Ya }BG#[]7tZ](:DRcAZ<7,"GAhRYy3_vljeW}\Xd3Υ61Xۑ`ϙʍMVΙ kgk1lqb׻(5}$5GâT6 OYSGPN4tiGsp XvJfTrk *Vrd[,ܪ-/(W*ߞԣT Zip߷BJuc`YRn:A o`P|P#E205 fAP`Fj(l@ӎrCx 48/ŀ^}-Jܝ^}=2M2 h`4ld^ Ʋ4̤~T l*NvP3];;X0` vh34mL7{C>zخ|Ujջ!«.z\;sj4) j% {t^*%P.Aj7ٝPkPP7VZDDݐg729´ڭU# GrdXӁJq9l-`" bv!Z=_5V9^Ҷ54ޞxupluJPDx 섻bݟpנb[! w?ĺ_puJ0jrOiP iђ$[}} f$zbBf_U#-k}H:,0pk-6~zZu#SpPGF\ t)S))'tML lVY wFy5ED.hՠ-; $|n%K˰/+{VqV}x{Va:Ą6Kj %F^[y#Ae%FN/k#wC+Zn(/.16?E6Jl!\H1E6OcΣ5v ˧漵jj-FEh_ I*ɯ= Ѻ|k.NOv~t!j~GaέqW̖Kq㢴W9໰F'a?z#H@hSPH$F-@ Ї+ 1(-Xs?yl3<*tEXpmp0S /V9FA6}*)MB3E|5|K9&xE fBAM8Xp*l =-qFmy&N`ve~ti,HO1\Pz>cz/]wQAL/F 8UC˷m k넳x4 ag4lYA]>`>%-OxP@ 7/qmm"-^-B ()9 5eh*pИ1 ɽ^K(kv ~zn'M.Tghb7n lq"9"x xlU2ͅ&~x v'[Es8B?"BC!̱8V[9e)Bf`-kk!^rfQ6Xv1oz%b{a&gE-i^EY^!Uvڮ Zt 0r`O[^$P7E pHpʋ{O ILy֞'70GQlx`*^;^9ޘ+(|W'ѡg+x$S黖`zA+2[z!MBQG892Q?oy} 8 [~? [h@>JYhP,ˠP*a3\n'ݰDgxPX8{tgres˘uu QMKBy-qbģLCE+VyYՐRB $}9!J u9_+i|3/̔:;E &ēuy1Ĩat@ZAx$i*8{MYBSQȼ ?P [?~gVZ-:uOxl+VL]Z5/6O:'+Q&䗺6]7[슢4ݻ9su$`LWl+^~C{Z?`G;jLEvTS9dM*R F4qMof!5G5(=oYӯ~iIѧ&/fA"{K#zS=}ъ]ua`~ͧU: o"\Nj~[M{sbuOa,L/2GGrxp} !};a |OJD7 V $!~} Qq$c7\[rx+CCݧ&c.:>kڦka8j\ZkdT0w/L6[7k˛Nr[u =7 r,)lvFC46p2|Z {OxZ l.A|@p/l"AoBoj1T'+7Q@T'$M@y $Le:oA$m=Uu2 I3w l*N_7|cj]6$y[K'NbZSd+p>|8@ ` >qށ h+.\[<9MF]Zdxe QrzEf Q$T[F]ŹEfE$m H<^sGq˻yuCWlP&aV({n[O_LK?(aO4&1*ڗ[]. 6ڗ[w B3tحU/tJHFUI$M!+$~ Ňhl)g]SF A Buaz"(5S0ϵZKhYQ׍k_[[{/.ӷ ͷe/S"dI[//Sx4*kiHE6TIaE6TIkEJ3H߆* H0ՊQHEiEsEJt`;&a)?L"_z$p]H0/"خe.$I LokK O+mxQ>2]_xQ>r^_x<2]_xQ>]_ Tnx$p}=(0"p}=(ɭNLo}iy'2LzU>2&=*i9!k3&=* &.`0ikxbi, Dz|Zi D߇,߇*5g$>>OT+|}|X)Y&I=oHT亴 I H@`C I$jt |} ]vk]4Ju$[j?Qf8 DI0t3$sO;Ŷ P$ax$uOڀ (0a<7ma"virZ˴(iʴl t$̳$HwI@UL PeAyeL PeAwevki3AQT^b -BżZ**UsVh,P4L=@M0Fބ(M-FD 1Ly4|ylwW/oX'Rg-*3P挖anevXe$s=R0-4$9 MVyb8A$ N  s$T_Pj1mM}ng)2_?a΁a/ 9s(8"%]@H LBH~`4FK漳 ނ* 3-YP%a%"hɂ* -.T}^3?iEUI I\y"̰P˷'6U}4O 'Zs3O6O LB]˯'5"ލS. 3:R.KZ[GJ($%-ӭ#%貤u2R:8Hjiڜ20mkdu: "Lt:m-6#Sx!:R~۵$%a6DIخ8}O:N%a@EhN;P<}Oek0'ke@jbM-UL}RQ1j]#0\da3c ح538}ղyzPa A;ạr'aǛ Mr$lݚ4PjsLÍj.N>TIخeC.+ |0ʓwӫ<*T/Ne:@-Q\%e:@-Q\9k,N0'p'lvO #.Bwjjg=Vp[]8]ErQ˴y_* smމ^`"TIgN5;d/& e>2{ e>r{!ԵByna%=F1QDWe K c,AD!R;$YvVPD%JVL@5EAϲ3Y}Y>V g9Kd,UĜ$p(1DIPt3 Q~;'1'> EfsP$ac "0gHv J':0[q囮Q9sZ- i9D`0s%a-<ZZ-|3$:黖=IP%aM*?ě<˩}'Cn1|shpfRtCKsOλO?h?^zo?9~BX߬=454ϗϙt*N>qӧO мasKc0΄2QJ.]5zPVCM*S>ӥ֋n;n->35^{؝zcZvc 9}wWL8}5W1;z8o60a&LkнXjuּ{ k0=%c$~Eq}C< 8^8+gF,: - aʲ!6 +KN`/^eEjK8=y96`>邵Gw°_qpH+pbu8 {T*!n֢ (]+d2L[fXvM/谖L}(UL^AoRW RԱ !3X$5 tPlSQQs ڣ Ze#b*+h McJ3/Q`a-d졗4ϲDSu9 M/l)#'_uo]sIS=ѻ8gtoΩ>h;O']A^0J%7sMr ֜p3+{VJxЌs;df':'$;jp^QSƑX:MFC S[Hݣc)&ĢM]w:Duxuez= ^6z=^U`vy+\b34`Ҭj:|5P=7[qڶ"Vw#bdz)b[Gd׀` u!Hnߔtwކ}[ǍЍ6+@sY*A7ߙqpJڹQo!.zs2ᝐ2uz3,M=D>Qګ~y3vIzl]gi-(KU 7~L (FI)9== (M~ ,0H}uw@dv *3H*|w%zw }7a 5nu 1Rrw ؟ɡ&p4LjkM1Gx<*^;0WͯRBI4F@!J wҡ.xx$sj.E[6hG]ONbrsuCO6T7%3`7Dr ֥3ik8 LZ*qeA؃ҜZv4;^0x,rϿ 'EqB|z"w>+w$QsG~|j*apA7]`+I㰳>oV9ć_E}^lo0m90Y,E3961ߙK􉱩w\p(nVh` ncdlzIΏa Wr}MVF5<ñN=ñ[kN޼X܃N"֩-X?bII@[`Qҫ~y39Yv[HjRnBJ;&*Cpeҙ7V9.-Zu<&MR.;__t\˃rid/4 |Y4<uug pm7 ]Ǟ--Fqu+/!&< [RzL&s8'Vf`b#0Óz Bu;3o]a,}6>*aꝒ%Hr M^5bu:Mހj'hv8v\ A,U=p !=$Mq< '!KFټ![ēDF6ۤWϺW˱3o)]6]^]–_;9E Qyq{4Pܕ(}HoP U76^{NzCb$ a5_ӪB.[~9: H& >c5 =Lj'2dZJ`Ey1bsWܭp7{}ޮzKr`NHn--ʏ٪ 0L g &ēu@ŘoM4iS*9;VNE6ڡ9WֹL Q: Rm^}Y@ ׬Jh\2$z5O3^(-q%j;Ud'HswVׯ^,X3V!%Mw\Ġe%J?!-ܦs­ē[x43'튈5eXUE܍`]6`'l:nކ*o5VӫIDކ4 [jӴez$ [>TfF KYz["Ys ;O:k+ (PҸec9VwjPmɚ77+QħXIڪ+7H|\MD]ATz &T]*AưKx]`N 侁A8ʝc?4($; Ea"13-W~ !3Zpcvsc6oiB 1)cJ[V[Z4wAتn /bDAs3*lyMѝy^D5@!Cl`fZЛw\SopA>Xn;?IBuUGNBA&dH.zp/cYݰjbid&RN4ZRMxbO5*}X:WVlBeDp4b笨uf*hH!FPd>*%3\;/z^K5VKA*c%ƴ'Lj'1W'oxd_ͭ2՛h-;!5N O7/D{]B Fqc7xDw GF,Џ+@Q=~zFw1>g2Hl6A8Ҵ[m'Vix*I:>׎{pc~ý9x'T?[nHୄf6үzvۥ3ehbFL/9H4a"xeW-sX=>(##gƷ'Da?Tܵ0qy ,.e_ [ҫݺ[g ɚ@j֥^@X̓\ݰ{qaVAvBt!ims x=- h\`Oke*Ɯj|i8p(!.;x]B|6wژW]fWNg>AO/Z+M4mhAë("xMigAe FfG7N3]^L3ӆgEZ];3HsxcN6.̓+۫%Bѧ& ;tr [~zH/F1\k\NA4՛ .4,#TRKDfӃa?A…l A | [lUZNc [hFLf`lhJ'yӰqIP9 *c $K| y  {1NJ;Nf\0lO]A} G.h7eD ?(e_ '(TJu֡+Wa_~(&^{_c!ӁѺKu+,6lKɧZpA 놧Hb"ws#ݐJ?ԠіȈn9cr\LҊp?2j=ӢF.F}Z߾چ219=*O(H1f\>9|~Up-5NmBcK٥bWzW^M3O8ʪ PzW?4߸@ Qd 2-.0Ҭ`AןVq[ZZNI`D+d xY0>&(0azW }> Hӊ$5mR l-4O{`6$Goy}H`eWy~Ac|)*O" ̰"JS+U4"@vO ǛN]Co ϼS7a߲%#ģvetVT 0hr Lx7 ~p-?7'| x~As<5:< [h#w3H$19 pFm-U?EC3(Jҏ*-UG^l7~~ql7fݏ!b8~JnYR埂yg0٥O e~Bi*]{CF)U s3}?:sWpk6ͱhAO08 [lVe'-4jv`/ 1>b짊QW2$SZXr`ƽ؟ƛ?͠f|-j`c̸'ȫ4߸gI 3[Dآe6EfᦍBE2npdʳmo+AgMmطEQ;F~7?dOVF1jgkfL30j5U %^2 $sZ}ZrpV ~&c2 !$v#)Q85z]v ~)|%}9?E (8&btEcYM]f^ƶLA`B 6iV ܔhʝ#f?miy2q-2o8CzZvޣ}lĘ^X*u~ֿ*zT\U%! [>r=LD~ `8nI;8} ȟ@d[`(l\wh8A#"1–?3˯A<ʒ Μ-Q*ZA?o`P|$:%K(Zx$SFЁ/*2vT!_8=i8 ^}Q\>RC^zv(U 8{Da$K/Ix}C m/ 䱖z7Ǣ!>FM#U߅2ž=b`)i !oijaW1HfMtB.:vV^w;P(^BtעAYs*@~Q}d~.`<<\-? v{@[h2 [#Q߀* ;awP-^%)eBG]70oBfMmd~&Q8y$eJt~B5L iA lUT/E*?* 3H$̵"%{VUY.`)P!?2HC-犔 +?4 H`ziSqSKeZ IVح IB4${U" #HV[/PYS[e%N߂(i# [巠FQ] [Pȷ;@Q~ X', 9N`lsMnc(p7lui>u1I [֖U'ht&Hv J':Pp>o4|OdmZäoCr&}YC0P%a$&m n=-c/;wfQI;wFMņ ~OT+|db&ڴI;&[O$:n8$̰(0&3l$̳'m˛_E&Sl%ɧ?. V0H(J4%a7lUN_Jͱ=o?MF]Zdg%a?( s`?( œN`q-ds(0&ϡH\x"̰s(0&wkV0a"n(B˴ /Ͽ@l / J_B6 Qs#(!e%DZ_f#8}xѴ}k2]Ne(6kj'TWP_!uSGRDk|*+(0ihY$=|$^ ;`\LK翅& ՝n'ZK[S};߁a/ a;$NpHt:c|"w&[A?vO sY]J GK$uD3-{0J5t>\$I Mv`&o3OSmi#LaG-ft3l#Ik5?0f~\ . 3:_k9ok2:_knk:8HjoͿ2 7hdu7 BʄOm-6#Sx!:Fd J DIخ8}O:N'0{ Lu~Y"] eg- eg-{" Ե̦3In;aO4/@x$iQ0km FI" f&;XDoѢKآ(Fk1 [̈́b@[shlPjsóLÍpR/P%a* s@&{N 0 dҚ@n,N0' =-TiB`CD`7P5Ƨ =V[]dM^(XAMy,I:%DIXwSK. \% P2Kw(k9%@7P2Kw(0ϭ`V0ɓ$py@.oN`Z_8]s -dIa,V9ߢi,V7ߢf 6$p& sjCځn$a[m>˻AKt0V"2j LB. ~?x=]m%ϩ/PRwQѪ"BZ[8[_kVmR*эDm?y0Go(3Faͤ/N9VMiŝK9\H}x`շ&u|ښ&P7߽)skrjߦ4Tv7 wh)M*~84'.CSC|9an MLWR\gN;}7l8a+qw\B[#CM*Tâ>ӥ֋n;n->3tݽ}{N=1Gx0AG~U#`7쇍J=9Y0_5l_w ~5:kЩo>LO+\5jƢ-`_Q\Pf0'_NL3#iBx6㖭O ~66 's ? 2ӐoM\C-[\B6u_AvٯU֐6YCF`+l4u#d^u:Y Eysl"ꏚA4 ڢϸμnQv醧q8ٯG}Va_W#>} ̼8 Y#d9\Sbr_/ M7ð+N3fi'n7j+|YkgcU#Mt- V>zɬ iZi3 4ުn^1#@mv"%<Ǻ6`>邵-S?VW\; Xʶuԛhm2ﹷR_h3 a*>ҫ~xAɑ09>$-uzA< BGo}/x)xOa6q'xtpm c-C/QM7빖=oX6ojx XSOe/& ɚV@h`DIQp4"5'Aϛ#غ9EOqW6 '?ɠ_]M w6.܄.-c$؎2 I-O(>Oذr 8ئv4>] BinxPNEC4݂5]2n1t\$Qr#֩g5ׁaOeU k-I໰ߕ&s<6-i.z8EO_4]SSASeE_ !xPCS!^Z Z6swz`֭׽3T1yJnv\}.HQ&Ĭ1YIB[BL 9ˉY[a;j œKh QC :d#b*!ZP;;ϗ8M@f"ZedPɚ1 K9Aǝ2\  F泦7Hos|Z6]+\O|%Nzz+ YޏeCN'Qȑ AY-hƚr8EؿS4~m_KҒZufe_~W绎=_5Uİu_Ͼ! i0&'&0bzr[{,ctFA,GѝH BuC`yXEstW7b;pzœ9RQ_t'yiĴ^_ L FBv)S^=Ԟ^֖rs#'s3S[uj^bŲe({|B!< [l%ic?U.ð+x+:AHo ٨yD"* =L"b6ʽ4aޯW ,*歄 [hԳUWS4uAS@q, fTTwlY5 }&56,`}x 5%I r7-4)ypY2˸9Kmmkv(ϖGE+VyHªEEO4Fy!J wҡM ⑔Ω`Ha%|fbŷ&n]J&LvwU"aҙ5X&m(qo!.9BiPwͱo-ihoѕvz""ǁg`g%'w–o0J֓xN{Kdo!M98;دOB% ryE:XqM5mDUy "[G2^GT6{BY;LMLw҉[}blĝ;75v' [՝\htاU6z%N9оYOaZt&TV͒P(l+ULT4!|XJd]Fә  *E2SSg㣢V^$K|7侁A<uk|N9Y1GiѮ [hKTUل#:xο3Njd4>Yl$t&ŵ&⅓D8DCGG-3:g ǥ_lAT`X_y!ƄbQ+/<6*aE/70(^_H`KV|#iL<4sm$jjCj-)F4ēu]DfŘGzD)3ԒA'%"]#g/T*x4C_~ | _{U*=s<3RЃxJ(--/M  $I)YÐҌ'EfU wFID l=߈u>,U30 /K r:'U2Ѡ?AB˄|"w{C^0l.Ч8^ Hހ-ҵa۰rmxW88ڂ=B Z'o~[a~1r`GmCdR~'}3a4uh m4|nHՔ=z,.K?T5*NTN+ >/}HRBw+[A!U'(5j tY̰ߵbVg+k*pJyփp{p^,侁O]ŢEa n/̔N4$w&ēu<1'5߂[JiS58Jb80#TNƷP~x[wux upeޠ;4`RrЦN[%_ҍx}^w %Buz ;üd ܜ fJ1&:ZG m[ :g*ܯA<* AȤ76o-Z5rsڵk- tދ"" KYz["Ys ;}[O:k+\(oKҘ1+T[il͢e$nI'iqF`+l@Ui?z_-Tp[~5AMo Y`x2!o`O41ISKfBaxL,.f,.%#9&I ;=l' EVa[x]izx뼅W d悲Vp:?/9~k}歪f6үzvۥ3eZtfvH-"qeؗ^>n,N_"z|œ\cq$,p(U|>Q?VVR殅c` v)ZHUnQ x{(Y.}9C ĨfQZ+~ѩkv~ F0p}bBt!ims xPPA{dM4.0'>T96x ׏{ 44_]Bw%1'8}Ex#>mi=E ^E僻 e FfG7 gfL7ڹޗD'֦ ԋ!btGxiaf ߶Z"}jo Zۀ]C -`?=Lp.+#^9ExzMmpc M!R{G (%2[xɨrͫVBk|e5`9ϛO$lO*'l5 Ryy|tS{3Q}>zK/ez6RVzW^M(>} UVcƪ/#J{\(j2f`V[rTxxLcZ0OgJi:%.u+fQ(MW }`ArqCa{-7FoMrw[\H0ë%]$%^'A"=]!=s<|)*O" ̰P2Uz\qb xɗ!^7` g)B[ QML2oIUAF|`N+侁A<$A ]7 *x@mYs< 㑯!i*/K]7 3ҹ&3CL¾*QdKբ qcx%Ru&yx) iQ6떐]1fuϐ]ϔf~ D`a.>F|4.=vԃ*9:㙾y,85Fulo8ZO1fO[V蜼>$l-4IgUh{agpMe?U4=@Q/v k/70q/xs—{Y / lͷ/hQcƍ ~@iql@ 3[Dآe6EfᦍBE2npdʳm0>ƜG1[^NbZt:1F<ԯX3zk~T\NOF환+je%L&뫿^_g1zgM /='Oъ]u(}-=>Ûj?"o(+M߄tfx$yt'L\vxmoL7{%qa7ni _Ћעxz{ysq{'i},LIQM}8eioAbISGxAia#cƮMGwo@64x$Kfwj8}p]%!l-4:m\T+ZTvȦY$^C1GYęs9Б$)Y:?Eub~|qJ9hM;/ sa7K]s϶~EBW$L1ۺ}`>Q~ypDI"w[`_V@^^-vH{-J\Ng`d[KՉ=໰Yس(:pbJ !o1x4wׯ_^_K$ aw+/;Wo$O ,JE|F[O(Sd~/<<\-? sRga; B9 [#Q $ݙBxЖ A8y2ج _4(<2%:p?lO iA lTOE*UfXs0׊fXs0ϊwSHTiiE+h9WD@fX IgEJӫH ߘZ*֢$lݚ<$I(r@VD`V$A$쀭' jD֔vYBiD W!_.Eu!+_B~ӡ . W!_0 CN[\SD'E%I[S]:%IتN@D ҙ EVP:I;Ryä{"ä_*MtkPi9~ YC0נJoC6 Qs#(!e6DZof#8}xѴ}k2]Ne(6kjT;P uSGRDk|*(0ihY$|$;`\GK翆& l'ZF[S}]wYSKBiNI.TgO aDJ{`1Z0$poJ\GKD`/0ҿ* -.T}^3OEV<$̰=h0f3l=-fW)i3UZ<f$Եy^3M.נK½Uκ$hkP4EFB5MrڅO_. pǯѯ|M4ZLhƯDGHA\~S6 ]k͡qJE-=9>yzxG= cЄ?_>gNدCT}l( {:8+Dd+wլHBFOTE}zIwKAQ;1v|,Z>}0g$.6^{؝zcڐ;`8nԍsч_ÝqUF޲gsh#1  a4~F ݻ;9Ne_Zgüp9ۯ=LO+Ÿh5EkƢ `_Q\PV0'*V;+gF,: m6–ܲlH}L8w $S&֡ lxqj sۘ;A 3fː1Tn-Bunxd,KXH oe?5gve~tug&h)=}s夻9D Wan_W#`e[(xsE$9l@ĈG2Y(Ͻ냃7"0q{ݹղ1*L pe,l xūիr^q#4A"M !?+5:Fm `@=l}uu[`Nڄ􈅶 /(+e[‰Sū^}Q $x,ߜOpx krAd"=&M /HQ:^nA#ix@QXD1HQ'(O>,,/o~ -#\^a؇Ei3Ϥ_9@#< |sKO=(zjlU0 JՒtނDXgQay'+kHqy߄=e~pP6e}ةxݓ J9bc([awV0pzɚ|ROlNGaJ:{:Fud"wm,:ME }#J֠s1/Ofւw2G. P *WJ" :1W *y^avŽ8c]ڛ Qa\4f[q-]&Yuh2:0aCxIi{j'}ڜq\]'RPjq#h .p!dF/saħHOn'|W a 0:/J9r,)#T2đQ+dD< v樤{̄vm4zltiz8{JI[Nx؟I#w@}' vP¶\xƌr,%(YӦxzˣ\LjL7jG' Qj`P]wIa*şw2 r)F4ēuA<ĘS{Ҹ44oD㊠1kFs_sTLu(țCx^}IydۊHtܽ- | kR#:!$*~ $r!b?ݡZ ΘÿOt`Bx )pP+e.$pg R4أXrA8Br Jւ5G5W6 fo[o' hGc}}z/aX0]/To~iD99x/lEF+Sv1KI-NX?O &^؟(+\~ df|A<<[8 UtпY?<ao_3@~bVV}OH÷Cfn"3Q/l[f&ģ, Ik_VZp侁Aq(\ѢHWU'ȪQi9W:|aWhVBx6TLUd!ER3;t[[]P [pA-ڪ[pR5P*lG" Xy r$l-$)Ms "iJ݂s$lV݂BCڪ[pS( ;-^* <0s ܕ*=p2(Ǵ7%1rL{HvC 4@ 1M# t dL{ӈ" ^tz$ܩ)-mހ wiiND`7U[uMSZڼ=ֹ)3m=vm)i9oB73͚W:oB7!FQQȪ&qS}&yS[q(suT;y`otf,0:Iة)-evihNDkHKCaAx@[uG"n U*zjlrzqCu.ND`S[uFZ, `+(%@]()dF}|#oYD߀,Yo@o*`?MF]Zd&DI0M0a<f8|SwO; 7@2Joy $pt $uDڀnAy0R߯8I;]6dy[˴ Yrn>`-mȒ0wu-.wJv-;P-祤;("wL@w4KI[H%ZPz]뚻+x܍Uڒٲz '{Z٤쁮uy=d=Me';)ZP~k5m7A_dqyڪ ּ:MQ?^ƨP]V8g/Հ^4&;IBWf uF v \VBVCdUUj{` R]/vZ rw0GQs!^Ga>%jugO xE^&,VfE[H+F"8A}Ej"'Ej5uZI2ɋDڠ@"hI.R˪!ċԲT0/Raj qZZ~EjY)9IEjY%A3@rvY:4%Ej>6m2vmvufp^8qi#u4=ku+lGZjWnbnR9 B("ܤ@^^M ;[?zaR_Ha uc*r -/b2lM>q:cJJ/ZnP'p᜗t !i=tB1pe0gس܅ el={ Rז:r+@2!g}_kP1cRRec^a-ը)ar W$1R3kv![[a*&xl [3"!q|PߗJb fYWZQ#vmӰgWa/SZmD$2l)sq1=<6~xr-ԏ LoUJ?nOBdqo^"I+jo&#>C~Uڴof)$Gzpg7?ٽpQˏvHpMA =h5{` 3z}rgN侁A<* Kg/R&F@9NU/o!J{/DŽn6.wyˢփh'>S\6v.HD5iBAj 셭fb; 3#r/-߬usV,{sND3W ~#v8{Jb7{l(Mz4]E [o3:n o4v̠6]9Ro" ba?̮mׁaVRW/^P~$r5>H4iǽxœ\Wj,Xv0B0{{րQ\0`|ӓTE#3,@7 u؋F?:9n>EbhЀL hNipn?%i r M7Gyg(n%m@κ8 {8ZW-_-?KKA"uL?><ޢN,/ Z CZZF UY=)< : &lpMߵ[ԉ-`4iwNw}줓\%O7cR2Xtt7uzl`z!ZgdJ-fq:E Hm-ܵ5;< ;=6[Gd.`'m*w>~MM6[R mR E "N߃-xj 4&{w1b4jR7O_БA2R`h t jQP4-V^0Ǟ;0Sq|qhg4m*$>0HE \3cO-h2vu Ҫ{Zr=Zu!UJ>E1IE& +źV;9cB}-<ɧa m7s(ЂmI{A<4޴kFx|6Jƒ?CUv*M?A@yV ^幅&0Jy{ܞq8 Q2,Z.D&y@E yv*.D&yo@EyP@z=-i!HKɔ6n`+lvOGB!I5kisS8&PsEivD(* YuyI⺊I;R :5|TH˴||!̰$̳Iu> >d`NjK}}QS1S+ !}Zڊ[<2&[OC5\;dA o~Y~D?,?Y@*`?MF]Zd$p$uO:C|~ -dV" 3&}$uDڀ>E9L"IA &mr'G4L[x4[x"a o@yki͐Og9)NC䧡i-4ȴH~T乷Lإp( bT@eY G\C@mYd^-- " 2 l;֐6Kea$̰* smk3lkfJ}PPy chչ83De+QwhBɴFQT DuKAa;1v|,Z>}0g$T4^{؝zcX qNjUMhk6*cvʇqm$fa|!L/(!~{w')0??Tl-,լ\ŇbWƠtX%s({(UJ&Yt Jr#l&,[ ~65a؂̹ܟ` mW 'E:[_[B6_An;! y)rԍݰ e;*UiVYCģ(ko".nxSⷬ}=4 ηRRgggu,xE$Bl@ĈG2YW@- FdMNI˥7J5YecU%Y:k.Woݰ, &kXH߱ks =8:-C 'ѫvI]K^/¾(_aA<ʺ{ 4E%ؗiP1ɚf@5Lqڨ-Wr5L-CÝ Gz^xsx!j79Pc˘ sY ,zmzTͫv^;˩Ќ"\a,яTQYmsv5iQ&z-]\Au jݘVqm/yf~* -͛Dq"lѴʏvvm(ABM h>%w`iNpBE=*qڻݰEi!C1F1ǤuK q)اvGmO^@@>u+Χ5}Dn[ QnOx` O; Q]wnB[B0陘T[-Z})r\_I"WdMӰr7gѨJ! ']8>}/WcMԮ7D p~>w(pDO2G+W1Ke z=O2jWA_l"DSz]xvknJ6 y4pA<ijQ UND8N4F7!J u.Wkעޮս\sXrO*1<[!++/W&V^l֮_ yqji V#:$:W'DZ /iV˪JB(\%j-Y.}m )oI\گEK1\&dj8'ڪ$ ǚ@4=Y_dj5A_uwZfǜRXɥr!;=$HuZ-N6X0fv@zxL3 wj$3f:Eado0; 2Gq&6;U7( sTf&L: ָl?^;>S70(kW51G2U`6Vn7Q B*:!3u6s1CݣK\I!1E[,-EӪ<D ^,-iӪ#Iۀu(T8P%a*XZ =U B^`p`i)kIU27(Ohuß% nz%V7$VZ=QƲL'P@NhuM) f'G:7͓#~YmxHyz$Tw_][u"m `v <Ս:OA4(<y${_|<E$~Kwn0; U2|*Ok9w>O#k3|* |.`zqq<eVH[g3HFM#3B][uBZ*=eƳsP)}@J.1; YJoyq, \qD>`ꊓ$z$삭rKwuMv90Q90Q<f8?QœN`zxKCC@0Ñy(0ϑ7Rl2m!a-fCykiR]* 3_*/h9/\2_*/h*;H.%ZPz]ZE`N;z.F媊xKhmɔaD[WZ J?LTvB3h$NтR[kGۿDImE FNjL}vCy? 8U{P+_ `MXd:> WP/-'j?yN\s5BKpܯj_2kv Wc(M= sEיs*w}xsEFL8hr\MS.dgkDWoF_X%+索K2hemP  *u}i%N,M8jYL~ap>#Tq^xQ H40`Q9: eܼ|IoH~M4R-@:6lb_|{׀G] F~i&͠(yoae{TagM7{{րQ\0YI*Bk^x )h]%3kn^4JO9שqˈ/;fFvVvʄoaP,O tBh|Z?Lu&MinwCU{`(iwO>~B6O–_~`+oǡ_gFϮqby lv[i_ژPw;En?k.HeA){$mק-;TB^tZ3=+'V׀o@_; ΕaWT􋧀oVnP1A-b{'W$\91 ^ r{1ބ\9}8{Nh>r` .^ʡ)"πXp2$&PZEB}ò=\2 \@T>B<[~tW)8'f)G)u$D##ģL ;vp;`5z&(n~4<.!{u5!;3P^40a%LS|i$:"]f39Du=+zY![a WleoLX˰/gӱhƻ-[Abō +,]p^i<W[*Ͱ{[)׌vIo'W6l[r#hS=eRXOqMǢ2[Ϯn:9Ϛg0YSDk?v_6Ufڦ-ߍݦ  ;iڵ | PP{jYӏ6~0`C`WUH* t9y?0p/ͻ s]s>PEDLkQ) QPD:e钙fϜ1 gMi&; ھ;`lIZ.s,æ=88 g)-*$kt.nWeb6u (mS²=?`_~ `Қ TSϝUwf/9!XhoVqlȽuygRRI_3m*Gu?N&fNf$'A*|vn`7nܠ}ޡ%u0 dP?͠-+o6fQMQ}"<KiTq.GsIw w;ҪSY%{]-kaLÍvvp7D4l@| ֑>}_<LU# < [>W5c>lW.=b۔O/5`Kz0xQK?i% Ea65q K ݓ&ujiF@P]aY'ߔ]::Pg<.^{9؃S#Z'ð`uG@Zr/pPkZ{`##wa!| % +ź39cB}=b7GCo߆2Q'Qے- r!xdOA]o g|F\(D@XQ(Úve>>ēu(JW/=ocN9W1ZoV|Pxi UbHQ6ňF;xθȬs\)q}pxTwYܙlЍt4VMnrMLP | R Jz?~B'~nB"Rmx:D€kAtࠖ=x#Ebxu\ֳ\sj@ ĘR>Y6 ֌U03)&|K6ňF;95﷐Y1$p}[)29F YV װ}u8/e};Nty%w[b բƊp37\w%Yz +:n\4os+{Vxn{3 BGW@kbxԓZd{! >.MW=10T*f}P$ K*' 0"d+*BJ7vO%ܵk5!uDҊVˎn).D uB5kK9Sp=ƙIk*.Y]XK=K.rW l!&m+~r Bw#—f#* k6r̰fS"j"; >ܵۻpcvsoCYr @i=@rs-/J'. xģz[f^տCF환͞1L?(#:U}}z/YӟX0]/To~iD99x/l4G+Sv-͒,}tAXo|7Nj~ecӣc\buOa,L/2GDZc尙{y3䗆{i$#<XcTS,N4E[{ k/OπABWPr(E|KAZ 0%=CFOwj2zg|- !bBnt?lthAP:L1&ܮ NL8~j3C(w*Cu͂ͬD/sزraX$,!lݢuCla}2J> -4{ ,'iA<ʒ ΜvIii$j$Kth!4Fkڦkan*& thifQ V˻eVm26Vdl 79vJk-,ilZ [` D|(C؄9 {w,CxHJYOfFJv+#P'HVD`/0 $̳$]*-Q\Ej-C|u!JQ\ E q!Mm"A.DjW" I( .٩ HXSb.@ HFM#d[O_ P&~sP)-0I[CNޒq$>], –_O(섭&Ht$삭rKwuM>o?MFBr2| Qf8 Q:' GO!ʧZx LoQx[%(0ÑIH3)-Ay0R߯8I]dL˴Y>rn>`-3Ȓ0wu-)R'ŏJ Ck9?FXt01Tr0ϽcnE Ĩf{^%Qb7P ,Vy-*ȟfQ|5#/{`Pۓ6ElK\] |r$l`-M|ITIaGJ\;"D`/0Î@y*.`▖pǀȕ̟@hN}Q~< J'Za@hN}dV*$^PZ^Bj9/{ne)I%'=]( &9s~X©'Μd:~m>sB\mL8 {ZpHА`zan fY0p#+,bdVc /(x~BU~R 7z[sAoc9eL`>1c-A 'aA'23f&3sW S$kf:d? zA/^䰏dD0ɡRAHQü=, nO4r}ܝzs~ 1> ݗJ&?sU NYRJ1w#wm>~8xbz7k(kW) z g{UBnG1UnPsk8^fAt8>r![#+ oVoӱCG]lgIC ≭M/N6BBPDolTOơZ1mSQ [nKױ [v1`rK;^ {eTC!!VCKZ;8ģ*k#8w..j:U3\[WE,vZ;6b%"Ɓ8GضŦo=BD!V'wo͓$0jdRV-S ,H^@|2:')ur5UxS'8")urTuTT'[MAf7x[mLJV&ӓd9ZnLJ\jdj +!rdLSfj$< [jq8Y}_e38$}~RDL0.&Ye+Fs@|e7ra#P˸e*GX-9²mGXcP\.}ЧN ԲVEjS"թAZ<\=1A4s $亢IߕHTJFX0ִ+)rZmJ+LKG9ē6Q@GFPюkyEL!#Mt´YPO.REܵ5Vo.Ic-Ii4ky8SL}W!7_VaEϕDC g Фqb lqBhzu=8Tk) TID&z*sYH,k @$-ӳY4K_D@MLg!MBAN] VHن290ŊTIiEJNSHuzVhE)T"4Y892HL"4 H0T~k$Lqk$tf& I,g `r3_+Z}~E8I8I8;)N?Ln~i:#3L*'YäIree¡ k͝Iy3=aRgLL LB H)(d+RkC)C `P%a%?''3ZR{$L& 3m0f~e6$0f^ j3¼2n00f;n9f&"]vuנ3Iބ. S ]dD!R ]dDɒ?RȽ+ŝ9q sS aǰQX8p)sLfC(!KuC(!xC!KuC(!v&zΥʇ{T#K|2|>B|Uf$:C:Ţw A"R.B,"PcEhL,XQ`r zd | Yx\א%a@Gb$C(j,z<>ҝ{bY} Y>NW!YK1d8]>,g,ǐD%*}(0ű(0ӱ8VzEf9V"Jt [/ r| Y>eVO!˧, X>, @PcIU]k֪ gP%agP3p3pT9^C $X 0HY2δx`uNYzyR Z^d^Aځ#L r9A2)(Kj9 B L!fU&KP$a]e?LUS!eː2erz2$̲=|u$LC~缽*ڰ@+,}+&p"!@Sq C/9_8; *(ZuģfcA8;>$j w3Tk(3Di̤c-RAÎo|S}|Ź[T8DBԤ5ot}L!<;ŋ;eз/ gOek )ߥA!S6C(A-նTh3{6c0}х_ M?!^ocMWEw ݞ.VJv 7֯z޵}xZ+KnzXKY*\_z׮^:3핉nMT *mNP%?cRhx&hXy ZnS+7rviV+T4jFt5=rgPO.cf[jU",r?!j\:}Ȃ(&K_(rs& ar'-{RsVZ V9\GriP"w`Qל2Dur0]+F> ZG'`HM'9< d :ɜ!0۶QY1s4$MjþAA&o䊭Z rd Y D0ɡRADQühz2^O4`r}ܝzs~ 1> ݗJ'5ƶlk#Cxe܍BѷJ!;s(b$Bݣ]$CT}JC|ą~"JQx Fvl%%bbܙLNhlzʪKn wT,Zͪ^d!7N:?YuR3WÖU#O`s|yE:`7t1cfM/Nf/þY5 B刈\ނ-Ah7, $4FX{txSPSX7Q&(R |k(Gxv|O nlqzLtMTڔ,lxկGRdxAWQiz#3U鮉FȭPP[>u8._~cXeg.{5 P_7Wn -oիH᪚<>șU/bƊmTԤVxQ+i&2܄!R3GnЂ" bIwWh~} ܡ|Į3Ɓ_:BB~A!  | ipaq|xR_˂Dxb  'omE+!JmU.K'1~9Saqx_3m^67G_a4\o<9։ jU]5^OhSWF'״U%*V11kmL3>tljXM 8`.6xSX׍zaqr̎I'Q1F#ggA~CžH_w3^ݼxޞdl(WQudnk%bYq[@z2Tn cN{/|\^xpoE(`Guv7vIq75;x9(@@{eq]c5nATtdƚku`BVgfB7Ek2aʰMqALOr'$3'CO}-֢$JOD棤9Et  gB7݂$o7%%[-y Z|`?lR"&mִ5,uqX; ]H>Ѳ?4EXwRm@wX-Ib~òm@ɵ !yhgYcQy0ˁ'70:\=1q`hX.ydCLw̻HvQT)jlI.I.y;¡Qr?!iC OzdՂQ v. )J{T֓_@KX&w@՗&] $~Ňp N}W!7_VaEϕD  q#b h['6ᶘB@Y%aKj.IN~6χCpb}1>4"yڥGQD@-Uɔ;ZV/ .S?< t=]C"}UX>* 3H `#0ˊH9T"K"]4Y)Ѐ)V&a)&WO~} I85$I8`M~} If9EOT81D} Q>fGpC!Ycm(>+Z}>" S{Ef:Ii5 0?%3E4ב&=*TIOʧ,aSd aäP%a$? aI  FUg3hKV+b}Y>*Y{$$ |ՊDAX4KI1ٿdָ<" SlC6Db$̲'DWz9$:I`_@/X dI!OK%KuK%SܶQ"0TĊi%tI8[罹QB-\( S 2-A 0 DIe 2uF h\NWr](2D@!D䜨BWji\aǙVji\aƙVLT NU+U }UZW*T*c*_%P4~^T!Jkq#%5K Qf6Q@^7U\c`X.]m Y(f"0XjU2 \bOG-?XP^f[hv;#-4Ixv ;IJ[-4I_$'Ji;Oww`E;;$Nt( :cb"$`kMbd+R뿇* S-}Uf:Z"')* -aRT3/{5$a$a<MmI`|]2 Kaa7D`b3$Xvµ|ի3^.4-xT UMnC=X#?}l`0?ۻjk;aB`yd4̛O - l _on(H_uluXQψ[}rZhV2I'uD~%rxœ*3ڋ;FB%_U 6-mi9'΄Ӱy ' V^/,ml7 Ԅ{eE k-jXyAW⧘rC<|t?ljuѝGa˥RƐc)cF)["FuJQ5(W\Cs%Aڋ,"=cv[jU">~v/8#]mK'2XY"d7J&}LjSSS$ۑ_-=e}f|?kѥANf+lKyju@#Ͷ83ޭyMOvwlusWS(TI8؊T?I|[ܵ{pT#Д ǵ3٤;^l܉ XÞWʶ{S,Q`p Xl0un{viKmӰOǘNL 3"5%g9ۛQ($۟}.܏s'mH{ ;1g3B!6qFC+kW*|ҭX[$DcwlJ%5Nn:49>0zp5 0z@*gJ{^1+Z!e |oQz⑤D +Mk]{t4׫jqݧ|%v=ބ}S^cjuJriwH9[FFTzK4QctR'vaWi vJ0p8v ^*I9(|bA&F3Eńr8{$֚~xvㆈ{{5PQWz?_)W+1rH kҦTPi8?deہ)T95kshym/H=\CU"[ " zpl#ErC r4p;Aor'Z%@wCjLs-t'9ē6>@wOMN7P< gZTu۫3\v*G3"+; ]})});Dqe+%qHU:ϡ݋f;%aI5PZD)k}xiV#8M #VlQeS.%fX^A%Qo0/sD r{rb$8fZ~=_QÞ%:rcVQ4fR9C^wbּZu{3hfQsjUo~@oSнu~a'\*`no3z1Ag]i*ER4odUḪuU!| r~ ?>4fC/ZĠL; 侍CNՄth]7xSe~ -,i7-| jJ8[nqRjr~c;PM8S|S0mV JIugzœ g kxnj^#Xjn͸4-յO[;ee?ҸXzW{K?zIM4ö^au1 µO ZU=X-qlZؿi-dd 58E:r<r.uhaET5clMH4'1)*/ BnOL29Pﰈjt`KWL+n?:uԟ+֪7Lk 颈j_AԎLӫe!ňb/Vd[2%RXQ Wջ;ns iZÚa4$w)뻗*޷Da oLI8Ahy1 \蒟eF?oPDR dfͺF,y]b;tGݪ)F48hpbF2 W%\+=+}; >.ۼg mfTE 6qsD{OLʆYm}ʹgTT1>n2ԼO i+K&&q/V wiðOPڭ9mԕ |ͭTmr5˛1UPbQ4 wo u»c,wL?"|n^("ggFgFboΎ9$#=A=Nr^*PHuN`'C#< [&'%ܠ*Nh<&\]B`9%x} 2{c{~3TnA10mMy xRVIfNDN$V wt}-*Pm3*M  bE8 B!=Pjj\wpm4[!J<|g(6W""Ek5߬ =ȒMV߀&\#B h}&Ji{;WDy ]D?Yls`k SO)kG\H? c.,G[< jհ +7,A ʕ c b P!]D0ܴ_*RKP% J#+(6)ԿR2 ],ppL!e$Ot(ʔhSj41.CG3)-\DEzT+P%a TIiEJNSHWJ,+R? L"*S4_T+W+qEJ4`+H0ˊH; xQA~!I>xO5$Iȝq" :GOLB}jmUu~qqu~ Et  秆I t#3L:Le $qR>pvSi,@m'? TIQ8}ʄC .o_,Bi qڥGQD`aj DJOGa&1ZZ2ʕ E0R$tD?uhUf9Z_*O5ˆU\& SlWILy"0L_&WY*xm&OF} 'C?Pkl}kj@rzCR»͵_}nwk73?[^3GRf W^WL{b[ѲSa>TE7|"3C*VMͮ|٥YP nZ..}[Q,=tY+qUq(0?ۻxn-۷k;Lk=0[DЋˋPPRzNCv\MG~%Zx¬U~3g%Cw@J޿}ҿV3-mizKVk g`(N?rC<4^Xۂn8 >"C-׸Vu]1x~ C~QR)7z[ɱK:Irq'9BFZEjU^ 5RyBb)!'9r`}.>dAxe@:gR bg<Ԧ϶oGQ=5G_m5Z5R e)t&xZU:{H>:f[h Ѽ& ;)H A$pv|E-_Ꮋ8{B`G4Wv'V畲-bJxNT1 ݞ1=[x+@\.`vm< t=dg`Q)t=!>*>~H9ē6N@=};kŭ E ڙd{y8}5kҦ WVuwBtEAwKIbk/\[S:R'簟'_>BYmwd^ʚhGf oQ㉋.O7J$ZMS~ᦝ(>&} [IL`Ai#o?YŢjnA]]6ܵJ!(sAY=MS4s%]y֠QrW%m܆ס=I@r'm!&m=5%,}@ϲ&n{]װ= ~RB82;aK[)0KK_OLo& 'k*X) zQB#YΨҡϡ|7b8Dix ̉X{MQ]LvD)o}?xi Zm]Z7Qj4VSZ]~='R2ހwŦt#˝To?^ :(^M `pZ+r1ܱc΄g{itrx )Hj`뉉(2l5 $*kD7_FÕ-QE ?k5W4^Ù]ToP OuLܧޭCIW%ӫ݊jlZ9G%!ܢT= !Ɠ)AqnUDCuZvbZRM+ЏbqnG25װN!waKP'V;͆^zdg}HF侍C<5vFuPh To062+Čd|JCf<ƿm"'A!؇b"n/0lvcݱUl\V=,-r+ĉEUqvȩ/_–l)MVa?Ww$7: pҥL䃠G _/`Z77ouSN9qNÞN^n8{F9M>!| [W9Ea,ԁSF!b \ݲHx0ų_/c|gcL+\%$^]*eUDssp#r/a1v_w5Q ~xY~p R:r>\C_Ú_ V7Df#!;­b2c|{K俓5bdqíKHí--zVKr!i BO#>Nd|AbҪ08*۔G_>1]ctR>1Ҧ\'&SQW wiðOPڭ9mԕ 9_s+U2F'4^ g(ℿ ǁ7:kw''O8ģc&_]'&ٲQ؛W$#=A} !SiUz)B߁ ax MN7du u`S#k" |z Mr #̈́R tAMX O]9$xbK0s"ocpϋܷq($Ϊá(HpughefޙDI.#Jź"&u7Di-Eamnہl-mYAx )? -?!BnZ5L)1H^ypTӜCD$HJ!C(G`W`Q mRm]Y4 `2-@$Ot(ʔhSj41 MQأȔOÖ|"g%TIbEj@VD0ŊԀ* H00ъSLEZ4,ՊiY)L"-BYVKc*ҎB+UZt$ݗ'p \Ct1QAPd:1AkL 5!0lsG$FV&Ix vb"iB}jmUu~qquP$J: Pp~j$T:LzUc!kS&* &aKj]=4܅y*q:dtjEL:T :ՊD!utGo]4 5V5&ޓU+A)6%(0&SlKP$aM<&w|Y3MA~eHR!2x_,,|,leȒ0|OC21P @K iԂ.-Mt(j bKr}?5 TiY2s$ZV JL0 d@Y0 ӢKW" SVHL{Db Ef%zQ*.v{QgV!,=rj =DIeIU]@"EjC6K5 jC68 jC6K5 jC66 jC#,(h™DIb@˸ uPBj@˶ uP@dzXtetAP eHvQT)jL!T-R$ry=&`!Gx4I[**)4IxT孪O"0~5h0=e$'Ji;Oh],޾XH7 $Nt( :cb"݀0 5Z"%G--ʆP%aP%a%"phTIh 觚e*y~& Sl?B6D`b3ȲmI`|]2&Rm7!Mq3O)6&Ʋk)`r|O eWw :NU䯠K']e<1+_T']e;1+_$'揨2kh,~ m)_#*1$T;\M4 3봓?BJA)$` 0AY0}C2]@aee'#@ I_^'r?!ޞN\5Sig%([u#YJξg\ r- N-$j&ϻk$IE! laiB ?+^蓾E¯릿 ~4C*[ߦ2] o 9J`tu{>Xo7߻VyⵏUkzez-WK#}z)W3Kk+W/}yիWgr1]֭c/ŒnqQMItb&h\t snS+7viV+T4(.}[Q,=tY+qu0AZyp 5ȟO -*l _on(J_uluïSg_>9=4+q[jUѤNxWbu(/p'C>(c,T7@4ݜmgiʼpG Kw[0͂&a/^f]>K/F^87|!G9 JJ^K=Ȍ=H])1xbʘ^6\{%btK^d amuie?!i\:}Ȃ(&q1֤65}s$v&D}xj9j+-~r\Zy\-JASW/kU!2niu3$tawV w5$Hu+ۼ'`O7ZMҭTs'V畲-b}JxGHT1 ?=[x'Z\.V\}Ab2nYv.gvY#aJ"]r'7]QH·?\m#O4{ ;ޓ .H7[ n_tk؎k+GmRpd88vU //s'xތܪ]>VRt =Jz'9Emƍc#R;(lXw <[.5>(8Hj5n{Uuy*(HkZe kWi/81{A7VU6L0.YcHᚗ6^fhK%1o5by|* J ^I=j*M߉W W]eB8 f1+9s"ޫ!Z-]w˓uJ/%U.}(C}tjќJjkitWvT7 ~]*rjDlJiKrF#\4]}5n\OފR72jdz7&ՊۛH2,jN k)nN݃}/:1EJz\fFz3RU-7UƔ[o8I]+5MA>oҙ+] 5=_Gs*RA3|V0aFFL8Z hYosz~ݰ -Nfa?W~qopG?3_+&HjDFr[nO>)ê7C3h/.fcʖ}KO7_>4[jpLV~)\Ai-طomc1lgirC<1)Mp]l|7GWOơZK'f ^WtMv`KŜY,qx.p]qyK3l^RF7iÚaiy_DMB1Bu-_x?ʄa_WOĭ :ZS蓞!B.v!JgqK,QoIUj @8#h<|h426B}≩Ǹaqx_3m Fz]zkNj'[洕W 8a؎' ֜6zymZf?z7&iG\ƷEDƋb+*?Dc,wL?"n^OLje\7gG9 fԓ |Xn] .@@N7Mmzļ\,yv2T/iR+N+ s%47%З rQ޳ ]nU-0ŊTIiEJNSHoAYVhE)T" ifV!,㊔h+ې&a)&WvruW_٬֢w I>y$lq-xz$ǁl۵I$I%$'JȧNmC剹I tg-OMOP%1އ,C,0 އ4ﳖ%%QnD}%\Ӫ&aCcN[$h+H(0&SlH,x?L)sHKu|2?,T ,Ȓ0|OC21ЇC4|Z^FPi+ч%lFɿT *ȴЅϭh%$L1$4D)AY0 Ӣ6o[" S.B@@?0"IeQ*.vZ}~ Q~2>F|Cb$̲$CϮ{)>*T,(c(1K5 |̲>2 GXRQP(tpj%a>*'P哬 JIO'+ T$Qvt ͧPSfФT|Z J"{5SS(0ef;A’b|Mg n'Žs*-BϠI6*ͤC>e¡!`m"D|iNEaR['&&[@ph%WjTIbgTIig}Uf%:^3lXIϗ$aKh0f Sl_B/Y ]ov*1!dUaKRK%SourwZC9WyEM(w\-*;{#{͝ȑrsDe! Brdhﶤc{&Ԕ91DN*USsV 3-[F9JǏrrG^-oeCdt4|F{5 >]nݱU]M j'c+R~o w6= 8ntq5pnST۹u1W-A Ƕ1 Fz/O>crDdcxyeH׳M(Gn8xҦʫSةMQVJCxbjk5ak^P'5 a39{H:&nk] OŽ8EnV/N{](E_"i[ݸNx xt2dxz(l]ͭhb4Ӣu?UX}u5pn"\LiWRM)b2uno,HzH[ .U?hU+;ԑ ={ma_L_Ixbz7j^@x$ S*,( XӸ5P5`mB"-.y M-jysvޫc F0# `xV2@,A1pv xD-W`7++kدy= dXuOUw]#}lJt7媻m$"^YBz ]A~xBp7ŗ[R&. 'u{V ǰ7lZw*5W&?69ĝz1%F#H_MKGZbvx[r>lZT' Q۫sCtLB Eʂxtp'iY=/ rɡDJLW3 _ӭU \!rAZ]1-t kvFGT4Tgc  8 {4n wڎiUjF릡&j V$\.ONϯV!Mח+ǯXeRg on(_҈u 7W rkQ998}^dLcz9cM0i"Ws?y%f^A\|Eۢ_TS{jnH(C8#Y:TQ7xS=T -Zqov0$۩.?׊[܅׊/pЀˣѮէZ٢-&ج kf&#`Nxtն M8 iuřVAa;hxB@TTu%}&.Ϸ(dZc-vU /G!3Fql-G9:-h/Z`K5{b'r |ۄ;?<G7a(=!ӒYӦI,&ț|@eԍNDȺ|T+$3Wrwx %Ux_^>i4`.sSG:ZDVAC.h-҉F4\,T]%-jy“{+Em~Ya kvn"3mðsnsU9ģH~c1QAwuhBꁴI :),HWz, _ p`F>ˏ}SPT|L}_+.^T~aٮt8V2 rjl5:C3,]܍9;rMr(I7R nJ큽'6Hk?CLH(eI+1K@u vE6%RQڊO"z9dKU*$,pzRKJ2nW ?}GZR.tnx՗{=l!DI1#$Q'0SIJƏ9:ЩUuUT5<ǚtW-Vǘ􊪑_wv L9i(uW[D"z٪aS\Yu>&㣑t^eqTe*>H#jr !.(SO*=2Ĭx"SDuV?fF|Bh#f큪g mIuP15\:F9ģ:^b(iXdΙ{`U ֋~^k^+"\8QqHuѥJΰs7K_h+w,hnjFƅ Œd"H?[^Hk Ύ0zdvL{ o0>AYR7!^ZS:aAux ҄ܠPnHish`N"7khr/W؏W&OǢK' #lqSj%|O!gg]/}7P 3reaoBjnKG|1JH JN8OGxHŷW`)Wƴ`{TO7AmlЮBFuc^CM^*R۟aFiwWKr.G%wŚrơ脆tg"0h~GiV%pReh&[9ްhƸlvƶ]T SPrt-`W!7_VA! GpzwEJ@"px#TI{qavIwL mR͕?A?a'H'$Ot(ʔhSlMI'Hph2%cӰ蟨Hن.w[0Ŋ-TIiEJNSHBYVhE)T"Z i2HL"$̲"%c*ҎB+UZT$ U#/O$TPUD8pvHwBn_'$Z}Hc%<I[VU'gPg$CV'*O > Pe:L*@0!LqT* &aKja^7G tjELdi@L*JԀ4 h夬V$j@S&Q$`kI4DbE^$L/B6S"IeO4L>b\eW!U~\eW!U~$LnӐL t \.2$5r i.6%C@AFנKr}?5 TiY2s$Z%aA&$4D)L0 &dZt^n:AzH{HL{DbIezqF m\gV:˸\G搘@!J,O?L +dŢ]X곂RaEg Rg'v!N2*Y.o+!*YEK'H0Pi$`kMd+RC)CCC `P%aP? L5ˆUﴡIy$̴'yYN' snAk5,L،lj%AFqPSP2TM+jdu@#Ͷ83ޭ1yMOvwlqWS@I8؊T[t{pr:U=NT BidyCw{opf C08 v-!eV.ݍYYJzË `ڒ#cX1J~7co7kszujRRWUݴ$z(Hx_N?h]ށ}'~&8[ߦ$&rC<4v{A"#P!!&D"eA<:8ē,A,}'3zAftgq*5Z5 •-ob:aP9De[(/HX}o&?0#w1RT͂ҜJThe8DmWYAP $‡*34N_7C/4/W[eҵn=yB]`_RiD:+]ބ}S}Dr"s tz2kah~w7gr57?ZlkU6QԹ=y*쫱e7b~z5cW $m,PthC<2wO/tp^U,FM]$L6iŊ- |_v Okſ<0 5#Ucҟ l#xJMnSWUO :Y*_M ZF:Pk7{tGo[o_޸!uŞB6 ir'ZMp]zVB%[' QjP嚷Y\T+iNe%Oߣa;SҘXiLjW Q&H+wR 2:dEXxݐC)gʉ2M ۮ =; (ntVZz2qyYճZ6[F%W!ʧƎ rțE3K,JagP>bDcÌ/Y!f$XiLsOǪmx-7R-{t"!7ֈX^xpoEa)cD3zՆa"ܞžUBp`bqx]e6iL0 J:tBǦ;ƫ3㣐褶eb?\Gen;8Y$MqXJqGUXRmd%IHKL1 *"zO9;튙\?"ឭ *ZtU)uuMtuzVKr!i,"BT>\:,G1Yi4aD :A9kֽJ$/Ջ^y߃a|qS$)n?)ا2(o;xJŕ1m6V [l:eJ݊V Z]hwW7 St ԯFdNV | 0zQ/WK.mC*r6i6400P|h]CtoB&K6TjB&R|Uj"{5Z*5LUJGcwRieWw :E;ȒpT&&w% rMDI8hDAðc(%#@)OIܫԊx-Y+ur=kCJt\Xz,%C/µ|ի3^.tĩ0'ģxzNxwwgh]镴KZ7 K鑫=tY+qSa6 w[jk;a`y-ߜ [?aEm xm U5u 9qpONZVڽU4K_ޡ!0rE#f~ΥzK[B\m M8{Fp①!M[|j]>Z^v(g ?!_BPuxT 7[.߃ÚnN;g}xbʙc~o.A{+'a1\-*;{+-KippI0>Nu DHu!+Vm{' q\8I{N"Ϭ)mγ Yӽ*h?OԤ@cb˼O옫Ӗ -3iӰOǘ׃AޱvFuH׳^9opvH9ē6N@=ȃhu4GAJ켖_m=pms*89l0 aO'0J8{&}!^P>D)b2z޽M8zbĦ36Y˿ 6V2O),1A zX{i+_OLoW#]BEJIpE D[*,J(?oyյP-GBaIc*u =\Tv>8D0g?;ez.A!9牌LB9%KYc4>2Ҍrl3sq5+^.BfP>_OSMb15Y3,BgvN{%*"6ɷ w"ݺV2)D^&Êlq/SZ OO=IO0^][FAN>-kb:^T}测~YT4Z.U嗑'@HMDY=~RqfAwEЪM $‡Keu*8$IrkðL:ϭ odHNFDUYMI)]ބ}S95p2tJ~463 bOj-)5 BdxuV(*υ {b)侍C<]#bܸJ^#U@X zIkӉŊ JBam4FuX<4GTuoX[]6+5Q#L8 {VzboІ-chj{cp5wzkzM#ܸiMx  YӦT!v)N6 “uz6ժJ[By%*eo$q>RQ . {!I r ljlip bq$K 3Κ"}Z'@tp0.#of/&]Ϗ*꠸o(n?P}AT<n74A6V7ԧ\ G6"ƪѾ PT̔UM ۮE"v/ WSHsK;]]U=%oPDc)b2kuH6֘Q]RM11aFKȬ3e+~X 卒ҽ\'V2-bA밯ZEJga@ 2!Fu[_ H *nC>Z >NLL/YdKv(_B_8øM !E5ǥ6äK]i4*+ x=8!BCj?Sr8¶,lkY50%=IZkA3.MxTS#,ue4}9q.TW}>e.=Gh)(R\ct7&N'M h)2:H+Fvh]<@?CYƇiep1+i1A0#5ĢcXR럮V)Fa U4K7#nx\7OӪpA()t{Q]SA牕6'ûѼOw/ 9/a/0տn0տ{ȐN`*)CڞHv:9rxq95ɷlFiSs)nd:lHΔ !AW`Ęu;!oΧ,A1Dz+دQ,5*nno7oa'?-8'myQњÖ`=918<Dlyo٫'Orex!$rtxRinp;CS^wSL } ǃY]G:,ؿT GL0 xw(gD&gx-䫆v!XZ9el#K/WRQɸf32klj-7"aVT V z1M);=XzTǿ^tG K 4M-.k;(*jÖ!#1]O`<~iwW,oU lq::V]EUj @8ē6!uz>Nd#D΃QLcEyi1af('u;gzͺW)|;Kk_%"OwaU~/rmt3l ' ڲ[{ƅ Œ%![`8>1{R N)VTs1:wL{6O[Z/&d: 0?>qt"~ j%CD(_ r$-5(MlqpL* j.AoJݤ$d.MODeI)-TIeIUtGVbE(C]eHL?C?\˖ U3kyawR~( ?CCL~ _$C82&k#CGaBDT;+Mz$ΔM]8p\6 %jCtx;_A9]VA9Sg1`IJ ǧ::*Ujh3UY;y0'&<*ԙ/k Pf%\b*-@L;(!`kɫe}*QlcwRieWw :IY–$j@'`51%'C,5 Ka1QaJ$HwUhjE-Bt%Z,YKYӕh,f,"dYLTܢdViS*DIbi$4D)V!Um 4 SA)נHLD`~ $r0O 滱Ip G4Y- Y,›%a|-r?!ޞVtP ?3Z.(Xu#YDhye_׳r![N"2(_FՍ R`CJxm&MF} 'C#xC*[ߦ2] 57t{X) ۙ.\[n{*_q#?jML/5czO/jfp-//_z̴W&˺5ݴ8q*̈*&ݔDc[4yF{[Z ZnS+7viV+T]Ft5=rPO.^yc/tK^aid~}.>dAxe+( Lv{#.ʒ9j+ɄyxVQfZdt2%s@}K=AfHG-gwkxh^[}y D$DE-_vl=\2Ij"76畲-˃>yN ۱Dw8ycN[tv,m< tN_/\Tm$,xb{{5$|{ŴFr?!ipg *vlCfօCjm➭<:1::%qFL40z"U EӰ_¯o`IF_Rΰ~ؙ ϳƦ*V=Ssf|Y - ,壪>;8ܲ[m,zr#7W̢4 054>](Ѵ&SS CHCr%ըJQY5F/ua'_qxq_ALZR+rys[g xQRv{ܢ0b9=KkM< ;qCD==+A#R+PJ^RA `M;oR׌iͷN"?r ETl)t': Yس Pp3UXR ^:M[=sa C@ KSA_8Ē QnvB`تIBљкk'5fhP2#y|RY5Be^L9vX–TG7`Uᖋp~>j e2Z.mӝO4!&P޽%Ĩo}@XKBg:,q i({[ΈGwsJK0vK0Ғ!޾n+[MkWRGdiWCʯ8Fhu`R.w2MQʗZxέX {yp%k_+s^+e'XA'ZxA|,(.H;[:XKl@x F̖?k`XcwX;&]F,g?+|?-sAacB6_tF0FKmur&E\mjuj섈E<'gmV-rcҌrD֛[?+î}Fp:4  GG:x-z-a jYi`տ<俵0Kb;N0k)#, Fհ ?K"1g1e#l</`J %w3۰o+gA- j;aw^8RN#&~1})8x-!%7`KUңs-^@ai fAME-#K =,n K 0r ci9TmGY+ĔWEh}1z*i' HxTC،A`5gĠ5v33w3E`9;<-U77IĊ0H'X\mM\'=) 5/l14/{V^ W/EpE 1]r< [={m _mS?H<_6  X>$Div 7e4iB8ē6HfB9!r?j)@m=7a\۳yZn_ hbQˍ.^ؽ9 WifQ3]h:# Wx}W9U9chVEsmrJ5|f=!4HGTub]]5-ﮭ1_+ôM&y~6CۧX[bة%7we63j/ B'5zh`uD/Hj D{` Ǘ9MjhOgaMUC,mӀ8{"}NC!#[Am\?ɩU\'rد(:π7-R3Mpќ8d{.yoslЉڒ[\s;(E'ࢌ.!_QY. ܱG1UgkF~]nŒuÖi)VV_7;] 3& – 3d9ER kwߒK"+AGWpW?B:P'W vgMwuy=`h`cK}ov* ,ӱoP~,r$P/YGcG u\/ï*!:CWM:vmvkP aN%8mطK|WZ^BaWpn [-L^BN¾cʖs[Kp? 䖸q_2F~+eyKzeW+h~EF ~6pk-d;PM+s'&yu)N6cB5Ps*Fz_z6:[tCssW(_Y9-w, GFd݁w_rw)E?[GmSl^`| ᤸZq3}+ژkߒttV;w; b3gOpbFyJu r{>}  8hQ]?,S8o˺1bpx2Fj\^}%<xT)UiZ00"%[ߦ_,]njjXiS=_RG|)z_w1`:N+m8ՊE/6;> O tbF)\?ÚaSbNu-_x þL[R|. a=*ErG( C]Hlx b:tXTr [}u+prt D%oK$r8[F1"B?3ȿDo!W`?%헧o`y[9rxi:eyaZO=X&5u-f,_YXD)7APAL|gaKuHMV_ J8p[sFe+1 =N\ނ}+"F #wX rn]5Xͪ!bM实ik'[XQ1ƻ} E' nVPc#MP)M[;e)(QeS F451@0COo:DFK85%wܷq'm#BO浏 ftXr~g31cpԒzaj C[H\ƁJ&^}!NÞNcG~ [qDQv %vq% 7k~C< s!t`@8ē6 )bQ Qg{oZWŷ⬂-!w<@!_l bFR dK]XH: }Lu߄1tF 1#+=+# UfIQ9-5#ַ"w{={d錢Ƣ(AP|/L[ O>sa,9jO 4GD_j 1{{*,ܕݸt} rqCQ4o|B&aVξ.Y*i 5QA;'@o[Q:6DMxe:GW-){2jk[{RPXs8 {6y~z'rC{i!>$e/gڢ"@.`tZ?MW`ĨDO)mR}_*MFaV,m*WlCCA}Bn͈7*jlɲSȟXGr!il BL/o͇H3ʇHP=+ ~xbEmEm6LxFϪ7G_> W[T|bBbp6 5>ݚF/O]%JQrhU7&iGnw+8`.qWqZx6׻ I'Q1B^KrY?;Ĥ6:[6fsv4r5d3g2H?cZwV}c{uN`pq̤x4 M/`Eߝ[1-vSR' 2{c{~3Tr5?=`X9$xbK0s"v4&Yv}.*j:8(ɑt-W? \mj$7dCMt/K#`?.Y ls`k l 8{LZmjհ\?`$/ 1–jqsH|6m$-5EQ8[RhoBepg?Ǯ?4]:yeJ4)R5LI8 {41iV;m RP%a?* 3H `?* H00ъSLE/ RH/X)Ѐ)V$̲"%c*ҎB+UZ_B}翄$ a&!O"p8;V$B$C+",OԈ(N>'O!?Etx/yB ]BU )rgIB&P?-|(G#_sEE&2B $cqP' $CV'*O zeIUKugP埱I!LqgP%a$? aI 1oT%v9dJV$C,0 9IYI!?,v1٦UMij$xOV"H_C)6$̴' EfēA`rM|Η5_TIx_TIv%ar#4YIOV|SOb6 O,f SlIy \3t]N$w%aS]xjPH:5w߱leXSG Wq6zCSP#*1=I8[n].Jon۞GH@C i?īmU=] LMo_?^vsk/^YWrd=ҧr5Trҗ]zuf+eݚMln"q}$P_gTt#ٕ^14KJmFt5݊Ze~ӧ Z)Z!o{V\|[o+ tj#w3?a~'Lh-|ϗͻ$u?ԱّW8'f-n+Y^* JUh/J6  fZWnx^}Yp+①4zan vY$c4>_~mnwa78x~!yCU~`?lDjud΂݃ ك%*JC8S朡_ܘmY~Nם Rދ\"=c[jU;j:#S̱ϥ9݇,bn-ָꉪImjjJdv(u߉@0-ifu2U:~ؓC<2nyR hg3ڻ5v4IvjHP; =[zWcyNP.X,MR;enͶ1ycrDDhgEkJ"]r'{sϥ6qM)|Oa6q뤣u@Zg !rqV+ĥ]3.m$t_K >P_a`\LiɼQmMX]QznEm,zrXWq,]m=6oo}eMo¾L~1: R9;-ײRi4*N`?qasw-VW']C c-`/`>!G1{ 71-mow-B,#Gbiga9n(\z%rby#$K@V*mjkzJvC6@oP|J_3ʺ672:5Q/ ҝ밯'/^gaϦ?R$78ēVC7G8<Ēj(.|"R[=sa C@ KSA_8Ē Q*Npb{Y[57 K0IM8 >ToP;ǵS|3qN '*l1Ց> r4p;Aor'Z%@wCjLs-t'9ē6>@wOMN7p'7kPXKBga;eok#vͭb`_J_J2xbz7Ol5{hqHU:ϡ›Vewᦗ;HաI5ܩ譎OTup^5Zb}J=B _&ܳ@UERF]SX,ʏ Z(.H;bGb /<*#z`3*;4v=Q~|U,#4;@|%ww)+~?B-}aX]R=dފv^{v4F,XN-huTr&0.8e\1ڦD3$ m'BOּ媻ȁɭ@ӷ<~W]Ѽ?:I9 ބ`ߊMIlZ6#p6պsUh,4G 8[u 3y-U4[sݪ3;=]2fdLJfnbNkzqW_5)z1cհMsSETJǀ/aLt)K{/'aǷc0r\K/AEўLqi_[EP"Żћ>,:cvfN,r'&mu)N6ۍ (½RFz|z6ՆWUЊ.[YŚ".Ȉ ^0lW3];J#%<fYc{bj {tgNDC"7| q:a\u .ls'$Sᴊ-Z3KRf&5$ח&LIzoo~ 0$ 79W/hM~[AR(7Y}j[^*lC+{*=9d'C1\gbDcCҫ Ym-ݪ4Lhbp6 8>ݚF/O]gikn \6(8oLZӌ:w5RVjZY os atc8ģĘV+Z}-u:" `Kڪ$S8G(pv SXT8?5LZ=֎0'ָ6aOPO,aOI?AY0p%5L_7[޲ƅŃ [-Tb9\\o!ͷLdr1,߲S[HP%{]Az?C)6?C6Db3IeO5=鐤R됤2됥R됤β%argredːFse5]~FPi+tI8[罹QB 2-:UD%aA `WrP!1%a'&W}v}ef<f XHHf.8"%@ZDLePe R 8 {4v"]vuנIZ%atig-:+oAvVBXG W1C YaP6+L(UVAJN+&lNigbi' *DIbd Q #D`bd Qf%CD# tICYP{qd5Zd=I_dTt'r?!ޞo5Siy/mvPGn-}}?vˁ<;X=D-ڡyPcq 3A! laiB ?.^蓾E¯릿 ~4C*[ƞ7bT0lgnzsmW]~ǍϪ52䖫׌%>µ|ի3^.0¼nbry}$?hhtInS+7vi.-.}[Q,=tY+qS?ÌdmFʃ ׂa wmesZmd~b'oi!/y7ԥn::;4=Pω[}rhV㶲Iȯ\PV_O]9(c,TPntGlHQ&.~"x$hOh^Xۂn: >"C-׸l]1x~ C~QR)7z[ɱK:Irq'т|tU+e7A{A`1\-*FU;(XӍiedf}.>dAxe8*&)Sۑa8}mu+諭DY1gZdu9Es@[bT#Ȭhřn k|ݰk4NaKՇ-va+ܑۼ'`Uq$anͶycrDdgEkJ"]r'ǰ{s:rjO4:!vlw;Y D{0OjUݿbI\<= ލI¯Y@ɯLUxKCeo8p&aq<) !|A9[X6@I-U!I:L ʡH\1;nt[ϻEw.uhpxMe{)M!!tlxeOJQY5F/ua'_qxq_AXNt; 1D0\ܖY,7hxT]=(zh _!s TTꕠWՊu,Z%+Tb:ٴAY1v`+UN~(ڜ6Z|$R#PDȖHwþz9=HOZ ; pfPKػpKA?4<;[=sa C@ KSA_8Ē Q*Npb{Y[57 K0IM(X*c#TqLn'I,l [Lux\*NV PZ,SeܶnK?E.O4!&P=5%:=@qb- Wg4U g#eLrUo`_J_J2xbz7/Gl5{}\YJIpe D4=Y|B" =$ ){rzy%#A8"R@P)ՀfYrZ }z : T=w̅3+"lGygCMt&,wiCmڪ+lKe3yOO;plsnLqN .~BMdˆJq 1qlfu3zt !DU3U(%rUAtosm:*Cx-kM/pp ރ?< _k+k ) (Ir B5qAFlX,d#(np$)g@0֩N:#S܋.HPx4[aQr끈`zZ(vbZ [?_&2i1~1$g8d 8l+9J_!IL_)YraUXduo.hl1K>Q/\OnP]t +,3uNL&\`z`=V<Bt /!rRC wdGĪ >FɭvH3@ :]d^ w亁}R #3ԥ7@.oLAބ}3yKߊ!Ir6k~j*] K?C%eWt8U4Y(I5@<_H}&`&lIEaE'R;" 4Ph/U'vJn'|P&Yad负=h ~1mطnEa,̴jWg\ ,{7)Bs5U - r/}Uk6KHʗ?*x9&EdrUp=ʫǩc슝&rC?-˨ ݭ/n}<[hZM1 -RqN`{x |Pҿ|"pfT3TY*e_msH;B5ն57stCşAnU,o}OT{I 32ȧ1ģ, ©eמU*Z,%C5ItDΜG('+(;xI(.=Rպ$2قzC 7͢DqgU@)L$( }o3 ˣ-6q&!6'=$LHTx"LH4xJX&)PݲQ3nn-~eH%:/Ce-|,kːdYKw_, 7ߺ$O9yr^54:]k*(J b4:]ig@)wdp' =w*:0I0I&" Lpi$Lsui}$L$LJځ @Ai@)N`z[paLQ.jErQK}.TeKO%a}6T,[P[ZʳoAoi΂U; Iأk 6Tv }|;m UB߆*NYoCoU[$b$L7Dn-Fݨ!m Q[K7*Ȼz6eS|(6kjRj=P{;¹#R"db Jeywd35Յ| 4I[hޜO_M-eI:U@N= Z]Sb/^0lj{9™#)R" &!R)2ȚB :ѯ& SuDZh0M'JՉV)DaOKԉ|% LBD)}9ѭH<3(2'C .̿|QIޯ%0~Z GyVυ{a fQhFSM2N?"r&|:IhZNABR(.N_Q&89u%aDAiNR]N. TKA(Z2?<9JzLKlrP&QO|&x=E5*)᥿' nU`-]Y;۪Ǹ Zy &MeOg/QHyiN܅ $,U0fokk"o47+ZoU#u-qM!^ʷJ9$ug(orZ{xyܙŇozVZCC^t֘Շ&gf!w6{gO:ulȯCEZs0*h!R)SEGW NJ+CѢ_цG誐sUke7oߪo .2F:JQoV ?|+?l\U1-0٥Ĥyo1?B ݹ=5b֋DCM+klUao\?9,jWI}_Qtb'*)dw ,sv6+un:~r`YYK >.͜;)!T*Ğ&vE-*uVmY{dP;b'b!O [(`BGYתyTP;cGQ "ٛT6w7:5 r]LNP\`RXtUحCe7G'Ut,ǥSsL4 B<ْUmFk lpp?"w#ʌ0;P7eW}ߨU|&aiWpS7d1#.c'ZOd4-65c|-[e{a*R[׫R ']vf~3< X*]bZR~ޚ5Vh ni ^ˍ(̎sB "^7(bG׸ձ)aNm{c'i[j75Q+*0YvNwg8!nZdNݽiV 'h$ɋT $M9a}4?"$Sp8"5 ).] ž9WqBm|ފr#=(1ģl0?Z MZRY u BA\,CKsz5;` ʹZ!fnH-! K-6u%3-ߙ]d,c3Ֆ~%ugh ORg`M?mx9y M/ݺ1XH%WBHB5B\3`{' " 퍣 -@yxP?/^}y'*l?g:bύ%d~t p> Ú5-c $ .L!2=eټMnx`Ks5-?\:#Q9 4>tbN8^eG__ -'ؑ`v&^[!Ѻ|Om pP/N_J~引<4~JU,4Q(Vy3ɭuv/ "̀vdWNE_(KZeERl!r8h~AsDƀ~MckԠEmȬ Ջv4Sմ<s>HsvczhA/,.+d8z7-mYKlYEa<*| [__J%wiςP_-s=.jժN0?nChd">%Ո~q34luw5%ۦ/+_fs{~bp gwy2 o$mr ga eCy`vAZNz0wcBŽ [iiBƋ5$@u?!kk1ģH[ 7똱BWMSFE2|teP)xdDL7<@hJdٷo_Tk-N`rJn'i1 VL Hѳ^_z:$6 4grd;^ӲR|^s윏K#ebY0=9> [hyی8ږz:!+,LYY賕yz^CztE4.J((7kK嚵e!$:cB&a XVo"iwG=K `ߝk^-㻏`Q~ͩl[~ml `3~S 'PMQ46IrH~Sms漙+K>ymft@pM:rیE½o(&`l{WDb :F̺`S1WA I䘦nM) _WSot0;|{84D`3ݲyG4OE8 DN Ji f5((![0,z4#hjHVcnj%y^ 7׵4|=Jc~!+G׮N#ըa&-L:PQKQ,AXISw'3I\(o\;=cvbu/-,O4\W;,;CD1lr;#;eB'жP.VjD)E}X9~!M6HT֢xxЪVe(ia߻Pr'` [ŽA$&+q^0KeYv˓Zlv[mZ v{@]W 0!AWAvH^«vaW/ٌiEÞXhMAb8Uv(vѢs 9B{\91l~$y* j8fJnx|rbpxz&ʉCzsDU9e|[ \BSD|<IM%!Pf!]V*Yc.5XX?I薳s<2FȨb-:5"[cG gF`oKR˳(=Un[@v4UQGke3vGD_ 9@u=zeY+1l-4jZ_Bυrњ6wǂ /¾LǢy4\~!%=+nKh?~ςk ,V v=(o'lKr0ڴ^D;3 ^W: ͒MH0YoT8>ݗ+7J [_<H%xX0f /jy"v+ p"Wa*ͻs[!0ka- PkQ -X.:ބ;. ̝ٱ3rۥi=]α{frٌ=slܦa{vt'GuTZ leFzWBZu{D;0K~3ϛBz9D;!$ S܈ar3AxvB{..x͓Uy;,7Rr` ΀B%ay'b#iw(޺v3-VOOUv=n}% G8o),mZRWvYЩD{ܲ" xJPq z!TdaXy]УCڋu+CˮȢJKa) E Mہ`PҾ/n} <[>)K+|aY+Ŷ)?=4ȢWa E{ڃ3!hm:O 9ߋl١\Aneki,a8ll£ M)5k(8 Na: om L~_G#` -@8U"r)r3y9Jn/^U1僟6bG 'סF؍ʔ,YRNA'9$C%ON/NN /`d\afy5E4ƀ'tfAtEJL:V0aI‡|\W/OŽ D/7@0veo!A:ZMT@qBaIw>o[(Fb7?zsF^/ ݭndwލ"Es [4Gv?< [|:bX4+P">]w_\# Ќ*ADځ`Ko^QBh2~b}~TaU-%NqF7O4l@jr?j\dŲ)C9#׋dDH8-txQ KTGqo!鰲y =ɗ#Ln@jn5E0!"ӆeX a&GF2CQr 8[_f 1YB[Mgb'MSmIs4>?H[:/!>;` %N; R2I3]M76o8}EZ\"+iاo1'oBl6Dnn&`l>GӃKKEQWND¾*M:P0G%U~6o. Z /ńZ\ԍ>PkbKj)w~|Xn-~_kDe 1_䚁`EC(hPl}c.r,;g۾]?6(v/9^Q`?'MJQh1NJ3jS8F-Q(}W5P]|˶O%(4At=ޗ<&ؘ_˳s0_.DK7 {up' {B1X0-riX.<;k,\AvȗmBMdj;ߩk[aooNdwVܥ [,d}tG\1cG yE>a5Ծ[ {NtGŢfW İP_>]euxW}Jx Ph]6{ܛǫbbr8[l]UEE0J}HߧR!i- X#7(ț{ /${97ށeW=x3oưvpFȪoA&GY}r>+&C4+ijfN F?m5kQ[ZXLI`D+dxȌ)6pa,8"/G^? W^U㽖kc7-?)VS"+w-]$Gwi}:Hu`%<AD8O" Lyj:"ǹ" n'lu} >[h&N-FKF߈!Eov)DS 1ēH|/^͂kG(bmˏ 99yFON %%< tL3˰/ &ZwpaEMQMՏưxܹEwQ\&\t>暴RyC%K?1terz!u9 SVޜev)8n7.r?N׺j~qMVBj`/{Qr;}fS* RG`_Jw!ڋbp/ eCeͲ0r+"2V--Jnfp|Y`A7<شTh;@LWyXއ-|cb"guM7E1_LF_R#%r $fI(Std>n4t\#PX8{ >?DjopV ^͂kGd|7^'͂kG(>ϐ FT:H'-DGR9s@A^qlN6u̳^xl:-ћ{jdv4"&7Ig|A ,sbd/F=䘖njBx@#kMU{"ϛ /N>SV96=ٖ 5^|?OkfbGDZm,7s% \֋ eFFvG25gjW2c}?#Tf;~.M3K?^Vw\k#<4Q%A!ߩWvmMfgł_O O7(Qwؒfxٹ^l7A(w0i`e"~d[a P$ȿE"&RH<;O!ʆιrJ0=9Zς,0ai;VWnfl*62Z# Vρ܅O{c~?VB>z'oW:;aq}DM" `w/gg#ҎP-cFٺ+m4c D a)()0xBRt#C t+GAJ+:+] >dׯƯ(.~WA0MkH;B5~Ϡ=3Aץ3j8I}|L ;;a 71dC!eYN7zP*ZYIJ!x%:-K70,dx$sr)I}opa7KUîT{}^2mty>}WN(lYLDKɵ/ A"[,ZݜtOFM_2>=b`;pGMHUPT8s]BOif`gR)xز;8+cɟ'J'JT)LБ~$LӑR:ҘBE'!Oj:OBRvDt4 t~`iSnӋ%^/$a!IBY$U"5$a'l<)=@FdMyn/+q2D)N&O(?]4BVB>)S:aa vj>&IOC` -P$al!-N" [eOCNnuR@NäG"ä@&}03(I* &Q^äu5JKg!B+͢Zg!B ,YheV$Y:Mig!MBգ%:amNz" l?Ev`MH4xJX&)Pgi!k?I~^KyyZC$~@/[#uݰrEp(QT8\M* {͚ך!]bm'֕7u&2)HxME^Z}ۀb$VEJߎ!"mx\:5(FDG2[tk(-uz(x75*IRm\cDO4 ")&nr7VnUa\I+YpcZ4t"s ^MO>QMG'aL^Lb'i-ȁ'éPxt hv}u?lmι">^EoEN^JQMtg6K܄&-c,؆: Yv-OF(>Pŭ9'$^V([MD4:i:LI7{̴|gz.;vqd21؛# $6ХT>/]~ :G`_+Dzf Vrxu٩LG5`.{DINP{7Jc"sω^ˇ~z'󰟗.<ڎmD]%Mm5آ]fsʝkZ٥QϊCeǠWҡafz Տp+l mH0+l]v- cɸQDG__ǐ_h0l!K-4P5էrߎ*.HiC7Pn-K-1#HMT]Nf4-If52:y%wdh`< :sfvft3C ~Q;jZ}Jwa߭۫uV^i yНX]V0~e|j[ %jPj)L\ϱ a„Upk3%OJO4b'mi$]_mnS41`m*{2#Rr]K$mL&t+E+;WZLݰ`k0Ms'aHe_Gz`I)I%qNžT(zMQ˰/^ǀSPrGӰT駦{@.Mi_z. )XOR\$gz Qk,fJb'"ZN%ؗu"!,OΌjm פ9FM[Ԛqa+l^k~3kZA=s>XHsvczhA/,.+d8>%<[lkZ^b@B~MssmrQe]B{ J40;/vJ8{N{.w66S4+P#bqevQG@[Fcho-<7a׿Pr ElnO a &)-KSH_B2<*^> Ye= ~2Ei6gÆ }D%"Eiu yڿJ+EJĔ$)tmmD (9:fiߪ5nʨC2FXF>cRC zthZS ΂Lϙn[yVNfdٷo_Qk-N`VۑSr;L ,LanJ3ؔ]4،}ӹg>e2[.l yQRƊ^s윏K#ebY0=Mju``ی8ږt:,!Kڴ6feV&yg#W\Y j!CtRJU{J`9 -6?ko 'b"8 -P5Ս~Bs (ZJ )u#_W}XŽ셠@95W^ H#&0aݲI4N0sS)ikI)q*QVsޠZpKdg>دB|{8<}npv4Un?su9E #(b&9tۨ@~v %uh'ybyRi/J[!j{% qsՖ*'kt{(!}BssE+_Q.ڍa M#؏kЍthIu[h֒_o~KZ0Po V$;a[wu&JB9>Fɝ>@ޡq5JUk_i}DykYM7I՞vϛyFo&7cyL*Ts,Hx5EC5{J8T.<" QeBʺ̉pB2z'"2GU!W%"J-۰ߖq.[2hf A|"6 1RAstGZ9ot9Z dCukѩ]hl!eҞ7nn-/L wީ<(=Z%nJ K@QljVkyvGDxYHg|1,SMTȅ n'`^*o;p?Jzہ'ao <[~ Y;MP^t&Ip?: FruR(>6l ^Aw}cs(qẺȝ[b8{0C)-!8y@ɘ"D0lbv@ӰORrg`-4?=X;1,b⟆c.@4*meհ˲R~cBt9Es#yځ`-t͖=ck;߯,al$=em|r}"kD!8 ^)B*kyM5h<2}:6^!%^~1|^ <[J51^}I RYس(vsH<-:spU|8[( hǀ&lSZܻ (7bG]9b7vX3pY?2V` -~UMa{J-jۯS:E7,:Ԓ3:^:B ;N.klKEߕМ‘"a69F4:b'邋KS#8= hI7( fp)8C9h %!ރkcڥu㱥:?--x `@T]5VGRk*9<[o% <tQmµܽ q8[htpDJQ/!'wGژPx6Dxw8Aq)-L[wf1\8$~d f# (j@k "3b%wx %B̢xUEDƀÖG9܅:a7*S&X4rfe b!>-6B->Prۻ Cp^Kv{ZOO)a)*'(~i&M`tl}ɰ8+R| IOKcIOO {f%ÔF/ "ψ~X.g+.w`OM.B㇀al CDxz( _܇ߠ_oUˁWޥ:fb'i:r B5q:.wYF͜ E2$t 8BK@ԩL{(px{㨕鰲˂6(K>#Ln>R3ҭj])aIAF-l"LoB;Mt\nB}tAI'_))׷3.-^1bpJR}3*R W"}Hi:!-e/! X#7( ɛ{˽oA};,goF}K ` gTJ0a۔o[x5YL3UK4+%Twx !G6wi1ZbeJ#2^!ݝWFfN< !fِ88vp2 nZݘ|@[hZO߁ {t^ݥ'<"=k_[O$2_C T-]j2< 2IV}q#LxݨI߭V~I޼>QaE(UZtkJEX~ 7`J.9}Js<!B9]|SVޜev)8n7.rںj~qMVBj`/{Qr;}fS* RG`_J=RR 1Lxs'{Yc(,Y~@ nleJˍ{fW1EdZb3[\#PnmyicRvF -7[Do2^caGJIP(St?7Kd YJv\@U, =P ѿڧb(ܧȂkpYx̂okHY#xG6R4r BܨZ'Bj?n9(>”"" m]5#ģM13zͲ~[ҳFofr  Lc_tޑ/8;kxtxW`o02'OfqXٳKiy(':F_l߶'c)ŸjӦ99{F?̂C<}WN(QRck^}AZ#y{xQԻ973W 0;nF+H[hu/?=b`I+?-o߀F 5^A5s @WFS]%@vc݁lAwy\)-l9 DEc_l#fJ? {|U'GgaGC y4fJ%8)kvG!NB%ќnQS$ݕB)n`lqVKLpiHYS;LidOpHʔ0>BO? if`gR)x;8+cr⿁* t$LՑ=鿁* t~74PG3h:ҟ4FKّLБ I#Hr3WuO^,z In<-$I(AVD`7V<-$I [A+-OJPYS[J YN&kO? Q,t( Y,(NMpوO? Q,NXrݰ5ItRA`謹:I[k˪wVY;kANnuR@NäG"ä*NKtsPi)~EC0J4I~7G0%7se?YǗC?U4j*6dH!͟VjO?YJM$ӄ;iV׉0IQ:D: N20I&J XI `:P$a=E%{$LJw F!ǻ _uQ%/ɖ@ $L}R]Pg(L?B? U~XKtP凵gA? e~XKtP凵tgA? ehBӅ Td#i+#PGUGʏЏ@BH(DI`#QZʍGQC>%n#QTjlfmϘgMP/bv-JeNpH&§_2 <Bg;97CM"MJ]̧_& wÖH@D [Zo } 4I=>)@5-O_0 5}"UW9™#)R" W!LB RJ0;SҤQTIhנJTGKD`0үAi(nT}fC 6M`CS{kʅ t1-UAR^ PjD˧яA=|F)}ߪ=M!o@%J7$C)7P@R1>IPZNAtK]igf+6]SM, iZqY>:i-Ѹ,,?Ө"EbgI7|$Lu &3$aYU{c+d ]%,P"w|6U#X?W˶WvprgE[QHYۢc5R^dYD!E^cɋQ2G^5w)}%y-QJ>Cm_?RPפe|gg P. ʽ18ѹ3 gg&b1i=MΔBl'Ξ:uؐｆ52,JĤ\J,|OQ.]!:U-g,2~׵e{ș}0\mr[kD;쀑"ۆUMkg WqoMkv6 cdL㏬bCBwnOM"]-PZWW|~XUѯ]ybC=C 5Bil\sbC _ M8 {X:wR'bG.'/W!w%BF'ҋ:O8WHh(y2F`l<􂩻5]TPcGQ\E@u, rcl֜7k3䱲am@!>y^ZeۀB$FJߌ!mx\:5'FDG2[5ҿ$~688oy#ʍC Svjډe1, &Y:ٖVG'p2kFFV1>-ʼxY j{{U-R ']v3;@t&^ʎ yN`I[u՛pBp? 慨"tYfT* |Wr# \P< Qtר$}8!ilAD(SXM 'nF {pøVFg9ѳ}=ǴfiE&l-4kh$ɋT $M9a}4?"$Sp8 "5 ,|A _ѮoߑÞ9Wq(7aK?CY6=Н` Z_s^{`@rY:۵p<&z5Uk֫O -6tF#.o)>0bS'1Xbޜ1},E fʴ u}:!gaWBY9%4=gRaᱬ/\09^ lv*P' o^py_F{MǀS5ޭ ^}A_> =]w{^x1x엤QhZ f3~3ӡ@I;).T7BuV`vCAwΧZviHw`n1osx_!~ ",f_zRȶ.;Ĉ\x dX˨u"{`(q`[p`1-?>%P''a 9>`^/vNspF7Pnp!K-1#۬QI쨘 fr9(mjKmWNbrVaog4"ӭsc[v?1.5"];H3?+=P0BίqE;x J@*3Q^6fpR1-!La&h ni*h/"H[4An&*xv %c5u,iSQ$-ru.UQ= BFXy\>cRC zFY:TbGS~IZ4`%㚷] t "r> cAǜrN\v[Y.nEg9#SߤP[K'O.{jg`Hޒɹ420]qklwh<[n˨x$+<[wOVZQr6sI~R[.lc3znXh={U|@0YX=ݝE௚FCfڮHWSكn)u<;;iEZ =o =iJ-:kh,&}}ux.#P)(>Ʃ9en"͜:)yÙ7|Ɋzl/p4PZҼcTK p:_ f74/*$oK/]vc$^MNIr(sŢ 1<7uפyl2p'9pL FZkvϛ?B0z3s@?ԪB5 Z %פ-m#F (}lA/<<;-#b<pLPhK "i5˩FP.Yeɱ{.91l.흆f>L$G۵9vM"Ӫ_=R/Cm>[~j78'ЬFip < NVubyUb0_ wax* ߻w;Uw F5.#ؤf~a<"33D,IeӓO>`̮#k-%UD-gPmAZv0 lƴb<~m̫s1*)w3O.'`O$7bWq\\B; s "6ʥ*@AÞOF2 Dp2Ѿ\h~BKD/߂4s̤F8Gn旂Da9]V*Yc.HX?j7FƜlb֕@"٭XNDck (v&6R`;p'lu^(=*7׳@v`wI~3J '^neؗ9@u:e)1l-4Z"x8;ްZ"xU|vcJ 9LxᳶM;iP6~*G RU{W6֠uDk8[n(H PR3g` -?y9Jn/rU"Eǝ]UҎN@]to!EYpqչ>zt3`/pѸP<7:$|M7 T+q9);kB;! YV)xIO(12 hL7Khn t8Ts?y cKfۃZzNpz)J5[c2v-eϖHG;8inG/3ƿpkVϤ*" W%}D6F^8 <[~`|!^5m-Oti; pr"MJP&jQt b3h-JTPՐ֬Dfx J$K҅E ּ~>[~8܆:a7*Sʦ~T^`zWsMPrۼ '-ZA,LT`\Xa HnѢ+-gSEwӥ1'eip#t3oaJ#i@p [qc3p M.B-G4X $]~/"LI}4)jX.`8)'@z `I&{[a3'4 imJnxUY23˫+1 4~,;P,9cLoYvJCAKPg^ ^`nȚy3A%2_,Dh?DS k5_cOg.h.ާG92MֈN\i\Xټ/a8Ezu8!ElGacnv%|7 BĒ p4QrVŤGNCdD=~EonYa6E-aic3&ţ0(]"%ÑXu1cүq!-Ԡ#wn:=.8XW;XMxwh=iV:wI2 AZBwK75"|M m+k?;(ǜ%b=AַbA8j5\'pok(c㰏'?vSꦻHM=4O(#u+6K\6ZKmnMPS괇íl^o#o;V;x$ؒX>-Ο#ؒNžT2_|ɨ5دI%>&ׁ؅| &7j ٔ2o!iGӃKKf{+'ȀWaz,A?7pj-Ukj3}ukՖL-R` oxXn-~!i ]'(f`;l'X-7c[ /ٶl KWTDx79Ba|Rn@Hg1NJ3jS8F-yMAUa,J\}*AFQ㿐|0Z0r!ZWxNxebcZLVP]nyvp=wY䄬/}mBlj;¥}­7|Y?P1D!!"ہ{`oNw"K/E6MqOB}=p}2j}6r&|[7"jNE @oa7lh}D $\l(˻l '{W4p 6T߄a•QYi:!m_^;,goF}(}3EVGeJˍ|ܷ@< CDت%vk;T{<DEoTbeJ#2^!ݝWFfN< !rِ886P.dՀ^˵Sݖoa M+ۑa.vK}4>$H:Cs߁ Ly~ |"'i&<5Pd\McebxxB3w-]j2< 2IV}q#Lx]IߥV~I޼QaE=(QZtkJEX~ '`J.9Js<B9]!Vޜevp7.r.ںj~q>&a+lM}V5Vva(>bOM#K/%ԋnHojb)&܋[xs'{YoŰO],[n߯ l 7?=+"2V--Jnfp|Y`A7<شTh;@LWyXއ-|c"guM7E1_LF_R#%r $f0u)\O%2,%Tf;k. *xHOii) i;;,x̂okpYxG6R4~9pnTMuڋH[yaJȁsǥSZx:1BҎPw\g F~feu+Μzg'#alP|H;B5_+A\pݝOLܚfo3uKynbqagk?w1+'C$O8al.̳{Ŧ8:o][n߲ X>l" DM\ "n&6*ǘ頳.[`.7Ya)x#Tg J1<<,Ejݿrf0 S9'Xsy+ &<ӠK0"LAW`@A~b?ؗ'S SJnG#g ~?AP^t8N7 CS;AqxCpxE?{Lڴ{=7Bo-  C`Dw`@qܼ\ >y$N·iS#3cV{`X!vǓdy:l ݢ~G/ګ( @旤j@Iͷ~X X ;awFfsʡ, J^ bGPd4_`14\>C YWQ-ݥ-JDx %klQ2#.@xAQګ~y'Pr-ӰOKwCL o-w-n 2E{.JFGx ~8 {Rf/uz2==#?-Fg9ع_ U^A5r Wn5,E-/_1=+etݭ/_6@Y;U6lVk( }W%CQ~~ay4J~19):@[h4'_;a ye^D`p/lu u vW =X-.SDc1Hcج ]C4?iI[ȣc&av&R`#:6qR 0AGP%a&H$LӑR:ҘBEoB%HM-eGJ0AG&a#m\=}zE $lVy$I(OVD`7V< $섭'(Ո)-%N Q6 Y'߆(hՅ@ mN&`'߆(X', 9R]nBݔr(p]W@m:@;p7l:$쀭vrJUw&?2]&.TZä߅*WKy(I U9L=ZI-QZ:?Y~Zi D?Y~hTl!͏C+{E'яC,iMD?i2جM/ +os=(0&HTx"L=(0&֯o^$ -' Oh)?Y~BKt HZO@o]'O`h'O"oFRD (5'Kb}?9R (5NL.mxC N2>DI$&8%aL~L zj)(0觠HT{D`SP$a=PJX>ow4 9n(?%>? Q~ZK}~i!J4'lz{dUgh΂~,gh΂~,gL^Phx"W*?B? U~6m~l ,TٔYuU(`W( l?Q~NKjDAm? 9ݲ9̼i84?e~5k)5Ty(ȝFܑT)2Mb1O2 <Bg;9b@U^O[CM $>@ʵhPݱ{~}R{RKks[L"a!6kjb5D"s3GRD(B 6KA>`vIh #0A`?* -Q@ Nͼh?& l$L'?&XKW)h3 Z<&$dZz<Xf~GnԘDc)|&KAV_D|QtEhp?lN)%] Q&85%0թQ" LpjK%aS~SKi-ѩ?2DKyj@F;QIBDG0T.)b\xi\?9BoJ5Y k/a5kQ&]UnQ3d@-oJ{,K9)TIܟA= $Ls~h>e(0 _" ۴7v`j EvV0^V' ߆nP&a?2 S 9IbP^5U0 ]%Ν%[#XKWζi99~E lTLn%jё)2BCJ>R:k8yW~B9(I%0x2`շ&sUҌxmMp$fF3~G}HD]K\~m*9C3 9qro -=<<|t̂7=GcfIX:kLZC3e;=yj􉳧N:6;!r 0k0*i!"R) SI+]H,2~We{ș}0לhr[kF%#)aUc}oç{UUsyӚ]*,Ș#+tНS/fHzK?Դ2*k]ؼ/O%5,o2Gͯ(v?T1 gļN]#gvAKaZlrj O>-M;)31#@CvU>mՊeb.S(**J~O <9Cnv#P>UMzԫe^-'pŝWafxx{P&T>՟ ( IrtjN@<"ddcdg m{E;Mg&j7j˺xIfcX\1SMt-1#.cYOd4-6c|-[9eS<{a*R[שVObfvpx.s XhWp T}`_YyZhf`*U<19,>(-uz(x$zð'6R1ē4-ȁ{ kqjFm1 Z-+穩7*K䁽Ka{>Nt[V" „mfzHq?l&uoDק}>=Z 23%Tn-ȁӟGĜĨ{W_I`Twff>ߏ-٬hxsvx z+8+!EoRVUބ&b,؆*!ʴ_v-NP|ZUm WVm*5iH: ]zΣmtyˎu[%';>E k֛iiFUY Ҽp3%og;>KentǢn;o /H负2dzÕ&7 Vr pǴeOv6(QWxj"8!q؂"SshXӽ⩷{7,]Iz e#>'RH[a .# *%^}Qw7Scfgnh8+u$NT?`gȅ~-'b8[(?Dm^}9~)%%xd5lvCA뢦Fx>Vnplsd5 l-?G݃ v$DA$ GS APr뵥05=aL`R33ʈ:x>jLRrQBJ8[~*QۻWfgí>MbjSrG` u9J&wB'`H9&6#K/%S6'c1x|m&VfCʹXQ_d3+ڮDz5oX&Mx6+`x&8 e #G2A]"|3 d"8 4SJi܌1ϛ4U7S?GOͲ"kQMj`J~Յ#T0x鎞 S.}4:Iu+S~fsrOA؃ꢚin+yJnRpo({SU9(3wbGP[d,Xdt_ѡ7 ו*m1qr-T9ED 0l-r|->ȆNtR ?kWch-߻@ U[uT",%/_˗6l-%wX]J#So$Vr[Z @[SWhJhzy=Jnpl3^MѸB<V;F,6 yڴx#xh˃ftpfUo32| {fG"CZ@ئU6SԔW#1ētEHs\ы{ӥчҘ8C+n䀙 &bEui"?8bF]y_^pX}1q9 :˄ģ%cGn#%V2\٥#8E+ ۴T86URlfRMY.(7R4b󎒹fK>U202 ֛P%1ÔZc(Sq$}\)UM&L-ڶ~Fr-)'a%< TU "xh62L=-J~/߀FtJ !Ғo^y "4~_be+YMQQg5ē 4F_@%$[hڂi,t vw'q=H}[%z\[ H?k[7ZY~.s$g -HY*u=n21g+96Is7$MX2և0/ɳ FG6.Eκs`re tOnT V(:3H:B5]+*5Qql5#:fG-8zRt Vi=%e/'SZ?ʿ6K4`O)/>|+aR`?,=F^ui*ۗM]۟AGԳE1k{tnVOb/ŢZ`_oh٬9oKG"hRG@!Mrg|6n] iĒ̢YНbldeZ:1; [H|U^}=%l H15khZ,y_E8{L5Rjghňģ(\$L?iK4gj _$>q{TJLw- uD:ҐV(qg%Cڸ7:7kȾID$Y{%3E&+GT1\U.ps{|cW$516vkj\YMB A.:]ƨ/={z fm0c9We^ }џûޅ}WI'<'l]G_XGlBaлQȢJ\6(.o"alg$ݶ Ld\Mr@ V< 5aTTVr cCąyiGF~r7j&pi$LL:G$ *c&0_-e $5,[ڏW^9ܯ0 ڄې{H06B"AEY[HnH+HeYWMvN#jbǑ+J=}opzGXrt@6)vO\#(.=yVsIk݁إ.M5-<6^j  6SlP`*{D( p?lh 5ќ+ +pR|b Qa1v–ߋ/p < [(2B_* `wPJ[܁Rh29]Y-'wAB4 gL-d.H0;L)Ñ^ +8R$LБP%a&Hu0MGJwHc q3挖#4g)` I#Hr3WuO^,z,$IئI^RBӐ' 쀭!,$I [A+-OJPYS[|ynVDC4k(sA!9Nȥ892_~P@7fٲ> (pVU4H6+$@P|4H j':)NT|a#\aRkPe^KyG&8LCi藺=ZI-7(k.BJV$: YjJtҜVjO&>TN&!6'9(0&~$L'9(0&֯o yl8LH<7!KSKtoBބ, 7ߺ$O977;Uakh MpHjt|}$-(πRS44NzUu!J'BN2N`L!J4'(.`]'&`E&-@@@;0h$LJw F!ǻ٭QDg,j)"J([B|-BiOJ X? vxUZZTii)ςZP%: jA,ehB' J;YPBmNV6TiPP4:@K%a| ,i)7%Ԑh#_(KZ| ճ.M(MPlԮPPȝFܑT)2Mb1OoBi3ٜ&x$l-4oΧO$ [yt;5eЧM%N\^Rӧ| a`ج aȜF̑)JuDB 6KA>`vIh JGKTIh&8ZJ4GK~7PS3?eX9U24I`3_& Sm@0f MtyJ/|E"<9%CZ<&CLKo E:^p '0# 傖֑T-ѭ# 傖֑ԑ[G;1G%aӢ JTE@'0iG%aӢ~ӢKiE-iE(sQKyZش"InZ;%!EoO Y%x鷀x΀ºUAR[ *iF{7^['}cG}H@]K\~mC%ǜ;C3 c|(sG,X/>|ӳ}4=o􊥳Ƥ>49S6 ٓO8{ԩcC~*PQqL JqDpTt؏6@/z8P"*J3xNcnc9ia $jޚ|`RXVy}i6=|o 嚞K\d_ebM?a >+l`oR&CB%ыg8o.Ui=+y 8W4^0aK?C<޾kzNiKeNԁnOҡp/c(>RX='Rg[sO=CD^}6HJ5Aakrp6Ƈ΅ %o9=+(˥Tk臲=ZՎ\ҡE̕yo|tq@U-sĨKpknawK {!2r~i.˗ sxuDz`_fyN/-eP 3v=b~S;469SZR%ԭ.Y6.` [h/7`տVQrG`lځuc;ܣtx %iniugK00 IP0ТXζ{lN7h0|;g3N bC3<[h8)ӰOK&! g~FYɼs_g͢ |xho!e[Mw㴙5ˆ5[aֿl`lHlz@ezI/?4pn-N0aipKF Y;I-<#w)SԦʮI^9Cɵ–saSXȦLo9qzx礩v># }9W\m"d=OjudFu*(sI:mDfaN[<탨yQ$-ru%g4CbGޯMM1#)W/O,-q"ãgY1v}c/H[haY3je +2w.r2z"Xޅ}W)@lX\[3߀NLkAuRgw_nmovFSڈA7PMѿz᚟ ePλ敚mV~jeshtO G~R"ɴL=#XIne:vΖ$`?.EGق9^C Gfrn%t $i}j)8GB2(`@ʒB6hws'l5k&CXijIv X0)C-< V`I6kj0*p&ݞ@ '5:dnvR;)\P 1Iшu%sc~ufV8KsUM@~al/<Š0%EgikhOs}-s )tW=;g=t()*I1vQѕFO rW~ 4@uvAʖmSd&q=ۡӀ"ħV( lc>٨WKю%7~೰{Vr,ݪb˹UAt1dP`##7~_/0yL/Ő^]/:D26;fp8F3 +ՊeV̖a͛mQ'[lAn 0yHlr@7O4b9 Kb& ؅Q91x2~ᘖnjkd޷~i3;̈́xq~ʱAζ,#<X 7#TNoh~feuwί89ڪW/e:ǎgsKu~ u=%5<(W  g۳Kt Eg du1iz٣U5 +[7M&&^eE-!TwѮG j l367;HP~6؜/rcǸ!B 7\nf<\!Cw8\cSӬK`e}gS0]w|$^cry=|k\eշPVSx{L#inϓ{HvG 5y#TӚϦ]X!~{ٲ~ؠQ΄`yI܌^ BuK%}%;[: 秂N _B2C_/cqLznUBN;]/S@%rSqb|iGF=4؄O*s{ {`<00 յ Wg0*(Wx &V4鸆K?79ώ YBu#m"zST$`fBLc02 SH0H;BEA].~hs-<]Bu꺧p"|BE"L{j!ը57stqL?l!l*DImpK [8V A.b)rJPn{E\# ©5JE˽L7XVCt949xmM+cqZoUӵ5x+*9C3 9qro -=<<|t̂7=GYsl􊥳Ƥ>49S6 ٓO8{ԩcCW/O u(Qi!*R) SMW( Nh#rG5j]/eDv?|yQ1#X^ ÅQRM0[ ^0ٯvctjݣ5}+5IIgcX\1Y:{&rOl;c{ԉC3E[uG(VG]J=Vr{+{ԉubV|Vpu.i]Qߌ @ئG_nVݣ.5ȵJ@!eo_ަW9THp=I؂Pf4V|lfͨQ;$&_ct>-@5zU+;r3w˶gL 3p_`?H/@4:W1૰_&<| k.` ]F&V.,. kygS xa= 06,3LeuG;==;h9lI$Ǯ^9Qy5a&"2N*ېwۤl\&ȥ)2[ w-]8 "t;aw&WC ەVTKp1|D&FArKSbݣ_lrPn=PR'COdVp)6U˅"{ii/دu!@_Q(_#ӏk(jտ-<\#ɏ)gb'"d4;bMWCa [H< [UG}tL[Q@{a,Yc)>ǖ Pxo'G/~I0:Yg"FlڕFձñb0Ln'^l!ͧ:J l1[2eIrs|-Ss, ;%T $M 9a}&77cK/JOIC[aoU՚jKaUۀ 6p7|e8YZFl 3w AB]Lv6%)x]#a}\S꠹3K|1DAС~a%|ۜsE8o}@N^J ޭjӃ({$ڝ2ʂNԁ֦{I1W,ݳ|Իoc$?O7awdfݭSI9Uvv}J[~OW_YhKTO>,'~x.-UoF7PΛ=-KGK Hs{\T . cߩg`^(po1Ab;ʾPֶWhܱ+7 LuWKSwo/-oϛFK0/-}H:B5G[<J"oNw#{M2>yC9?%Kv6P|Ms_VxT w}mH^{.X:a@#v-Hq/Bv}Fav/@>Zh]bWr, F<Pk4tQ84]Èpt-^lreנ f-e[een0nEp{tL"k7Շ 翶fƂ~CHJw..@A?d&8˛`ߢ6\ d0SʅsY鋵> o$ -T&#살ppMcpi >2]6Dv.M{N2G`Pډ+A+Naɵ1wާ/OVvQB 16jb%NS:NJ_ /Ո+ އ}_/-V2>anډ``AFܻT ^~HI,H}Ԍb La.@|;P~q3bը@l`-Nʝ4`MuzrʍQ ~xeIFgYYivADGMB~{JhnizvȐ '(,""s=N|M#⑼@pPP$D4 +;%w xUl5?4)hEsvc&EX69cme_\zQM5!+1cI NQ}GLծ$w.gxYpkaeq>_M+gΛ^lQ}c NxEedIJz)bB1XQl&B1/cD#x.L)$>FD>Y0{-)"-4R?D栶4tPSf M–)4" c)+Ml"%sx6a͒9tɴFrqinOO̞K:X8hEi2. qjJS|aN5:;>+-c!ts(n7H`_gӓ[g *-ҜҊz7]k 21su4)ݝ݃^N:tj:Ve"[3 B0 Bt‘@ʲ/PѪa+12y`Xg4î ewk6fqENlJYBw@ɭh4At0UGy4 [,\iC\ +($ҧ` ͈U!*#!>૰_5my5[he}f>l-޻i e[wq!8"IMZpz˭鹜 @8_K*G{a0$:rs lp(|axZ1j /i.3­ֿX.A* @b-v`+Ve"8Ed:ݰdvOJe€`ܪ%" =Ld'` ,\.~Gpx0bvtgQh%LhF'{.x$i.'bk 'v-\5Bs Frcj:n5+`p[( 7ޔBon- lyCӢPĚ {Ԯ"[ՅhʕK3{܁!a\[=Ep?)KsbX_*i۲" ݚWv|` -3,Ҥ&ςγJ݄L ^lJ9ٔ2o!iĂ^HZ{KvUjdzC a.ٌ#,x.(SR-$}K)~)o Bpb*9Mltcvm$T?q%5H^}3Jn8{L7Yh\>[~q׳iGc,j͂-2=خ[=߁{xMS{V Mx Z#Q#trPg.L@<;ӉO3pl^#CmћYo7"R>}Z%"pm& -ԒM8{@l.?=1 T8|O30AA5ADځO .%8(A` ^X8@CpI4[a_\#piz " [hiV .})Bg1$[|@/`^k,f`;.taopD~e%ֽ.z[h` 5Es8{0A>c)z+P@ExGi&8PO@ q&8P24* PjR5յԛ P{%C  ۹pnm|50”jkȁsy9)XmlTeshtO.V)XGҺR" uB5*rln {t쯴trv$bs |p4ͰݸribU3[,mJy 7y CᬔT6NQoRxpJsd>[4}.r7ttջtDb3|. {gA#[N4!NTzGa N[lyt\u۝w)9k8FޜNFUM *#@u[&Vzor̠>d9I{ J8[ye$a|=VL|Z v)'{NTv9Q9 L{Ngc> n?cJvm>gM~0gfXQ_dt5hy|u&ZDHI(b (R&j%%(5ZIۭR$ F(ю';d}23̒=ǎx̛yY;N%c;SpTAK| {=w?'D05g!*AY}r;ϔQZ"̤^sÛb.:E? .{ּRn^REI Yw@;tB"gz.?KF{ A֕F1}/Pͪ2% po}J g/XpLG~Y>{ H$: }ͬ30pFQ+~a'dS:]wj#a.izE [4RfTy ,~TF~z޴ 0~ÐWH?aԬgTenQxKl.M?-mMsWۏ{ y0jQQ+r/8T~M ^㐏+j < Y1r'p Xc$RA yxhZ4]\g}|̨G]c'MCxF? *濢 >PHQ2]6i[_VtN? ~}-"3":COFH)G̓3@os[e+3 Ik%Ed BX4޾57bmf' R_&u I&3o;\dMlәuWxe7$"^"qς a;vi^gK| ?1Yb[SjmvK? a6e֮ۡ+E7QMi~]Dtx>p3 SbY蹯7%< Yh0*W?>)@H#]d$Fۀ! ݾ[b+g]z*OexJβy XwoB)~2{Fr"lpdc:( N51ދ`sΨ@ ~ fܸܞs\J.2Htn( פI~!D`4uTf>҆H /C \nS+0 .B3.; 睲侅HNB5m[up(_ց _g ?#mAVI"~mG5#yE;g~睈~Nn>ņ8 ^n!BَvC;~COn4/;HOA[Tp: ye*|8Rw8 Ybu*?(^""W!ߖY&W.Yn,|;L9Bi~{]/ @ xm󐅦|mNB669-w 49 sl7NͻAc̷i5EmP.BުC_.|p]7wwC I@ :]&geZ~H^Ƚ^!b'O)/R@R6Xv&Z<yW.׍AnD(ZEc NꚀ 9m[qo;W_Mpn 7_4̬uYrB9S̺L 72̫]REbCxx8ljgx譒]BVU?<|,= wa,ރ/AVj ]F L,y6끒v&$5*mϺ q_rЋA&ve͛+9x ހ,ߟv13Z~^ A} rE6eqWCtx70'n@ 4Zig$e.ȅ?oa+Vel[q]ԅ:Wr_o㋄G p oQtC\|>po`N.C(KZǥ:?yk>Q=֜α?oVH͛D(~bvuI '^Rց.C/3`HӓzĀ{ d`Vm@^ghfLkf>'| (k[樂Q{zY,oa$QgS $ Ċ3̯O$BOU(phwG5NXj8w);i-x'N dؠeX;o_>sQ':;/ɏ59Bב'uOBjjǨbg'|OTu!XaC&t\i ܌{3@Z?.w m Df][< 5L#,twG(?s%ģ )k_J_=$ cD'd/Qi-703J9!,ε&t^7rTj;%3{5Fh(ѐĤC YcTAm{w'fbͩ)w/O` ]7?1,!m'!'JBuFJ{ ;0 m/Щ| <6?i)86k Oai.I3%: d!g $L@NLI/d5%`#3X%a`uuD`0FGgJz:R#e,Tđ9LϵX4\#%:0FG0Mz:R Α6 _ $a/`x '사 1ϿI6Oҿ(Չ4OYތ`B4k S0O.EB@? jgKO(? lrJ u5 tkja,AHݐU οEv@ڲI:{ l!H. Z'u@iôe["ӤO*?:M4ZIF8M4$أE5MjI-\5Istv9~fM2*~fXEb'LD? leg`YlDV9 LPG;&:]q+X$a]_" N`]_" œ&::'$?:,LZ'Y~VuYgN? $nZ2O5п]56!>k_lFF@7Pjg $,6Qү4c[ %aL$" qo`\d"HfF&HG $tc-,#PҿqӖ}+vsZs0iuvC|N s0JzO }6{zTIk~VyΫe~^uk]<,Gj:kZ ~Vx- /BBXl_U~!R E'#a1v_Q~Qs'E/jv_Q~Qo'E4/jQvm;mΤ̬M4wجK ҿeJQt$uMb3JIX ?6"'MJeϿM,etBVb$Tw>I~VoMاz?0 5c#?p GH`HIC` 09li\ɭ ]0җ`u-}gK_UsD裺93ٕG$a?& .`?&Qo7O#)e-n0/ku`aVnFͷzF:gIY8I~vIё.WHzt+˯h=:hQٙZx>ԺWa_bUW5xvUT3ӯ6 {!)?< r;mc$qu`u]%=@]mu`\D Q942V.@Ko {mx[ier5/?<4DtK'DrW?xP~a6D쓾LhƯ{km~t 5x*&;O95#?ˤ̼5zWykvvg%G-eGGfճlYcdvΤ&O;}SFGv1bdGkدUbB,.|XÍTB4xXJ%sםv66rz6gf*mF6e[7nL 2=5i%D16Wu_:}*6VwKB܂&`}knŤۤv釚*Fkc[w_M[cUjtbVCPu1ǯ93ƙ%l^tV;1P#g ],xhȍN^ Q7^B놨yOCTy-=J)PSL 5I <W QT;/VuZwUROȱͨ%Aȃ kNۙd[cv5F#Xc K'tG8BVlyaȇxð@1Gۇdmb#oVI}?x⦱%HfX7>6f47U0lüU;N7Hq<%TwwV]׀ SjIW!_U G@~%z?Lxzȯv-7Pys!@^]FM v^;tKVГFHfݬnwZ#_xcQeyo6uN*;Pv;1_-TJ*ӗ;!\2 i;Y~ɔp} p5chSQ32AfRܝ71JCw'gxn`%5b'yCHmc#%ԓOVVsYg`.ZS/Xd FJ)~_r}v-vZ\6W }RO#1sta/ ہǣ7v' O?S$WG8QdpUGyuK\<YU&t:d]IWA 쇬n8Œ6dU#O6pb{䗤Y^JY}/vzeP6vy-ݐwK5[=Ǝ00M'~d!guxf?'Hy(z-n~cP,Cn-gjf6@nIFM%c4 ʛ]yNj́(v녟KicSYfsF>oӢi8.w4QO?; ۮ-N>p=0к/3N-PM3pa sY{w(I>w@AS1 '$cOny!Ϛ) it|ƭo&RFz2yg(hy|r.ep<ẍ́w]6%RA<޾鞑_rي'`>^thAs!֕+T$P Aa"G\⌗sS7L=E*(pP<s8 yXbtv-m9CaFDTF M>uT5^Z]]o`PΥmӣyS!ҡt`YW2tZ#e^&FF2E3̘Lza8_1v5bƒi W|ڽj!\v@٫-yZ[}X\P6yq&t#cOyy!y{B>͐y@~RVBAiJh?y?N,;.(/@Œa!b}%M JG5=%wl 53U3hU(v$@K'FayjYӦ15(jL+O39h<8/^h(CӧyH}?R~zd~9m鋅 F$tr7I憂 CrYǫp"-o.«;ΜApД;>[!QN;{WI Ma9LI0.69*o$N)ϤݜL[ ݬrFjd an% ~qp_"u#GvuC(*d>r榾#;}Ӌz?0( 239#唨w˰ݣ_SJ^dՙr}Jb pd͍m> ii+sQk+oNg9:yriq_x!W{:bd͍0, w#r#eR&Qn|@Ic(tQ78R:Y`PY!w _FCA15V8KCTɹgA<͙u`|+N)X o:&`.>#] ≻f|ARfݩ׏CVkOr˷'d!U= c1#"sx@zA>&]_uQBUV-["5sxxj8HL^<!u}TM>N+̚/J/.yx>9i-\u/ON[ Hs:K /;Oy#msnA杙s䲑]2S`LxX,oSA\`|fֽh9ڻL/}% iN"]32锞, bPB|sÖ-eA MeE9('TQԊ?&`V Iu@6[ {NR S_璦{HpjC qA"8|4 >(_ރ2c i98A ^4 L-oZ3zOgu.;d98{E|$tiewi`cRiߌLix, mHVȭ[(E l|#mvʪEp9t@^8竓=uԠz qЁ!l.kV $TMSυHiNrK=$W.)dªc#;q !jW#p d|F=]SSNj!,tze"[pDCgO7:N| )1Hi-sL{l7VbNρ% (!ptCR7Yh"JlZѸ 4cvNOskwL^׍d>gY|raL!uIG k_8C餛;? $2M>ƜJP]T :g)ܪ@<&k_ħБ!F`d6?e.=!R?VS^>}!Zn!CTnK#Zo\W.qܮ@Cpu4!Gozz " x*BA\ S7=?Jz  8Y|z;^=XGq7OVp5>) qAz7H0PjVV^j:Mc%ࣚ8:l+?ᴖNQ~=W*Cq/σ#!s/_̜i9v1 n$'JBǂwJWܸf:,cxBf!2n+ >Ʒ,PZuj/|f/9)yJ} %F4wŽc̘KƦý{NsVDerK#.R UNz}(9/!6,lA&z8R Gi9}aegm"޽ӭzq,eW`smm}fQTr͑zy'k<Yl'mh !_ޑA4d̊+ҙ :;ː\5ƪ/)qX;!Ap3ȚVߋIC}mܶE<' Hӊ9 s Pܯ>w ,u"x8y^Gz݇H/@ JC~>MJ g~Ƣ\;,z yUYZ |gڂV׉o`O4(7LA;ct}3ql}%u; _ecZk@&yڽk8,™r?~v6a_!Vfkra1$p1͑3k"{oq!_1L)OJJL=bضȕE0'ĜO OEoNG!_9/]^,4sf`>fgq/hJ`d>S%u[#4- !ȇՐPGr 8 YWadQA63YQC_`s뜱߬l?Nڳ]`Ƴ/9#cr(/ki&,vn&B7O]Pc]]zջtSDcb+|.m[L|Z1I2<'*{O8<'uA礽f3(;<,3˲)]0^eWH Jy8_1cҼoܳ8 :6;fCB&$ۋSN.2F~=:Tt`%YK[i4J>`;E 6x|@2~t2 `XPjTvuUsA.43t:7:e頔5E\v],w>~NrepZ5>Ϝcy~H:B$7dYćxېo7>7_7lѤ9׺7٠\RL lUL:Ap4}/Ԓ{d:V C(:B=~fQ;U3Q\ Tgz4, t OA/&9VF mZ }hvCQ+#%^$jSV'OA_>CRwxikn>N,6 SO߬y'}[梺[m.ܑ` J(*.3;JVJFKͦE9߂!ڃƙbXŅ-.>in'p?$(tBVaqSNG! -Ix |d")DhVXoVZ]T2%@Ʒ2XO6۔wTU EV 5i@FKDƒ 4,ׯ==saoWjC iO_.}z@ݒXH/9cp@vKBBu(ycFyMo@!\m[dg=ߦy3c|;շ+m`'hwbt}trY_1uJG;ɴ% ,~OܾeJ9wX2R6Jr.ZCZW t%70'.nw+5 wM @IuYg`nWQ`lva߁FvʪJJ]Z0.li8ReodE܍P`@_4WsXw<]g5½ !WZߋ^q$8CfTf5M ^㐏+ؼ < (_A%'#I?/jn߇EYjSTsgpdb/@!t}ng; NF?!oW7]6;Bno5;!6^{gjcHԺ(R :gFuG<>>7b==! b.S0TFv3zA!F}7Glntv̧m}1[9(AS槶ҋTϼ OB>"uG ^NO@>_1mmǏ1'8JX4޾57bmf' _&u I&.O]&o[A^dM kәuBe7$b("qݿvҼΖ+AO1YbSRjmvKA r2wSk㛡gu ≛ƿG 4NH?-kkV)^+vܗ1,4+> `!x ~0^d %xig O+Eģh?oVH͛t'f\w<_bPw>1m }}z׳F6gP000ɴg<П'O&܋5S;tY[73]'́7齺35[j%EːYYkz/rA _+q"UHM!=pɻ[`POL+D"?_PdGP|}TVp );i-Ąa/}-;o+޷_>>qjPe^./VZ AH/@j̠=p9mJ<"͇7H_(m; ܫ`?+l !ќZr#ljuad !0½;}P uX%a7:X(?,,B݁4'w4 ͚`>3}'L(F4S"Bh|fN&arfJ{ H/,E`1:w* H>`]Jz:R#e,Tđn-VGn滵:;R"ctiӑ^`t)pٰU^/0Iћo$ ;!˟0O"Ye/b$ YA/mPi4é|&>`0}L}gYOSXD$!Qtds~ Ic[HºvDc[Hzv/0.ɵ;34UL$߯:?LZ'Y_u~N$nZ2O5.?͢mF?ʦQl$mt&|6%ad~(Efxo( c\dm%a]^`L $"F4c52'߁E8X$a]GDw`F+;abuQ~P j僲5gQ}n`t3[^NU~HuCiu^,CZU~H*`=ZTY72~Vx-ðB? paXlU~8R E'#G`1vQ~Ds'hvQ~Do'4hQvm7%L1"'͏2? ͚ڽ+(,(FґR"5>+(,@Hm~6I(>6IXZI$]U& zOҿ([>w0)^1YS; 1ҏ0?i.I#%R1># PHIA`r"Ҭ[{JgK$l8[=X%a=gKP>3)]߇M>l<>lv?0nh"ab?VnIkIA`t|gsa+Τ'`1Z|ZGG>Vߣ#@ё糯I;}I-xm~R!kDJ9>;$lzCÐ2դPS-R Z0;[qru>dcYyPT I+dXT}a6kk"Iho4Wڽ6y?kG]Crock}dȏ,2)3o0xՇgdﯿ]yهkQKّY{e9}](3ɓN8{ԩ]ّ~erKphnbSaQԶ ;mlBO܀f*mF6e[7nL ??i%mI6WnQçVqN#h3`-ƟT0L?5U*k^0ᡊU򋯋*u5:k1MЯ(=TC w\iXg\zH#u1Xyse5T,E7o@!V܅Ko2GF vwzb7*%yaX nDm;! y"jnBE{F&mŇ݄؄ \&RUC;ģj: gmFvC\Aw"R EU4p)sh2aR|p~ 5E8 yTai;~8=c K'tiU#b9[ kF`ZdH?Y~sjP5IIu >V4'5{5:U,7m` vCI6[uX7&C[|tԹ 3$ԮW9nb- C]-:ZA\7o'a(4V 6Y*760i+//IVVC0vN 4E.{="6;-Kf#H$w`ݨ2­r bY=Y\<xAe%ŗ˒I}/x̒%u- ,2a;ۄmxSe?"N`YfJei&@xQda+6>|+ \i/y*P7೐%_ǁzLC/?o,ț|0 9+l˻dMHnIG-v"t%YEgtCO.y#Iy-;O`)ehJ/ޘc}ou1xyia iK$RORNB|/{J.;6wЁs[aF d} ЊR}wMÐ+4GIJGIoM }%um#H[I'i ,2Y ̺ZX)%~ː_O?vZ\6W ZYYGGk=<gpDSERArXi%U qM@;+by]P5YȳZ&˨ ? gMgdUúX@gEDN@>OmB}TOm/C,hȱ岙u=HGf!o {&QMw?VtBzȘY[`(82CEH>axE ~3t7r=W:9N3NdEW _ϦE]֎p[ ˏZCa[/W{Ű L^瞔1((lkFTz}omxD+KU?$>~1y΃F 2dޗ&Ӑ[525 eoL}H+5իH ≛0Jh7Z[5Wrק )MҩWL{9Do|:zA,4'RAIJ' T&d+v2)tR8Ux  )5a xO%j;eM9+M7y퓈Oq'3Vht#n/ڰ }2 ?àYWf':Ԋ#8 _`6@nF72(|9Pkӽt6@.l8jᚠ"Kg"QwTDutQ+]h9sBX Pa/LaqY\weFI 5I\!/jN#eV7-%P9Gd4ܦG ~|#u/ʏ%JkWD҄ѭBڻFXϊT%JYUumI-\LgC3!?Иj\Qh8 0|Rq//@}"u 3-e?YPX, FH97v2o&mdmnOE@&=v;Kw%gٙuhz3.]]g u Tf f!OL*xŖW!C h,…Fߨ#_0DAfY:571(nZq-L. 7AޤlK?: j¨^ .9]ܾW Mw= |dwOH +G-4Ʋ[;vBVݴVj;BuiS+w1GU;5,^[ˠ&_LjՈS$ìtW9}=/)cRyI/Mybԯ{fhTCCKZVVքABG#@#,%SNar>> ܣq#rֵfȥ=*Y3¹GR_#dU%LCQPVZ)d!OReaY-3eԏ0GOi$Y-V]=Ւsyñ4N]2e56+q,X1?4vY:v+ۻiM0&-0kZ V5Mzr KߒI}/Y`kʳ1Ⴒq JJQ*kP%iD9+ZU46i4"}5|/^ʚ&],!V5MHfM#2jUY8mrA61Xq[xŀUSִ ʖӊk.GYZaYӢj dMi WʚucءI$ #+EwiQvY;*kDoMiUYӢj6`@4AK#k}5-~k ."ΚFǵiQ^'{$F1X5-ꎢ.m9E;;: iD5-ʞB$kZU4~5-ێfB8UeMըۣidMCpQn0iV5-*#uiq<Y$߾V(x]x1gΨm V<*v5o\ƹ\RTG2H0)x ! <ꖹ/Y짗*UUlMw A"i:{9U#s3訯t.-0“@A&B)@OA>dIxdu:6ބ|SǾ+np#-E&wAmʂAM 0 U*[f<5mO-\vaa-1|/0VIMx nJi5M_nAaA'U k?xt0o?Y~Ð ≛L _UjU49g_v`@Kd-=̓Ъ_FIHM0 FH֪_JֈX2ժ_FY%}ZUXd RJ `@($0 `}%$.kZU˸ݫ"d (<) Љ9gM-UkK H|U%`IHJSJh-ZU˨*SJh/DuG8y]9 H|em_ ֖LKb2U%diK&XlP쒸CP>V]/a]/Q9&ėQ:RdA/kJyKU%J%@p56ӵ2%7 lkI|ITz}ZU˨ZR_2 A/2h$/C}h8U%k_aYJM5 e\>?`E˸h0 2u*8'=ZojYA]"''>@^@6Ġ߲ &iBtw3Gј/B&7 6ztnF .m4jD_o֪Felq?`E~]ɷBj+^_|P3ʜ &UcG<3Yp(MII+$9"ǁb}V KSaxX+b] it!D<&]k4^1Wc:<#MpiB&+( yf~aXQJ LXG>>Zm"2XE>*%0 L7ԧD!J uN)Qs5ʵD9R&db*Sm(QM"O{.*%`ē8^ӪRr_J6_5.6Jr B iq}sZK'MXEX*"9  ,A=w0 TR)B+0e1!ʬFe5sn`PM/~dُ/e9ݙp ye K2j2^ԏOzUQ8Η}<OA%fq{F ]l`Pؽ~v* i"4D}=D)ĥ_O%L%Tz ҙ#j9$>">N t -,IB#1GF4F1F4Cn!2G~-[R V M?]D d x"Z!Tl|ģN/ys0 *K]X ouh霯f}l7 ߈FIMh)f6 b@kHMGHK`"8g,Z\S'V\ \qY2+".Ȃ7.#rEHv6`-׏IGp%.!7 h,W8E ,U:iPv`@ ^LhU(R,(?? @!Y#b6 pT @eZ%cU"pLPDY'R!LPz[D5!;0 T@=:} جUZK2Q dUXPEϪ`ImXXSjPDeVm06-0`@ц@gEDNPDY[%P24Eg.2{qlzu}Pn6%*(jun0 `M)@AWYl`>ik*PQPȶ6DW+* @Uk#uu%ix\תPeH\&(D[5 eo6 E\>?`EhI)[N+-oaVu3<*B$˞HY+nK u: GR|t>a W >)scg?X6]G/bNTr>WXZod/a:ˆ)3\_q2i ׊k%,V>EHtѸ*5q ):: ^G[eqkCޯ"ZzQӞ`ts`:M?1;w|vbPw>1ieR z?%ӞuS˙OO'n*عUWu3cIsMzטY-a8[ EUnemk9 D5VB~ktfYA<]D^/:|T:Qe1jƍꬰǍbO8nTS3 S_=s2|9>. љ$s(Rc 4h)/0nLj]"BV#s:! y"j)Pj}RDjH}'xUhѷ-8N@>'t3H)V\)f(bhLϝ?A*~:@jB# ="mC oӁ7q2c#H12?3-(EÔ.Y+uen_*F'W֤ۨs' VIk+ptڃsŃay.O$QVR(QmAշF=Iֺ`ǩ5&H7; ]F tqlaȘcð@1G?"$e7~M s&7RycRqk֊1gTAhlPXEHSb$f^}J8 yR~Ɉ,) Xˊՙ3Z0qE>+hp X~:.7氞^(cZ!zL G!*zy8 =;< t@G (^ɝA&kzfTz)ms|c! 8З1X1*á/_6 dN7PatB;Gģ>B2җ!+,; zo5җCq;H#6ьؚJ_5o֎7z(8pUk]o}ߗ7 @>̗Ԉ މaG; q冷\w/$- p\˘k3&Q0 ` 5`ת+J8P>fhR6vb͚f1{!(M˘J|Nfܲ@E=Z)l,`-5=tˍ P1 1by t_jƀ!jg N˃z6!!N@#ͯoʍ&ȋwVXu]46\dEH9s -hp zT/!GH󐟗6F}5FC$A'M\YwO V $mX2Yrl:oOP7lH*:˒/{Y+ugrRc*6;h~ wi!,@7< Yh* XaV+F Fcǔ DphB61Y D6 xy1>\$mˋM.%3Ż`I|GȂeVroF &(zNj^3" g[etia8՜b4?ekY:K0wmw]n3rtw{SHZDӍ(PUŶ?T-[՝YUǀ'!f ԉsr3IPRr4&seLHZ\e*1>zǗSK;dHʵd\V8V:v] z w*}D ,r[k [8hi[΢3)nZzȻhS .[nՂ-WLc³ŎOEKM1̈́%r4p*t/_.BaLƁK^/3Gmm|O}Tev8kIZ8S.kgfZ{˄ΪE0:C@ǜtЖF3m'jR:g)@< . 9H4ģ-^$u[2i$ƓLy3t6%P[QxzuAՇkqC{i"CR$PV ʳy>j]g@) [ 2vH]#p'UŸ˜,[]'c"uxй+:& 'dԽ?KpRzҽY*΢d@fA׷jGlhXvrdEF6.Z.D7jJF!-(qa<3(5!- /gHuE+K*Q|pduΜ}=n7PKJgq&sf>/Hg N˖jt9*fhM9k5-fqcWyfNxu7v_K].j& !{?n=>Zm5Zx5GFA}C}/p%֋|g\ܨ歋GKnl} 5qv̢ࣚ֞<4B8?2en͸I|!C[vdx_h /A_'kzS膟Q̻0Om#o0]D,d)Zx*'EWrp!8R! ](6_1ҙVdCҍTNrz* @Ws  ~w23+dlW:Ixi-o]q JTf{Fڙ Y8rU=i;JT{UW4ȵ|\:3Om V$,AGS"KQ NN.}Rw n(6€ꂔ*ЃҽqHA8ʘ_&De}AbݮY KnSE+tKs< 3IxmlPOhQAޢ.AjZ)jQ^+={԰\:9XC__Bf([  \i$3vN9^+J[Q] r2*|‰$#u,O?bԏ,hς^>F^xP"3PN9E(BsWi^q7M/JN~ f{'93;8*;Rsv[NjNit^Ta3 ҆}nֻa߂[unطG5 7H-\5;w/%V, 0:B4ڎ  SDa n(3VXDZA&] KۡPR50'jS+v+sҡ Dh5iU ģآU%HܥZ)WEt&餵U+jR 6,U ҉QV ]ڂO"A:\WJ.IhY t/CZUtfc" eo6 Az\}#g"Az\4HVX# w\=ZUt.j~y^67VL׭:q^%y;8[nMԟ`M+9@QnUe ; m'aiEhBnu)+` !+^^ ȉxe'W+%E(Q8,+.73 B3<O A>']9[0K/)MtU^o@O\ބ|S^tv-m2-ː_VV ԃ]Z];R\C^[dLO0MVYeQ|wƲ?y*YBcعtR/dӶT>잱^uav$Q`nPk?*a^tC_Z8vfڝ)S_uli˦@ʓ0#B7w!ߍڮ_BԿ IvR1]Vh B>t㋄ Bӄyw@{ Pj_I2xƗ/ޘӗ ٦I Fn* Tff!O4xG܋}C}hN,r+Wu7sR{YgJqiw%4,ˮ}fJeq-Vuk Cppyu^$/>P&u88rѳиƝ#2{(~ئ3OCc$ٝ<聱>Kta5O>TvB8t1iintJO{D!BSl*&JTpTrQirװBlV%FaZq /nG#Ic# B~蓰nE! -Y,4^R ΄p@aWi\LeLLnh1xR,Uڽ1D3,tMwRv^脂XL5GQlߗ\͕U5{Nblz>jm& 'yR YɌ=@ƹ]02~-_]NO~@' 6*; BΓ`H诳;)gDxunxg$}tv $ k6OTv)/c <(]aAHpe6ܣF934))ΡYWE~ 00[oIԕ+N虴7|;]I[n~f6u,۠ <W _~>Z?2ΛnΎT:~~$mc%t$/e/#6BlH+ APv`y k>\`k| Ni G-S2MMESWVLXDN1 M]%x r R8?T7I'v0`A#ǶJnd|kH5WU5" H"/jp¦Dy'ljuczy_lv}%7؏m(7@9w/w}Tˍ .s+4,;YjgOs53ְ:J`H(~O+Bu^qiQ5i:`.kR8xKY,w nT"R<iwEpo}&KQGt1ܡ)!xSᜑ#G,)kR}@ذ|}YʂnTl^|Q~)~ִlI],̄%(N2l&"TS)l,7"u[ۥ&݁Ҋ1kB rU JBRtGݏw_eBu9R|T߱_VZ@7{( >.P-1G^'Obɴgh%П'O&Tιt3c&́725[Nj[5R9g{zY,oa$Gd+->!>phG5Ndj=Oa-; Ë˰X0Hnh.!s,RF2ILC؏ _eBLVnXXN =x&|$oKI#F$Y1cějWY~HLG*o<0ܫ'FG- a;d^KyiĶMF~iEeI,EDx.uhH--ha'JM~QJ-̚F/WPj~~OO1Z1,XnTDN;Ѵm x+)ӦٝǬdr>;;$iBHn]xvvw;FU!Tnkx;y~gf5!3ES#Ҭw\i].Jfoɀ @V(s@PpT ('lPn!tp 9yt*S #bA]Вi2߬y뗄{!Ts-( Bugp-Ͱ\ZpHRjܻ A<&I7iCHJYrm;:'oFevCjA{gjg9_bʝP> 2㮙P}s !wK=;<{'s Qk1Mm-Z]o`P~a6[ښȫ7*CZo5#]CroYͧ Y3#L[#7/:믾fgW^=~ZrRvd~d^Y=kf5Ff Ll䩱'Ξ:ujtř#;zaVzKzF?M-LYo|L}wߧ܃҇t7MLi,1Kv~R4U_e +ٙbŝpWc^1j)- n˔b]L4*6vrGݿTr!j3jxѩUPݿ)KмdJ32F߭)^ٜg RteyfU23] 3WNQ^q?r}ZU_Xr9rґ|K322s65(KՅ:'9Mrv2vH-<}-wU-J\Of lA`skr>&UՙSt4mgUNI?C-_Z)DBI/tests/0000755000176200001440000000000014627152517012024 5ustar liggesusersDBI/tests/testthat/0000755000176200001440000000000014627164412013661 5ustar liggesusersDBI/tests/testthat/test-dbUnquoteIdentifier_DBIConnection.R0000644000176200001440000000205714602466070023432 0ustar liggesuserstest_that("can unquote any number of components", { expect_equal(dbUnquoteIdentifier(ANSI(), "a"), list(Id("a"))) expect_equal(dbUnquoteIdentifier(ANSI(), "a.b"), list(Id("a", "b"))) expect_equal(dbUnquoteIdentifier(ANSI(), "a.b.c"), list(Id("a", "b", "c"))) expect_equal(dbUnquoteIdentifier(ANSI(), "a.b.c.d"), list(Id("a", "b", "c", "d"))) }) test_that("fail with NA input", { expect_error(dbUnquoteIdentifier(ANSI(), NA_character_)) expect_error(dbUnquoteIdentifier(ANSI(), c("a", NA_character_))) }) test_that("can unquote any quoted components", { expect_equal(dbUnquoteIdentifier(ANSI(), '"a.b"'), list(Id("a.b"))) expect_equal(dbUnquoteIdentifier(ANSI(), 'a."b"'), list(Id("a", "b"))) expect_equal(dbUnquoteIdentifier(ANSI(), '"a".b'), list(Id("a", "b"))) expect_equal(dbUnquoteIdentifier(ANSI(), '"a"."b"'), list(Id("a", "b"))) expect_equal(dbUnquoteIdentifier(ANSI(), '"a"""."b"""'), list(Id('a"', 'b"'))) }) test_that("Id is unchanged and wrapped in list", { expect_equal(dbUnquoteIdentifier(ANSI(), Id("foo")), list(Id("foo"))) }) DBI/tests/testthat/test-interpolate.R0000644000176200001440000000610414627152377017317 0ustar liggesuserstest_that("parameter names matched", { expect_equal( sqlInterpolate(ANSI(), "?a ?b", a = 1, b = 2), SQL("1 2") ) expect_equal( sqlInterpolate(ANSI(), "?a ?b", b = 2, a = 1), SQL("1 2") ) expect_equal( sqlInterpolate(ANSI(), "?a ?b", b = 2, .dots = list(a = 1)), SQL("1 2") ) expect_equal( sqlInterpolate(ANSI(), "?a ?b", .dots = list(a = 1, b = 2)), SQL("1 2") ) }) test_that("parameters in strings are ignored", { expect_equal( sqlInterpolate(ANSI(), "'? ?fuu'"), SQL("'? ?fuu'") ) }) test_that("named parameters check matches", { expect_error( sqlInterpolate(ANSI(), "?a ?b", a = 1, d = 2), "Supplied values don't match named vars to interpolate" ) }) test_that("positional parameters work", { expect_equal( sqlInterpolate(ANSI(), "a ? c ? d ", 1, 2), SQL("a 1 c 2 d ") ) }) test_that("positional parameters can't have names", { expect_error( sqlInterpolate(ANSI(), "? ?", a = 1, 2), "Positional variables don't take named arguments" ) }) test_that("parameters in comments are ignored", { expect_equal( sqlInterpolate(ANSI(), "-- ? ?fuu"), SQL("-- ? ?fuu") ) }) test_that("strings are quoted", { expect_equal( sqlInterpolate(ANSI(), "?a", a = "abc"), SQL("'abc'") ) }) test_that("unquoted strings", { expect_equal( sqlInterpolate(ANSI(), "?a ?b", a = SQL("abc"), b = SQL("('a','b')")), SQL("abc ('a','b')") ) }) test_that("some more complex case works as well", { expect_equal( sqlInterpolate(ANSI(), "asdf ?faa /*fdsa'zsc' */ qwer 'wer' \"bnmvbn\" -- Zc \n '234' ?fuu -- ? ?bar", faa = "abc", fuu = 42L), SQL("asdf 'abc' /*fdsa'zsc' */ qwer 'wer' \"bnmvbn\" -- Zc \n '234' 42 -- ? ?bar") ) }) test_that("escaping quotes with doubling works", { expect_equal( sqlInterpolate(ANSI(), "'this is a single '' one ?quoted string' ?bar ", bar = 42), SQL("'this is a single '' one ?quoted string' 42 ") ) }) test_that("corner cases work", { expect_equal( sqlInterpolate(ANSI(), ""), SQL("") ) expect_error( sqlInterpolate(ANSI(), "?"), "Supplied values don't match positional vars to interpolate" ) expect_equal( sqlInterpolate(ANSI(), "?a", a = 1), SQL("1") ) expect_equal( sqlInterpolate(ANSI(), "\"\""), SQL("\"\"") ) expect_error( sqlInterpolate(ANSI(), "\""), "Unterminated literal" ) expect_equal( sqlInterpolate(ANSI(), "?a\"\"?b", a = 1, b = 2), SQL("1\"\"2") ) expect_equal( sqlInterpolate(ANSI(), "--"), SQL("--") ) expect_equal( sqlInterpolate(ANSI(), "SELECT *\n--comment\n--consecutive comment with '\nFROM mytable"), SQL("SELECT *\n--comment\n--consecutive comment with '\nFROM mytable") ) expect_error( sqlInterpolate(ANSI(), "/*"), "Unterminated comment" ) # Test escaping rules expect_identical( sqlParseVariablesImpl( "?a '?b\\'?c' ?d '''' ?e", list( sqlQuoteSpec("'", "'", escape = "\\", doubleEscape = FALSE) ), list() ), list( start = c(1L, 13L, 21L), end = c(2L, 14L, 22L) ) ) }) DBI/tests/testthat/setup.R0000644000176200001440000000007614350241735015144 0ustar liggesuserssuppressWarnings(requireNamespace("RSQLite", quietly = TRUE)) DBI/tests/testthat/test-rownames.R0000644000176200001440000000213714602466070016615 0ustar liggesuserstest_that("logical row names uses default name", { df <- data.frame(x = c(a = 1)) expect_equal(sqlRownamesToColumn(df, NA)$row_name, "a") expect_equal(sqlRownamesToColumn(df, T)$row_name, "a") expect_equal(sqlRownamesToColumn(df, F)$row_name, NULL) }) test_that("character row names uses supplied name", { df <- data.frame(x = c(a = 1)) expect_equal(sqlRownamesToColumn(df, "x")$x, "a") }) test_that("no rownames in input gives no rownames in output", { df <- data.frame(x = 1) expect_equal(sqlRownamesToColumn(df, NA)$row_name, NULL) }) test_that("guess identify of row_names columns", { df <- data.frame(row_names = "a", x = 1, stringsAsFactors = FALSE) expect_equal(row.names(sqlColumnToRownames(df, NA)), "a") expect_equal(row.names(sqlColumnToRownames(df, TRUE)), "a") expect_equal(row.names(sqlColumnToRownames(df, FALSE)), "1") }) test_that("override identify of row_names column", { df <- data.frame(x = 1, y = "a", stringsAsFactors = FALSE) expect_equal(row.names(sqlColumnToRownames(df, "y")), "a") expect_error(row.names(sqlColumnToRownames(df, "z")), "not present") }) DBI/tests/testthat/test-data-type.R0000644000176200001440000000102314602466070016643 0ustar liggesuserstest_that("dbDataType works on a data frame", { df <- data.frame(x = 1:10, y = runif(10)) types <- dbDataType(MockDriver(), df) expect_equal(types, c(x = "INT", y = "DOUBLE")) }) test_that("dbDataType works on AsIs", { drv <- MockDriver() int_value <- 1L expect_equal(dbDataType(drv, int_value), "INT") expect_equal(dbDataType(drv, I(int_value)), "INT") date_value <- structure(17455, class = "Date") expect_equal(dbDataType(drv, date_value), "DATE") expect_equal(dbDataType(drv, I(date_value)), "DATE") }) DBI/tests/testthat/test-arrow.R0000644000176200001440000000264414602466070016117 0ustar liggesuserstest_that("write arrow to sqlite", { skip_if_not_installed("nanoarrow") skip_if_not_installed("RSQLite") con <- dbConnect(RSQLite::SQLite(), ":memory:") on.exit(dbDisconnect(con)) data <- data.frame( a = 1:3, b = 2.5, c = "three", stringsAsFactors = FALSE ) data$d <- blob::blob(as.raw(1:10)) tbl <- nanoarrow::as_nanoarrow_array_stream(data) dbCreateTableArrow(con, "data_tbl", tbl) dbAppendTableArrow(con, "data_tbl", tbl) tbl$release() expect_equal( dbReadTable(con, "data_tbl"), data ) tbl <- nanoarrow::as_nanoarrow_array_stream(data) res <- dbWriteTableArrow(con, "data_tbl", tbl, overwrite = TRUE) tbl$release() expect_equal( dbReadTable(con, "data_tbl"), data ) expect_equal( as.data.frame(dbReadTableArrow(con, "data_tbl")), data ) stream <- dbGetQueryArrow(con, "SELECT COUNT(*) FROM data_tbl") expect_equal( as.data.frame(stream)[[1]], nrow(data) ) stream$release() res <- dbSendQueryArrow(con, "SELECT COUNT(*) FROM data_tbl") expect_equal( as.data.frame(dbFetchArrow(res))[[1]], nrow(data) ) dbClearResult(res) # Implicit test for dbBind() tbl <- nanoarrow::as_nanoarrow_array_stream(data["a"]) stream <- dbGetQueryArrow(con, "SELECT * FROM data_tbl WHERE a < $a", params = tbl) expect_equal( as.data.frame(stream), as.data.frame(data[c(1, 1:2), ], row.names = 1:3) ) tbl$release() }) DBI/tests/testthat/test-00-Id.R0000644000176200001440000000152714602466070015535 0ustar liggesuserstest_that("Id() requires a character vector", { expect_snapshot(Id(1), error = TRUE) }) test_that("has a decent print method", { expect_snapshot(Id("a", "b")) }) test_that("each element is quoted individually", { expect_equal( DBI::dbQuoteIdentifier(ANSI(), Id("a", "b.c")), SQL('"a"."b.c"') ) }) test_that("Id organizes the standard named elements", { expect_equal( dbQuoteIdentifier(ANSI(), Id( "unnamed", column = "ultimate", table = "last", schema = "3rd", cluster = '1st', catalog = "2nd" )), SQL('"1st"."2nd"."3rd"."unnamed"."last"."ultimate"') ) }) test_that("Id organizes mingled named and unnamed elements; ignores NULL", { expect_equal( dbQuoteIdentifier(ANSI(), Id(table = "4", some_ref = "2", "3", catalog = "1", cluster = NULL)), SQL('"1"."2"."3"."4"') ) }) DBI/tests/testthat/test-DBItest.R0000644000176200001440000000203414627136333016257 0ustar liggesusers# Generated by helper-dev.R, do not edit by hand skip_if_not_installed("RSQLite") skip_if_not_installed("nanoarrow") # helper-DBItest.R # Also copied into DBI tryCatch(skip = function(e) message(conditionMessage(e)), { skip_on_cran() skip_if_not_installed("DBItest") DBItest::make_context( RSQLite::SQLite(), list(dbname = tempfile("DBItest", fileext = ".sqlite")), tweaks = DBItest::tweaks( dbitest_version = "1.8.0.50", constructor_relax_args = TRUE, placeholder_pattern = c("?", "$1", "$name", ":name"), date_cast = function(x) paste0("'", x, "'"), time_cast = function(x) paste0("'", x, "'"), timestamp_cast = function(x) paste0("'", x, "'"), logical_return = function(x) as.integer(x), date_typed = FALSE, time_typed = FALSE, timestamp_typed = FALSE ), name = "RSQLite" ) }) # test-DBItest.R # Also copied into DBI skip_on_cran() skip_if_not_installed("DBItest") DBItest::test_all( skip = c( if (getRversion() < "4.0") "stream_bind_too_many" ) ) DBI/tests/testthat/_snaps/0000755000176200001440000000000014602466070015142 5ustar liggesusersDBI/tests/testthat/_snaps/00-Id.md0000644000176200001440000000033414627136335016242 0ustar liggesusers# Id() requires a character vector Code Id(1) Condition Error: ! All elements of `...` must be strings. # has a decent print method Code Id("a", "b") Output "a"."b" DBI/tests/testthat/helper-dummy.R0000644000176200001440000000040014350241735016403 0ustar liggesusersMockObject <- setClass("MockObject", contains = "DBIObject") MockDriver <- setClass("MockDriver", contains = "DBIDriver") MockConnection <- setClass("MockConnection", contains = "DBIConnection") MockResult <- setClass("MockResult", contains = "DBIResult") DBI/tests/testthat/test-quote.R0000644000176200001440000000261514602466070016120 0ustar liggesuserstest_that("identifier", { expect_equal(dbQuoteIdentifier(ANSI(), character()), SQL(character())) expect_equal(dbQuoteIdentifier(ANSI(), "a"), SQL('"a"')) expect_equal(dbQuoteIdentifier(ANSI(), "a b"), SQL('"a b"')) expect_equal(dbQuoteIdentifier(ANSI(), SQL('"a"')), SQL('"a"')) expect_equal(dbQuoteIdentifier(ANSI(), SQL('"a b"')), SQL('"a b"')) }) test_that("identifier names", { expect_equal(dbQuoteIdentifier(ANSI(), setNames(character(), character())), SQL(character(), names = character())) expect_equal(dbQuoteIdentifier(ANSI(), c(a = "a")), SQL('"a"', names = "a")) expect_equal(dbQuoteIdentifier(ANSI(), c(ab = "a b")), SQL('"a b"', names = "ab")) expect_equal(dbQuoteIdentifier(ANSI(), SQL('"a"', names = "a")), SQL('"a"', names = "a")) expect_equal(dbQuoteIdentifier(ANSI(), SQL('"a b"', names = "ab")), SQL('"a b"', names = "ab")) }) test_that("SQL names", { expect_null(names(SQL(letters))) expect_equal(names(SQL(letters, names = LETTERS)), LETTERS) expect_null(names(SQL(setNames(letters, LETTERS)))) }) test_that("unquote Id", { expect_equal(dbUnquoteIdentifier(ANSI(), Id(table = "a")), list(Id(table = "a"))) expect_equal(dbUnquoteIdentifier(ANSI(), Id(table = "a", schema = "b")), list(Id(table = "a", schema = "b"))) expect_equal(dbUnquoteIdentifier(ANSI(), Id(table = "a", schema = "b", catalog = "c")), list(Id(table = "a", schema = "b", catalog = "c"))) }) DBI/tests/testthat/test-methods.R0000644000176200001440000000102614602466070016421 0ustar liggesusersexpect_ellipsis <- function(name, method) { sym <- as.name(name) eval(bquote({ .(sym) <- method expect_true("..." %in% names(formals(.(sym)))) })) } test_that("all methods have ellipsis", { symbols <- ls(env = asNamespace("DBI")) objects <- mget(symbols, env = asNamespace("DBI"), mode = "function", ifnotfound = rep(list(NULL), length(symbols))) is_method <- vapply(objects, inherits, "standardGeneric", FUN.VALUE = logical(1L)) methods <- objects[is_method] Map(expect_ellipsis, names(methods), methods) }) DBI/tests/testthat/test-table-insert.R0000644000176200001440000000161414602466070017352 0ustar liggesuserstest_that("appending with zero columns throws a dedicated error (#313)", { skip_if_not_installed("RSQLite") db <- dbConnect(RSQLite::SQLite(), ":memory:") on.exit(dbDisconnect(db)) dbExecute(db, "create table T(n integer primary key)") expect_error(dbAppendTable(db, "T", data.frame()), "column") }) test_that("appending with zero columns throws a dedicated error (#336)", { skip_if_not_installed("RSQLite") library(RSQLite) a <- data.frame(sep = c(1, 2, 3)) con <- dbConnect(SQLite()) on.exit(dbDisconnect(con)) dbWriteTable(con, "a", a) expect_equal(dbReadTable(con, "a"), a) }) test_that("appending with Id works (#380)", { skip_if_not_installed("RSQLite") db <- dbConnect(RSQLite::SQLite(), ":memory:") on.exit(dbDisconnect(db)) dbExecute(db, "create table T(n integer primary key)") expect_equal(dbAppendTable(db, Id(table = "T"), data.frame(n = 1:10)), 10) }) DBI/tests/testthat/test-sql-df.R0000644000176200001440000000037614627152377016164 0ustar liggesuserstest_that("NAs turn in NULLs", { df <- data.frame( x = c(1, NA), y = c("a", NA), stringsAsFactors = FALSE ) sql_df <- sqlData(ANSI(), df) expect_equal(sql_df$x, SQL(c("1", "NULL"))) expect_equal(sql_df$y, SQL(c("'a'", "NULL"))) }) DBI/tests/testthat/test-quoting.R0000644000176200001440000000064714602466070016454 0ustar liggesuserstest_that("NA becomes NULL", { expect_equal(dbQuoteString(ANSI(), NA_character_), SQL("NULL")) }) test_that("strings surrounded by '", { expect_equal(dbQuoteString(ANSI(), "x"), SQL("'x'")) }) test_that("single quotes are doubled surrounded by '", { expect_equal(dbQuoteString(ANSI(), "It's"), SQL("'It''s'")) }) test_that("special chars are escaped", { expect_equal(dbQuoteString(ANSI(), "\n"), SQL("'\n'")) }) DBI/tests/testthat.R0000644000176200001440000000060214602466070014000 0ustar liggesusers# This file is part of the standard setup for testthat. # It is recommended that you do not modify it. # # Where should you do additional test configuration? # Learn more about the roles of various files in: # * https://r-pkgs.org/testing-design.html#sec-tests-files-overview # * https://testthat.r-lib.org/articles/special-files.html library(testthat) library(DBI) test_check("DBI") DBI/vignettes/0000755000176200001440000000000014627152535012672 5ustar liggesusersDBI/vignettes/DBI-1.Rmd0000644000176200001440000006004014602466070014065 0ustar liggesusers--- title: "A Common Database Interface (DBI)" author: "R-Databases Special Interest Group" date: "16 June 2003" output: rmarkdown::html_vignette bibliography: biblio.bib vignette: > %\VignetteIndexEntry{A Common Database Interface (DBI)} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- This document describes a common interface between the S language (in its R and S-Plus implementations) and database management systems (DBMS). The interface defines a small set of classes and methods similar in spirit to Perl’s DBI, Java’s JDBC, Python’s DB-API, and Microsoft’s ODBC. # Version {#sec:version} This document describes version 0.1-6 of the database interface API (application programming interface). # Introduction {#sec:intro} The database interface (DBI) separates the connectivity to the DBMS into a “front-end” and a “back-end”. Applications use only the exposed “front-end” API. The facilities that communicate with specific DBMS (Oracle, PostgreSQL, etc.) are provided by “device drivers” that get invoked automatically by the S language evaluator. The following example illustrates some of the DBI capabilities: ```R ## Choose the proper DBMS driver and connect to the server drv <- dbDriver("ODBC") con <- dbConnect(drv, "dsn", "usr", "pwd") ## The interface can work at a higher level importing tables ## as data.frames and exporting data.frames as DBMS tables. dbListTables(con) dbListFields(con, "quakes") if(dbExistsTable(con, "new_results")) dbRemoveTable(con, "new_results") dbWriteTable(con, "new_results", new.output) ## The interface allows lower-level interface to the DBMS res <- dbSendQuery(con, paste( "SELECT g.id, g.mirror, g.diam, e.voltage", "FROM geom_table as g, elec_measures as e", "WHERE g.id = e.id and g.mirrortype = 'inside'", "ORDER BY g.diam")) out <- NULL while(!dbHasCompleted(res)){ chunk <- fetch(res, n = 10000) out <- c(out, doit(chunk)) } ## Free up resources dbClearResult(res) dbDisconnect(con) dbUnloadDriver(drv) ``` (only the first 2 expressions are DBMS-specific – all others are independent of the database engine itself). Individual DBI drivers need not implement all the features we list below (we indicate those that are optional). Furthermore, drivers may extend the core DBI facilities, but we suggest to have these extensions clearly indicated and documented. The following are the elements of the DBI: 1. A set of classes and methods (Section [sec:DBIClasses]) that defines what operations are possible and how they are defined, e.g.: - connect/disconnect to the DBMS - create and execute statements in the DBMS - extract results/output from statements - error/exception handling - information (meta-data) from database objects - transaction management (optional) Some things are left explicitly unspecified, e.g., authentication and even the query language, although it is hard to avoid references to SQL and relational database management systems (RDBMS). 2. Drivers Drivers are collection of functions that implement the functionality defined above in the context of specific DBMS, e.g., mSQL, Informix. 3. Data type mappings (Section [sec:data-mappings].) Mappings and conversions between DBMS data types and R/S objects. All drivers should implement the “basic” primitives (see below), but may chose to add user-defined conversion function to handle more generic objects (e.g., factors, ordered factors, time series, arrays, images). 4. Utilities (Section [sec:utilities].) These facilities help with details such as mapping of identifiers between S and DBMS (e.g., `_` is illegal in R/S names, and `.` is used for constructing compound SQL identifiers), etc. # DBI Classes and Methods {#sec:DBIClasses} The following are the main DBI classes. They need to be extended by individual database back-ends (Sybase, Oracle, etc.) Individual drivers need to provide methods for the generic functions listed here (those methods that are optional are so indicated). *Note: Although R releases prior to 1.4 do not have a formal concept of classes, we will use the syntax of the S Version 4 classes and methods (available in R releases 1.4 and later as library `methods`) to convey precisely the DBI class hierarchy, its methods, and intended behavior.* The DBI classes are `DBIObject`, `DBIDriver`, `DBIConnection` and `DBIResult`. All these are *virtual* classes. Drivers define new classes that extend these, e.g., `PgSQLDriver`, `PgSQLConnection`, and so on. ![Class hierarchy for the DBI. The top two layers are comprised of virtual classes and each lower layer represents a set of driver-specific implementation classes that provide the functionality defined by the virtual classes above.](hierarchy.png) `DBIObject`: : Virtual class[^1] that groups all other DBI classes. `DBIDriver`: : Virtual class that groups all DBMS drivers. Each DBMS driver extends this class. Typically generator functions instantiate the actual driver objects, e.g., `PgSQL`, `HDF5`, `BerkeleyDB`. `DBIConnection`: : Virtual class that encapsulates connections to DBMS. `DBIResult`: : Virtual class that describes the result of a DBMS query or statement. [Q: Should we distinguish between a simple result of DBMS statements e.g., as `delete` from DBMS queries (i.e., those that generate data).] The methods `format`, `print`, `show`, `dbGetInfo`, and `summary` are defined (and *implemented* in the `DBI` package) for the `DBIObject` base class, thus available to all implementations; individual drivers, however, are free to override them as they see fit. `format(x, ...)`: : produces a concise character representation (label) for the `DBIObject` `x`. `print(x, ...)`/`show(x)`: : prints a one-line identification of the object `x`. `summary(object, ...)`: : produces a concise description of the object. The default method for `DBIObject` simply invokes `dbGetInfo(dbObj)` and prints the name-value pairs one per line. Individual implementations may tailor this appropriately. `dbGetInfo(dbObj, ...)`: : extracts information (meta-data) relevant for the `DBIObject` `dbObj`. It may return a list of key/value pairs, individual meta-data if supplied in the call, or `NULL` if the requested meta-data is not available. *Hint:* Driver implementations may choose to allow an argument `what` to specify individual meta-data, e.g., `dbGetInfo(drv, what = max.connections)`. In the next few sub-sections we describe in detail each of these classes and their methods. ## Class `DBIObject` {#sec:DBIObject} This class simply groups all DBI classes, and thus all extend it. ## Class `DBIDriver` {#sec:DBIDriver} This class identifies the database management system. It needs to be extended by individual back-ends (Oracle, PostgreSQL, etc.) The DBI provides the generator `dbDriver(driverName)` which simply invokes the function `driverName`, which in turn instantiates the corresponding driver object. The `DBIDriver` class defines the following methods: `driverName`: : [meth:driverName] initializes the driver code. The name `driverName` refers to the actual generator function for the DBMS, e.g., `RPgSQL`, `RODBC`, `HDF5`. The driver instance object is used with `dbConnect` (see page ) for opening one or possibly more connections to one or more DBMS. `dbListConnections(drv, ...)`: : list of current connections being handled by the `drv` driver. May be `NULL` if there are no open connections. Drivers that do not support multiple connections may return the one open connection. `dbGetInfo(dbObj, ...)`: : returns a list of name-value pairs of information about the driver. *Hint:* Useful entries could include `name`: : the driver name (e.g., `RODBC`, `RPgSQL`); `driver.version`: : version of the driver; `DBI.version`: : the version of the DBI that the driver implements, e.g., `0.1-2`; `client.version`: : of the client DBMS libraries (e.g., version of the `libpq` library in the case of `RPgSQL`); `max.connections`: : maximum number of simultaneous connections; plus any other relevant information about the implementation, for instance, how the driver handles upper/lower case in identifiers. `dbUnloadDriver(driverName)` (optional): : frees all resources (local and remote) used by the driver. Returns a logical to indicate if it succeeded or not. ## Class `DBIConnection` {#sec:DBIConnection} This virtual class encapsulates the connection to a DBMS, and it provides access to dynamic queries, result sets, DBMS session management (transactions), etc. *Note:* Individual drivers are free to implement single or multiple simultaneous connections. The methods defined by the `DBIConnection` class include: `dbConnect(drv, ...)`: : [meth:dbConnect] creates and opens a connection to the database implemented by the driver `drv` (see Section [sec:DBIDriver]). Each driver will define what other arguments are required, e.g., `dbname` or `dsn` for the database name, `user`, and `password`. It returns an object that extends `DBIConnection` in a driver-specific manner (e.g., the MySQL implementation could create an object of class `MySQLConnection` that extends `DBIConnection`). `dbDisconnect(conn, ...)`: : closes the connection, discards all pending work, and frees resources (e.g., memory, sockets). Returns a logical indicating whether it succeeded or not. `dbSendQuery(conn, statement, ...)`: : submits one statement to the DBMS. It returns a `DBIResult` object. This object is needed for fetching data in case the statement generates output (see `fetch` on page ), and it may be used for querying the state of the operation; see `dbGetInfo` and other meta-data methods on page . `dbGetQuery(conn, statement, ...)`: : submit, execute, and extract output in one operation. The resulting object may be a `data.frame` if the `statement` generates output. Otherwise the return value should be a logical indicating whether the query succeeded or not. `dbGetException(conn, ...)`: : returns a list with elements `errNum` and `errMsg` with the status of the last DBMS statement sent on a given connection (this information may also be provided by the `dbGetInfo` meta-data function on the `conn` object. *Hint:* The ANSI SQL-92 defines both a status code and an status message that could be return as members of the list. `dbGetInfo(dbObj, ...)`: : returns a list of name-value pairs describing the state of the connection; it may return one or more meta-data, the actual driver method allows to specify individual pieces of meta-data (e.g., maximum number of open results/cursors). *Hint:* Useful entries could include `dbname`: : the name of the database in use; `db.version`: : the DBMS server version (e.g., “Oracle 8.1.7 on Solaris”; `host`: : host where the database server resides; `user`: : user name; `password`: : password (is this safe?); plus any other arguments related to the connection (e.g., thread id, socket or TCP connection type). `dbListResults(conn, ...)`: : list of `DBIResult` objects currently active on the connection `conn`. May be `NULL` if no result set is active on `conn`. Drivers that implement only one result set per connection could return that one object (no need to wrap it in a list). *Note: The following are convenience methods that simplify the import/export of (mainly) data.frames. The first five methods implement the core methods needed to `attach` remote DBMS to the S search path. (For details, see @data-management:1991 [@database-classes:1999].)* *Hint:* For relational DBMS these methods may be easily implemented using the core DBI methods `dbConnect`, `dbSendQuery`, and `fetch`, due to SQL reflectance (i.e., one easily gets this meta-data by querying the appropriate tables on the RDBMS). `dbListTables(conn, ...)`: : returns a character vector (possibly of zero-length) of object (table) names available on the `conn` connection. `dbReadTable(conn, name, ...)`: : imports the data stored remotely in the table `name` on connection `conn`. Use the field `row.names` as the `row.names` attribute of the output data.frame. Returns a `data.frame`. [Q: should we spell out how row.names should be created? E.g., use a field (with unique values) as row.names? Also, should `dbReadTable` reproduce a data.frame exported with `dbWriteTable`?] `dbWriteTable(conn, name, value, ...)`: : write the object `value` (perhaps after coercing it to data.frame) into the remote object `name` in connection `conn`. Returns a logical indicating whether the operation succeeded or not. `dbExistsTable(conn, name, ...)`: : does remote object `name` exist on `conn`? Returns a logical. `dbRemoveTable(conn, name, ...)`: : removes remote object `name` on connection `conn`. Returns a logical indicating whether the operation succeeded or not. `dbListFields(conn, name, ...)`: : returns a character vector listing the field names of the remote table `name` on connection `conn` (see `dbColumnInfo()` for extracting data type on a table). *Note: The following methods deal with transactions and stored procedures. All these functions are optional.* `dbCommit(conn, ...)`(optional): : commits pending transaction on the connection and returns `TRUE` or `FALSE` depending on whether the operation succeeded or not. `dbRollback(conn, ...)`(optional): : undoes current transaction on the connection and returns `TRUE` or `FALSE` depending on whether the operation succeeded or not. `dbCallProc(conn, storedProc, ...)`(optional): : invokes a stored procedure in the DBMS and returns a `DBIResult` object. [Stored procedures are *not* part of the ANSI SQL-92 standard and vary substantially from one RDBMS to another.] **Deprecated since 2014:** The recommended way of calling a stored procedure is now - `dbGetQuery` if a result set is returned and - `dbExecute` for data manipulation and other cases that do not return a result set. ## Class `DBIResult` {#sec:DBIResult} This virtual class describes the result and state of execution of a DBMS statement (any statement, query or non-query). The result set `res` keeps track of whether the statement produces output for R/S, how many rows were affected by the operation, how many rows have been fetched (if statement is a query), whether there are more rows to fetch, etc. *Note: Individual drivers are free to allow single or multiple active results per connection.* [Q: Should we distinguish between results that return no data from those that return data?] The class `DBIResult` defines the following methods: `fetch(res, n, ...)`: : [meth:fetch] fetches the next `n` elements (rows) from the result set `res` and return them as a data.frame. A value of `n=-1` is interpreted as “return all elements/rows”. `dbClearResult(res, ...)`: : flushes any pending data and frees all resources (local and remote) used by the object `res` on both sides of the connection. Returns a logical indicating success or not. `dbGetInfo(dbObj, ...)`: : returns a name-value list with the state of the result set. *Hint:* Useful entries could include `statement`: : a character string representation of the statement being executed; `rows.affected`: : number of affected records (changed, deleted, inserted, or extracted); `row.count`: : number of rows fetched so far; `has.completed`: : has the statement (query) finished? `is.select`: : a logical describing whether or not the statement generates output; plus any other relevant driver-specific meta-data. `dbColumnInfo(res, ...)`: : produces a data.frame that describes the output of a query. The data.frame should have as many rows as there are output fields in the result set, and each column in the data.frame should describe an aspect of the result set field (field name, type, etc.) *Hint:* The data.frame columns could include `field.name`: : DBMS field label; `field.type`: : DBMS field type (implementation-specific); `data.type`: : corresponding R/S data type, e.g., `integer`; `precision`/`scale`: : (as in ODBC terminology), display width and number of decimal digits, respectively; `nullable`: : whether the corresponding field may contain (DBMS) `NULL` values; plus other driver-specific information. `dbSetDataMappings(flds, ...)`(optional): : defines a conversion between internal DBMS data types and R/S classes. We expect the default mappings (see Section [sec:data-mappings]) to be by far the most common ones, but users that need more control may specify a class generator for individual fields in the result set. [This topic needs further discussion.] *Note: The following are convenience methods that extract information from the result object (they may be implemented by invoking `dbGetInfo` with appropriate arguments).* `dbGetStatement(res, ...)`(optional): : returns the DBMS statement (as a character string) associated with the result `res`. `dbGetRowsAffected(res, ...)`(optional): : returns the number of rows affected by the executed statement (number of records deleted, modified, extracted, etc.) `dbHasCompleted(res, ...)`(optional): : returns a logical that indicates whether the operation has been completed (e.g., are there more records to be fetched?). `dbGetRowCount(res, ...)`(optional): : returns the number of rows fetched so far. # Data Type Mappings {#sec:data-mappings} The data types supported by databases are different than the data types in R and S, but the mapping between the “primitive” types is straightforward: Any of the many fixed and varying length character types are mapped to R/S `character`. Fixed-precision (non-IEEE) numbers are mapped into either doubles (`numeric`) or long (`integer`). Notice that many DBMS do not follow the so-called IEEE arithmetic, so there are potential problems with under/overflows and loss of precision, but given the R/S primitive types we cannot do too much but identify these situations and warn the application (how?). By default dates and date-time objects are mapped to character using the appropriate `TO_CHAR` function in the DBMS (which should take care of any locale information). Some RDBMS support the type `CURRENCY` or `MONEY` which should be mapped to `numeric` (again with potential round off errors). Large objects (character, binary, file, etc.) also need to be mapped. User-defined functions may be specified to do the actual conversion (as has been done in other inter-systems packages [^2]). Specifying user-defined conversion functions still needs to be defined. # Utilities {#sec:utilities} The core DBI implementation should make available to all drivers some common basic utilities. For instance: `dbGetDBIVersion`: : returns the version of the currently attached DBI as a string. `dbDataType(dbObj, obj, ...)`: : returns a string with the (approximately) appropriate data type for the R/S object `obj`. The DBI can implement this following the ANSI-92 standard, but individual drivers may want/need to extend it to make use of DBMS-specific types. `make.db.names(dbObj, snames, ...)`: : maps R/S names (identifiers) to SQL identifiers replacing illegal characters (as `.`) by the legal SQL `_`. `SQLKeywords(dbObj, ...)`: : returns a character vector of SQL keywords (reserved words). The default method returns the list of `.SQL92Keywords`, but drivers should update this vector with the DBMS-specific additional reserved words. `isSQLKeyword(dbObj, name, ...)`: : for each element in the character vector `name` determine whether or not it is an SQL keyword, as reported by the generic function `SQLKeywords`. Returns a logical vector parallel to the input object `name`. # Open Issues and Limitations {#sec:open-issues} There are a number of issues and limitations that the current DBI conscientiously does not address on the interest of simplicity. We do list here the most important ones. Non-SQL: : Is it realistic to attempt to encompass non-relational databases, like HDF5, Berkeley DB, etc.? Security: : allowing users to specify their passwords on R/S scripts may be unacceptable for some applications. We need to consider alternatives where users could store authentication on files (perhaps similar to ODBC’s `odbc.ini`) with more stringent permissions. Exceptions: : the exception mechanism is a bit too simple, and it does not provide for information when problems stem from the DBMS interface itself. For instance, under/overflow or loss of precision as we move numeric data from DBMS to the more limited primitives in R/S. Asynchronous communication: : most DBMS support both synchronous and asynchronous communications, allowing applications to submit a query and proceed while the database server process the query. The application is then notified (or it may need to poll the server) when the query has completed. For large computations, this could be very useful, but the DBI would need to specify how to interrupt the server (if necessary) plus other details. Also, some DBMS require applications to use threads to implement asynchronous communication, something that neither R nor S-Plus currently addresses. SQL scripts: : the DBI only defines how to execute one SQL statement at a time, forcing users to split SQL scripts into individual statements. We need a mechanism by which users can submit SQL scripts that could possibly generate multiple result sets; in this case we may need to introduce new methods to loop over multiple results (similar to Python’s `nextResultSet`). BLOBS/CLOBS: : large objects (both character and binary) present some challenges both to R and S-Plus. It is becoming more common to store images, sounds, and other data types as binary objects in DBMS, some of which can be in principle quite large. The SQL-92 ANSI standard allows up to 2 gigabytes for some of these objects. We need to carefully plan how to deal with binary objects. Transactions: : transaction management is not fully described. Additional methods: : Do we need any additional methods? (e.g., `dbListDatabases(conn)`, `dbListTableIndices(conn, name)`, how do we list all available drivers?) Bind variables: : the interface is heavily biased towards queries, as opposed to general purpose database development. In particular we made no attempt to define “bind variables”; this is a mechanism by which the contents of R/S objects are implicitly moved to the database during SQL execution. For instance, the following embedded SQL statement /* SQL */ SELECT * from emp_table where emp_id = :sampleEmployee would take the vector `sampleEmployee` and iterate over each of its elements to get the result. Perhaps the DBI could at some point in the future implement this feature. # Resources {#sec:resources} The idea of a common interface to databases has been successfully implemented in various environments, for instance: Java’s Database Connectivity (JDBC) ([www.javasoft.com](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/)). In C through the Open Database Connectivity (ODBC) ([www.unixodbc.org](https://www.unixodbc.org/)). Python’s Database Application Programming Interface ([www.python.org](https://wiki.python.org/moin/DatabaseProgramming)). Perl’s Database Interface ([dbi.perl.org](https://dbi.perl.org)). [^1]: A virtual class allows us to group classes that share some common characteristics, even if their implementations are radically different. [^2]: Duncan Temple Lang has volunteered to port the data conversion code found in R-Java, R-Perl, and R-Python packages to the DBI DBI/vignettes/hierarchy.png0000644000176200001440000022345514350241735015363 0ustar liggesusersPNG  IHDRJPwFiCCPICC Profile(c``RH,(a``+) rwRR` \\À|/­+JI-N8;1doyId$e @"- v:}¾V dl&]| SR@0$AIjE v/,L(QpTg^)(!?ÓQ B bs$20A20,a`S3d`g`7' j #1!>CI pHYsgR@IDATx |չHH&  hPTIe K [B@?JQ[*P-޲IPH,H s dO&3gY|uf9K<@@@@@<4@ذaǻt `\,/@@D% 7nL6M#8T':^*C@Hzڏ uԑiԨH` 8u D@(Sfgp     $Jݼi    -@l#@@@@@7 QL@@@@@leq    R7`    e (-ۈ3@@@@@Hy<@@@@([DiF    n.@;!    @$J6 @@@@psn4@@@@ QZg     (uy     PҲ8@@@@\Dw0C@@@@Hm     $Jݼi    -@l#@@@@@7 QL@@@@@leq    R7`    e (-ۈ3@@@@@Hy<@@@@([DiF    n.y 6liӦN>}z"    QhqCX~R[xڵR_E@k\__t[Q>G@-GI) M믿[Y&+)IrѶnZZ֯RCO~;i>VsbDZU @@L,@ĝG  sr%=zWn4[lH{*;O~-HlZb™#ẻҩ;^fj#~ [I{9)4E@՛,}#`9nqv\N$%Jbbw 40   ++  PQ$[=[̅$wy!""=.nڟ]f7LSx %ݝrIrL_P-G$*($2%}dOjM,JçΖ-}1Yp XBs˜n 3[S},~5RXğ8+\>(CW4ms5ںrĆ @1Z<ت3IOmeOl=%@,**Y\3om|^T<mX}@d>v}uMD 욾 5Jݻm*a݆^ =KOd\4ٿȽIKWHU[1)*[k>[#z^-[lۏr2ܡeW-'@@"va@@|idL I4r>LJIm6g 7rtUE'=&'SR$99Y\cwѤdLcZ!ٳg:_>}:)+9~IIH5'M}`璚-i22zUx2)fd1v4hGVK^Jt"u#I<{fH$czrG- )e|{\IO=$K/5H=cg"j)}'Y^mGW?ID驒} 39AL+/5ef9*)F_SjIv1Ҕ2e@@{ 3{HY  `mʮ]QF)R.yhOPc&ʢըlY:OF[%YWT,mNY*~mlG}T8Iʙ_8>} ir~Iz>t(jhAg$hWW&eK wA|2$@滄Γ8ԢǞldjppHbMZ.2w+v1Kdͨlc3'vcUewK\I^˼,0c iذL8 v@L'Ru# irW(1sB$UeIfF.'ON*H'r.@!ŮR,?IoTf!3[IRuOƨ׊$$X&.FRH,6Ij$:M$Um_mlZ#taXѩAdn ?P8 @@$JH  @91,cd%D,bsJ55Br̤tNދN brZ <`34ӷe?YuBL-%Sn7FuNۃXumZ$:i\g=VdSEO-#V/F&Wr͔M?ʢkEH\֏3~' 7퓬V/LxBN /|^p̜INd n|  `w۝@SH)'k˙id_ۨƻN#i6Pߚ_Ίs%-\P&%-/iY )!ӈǟ.Z/4hXmW*.LI[o6elհ]ؿΔr-hQH_닋Bnэ4@hf2  @u xo&[/i,и]JZr:zUDTzgȚw^)L"|,F^{Pef-[UnFī  H:Κ@@*+_^l׽̍f>؍*[-! xkzN_R@@ -ؼm$r@@ (u*?# K?X]2SBك)8|D>!ߋ`4i09 @@8s  .&%!Q$θeggKI&J|" TEOUZ@@ q   `OS@@@@@$JMm     QjOMB@@@@S (5e4    SD=5) @@@@L)@ԔF     `OԤ,@@@@0RSvA#    =HS@@@@@$JMm     QjOMB@@@@S (5e4    SD=5) @@@@L)@ԔF     `OԤ,@@@@0RSvA#    =HS@@@@@$JMm     QjOMB@@@@S (5e4    S˞Q O2ydiР $@3g̛7$@@MFq[h  ,;wt@ x{{s=W+8@!@    `RSw#    =HC2@@@@@$JM}     QjE@@@@@S (5u<    CD=)@@@@L-@G W̙3 @ϟ7E !@5(@k׮ɲedРA /xDid[n>9 O,- ^  i$J=i/ Nؽ{e„ BJ8}$%%`ddv]v%66Vڷo/cƌuIvvٛF  P 5ʥH@pT=ztɒ%#G#GJƍ=\ Ç_ۗx\Yj۷Ohӈ Zj٭ B@ (5o9 .'puٰae:A#\:$J]/<%vڵkE%MSRRdС)?N@(FDi1(< otrt͚5jv+=RDGv4Z-ojei @@Z@@ZZXB'HHRݱc4k^UP P-Z^{Mj3<#wyN@pǴ@ ͛urһ׿{ҹsgAA |AQ3fȞ={tTaj~F" @5 0)@wPԺ+WvITT 2DܡyLwrP}7oޔx4GISuʁ #RKZ ].]*AzE{׮P jՒ^z[vvlڴI'M'O,aaaz>}+7@@(-  )?ѣjU~ڣݻwF:*,!111zDZϴ[nRF*O  x7F@\N:9l2=bTm4l0wX H_zZΞ=+k֬I3g~#>>!`J6v@rre-~~~zJlAP  #be״@iiirJ QrfL*BG(K ((H~޽{uҴW^:Q>eVBu@)rBq ͕͛7W_}% .]8:CZQZ?|:i6zGD2Unb cH:ƙZ@(ÇurT m׮DEEM=ԩS283 (5So \~]o߾]z)4ӧKZg 0廈@|QN@FzLWP@ʒMJJ#Fj)@* xyya0׮]7ի7[4Uy #Jݹwi @ /^,ׯ.]ѣdS; 0ԝzKdݺuzzÇ%<<\ϐڵԨQÝJ[@$J @RSShQ3FF)7`IJD)p}ާFFGGEmfO~D @9H@<[ƍa=~2tP=z4$$ijah=v QjD@ǎӣLW\gPDDDi֭U! `7D@78pZfyurtF)8WDs&Pv=j]wUb@Sة@DQS&Mjj}BB4oܕ&6@.fV۟'پ}?{l=%?22Rk@02j\ veݹsQG4]ci.&RAj[i\\t]|١oKr@OgK &8r䈞Z6urԩS" 'Pvm0`]rE֯_/-I&IuҴGRV- @}SO=&-WDyӧjFիW(S5=l\ @HV@\Y:9|r=vec W5b4kÇQWi-O , L ̔kɓ'gO?Tڶm`@JxEf̘!wIP ISgÆ K-@#JH .!)jh^f͚.A @(-ޅgd7orz6m{L'M(wy'v@j`Di5R4 @ :uJ.]oYfIrj@@jUS*i:e IS޸wO )wZZ ++KԚ _222tt2~x]G@ZWg$&&?|/,?//"! P FVK@#g%I7ڥKׯxyvV@+Pn]yٳf3gf#86(jCpYMW@=e˖*!ݻw4n=L@@\M6^zIRRR&P/]!*iڦMrI (6s ܸqC6lؠG۷O;\U`3R 8p@'MW^-M4 Çw]x@(FŠ s%Kbѣ걏sV@0 noܹSk׮Ҿ}{ Txx 9@`D@*pyYbZ55j4oܡqP8Oγf}ZoȥKDm6- `fFpQYQWMiS?SRF @Y(u<"@IzJaF)?$ {(u~ K?~\]ls=zja$ %#pM/Dݫk֬VZ餩|Ӹqc@L 8Xʕ+K7ey|zg$@@=̞=[[:u>>]s &` :@W8uꔨiK,z#FJā&` ;@@ ##C֯_jmv~@.` ` &D'%111zjّ#GFGfXu 5#v$JݮKi+p9QkZJj-S5ҴcǎkB@3 (5So+ @={董j.]]/^^n*|XFP[5<҄F# Q(iA,p=rtŊz(2dSTe (-ۈ3@3RSS2IrQAEFFJppgj@z_8RzGUf?j(U˖-u! AYf/ѣG(_z:~DD1BZnm(@@ 0 t2tҥo>}zY&[GSQ)=M;@^IUV=ܣGѦwu@#HzdhpǏuGUEzÇK@@;46  (Φ `W>Lz!42dԩSec&0@UHJO P1 E54""BoU8p ޻F?P@MARdԨQuViժ [C  TL 00PLoПմ&MX8QD'wUXӧ̘1Cz)g2_w1  {u(;wIST(pWj@zz_=n&uGMmƤ6fRYKi x;ޜ@GWV҃ x 4߿9"@*$ qq2x+Wdڵzj/#GԻ}5H9@@@toooyիgɲeW_}iϞ=VZī Q hA7)jh޽f͚i"&`D:P@;\xQHP#M=*jT T.]P:E  QZy;D78}tuJTTAZ~}7j%MA\SDk Q!PW^-*i6KU[Z۔pã-N} 2YYYb <<\222d/, 4޽* PQp9 .ѫW]y.+!  @ֹsd͚5oӧEe;vZ%\'fN4yl޼Y.]**):p@ }'ܧ6sN N8!R Su HHJJSWX?_ "uP[D@W8tN%5j7>|8\È ` t! @/_֋jjͨQd֭ҪU/ @@8:͜9SvܩOtMtTmZ~}s P#JKp@^^ѣһwoQ=FN@%R{IR @Y[Q[lΝ;뤩 je:/RcZRRRjQZ?gQ s   }۵kdƍ:iF̈^z:]0nݺ%#Gd!uB@!@ԉ PGGi֭s9 zo#\*-+Wp t=~2afXF@@>~'||{Z4,,L?>w!y(>8T믿Sz:uS:X@#Jw `&(>Lz!=5`$V QZ O!@Ξ=D_dԬYS'GyiҤI j@ QJ@qlٲE'Mm&ݺu0;5 M6ѣ{!C(>f@@@j׮-ԷL=tѢE+O?j15\_GDK !!A7o u   @95j$ƍӷSNjkdzMvڕ$NAG 0ԑԅn޼Q;vȀt'0q@Q @  #W#M(ӈiѢ#(Ce2.,/+VH۶mLϗ;ih?   P!ۋ͘1Cvޭ=zߵTtСҰa  `?V%%!6/_?X???ٺulܸQ'JIMW:@IDAT@@p@ΝwߕG믿.jSܐ=tz3'Fx#J=i8yyy7f^zɴiDYF y   `ZjI޽-;;[6mڤGN AXd^A#jѥKJfQ5CÁ #Xԁ `65/&&Fo64hN> f1[giQj"P'pYnNDȑ#}gJ( @@@u֕{NΜ9#k֬ѳΞ=+Æ #F?\ 0 ;wQhnQ5CM@@Y(u<"Q %%EO_r?22RkڦM36p).N>իj:ѣ/ 4e @%HVK@08ѦwuF} @%h\ կz3tYx$$$Ȅ $ !  e ӟȑ#oʷ~+]vuN:>x`DGt3{jN:ѣgwDO@;@ 0ԤG .)#[n Q? {wC??"1?.:tw}5Ex“QIM[R@-=gyuֲgYb <$[:B-&Kl… Eˁ ~ZIIIzeˤ]v2~xٲeܼy5jȎ;EҹsgoAQaNsCƍi&=zT"2d=裏Gi F/e#Jը߾}aÆn@@p dڵzj9zFvҥ ˯~+ pSQ)=M;B 11QL Tm{OHE@c4@5zPu͚5㋙- @m۶+x = ԣK&QxROmjJ߇~וy/R:*Qkv4 g (US T1i$VZz]?/;ȳ>+j:j@>^U;[ѣԨQKy @P̨/ɓoMi f~Ni~5?gΜGꤪ^ˁ 0z8M@MG/ Mh{|wtR}urTX`{*@p{5tΜ9:Q6rR3+8@@9>>>zMR.iiWw QꎽJ*+L8Qݢѫ?Dz}ڵzJ1B?Vq  m۶?0^xQԨ]v7O& B@}@zJ& gZ.7h@V^-+W _w]USyCW/ "/xyyɵk$%%E+X@@p@MJ\@M39sK{=ƲI.]^zIoEI~HZ"q@C''N5T|@@%@YkZҥ;rbۡvTkL0AR@(^@%GH .x@@1Lw3'|"Ndhi;vLN5@<^UVҰaC@@9(u;L@r _~Yӥ$j^ffdM%\@.#$@@B]-0@q_|DEE稍'ԩ7PkJF@i׮׿?  PѣSN%  8Fq ۷O}QַMʽ+m۶ }_=V}&m%a#   (5Fjƍr&/!   YD{@@@@@.ldF A@@@@3 (5s;    ED])@@@@,@̽G     `va@@@@0R3#    ]HڅB@@@@@^*ׯ{3s[@B@}ڴiҤIg 999oKzz+C  .&+"#;op?5h,_~L8i1Pq|w.ޅg@3 X~w#JUcԈ^x"v@ AҥKpו6l+u .$p)Pll+c@ߝY}I     `v@@@@@0Rs#    H"@@@@@$JD    v QjD@@@@@s (5w=    AD)@@@@-@G     `v@@@@@0Rs#    H"@@@@@$JD    v QjD@@@@@s (5w=    AD)@@@@-@G     `v@@@@@0Rs#    H"@@@@@$JD    v QjD@@@@@s (5w=    AD)@@@@-@G     `v@@@@@0'z dIK}ߢ   >xI.A  ,@ԓ{ ۞{e$1kt Y=M@0@, jǘI 7@p@&'k"Hԕ"M[Q2"֟ZD w@N 7[/Jx+iīA3fXع3SSnjkJZ6#vTa|@@ ͒=s]8(ʓ)M?I lIMOyD{:"uRNCipwSicCEN:H)u5CwD/׷/iW[5#1ʩ(4]Ff|2mP\uaҴe ҩK_"9iUDIV@ޛ{RzK6P{-UۢCOwh)rTײTt;29hq?|8~[ϕs'JcsxX9+/c muƏ֟ZlO1  =sy罵b|-/P?5J>Ԭ2oZ%"OϾ"im\#S>h ccn:wM )υ}vwfjr`q| 7O1w \ȕm*sf:F'[,˔59 AUcdev7TC&vR_.22 X T731FFO/{߬)FS%1-`-LTm.??]7Hq](UTP '1XT&SWW?X]@ [ޖY ~m>s,ϭFL>gl8?"wi$JTA9]ڗYrh9v;M7dA̹r׫fE>)1E Wz7?/9U&0r")Q z `V$7j)$$iqVݻxV = _)LUKLp~^7~_i&,׼6oLFI YgA՟q<6oR%Y .g}M;5潯e$gƲ^u?xܼ%}1>clSrD%r..7u̼q燎7xmjԩ6Y㬯/=xn%U+oŻgFl3K.0}sV{=TPq>_U,W-_kIK,?W= Y'68jHWËysms{fI%cQf2bfOUP>U3oSQJkzpNȲZzʚ:[% ٲ7U:53K3xpKs~6٥~ҐM39zRf_{7Wͅsy*;M02bY‹eƭgI2zK6QjM~?hq#L{QƏ/>;Djx7 \h[ Qiͫ4Xt# JpJ/R'H+=:H>crb\7[Y`IA$餹Ѳ;1w?QU?l$ڀ@6hqvX]~emk.l4-npkw%tXk B~ddj&".M;wL2$Ir?{sUJ w,uÓa@ ީ/zwݺ{j$Yk*-:խsg}./rZb *ަŽBFb^* O13Lc^h?nUJ: +t&N{/: zkځ \"U:F3?RvS|6?urE'1OF̿mmӶkf}l;Bհ8ks**-E4 8F{Sڷa}b1k%Ͷg8 1{Q2] ~QfKhqp9?\aW .ezr}9S9{=>To@/3 ~rty#z)Jq2StfM}ߵfzX,Uő\PJզ@ǣZ/O>ykz.hMU{Yð=B؅ 0<׽PJszǾ֣YW[Nx(K vz|xTY3ݕrYcfWVfio:ۼ7W"VLL?;:ߨ5o&1C4LGLy߬8g}{VMPPK|單̥JZ(X̽qsbZ7({4yEz7b؉L<7\5chEҪ …qׯoFҘQϽpTy)v-n^2]e3%#O{^iˆa6<״Eg`^hR6o嫸&3Ov>3,|ǝnYnF7 CߨE4I@ ʏb]LrVO{$[CƝϪ)kR WBjmԤ~x2ڪ__'H^ؚGۗ̇¨O֕{ FYo5'MT7xΕXӚҡڃVI{]]{fP!&v>ЃukDƾ+_B՛FЭi5/;bj$V}KyId_t^J5OOҦczq } tҕwY"=MO:JV3 46aq8"Wn@OFRkz01 Qs@`" A쎦[mPڊ~Mј;jm7?y_Zo. 1uZ%`a%=+OkwͮݥL-> D PNw'ض+ޅtx5w[wH;;0-[5 q޼ܵI=1)Y{o_P{KoܥՎ^'ť %zX+ԃ&9NfV/NM\] Hٽ256iFkP7_LQXs++d\ٗ;BH5ڬ`.Uj)s>,k\Zuik{Lj툡m19kXOd9]9̩\sؽ럜݆<}Fp/-]7*S.awo?j[]nNxu4_=5գJKpZo#WUi;jib/ݝGǓ`SV^zN+eN?UN'WyKWg:? k(m᷂üz}gn)#oMt̓Ua+ֺ$>G5 l` \"k 82qy@`iY>7'x30O+o~PSca4ڻabs2==crѩƃFR+(Cݝ7֙lg~kzcUa]%լ?y OTNr &, 0 "mzz}zUjo]ݷ7uu~|jjMm:7#X]/ا?Lw{,˜%7($( =m^`î pk.tbc|HE8jVOw N.ܡT}g;o)1Js4u-&wk˶9 7ڄ)!vN ya!ɕd 5@W T;YS\ a\Yv0 .p= Z~KwQ=^|.[I3t3?f3kӤ&μnn(7z@}bwbOyKwhϦŶVTrq__q (ҨzK}KC\ln.n:s Ρjowkxm\@` {bp׿#2oS7ڸͷ]]?zYvqU^7ڢwgW7o:i^]'ۤ7p߷ ӏ%oS.J~b=Ъ:9Mڣ8>xh~G*ڛPO>gnMݱiI`xj<ӧNIuǟoj*bpy+^~HNE:sͱQ5L]UoL#jCixpڤ1Մ>+]MyԜ C95Uka[+M/!N/wbǞF\BB{OR%Pϛ@R{.>3o@=o-Y{%B7 {/JY0)S6wkǗ8 %;!ֽٟh{(5Z1=yToӥVȷ9o6xܼhj1VϒBZk߭[ާWGqmey_}{U9m/6Ӧޫ>⵺d|>&cFnjK=TL=NfkђeZ45Ma=u7;e߼Yk=!_ޥ[j=gNJ- h:NY7_ֽ; sYo)>Sm}_nPÏdzʦ7Nי"\yY@ "0 &_eU;жU|[TksG_lWybZiw׻]߱ʼ2)"7O7:K e4Jm\NsV>zݶw+hY?}\qjvR͞+ϢE;j <.gm< |CY, hUx3O)w̵sNUª}Hwo}aLaxjCc>*_ `|iqq8̗gx"+/ÐwwrF-g[$y_xߚ5k'A*%ս?߃Lzu:h.tBy_ =ezSYF_~1ߑRot޻{IűrOmMo룗_1Tp7-쬏r^2xGˢMXZno%uV_YYY#Ap51sؾ78P*\Տ1կ~/px|UվC}eE[;8YY"J-VM 94FW`-"Ʈ1(`lG2[R#-߶ TG쓆C/jS|ˉ߾:{/3o/7x}יSަC1 2 ұV{d/ǻc)Ѓ q0/{x̐^Uc, _ T|G7eÑك  k/G}qX6;d0kvWǒs ZWݨ+bx*pCniZijw/TCMϿ&*TUZQ]s“!̂hNqaz޿QnJ s_W;Osj@#0 Lu #K'l <[ޥklY6^,mW!u+ "3fn}a1Tj3t>l+ Bo t4CM`YjSyUjdƲ,Phn4W-^g?ih-aʁr&GQPp8;=gwr䫤Z:: @սW/c敨ցt{r DzORm19Tu䤺Z'CzTmUV^sf޾:Too_)WX^ ~X-*oSyZrG%mԖQ6YEQz/mORhUaL-kۣP̈́6+0Dˊ#,k"g 0AxOQIѣa||>1zS[mѦ<ya}U|WU;{?d[ y?ϳ-U6 ጼMj>Ra^iZ-kSCGYOO<裏/Ѫs|,δ!(37LkYk}!yԬ31C0p >\O~?~ 8: w歵SL'uŜ9HwFqlљsy+e֬9uWDžV9Ϸi4sv+[,<3r(wwu|1kߴ{rll[,9|+_1giÆ "U HcǼQoΝ4\|yw˪{iWQVL慈(ɚ9Yq͌޽/|4͜1C1[ c2*v:D539+3 jB@`HYZh~hFfգ}UIxNz+#s4v #/01EٹfEsq#`&w mPGbc'`h#    P:E@@@@@@`h( ~@@@@uJGH     ]ď    .@C @@@@@H7l oүJ-_s8    !@Cn~\x1 q@@@@tep     @ 0Gi B@@@@ P0j"B@@@@d4YKt!    @h(M5!    @ P%C@@@@@ a4&@@@@@ Yh(M֒!]     0JFMD     4&kɐ.@@@@H &"@@@@HVJdH    $L҄Q    $ Z2 @@@@&@Ci¨@@@@Ud-҅     4aD    *b%K.??&kI Ξ=/|WrH L:UUUU صk`yveL@` ؟'b|{ŋ'9FƱ@AAF9xgeU, &O{׽$9I d (xv6c    )(SEb@@@@@`$h( UD@@@@1%@C*.    #!@CH&    )JTqX@@@@ JGB0@@@@@`L P:"    H$uC}ݧΑ ^۷o3 j,iDXݫg}6ӓo|Jp&'? g @Dq"D܉UD;q. VOO8/[o8:( <_JgΜ|p}8rB@]gK+b̉( @3    $^ě#    $ IV $@@@@/@Ci͉@@@@L$+    4Ĉ    I&@CiA@@@@ PxsbD@@@@$4     @h(M91"    @ PdBr@@@@@ 4&ޜ@@@@@ h(M!9     xJoN     d4&Y@@@@H 7'F@@@@H2J@H    $^ě#    $ IV $@@@@/@Ci͉@@@@L$+    4Ĉ    I&@CiA@@@@ PxsbD@@@@$4     @h(M91"    @ PdBr@@@@@ 4&ޜ@@@@@ h(M!9     xJoN     d4&Y@@@@H 7'F@@@@H2J@H    $^ě#    $ IV $@@@@/@Ci͉@@@@L$+    4Ę`GyDiii6m7Pff}n@ƣsE} ?&MǬ'@<;B$ q  vttS__}uV@Y4e;o_z I@@@ p³sI5z='J //'R|V/+VD:>@-`9і hُ ΣO"@Ci1k߰o~s@Xn6F<}ҥ@HHh P:%@ #3sLzDa' PİF0|SJ\ $LgQQ PCWӟt>^gBC&@=10:? /s)YJG֗ГD Rz$I @` tMa9bC ;@@ xvNB!I 4D6ZzлgJx@+iRF0&g 'SiP:5V3&D#I//2 6mN8J'\O Zw[  H D'l@NSƚ cH=|3dF.DA 1q  $IS$dh(t{'zN9+ 0yJ'O*#&BG@Ə,h(Wa@zB$ zbL:O}j $" !CM,J'VyOZ=|&Me˖Mx @FN'': #L  02<;+& _Fp>փ+{@/宻:̰@@Ygd.6)#8a#l@IDATz{߫%K$[H 8XzY L'B)H4FRa߸xu @rlذ!9B*@@!<4. EH@@@@@ ^Jz@@@@4"$      r=    yJ|@@@@Wx@@@@Ƽ c    +@Ci\    c^1_d@@@@H7}{z{315c@Ng%@{{~a|dĀ!ӣ}k|^aȥ$RggJ;qիYBm۶h&HG}_o͛7/iDB@H_Wu5hÆ ƐcH?;P:a ԩSd-\0FL'o=b0cM`ҤIz߯%"~7rLv<;߲%gG\      Q!q    JOY@@@@ C2@@@@?4$'     0DJe     0~h(?eIN@@@@@`4@@@@@`P:~ʒ     h("!    t%9A@@@@! P:D8.C@@@@#@C)Kr    Ctp\    GS@@@@(@C @@@@Ə ,      Q!q    JOY@@@@ C2@@@@?4$'     0DJe     0~h(?eIN@@@@@`4@@@@@`P:~ʒ     h("!    H?Y!' 0:.G'mfF@YCmVM3c@@d4J4 0AԴkr[=ʥt>D]ڷvۛӂF=u_69D@`\hUkoJ'sݭW-Pvyp4X @.uӜtI=t9;ÿ-.sNgOwϏXْ}FU@`La%MNQjzSSUOLe Э++;2͖~mٮefyĉC:yF{nvЪ`_#E~q" W@0HvGv̜)=W6-p$|WG)w+m\eUJ˕=I'ЦٮSuI]47\x:̗hWwaQQgap~#lR^oICKZUYzG#—*;Y e5=jOx}}Si(Ļ-/4&m5-PV@F\g~yvVǫzdr2'U]QĞȣ]A~7Q1R[Yxɓ*7j Hy"9}m$ ghg5ui׫C Z6.mϟ졞jnW}}NA? 5fCF^`Q+ɆzxGFR7bmޱ& -CBAı֥9z#izv#nM0%%[>OGC:h@WgD%Tkż5Q%$t}>Lf0,Cx quRs>vo 4JXﾫӿ>lzz]}>u.:{^3s*-MϺVX~>8Y:v07e(7w8_Góh3?/ۼϵG>Ku\8vT˞w'_٤ԹzB7Ohme~q^1]7t_Pev߽9fvK*(|I[WlWOkSN-[*&}!~s:k:gƔκF^9-tE cL쟟(%un PGk)6[9tu/TQ;L3ZKGU+z޲O:]f-[0t17wt}Z_]Buy"k}W]\=R_uٯ:gVG m>{:N/z{L{Q_-X*sw'6MOc/]ۯU,xێwo>ZWO׎뉒.pc^RMKzw3w4>oA!]mjxIo!ХF:كP\;t꼰zTZCf^+ϜNyY?iGw}VyDkb}q{mf e\zJO׺aeNir|-=mzSLby3D-ҐEY~iitF/{U^:+Sr>r]g "@ƞC{vVufO[^jzvެ?ghϭzHE[(A5/AưtR_mm n_E|?YO~\gA#tܬ՞rgz;r]׻;ry(cKۑoh?=>jW#-[+zg.7'tj+]K8\v)?k ׮g¨unP#JWlw\w!GP}h{}N:6#a&xwC=X.[l޽;K|sV,lݺWVV˩C>*wg$z}+qnV8_gyX͆v/[}?rYE+|E^W`˯Ugy|vpsݱRL\8OQ?3uc: ds҂XaۈCb_II+^_qISlS~H1}ՅQ U*EHgabp(ЀI+.73!RGT-kqLK6Ysj5C;5GSZqBהN =YPBқguk=އte>5W5ԇ:AT_f6ugڪOّv3?WWX?/z7PgM X:{άy?~XZLKCFV=W_uTu;)׋ ⫯dnV͎4E3W05;Ljcޡ7FXWt'BW:֮vlj9h q¦&6[ xp=l x޿myvFnR)UO8h]_}~#&)i"(La X?_mOCZvs576*壶9JG?XW'5FMpk]7፤ x ꊾ^s>vFyZkzO{ig55o;ޮ1uV]eAXXf>QPcmd$CK}^2/}mfʃ(H+Jџ]Hj) 4s)K~hmn$5Oa?HZTVc?vP\ tt&ޘ=@#$] 0n[0/7Y_u=c5K4wf&]Tܦg[hvm߰24|yZ+/zL..)׶=q\_H_T,ӋAEaX<]eP,vQi\Յ 9xjy=|5P7=q,{/6=w7zLe*+) ˛wyJ7g_Mv'Jl۶vzպ=7)LoVSviټLJ.rv!W@0Ô`x \H`D`9y3mgϿgHo:{(|*@<#U_W]¦wցѮ /wMg 9>t1e Ѥݴ3Ȫ7p)E>w⮧=E):) {3y(lڧ/2|`z#23$4l}BWj.W+!pOWXgxY?;{Lrc_AA5Up2.㺧 o#_;RYg(.tޓYCKC!eC'COPF{b 0j\i/T͐W#[EwZcܵM-r{H?^󎽣˘z.WPQ7ߍzd0.>3)3/K &sþ)ԑo+?l1Avd,&3lMæB3av)ۧd_uB?wkﷶ I1]_yO^1Zyw f Ǒ##QfU-j9v nXOVt)G9rLb'꺠Sg2k¦q ѡڃΡf]}.QUsZc{ᗛaahʕP)dmt]9Ǟ՘m~`]2 G_k}'g}CaYkaF05K*ř7 [Ҟ [ͮJ[̃?qk]tywBNt N_`/-k x9Dl j,;tRf>O5#%0_Vi邖hTfej`w𷳏ipwpeZC_IW]俛hz;L֡Ǖ+i(M3$LG7+J\o] eۓ2{;]j;+(W~l@CkoGz᯴nn8©gz0p-gjb {4ӳ7ju\ib ޱB?Їl~kFw>%+_~B UV[_юyhV{(Y!ѯMGP_u]0C׏~?K5>Ҳ_ݧtS$Гljԧ?|3y#oi 3:4fvvg)#W lF}-tl )}f;[V |axJj͹t{N6Sڕ;+[|vsg9iZGx2I#hkT#"r"@,tyv4^%^]kk$'2ܺmȽc%QZ;G~oq kۈDD$"܎ W#O70 ' t(h{~ξ B[/;2÷\A;+:tSBu -*d~ի'2+q6y^̇7_?B_o>Lg~~.nSo7/2/r~Gz^UѶ{}3ޙ<i'KdMvc!pq $@K3t=*S[iuݢ[_]8[g.齹.RզپSmghzg]urGj=שɎ&:f~ٶAK+dשƃFRkm^yf^NWWvA+IÃv8뫰:R3iܹVgrr;@'seϳ_{Z*^=?-߿.4 "lRn?}-noE͎|Un7#c|w`c@J$)π&>,X ڝOչ1o[}  Ny ui)Z\eKg+^+o]4hŝfEo;{B=Y {P@вϮ m5-izsGbVOw ϊSrݟ )":Nc|;*5 {{[M7ͽūo~JyQZNթU>0ݞ@` Lv}߼~q?_z c^i F_-?%[6=~Yi|]c ڸYٳI |usm-s9g 2Ž>YUoܣ=4ʭ騞9gt}8ʢLie+\kzOM{:xPwe;֩) B_gk\7 0\<;4P9 sYw&OŚo¹zJ,Ε}ϏqV[Vk l>7lUoW?lD៟0 Cys}Y`t]%4 ~꾕 c P:Oo+ 8KN\4yL'7Yޏv LN}U j vBjJǵk<{6<'mPR4> | >ҶtCm:N'=Ey*ա{tg-0)_8ݤ:jl}Q [M| ᘭiQ}/7=nf/HѶ{o ckAۛjMf? tBZNʙP>9u2#N; mVаOMCK|A{ۥll&o GiI=o-Y{4.;XC "ӡݟsǎj8hqW;VGmg~޻T^u^;M=QwܪzLdP/+ue'uBo.ӻtl-YQa<ywևtG'~Gqme!:#usz3#j :S϶mNשjh^~њӺwhmPn1tbyI2CW쵝ua=W/t4K~f]fqQa=K6{<i/)P;Ny^P7y\%ݪ}O6f1R6[jB'g1a 0xvWDRӺ֤޺W&^KOtL:gNJ-rU7KF_ZFo|JCe9޴x}Eme-ް<-77,kl{ˮy\x82oku_þk *o=V1t&_X|K=k/%v_p Ɓ=>1_7ƛwwrFcш8#[cwٷHw 3<":*ϭIoAWTy)>վ - ;::'} }M-;,/k<./7uf?uu~1ߑh~*sa6W,跭﬏RFd>_[62܂+#y&eC9vD[%<;G֏U>~$U'z|EC|gނP?FFeoluR{ s[4p{@Fٙ Kr t3c[pG>Zrm"xRvmݬ[K2zW +jy=Y˷T8Qeye_Ly{gցvq$}k*mp.tԹ9Lt^z{ٟ-#/c^\TcGu|S @wğP!PsٓOr ^w6o6\j!OCC/1wJ׫81GoD nTv1[\nX<;j/хa|w4;^m ,JZBU1fDWrpgH' bYoi,Tmsڐx`&ݱ=4)&]>mZ5$Бͷ&vM]wTLzmNf;=gwjOJ*)-H %GH@`\ -D$d[<(Cү^mai;#c9jVMQr3nNUJTLOֺ<ۋspjoH_O޾QDMG4ODGΏ]cƹYuu]ޫk&CR[(i(,PmK,ތMj>RhAY߲~VD[$bXr:[jUVo7tm\֛EƝ΃/R9h7xߐsףa_Nz~O}nKL/*V 靗7PzyUYZ ?_{f8fs޴y,C~Ԭhu]~PN7/;Meյ5Y|@#mwa}ÑjP/3j|_B !yN9&[LV7ouqt-7֛yZ'Pcc}$N%IW TFF:ޠ~ޫ5koOH_W4k,mذ!! w$W=j;ըߚ Njrf-:gz=^*?+yY3I+} [SODӯBs23/ic9gzG|5k23}UuruҦ10;.X\2M3gP PH[鸠3fFuw{,ovpqXqO9Lyyiwh~T}sf?jyӪc064A6p(1-qiv>ԤcZLHtĘsnybL!0]j:A3g^٦Qa%!/+{ۀs۾TRHZoff.[W6:N̜\ N+%]Ygb{HzW)5? ff 3/i+󙝕ZfdfدH3㬯Ms| :o&'De5@&0{!!7n,Yb(W5305AP:̠ [󗬏!qDo qN6XC0W( I)HR J &QB%˴xGVyjoӽot덦y!kΙ-|%hو@ W ':@pp/`c P:|B8ݳZU%ֶf9X/8xP_s93Ra:ךv1XܼYEaa$@"Cq#@C)J2ү@JVoc~N ӣ!u߲  @H*d $^{ěcR $}(2Lb&@K{Ή.B@Q*K4! 0q8eMNb`@@@@4NR'         LDJ'bg@@@@pP`@@@@& 3    8h(up    Q҉X@@@@4:8@@@@@(@CD,u    Jl     Dt":yF@@@@ 6@@@@@`" P:K<#    CR     0h(N@@@@@!@C @@@@4NR'         LDJ'bg@@@@p8@ F3gΨX1^i h}{뮻-!SN֭[.iH@K`׮]*//Ɓ¸?;P:{d2?N 0,%%%*(( yf]~!+ƹw]{gkk>o~:qDp OѲ>Mn! SM@@@H.UVK/ >c[ <_O4I+FUQ?03gTff{7    G?ouocXCC *@Ci|^^"lҥ@@@ӧO>ξ-gE"c'LLJܯڈSx    .`=G[u]ɓ'wX$-o1bʬ=    @l'd,/Vmf: J O)V84&qY[N2şB'M"i 1 X]vՓ[/^ nGiL Sj}9}lAp>LJ2?iICINO~Qq@G>OhѢEǵ 0Nh(M₵)4iW5  c]zYaiJCi$! p r-tD '@CiHxbYv1?iICY[o8ު!q,  H X󔦤n(Ƹ I^Vk$O)C@``?^s/V=gaʂ @`%KTc\$/|PmmmIJ @l) -B@/`Mon\B$/=ǂ xpSj=XCX@@^dMsǂD4 @@`2?Q0   BA`q* /I7%@@_ @!`S:eʔO`@@FQQ'jٻ6;__vb\4]'ŢMJS$Ҥĥ !U}i".Ɋۤw}pE(O:bE,[:(--q 6`nTޞIǶ,yHsf9gfPUڤI꧀(@ P@~ 4sC Pr u]7%BR(@ P->>(@ P +J?K/ܹs ,(@ P(0Q:sK P(}cОvo <,(@ P(0&X P&7 | _Yg)@ P(@`Gi3H$@..\l۠2U|G"9x2 Q^u}.Z Wu'OB`LȲ4MW_}^{-,YfJN B}ݗq@iqu P`Xg0zA 0fώ4^{5#<_vHL9YQd!_w}n5Fgi.vnۃe%˅SG_s|+ew.rF\2(@ P OG=ر?!mn@cɂ s1]V\U,CTͣh|+iFV-Mau"m`SDQ.)?}ڃ+I7z'mg~צܹSݻw=A;U,u9EcqzqL |8Fhd?R$+B@r|mIwe=#okL+- d+Pms!r.0ZvsLB*/҇DۦTa$nH:L^Z$yzq0ɧoZ^NC'̥$#`ڼJ4(G]F{5٧H*-`hR(yt{N@fO}`8¾[m0'H-_^JnXԙ/3Sޓp pNy6]z͗xc(j[{̷Goe; !# \" Im5ㅉt tirW;GyʹITv[-V2!&+>YPz޲n :ܖ3*kt;jqc:58N=Y+@@8M1Eh1CMPFSܒ|"h\6SUMc~7#mz[4k]j=ż_mf2AO^g[ۉ"U>Tj.Gy yaw0L&zG[^7[2܄c! s4vvA8x.ۅ'%X4KmzF8 Ѣ(_90ukS%Qvoea&;1O,qR{?u;فNM3`z6iG=:#VӦ',`foeMgOJP-wܦ>MގNͺ];aTw?l//7coNQ^ ŗtpG|)2~&_hLDxFciLg,gm>nL5~8O0p|+rd&Ř\"sx ^fuz6 cc-R4c2aS'WrPve\(0ȳ꥖B}bSmnq#_k q|Nl*)_G֢0Q=vX㘞2%[ڶv9tіg> P Ncslء^cζe]| &ݴ5v)wh+7.z_ jjv`S<onمxaquRWE8x$7ivqv؉,bh.E3Qa3_jș:7HV3]QaCTcNn9kFֻ#qZ5:[Hc`GiԷUsW%^=+V@^MbM6}Smf6oތ|v\P[, گ#3$g}_Zb_Ljr nIJ4\˖݂j%bX'vVˍF 6sLxU{ U6l#&:U'[[ y-k@k @k#.#v=NӸzr](@ L2S8d#eI QnCWjх٫MEw̋Ƽ7&c_k.[9Xs@ls•8Tw.o a zy7yy Տǡ :SRi7.vׯ6εf9dACS+rF9zy4>Y˒^+̻j7."yY6blV^/s3Y7Y{| eza~WF]I-_(0*qieG.. !;r_| ܾrrzA1x'ЪdQ>"BP154w/$ǰ%çb+f4mFzۈkN/ .p5/d+*jR%q$ybecvٷ?^%Y aOj:$ kţkbyT`DZ2s*`dv$?!g5oCbf,ZӪl n,ĖCX3!`BپCϡ+8M^M+Qrd~v, Ǭy xMٍq(ernD⒤XWΧ5jnʹAwYR|ܭ]97RY%ݾr1S5jG>wWAr'{wh4o9I[e l[bW;Kssxqwǩ7dyu9~~u*xdhڴxHO<-v]Fؗ|NSkش>x 5XwY){ufẻn'UqNՎk?>[LH&q+C8>p=n/]?zȑ۝ζ;tvȫë'_(3j>]]P*uȓqJMF|1ɘYgzqR3oU-oÊGȣFПΝY֤'bJuXUؗo2964l]rP{${/S_+H6 /GAgS?}\$|]jkʮg)@ L@ܨ(GRȞΉXy|/;0Ǿf>z~5r:IP h=tSvF1|Ђ+oɹS(ˉ OyJU}T<'4~,Wp֣IYd׵9u(H?oVݽJC?R:Jz`6W%﬏e+rw"EV4dE.S {r D P`&O8xIk5dDnUY~^ Z'݉ w9{21 ,>ԷeVaHD=ؤq;vWm7bF LD{s]y64m_0i~* M =|uŐI~)j3]2 =oc1K#z.;Ion|@^3wћn#ȇ!U h+WoXdO;nXons&D`=YN:|yb,:f1$;W]:g2yA𢡄QTU46?V \rly{3E/xoXOMh_F :4RmzHtM K~S^4{% u J/[r.ٝ oBX7V6&%5Y Pv,h[k%4E`WVi3Uwl]֠TL4˻N][d<~Sult̸sHl*g@ba cK~Z=*:Eh |rU+MlT}߼D^ilZT T/Iª5Ss`.g#oȎe9zȫL3:{|)q5r6SRqk!!rzrO Uq%Jv)z)3 rsi˞"|}e^m*-+}-k\:o3jU峒>sW̫dL]͇FV,Sr$g[fjfl4:I햤>z!HNbs"کlӿik˹Rn{ QWD΢rTVYHSh_fz̋PK8x.7v_-?is E|y^Ś9MX}{vsƴcbdPOq{:K<7LpnCHStʻvxl֋,]*,qq~N33[>N3ǾPҺԞ~KRKǞ]LvrK;YlmY-ZW m3z5JoůuI9{0ԎgcbW-6JM aǣO5E5ط}e,?8v𑫡WOk5~?ULqVG^b N3ᙰU-JGi&G[q0q129 P9E8x.weۆv|U߃ _T?o 1͞fL}x/<{B,܃F_?Şґ벣tuԯ_m-ѫGG_Ol|Q3cg0rͶa6ķ [@>,o P(W{'C=4yj؄)\Fu%wl|Szk ON7cp4}O4V4Ύ E[ky pBޜey_`|8낑Y]@FN{"_!Y-jYuM"Fk[@D !:'!-W}jht 1%bGF@KO͡k˺jqiXvv)ݛ1ymR|*NF+{:0${vlM^5" c+me?[aٿZ!chPn'-p@,꜖ ]aKm2w5zh$ ujS uPW@gaMѧ%1_mzAS &}˟p\]Z)EE_eʃ#,Pt zEG9D Ԛ/-o]S[7W} tDma)#dMc=7c^;6h:DȿI{l$(ԶsV,Ȳ]UW*JŒ..)-?&T _NKe;U뮆]ޣ^^FkI0 ;R6:jc)=1YHymnt5ReOO<<(҄ 49Ro%EE]BGpD{l%)|_ƒx<ܑD9nn@18*'j,M:Цtk-)s22FlNhdG.*,|b*πe'z{M}qR՝U|W;|)'k2:CfgL 휲}d)vHL3Qξ]M<&&k4} RŴ@ĭM$'}}mH))V^+S:4zq:GH v68_| Ig#dy^_l52[[kh,ewCdT9vm" ŷn,fwmg8yy{%ڭ<޼Ɋ/|% kYG' rT5w:C^7/]Q˷Q߁Ez\A}[*h(>RԶ<>'ll!d4g[cGVyicd^nb:4x3442(C2JoP'!_Ry |YPFSjb{K{|d驎 >m/؟Y(@ E8x˺]M<&&"k1D%LǡT1m11a2ٱkg݇//WGzXLҮMܪC5ӯO` >ƗyX 0܊|ojdֿ:> X:|c=cK.f]MIn}7ȧ )ڀc!zZݒbr[ *gҜʕ+Z. slQ]'o'm-ELM(^8-cCaaKwfm 1X+_ܩģh,7=&%$Z<)veG%?ҍD6DgS, T^9M-IG?6W]lӛ %o[wȋ_:2)2;|zpU|AؼYsCErH*XSn7y';rX+J|?8|2&*K~ߚh昨y&Jo;.2˃vq|>b!!O*]A RĶwUhHRpچ> Guqf(0T4/2DgK]!R1'󌃙 d˜G>wCYYt8prN|{Wz3K䞋g\˯l㚥v֯ "cƬYt+$H+wm(KP^ CPX$.+$5w̛?߉Ҏ+Rq\`׮]7ood4RNOfM C! ,i02xQT濸xf]z)S"W!yEa=#Hs(79P?u{F:ҙs1g<6'KQG`?zRN,R-G9'Ud DJyR~ԓŴacb/Nts:S){{ ! Ds`Q(b|Nyn1J#i&lJ\.S*]._YU-roNU|7UXn P9(ByJmFd,XT\l"._$eNU&3^EM2+N}&sS+0YlJ1lw[6OvO%XTa%&LQ6[($So(f(@ P(@ Pgva(@ P(@ P(@q`G0s'(@ P(@ P@> 4F P(@ P(@ ;JDž;(@ P(@ PY|t7 P(@ P(@ P`\Q:. (@ P(@ P((üQ(@ P(@ P"qaN(@ P(@ P(@|`Gi>(@ P(@ Pv 3wB P(@ P(@ ;J0o(@ P(@ Pt\ P(@ P(@ P QGy(@ P(@ PE̝P(@ P(@ P,|>:(@ P(@ P(0.(f(@ P(@ Pgva(@ P(@ P(@q`G0s'(@ P(@ P@> 4F P(@ P(@ ;JDž;(@ P(@ PY|t7 P(@ P(@ P`\Q:. (@ P(@ P((üQ(@ P(@ P"P4.{)a{V*C@q&Vqpbw P`t3ΉkQ`,XgK]n 0]vIu]/~ke P`,Ν;.m P`ap(W3`f Sy%8`GinBS Cq0#KA P[MMMBh"/kQ^^"fXguV 2=(@ P(@ P`o?}(P(-[ .g\vex1G(@Ü 8(@ P(0E֮]$z:Ky;sHr+zrk(@ P(@1#W&ɬY`ۓ(@ P`vķ)@ P(@ P$0|hMړ1J9Q@(Mߌ)(@ P(@ P*pM7%ҥKuJ_(@(MI7(@ P(@ P)p7Cur-֗L P@ VVV𨀋ϢQȩ@^uj%kPP(@ P` h "R as 7X_2(@ P,SOʓ|Y4 P` _JJJ֬Y_(@ LE뮻uI{mŊ֗L P@ hw^'-c̢Q'w)'n3D P"W~#Iꪫ8>i _(@ ?akʻ3 ,(@ ]GiqJ9>in)?(@U:N)'U}D P(@ P ](SI=\ ]:N)'-#Q(@ Pc-qJ9>X} PSr|xg P(@ P 2 (@ 䋀66}C-ܒ/b>(@ P(@ LJ($qJ9>\1(087p8쑻(@ P(PyQ]s`ڵϒQ)X"-1)(@ P(@ +6N__s\f(@ L_ Q\\ G0T+v%_b)(0 ?rRc-0c lذc SY |;z&ΓH1(s!*(ͯP(@ P(@ P @.)@ P(@ P(@`Gi~(@ P(@ PvN:wI P(@ P(@ ;Jx07(@ P(@ PtйK P(@ P(@ P Q_ǃ(@ P(@ P&@]R(@ P(@ P%: (@ P(@ P(0(t(@ P(@ P/v`n(@ P(@ P(@ `Gs(@ P(@ P@~ 4sC P(@ P(@ L;J'(@ P(@ PKu< P(@ P(@ P`Q:%(@ P(@ P(_(ͯP(@ P(@ P @.)@ P(@ P(@`Gi~(@ P(@ PvN:wI P(@ P(@ ;Jx07(@ P(@ PtйK P(@ P(@ P Q_ǃ(@ P(@ P&@]R(@ P(@ P%: (@ P(@ P(0(t(@ P(@ P/sOg{1)%3(@ H`Zgh (@ Pd`Gdv}Usn<عm>"mp8?6g7W)kh voNx#}7)?*xnn4T&sJy]+OG5 x;w.][+BH2Fj*(@ P`r qjܚ{ u/YOBc? QIƴo|[oK*>[{bYOoˠrrKdƑ{v !j]ywT"g_wwQ&}sǃͨTb8\.ڿ?=ǷbsYwFH~6FsjǺ)@ L@!ӏY!>kT{\_c7QYIѶӛmKiݑڑw5(_BNOi_LbukC2Xok8&Öe fqFyb4a3g6rXwкW.O%=/_Ԍ4/iIi٘-h44ufZ޴A@$Nܖfی9x}0PW/]&mo5c%flb ?W(@ P /Jm~ːb[V:+b%l$Q۞4jtb`;6YWmو9A,jof4x\HRH\tRo}#ld*:#@غ<0 (@ Fqm_GzT؝8+܀BI*dYOڬ P`|rt{n|8R'6YZ,{~،<Dko8-CO rm~ zJ*ifGKټ -?*C8}ޢn@_:{_gkދ*f_ws^|v+Yu3w@ANj5w`ebh^y۠\n'*ο+v߆*Fۏx!*^.'{O/p9̽l%,elcM+^k(*Y!HqnoNʼnW T+à|h6[9t'^=Wega駮S;`[}eS/(@(:8n QSOx*zY!b}N ߩf\ua4۰e%rtxסFeb7?7BI#:{}<,= ;j ܿ.^e {ƄWݵp߱3}84~rU47߿s^3 | Uk\ASh~?W¶`-?v hs*qwbXΜ=}qDDŽq{~ļj'^~{msۥ׭$4='wPJRey9d±'U;M&;;(ŠEzHa'x]B\y <2W6JYo>_|( \ˑm;-<g`;ljt,'q;T>.5Įuw'>#6jt8qͿl)R9eObڛIxoVߋXs{i LC+Q~h'Gj}"eH(ӊ?@ֱ6y*_@|6w.q%IDATM/bDESO"ݾ{=yk.r{W[Jŗ[DOmw5VD}z#Vi۷jmxz-~~e-]/߯ XnT6/E(3hK2$p(ɮ6# p`|BSL} b+zmS~&ZaOnuM2@.ʮddrs 0+o%VGkO2lMS@@8Mq.=M [cW({$#P>cXeǔ8XgKnu4 5j|"h%mtF^=~p=٦ ZZ:MAKed}%RMu^ᩮ.KjzGx<^Ѩ5O:d0C%[ĭіWGuj;=#ywz{k!#^l"G:!U|F AcUVδl=BީS-oz{WVi|cSn5e/gXEt[}=c䨍tfKvi8BL6Fm phHlFKS ;CZxᏏ3#|#U!Qtfj㹩cY?@6sfCQ4Hd%Zo7Ωkp0GԹ-7v\"mڒXGvX1FK~p|1ʭL歏|ξ]'xJQkIfL>i7_3hkmЧS>ֿWRNZoϢ}-D:<lK }Fՙ,qdJ^he޳k 9{ L8`n߮]4jѼ؁]U˥q2֤-7#Y6=m2=r c !o翱 U7onYKźz[۰ڶ`W6{ǂ[ƣmU[fmmceB| 79e45::nOK]雐W\S oZT;O / R'>yq[ܨn@.aΜ j/8w܆M^y=T[!y-cԹ} h hmץqHseW% PSA,^{1Б=~|r}l#qG|\رq5)Wxtm[O9UI(+bd2M~lqƙwM/J~vJo9āAXeN&?ަnD.9+"N~u>mJ;|8[޺'MLkSM/oNxv7Zc7!Ԩ6sab]Zd}U+ߵxR,$v6nrW'OJr,q/lzR݁[sR- P`i_"VgܾfP{;#G㩽঵@ۯ5mjΆ. B5z !lZ*.iI]t|إ&y)gv]q 䭀֥yhvtW:ָrnS,5Yn7?ŴE=m6Մ` ɫ/LW}xY>QԤsWZψi%\2\9[eukOz_W+|Z(oO5rZ!/7^Y3yسJW&e:cb| :c{[.uS#7ؿKZ?@0sxrEiS;gOĻEXd3Jc31# ]"z+o7+Vcۆfa]mY Vؓa\~#7:~prz"{@Uv%g\(09XZm;Dof:Vt~iדىօp~fS|زv >h>)qu#F4x';EX$؟Ν$ƌzG[ZGqwwĶS DCG;uyU=ٱ1q˕uNu,'.>}_+{~]HޑslO?]Ae|EMg=jd׵9=rF.êbPPp]!d%JG\g$w-RXlջBw.[`)'UaN`~Ȭ}buGflcukyk݇_l"8mԲ+kD*Yrqdnk1\;VtoԓgwlbmbR @No `':i3N>8uf45vЋ_jc摷s;b:w|p;͗Wv'-x0Իx䍞F2?s/ҥ1|On"K2Gu>$M$;_F8' ܦl{jg?l:e+n?g)@ LRs;)´sHn)(W$geli]ٲ'mq߿j4:`ۜ?e^'I^]IYǏ4K.3BV"% X\ёan+G?~"L\7dx[%Rm55昽ڲu K^q\8τCtyPn@X=q}>,{t\>bSPuӴ $V(02i_˨0vZXaZգo_0_W>TQKlxH&z v.l\kCk(ߦ&LUtjiCeE77^//$̕sD[bPCtu*3p˱.=jmlJۊu8xz]@B\+8rn[Tiڧ6;WFy;8ʋ,;=4?~ }qjc)ejTYRq+î]?guJRW6`*=뷨1W9x/~Z5 ݋JKf˖+OZlH}7JO:L6帣Ŗ6Sl14GIա: N ȓv p.Ŧgȸat20U踩c\ne0Vg޾X=\U0>(ryzqbOfeA D6z=6^U߁hZOe;-ƚY(yeG~bgyv[ʥ^/c>UeGc8 \ʲmݺO.S(Lk||-%yrLP6 GS/J\ؿ69t-º͏oŘZ)n9xwM+&~[ch~->j.5nPk""rʳ~Bм[x/a"kP'qLg;fe`ڶO3Of4ɇ`P?{s+U AsƭJ8fϚk۾2/efǎ>r5tkz}8ڇdwϟ{?Eܻ&+JAng3aZ𮑶X|' hk渍TW(0Erվ~Φ}X.Ӿk<o6ݶ⻸E<gEu4:A 2tu.?ݱGvoJ!; ىR{ocb̜TF\o0<3X;V.N@V5:EpW>h) qcv5UNM>BKlYg (3"E{K>K D6x@}uE[U}hܞIDkU>Sl`epm-~!nɗOwFAm?^e]- _U;2mFcd.\- zmc“uu{3f¢ѭ#z²lz!/2xe7r3QsNT޹_ P`(aZ/:CwKʘPgcWZ\ $Ē.Q)Z"cubM._OHO.Klyb`$nhkCu8eyRSujS̋;/îd]J lm~\,Mp?>Q[{]9udaر픺|脥ޑW.&JUa|4ߞH}G,Q>"a<~2&!ҎM+Z6H{Y{ O*O lMY}=)XeZ~Bٶ`BwMBqQ ڂ2砍*4,oBoS []juT=>d%أ>\qGdzC]Zb5"(XkTN;LscJZnB^[w$~BX]׃TTk]Gm[ h>]jRiuZHSI/_}0VkOKdMQN6eGivkmx& BEk&>uNhQIhFʜ[&kUoAe7e}fNXιc P`,ƪ㡣܉ew]lH۵:d]hKs=$Tct + ۳yF@3eψ#V/qId~Ol˼NyW}6#Ԕ$Zf:NNҁO22lvQOmJM;qa b XHiie'*S8nrׁ;h'S%ñ㟱Dz2OS[`\cѾ-X}ZdU kMxeU2XOnQMM~y2t/M'#߰a>I-WDszu$5ek'b\c\n>r0 (O:oz?:SکRTUܹ\yż|fٵvY.m ].4xm;D^vώ8PI^/x<` +eQ'_5~_(PtiP3r:p_!lz"_=رm5ZgB];CFcom<*aam" ŷno UlkaeSE-S~TeWnC'1@OSɜs*)2[ݸ=aْ[0Mj)Sjb{K{|dᔟ8}Z3GOlJY P`2 EZ:m_#X=L+M5.ZxȪ|lڵlcw헡>WT}T}h%צ]o}jƱ6aK|L@;GO4Xn/ L]4txow-v;z_}# kf͆Zˮza)W#36z^jJ8ۤ+;mN-J2\DOk,$gh櫕R_QdN%")fks:y{lˮaNPƹ[ P`L P>kCNcB!ÔX/Vi cmy׈2]4w-sry+qI^syD_ߌ6O6u)l ѥ1V"R7teFcu{ &l:62D{qt=LtOn ؐ07mPlU(4Дnlӛ?'͟&7)ēIr{.Ͼ !M~g?n7rҝ]$5{!kB\/6p}+>G:y @\2Uo֏({ԭtld<-D\zF~X\: zKnD\e~#Caezӽiͧ%}VKg } ZW[*Ύ@@m_z%.;W/SO\u'}9Ffysx-8y󬙧z3zcGm%zh(ܔk\|sDzY'Nh9W>P\ݡEn#S5ΠOJ>Y]wHw\dDW_ѡ܍9~@<:!տD}tHvojK?zSQIp K0 MΈϺɴ.liPPשAw{/.ׯ_k:0^ZzV)Z ~VtQ5;c;sSV~K6)ԄL߾$oo}^"#՝I_"/Cv,J]B;:`yF5kd 8۬vYalRwf$rG[cr[lZufȷk80ؾqqy8}~-(=JIswRbuU1b V/Z)mJK.y@ܤ}&cLLco"icEIS-+V[-[[CWsCJ^"jq0Sr2$ν]B Cm- KC$t˿O}՗)æ^K9qnئ%hKMؕ]@j'OJ6~Z9hħu]c_ABB~Û;J)R?sm_cHvN,(bEӶ2 p2׌wTJF ^- w[T8.8Kz ⠶)y:ϙ?i(Ҩ[c>[eT 8(P:+>jh&]U$]/;Iw' f: -0{4meq oFd,TՎ9(em!$# PguVj"@.4xn<Z//AkFiDwtIkM/o,&`D蕃lSa>[  PXOt@KbjSvO;tmm䷟ʀ ݰn={lvPϧ"  E VMņ @ZAÅ-H_Γ^ߚt %.g++vd @ ؃BDߒ$M3K~IH\%ۯd^ֿ=Zmc @ V}S@4HE |/1 ;|4,sJרAR  P@ R&5HV[*e/ 6y  @muGpTm$8_,E@ eV&?l.g  _:  @~IE@@@@#@;uMI@@@@@ @C2    xG@wꚒ"    A@d@@@@R5%E@@@@R      ީkJ    @@@@@;JSה@@@@ J 0$#    wz))    `HF@@@@(N]SR@@@@0(5     Pꝺ     ` Pj!@@@@#@;uMI@@@@@ @C2    xG@wꚒ"    AJonn'O6!-011!> G ܺuK=*---.9E XW+W2k2vbSf' 0vvRmg^V$a255UT@GVZ傜E\vV< @U숀;k= 0vZuNҁRd     (CvzIENDB`DBI/vignettes/DBI-advanced.Rmd0000644000176200001440000002647114627140067015506 0ustar liggesusers--- title: "Advanced DBI Usage" author: "James Wondrasek, Kirill Müller" date: "17/03/2020" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Advanced DBI Usage} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} library(knitr) opts_chunk$set( echo = TRUE, error = Sys.getenv("IN_PKGDOWN") != "true" || (getRversion() < "3.5") ) knit_print.data.frame <- function(x, ...) { print(head(x, 3)) if (nrow(x) > 3) { cat("Showing 3 out of", nrow(x), "rows.\n") } invisible(x) } registerS3method("knit_print", "data.frame", "knit_print.data.frame") ``` ## Who this tutorial is for This tutorial is for you if you need to use a richer set of SQL features such as data manipulation queries, parameterized queries and queries performed using SQL's transaction features. See `vignette("DBI", package = "DBI")` for a more basic tutorial covering connecting to DBMS and executing simple queries. ## How to run more complex queries using DBI `dbGetQuery()` works by calling a number of functions behind the scenes. If you need more control you can manually build your own query, retrieve results at your selected rate, and release the resources involved by calling the same functions. These functions are: - `dbSendQuery()` sends the SQL query to the DBMS and returns a `result` object. The query is limited to `SELECT` statements. If you want to send other statements, such as `INSERT`, `UPDATE`, `DELETE`, etc, use `dbSendStatement()`. - `dbFetch()` is called with the `result` object returned by `dbSendQuery()`. It also accepts an argument specifying the number of rows to be returned, e.g. `n = 200`. If you want to fetch all the rows, use `n = -1`. - `dbClearResult()` is called when you have finished retrieving data. It releases the resources associated with the `result` object. ```{r} library(DBI) con <- dbConnect( RMariaDB::MariaDB(), host = "db.relational-data.org", port = 3306, username = "guest", password = "relational", dbname = "sakila" ) res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = 'G'") df <- dbFetch(res, n = 3) dbClearResult(res) head(df, 3) ``` ## How to read part of a table from a database If your dataset is large you may want to fetch a limited number of rows at a time. As demonstrated below, this can be accomplished by using a while loop where the function `dbHasCompleted()` is used to check for ongoing rows, and `dbFetch()` is used with the `n = X` argument, specifying how many rows to return on each iteration. Again, we call `dbClearResult()` at the end to release resources. ```{r} res <- dbSendQuery(con, "SELECT * FROM film") while (!dbHasCompleted(res)) { chunk <- dbFetch(res, n = 300) print(nrow(chunk)) } dbClearResult(res) ``` ## How to use parameters (safely) in SQL queries `dbSendQuery()` can be used with parameterized SQL queries. DBI supports two ways to avoid SQL injection attacks from user-supplied parameters: quoting and parameterized queries. ### Quoting Quoting of parameter values is performed using the function `dbQuoteLiteral()`, which supports many R data types, including date and time.[^quote-string] [^quote-string]: An older method, `dbQuoteString()`, was used to quote string values only. The `dbQuoteLiteral()` method forwards to `dbQuoteString()` for character vectors. Users do not need to distinguish between these two cases. In cases where users may be supplying table or column names to use in the query for data retrieval, those names or identifiers must also be escaped. As there may be DBMS-specific rules for escaping these identifiers, DBI provides the function `dbQuoteIdentifier()` to generate a safe string representation. ```{r quote} safe_id <- dbQuoteIdentifier(con, "rating") safe_param <- dbQuoteLiteral(con, "G") query <- paste0("SELECT title, ", safe_id, " FROM film WHERE ", safe_id, " = ", safe_param) query res <- dbSendQuery(con, query) dbFetch(res) dbClearResult(res) ``` The same result can be had by using `glue::glue_sql()`. It performs the same safe quoting on any variable or R statement appearing between braces within the query string. ```{r} id <- "rating" param <- "G" query <- glue::glue_sql("SELECT title, {`id`} FROM film WHERE {`id`} = {param}", .con = con) df <- dbGetQuery(con, query) head(df, 3) ``` ### Parameterized queries Rather than performing the parameter substitution ourselves, we can push it to the DBMS by including placeholders in the query. Different DBMS use different placeholder schemes, DBI passes through the SQL expression unchanged. MariaDB uses a question mark (?) as placeholder and expects an unnamed list of parameter values. Other DBMS may use named parameters. We recommend consulting the documentation for the DBMS you are using. As an example, a web search for "mariadb parameterized queries" leads to the documentation for the [`PREPARE` statement](https://mariadb.com/kb/en/prepare-statement/) which mentions: > Within the statement, "?" characters can be used as parameter markers to indicate where data values are to be bound to the query later when you execute it. Currently there is no list of which placeholder scheme a particular DBMS supports. Placeholders only work for literal values. Other parts of the query, e.g. table or column identifiers, still need to be quoted with `dbQuoteIdentifier()`. For a single set of parameters, the `params` argument to `dbSendQuery()` or `dbGetQuery()` can be used. It takes a list and its members are substituted in order for the placeholders within the query. ```{r params} params <- list("G") safe_id <- dbQuoteIdentifier(con, "rating") query <- paste0("SELECT * FROM film WHERE ", safe_id, " = ?") query res <- dbSendQuery(con, query, params = params) dbFetch(res, n = 3) dbClearResult(res) ``` Below is an example query using multiple placeholders with the MariaDB driver. The placeholders are supplied as a list of values ordered to match the position of the placeholders in the query. ```{r multi-param} q_params <- list("G", 90) query <- "SELECT title, rating, length FROM film WHERE rating = ? AND length >= ?" res <- dbSendQuery(con, query, params = q_params) dbFetch(res, n = 3) dbClearResult(res) ``` When you wish to perform the same query with different sets of parameter values, `dbBind()` is used. There are two ways to use `dbBind()`. Firstly, it can be used multiple times with same query. ```{r dbbind} res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = ?") dbBind(res, list("G")) dbFetch(res, n = 3) dbBind(res, list("PG")) dbFetch(res, n = 3) dbClearResult(res) ``` Secondly, `dbBind()` can be used to execute the same statement with multiple values at once. ```{r bind_quotestring} res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = ?") dbBind(res, list(c("G", "PG"))) dbFetch(res, n = 3) dbClearResult(res) ``` Use a list of vectors if your query has multiple parameters: ```{r bind-multi-param} q_params <- list(c("G", "PG"), c(90, 120)) query <- "SELECT title, rating, length FROM film WHERE rating = ? AND length >= ?" res <- dbSendQuery(con, query, params = q_params) dbFetch(res, n = 3) dbClearResult(res) ``` Always disconnect from the database when done. ```{r disconnect} dbDisconnect(con) ``` ## SQL data manipulation - UPDATE, DELETE and friends For SQL queries that affect the underlying database, such as UPDATE, DELETE, INSERT INTO, and DROP TABLE, DBI provides two functions. `dbExecute()` passes the SQL statement to the DBMS for execution and returns the number of rows affected. `dbSendStatement()` performs in the same manner, but returns a result object. Call `dbGetRowsAffected()` with the result object to get the count of the affected rows. You then need to call `dbClearResult()` with the result object afterwards to release resources. In actuality, `dbExecute()` is a convenience function that calls `dbSendStatement()`, `dbGetRowsAffected()`, and `dbClearResult()`. You can use these functions if you need more control over the query process. The subsequent examples use an in-memory SQL database provided by `RSQLite::SQLite()`, because the remote database used in above examples does not allow writing. ```{r} library(DBI) con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cars", head(cars, 3)) dbExecute( con, "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)" ) rs <- dbSendStatement( con, "INSERT INTO cars (speed, dist) VALUES (4, 4), (5, 5), (6, 6)" ) dbGetRowsAffected(rs) dbClearResult(rs) dbReadTable(con, "cars") ``` Do not forget to disconnect from the database at the end. ```{r} dbDisconnect(con) ``` ## SQL transactions with DBI DBI allows you to group multiple queries into a single atomic transaction. Transactions are initiated with `dbBegin()` and either made persistent with `dbCommit()` or undone with `dbRollback()`. The example below updates two tables and ensures that either both tables are updated, or no changes are persisted to the database and an error is thrown. ```{r} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cash", data.frame(amount = 100)) dbWriteTable(con, "account", data.frame(amount = 2000)) withdraw <- function(amount) { # All operations must be carried out as logical unit: dbExecute(con, "UPDATE cash SET amount = amount + ?", list(amount)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(amount)) } withdraw_transacted <- function(amount) { # Ensure atomicity dbBegin(con) # Perform operation withdraw(amount) # Persist results dbCommit(con) } withdraw_transacted(300) ``` After withdrawing 300 credits, the cash is increased and the account is decreased by this amount. The transaction ensures that either both operations succeed, or no change occurs. ```{r} dbReadTable(con, "cash") dbReadTable(con, "account") ``` We can roll back changes manually if necessary. Do not forget to call `dbRollback()` in case of error, otherwise the transaction remains open indefinitely. ```{r} withdraw_if_funds <- function(amount) { dbBegin(con) withdraw(amount) # Rolling back after detecting negative value on account: if (dbReadTable(con, "account")$amount >= 0) { dbCommit(con) TRUE } else { message("Insufficient funds") dbRollback(con) FALSE } } withdraw_if_funds(5000) dbReadTable(con, "cash") dbReadTable(con, "account") ``` `dbWithTransaction()` simplifies using transactions. Pass it a connection and the code you want to run as a transaction. It will execute the code and call `dbCommit()` on success and call `dbRollback()` if an error is thrown. ```{r error = TRUE} withdraw_safely <- function(amount) { dbWithTransaction(con, { withdraw(amount) if (dbReadTable(con, "account")$amount < 0) { stop("Error: insufficient funds", call. = FALSE) } }) } withdraw_safely(5000) dbReadTable(con, "cash") dbReadTable(con, "account") ``` As usual, do not forget to disconnect from the database when done. ```{r} dbDisconnect(con) ``` ## Conclusion That concludes the major features of DBI. For more details on the library functions covered in this tutorial and the `vignette("DBI", package = "DBI")` introductory tutorial see the DBI specification at `vignette("spec", package = "DBI")`. If you are after a data manipulation library that works at a higher level of abstraction, check out [dplyr](https://dplyr.tidyverse.org). It is a grammar of data manipulation that can work with local dataframes and remote databases and uses DBI under the hood. DBI/vignettes/spec.md0000644000176200001440000031353314627140170014146 0ustar liggesusers## DBI: R Database Interface DBI defines an interface for communication between R and relational database management systems. All classes in this package are virtual and need to be extended by the various R/DBMS implementations (so-called *DBI backends*). ### Definition A DBI backend is an R package which imports the DBI and methods packages. For better or worse, the names of many existing backends start with ‘R’, e.g., RSQLite, RMySQL, RSQLServer; it is up to the backend author to adopt this convention or not. ### DBI classes and methods A backend defines three classes, which are subclasses of DBIDriver, DBIConnection, and DBIResult. The backend provides implementation for all methods of these base classes that are defined but not implemented by DBI. All methods defined in DBI are reexported (so that the package can be used without having to attach DBI), and have an ellipsis `...` in their formals for extensibility. ### Construction of the DBIDriver object The backend must support creation of an instance of its DBIDriver subclass with a constructor function. By default, its name is the package name without the leading ‘R’ (if it exists), e.g., `SQLite` for the RSQLite package. However, backend authors may choose a different name. The constructor must be exported, and it must be a function that is callable without arguments. DBI recommends to define a constructor with an empty argument list. ### Examples ``` r RSQLite::SQLite() ``` ## Determine the SQL data type of an object This section describes the behavior of the following method: ``` r dbDataType(dbObj, obj, ...) ``` ### Description Returns an SQL string that describes the SQL data type to be used for an object. The default implementation of this generic determines the SQL type of an R object according to the SQL 92 specification, which may serve as a starting point for driver implementations. DBI also provides an implementation for data.frame which will return a character vector giving the type for each column in the dataframe. ### Arguments | | | |---------|-----------------------------------------------------| | `dbObj` | A object inheriting from DBIDriver or DBIConnection | | `obj` | An R object whose SQL type we want to determine. | | `...` | Other arguments passed on to methods. | ### Details The data types supported by databases are different than the data types in R, but the mapping between the primitive types is straightforward: - Any of the many fixed and varying length character types are mapped to character vectors - Fixed-precision (non-IEEE) numbers are mapped into either numeric or integer vectors. Notice that many DBMS do not follow IEEE arithmetic, so there are potential problems with under/overflows and loss of precision. ### Value `dbDataType()` returns the SQL type that corresponds to the `obj` argument as a non-empty character string. For data frames, a character vector with one element per column is returned. ### Failure modes An error is raised for invalid values for the `obj` argument such as a `NULL` value. ### Specification The backend can override the `dbDataType()` generic for its driver class. This generic expects an arbitrary object as second argument. To query the values returned by the default implementation, run `example(dbDataType, package = "DBI")`. If the backend needs to override this generic, it must accept all basic R data types as its second argument, namely logical, integer, numeric, character, dates (see Dates), date-time (see DateTimeClasses), and difftime. If the database supports blobs, this method also must accept lists of raw vectors, and blob::blob objects. As-is objects (i.e., wrapped by `I()`) must be supported and return the same results as their unwrapped counterparts. The SQL data type for factor and ordered is the same as for character. The behavior for other object types is not specified. All data types returned by `dbDataType()` are usable in an SQL statement of the form `"CREATE TABLE test (a ...)"`. ### Examples ``` r dbDataType(ANSI(), 1:5) dbDataType(ANSI(), 1) dbDataType(ANSI(), TRUE) dbDataType(ANSI(), Sys.Date()) dbDataType(ANSI(), Sys.time()) dbDataType(ANSI(), Sys.time() - as.POSIXct(Sys.Date())) dbDataType(ANSI(), c("x", "abc")) dbDataType(ANSI(), list(raw(10), raw(20))) dbDataType(ANSI(), I(3)) dbDataType(ANSI(), iris) con <- dbConnect(RSQLite::SQLite(), ":memory:") dbDataType(con, 1:5) dbDataType(con, 1) dbDataType(con, TRUE) dbDataType(con, Sys.Date()) dbDataType(con, Sys.time()) dbDataType(con, Sys.time() - as.POSIXct(Sys.Date())) dbDataType(con, c("x", "abc")) dbDataType(con, list(raw(10), raw(20))) dbDataType(con, I(3)) dbDataType(con, iris) dbDisconnect(con) ``` ## Create a connection to a DBMS This section describes the behavior of the following method: ``` r dbConnect(drv, ...) ``` ### Description Connect to a DBMS going through the appropriate authentication procedure. Some implementations may allow you to have multiple connections open, so you may invoke this function repeatedly assigning its output to different objects. The authentication mechanism is left unspecified, so check the documentation of individual drivers for details. Use `dbCanConnect()` to check if a connection can be established. ### Arguments | | | |-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `drv` | an object that inherits from DBIDriver, or an existing DBIConnection object (in order to clone an existing connection). | | `...` | authentication arguments needed by the DBMS instance; these typically include `user`, `password`, `host`, `port`, `dbname`, etc. For details see the appropriate `DBIDriver`. | ### Value `dbConnect()` returns an S4 object that inherits from DBIConnection. This object is used to communicate with the database engine. A `format()` method is defined for the connection object. It returns a string that consists of a single line of text. ### Specification DBI recommends using the following argument names for authentication parameters, with `NULL` default: - `user` for the user name (default: current user) - `password` for the password - `host` for the host name (default: local connection) - `port` for the port number (default: local connection) - `dbname` for the name of the database on the host, or the database file name The defaults should provide reasonable behavior, in particular a local connection for `host = NULL`. For some DBMS (e.g., PostgreSQL), this is different to a TCP/IP connection to `localhost`. In addition, DBI supports the `bigint` argument that governs how 64-bit integer data is returned. The following values are supported: - `"integer"`: always return as `integer`, silently overflow - `"numeric"`: always return as `numeric`, silently round - `"character"`: always return the decimal representation as `character` - `"integer64"`: return as a data type that can be coerced using `as.integer()` (with warning on overflow), `as.numeric()` and `as.character()` ### Examples ``` r # SQLite only needs a path to the database. (Here, ":memory:" is a special # path that creates an in-memory database.) Other database drivers # will require more details (like user, password, host, port, etc.) con <- dbConnect(RSQLite::SQLite(), ":memory:") con dbListTables(con) dbDisconnect(con) # Bad, for subtle reasons: # This code fails when RSQLite isn't loaded yet, # because dbConnect() doesn't know yet about RSQLite. dbListTables(con <- dbConnect(RSQLite::SQLite(), ":memory:")) ``` ## Disconnect (close) a connection This section describes the behavior of the following method: ``` r dbDisconnect(conn, ...) ``` ### Description This closes the connection, discards all pending work, and frees resources (e.g., memory, sockets). ### Arguments | | | |--------|-------------------------------------------------------| | `conn` | A DBIConnection object, as returned by `dbConnect()`. | | `...` | Other parameters passed on to methods. | ### Value `dbDisconnect()` returns `TRUE`, invisibly. ### Failure modes A warning is issued on garbage collection when a connection has been released without calling `dbDisconnect()`, but this cannot be tested automatically. At least one warning is issued immediately when calling `dbDisconnect()` on an already disconnected or invalid connection. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbDisconnect(con) ``` ## Execute a query on a given database connection This section describes the behavior of the following method: ``` r dbSendQuery(conn, statement, ...) ``` ### Description The `dbSendQuery()` method only submits and synchronously executes the SQL query to the database engine. It does *not* extract any records — for that you need to use the `dbFetch()` method, and then you must call `dbClearResult()` when you finish fetching the records you need. For interactive use, you should almost always prefer `dbGetQuery()`. Use `dbSendQueryArrow()` or `dbGetQueryArrow()` instead to retrieve the results as an Arrow object. ### Arguments | | | |-------------|-------------------------------------------------------| | `conn` | A DBIConnection object, as returned by `dbConnect()`. | | `statement` | a character string containing SQL. | | `...` | Other parameters passed on to methods. | ### Additional arguments The following arguments are not part of the `dbSendQuery()` generic (to improve compatibility across backends) but are part of the DBI specification: - `params` (default: `NULL`) - `immediate` (default: `NULL`) They must be provided as named arguments. See the "Specification" sections for details on their usage. ### Specification No warnings occur under normal conditions. When done, the DBIResult object must be cleared with a call to `dbClearResult()`. Failure to clear the result set leads to a warning when the connection is closed. If the backend supports only one open result set per connection, issuing a second query invalidates an already open result set and raises a warning. The newly opened result set is valid and must be cleared with `dbClearResult()`. The `param` argument allows passing query parameters, see `dbBind()` for details. ### Specification for the `immediate` argument The `immediate` argument supports distinguishing between "direct" and "prepared" APIs offered by many database drivers. Passing `immediate = TRUE` leads to immediate execution of the query or statement, via the "direct" API (if supported by the driver). The default `NULL` means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct `immediate` argument. Examples for possible behaviors: 1. DBI backend defaults to `immediate = TRUE` internally 1. A query without parameters is passed: query is executed 2. A query with parameters is passed: 1. `params` not given: rejected immediately by the database because of a syntax error in the query, the backend tries `immediate = FALSE` (and gives a message) 2. `params` given: query is executed using `immediate = FALSE` 2. DBI backend defaults to `immediate = FALSE` internally 1. A query without parameters is passed: 1. simple query: query is executed 2. "special" query (such as setting a config options): fails, the backend tries `immediate = TRUE` (and gives a message) 2. A query with parameters is passed: 1. `params` not given: waiting for parameters via `dbBind()` 2. `params` given: query is executed ### Details This method is for `SELECT` queries only. Some backends may support data manipulation queries through this method for compatibility reasons. However, callers are strongly encouraged to use `dbSendStatement()` for data manipulation statements. The query is submitted to the database server and the DBMS executes it, possibly generating vast amounts of data. Where these data live is driver-specific: some drivers may choose to leave the output on the server and transfer them piecemeal to R, others may transfer all the data to the client – but not necessarily to the memory that R manages. See individual drivers' `dbSendQuery()` documentation for details. ### Value `dbSendQuery()` returns an S4 object that inherits from DBIResult. The result set can be used with `dbFetch()` to extract records. Once you have finished using a result, make sure to clear it with `dbClearResult()`. ### The data retrieval flow This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of `dbBind()` or `dbBindArrow()`, is implemented by `dbGetQuery()`, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendQuery()` to create a result set object of class DBIResult. 2. Optionally, bind query parameters with `dbBind()` or `dbBindArrow()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Optionally, use `dbColumnInfo()` to retrieve the structure of the result set without retrieving actual data. 4. Use `dbFetch()` to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. 5. Use `dbHasCompleted()` to tell when you're done. This method returns `TRUE` if no more rows are available for fetching. 6. Repeat the last four steps as necessary. 7. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### Failure modes An error is raised when issuing a query over a closed or invalid connection, or if the query is not a non-`NA` string. An error is also raised if the syntax of the query is invalid and all query parameters are given (by passing the `params` argument) or the `immediate` argument is set to `TRUE`. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") dbFetch(rs) dbClearResult(rs) # Pass one set of values with the param argument: rs <- dbSendQuery( con, "SELECT * FROM mtcars WHERE cyl = ?", params = list(4L) ) dbFetch(rs) dbClearResult(rs) # Pass multiple sets of values with dbBind(): rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = ?") dbBind(rs, list(6L)) dbFetch(rs) dbBind(rs, list(8L)) dbFetch(rs) dbClearResult(rs) dbDisconnect(con) ``` ## Fetch records from a previously executed query This section describes the behavior of the following methods: ``` r dbFetch(res, n = -1, ...) fetch(res, n = -1, ...) ``` ### Description Fetch the next `n` elements (rows) from the result set and return them as a data.frame. ### Arguments | | | |-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `res` | An object inheriting from DBIResult, created by `dbSendQuery()`. | | `n` | maximum number of records to retrieve per fetch. Use `n = -1` or `n = Inf` to retrieve all pending records. Some implementations may recognize other special values. | | `...` | Other arguments passed on to methods. | ### Details `fetch()` is provided for compatibility with older DBI clients - for all new code you are strongly encouraged to use `dbFetch()`. The default implementation for `dbFetch()` calls `fetch()` so that it is compatible with existing code. Modern backends should implement for `dbFetch()` only. ### Value `dbFetch()` always returns a data.frame with as many rows as records were fetched and as many columns as fields in the result set, even if the result is a single value or has one or zero rows. Passing `n = NA` is supported and returns an arbitrary number of rows (at least one) as specified by the driver, but at most the remaining rows in the result set. ### The data retrieval flow This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of `dbBind()` or `dbBindArrow()`, is implemented by `dbGetQuery()`, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendQuery()` to create a result set object of class DBIResult. 2. Optionally, bind query parameters with `dbBind()` or `dbBindArrow()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Optionally, use `dbColumnInfo()` to retrieve the structure of the result set without retrieving actual data. 4. Use `dbFetch()` to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. 5. Use `dbHasCompleted()` to tell when you're done. This method returns `TRUE` if no more rows are available for fetching. 6. Repeat the last four steps as necessary. 7. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### Failure modes An attempt to fetch from a closed result set raises an error. If the `n` argument is not an atomic whole number greater or equal to -1 or Inf, an error is raised, but a subsequent call to `dbFetch()` with proper `n` argument succeeds. Calling `dbFetch()` on a result set from a data manipulation query created by `dbSendStatement()` can be fetched and return an empty data frame, with a warning. ### Specification Fetching multi-row queries with one or more columns by default returns the entire result. Multi-row queries can also be fetched progressively by passing a whole number (integer or numeric) as the `n` argument. A value of Inf for the `n` argument is supported and also returns the full result. If more rows than available are fetched, the result is returned in full without warning. If fewer rows than requested are returned, further fetches will return a data frame with zero rows. If zero rows are fetched, the columns of the data frame are still fully typed. Fetching fewer rows than available is permitted, no warning is issued when clearing the result set. A column named `row_names` is treated like any other column. The column types of the returned data frame depend on the data returned: - integer (or coercible to an integer) for integer values between -2^31 and 2^31 - 1, with NA for SQL `NULL` values - numeric for numbers with a fractional component, with NA for SQL `NULL` values - logical for Boolean values (some backends may return an integer); with NA for SQL `NULL` values - character for text, with NA for SQL `NULL` values - lists of raw for blobs with NULL entries for SQL NULL values - coercible using `as.Date()` for dates, with NA for SQL `NULL` values (also applies to the return value of the SQL function `current_date`) - coercible using `hms::as_hms()` for times, with NA for SQL `NULL` values (also applies to the return value of the SQL function `current_time`) - coercible using `as.POSIXct()` for timestamps, with NA for SQL `NULL` values (also applies to the return value of the SQL function `current_timestamp`) If dates and timestamps are supported by the backend, the following R types are used: - Date for dates (also applies to the return value of the SQL function `current_date`) - POSIXct for timestamps (also applies to the return value of the SQL function `current_timestamp`) R has no built-in type with lossless support for the full range of 64-bit or larger integers. If 64-bit integers are returned from a query, the following rules apply: - Values are returned in a container with support for the full range of valid 64-bit values (such as the `integer64` class of the bit64 package) - Coercion to numeric always returns a number that is as close as possible to the true value - Loss of precision when converting to numeric gives a warning - Conversion to character always returns a lossless decimal representation of the data ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) # Fetch all results rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") dbFetch(rs) dbClearResult(rs) # Fetch in chunks rs <- dbSendQuery(con, "SELECT * FROM mtcars") while (!dbHasCompleted(rs)) { chunk <- dbFetch(rs, 10) print(nrow(chunk)) } dbClearResult(rs) dbDisconnect(con) ``` ## Clear a result set This section describes the behavior of the following method: ``` r dbClearResult(res, ...) ``` ### Description Frees all resources (local and remote) associated with a result set. This step is mandatory for all objects obtained by calling `dbSendQuery()` or `dbSendStatement()`. ### Arguments | | | |-------|---------------------------------------| | `res` | An object inheriting from DBIResult. | | `...` | Other arguments passed on to methods. | ### Value `dbClearResult()` returns `TRUE`, invisibly, for result sets obtained from `dbSendQuery()`, `dbSendStatement()`, or `dbSendQueryArrow()`, ### The data retrieval flow This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of `dbBind()` or `dbBindArrow()`, is implemented by `dbGetQuery()`, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendQuery()` to create a result set object of class DBIResult. 2. Optionally, bind query parameters with `dbBind()` or `dbBindArrow()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Optionally, use `dbColumnInfo()` to retrieve the structure of the result set without retrieving actual data. 4. Use `dbFetch()` to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. 5. Use `dbHasCompleted()` to tell when you're done. This method returns `TRUE` if no more rows are available for fetching. 6. Repeat the last four steps as necessary. 7. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### The command execution flow This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of `dbBindArrow()`, is implemented by `dbExecute()`, which should be sufficient for non-parameterized queries. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendStatement()` to create a result set object of class DBIResult. For some queries you need to pass `immediate = TRUE`. 2. Optionally, bind query parameters with`dbBind()` or `dbBindArrow()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Optionally, use `dbGetRowsAffected()` to retrieve the number of rows affected by the query. 4. Repeat the last two steps as necessary. 5. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### Failure modes An attempt to close an already closed result set issues a warning for `dbSendQuery()`, `dbSendStatement()`, and `dbSendQueryArrow()`, ### Specification `dbClearResult()` frees all resources associated with retrieving the result of a query or update operation. The DBI backend can expect a call to `dbClearResult()` for each `dbSendQuery()` or `dbSendStatement()` call. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") rs <- dbSendQuery(con, "SELECT 1") print(dbFetch(rs)) dbClearResult(rs) dbDisconnect(con) ``` ## Bind values to a parameterized/prepared statement This section describes the behavior of the following methods: ``` r dbBind(res, params, ...) dbBindArrow(res, params, ...) ``` ### Description For parametrized or prepared statements, the `dbSendQuery()`, `dbSendQueryArrow()`, and `dbSendStatement()` functions can be called with statements that contain placeholders for values. The `dbBind()` and `dbBindArrow()` functions bind these placeholders to actual values, and are intended to be called on the result set before calling `dbFetch()` or `dbFetchArrow()`. The values are passed to `dbBind()` as lists or data frames, and to `dbBindArrow()` as a stream created by `nanoarrow::as_nanoarrow_array_stream()`. [![\[Experimental\]](https://dbi.r-dbi.org/reference/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) `dbBindArrow()` is experimental, as are the other `⁠*Arrow⁠` functions. `dbSendQuery()` is compatible with `dbBindArrow()`, and `dbSendQueryArrow()` is compatible with `dbBind()`. ### Arguments | | | |----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `res` | An object inheriting from DBIResult. | | `params` | For `dbBind()`, a list of values, named or unnamed, or a data frame, with one element/column per query parameter. For `dbBindArrow()`, values as a nanoarrow stream, with one column per query parameter. | | `...` | Other arguments passed on to methods. | ### Details DBI supports parametrized (or prepared) queries and statements via the `dbBind()` and `dbBindArrow()` generics. Parametrized queries are different from normal queries in that they allow an arbitrary number of placeholders, which are later substituted by actual values. Parametrized queries (and statements) serve two purposes: - The same query can be executed more than once with different values. The DBMS may cache intermediate information for the query, such as the execution plan, and execute it faster. - Separation of query syntax and parameters protects against SQL injection. The placeholder format is currently not specified by DBI; in the future, a uniform placeholder syntax may be supported. Consult the backend documentation for the supported formats. For automated testing, backend authors specify the placeholder syntax with the `placeholder_pattern` tweak. Known examples are: - `⁠?⁠` (positional matching in order of appearance) in RMariaDB and RSQLite - `⁠\$1⁠` (positional matching by index) in RPostgres and RSQLite - `⁠:name⁠` and `⁠\$name⁠` (named matching) in RSQLite ### Value `dbBind()` returns the result set, invisibly, for queries issued by `dbSendQuery()` or `dbSendQueryArrow()` and also for data manipulation statements issued by `dbSendStatement()`. ### The data retrieval flow This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of `dbBind()` or `dbBindArrow()`, is implemented by `dbGetQuery()`, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendQuery()` to create a result set object of class DBIResult. 2. Optionally, bind query parameters with `dbBind()` or `dbBindArrow()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Optionally, use `dbColumnInfo()` to retrieve the structure of the result set without retrieving actual data. 4. Use `dbFetch()` to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. 5. Use `dbHasCompleted()` to tell when you're done. This method returns `TRUE` if no more rows are available for fetching. 6. Repeat the last four steps as necessary. 7. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### The data retrieval flow for Arrow streams This section gives a complete overview over the flow for the execution of queries that return tabular data as an Arrow stream. Most of this flow, except repeated calling of `dbBindArrow()` or `dbBind()`, is implemented by `dbGetQueryArrow()`, which should be sufficient unless you have a parameterized query that you want to reuse. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendQueryArrow()` to create a result set object of class DBIResultArrow. 2. Optionally, bind query parameters with `dbBindArrow()` or `dbBind()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Use `dbFetchArrow()` to get a data stream. 4. Repeat the last two steps as necessary. 5. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### The command execution flow This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of `dbBindArrow()`, is implemented by `dbExecute()`, which should be sufficient for non-parameterized queries. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendStatement()` to create a result set object of class DBIResult. For some queries you need to pass `immediate = TRUE`. 2. Optionally, bind query parameters with`dbBind()` or `dbBindArrow()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Optionally, use `dbGetRowsAffected()` to retrieve the number of rows affected by the query. 4. Repeat the last two steps as necessary. 5. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### Failure modes Calling `dbBind()` for a query without parameters raises an error. Binding too many or not enough values, or parameters with wrong names or unequal length, also raises an error. If the placeholders in the query are named, all parameter values must have names (which must not be empty or `NA`), and vice versa, otherwise an error is raised. The behavior for mixing placeholders of different types (in particular mixing positional and named placeholders) is not specified. Calling `dbBind()` on a result set already cleared by `dbClearResult()` also raises an error. ### Specification DBI clients execute parametrized statements as follows: 1. Call `dbSendQuery()`, `dbSendQueryArrow()` or `dbSendStatement()` with a query or statement that contains placeholders, store the returned DBIResult object in a variable. Mixing placeholders (in particular, named and unnamed ones) is not recommended. It is good practice to register a call to `dbClearResult()` via `on.exit()` right after calling `dbSendQuery()` or `dbSendStatement()` (see the last enumeration item). Until `dbBind()` or `dbBindArrow()` have been called, the returned result set object has the following behavior: - `dbFetch()` raises an error (for `dbSendQuery()` and `dbSendQueryArrow()`) - `dbGetRowCount()` returns zero (for `dbSendQuery()` and `dbSendQueryArrow()`) - `dbGetRowsAffected()` returns an integer `NA` (for `dbSendStatement()`) - `dbIsValid()` returns `TRUE` - `dbHasCompleted()` returns `FALSE` 2. Call `dbBind()` or `dbBindArrow()`: - For `dbBind()`, the `params` argument must be a list where all elements have the same lengths and contain values supported by the backend. A data.frame is internally stored as such a list. - For `dbBindArrow()`, the `params` argument must be a nanoarrow array stream, with one column per query parameter. 3. Retrieve the data or the number of affected rows from the `DBIResult` object. - For queries issued by `dbSendQuery()` or `dbSendQueryArrow()`, call `dbFetch()`. - For statements issued by `dbSendStatements()`, call `dbGetRowsAffected()`. (Execution begins immediately after the `dbBind()` call, the statement is processed entirely before the function returns.) 4. Repeat 2. and 3. as necessary. 5. Close the result set via `dbClearResult()`. The elements of the `params` argument do not need to be scalars, vectors of arbitrary length (including length 0) are supported. For queries, calling `dbFetch()` binding such parameters returns concatenated results, equivalent to binding and fetching for each set of values and connecting via `rbind()`. For data manipulation statements, `dbGetRowsAffected()` returns the total number of rows affected if binding non-scalar parameters. `dbBind()` also accepts repeated calls on the same result set for both queries and data manipulation statements, even if no results are fetched between calls to `dbBind()`, for both queries and data manipulation statements. If the placeholders in the query are named, their order in the `params` argument is not important. At least the following data types are accepted on input (including NA): - integer - numeric - logical for Boolean values - character (also with special characters such as spaces, newlines, quotes, and backslashes) - factor (bound as character, with warning) - Date (also when stored internally as integer) - POSIXct timestamps - POSIXlt timestamps - difftime values (also with units other than seconds and with the value stored as integer) - lists of raw for blobs (with `NULL` entries for SQL NULL values) - objects of type blob::blob ### Examples ``` r # Data frame flow: con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "iris", iris) # Using the same query for different values iris_result <- dbSendQuery(con, "SELECT * FROM iris WHERE [Petal.Width] > ?") dbBind(iris_result, list(2.3)) dbFetch(iris_result) dbBind(iris_result, list(3)) dbFetch(iris_result) dbClearResult(iris_result) # Executing the same statement with different values at once iris_result <- dbSendStatement(con, "DELETE FROM iris WHERE [Species] = \$species") dbBind(iris_result, list(species = c("setosa", "versicolor", "unknown"))) dbGetRowsAffected(iris_result) dbClearResult(iris_result) nrow(dbReadTable(con, "iris")) dbDisconnect(con) # Arrow flow: con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "iris", iris) # Using the same query for different values iris_result <- dbSendQueryArrow(con, "SELECT * FROM iris WHERE [Petal.Width] > ?") dbBindArrow( iris_result, nanoarrow::as_nanoarrow_array_stream(data.frame(2.3, fix.empty.names = FALSE)) ) as.data.frame(dbFetchArrow(iris_result)) dbBindArrow( iris_result, nanoarrow::as_nanoarrow_array_stream(data.frame(3, fix.empty.names = FALSE)) ) as.data.frame(dbFetchArrow(iris_result)) dbClearResult(iris_result) # Executing the same statement with different values at once iris_result <- dbSendStatement(con, "DELETE FROM iris WHERE [Species] = \$species") dbBindArrow(iris_result, nanoarrow::as_nanoarrow_array_stream(data.frame( species = c("setosa", "versicolor", "unknown") ))) dbGetRowsAffected(iris_result) dbClearResult(iris_result) nrow(dbReadTable(con, "iris")) dbDisconnect(con) ``` ## Retrieve results from a query This section describes the behavior of the following method: ``` r dbGetQuery(conn, statement, ...) ``` ### Description Returns the result of a query as a data frame. `dbGetQuery()` comes with a default implementation (which should work with most backends) that calls `dbSendQuery()`, then `dbFetch()`, ensuring that the result is always freed by `dbClearResult()`. For retrieving chunked/paged results or for passing query parameters, see `dbSendQuery()`, in particular the "The data retrieval flow" section. For retrieving results as an Arrow object, see `dbGetQueryArrow()`. ### Arguments | | | |-------------|-------------------------------------------------------| | `conn` | A DBIConnection object, as returned by `dbConnect()`. | | `statement` | a character string containing SQL. | | `...` | Other parameters passed on to methods. | ### Additional arguments The following arguments are not part of the `dbGetQuery()` generic (to improve compatibility across backends) but are part of the DBI specification: - `n` (default: -1) - `params` (default: `NULL`) - `immediate` (default: `NULL`) They must be provided as named arguments. See the "Specification" and "Value" sections for details on their usage. ### Specification A column named `row_names` is treated like any other column. The `n` argument specifies the number of rows to be fetched. If omitted, fetching multi-row queries with one or more columns returns the entire result. A value of Inf for the `n` argument is supported and also returns the full result. If more rows than available are fetched (by passing a too large value for `n`), the result is returned in full without warning. If zero rows are requested, the columns of the data frame are still fully typed. Fetching fewer rows than available is permitted, no warning is issued. The `param` argument allows passing query parameters, see `dbBind()` for details. ### Specification for the `immediate` argument The `immediate` argument supports distinguishing between "direct" and "prepared" APIs offered by many database drivers. Passing `immediate = TRUE` leads to immediate execution of the query or statement, via the "direct" API (if supported by the driver). The default `NULL` means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct `immediate` argument. Examples for possible behaviors: 1. DBI backend defaults to `immediate = TRUE` internally 1. A query without parameters is passed: query is executed 2. A query with parameters is passed: 1. `params` not given: rejected immediately by the database because of a syntax error in the query, the backend tries `immediate = FALSE` (and gives a message) 2. `params` given: query is executed using `immediate = FALSE` 2. DBI backend defaults to `immediate = FALSE` internally 1. A query without parameters is passed: 1. simple query: query is executed 2. "special" query (such as setting a config options): fails, the backend tries `immediate = TRUE` (and gives a message) 2. A query with parameters is passed: 1. `params` not given: waiting for parameters via `dbBind()` 2. `params` given: query is executed ### Details This method is for `SELECT` queries only (incl. other SQL statements that return a `SELECT`-alike result, e.g., execution of a stored procedure or data manipulation queries like `⁠INSERT INTO ... RETURNING ...⁠`). To execute a stored procedure that does not return a result set, use `dbExecute()`. Some backends may support data manipulation statements through this method for compatibility reasons. However, callers are strongly advised to use `dbExecute()` for data manipulation statements. ### Value `dbGetQuery()` always returns a data.frame, with as many rows as records were fetched and as many columns as fields in the result set, even if the result is a single value or has one or zero rows. ### Implementation notes Subclasses should override this method only if they provide some sort of performance optimization. ### Failure modes An error is raised when issuing a query over a closed or invalid connection, if the syntax of the query is invalid, or if the query is not a non-`NA` string. If the `n` argument is not an atomic whole number greater or equal to -1 or Inf, an error is raised, but a subsequent call to `dbGetQuery()` with proper `n` argument succeeds. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) dbGetQuery(con, "SELECT * FROM mtcars") dbGetQuery(con, "SELECT * FROM mtcars", n = 6) # Pass values using the param argument: # (This query runs eight times, once for each different # parameter. The resulting rows are combined into a single # data frame.) dbGetQuery( con, "SELECT COUNT(*) FROM mtcars WHERE cyl = ?", params = list(1:8) ) dbDisconnect(con) ``` ## Execute a data manipulation statement on a given database connection This section describes the behavior of the following method: ``` r dbSendStatement(conn, statement, ...) ``` ### Description The `dbSendStatement()` method only submits and synchronously executes the SQL data manipulation statement (e.g., `UPDATE`, `DELETE`, `⁠INSERT INTO⁠`, `⁠DROP TABLE⁠`, ...) to the database engine. To query the number of affected rows, call `dbGetRowsAffected()` on the returned result object. You must also call `dbClearResult()` after that. For interactive use, you should almost always prefer `dbExecute()`. ### Arguments | | | |-------------|-------------------------------------------------------| | `conn` | A DBIConnection object, as returned by `dbConnect()`. | | `statement` | a character string containing SQL. | | `...` | Other parameters passed on to methods. | ### Additional arguments The following arguments are not part of the `dbSendStatement()` generic (to improve compatibility across backends) but are part of the DBI specification: - `params` (default: `NULL`) - `immediate` (default: `NULL`) They must be provided as named arguments. See the "Specification" sections for details on their usage. ### Specification No warnings occur under normal conditions. When done, the DBIResult object must be cleared with a call to `dbClearResult()`. Failure to clear the result set leads to a warning when the connection is closed. If the backend supports only one open result set per connection, issuing a second query invalidates an already open result set and raises a warning. The newly opened result set is valid and must be cleared with `dbClearResult()`. The `param` argument allows passing query parameters, see `dbBind()` for details. ### Specification for the `immediate` argument The `immediate` argument supports distinguishing between "direct" and "prepared" APIs offered by many database drivers. Passing `immediate = TRUE` leads to immediate execution of the query or statement, via the "direct" API (if supported by the driver). The default `NULL` means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct `immediate` argument. Examples for possible behaviors: 1. DBI backend defaults to `immediate = TRUE` internally 1. A query without parameters is passed: query is executed 2. A query with parameters is passed: 1. `params` not given: rejected immediately by the database because of a syntax error in the query, the backend tries `immediate = FALSE` (and gives a message) 2. `params` given: query is executed using `immediate = FALSE` 2. DBI backend defaults to `immediate = FALSE` internally 1. A query without parameters is passed: 1. simple query: query is executed 2. "special" query (such as setting a config options): fails, the backend tries `immediate = TRUE` (and gives a message) 2. A query with parameters is passed: 1. `params` not given: waiting for parameters via `dbBind()` 2. `params` given: query is executed ### Details `dbSendStatement()` comes with a default implementation that simply forwards to `dbSendQuery()`, to support backends that only implement the latter. ### Value `dbSendStatement()` returns an S4 object that inherits from DBIResult. The result set can be used with `dbGetRowsAffected()` to determine the number of rows affected by the query. Once you have finished using a result, make sure to clear it with `dbClearResult()`. ### The command execution flow This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of `dbBindArrow()`, is implemented by `dbExecute()`, which should be sufficient for non-parameterized queries. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendStatement()` to create a result set object of class DBIResult. For some queries you need to pass `immediate = TRUE`. 2. Optionally, bind query parameters with`dbBind()` or `dbBindArrow()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Optionally, use `dbGetRowsAffected()` to retrieve the number of rows affected by the query. 4. Repeat the last two steps as necessary. 5. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### Failure modes An error is raised when issuing a statement over a closed or invalid connection, or if the statement is not a non-`NA` string. An error is also raised if the syntax of the query is invalid and all query parameters are given (by passing the `params` argument) or the `immediate` argument is set to `TRUE`. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cars", head(cars, 3)) rs <- dbSendStatement( con, "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)" ) dbHasCompleted(rs) dbGetRowsAffected(rs) dbClearResult(rs) dbReadTable(con, "cars") # there are now 6 rows # Pass one set of values directly using the param argument: rs <- dbSendStatement( con, "INSERT INTO cars (speed, dist) VALUES (?, ?)", params = list(4L, 5L) ) dbClearResult(rs) # Pass multiple sets of values using dbBind(): rs <- dbSendStatement( con, "INSERT INTO cars (speed, dist) VALUES (?, ?)" ) dbBind(rs, list(5:6, 6:7)) dbBind(rs, list(7L, 8L)) dbClearResult(rs) dbReadTable(con, "cars") # there are now 10 rows dbDisconnect(con) ``` ## Change database state This section describes the behavior of the following method: ``` r dbExecute(conn, statement, ...) ``` ### Description Executes a statement and returns the number of rows affected. `dbExecute()` comes with a default implementation (which should work with most backends) that calls `dbSendStatement()`, then `dbGetRowsAffected()`, ensuring that the result is always freed by `dbClearResult()`. For passing query parameters, see `dbBind()`, in particular the "The command execution flow" section. ### Arguments | | | |-------------|-------------------------------------------------------| | `conn` | A DBIConnection object, as returned by `dbConnect()`. | | `statement` | a character string containing SQL. | | `...` | Other parameters passed on to methods. | ### Additional arguments The following arguments are not part of the `dbExecute()` generic (to improve compatibility across backends) but are part of the DBI specification: - `params` (default: `NULL`) - `immediate` (default: `NULL`) They must be provided as named arguments. See the "Specification" sections for details on their usage. ### Specification The `param` argument allows passing query parameters, see `dbBind()` for details. ### Specification for the `immediate` argument The `immediate` argument supports distinguishing between "direct" and "prepared" APIs offered by many database drivers. Passing `immediate = TRUE` leads to immediate execution of the query or statement, via the "direct" API (if supported by the driver). The default `NULL` means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct `immediate` argument. Examples for possible behaviors: 1. DBI backend defaults to `immediate = TRUE` internally 1. A query without parameters is passed: query is executed 2. A query with parameters is passed: 1. `params` not given: rejected immediately by the database because of a syntax error in the query, the backend tries `immediate = FALSE` (and gives a message) 2. `params` given: query is executed using `immediate = FALSE` 2. DBI backend defaults to `immediate = FALSE` internally 1. A query without parameters is passed: 1. simple query: query is executed 2. "special" query (such as setting a config options): fails, the backend tries `immediate = TRUE` (and gives a message) 2. A query with parameters is passed: 1. `params` not given: waiting for parameters via `dbBind()` 2. `params` given: query is executed ### Details You can also use `dbExecute()` to call a stored procedure that performs data manipulation or other actions that do not return a result set. To execute a stored procedure that returns a result set, or a data manipulation query that also returns a result set such as `⁠INSERT INTO ... RETURNING ...⁠`, use `dbGetQuery()` instead. ### Value `dbExecute()` always returns a scalar numeric that specifies the number of rows affected by the statement. ### Implementation notes Subclasses should override this method only if they provide some sort of performance optimization. ### Failure modes An error is raised when issuing a statement over a closed or invalid connection, if the syntax of the statement is invalid, or if the statement is not a non-`NA` string. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cars", head(cars, 3)) dbReadTable(con, "cars") # there are 3 rows dbExecute( con, "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)" ) dbReadTable(con, "cars") # there are now 6 rows # Pass values using the param argument: dbExecute( con, "INSERT INTO cars (speed, dist) VALUES (?, ?)", params = list(4:7, 5:8) ) dbReadTable(con, "cars") # there are now 10 rows dbDisconnect(con) ``` ## Quote literal strings This section describes the behavior of the following method: ``` r dbQuoteString(conn, x, ...) ``` ### Description Call this method to generate a string that is suitable for use in a query as a string literal, to make sure that you generate valid SQL and protect against SQL injection attacks. ### Arguments | | | |--------|-------------------------------------------------------| | `conn` | A DBIConnection object, as returned by `dbConnect()`. | | `x` | A character vector to quote as string. | | `...` | Other arguments passed on to methods. | ### Value `dbQuoteString()` returns an object that can be coerced to character, of the same length as the input. For an empty character vector this function returns a length-0 object. When passing the returned object again to `dbQuoteString()` as `x` argument, it is returned unchanged. Passing objects of class SQL should also return them unchanged. (For backends it may be most convenient to return SQL objects to achieve this behavior, but this is not required.) ### Failure modes Passing a numeric, integer, logical, or raw vector, or a list for the `x` argument raises an error. ### Specification The returned expression can be used in a `⁠SELECT ...⁠` query, and for any scalar character `x` the value of `dbGetQuery(paste0("SELECT ", dbQuoteString(x)))[[1]]` must be identical to `x`, even if `x` contains spaces, tabs, quotes (single or double), backticks, or newlines (in any combination) or is itself the result of a `dbQuoteString()` call coerced back to character (even repeatedly). If `x` is `NA`, the result must merely satisfy `is.na()`. The strings `"NA"` or `"NULL"` are not treated specially. `NA` should be translated to an unquoted SQL `NULL`, so that the query `⁠SELECT * FROM (SELECT 1) a WHERE ... IS NULL⁠` returns one row. ### Examples ``` r # Quoting ensures that arbitrary input is safe for use in a query name <- "Robert'); DROP TABLE Students;--" dbQuoteString(ANSI(), name) # NAs become NULL dbQuoteString(ANSI(), c("x", NA)) # SQL vectors are always passed through as is var_name <- SQL("select") var_name dbQuoteString(ANSI(), var_name) # This mechanism is used to prevent double escaping dbQuoteString(ANSI(), dbQuoteString(ANSI(), name)) ``` ## Quote identifiers This section describes the behavior of the following method: ``` r dbQuoteIdentifier(conn, x, ...) ``` ### Description Call this method to generate a string that is suitable for use in a query as a column or table name, to make sure that you generate valid SQL and protect against SQL injection attacks. The inverse operation is `dbUnquoteIdentifier()`. ### Arguments | | | |--------|--------------------------------------------------------------| | `conn` | A DBIConnection object, as returned by `dbConnect()`. | | `x` | A character vector, SQL or Id object to quote as identifier. | | `...` | Other arguments passed on to methods. | ### Value `dbQuoteIdentifier()` returns an object that can be coerced to character, of the same length as the input. For an empty character vector this function returns a length-0 object. The names of the input argument are preserved in the output. When passing the returned object again to `dbQuoteIdentifier()` as `x` argument, it is returned unchanged. Passing objects of class SQL should also return them unchanged. (For backends it may be most convenient to return SQL objects to achieve this behavior, but this is not required.) ### Failure modes An error is raised if the input contains `NA`, but not for an empty string. ### Specification Calling `dbGetQuery()` for a query of the format `⁠SELECT 1 AS ...⁠` returns a data frame with the identifier, unquoted, as column name. Quoted identifiers can be used as table and column names in SQL queries, in particular in queries like `⁠SELECT 1 AS ...⁠` and `⁠SELECT * FROM (SELECT 1) ...⁠`. The method must use a quoting mechanism that is unambiguously different from the quoting mechanism used for strings, so that a query like `⁠SELECT ... FROM (SELECT 1 AS ...)⁠` throws an error if the column names do not match. The method can quote column names that contain special characters such as a space, a dot, a comma, or quotes used to mark strings or identifiers, if the database supports this. In any case, checking the validity of the identifier should be performed only when executing a query, and not by `dbQuoteIdentifier()`. ### Examples ``` r # Quoting ensures that arbitrary input is safe for use in a query name <- "Robert'); DROP TABLE Students;--" dbQuoteIdentifier(ANSI(), name) # Use Id() to specify other components such as the schema id_name <- Id(schema = "schema_name", table = "table_name") id_name dbQuoteIdentifier(ANSI(), id_name) # SQL vectors are always passed through as is var_name <- SQL("select") var_name dbQuoteIdentifier(ANSI(), var_name) # This mechanism is used to prevent double escaping dbQuoteIdentifier(ANSI(), dbQuoteIdentifier(ANSI(), name)) ``` ## Read database tables as data frames This section describes the behavior of the following method: ``` r dbReadTable(conn, name, ...) ``` ### Description Reads a database table to a data frame, optionally converting a column to row names and converting the column names to valid R identifiers. Use `dbReadTableArrow()` instead to obtain an Arrow object. ### Arguments
conn

A DBIConnection object, as returned by dbConnect().
name

The table name, passed on to dbQuoteIdentifier(). Options are:

  • a character string with the unquoted DBMS table name, e.g. "table_name",

  • a call to Id() with components to the fully qualified table name, e.g. Id(schema = "my_schema", table = "table_name")

  • a call to SQL() with the quoted and fully qualified table name given verbatim, e.g. SQL('"my_schema"."table_name"')
...

Other parameters passed on to methods.
### Additional arguments The following arguments are not part of the `dbReadTable()` generic (to improve compatibility across backends) but are part of the DBI specification: - `row.names` (default: `FALSE`) - `check.names` They must be provided as named arguments. See the "Value" section for details on their usage. ### Specification The `name` argument is processed as follows, to support databases that allow non-syntactic names for their objects: - If an unquoted table name as string: `dbReadTable()` will do the quoting, perhaps by calling `dbQuoteIdentifier(conn, x = name)` - If the result of a call to `dbQuoteIdentifier()`: no more quoting is done ### Details This function returns a data frame. Use `dbReadTableArrow()` to obtain an Arrow object. ### Value `dbReadTable()` returns a data frame that contains the complete data from the remote table, effectively the result of calling `dbGetQuery()` with `⁠SELECT * FROM ⁠`. An empty table is returned as a data frame with zero rows. The presence of rownames depends on the `row.names` argument, see `sqlColumnToRownames()` for details: - If `FALSE` or `NULL`, the returned data frame doesn't have row names. - If `TRUE`, a column named "row_names" is converted to row names. - If `NA`, a column named "row_names" is converted to row names if it exists, otherwise no translation occurs. - If a string, this specifies the name of the column in the remote table that contains the row names. The default is `row.names = FALSE`. If the database supports identifiers with special characters, the columns in the returned data frame are converted to valid R identifiers if the `check.names` argument is `TRUE`, If `check.names = FALSE`, the returned table has non-syntactic column names without quotes. ### Failure modes An error is raised if the table does not exist. An error is raised if `row.names` is `TRUE` and no "row_names" column exists, An error is raised if `row.names` is set to a string and no corresponding column exists. An error is raised when calling this method for a closed or invalid connection. An error is raised if `name` cannot be processed with `dbQuoteIdentifier()` or if this results in a non-scalar. Unsupported values for `row.names` and `check.names` (non-scalars, unsupported data types, `NA` for `check.names`) also raise an error. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars[1:10, ]) dbReadTable(con, "mtcars") dbDisconnect(con) ``` ## Copy data frames to database tables This section describes the behavior of the following method: ``` r dbWriteTable(conn, name, value, ...) ``` ### Description Writes, overwrites or appends a data frame to a database table, optionally converting row names to a column and specifying SQL data types for fields. ### Arguments
conn

A DBIConnection object, as returned by dbConnect().
name

The table name, passed on to dbQuoteIdentifier(). Options are:

  • a character string with the unquoted DBMS table name, e.g. "table_name",

  • a call to Id() with components to the fully qualified table name, e.g. Id(schema = "my_schema", table = "table_name")

  • a call to SQL() with the quoted and fully qualified table name given verbatim, e.g. SQL('"my_schema"."table_name"')
value

A data.frame (or coercible to data.frame).
...

Other parameters passed on to methods.
### Additional arguments The following arguments are not part of the `dbWriteTable()` generic (to improve compatibility across backends) but are part of the DBI specification: - `row.names` (default: `FALSE`) - `overwrite` (default: `FALSE`) - `append` (default: `FALSE`) - `field.types` (default: `NULL`) - `temporary` (default: `FALSE`) They must be provided as named arguments. See the "Specification" and "Value" sections for details on their usage. ### Specification The `name` argument is processed as follows, to support databases that allow non-syntactic names for their objects: - If an unquoted table name as string: `dbWriteTable()` will do the quoting, perhaps by calling `dbQuoteIdentifier(conn, x = name)` - If the result of a call to `dbQuoteIdentifier()`: no more quoting is done The `value` argument must be a data frame with a subset of the columns of the existing table if `append = TRUE`. The order of the columns does not matter with `append = TRUE`. If the `overwrite` argument is `TRUE`, an existing table of the same name will be overwritten. This argument doesn't change behavior if the table does not exist yet. If the `append` argument is `TRUE`, the rows in an existing table are preserved, and the new data are appended. If the table doesn't exist yet, it is created. If the `temporary` argument is `TRUE`, the table is not available in a second connection and is gone after reconnecting. Not all backends support this argument. A regular, non-temporary table is visible in a second connection, in a pre-existing connection, and after reconnecting to the database. SQL keywords can be used freely in table names, column names, and data. Quotes, commas, spaces, and other special characters such as newlines and tabs, can also be used in the data, and, if the database supports non-syntactic identifiers, also for table names and column names. The following data types must be supported at least, and be read identically with `dbReadTable()`: - integer - numeric (the behavior for `Inf` and `NaN` is not specified) - logical - `NA` as NULL - 64-bit values (using `"bigint"` as field type); the result can be - converted to a numeric, which may lose precision, - converted a character vector, which gives the full decimal representation - written to another table and read again unchanged - character (in both UTF-8 and native encodings), supporting empty strings before and after a non-empty string - factor (returned as character) - list of raw (if supported by the database) - objects of type blob::blob (if supported by the database) - date (if supported by the database; returned as `Date`), also for dates prior to 1970 or 1900 or after 2038 - time (if supported by the database; returned as objects that inherit from `difftime`) - timestamp (if supported by the database; returned as `POSIXct` respecting the time zone but not necessarily preserving the input time zone), also for timestamps prior to 1970 or 1900 or after 2038 respecting the time zone but not necessarily preserving the input time zone) Mixing column types in the same table is supported. The `field.types` argument must be a named character vector with at most one entry for each column. It indicates the SQL data type to be used for a new column. If a column is missed from `field.types`, the type is inferred from the input data with `dbDataType()`. The interpretation of rownames depends on the `row.names` argument, see `sqlRownamesToColumn()` for details: - If `FALSE` or `NULL`, row names are ignored. - If `TRUE`, row names are converted to a column named "row_names", even if the input data frame only has natural row names from 1 to `nrow(...)`. - If `NA`, a column named "row_names" is created if the data has custom row names, no extra column is created in the case of natural row names. - If a string, this specifies the name of the column in the remote table that contains the row names, even if the input data frame only has natural row names. The default is `row.names = FALSE`. ### Details This function expects a data frame. Use `dbWriteTableArrow()` to write an Arrow object. This function is useful if you want to create and load a table at the same time. Use `dbAppendTable()` or `dbAppendTableArrow()` for appending data to an existing table, `dbCreateTable()` or `dbCreateTableArrow()` for creating a table, and `dbExistsTable()` and `dbRemoveTable()` for overwriting tables. DBI only standardizes writing data frames with `dbWriteTable()`. Some backends might implement methods that can consume CSV files or other data formats. For details, see the documentation for the individual methods. ### Value `dbWriteTable()` returns `TRUE`, invisibly. ### Failure modes If the table exists, and both `append` and `overwrite` arguments are unset, or `append = TRUE` and the data frame with the new data has different column names, an error is raised; the remote table remains unchanged. An error is raised when calling this method for a closed or invalid connection. An error is also raised if `name` cannot be processed with `dbQuoteIdentifier()` or if this results in a non-scalar. Invalid values for the additional arguments `row.names`, `overwrite`, `append`, `field.types`, and `temporary` (non-scalars, unsupported data types, `NA`, incompatible values, duplicate or missing names, incompatible columns) also raise an error. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars[1:5, ]) dbReadTable(con, "mtcars") dbWriteTable(con, "mtcars", mtcars[6:10, ], append = TRUE) dbReadTable(con, "mtcars") dbWriteTable(con, "mtcars", mtcars[1:10, ], overwrite = TRUE) dbReadTable(con, "mtcars") # No row names dbWriteTable(con, "mtcars", mtcars[1:10, ], overwrite = TRUE, row.names = FALSE) dbReadTable(con, "mtcars") ``` ## List remote tables This section describes the behavior of the following method: ``` r dbListTables(conn, ...) ``` ### Description Returns the unquoted names of remote tables accessible through this connection. This should include views and temporary objects, but not all database backends (in particular RMariaDB and RMySQL) support this. ### Arguments | | | |--------|-------------------------------------------------------| | `conn` | A DBIConnection object, as returned by `dbConnect()`. | | `...` | Other parameters passed on to methods. | ### Value `dbListTables()` returns a character vector that enumerates all tables and views in the database. Tables added with `dbWriteTable()` are part of the list. As soon a table is removed from the database, it is also removed from the list of database tables. The same applies to temporary tables if supported by the database. The returned names are suitable for quoting with `dbQuoteIdentifier()`. ### Failure modes An error is raised when calling this method for a closed or invalid connection. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbListTables(con) dbWriteTable(con, "mtcars", mtcars) dbListTables(con) dbDisconnect(con) ``` ## Does a table exist? This section describes the behavior of the following method: ``` r dbExistsTable(conn, name, ...) ``` ### Description Returns if a table given by name exists in the database. ### Arguments
conn

A DBIConnection object, as returned by dbConnect().
name

The table name, passed on to dbQuoteIdentifier(). Options are:

  • a character string with the unquoted DBMS table name, e.g. "table_name",

  • a call to Id() with components to the fully qualified table name, e.g. Id(schema = "my_schema", table = "table_name")

  • a call to SQL() with the quoted and fully qualified table name given verbatim, e.g. SQL('"my_schema"."table_name"')
...

Other parameters passed on to methods.
### Value `dbExistsTable()` returns a logical scalar, `TRUE` if the table or view specified by the `name` argument exists, `FALSE` otherwise. This includes temporary tables if supported by the database. ### Failure modes An error is raised when calling this method for a closed or invalid connection. An error is also raised if `name` cannot be processed with `dbQuoteIdentifier()` or if this results in a non-scalar. ### Specification The `name` argument is processed as follows, to support databases that allow non-syntactic names for their objects: - If an unquoted table name as string: `dbExistsTable()` will do the quoting, perhaps by calling `dbQuoteIdentifier(conn, x = name)` - If the result of a call to `dbQuoteIdentifier()`: no more quoting is done For all tables listed by `dbListTables()`, `dbExistsTable()` returns `TRUE`. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbExistsTable(con, "iris") dbWriteTable(con, "iris", iris) dbExistsTable(con, "iris") dbDisconnect(con) ``` ## Remove a table from the database This section describes the behavior of the following method: ``` r dbRemoveTable(conn, name, ...) ``` ### Description Remove a remote table (e.g., created by `dbWriteTable()`) from the database. ### Arguments
conn

A DBIConnection object, as returned by dbConnect().
name

The table name, passed on to dbQuoteIdentifier(). Options are:

  • a character string with the unquoted DBMS table name, e.g. "table_name",

  • a call to Id() with components to the fully qualified table name, e.g. Id(schema = "my_schema", table = "table_name")

  • a call to SQL() with the quoted and fully qualified table name given verbatim, e.g. SQL('"my_schema"."table_name"')
...

Other parameters passed on to methods.
### Additional arguments The following arguments are not part of the `dbRemoveTable()` generic (to improve compatibility across backends) but are part of the DBI specification: - `temporary` (default: `FALSE`) - `fail_if_missing` (default: `TRUE`) These arguments must be provided as named arguments. If `temporary` is `TRUE`, the call to `dbRemoveTable()` will consider only temporary tables. Not all backends support this argument. In particular, permanent tables of the same name are left untouched. If `fail_if_missing` is `FALSE`, the call to `dbRemoveTable()` succeeds if the table does not exist. ### Specification A table removed by `dbRemoveTable()` doesn't appear in the list of tables returned by `dbListTables()`, and `dbExistsTable()` returns `FALSE`. The removal propagates immediately to other connections to the same database. This function can also be used to remove a temporary table. The `name` argument is processed as follows, to support databases that allow non-syntactic names for their objects: - If an unquoted table name as string: `dbRemoveTable()` will do the quoting, perhaps by calling `dbQuoteIdentifier(conn, x = name)` - If the result of a call to `dbQuoteIdentifier()`: no more quoting is done ### Value `dbRemoveTable()` returns `TRUE`, invisibly. ### Failure modes If the table does not exist, an error is raised. An attempt to remove a view with this function may result in an error. An error is raised when calling this method for a closed or invalid connection. An error is also raised if `name` cannot be processed with `dbQuoteIdentifier()` or if this results in a non-scalar. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbExistsTable(con, "iris") dbWriteTable(con, "iris", iris) dbExistsTable(con, "iris") dbRemoveTable(con, "iris") dbExistsTable(con, "iris") dbDisconnect(con) ``` ## List field names of a remote table This section describes the behavior of the following method: ``` r dbListFields(conn, name, ...) ``` ### Description Returns the field names of a remote table as a character vector. ### Arguments
conn

A DBIConnection object, as returned by dbConnect().
name

The table name, passed on to dbQuoteIdentifier(). Options are:

  • a character string with the unquoted DBMS table name, e.g. "table_name",

  • a call to Id() with components to the fully qualified table name, e.g. Id(schema = "my_schema", table = "table_name")

  • a call to SQL() with the quoted and fully qualified table name given verbatim, e.g. SQL('"my_schema"."table_name"')
...

Other parameters passed on to methods.
### Value `dbListFields()` returns a character vector that enumerates all fields in the table in the correct order. This also works for temporary tables if supported by the database. The returned names are suitable for quoting with `dbQuoteIdentifier()`. ### Failure modes If the table does not exist, an error is raised. Invalid types for the `name` argument (e.g., `character` of length not equal to one, or numeric) lead to an error. An error is also raised when calling this method for a closed or invalid connection. ### Specification The `name` argument can be - a string - the return value of `dbQuoteIdentifier()` - a value from the `table` column from the return value of `dbListObjects()` where `is_prefix` is `FALSE` A column named `row_names` is treated like any other column. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) dbListFields(con, "mtcars") dbDisconnect(con) ``` ## Is this DBMS object still valid? This section describes the behavior of the following method: ``` r dbIsValid(dbObj, ...) ``` ### Description This generic tests whether a database object is still valid (i.e. it hasn't been disconnected or cleared). ### Arguments | | | |---------|------------------------------------------------------------------------------------| | `dbObj` | An object inheriting from DBIObject, i.e. DBIDriver, DBIConnection, or a DBIResult | | `...` | Other arguments to methods. | ### Value `dbIsValid()` returns a logical scalar, `TRUE` if the object specified by `dbObj` is valid, `FALSE` otherwise. A DBIConnection object is initially valid, and becomes invalid after disconnecting with `dbDisconnect()`. For an invalid connection object (e.g., for some drivers if the object is saved to a file and then restored), the method also returns `FALSE`. A DBIResult object is valid after a call to `dbSendQuery()`, and stays valid even after all rows have been fetched; only clearing it with `dbClearResult()` invalidates it. A DBIResult object is also valid after a call to `dbSendStatement()`, and stays valid after querying the number of rows affected; only clearing it with `dbClearResult()` invalidates it. If the connection to the database system is dropped (e.g., due to connectivity problems, server failure, etc.), `dbIsValid()` should return `FALSE`. This is not tested automatically. ### Examples ``` r dbIsValid(RSQLite::SQLite()) con <- dbConnect(RSQLite::SQLite(), ":memory:") dbIsValid(con) rs <- dbSendQuery(con, "SELECT 1") dbIsValid(rs) dbClearResult(rs) dbIsValid(rs) dbDisconnect(con) dbIsValid(con) ``` ## Completion status This section describes the behavior of the following method: ``` r dbHasCompleted(res, ...) ``` ### Description This method returns if the operation has completed. A `SELECT` query is completed if all rows have been fetched. A data manipulation statement is always completed. ### Arguments | | | |-------|---------------------------------------| | `res` | An object inheriting from DBIResult. | | `...` | Other arguments passed on to methods. | ### Value `dbHasCompleted()` returns a logical scalar. For a query initiated by `dbSendQuery()` with non-empty result set, `dbHasCompleted()` returns `FALSE` initially and `TRUE` after calling `dbFetch()` without limit. For a query initiated by `dbSendStatement()`, `dbHasCompleted()` always returns `TRUE`. ### The data retrieval flow This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of `dbBind()` or `dbBindArrow()`, is implemented by `dbGetQuery()`, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendQuery()` to create a result set object of class DBIResult. 2. Optionally, bind query parameters with `dbBind()` or `dbBindArrow()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Optionally, use `dbColumnInfo()` to retrieve the structure of the result set without retrieving actual data. 4. Use `dbFetch()` to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. 5. Use `dbHasCompleted()` to tell when you're done. This method returns `TRUE` if no more rows are available for fetching. 6. Repeat the last four steps as necessary. 7. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### Failure modes Attempting to query completion status for a result set cleared with `dbClearResult()` gives an error. ### Specification The completion status for a query is only guaranteed to be set to `FALSE` after attempting to fetch past the end of the entire result. Therefore, for a query with an empty result set, the initial return value is unspecified, but the result value is `TRUE` after trying to fetch only one row. Similarly, for a query with a result set of length n, the return value is unspecified after fetching n rows, but the result value is `TRUE` after trying to fetch only one more row. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendQuery(con, "SELECT * FROM mtcars") dbHasCompleted(rs) ret1 <- dbFetch(rs, 10) dbHasCompleted(rs) ret2 <- dbFetch(rs) dbHasCompleted(rs) dbClearResult(rs) dbDisconnect(con) ``` ## Get the statement associated with a result set This section describes the behavior of the following method: ``` r dbGetStatement(res, ...) ``` ### Description Returns the statement that was passed to `dbSendQuery()` or `dbSendStatement()`. ### Arguments | | | |-------|---------------------------------------| | `res` | An object inheriting from DBIResult. | | `...` | Other arguments passed on to methods. | ### Value `dbGetStatement()` returns a string, the query used in either `dbSendQuery()` or `dbSendStatement()`. ### Failure modes Attempting to query the statement for a result set cleared with `dbClearResult()` gives an error. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendQuery(con, "SELECT * FROM mtcars") dbGetStatement(rs) dbClearResult(rs) dbDisconnect(con) ``` ## The number of rows fetched so far This section describes the behavior of the following method: ``` r dbGetRowCount(res, ...) ``` ### Description Returns the total number of rows actually fetched with calls to `dbFetch()` for this result set. ### Arguments | | | |-------|---------------------------------------| | `res` | An object inheriting from DBIResult. | | `...` | Other arguments passed on to methods. | ### Value `dbGetRowCount()` returns a scalar number (integer or numeric), the number of rows fetched so far. After calling `dbSendQuery()`, the row count is initially zero. After a call to `dbFetch()` without limit, the row count matches the total number of rows returned. Fetching a limited number of rows increases the number of rows by the number of rows returned, even if fetching past the end of the result set. For queries with an empty result set, zero is returned even after fetching. For data manipulation statements issued with `dbSendStatement()`, zero is returned before and after calling `dbFetch()`. ### Failure modes Attempting to get the row count for a result set cleared with `dbClearResult()` gives an error. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendQuery(con, "SELECT * FROM mtcars") dbGetRowCount(rs) ret1 <- dbFetch(rs, 10) dbGetRowCount(rs) ret2 <- dbFetch(rs) dbGetRowCount(rs) nrow(ret1) + nrow(ret2) dbClearResult(rs) dbDisconnect(con) ``` ## The number of rows affected This section describes the behavior of the following method: ``` r dbGetRowsAffected(res, ...) ``` ### Description This method returns the number of rows that were added, deleted, or updated by a data manipulation statement. ### Arguments | | | |-------|---------------------------------------| | `res` | An object inheriting from DBIResult. | | `...` | Other arguments passed on to methods. | ### Value `dbGetRowsAffected()` returns a scalar number (integer or numeric), the number of rows affected by a data manipulation statement issued with `dbSendStatement()`. The value is available directly after the call and does not change after calling `dbFetch()`. `NA_integer_` or `NA_numeric_` are allowed if the number of rows affected is not known. For queries issued with `dbSendQuery()`, zero is returned before and after the call to `dbFetch()`. `NA` values are not allowed. ### The command execution flow This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of `dbBindArrow()`, is implemented by `dbExecute()`, which should be sufficient for non-parameterized queries. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendStatement()` to create a result set object of class DBIResult. For some queries you need to pass `immediate = TRUE`. 2. Optionally, bind query parameters with`dbBind()` or `dbBindArrow()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Optionally, use `dbGetRowsAffected()` to retrieve the number of rows affected by the query. 4. Repeat the last two steps as necessary. 5. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### Failure modes Attempting to get the rows affected for a result set cleared with `dbClearResult()` gives an error. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "mtcars", mtcars) rs <- dbSendStatement(con, "DELETE FROM mtcars") dbGetRowsAffected(rs) nrow(mtcars) dbClearResult(rs) dbDisconnect(con) ``` ## Information about result types This section describes the behavior of the following method: ``` r dbColumnInfo(res, ...) ``` ### Description Produces a data.frame that describes the output of a query. The data.frame should have as many rows as there are output fields in the result set, and each column in the data.frame describes an aspect of the result set field (field name, type, etc.) ### Arguments | | | |-------|---------------------------------------| | `res` | An object inheriting from DBIResult. | | `...` | Other arguments passed on to methods. | ### Value `dbColumnInfo()` returns a data frame with at least two columns `"name"` and `"type"` (in that order) (and optional columns that start with a dot). The `"name"` and `"type"` columns contain the names and types of the R columns of the data frame that is returned from `dbFetch()`. The `"type"` column is of type `character` and only for information. Do not compute on the `"type"` column, instead use `dbFetch(res, n = 0)` to create a zero-row data frame initialized with the correct data types. ### The data retrieval flow This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames. Most of this flow, except repeated calling of `dbBind()` or `dbBindArrow()`, is implemented by `dbGetQuery()`, which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by `dbConnect()`. See also `vignette("dbi-advanced")` for a walkthrough. 1. Use `dbSendQuery()` to create a result set object of class DBIResult. 2. Optionally, bind query parameters with `dbBind()` or `dbBindArrow()`. This is required only if the query contains placeholders such as `⁠?⁠` or `⁠\$1⁠`, depending on the database backend. 3. Optionally, use `dbColumnInfo()` to retrieve the structure of the result set without retrieving actual data. 4. Use `dbFetch()` to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards. 5. Use `dbHasCompleted()` to tell when you're done. This method returns `TRUE` if no more rows are available for fetching. 6. Repeat the last four steps as necessary. 7. Use `dbClearResult()` to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use `on.exit()` or `withr::defer()` to ensure that this step is always executed. ### Failure modes An attempt to query columns for a closed result set raises an error. ### Specification A column named `row_names` is treated like any other column. The column names are always consistent with the data returned by `dbFetch()`. If the query returns unnamed columns, non-empty and non-`NA` names are assigned. Column names that correspond to SQL or R keywords are left unchanged. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") rs <- dbSendQuery(con, "SELECT 1 AS a, 2 AS b") dbColumnInfo(rs) dbFetch(rs) dbClearResult(rs) dbDisconnect(con) ``` ## Begin/commit/rollback SQL transactions This section describes the behavior of the following methods: ``` r dbBegin(conn, ...) dbCommit(conn, ...) dbRollback(conn, ...) ``` ### Description A transaction encapsulates several SQL statements in an atomic unit. It is initiated with `dbBegin()` and either made persistent with `dbCommit()` or undone with `dbRollback()`. In any case, the DBMS guarantees that either all or none of the statements have a permanent effect. This helps ensuring consistency of write operations to multiple tables. ### Arguments | | | |--------|-------------------------------------------------------| | `conn` | A DBIConnection object, as returned by `dbConnect()`. | | `...` | Other parameters passed on to methods. | ### Details Not all database engines implement transaction management, in which case these methods should not be implemented for the specific DBIConnection subclass. ### Value `dbBegin()`, `dbCommit()` and `dbRollback()` return `TRUE`, invisibly. ### Failure modes The implementations are expected to raise an error in case of failure, but this is not tested. In any way, all generics throw an error with a closed or invalid connection. In addition, a call to `dbCommit()` or `dbRollback()` without a prior call to `dbBegin()` raises an error. Nested transactions are not supported by DBI, an attempt to call `dbBegin()` twice yields an error. ### Specification Actual support for transactions may vary between backends. A transaction is initiated by a call to `dbBegin()` and committed by a call to `dbCommit()`. Data written in a transaction must persist after the transaction is committed. For example, a record that is missing when the transaction is started but is created during the transaction must exist both during and after the transaction, and also in a new connection. A transaction can also be aborted with `dbRollback()`. All data written in such a transaction must be removed after the transaction is rolled back. For example, a record that is missing when the transaction is started but is created during the transaction must not exist anymore after the rollback. Disconnection from a connection with an open transaction effectively rolls back the transaction. All data written in such a transaction must be removed after the transaction is rolled back. The behavior is not specified if other arguments are passed to these functions. In particular, RSQLite issues named transactions with support for nesting if the `name` argument is set. The transaction isolation level is not specified by DBI. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cash", data.frame(amount = 100)) dbWriteTable(con, "account", data.frame(amount = 2000)) # All operations are carried out as logical unit: dbBegin(con) withdrawal <- 300 dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) dbCommit(con) dbReadTable(con, "cash") dbReadTable(con, "account") # Rolling back after detecting negative value on account: dbBegin(con) withdrawal <- 5000 dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) if (dbReadTable(con, "account")\$amount >= 0) { dbCommit(con) } else { dbRollback(con) } dbReadTable(con, "cash") dbReadTable(con, "account") dbDisconnect(con) ``` ## Self-contained SQL transactions This section describes the behavior of the following methods: ``` r dbWithTransaction(conn, code, ...) dbBreak() ``` ### Description Given that transactions are implemented, this function allows you to pass in code that is run in a transaction. The default method of `dbWithTransaction()` calls `dbBegin()` before executing the code, and `dbCommit()` after successful completion, or `dbRollback()` in case of an error. The advantage is that you don't have to remember to do `dbBegin()` and `dbCommit()` or `dbRollback()` – that is all taken care of. The special function `dbBreak()` allows an early exit with rollback, it can be called only inside `dbWithTransaction()`. ### Arguments | | | |--------|-------------------------------------------------------| | `conn` | A DBIConnection object, as returned by `dbConnect()`. | | `code` | An arbitrary block of R code. | | `...` | Other parameters passed on to methods. | ### Details DBI implements `dbWithTransaction()`, backends should need to override this generic only if they implement specialized handling. ### Value `dbWithTransaction()` returns the value of the executed code. ### Failure modes Failure to initiate the transaction (e.g., if the connection is closed or invalid of if `dbBegin()` has been called already) gives an error. ### Specification `dbWithTransaction()` initiates a transaction with `dbBegin()`, executes the code given in the `code` argument, and commits the transaction with `dbCommit()`. If the code raises an error, the transaction is instead aborted with `dbRollback()`, and the error is propagated. If the code calls `dbBreak()`, execution of the code stops and the transaction is silently aborted. All side effects caused by the code (such as the creation of new variables) propagate to the calling environment. ### Examples ``` r con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cash", data.frame(amount = 100)) dbWriteTable(con, "account", data.frame(amount = 2000)) # All operations are carried out as logical unit: dbWithTransaction( con, { withdrawal <- 300 dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) } ) # The code is executed as if in the current environment: withdrawal # The changes are committed to the database after successful execution: dbReadTable(con, "cash") dbReadTable(con, "account") # Rolling back with dbBreak(): dbWithTransaction( con, { withdrawal <- 5000 dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) if (dbReadTable(con, "account")\$amount < 0) { dbBreak() } } ) # These changes were not committed to the database: dbReadTable(con, "cash") dbReadTable(con, "account") dbDisconnect(con) ``` ## Get DBMS metadata This section describes the behavior of the following method: ``` r dbGetInfo(dbObj, ...) ``` ### Description Retrieves information on objects of class DBIDriver, DBIConnection or DBIResult. ### Arguments | | | |---------|------------------------------------------------------------------------------------| | `dbObj` | An object inheriting from DBIObject, i.e. DBIDriver, DBIConnection, or a DBIResult | | `...` | Other arguments to methods. | ### Value For objects of class DBIDriver, `dbGetInfo()` returns a named list that contains at least the following components: - `driver.version`: the package version of the DBI backend, - `client.version`: the version of the DBMS client library. For objects of class DBIConnection, `dbGetInfo()` returns a named list that contains at least the following components: - `db.version`: version of the database server, - `dbname`: database name, - `username`: username to connect to the database, - `host`: hostname of the database server, - `port`: port on the database server. It must not contain a `password` component. Components that are not applicable should be set to `NA`. For objects of class DBIResult, `dbGetInfo()` returns a named list that contains at least the following components: - `statatment`: the statement used with `dbSendQuery()` or `dbExecute()`, as returned by `dbGetStatement()`, - `row.count`: the number of rows fetched so far (for queries), as returned by `dbGetRowCount()`, - `rows.affected`: the number of rows affected (for statements), as returned by `dbGetRowsAffected()` - `has.completed`: a logical that indicates if the query or statement has completed, as returned by `dbHasCompleted()`. ### Implementation notes The default implementation for `⁠DBIResult objects⁠` constructs such a list from the return values of the corresponding methods, `dbGetStatement()`, `dbGetRowCount()`, `dbGetRowsAffected()`, and `dbHasCompleted()`. ### Examples ``` r dbGetInfo(RSQLite::SQLite()) ``` DBI/vignettes/DBI-proposal.Rmd0000644000176200001440000006640614602466070015600 0ustar liggesusers--- title: "A Common Interface to Relational Databases from R and S -- A Proposal" author: "David James" date: "March 16, 2000" output: rmarkdown::html_vignette bibliography: biblio.bib vignette: > %\VignetteIndexEntry{A Common Interface to Relational Databases from R and S -- A Proposal} %\VignetteEngine{knitr::rmarkdown} --- For too long S and similar data analysis environments have lacked good interfaces to relational database systems (RDBMS). For the last twenty years or so these RDBMS have evolved into highly optimized client-server systems for data storage and manipulation, and currently they serve as repositories for most of the business, industrial, and research “raw” data that analysts work with. Other analysis packages, such as SAS, have traditionally provided good data connectivity, but S and GNU R have relied on intermediate text files as means of importing data (but see @R.imp-exp and @R-dbms.) Although this simple approach works well for relatively modest amounts of mostly static data, it does not scale up to larger amounts of data distributed over machines and locations, nor does it scale up to data that is highly dynamic – situations that are becoming increasingly common. We want to propose a common interface between R/S and RDBMS that would allow users to access data stored on database servers in a uniform and predictable manner irrespective of the database engine. The interface defines a small set of classes and methods similar in spirit to Python’s DB-API, Java’s JDBC, Microsoft’s ODBC, Perl’s DBI, etc., but it conforms to the “whole-object” philosophy so natural in S and R. # Computing with Distributed Data {#sec:distr} As data analysts, we are increasingly faced with the challenge of larger data sources distributed over machines and locations; most of these data sources reside in relational database management systems (RDBMS). These relational databases represent a mature client-server distributed technology that we as analysts could be exploiting more that we’ve done in the past. The relational technology provides a well-defined standard, the ANSI SQL-92 @sql92, both for defining and manipulating data in a highly optimized fashion from virtually any application. In contrast, S and Splus have provided somewhat limited tools for coping with the challenges of larger and distributed data sets (Splus does provide an `import` function to import from databases, but it is quite limited in terms of SQL facilities). The R community has been more resourceful and has developed a number of good libraries for connecting to mSQL, MySQL, PostgreSQL, and ODBC; each library, however, has defined its own interface to each database engine a bit differently. We think it would be to everybody’s advantage to coordinate the definition of a common interface, an effort not unlike those taken in the Python and Perl communities. The goal of a common, seamless access to distributed data is a modest one in our evolution towards a fully distributed computing environment. We recognize the greater goal of distributed computing as the means to fully integrate diverse systems – not just databases – into a truly flexible analysis environment. Good connectivity to databases, however, is of immediate necessity both in practical terms and as a means to help us transition from monolithic, self-contained systems to those in which computations, not only the data, can be carried out in parallel over a wide number of computers and/or systems @duncan2000. Issues of reliability, security, location transparency, persistence, etc., will be new to most of us and working with distributed data may provide a more gradual change to ease in the ultimate goal of full distributed computing. # A Common Interface {#sec:rs-dbi} We believe that a common interface to databases can help users easily access data stored in RDBMS. A common interface would describe, in a uniform way, how to connect to RDBMS, extract meta-data (such as list of available databases, tables, etc.) as well as a uniform way to execute SQL statements and import their output into R and S. The current emphasis is on querying databases and not so much in a full low-level interface for database development as in JDBC or ODBC, but unlike these, we want to approach the interface from the “whole-object” perspective @S4 so natural to R/S and Python – for instance, by fetching all fields and records simultaneously into a single object. The basic idea is to split the interface into a front-end consisting of a few classes and generic functions that users invoke and a back-end set of database-specific classes and methods that implement the actual communication. (This is a very well-known pattern in software engineering, and another good verbatim is the device-independent graphics in R/S where graphics functions produce similar output on a variety of different devices, such X displays, Postscript, etc.) The following verbatim shows the front-end: ``` > mgr <- dbManager("Oracle") > con <- dbConnect(mgr, user = "user", passwd = "passwd") > rs <- dbExecStatement(con, "select fld1, fld2, fld3 from MY_TABLE") > tbls <- fetch(rs, n = 100) > hasCompleted(rs) [1] T > close(rs) > rs <- dbExecStatement(con, "select id_name, q25, q50 from liv2") > res <- fetch(rs) > getRowCount(rs) [1] 73 > close(con) ``` Such scripts should work with other RDBMS (say, MySQL) by replacing the first line with ``` > mgr <- dbManager("MySQL") ``` ## Interface Classes {#sec:rs-dbi-classes} The following are the main RS-DBI classes. They need to be extended by individual database back-ends (MySQL, Oracle, etc.) `dbManager` : Virtual class[^2] extended by actual database managers, e.g., Oracle, MySQL, Informix. `dbConnection` : Virtual class that captures a connection to a database instance[^3]. `dbResult` : Virtual class that describes the result of an SQL statement. `dbResultSet` : Virtual class, extends `dbResult` to fully describe the output of those statements that produce output records, i.e., `SELECT` (or `SELECT`-like) SQL statement. All these classes should implement the methods `show`, `describe`, and `getInfo`: `show` : (`print` in R) prints a one-line identification of the object. `describe` : prints a short summary of the meta-data of the specified object (like `summary` in R/S). `getInfo` : takes an object of one of the above classes and a string specifying a meta-data item, and it returns the corresponding information (`NULL` if unavailable). > mgr <- dbManager("MySQL") > getInfo(mgr, "version") > con <- dbConnect(mgr, ...) > getInfo(con, "type") The reason we implement the meta-data through `getInfo` in this way is to simplify the writing of database back-ends. We don’t want to overwhelm the developers of drivers (ourselves, most likely) with hundreds of methods as in the case of JDBC. In addition, the following methods should also be implemented: `getDatabases` : lists all available databases known to the `dbManager`. `getTables` : lists tables in a database. `getTableFields` : lists the fields in a table in a database. `getTableIndices` : lists the indices defined for a table in a database. These methods may be implemented using the appropriate `getInfo` method above. In the next few sections we describe in detail each of these classes and their methods. ### Class `dbManager` {#sec:dbManager} This class identifies the relational database management system. It needs to be extended by individual back-ends (Oracle, PostgreSQL, etc.) The `dbManager` class defines the following methods: `load` : initializes the driver code. We suggest having the generator, `dbManager(driver)`, automatically load the driver. `unload` : releases whatever resources the driver is using. `getVersion` : returns the version of the RS-DBI currently implemented, plus any other relevant information about the implementation itself and the RDBMS being used. ### Class `dbConnection` {#sec:dbConnection} This virtual class captures a connection to a RDBMS, and it provides access to dynamic SQL, result sets, RDBMS session management (transactions), etc. Note that the `dbManager` may or may not allow multiple simultaneous connections. The methods it defines include: `dbConnect` : opens a connection to the database `dbname`. Other likely arguments include `host`, `user`, and `password`. It returns an object that extends `dbConnection` in a driver-specific manner (e.g., the MySQL implementation creates a connection of class `MySQLConnection` that extends `dbConnection`). Note that we could separate the steps of connecting to a RDBMS and opening a database there (i.e., opening an *instance*). For simplicity we do the 2 steps in this method. If the user needs to open another instance in the same RDBMS, just open a new connection. `close` : closes the connection and discards all pending work. `dbExecStatement` : submits one SQL statement. It returns a `dbResult` object, and in the case of a `SELECT` statement, the object also inherits from `dbResultSet`. This `dbResultSet` object is needed for fetching the output rows of `SELECT` statements. The result of a non-`SELECT` statement (e.g., `UPDATE, DELETE, CREATE, ALTER`, ...) is defined as the number of rows affected (this seems to be common among RDBMS). `commit` : commits pending transaction (optional). `rollback` : undoes current transaction (optional). `callProc` : invokes a stored procedure in the RDBMS (tentative). Stored procedures are *not* part of the ANSI SQL-92 standard and possibly vary substantially from one RDBMS to another. For instance, Oracle seems to have a fairly decent implementation of stored procedures, but MySQL currently does not support them. `dbExec` : submit an SQL “script” (multiple statements). May be implemented by looping with `dbExecStatement`. `dbNextResultSet` : When running SQL scripts (multiple statements), it closes the current result set in the `dbConnection`, executes the next statement and returns its result set. ### Class `dbResult` {#sec:dbResult} This virtual class describes the result of an SQL statement (any statement) and the state of the operation. Non-query statements (e.g., `CREATE`, `UPDATE`, `DELETE`) set the “completed” state to 1, while `SELECT` statements to 0. Error conditions set this slot to a negative number. The `dbResult` class defines the following methods: `getStatement` : returns the SQL statement associated with the result set. `getDBConnection` : returns the `dbConnection` associated with the result set. `getRowsAffected` : returns the number of rows affected by the operation. `hasCompleted` : was the operation completed? `SELECT`’s, for instance, are not completed until their output rows are all fetched. `getException` : returns the status of the last SQL statement on a given connection as a list with two members, status code and status description. ### Class `dbResultSet` {#sec:dbResultSet} This virtual class extends `dbResult`, and it describes additional information from the result of a `SELECT` statement and the state of the operation. The `completed` state is set to 0 so long as there are pending rows to fetch. The `dbResultSet` class defines the following additional methods: `getRowCount` : returns the number of rows fetched so far. `getNullOk` : returns a logical vector with as many elements as there are fields in the result set, each element describing whether the corresponding field accepts `NULL` values. `getFields` : describes the `SELECT`ed fields. The description includes field names, RDBMS internal data types, internal length, internal precision and scale, null flag (i.e., column allows `NULL`’s), and corresponding S classes (which can be over-ridden with user-provided classes). The current MySQL and Oracle implementations define a `dbResultSet` as a named list with the following elements: `connection`: : the connection object associated with this result set; `statement`: : a string with the SQL statement being processed; `description`: : a field description `data.frame` with as many rows as there are fields in the `SELECT` output, and columns specifying the `name`, `type`, `length`, `precision`, `scale`, `Sclass` of the corresponding output field. `rowsAffected`: : the number of rows that were affected; `rowCount`: : the number of rows so far fetched; `completed`: : a logical value describing whether the operation has completed or not. `nullOk`: : a logical vector specifying whether the corresponding column may take NULL values. The methods above are implemented as accessor functions to this list in the obvious way. `setDataMappings` : defines a conversion between internal RDBMS data types and R/S classes. We expect the default mappings to be by far the most common ones, but users that need more control may specify a class generator for individual fields in the result set. (See Section [sec:mappings] for details.) `close` : closes the result set and frees resources both in R/S and the RDBMS. `fetch` : extracts the next `max.rec` records (-1 means all). ## Data Type Mappings {#sec:mappings} The data types supported by databases are slightly different than the data types in R and S, but the mapping between them is straightforward: Any of the many fixed and varying length character types are mapped to R/S `character`. Fixed-precision (non-IEEE) numbers are mapped into either doubles (`numeric`) or long (`integer`). Dates are mapped to character using the appropriate `TO_CHAR` function in the RDBMS (which should take care of any locale information). Some RDBMS support the type `CURRENCY` or `MONEY` which should be mapped to `numeric`. Large objects (character, binary, file, etc.) also need to be mapped. User-defined functions may be specified to do the actual conversion as follows: 1. run the query (either with `dbExec` or `dbExecStatement`): > rs <- dbExecStatement(con, "select whatever-You-need") 2. extract the output field definitions > flds <- getFields(rs) 3. replace the class generator in the, say 3rd field, by the user own generator: > flds[3, "Sclass"] # default mapping [1] "character" by > flds[3, "Sclass"] <- "myOwnGeneratorFunction" 4. set the new data mapping prior to fetching > setDataMappings(resutlSet, flds) 5. fetch the rows and store in a `data.frame` > data <- fetch(resultSet) ## Open Issues {#sec:open-issues} We may need to provide some additional utilities, for instance to convert dates, to escape characters such as quotes and slashes in query strings, to strip excessive blanks from some character fields, etc. We need to decide whether we provide hooks so these conversions are done at the C level, or do all the post-processing in R or S. Another issue is what kind of data object is the output of an SQL query. Currently the MySQL and Oracle implementations return data as a `data.frame`; data frames have the slight inconvenience that they automatically re-label the fields according to R/S syntax, changing the actual RDBMS labels of the variables; the issue of non-numeric data being coerced into factors automatically “at the drop of a hat” (as someone in s-news wrote) is also annoying. The execution of SQL scripts is not fully described. The method that executes scripts could run individual statements without returning until it encounters a query (`SELECT`-like) statement. At that point it could return that one result set. The application is then responsible for fetching these rows, and then for invoking `dbNextResultSet` on the opened `dbConnection` object to repeat the `dbExec`/`fetch` loop until it encounters the next `dbResultSet`. And so on. Another (potentially very expensive) alternative would be to run all statements sequentially and return a list of `data.frame`s, each element of the list storing the result of each statement. Binary objects and large objects present some challenges both to R and S. It is becoming more common to store images, sounds, and other data types as binary objects in RDBMS, some of which can be in principle quite large. The SQL-92 ANSI standard allows up to 2 gigabytes for some of these objects. We need to carefully plan how to deal with binary objects – perhaps tentatively not in full generality. Large objects could be fetched by repeatedly invoking a specified R/S function that takes as argument chunks of a specified number of raw bytes. In the case of S4 (and Splus5.x) the RS-DBI implementation can write into an opened connection for which the user has defined a reader (but can we guarantee that we won’t overflow the connection?). In the case of R it is not clear what data type binary large objects (BLOB) should be mapped into. ## Limitations {#sec:limitations} These are some of the limitations of the current interface definition: - we only allow one SQL statement at a time, forcing users to split SQL scripts into individual statements; - transaction management is not fully described; - the interface is heavily biased towards queries, as opposed to general purpose database development. In particular we made no attempt to define “bind variables”; this is a mechanism by which the contents of S objects are implicitly moved to the database during SQL execution. For instance, the following embedded SQL statement /* SQL */ SELECT * from emp_table where emp_id = :sampleEmployee would take the vector `sampleEmployee` and iterate over each of its elements to get the result. Perhaps RS-DBI could at some point in the future implement this feature. # Other Approaches The high-level, front-end description of RS-DBI is the more critical aspect of the interface. Details on how to actually implement this interface may change over time. The approach described in this document based on one back-end driver per RDBMS is reasonable, but not the only approach – we simply felt that a simpler approach based on well-understood and self-contained tools (R, S, and C API’s) would be a better start. Nevertheless we want to briefly mention a few alternatives that we considered and tentatively decided against, but may quite possibly re-visit in the near future. ## Open Database Connectivity (ODBC) {#sec:odbc} The ODBC protocol was developed by Microsoft to allow connectivity among C/C++ applications and RDBMS. As you would expect, originally implementations of the ODBC were only available under Windows environments. There are various effort to create a Unix implementation (see [the Unix ODBC](https://www.unixodbc.org/) web-site and @odbc.lj). This approach looks promising because it allows us to write only one back-end, instead of one per RDBMS. Since most RDBMS already provide ODBC drivers, this could greatly simplify development. Unfortunately, the Unix implementation of ODBC was not mature enough at the time we looked at it, a situation we expect will change in the next year or so. At that point we will need to re-evaluate it to make sure that such an ODBC interface does not penalize the interface in terms of performance, ease of use, portability among the various Unix versions, etc. ## Java Database Connectivity (JDBC) {#sec:jdbc} Another protocol, the Java database connectivity, is very well-done and supported by just about every RDBMS. The issue with JDBC is that as of today neither S nor R (which are written in C) interfaces cleanly with Java. There are several efforts (some in a quite fairly advanced state) to allow S and R to invoke Java methods. Once this interface is widely available in Splus5x and R we will need to re-visit this issue again and study the performance, usability, etc., of JDBC as a common back-end to the RS-DBI. ## CORBA and a 3-tier Architecture {#sec:corba} Yet another approach is to move the interface to RDBMS out of R and S altogether into a separate system or server that would serve as a proxy between R/S and databases. The communication to this middle-layer proxy could be done through CORBA [@s-corba.98, @corba:siegel.96], Java’s RMI, or some other similar technology. Such a design could be very flexible, but the CORBA facilities both in R and S are not widely available yet, and we do not know whether this will be made available to Splus5 users from MathSoft. Also, my experience with this technology is rather limited. On the other hand, this 3-tier architecture seem to offer the most flexibility to cope with very large distributed databases, not necessarily relational. # Resources {#sec:resources} The latest documentation and software on the RS-DBI was available at www.omegahat.net (link dead now: `https://www.omegahat.net/contrib/RS-DBI/index.html`). The R community has developed interfaces to some databases: [RmSQL](https://cran.r-project.org/src/contrib/Archive/RmSQL/) is an interface to the [mSQL](https://www.hughes.com.au/) database written by Torsten Hothorn; [RPgSQL](https://sites.cns.utexas.edu/keittlab/software-0) is an interface to [PostgreSQL](https://www.postgreSQL.org) and was written by Timothy H. Keitt; [RODBC](https://www.stats.ox.ac.uk/pub/bdr/) is an interface to ODBC, and it was written by [Michael Lapsley](mailto:mlapsley@sthelier.sghms.ac.uk). (For more details on all these see @R.imp-exp.) The are R and S-Plus interfaces to [MySQL](https://dev.mysql.com/) that follow the propose RS-DBI API described here; also, there’s an S-Plus interface SOracle @RS-Oracle to Oracle (we expect to have an R implementation soon.) The idea of a common interface to databases has been successfully implemented in Java’s Database Connectivity (JDBC) ([www.javasoft.com](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/)), in C through the Open Database Connectivity (ODBC) ([www.unixodbc.org](https://www.unixodbc.org/)), in Python’s Database Application Programming Interface ([www.python.org](https://www.python.org)), and in Perl’s Database Interface ([www.cpan.org](https://www.cpan.org)). # Acknowledgements The R/S database interface came about from suggestions, comments, and discussions with [John M. Chambers](mailto:jmc@research.bell-labs.com) and [Duncan Temple Lang](mailto:duncan@research.bell-labs.com) in the context of the Omega Project for Statistical Computing. [Doug Bates](mailto:bates@stat.wisc.edu) and [Saikat DebRoy](mailto:saikat@stat.wisc.edu) ported (and greatly improved) the first MySQL implementation to R. # The S Version 4 Definitions The following code is meant to serve as a detailed description of the R/S to database interface. We decided to use S4 (instead of R or S version 3) because its clean syntax help us to describe easily the classes and methods that form the RS-DBI, and also to convey the inter-class relationships. ```R ## Define all the classes and methods to be used by an ## implementation of the RS-DataBase Interface. Mostly, ## these classes are virtual and each driver should extend ## them to provide the actual implementation. ## Class: dbManager ## This class identifies the DataBase Management System ## (Oracle, MySQL, Informix, PostgreSQL, etc.) setClass("dbManager", VIRTUAL) setGeneric("load", def = function(dbMgr,...) standardGeneric("load") ) setGeneric("unload", def = function(dbMgr,...) standardGeneric("unload") ) setGeneric("getVersion", def = function(dbMgr,...) standardGeneric("getVersion") ) ## Class: dbConnections ## This class captures a connection to a database instance. setClass("dbConnection", VIRTUAL) setGeneric("dbConnection", def = function(dbMgr, ...) standardGeneric("dbConnection") ) setGeneric("dbConnect", def = function(dbMgr, ...) standardGeneric("dbConnect") ) setGeneric("dbExecStatement", def = function(con, statement, ...) standardGeneric("dbExecStatement") ) setGeneric("dbExec", def = function(con, statement, ...) standardGeneric("dbExec") ) setGeneric("getResultSet", def = function(con, ..) standardGeneric("getResultSet") ) setGeneric("commit", def = function(con, ...) standardGeneric("commit") ) setGeneric("rollback", def = function(con, ...) standardGeneric("rollback") ) setGeneric("callProc", def = function(con, ...) standardGeneric("callProc") ) setMethod("close", signature = list(con="dbConnection", type="missing"), def = function(con, type) NULL ) ## Class: dbResult ## This is a base class for arbitrary results from the RDBMS ## (INSERT, UPDATE, DELETE). SELECTs (and SELECT-like) ## statements produce "dbResultSet" objects, which extend ## dbResult. setClass("dbResult", VIRTUAL) setMethod("close", signature = list(con="dbResult", type="missing"), def = function(con, type) NULL ) ## Class: dbResultSet ## Note that we define a resultSet as the result of a ## SELECT SQL statement. setClass("dbResultSet", "dbResult") setGeneric("fetch", def = function(resultSet,n,...) standardGeneric("fetch") ) setGeneric("hasCompleted", def = function(object, ...) standardGeneric("hasCompleted") ) setGeneric("getException", def = function(object, ...) standardGeneric("getException") ) setGeneric("getDBconnection", def = function(object, ...) standardGeneric("getDBconnection") ) setGeneric("setDataMappings", def = function(resultSet, ...) standardGeneric("setDataMappings") ) setGeneric("getFields", def = function(object, table, dbname, ...) standardGeneric("getFields") ) setGeneric("getStatement", def = function(object, ...) standardGeneric("getStatement") ) setGeneric("getRowsAffected", def = function(object, ...) standardGeneric("getRowsAffected") ) setGeneric("getRowCount", def = function(object, ...) standardGeneric("getRowCount") ) setGeneric("getNullOk", def = function(object, ...) standardGeneric("getNullOk") ) ## Meta-data: setGeneric("getInfo", def = function(object, ...) standardGeneric("getInfo") ) setGeneric("describe", def = function(object, verbose=F, ...) standardGeneric("describe") ) setGeneric("getCurrentDatabase", def = function(object, ...) standardGeneric("getCurrentDatabase") ) setGeneric("getDatabases", def = function(object, ...) standardGeneric("getDatabases") ) setGeneric("getTables", def = function(object, dbname, ...) standardGeneric("getTables") ) setGeneric("getTableFields", def = function(object, table, dbname, ...) standardGeneric("getTableFields") ) setGeneric("getTableIndices", def = function(object, table, dbname, ...) standardGeneric("getTableIndices") ) ``` [^2]: A virtual class allows us to group classes that share some common functionality, e.g., the virtual class “`dbConnection`” groups all the connection implementations by Informix, Ingres, DB/2, Oracle, etc. Although the details will vary from one RDBMS to another, the defining characteristic of these objects is what a virtual class captures. R and S version 3 do not explicitly define virtual classes, but they can easily implement the idea through inheritance. [^3]: The term “database” is sometimes (confusingly) used both to denote the RDBMS, such as Oracle, MySQL, and also to denote a particular database instance under a RDBMS, such as “opto” or “sales” databases under the same RDBMS. DBI/vignettes/biblio.bib0000644000176200001440000001772214350241735014613 0ustar liggesusers@string{jcgs="Journal of Computational and Graphical Statistics"} @inproceedings{s-corba.98, author = "Chambers, John M. and Hansen, Mark H. and James, David A. and Temple Lang, Duncan", title = "Distributed Computing with Data: A CORBA-based Approach", booktitle = "Computing Science and Statistics", year = 1998, organization = "Inteface Foundation of North America" } @book{S.88, author = "Becker, R. A. and Chambers, J. M. and Wilks, A. R", year = "1988", title = "The New S Language", publisher = "Wadsworth", address = "Pacific Grove, California" } @book{S.92, editor = "Chambers, J. M. and Hastie, T.", year = 1992, title = "Statistical Models in S", publisher = "Wadsworth", address = "Pacific Grove, California" } @book{S4, author = "Chambers, J. M.", title = "Programming with Data: A Guide to the S Language", publisher = "Springer", address = "New York", year = 1998 } @article{R.96, author = "Ihaka, Ross and Gentleman, Robert", title = "R: A Language for Data Analysis and Graphics", journal = jcgs, volume = 5, number = 3, year = 1996, pages = "299-314" } @book{corba:siegel.96, author = "Siegel, Jon", title = "CORBA Fundamentals and Programming", publisher = "Wiley", address = "New York", year = 1996 } @book{pvm, title = "PVM: Parallel Virtual Machine. A User's Guide and Tutorial for Networked Parallel Computing", author="Geist, A. and Beguelin, A. and Dongarra, J. and Jiang, W. and Mancheck, R. and Sunderam, V.", year = 1994, publisher = "MIT Press", address = "Cambridge, MA" } @manual{splus, title = "S-PLUS Software Documentation", key = "S-PLUS", organization = "StatSci Division of MathSoft Inc.", note = "Version 3.3", year = 1995, address = "Seattle, WA", } @book{tierney.90, author = "Tierney, Luke", year = 1990, title = "LISP-STAT: An Object-Oriented Environment for Statistical Computing and Dynamic Graphics", publisher = "Wiley", address = "New York" } @article{tierney.96, author = "Tierney, Luke", title = "Recent Development and Future Directions in {LispStat}", journal = jcgs, volume = 5, number = 3, year = 1996, pages = "250-262" } @article{odbc.lj, author = "Harvey, Peter", title = "{Open Database Connectivity}", journal = "{Linux Journal}", year = 1999, volume = "Nov.", number = 67, pages = "68-72" } @article{duncan2000, author = "Temple Lang, Duncan", title = "{The Omegahat Environment: New Possibilities for Statistical Computing}", journal = jcgs, volume = "to appear", year = 2000, number = "" } @manual{sql92, title = "{X/Open CAE Specification: SQL and RDA}", organization = "X/Open Company Ltd.", address = "Reading, UK", year = 1994 } @book{MySQL, author = "DuBois, Paul", title = "{MySQL}", publisher = "New Riders Publishing", year = 2000 } @manual{R.ext, title = "Writing {R} Extensions", organization = "{R} Development Core Team", note = "Version 1.2.1 (2001-01-15)", year = 2001 } @manual{R.imp-exp, title = "{R} Data Import/Export", organization = "R-Development Core Team", note = "Version 1.2.1 (2001-01-15)", year = 2001 } @manual{R-dbms, title = "Using Relational Database Systems with {R}", organization = "R-Developemt Core Team", note = "Draft", year = 2000 } @manual{bates.mysql, title = "Using Relational Database Systems with {R}", organization = "R-Developemt Core Team", note = "Draft", year = 2000 } @techreport{proxyDBMS, author = "James, David A.", title = "Proxy Database Object in the S Language", institution = "Bell Labs, Lucent Technologies", year = "In preparation" } @techreport{RS-DBI, author = "James, David A.", title = "A Common Interface to Relational Database Management Sysmtems from {R} and {S} --- A Proposal", institution = "Bell Labs, Lucent Technologies", year = "2000", address = "www.omegahat.org" } @techreport{RS-MySQL, author = "James, David A.", title = "An {R}/{S} Interface to the {MySQL} Database", institution = "Bell Labs, Lucent Technologies", year = "2001", address = "www.omegahat.org" } @techreport{RS-Oracle, author = "James, David A.", title = "An {R}/{S} Interface to the {Oracle} Database", institution = "Bell Labs, Lucent Technologies", year = "In preparation", address = "www.omegahat.org" } @manual{r-data-imp:2001, author = {R Development Core Team}, title = {R Data Import/Export}, year = {2001}, address = {\url{https://www.r-project.org}} } @manual{mysql:2000, author = "Axmark, David and Widenius, Michael and Cole, Jeremy and DuBois, Paul", title = {MySQL Reference Manual}, year = {2001}, address = {\url{https://www.mysql.com/documentation/mysql}} } @manual{jdbc:2000, author = "Ellis, Jon and Ho, Linda and Fisher, Maydene", title = {JDBC 3.0 Specification}, organization = {Sun Microsystems, Inc}, year = {2000}, address = {\url{https://java.sun.com/Download4}} } @article{using-data:2001, author = "Ripley, Brian D.", title = {Using Databases with {R}}, journal = {R {N}ews}, year = {2001}, month = {January}, volume = {1}, number = {1}, pages = {18--20}, address = {\url{https://www.r-project.org/doc/Rnews/}} } @Manual{odbc:2001, title = {Microsoft {ODBC}}, organization = {Microsoft Inc}, address = {\url{https://www.microsoft.com/data/odbc/}}, year = 2001 } @Book{PerlDBI:2000, author = "Descartes, Alligator and Bunce, Tim", title = {Programming the {P}erl {DBI}}, publisher = {O'Reilly}, year = 2000 } @Book{Reese:2000, author = "Reese, George", title = {Database Programming with {JDBC} and {J}ava}, publisher = {O'Reilly}, year = 2000, edition = {second} } @book{Xopen-sql, author = {X/Open Company Ltd.}, title = {X/Open SQL and RDA Specification}, publisher = {X/Open Company Ltd.}, year = 1994 } @book{mysql-dubois, author = "DuBois, Paul", title = {MySQL}, publisher = {New Riders}, year = 2000 } @techreport{data-management:1991, author = "Chambers, John M.", title = {Data Management in {S}}, institution = {Bell Labs, Lucent Technologies}, year = 1991 } @techreport{database-classes:1999, author = "Chambers, John M.", title = {Database Classes}, institution = {Bell Labs, Lucent Technologies}, year = 1998 } @inproceedings{R-dcom, author = "Neuwirth, Erich and Baier, Thomas", title = {Embedding {R} in Standard Software, and the other way around}, organization = {Vienna University of Technology}, year = 2001, booktitle = {Proceedings of the Distributed Statistical Computing 2001 Workshop}, address = {\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2001}} } @inproceedings{R-tcltk, author = "Dalgaard, Peter", title = {The {R}-{T}cl/{T}k Interface}, organization = {Vienna University of Technology}, year = 2001, booktitle = {Proceedings of the Distributed Statistical Computing 2001 Workshop}, address = {\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2001}} } @inproceedings{duncan-dsc2001, author = "Temple Lang, Duncan", title = {Embedding {S} in Other Languages and Environments}, organization = {Vienna University of Technology}, year = 2001, booktitle = {Proceedings of the Distributed Statistical Computing 2001 Workshop}, address = {\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2001}} } @inproceedings{BDR-RMR, author = "Ripley, B. D. and Ripley, R. M.", title = {Applications of {R} Clients and Servers}, organization = {Vienna University of Technology}, year = 2001, booktitle = {Proceedings of the Distributed Statistical Computing 2001 Workshop}, address = {\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2001}} } @inproceedings{rsdbi-dsc2001, author = "Hothorn, Torsten and James, David A. and Ripley, Brian D.", title = {{R}/{S} Interfaces to Databases}, organization = {Vienna University of Technology}, year = 2001, booktitle = {Proceedings of the Distributed Statistical Computing 2001 Workshop}, address = {\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2001}} } DBI/vignettes/DBI-arrow.Rmd0000644000176200001440000001517214602466070015065 0ustar liggesusers--- title: "Using DBI with Arrow" author: "Kirill Müller" date: "25/12/2023" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Using DBI with Arrow} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} library(knitr) opts_chunk$set(echo = TRUE) knitr::opts_chunk$set(error = Sys.getenv("IN_PKGDOWN") != "true" || (getRversion() < "3.5")) knit_print.data.frame <- function(x, ...) { print(head(x, 6)) if (nrow(x) > 6) { cat("Showing 6 out of", nrow(x), "rows.\n") } invisible(x) } registerS3method("knit_print", "data.frame", "knit_print.data.frame") ``` ## Who this tutorial is for This tutorial is for you if you want to leverage [Apache Arrow](https://arrow.apache.org/) for accessing and manipulating data on databases. See `vignette("DBI", package = "DBI")` and `vignette("DBI-advanced", package = "DBI")` for tutorials on accessing data using R's data frames instead of Arrow's structures. ## Rationale Apache Arrow is > a cross-language development platform for in-memory analytics, suitable for large and huge data, with support for out-of-memory operation. Arrow is also a data exchange format, the data types covered by Arrow align well with the data types supported by SQL databases. DBI 1.2.0 introduced support for Arrow as a format for exchanging data between R and databases. The aim is to: - accelerate data retrieval and loading, by using fewer costly data conversions; - better support reading and summarizing data from a database that is larger than memory; - provide better type fidelity with workflows centered around Arrow. This allows existing code to be used with Arrow, and it allows new code to be written that is more efficient and more flexible than code that uses R's data frames. The interface is built around the {nanoarrow} R package, with `nanoarrow::as_nanoarrow_array` and `nanoarrow::as_nanoarrow_array_stream` as fundamental data structures. ## New classes and generics DBI 1.2.0 introduces new classes and generics for working with Arrow data: - `dbReadTableArrow()` - `dbWriteTableArrow()` - `dbCreateTableArrow()` - `dbAppendTableArrow()` - `dbGetQueryArrow()` - `dbSendQueryArrow()` - `dbBindArrow()` - `dbFetchArrow()` - `dbFetchArrowChunk()` - `DBIResultArrow-class` - `DBIResultArrowDefault-class` Compatibility is important for DBI, and implementing new generics and classes greatly reduces the risk of breaking existing code. The DBI package comes with a fully functional fallback implementation for all existing DBI backends. The fallback is not improving performance, but it allows existing code to be used with Arrow before switching to a backend with native Arrow support. Backends with native support, like the [adbi](https://adbi.r-dbi.org/) package, implement the new generics and classes for direct support and improved performance. In the remainder of this tutorial, we will demonstrate the new generics and classes using the RSQLite package. SQLite is an in-memory database, this code does not need a database server to be installed and running. ## Prepare We start by setting up a database connection and creating a table with some data, using the original `dbWriteTable()` method. ```{r} library(DBI) con <- dbConnect(RSQLite::SQLite()) data <- data.frame( a = 1:3, b = 4.5, c = "five" ) dbWriteTable(con, "tbl", data) ``` ## Read all rows from a table The `dbReadTableArrow()` method reads all rows from a table into an Arrow stream, similarly to `dbReadTable()`. Arrow objects implement the `as.data.frame()` method, so we can convert the stream to a data frame. ```{r} stream <- dbReadTableArrow(con, "tbl") stream as.data.frame(stream) ``` ## Run queries The `dbGetQueryArrow()` method runs a query and returns the result as an Arrow stream. This stream can be turned into an `arrow::RecordBatchReader` object and processed further, without bringing it into R. ```{r} stream <- dbGetQueryArrow(con, "SELECT COUNT(*) AS n FROM tbl WHERE a < 3") stream path <- tempfile(fileext = ".parquet") arrow::write_parquet(arrow::as_record_batch_reader(stream), path) arrow::read_parquet(path) ``` ## Prepared queries The `dbGetQueryArrow()` method supports prepared queries, using the `params` argument which accepts a data frame or a list. ```{r} params <- data.frame(a = 3L) stream <- dbGetQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a", params = params) as.data.frame(stream) params <- data.frame(a = c(2L, 4L)) # Equivalent to dbBind() stream <- dbGetQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a", params = params) as.data.frame(stream) ``` ## Manual flow For the manual flow, use `dbSendQueryArrow()` to send a query to the database, and `dbFetchArrow()` to fetch the result. This also allows using the new `dbBindArrow()` method to bind data in Arrow format to a prepared query. Result objects must be cleared with `dbClearResult()`. ```{r} rs <- dbSendQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a") in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 1L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 2L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 3L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 1:4L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) dbClearResult(rs) ``` ## Writing data Streams returned by `dbGetQueryArrow()` and `dbReadTableArrow()` can be written to a table using `dbWriteTableArrow()`. ```{r} stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a < 3") dbWriteTableArrow(con, "tbl_new", stream) dbReadTable(con, "tbl_new") ``` ## Appending data For more control over the writing process, use `dbCreateTableArrow()` and `dbAppendTableArrow()`. ```{r} stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a < 3") dbCreateTableArrow(con, "tbl_split", stream) dbAppendTableArrow(con, "tbl_split", stream) stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a >= 3") dbAppendTableArrow(con, "tbl_split", stream) dbReadTable(con, "tbl_split") ``` ## Conclusion Do not forget to disconnect from the database when done. ```{r} dbDisconnect(con) ``` That concludes the major features of DBI's new Arrow interface. For more details on the library functions covered in this tutorial see the DBI specification at `vignette("spec", package = "DBI")`. See the [adbi](https://adbi.r-dbi.org/) package for a backend with native Arrow support, and [nanoarrow](https://github.com/apache/arrow-nanoarrow) and [arrow](https://arrow.apache.org/docs/r/) for packages to work with the Arrow format. DBI/vignettes/backend.Rmd0000644000176200001440000002414014350241735014720 0ustar liggesusers --- title: "Implementing a new backend" author: "Hadley Wickham, Kirill Müller" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Implementing a new backend} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- ```{r, echo = FALSE} library(DBI) knitr::opts_chunk$set(collapse = TRUE, comment = "#>") ``` The goal of this document is to help you implement a new backend for DBI. If you are writing a package that connects a database to R, I highly recommend that you make it DBI compatible because it makes your life easier by spelling out exactly what you need to do. The consistent interface provided by DBI makes it easier for you to implement the package (because you have fewer arbitrary choices to make), and easier for your users (because it follows a familiar pattern). In addition, the `DBItest` package provides test cases which you can easily incorporate in your package. I'll illustrate the process using a fictional database called Kazam. ## Getting started Start by creating a package. It's up to you what to call the package, but following the existing pattern of `RSQLite`, `RMySQL`, `RPostgres` and `ROracle` will make it easier for people to find it. For this example, I'll call my package `RKazam`. A ready-to-use template package is available at https://github.com/r-dbi/RKazam/. You can start by creating a new GitHub repository from this template, or by copying the package code. Rename "Kazam" to your desired name everywhere. The template package already contains dummy implementations for all classes and methods. If you chose to create the package manually, make sure to include in your `DESCRIPTION`: ```yaml Imports: DBI (>= 0.3.0), methods Suggests: DBItest, testthat ``` Importing `DBI` is fine, because your users are not supposed to *attach* your package anyway; the preferred method is to attach `DBI` and use explicit qualification via `::` to access the driver in your package (which needs to be done only once). ## Testing Why testing at this early stage? Because testing should be an integral part of the software development cycle. Test right from the start, add automated tests as you go, finish faster (because tests are automated) while maintaining superb code quality (because tests also check corner cases that you might not be aware of). Don't worry: if some test cases are difficult or impossible to satisfy, or take too long to run, you can just turn them off. Take the time now to head over to the `DBItest` vignette at `vignette("test", package = "DBItest")`. You will find a vast amount of ready-to-use test cases that will help you in the process of implementing your new DBI backend. Add custom tests that are not covered by `DBItest` at your discretion, or enhance `DBItest` and file a pull request if the test is generic enough to be useful for many DBI backends. ## Driver Start by making a driver class which inherits from `DBIDriver`. This class doesn't need to do anything, it's just used to dispatch other generics to the right method. Users don't need to know about this, so you can remove it from the default help listing with `@keywords internal`: ```{r} #' Driver for Kazam database. #' #' @keywords internal #' @export #' @import DBI #' @import methods setClass("KazamDriver", contains = "DBIDriver") ``` The driver class was more important in older versions of DBI, so you should also provide a dummy `dbUnloadDriver()` method. ```{r} #' @export #' @rdname Kazam-class setMethod("dbUnloadDriver", "KazamDriver", function(drv, ...) { TRUE }) ``` If your package needs global setup or tear down, do this in the `.onLoad()` and `.onUnload()` functions. You might also want to add a show method so the object prints nicely: ```{r} setMethod("show", "KazamDriver", function(object) { cat("\n") }) ``` Next create `Kazam()` which instantiates this class. ```{r} #' @export Kazam <- function() { new("KazamDriver") } Kazam() ``` ## Connection Next create a connection class that inherits from `DBIConnection`. This should store all the information needed to connect to the database. If you're talking to a C api, this will include a slot that holds an external pointer. ```{r} #' Kazam connection class. #' #' @export #' @keywords internal setClass("KazamConnection", contains = "DBIConnection", slots = list( host = "character", username = "character", # and so on ptr = "externalptr" ) ) ``` Now you have some of the boilerplate out of the way, you can start work on the connection. The most important method here is `dbConnect()` which allows you to connect to a specified instance of the database. Note the use of `@rdname Kazam`. This ensures that `Kazam()` and the connect method are documented together. ```{r} #' @param drv An object created by \code{Kazam()} #' @rdname Kazam #' @export #' @examples #' \dontrun{ #' db <- dbConnect(RKazam::Kazam()) #' dbWriteTable(db, "mtcars", mtcars) #' dbGetQuery(db, "SELECT * FROM mtcars WHERE cyl == 4") #' } setMethod("dbConnect", "KazamDriver", function(drv, ...) { # ... new("KazamConnection", host = host, ...) }) ``` * Replace `...` with the arguments needed to connect to your database. You'll always need to include `...` in the arguments, even if you don't use it, for compatibility with the generic. * This is likely to be where people first come for help, so the examples should show how to connect to the database, and how to query it. (Obviously these examples won't work yet.) Ideally, include examples that can be run right away (perhaps relying on a publicly hosted database), but failing that surround in `\dontrun{}` so people can at least see the code. Next, implement `show()` and `dbDisconnect()` methods. ## Results Finally, you're ready to implement the meat of the system: fetching results of a query into a data frame. First define a results class: ```{r} #' Kazam results class. #' #' @keywords internal #' @export setClass("KazamResult", contains = "DBIResult", slots = list(ptr = "externalptr") ) ``` Then write a `dbSendQuery()` method. This takes a connection and SQL string as arguments, and returns a result object. Again `...` is needed for compatibility with the generic, but you can add other arguments if you need them. ```{r} #' Send a query to Kazam. #' #' @export #' @examples #' # This is another good place to put examples setMethod("dbSendQuery", "KazamConnection", function(conn, statement, ...) { # some code new("KazamResult", ...) }) ``` Next, implement `dbClearResult()`, which should close the result set and free all resources associated with it: ```{r} #' @export setMethod("dbClearResult", "KazamResult", function(res, ...) { # free resources TRUE }) ``` The hardest part of every DBI package is writing the `dbFetch()` method. This needs to take a result set and (optionally) number of records to return, and create a dataframe. Mapping R's data types to those of your database may require a custom implementation of the `dbDataType()` method for your connection class: ```{r} #' Retrieve records from Kazam query #' @export setMethod("dbFetch", "KazamResult", function(res, n = -1, ...) { ... }) # (optionally) #' Find the database data type associated with an R object #' @export setMethod("dbDataType", "KazamConnection", function(dbObj, obj, ...) { ... }) ``` Next, implement `dbHasCompleted()` which should return a `logical` indicating if there are any rows remaining to be fetched. ```{r} #' @export setMethod("dbHasCompleted", "KazamResult", function(res, ...) { }) ``` With these four methods in place, you can now use the default `dbGetQuery()` to send a query to the database, retrieve results if available and then clean up. Spend some time now making sure this works with an existing database, or relax and let the `DBItest` package do the work for you. ## SQL methods You're now on the home stretch, and can make your wrapper substantially more useful by implementing methods that wrap around variations in SQL across databases: * `dbQuoteString()` and `dbQuoteIdentifer()` are used to safely quote strings and identifiers to avoid SQL injection attacks. Note that the former must be vectorized, but not the latter. * `dbWriteTable()` creates a database table given an R dataframe. I'd recommend using the functions prefixed with `sql` in this package to generate the SQL. These functions are still a work in progress so please let me know if you have problems. * `dbReadTable()`: a simple wrapper around `SELECT * FROM table`. Use `dbQuoteIdentifer()` to safely quote the table name and prevent mismatches between the names allowed by R and the database. * `dbListTables()` and `dbExistsTable()` let you determine what tables are available. If not provided by your database's API, you may need to generate sql that inspects the system tables. * `dbListFields()` shows which fields are available in a given table. * `dbRemoveTable()` wraps around `DROP TABLE`. Start with `SQL::sqlTableDrop()`. * `dbBegin()`, `dbCommit()` and `dbRollback()`: implement these three functions to provide basic transaction support. This functionality is currently not tested in the `DBItest` package. ## Metadata methods There are a lot of extra metadata methods for result sets (and one for the connection) that you might want to implement. They are described in the following. * `dbIsValid()` returns if a connection or a result set is open (`TRUE`) or closed (`FALSE`). All further methods in this section are valid for result sets only. * `dbGetStatement()` returns the issued query as a character value. * `dbColumnInfo()` lists the names and types of the result set's columns. * `dbGetRowCount()` and `dbGetRowsAffected()` returns the number of rows returned or altered in a `SELECT` or `INSERT`/`UPDATE` query, respectively. * `dbBind()` allows using parametrised queries. Take a look at `sqlInterpolate()` and `sqlParseVariables()` if your SQL engine doesn't offer native parametrised queries. ## Full DBI compliance By now, your package should implement all methods defined in the DBI specification. If you want to walk the extra mile, offer a read-only mode that allows your users to be sure that their valuable data doesn't get destroyed inadvertently. DBI/vignettes/spec.Rmd0000644000176200001440000000177114607456777014313 0ustar liggesusers--- title: "DBI specification" author: "Kirill Müller" output: rmarkdown::html_vignette abstract: > The DBI package defines the generic DataBase Interface for R. The connection to individual DBMS is provided by other packages that import DBI (so-called *DBI backends*). This document formalizes the behavior expected by the methods declared in DBI and implemented by the individual backends. To ensure maximum portability and exchangeability, and to reduce the effort for implementing a new DBI backend, the DBItest package defines a comprehensive set of test cases that test conformance to the DBI specification. This document is derived from comments in the test definitions of the DBItest package. Any extensions or updates to the tests will be reflected in this document. vignette: > %\VignetteIndexEntry{DBI specification} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r echo = FALSE} knitr::asis_output(paste(readLines("spec.md"), collapse = "\n")) ``` DBI/vignettes/DBI-history.Rmd0000644000176200001440000001221414602466070015426 0ustar liggesusers--- title: "History of DBI" author: "David James" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{History of DBI} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- The following history of DBI was contributed by David James, the driving force behind the development of DBI, and many of the packages that implement it. The idea/work of interfacing S (originally S3 and S4) to RDBMS goes back to the mid- and late 1990's in Bell Labs. The first toy interface I did was to implement John Chamber's early concept of "Data Management in S" (1991). The implementation followed that interface pretty closely and immediately showed some of the limitations when dealing with very large databases; if my memory serves me, the issue was the instance-based of the language back then, e.g., if you attached an RDBMS to the `search()` path and then needed to resolve a symbol "foo", you effectively had to bring all the objects in the database to check their mode/class, i.e., the instance object had the metadata in itself as attributes. The experiment showed that the S3 implementation of "data management" was not really suitable to large external RDBMS (probably it was never intended to do that anyway). (Note however, that since then, John and Duncan Temple Lang generalized the data management in S4 a lot, including Duncan's implementation in his RObjectTables package where he considered a lot of synchronization/caching issues relevant to DBI and, more generally, to most external interfaces). Back then we were working very closely with Lucent's microelectronics manufacturing --- our colleagues there had huge Oracle (mostly) databases that we needed to constantly query via [SQL*Plus](https://en.wikipedia.org/wiki/SQL*Plus). My colleague Jake Luciani was developing advanced applications in C and SQL, and the two of us came up with the first implementation of S3 directly connecting with Oracle. What I remember is that the Linux [PRO*C](https://en.wikipedia.org/wiki/Pro*C) pre-compiler (that embedded SQL in C code) was very buggy --- we spent a lot of time looking for workarounds and tricks until we got the C interface running. At the time, other projects within Bell Labs began using MySQL, and we moved to MySQL (with the help of Doug Bates' student Saikat DebRoy, then a summer intern) with no intentions of looking back at the very difficult Oracle interface. It was at this time that I moved all the code from S3 methods to S4 classes and methods and begun reaching out to the S/R community for suggestions, ideas, etc. All (most) of this work was on Bell Labs versions of S3 and S4, but I made sure it worked with S-Plus. At some point around 2000 (I don't remember exactly when), I ported all the code to R regressing to S3 methods, and later on (once S4 classes and methods were available in R) I re-implemented everything back to S4 classes and methods in R (a painful back-and-forth). It was at this point that I decided to drop S-Plus altogether. Around that time, I came across a very early implementation of SQLite and I was quite interested and thought it was a very nice RDBMS that could be used for all kinds of experimentation, etc., so it was pretty easy to implement on top of the DBI. Within the R community, there were quite a number of people that showed interest on defining a common interface to databases, but only a few folks actually provided code/suggestions/etc. (Tim Keitt was most active with the dbi/PostgreSQL packages --- he also was considering what he called "proxy" objects, which was reminiscent of what Duncan had been doing). Kurt Hornick, Vincent Carey, Robert Gentleman, and others provided suggestions/comments/support for the DBI definition. By around 2003, the DBI was more or less implemented as it is today. I'm sure I'll forget some (most should be in the THANKS sections of the various packages), but the names that come to my mind at this moment are Jake Luciani (ROracle), Don MacQueen and other early ROracle users (super helpful), Doug Bates and his student Saikat DebRoy for RMySQL, Fei Chen (at the time a student of Prof. Ripley) also contributed to RMySQL, Tim Keitt (working on an early S3 interface to PostgrSQL), Torsten Hothorn (worked with mSQL and also MySQL), Prof. Ripley working/extending the RODBC package, in addition to John Chambers and Duncan Temple-Lang who provided very important comments and suggestions. Actually, the real impetus behind the DBI was always to do distributed statistical computing --- *not* to provide a yet-another import/export mechanism --- and this perspective was driven by John and Duncan's vision and work on inter-system computing, COM, CORBA, etc. I'm not sure many of us really appreciated (even now) the full extent of those ideas and concepts. Just like in other languages (C's ODBC, Java's JDBC, Perl's DBI/DBD, Python dbapi), R/S DBI was meant to unify the interfacing to RDBMS so that R/S applications could be developed on top of the DBI and not be hard coded to any one relation database. The interface I tried to follow the closest was the Python's DBAPI --- I haven't worked on this topic for a while, but I still feel Python's DBAPI is the cleanest and most relevant for the S language. DBI/vignettes/DBI.Rmd0000644000176200001440000001621514627140067013736 0ustar liggesusers--- title: "Introduction to DBI" author: "James Wondrasek, Katharina Brunner, Kirill Müller" date: "27 February 2020" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to DBI} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set( echo = TRUE, error = Sys.getenv("IN_PKGDOWN") != "true" || (getRversion() < "3.5") ) ``` ## Who this tutorial is for This tutorial is for you if you want to access or manipulate data in a database that may be on your machine or on a different computer on the internet, and you have found libraries that use a higher level of abstraction, such as [dbplyr](https://dbplyr.tidyverse.org/), are not suitable for your purpose. Depending on what you want to achieve, you may find it useful to have an understanding of SQL before using DBI. The DBI (**D**ata**B**ase **I**nterface) package provides a simple, consistent interface between R and database management systems (DBMS). Each supported DBMS is supported by its own R package that implements the DBI specification in `vignette("spec", package = "DBI")`. DBI currently supports about 30 DBMS, including: * MySQL, using the R-package [RMySQL](https://github.com/r-dbi/RMySQL) * MariaDB, using the R-package [RMariaDB](https://github.com/r-dbi/RMariaDB) * Postgres, using the R-package [RPostgres](https://github.com/r-dbi/RPostgres) * SQLite, using the R-package [RSQLite](https://github.com/r-dbi/RSQLite) For a more complete list of supported DBMS visit [https://github.com/r-dbi/backends](https://github.com/r-dbi/backends#readme). You may need to install the package specific to your DBMS. The functionality currently supported for each of these DBMS's includes: - manage a connection to a database - list the tables in a database - list the column names in a table - read a table into a data frame For more advanced features, such as parameterized queries, transactions, and more see `vignette("DBI-advanced", package = "DBI")`. ## How to connect to a database using DBI The following code establishes a connection to the Sakila database hosted by the Relational Dataset Repository at `https://relational-data.org/dataset/Sakila`, lists all tables on the database, and closes the connection. The database represents a fictional movie rental business and includes tables describing films, actors, customers, stores, etc.: ```{r} library(DBI) con <- dbConnect( RMariaDB::MariaDB(), host = "db.relational-data.org", port = 3306, username = "guest", password = "relational", dbname = "sakila" ) dbListTables(con) dbDisconnect(con) ``` Connections to databases are created using the `dbConnect()` function. The first argument to the function is the driver for the DBMS you are connecting to. In the example above we are connecting to a MariaDB instance, so we use the `RMariaDB::MariaDB()` driver. The other arguments depend on the authentication required by the DBMS. In the example host, port, username, password, and dbname are required. See the documentation for the DBMS driver package that you are using for specifics. The function `dbListTables()` takes a database connection as its only argument and returns a character vector with all table and view names in the database. After completing a session with a DBMS, always release the connection with a call to `dbDisconnect()`. ### Secure password storage The above example contains the password in the code, which should be avoided for databases with secured access. One way to use the credentials securely is to store it in your system's credential store and then query it with the [keyring](https://github.com/r-lib/keyring#readme) package. The code to connect to the database could then look like this: ```{r eval = FALSE} con <- dbConnect( RMariaDB::MariaDB(), host = "db.relational-data.org", port = 3306, username = "guest", password = keyring::key_get("db.relational-data.org", "guest"), dbname = "sakila" ) ``` ## How to retrieve column names for a table We can list the column names for a table with the function `dbListFields()`. It takes as arguments a database connection and a table name and returns a character vector of the column names in order. ```{r} con <- dbConnect(RMariaDB::MariaDB(), username = "guest", password = "relational", host = "db.relational-data.org", port = 3306, dbname = "sakila") dbListFields(con, "film") ``` ## Read a table into a data frame The function `dbReadTable()` reads an entire table and returns it as a data frame. It is equivalent to the SQL query `SELECT * FROM `. The columns of the returned data frame share the same names as the columns in the table. DBI and the database backends do their best to coerce data to equivalent R data types. ```{r} df <- dbReadTable(con, "film") head(df, 3) ``` ## Read only selected rows and columns into a data frame To read a subset of the data in a table into a data frame, DBI provides functions to run custom SQL queries and manage the results. For small datasets where you do not need to manage the number of results being returned, the function `dbGetQuery()` takes a SQL `SELECT` query to execute and returns a data frame. Below is a basic query that specifies the columns we require (`film_id`, `title` and `description`) and which rows (records) we are interested in. Here we retrieve films released in the year 2006. ```{r} df <- dbGetQuery(con, "SELECT film_id, title, description FROM film WHERE release_year = 2006") head(df, 3) ``` We could also retrieve movies released in 2006 that are rated "G". Note that character strings must be quoted. As the query itself is contained within double quotes, we use single quotes around the rating. See `dbQuoteLiteral()` for programmatically converting arbitrary R values to SQL. This is covered in more detail in `vignette("DBI-advanced", package = "DBI")`. ```{r} df <- dbGetQuery(con, "SELECT film_id, title, description FROM film WHERE release_year = 2006 AND rating = 'G'") head(df, 3) ``` The equivalent operation using `dplyr` reconstructs the SQL query using three functions to specify the table (`tbl()`), the subset of the rows (`filter()`), and the columns we require (`select()`). Note that dplyr takes care of the quoting. ```{r message=FALSE} library(dplyr) lazy_df <- tbl(con, "film") %>% filter(release_year == 2006 & rating == "G") %>% select(film_id, title, description) head(lazy_df, 3) ``` If you want to perform other data manipulation queries such as `UPDATE`s and `DELETE`s, see `dbSendStatement()` in `vignette("DBI-advanced", package = "DBI")`. ## How to end a DBMS session When finished accessing the DBMS, always close the connection using `dbDisconnect()`. ```{r} dbDisconnect(con) ``` ## Conclusion This tutorial has given you the basic techniques for accessing data in any supported DBMS. If you need to work with databases that will not fit in memory, or want to run more complex queries, including parameterized queries, please see `vignette("DBI-advanced", package = "DBI")`. ## Further Reading * An overview on [working with databases in R on Rstudio.com](https://db.rstudio.com/) * The DBI specification: `vignette("spec", package = "DBI")` * [List of supported DBMS](https://github.com/r-dbi/backends#readme) DBI/R/0000755000176200001440000000000014627152517011063 5ustar liggesusersDBI/R/dbCanConnect.R0000644000176200001440000000173014602466070013523 0ustar liggesusers#' Check if a connection to a DBMS can be established #' #' Like [dbConnect()], but only checks validity without actually returning #' a connection object. The default implementation opens a connection #' and disconnects on success, but individual backends might implement #' a lighter-weight check. #' #' @template methods #' @templateVar method_name dbCanConnect #' #' @return A scalar logical. If `FALSE`, the `"reason"` attribute indicates #' a reason for failure. #' #' @inheritParams dbConnect #' @family DBIDriver generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' # SQLite only needs a path to the database. (Here, ":memory:" is a special #' # path that creates an in-memory database.) Other database drivers #' # will require more details (like user, password, host, port, etc.) #' dbCanConnect(RSQLite::SQLite(), ":memory:") setGeneric("dbCanConnect", def = function(drv, ...) standardGeneric("dbCanConnect"), valueClass = "logical" ) DBI/R/dbListFields_DBIConnection_character.R0000644000176200001440000000042714350241735020265 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbListFields_DBIConnection_character <- function(conn, name, ...) { list_fields(conn, name) } #' @rdname hidden_aliases #' @export setMethod("dbListFields", signature("DBIConnection", "character"), dbListFields_DBIConnection_character) DBI/R/11-dbAppendTable.R0000644000176200001440000000323114602466070014104 0ustar liggesusers#' Insert rows into a table #' #' The `dbAppendTable()` method assumes that the table has been created #' beforehand, e.g. with [dbCreateTable()]. #' The default implementation calls [sqlAppendTableTemplate()] and then #' [dbExecute()] with the `param` argument. #' Use [dbAppendTableArrow()] to append data from an Arrow stream. #' #' Backends compliant to #' ANSI SQL 99 which use `?` as a placeholder for prepared queries don't need #' to override it. Backends with a different SQL syntax which use `?` #' as a placeholder for prepared queries can override [sqlAppendTable()]. #' Other backends (with different placeholders or with entirely different #' ways to create tables) need to override the `dbAppendTable()` method. #' #' The `row.names` argument is not supported by this method. #' Process the values with [sqlRownamesToColumn()] before calling this method. #' #' @inheritParams dbReadTable #' @param value A [data.frame] (or coercible to data.frame). #' @param row.names Must be `NULL`. #' @inheritParams sqlAppendTableTemplate #' #' @template methods #' @templateVar method_name dbAppendTable #' #' @inherit DBItest::spec_sql_append_table return #' @inheritSection DBItest::spec_sql_append_table Failure modes #' @inheritSection DBItest::spec_sql_append_table Specification #' #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' dbCreateTable(con, "iris", iris) #' dbAppendTable(con, "iris", iris) #' dbReadTable(con, "iris") #' dbDisconnect(con) setGeneric("dbAppendTable", def = function(conn, name, value, ..., row.names = NULL) standardGeneric("dbAppendTable") ) DBI/R/dbWithTransaction_DBIConnection.R0000644000176200001440000000247114350241735017331 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbWithTransaction_DBIConnection <- function(conn, code) { ## needs to be a closure, because it accesses conn rollback_because <- function(e) { call <- dbRollback(conn) if (identical(call, FALSE)) { stop( paste( "Failed to rollback transaction.", "Tried to roll back because an error", "occurred:", conditionMessage(e) ), call. = FALSE ) } if (inherits(e, "error")) { stop(e) } } ## check if each operation is successful call <- dbBegin(conn) if (identical(call, FALSE)) { stop("Failed to begin transaction", call. = FALSE) } tryCatch( { res <- force(code) call <- dbCommit(conn) if (identical(call, FALSE)) { stop("Failed to commit transaction", call. = FALSE) } res }, dbi_abort = rollback_because, error = rollback_because ) } #' @rdname hidden_aliases #' @export setMethod("dbWithTransaction", signature("DBIConnection"), dbWithTransaction_DBIConnection) #' @export #' @rdname dbWithTransaction dbBreak <- function() { signalCondition( structure( list(message = "Aborting DBI processing", call = NULL), class = c("dbi_abort", "condition") ) ) stop("Invalid usage of dbBreak().", call. = FALSE) } DBI/R/show_DBIConnector.R0000644000176200001440000000051114350241735014506 0ustar liggesusers#' @rdname hidden_aliases #' @param object Object to display #' @usage NULL show_DBIConnector <- function(object) { cat("") show(object@.drv) cat("Arguments:\n") show(object@.conn_args) invisible(NULL) } #' @rdname hidden_aliases #' @export setMethod("show", signature("DBIConnector"), show_DBIConnector) DBI/R/transactions.R0000644000176200001440000000370014602466070013711 0ustar liggesusers#' Begin/commit/rollback SQL transactions #' #' A transaction encapsulates several SQL statements in an atomic unit. #' It is initiated with `dbBegin()` and either made persistent with `dbCommit()` #' or undone with `dbRollback()`. #' In any case, the DBMS guarantees that either all or none of the statements #' have a permanent effect. #' This helps ensuring consistency of write operations to multiple tables. #' #' Not all database engines implement transaction management, in which case #' these methods should not be implemented for the specific #' [DBIConnection-class] subclass. #' #' @template methods #' @templateVar method_name transactions #' #' @inherit DBItest::spec_transaction_begin_commit_rollback return #' @inheritSection DBItest::spec_transaction_begin_commit_rollback Failure modes #' @inheritSection DBItest::spec_transaction_begin_commit_rollback Specification #' #' @inheritParams dbGetQuery #' @seealso Self-contained transactions: [dbWithTransaction()] #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "cash", data.frame(amount = 100)) #' dbWriteTable(con, "account", data.frame(amount = 2000)) #' #' # All operations are carried out as logical unit: #' dbBegin(con) #' withdrawal <- 300 #' dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) #' dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) #' dbCommit(con) #' #' dbReadTable(con, "cash") #' dbReadTable(con, "account") #' #' # Rolling back after detecting negative value on account: #' dbBegin(con) #' withdrawal <- 5000 #' dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) #' dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) #' if (dbReadTable(con, "account")$amount >= 0) { #' dbCommit(con) #' } else { #' dbRollback(con) #' } #' #' dbReadTable(con, "cash") #' dbReadTable(con, "account") #' #' dbDisconnect(con) NULL DBI/R/dbDisconnect.R0000644000176200001440000000117114602466070013600 0ustar liggesusers#' Disconnect (close) a connection #' #' This closes the connection, discards all pending work, and frees #' resources (e.g., memory, sockets). #' #' @template methods #' @templateVar method_name dbDisconnect #' #' @inherit DBItest::spec_connection_disconnect return #' @inheritSection DBItest::spec_connection_disconnect Failure modes #' #' @inheritParams dbGetQuery #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' dbDisconnect(con) setGeneric("dbDisconnect", def = function(conn, ...) standardGeneric("dbDisconnect") ) DBI/R/rownames.R0000644000176200001440000000526114602466070013040 0ustar liggesusers#' Convert row names back and forth between columns #' #' These functions provide a reasonably automatic way of preserving the row #' names of data frame during back-and-forth translation to an SQL table. #' By default, row names will be converted to an explicit column #' called "row_names", and any query returning a column called "row_names" #' will have those automatically set as row names. #' These methods are mostly useful for backend implementers. #' #' @param df A data frame #' @param row.names Either `TRUE`, `FALSE`, `NA` or a string. #' #' If `TRUE`, always translate row names to a column called "row_names". #' If `FALSE`, never translate row names. If `NA`, translate #' rownames only if they're a character vector. #' #' A string is equivalent to `TRUE`, but allows you to override the #' default name. #' #' For backward compatibility, `NULL` is equivalent to `FALSE`. #' @name rownames #' @examples #' # If have row names #' sqlRownamesToColumn(head(mtcars)) #' sqlRownamesToColumn(head(mtcars), FALSE) #' sqlRownamesToColumn(head(mtcars), "ROWNAMES") #' #' # If don't have #' sqlRownamesToColumn(head(iris)) #' sqlRownamesToColumn(head(iris), TRUE) #' sqlRownamesToColumn(head(iris), "ROWNAMES") NULL #' @export #' @rdname rownames sqlRownamesToColumn <- function(df, row.names = NA) { name <- guessRowName(df, row.names) if (is.null(name)) { rownames(df) <- NULL return(df) } rn <- stats::setNames(list(row.names(df)), name) df <- c(rn, df) class(df) <- "data.frame" attr(df, "row.names") <- .set_row_names(length(rn[[1]])) df } #' @export #' @rdname rownames sqlColumnToRownames <- function(df, row.names = NA) { name <- guessColName(df, row.names) if (is.null(name)) return(df) if (!(name %in% names(df))) { stop("Column ", name, " not present in output", call. = FALSE) } row.names(df) <- df[[name]] df[[name]] <- NULL df } guessRowName <- function(df, row.names) { if (identical(row.names, TRUE)) { "row_names" } else if (identical(row.names, FALSE) || is.null(row.names)) { NULL } else if (identical(row.names, NA)) { is_char <- is.character(attr(df, "row.names")) if (is_char) { "row_names" } else { NULL } } else if (is.character(row.names)) { row.names[1] } else { stop("Unknown input") } } guessColName <- function(df, row.names) { if (identical(row.names, TRUE)) { "row_names" } else if (identical(row.names, FALSE) || is.null(row.names)) { NULL } else if (identical(row.names, NA)) { if ("row_names" %in% names(df)) { "row_names" } else { NULL } } else if (is.character(row.names)) { row.names[1] } else { stop("Unknown input") } } DBI/R/dbiDataType_character.R0000644000176200001440000000030614350241735015405 0ustar liggesusersdbiDataType_character <- function(x) { "TEXT" } setMethod("dbiDataType", signature("character"), dbiDataType_character) setMethod("dbiDataType", signature("factor"), dbiDataType_character) DBI/R/01-DBIObject.R0000644000176200001440000000273214602466070013150 0ustar liggesusersNULL #' DBIObject class #' #' Base class for all other DBI classes (e.g., drivers, connections). This #' is a virtual Class: No objects may be created from it. #' #' More generally, the DBI defines a very small set of classes and generics that #' allows users and applications access DBMS with a common interface. The #' virtual classes are `DBIDriver` that individual drivers extend, #' `DBIConnection` that represent instances of DBMS connections, and #' `DBIResult` that represent the result of a DBMS statement. These three #' classes extend the basic class of `DBIObject`, which serves as the root #' or parent of the class hierarchy. #' #' @section Implementation notes: #' An implementation MUST provide methods for the following generics: #' #' \itemize{ #' \item [dbGetInfo()]. #' } #' #' It MAY also provide methods for: #' #' \itemize{ #' \item [summary()]. Print a concise description of the #' object. The default method invokes `dbGetInfo(dbObj)` and prints #' the name-value pairs one per line. Individual implementations may #' tailor this appropriately. #' } #' #' @docType class #' @family DBI classes #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' drv <- RSQLite::SQLite() #' con <- dbConnect(drv) #' #' rs <- dbSendQuery(con, "SELECT 1") #' is(drv, "DBIObject") ## True #' is(con, "DBIObject") ## True #' is(rs, "DBIObject") #' #' dbClearResult(rs) #' dbDisconnect(con) #' @export #' @name DBIObject-class setClass("DBIObject", "VIRTUAL") DBI/R/dbFetch_DBIResult.R0000644000176200001440000000033314350241735014413 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbFetch_DBIResult <- function(res, n = -1, ...) { fetch(res, n = n, ...) } #' @rdname hidden_aliases #' @export setMethod("dbFetch", signature("DBIResult"), dbFetch_DBIResult) DBI/R/dbDriver.R0000644000176200001440000000332414602466070012744 0ustar liggesusers#' Load and unload database drivers #' #' @description #' These methods are deprecated, please consult the documentation of the #' individual backends for the construction of driver instances. #' #' `dbDriver()` is a helper method used to create an new driver object #' given the name of a database or the corresponding R package. It works #' through convention: all DBI-extending packages should provide an exported #' object with the same name as the package. `dbDriver()` just looks for #' this object in the right places: if you know what database you are connecting #' to, you should call the function directly. #' #' @details #' The client part of the database communication is #' initialized (typically dynamically loading C code, etc.) but note that #' connecting to the database engine itself needs to be done through calls to #' `dbConnect`. #' #' @param drvName character name of the driver to instantiate. #' @param drv an object that inherits from `DBIDriver` as created by #' `dbDriver`. #' @param ... any other arguments are passed to the driver `drvName`. #' @return In the case of `dbDriver`, an driver object whose class extends #' `DBIDriver`. This object may be used to create connections to the #' actual DBMS engine. #' #' In the case of `dbUnloadDriver`, a logical indicating whether the #' operation succeeded or not. #' @import methods #' @family DBIDriver generics #' @export #' @keywords internal #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' # Create a RSQLite driver with a string #' d <- dbDriver("SQLite") #' d #' #' # But better, access the object directly #' RSQLite::SQLite() setGeneric("dbDriver", def = function(drvName, ...) standardGeneric("dbDriver"), valueClass = "DBIDriver" ) DBI/R/dbIsReadOnly_DBIObject.R0000644000176200001440000000027514350241735015330 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbIsReadOnly_DBIObject <- function(dbObj, ...) { FALSE } #' @rdname hidden_aliases setMethod("dbIsReadOnly", "DBIObject", dbIsReadOnly_DBIObject) DBI/R/dbDriver_character.R0000644000176200001440000000032114350241735014751 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbDriver_character <- function(drvName, ...) { findDriver(drvName)(...) } #' @rdname hidden_aliases setMethod("dbDriver", signature("character"), dbDriver_character) DBI/R/show_DBIDriver.R0000644000176200001440000000061114350241735014010 0ustar liggesusers#' @rdname hidden_aliases #' @param object Object to display #' @usage NULL show_DBIDriver <- function(object) { tryCatch( # to protect drivers that fail to implement the required methods (e.g., # RPostgreSQL) show_driver(object), error = function(e) NULL ) invisible(NULL) } #' @rdname hidden_aliases #' @export setMethod("show", signature("DBIDriver"), show_DBIDriver) DBI/R/dbGetInfo_DBIResult.R0000644000176200001440000000055014350241735014716 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbGetInfo_DBIResult <- function(dbObj, ...) { list( statement = dbGetStatement(dbObj), row.count = dbGetRowCount(dbObj), rows.affected = dbGetRowsAffected(dbObj), has.completed = dbHasCompleted(dbObj) ) } #' @rdname hidden_aliases setMethod("dbGetInfo", signature("DBIResult"), dbGetInfo_DBIResult) DBI/R/show_DBIConnection.R0000644000176200001440000000061214350241735014655 0ustar liggesusers#' @rdname hidden_aliases #' @param object Object to display #' @usage NULL show_DBIConnection <- function(object) { # to protect drivers that fail to implement the required methods (e.g., # RPostgreSQL) tryCatch( show_connection(object), error = function(e) NULL ) invisible(NULL) } #' @rdname hidden_aliases #' @export setMethod("show", "DBIConnection", show_DBIConnection) DBI/R/dbiDataType_list.R0000644000176200001440000000037514350241735014432 0ustar liggesusersdbiDataType_list <- function(x) { is_raw <- vapply(x, is.raw, logical(1)) if (!all(is_raw)) { stop("Only lists of raw vectors are currently supported", call. = FALSE) } "BLOB" } setMethod("dbiDataType", signature("list"), dbiDataType_list) DBI/R/dbFetch_DBIResultArrow.R0000644000176200001440000000057414602466070015436 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbFetch_DBIResultArrow <- function(res, n = -1, ...) { if (is.infinite(n)) { n <- -1 } if (n != -1) { stop("Cannot dbFetch() an Arrow result unless n = -1") } as.data.frame( dbFetchArrow(res, ...) ) } #' @rdname hidden_aliases #' @export setMethod("dbFetch", signature("DBIResultArrow"), dbFetch_DBIResultArrow) DBI/R/dbReadTableArrow.R0000644000176200001440000000222214602466070014343 0ustar liggesusers#' Read database tables as Arrow objects #' #' @description #' `r lifecycle::badge('experimental')` #' #' Reads a database table as an Arrow object. #' Use [dbReadTable()] instead to obtain a data frame. #' #' @details #' This function returns an Arrow object. #' Convert it to a data frame with [as.data.frame()] or #' use [dbReadTable()] to obtain a data frame. #' #' @template methods #' @templateVar method_name dbReadTableArrow #' #' @inherit DBItest::spec_arrow_read_table_arrow return #' @inheritSection DBItest::spec_arrow_read_table_arrow Failure modes #' @inheritSection DBItest::spec_arrow_read_table_arrow Specification #' #' @inheritParams dbGetQuery #' @inheritParams dbReadTable #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE) #' # Read data as Arrow table #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars[1:10, ]) #' dbReadTableArrow(con, "mtcars") #' #' dbDisconnect(con) setGeneric("dbReadTableArrow", def = function(conn, name, ...) { require_arrow() standardGeneric("dbReadTableArrow") } ) DBI/R/dbSendQueryArrow_DBIConnection.R0000644000176200001440000000055414602466070017143 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbSendQueryArrow_DBIConnection <- function(conn, statement, params = NULL, ...) { result <- dbSendQuery(conn, statement, params = params, ...) new("DBIResultArrowDefault", result = result) } #' @rdname hidden_aliases #' @export setMethod("dbSendQueryArrow", signature("DBIConnection"), dbSendQueryArrow_DBIConnection) DBI/R/dbListTables.R0000644000176200001440000000152214602466070013555 0ustar liggesusers#' List remote tables #' #' Returns the unquoted names of remote tables accessible through this #' connection. #' This should include views and temporary objects, but not all database backends #' (in particular \pkg{RMariaDB} and \pkg{RMySQL}) support this. #' #' @template methods #' @templateVar method_name dbListTables #' #' @inherit DBItest::spec_sql_list_tables return #' @inheritSection DBItest::spec_sql_list_tables Failure modes #' #' @inheritParams dbGetQuery #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbListTables(con) #' dbWriteTable(con, "mtcars", mtcars) #' dbListTables(con) #' #' dbDisconnect(con) setGeneric("dbListTables", def = function(conn, ...) standardGeneric("dbListTables"), valueClass = "character" ) DBI/R/dbUnquoteIdentifier_DBIConnection.R0000644000176200001440000000167314602466070017657 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbUnquoteIdentifier_DBIConnection <- function(conn, x, ...) { # Determine quoting character quote_char <- substr(dbQuoteIdentifier(conn, ""), 1, 1) if (is(x, "SQL") || is.character(x)) { if (is.character(x)) { stopifnot(!anyNA(x)) } x <- lapply(x, unquote, quote_char = quote_char) lapply(x, Id) } else if (is(x, "Id")) { list(x) } else { stop("x must be SQL, Id, or character", call. = FALSE) } } unquote <- function(x, quote_char) { # replace doubled quotes with escaped quote gsub <- gsub( pattern = paste0(quote_char, quote_char), replacement = paste0("\\", quote_char), x ) scan( text = x, what = character(), quote = quote_char, quiet = TRUE, na.strings = character(), sep = "." ) } #' @rdname hidden_aliases #' @export setMethod("dbUnquoteIdentifier", signature("DBIConnection"), dbUnquoteIdentifier_DBIConnection) DBI/R/dbListFields_DBIConnection_Id.R0000644000176200001440000000040214350241735016656 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbListFields_DBIConnection_Id <- function(conn, name, ...) { list_fields(conn, name) } #' @rdname hidden_aliases #' @export setMethod("dbListFields", signature("DBIConnection", "Id"), dbListFields_DBIConnection_Id) DBI/R/dbColumnInfo.R0000644000176200001440000000201514602466070013556 0ustar liggesusers#' Information about result types #' #' Produces a data.frame that describes the output of a query. The data.frame #' should have as many rows as there are output fields in the result set, and #' each column in the data.frame describes an aspect of the result set #' field (field name, type, etc.) #' #' @inheritSection dbBind The data retrieval flow #' #' @inheritParams dbClearResult #' #' @template methods #' @templateVar method_name dbColumnInfo #' #' @inherit DBItest::spec_meta_column_info return #' @inheritSection DBItest::spec_meta_column_info Failure modes #' @inheritSection DBItest::spec_meta_column_info Specification #' #' @family DBIResult generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' rs <- dbSendQuery(con, "SELECT 1 AS a, 2 AS b") #' dbColumnInfo(rs) #' dbFetch(rs) #' #' dbClearResult(rs) #' dbDisconnect(con) setGeneric("dbColumnInfo", def = function(res, ...) standardGeneric("dbColumnInfo"), valueClass = "data.frame" ) DBI/R/dbFetchArrow_DBIResultArrow.R0000644000176200001440000000145314602466070016446 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbFetchArrow_DBIResultArrow <- function(res, ...) { chunk <- dbFetchArrowChunk_DBIResultArrow(res) # Corner case: add empty chunk only for zero rows, for schema if (chunk$length == 0) { return(nanoarrow::basic_array_stream( list(), schema = nanoarrow::infer_nanoarrow_schema(chunk), validate = FALSE )) } out <- list(chunk) repeat { chunk <- dbFetchArrowChunk_DBIResultArrow(res) if (chunk$length == 0) { return(nanoarrow::basic_array_stream( out, schema = nanoarrow::infer_nanoarrow_schema(out[[1]]), validate = FALSE )) } out <- c(out, list(chunk)) } } #' @rdname hidden_aliases #' @export setMethod("dbFetchArrow", signature("DBIResultArrow"), dbFetchArrow_DBIResultArrow) DBI/R/dbSendStatement.R0000644000176200001440000000457614602466070014301 0ustar liggesusers#' Execute a data manipulation statement on a given database connection #' #' The `dbSendStatement()` method only submits and synchronously executes the #' SQL data manipulation statement (e.g., `UPDATE`, `DELETE`, #' `INSERT INTO`, `DROP TABLE`, ...) to the database engine. To query #' the number of affected rows, call [dbGetRowsAffected()] on the #' returned result object. You must also call [dbClearResult()] after #' that. For interactive use, you should almost always prefer #' [dbExecute()]. #' #' [dbSendStatement()] comes with a default implementation that simply #' forwards to [dbSendQuery()], to support backends that only #' implement the latter. #' #' @inheritSection dbBind The command execution flow #' #' @template methods #' @templateVar method_name dbSendStatement #' #' @inherit DBItest::spec_result_send_statement return #' @inheritSection DBItest::spec_result_send_statement Failure modes #' @inheritSection DBItest::spec_result_send_statement Additional arguments #' @inheritSection DBItest::spec_result_send_statement Specification #' @inheritSection DBItest::spec_result_send_statement Specification for the `immediate` argument #' #' @inheritParams dbGetQuery #' @param statement a character string containing SQL. #' #' @family DBIConnection generics #' @family command execution generics #' #' @seealso For queries: [dbSendQuery()] and [dbGetQuery()]. #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "cars", head(cars, 3)) #' #' rs <- dbSendStatement( #' con, #' "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)" #' ) #' dbHasCompleted(rs) #' dbGetRowsAffected(rs) #' dbClearResult(rs) #' dbReadTable(con, "cars") # there are now 6 rows #' #' # Pass one set of values directly using the param argument: #' rs <- dbSendStatement( #' con, #' "INSERT INTO cars (speed, dist) VALUES (?, ?)", #' params = list(4L, 5L) #' ) #' dbClearResult(rs) #' #' # Pass multiple sets of values using dbBind(): #' rs <- dbSendStatement( #' con, #' "INSERT INTO cars (speed, dist) VALUES (?, ?)" #' ) #' dbBind(rs, list(5:6, 6:7)) #' dbBind(rs, list(7L, 8L)) #' dbClearResult(rs) #' dbReadTable(con, "cars") # there are now 10 rows #' #' dbDisconnect(con) #' @export setGeneric("dbSendStatement", def = function(conn, statement, ...) standardGeneric("dbSendStatement"), valueClass = "DBIResult" ) DBI/R/dbSendStatement_DBIConnection_character.R0000644000176200001440000000045714350241735021004 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbSendStatement_DBIConnection_character <- function(conn, statement, ...) { dbSendQuery(conn, statement, ...) } #' @rdname hidden_aliases #' @export setMethod("dbSendStatement", signature("DBIConnection", "character"), dbSendStatement_DBIConnection_character) DBI/R/dbGetInfo.R0000644000176200001440000000130214614477037013046 0ustar liggesusers#' Get DBMS metadata #' #' Retrieves information on objects of class [DBIDriver-class], #' [DBIConnection-class] or [DBIResult-class]. #' #' @param dbObj An object inheriting from [DBIObject-class], #' i.e. [DBIDriver-class], [DBIConnection-class], #' or a [DBIResult-class] #' @param ... Other arguments to methods. #' #' @template methods #' @templateVar method_name dbGetInfo #' #' @family DBIDriver generics #' @family DBIConnection generics #' @family DBIResult generics #' @inherit DBItest::spec_get_info return #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' dbGetInfo(RSQLite::SQLite()) setGeneric("dbGetInfo", def = function(dbObj, ...) standardGeneric("dbGetInfo") ) DBI/R/dbExistsTable_DBIConnection_Id.R0000644000176200001440000000044514350241735017052 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbExistsTable_DBIConnection_Id <- function(conn, name, ...) { dbExistsTable(conn, dbQuoteIdentifier(conn, name), ...) } #' @rdname hidden_aliases #' @export setMethod("dbExistsTable", signature("DBIConnection", "Id"), dbExistsTable_DBIConnection_Id) DBI/R/dbiDataType_POSIXct.R0000644000176200001440000000020314350241735014676 0ustar liggesusers#' @usage NULL dbiDataType_POSIXct <- function(x) "TIMESTAMP" setMethod("dbiDataType", signature("POSIXct"), dbiDataType_POSIXct) DBI/R/interpolate.R0000644000176200001440000000745114350241735013535 0ustar liggesusersNULL #' @export #' @rdname sqlParseVariables sqlCommentSpec <- function(start, end, endRequired) { list(start = start, end = end, endRequired = endRequired) } #' @export #' @rdname sqlParseVariables sqlQuoteSpec <- function(start, end, escape = "", doubleEscape = TRUE) { list(start = start, end = end, escape = escape, doubleEscape = doubleEscape) } #' @export #' @rdname sqlParseVariables #' @param sql SQL to parse (a character string) #' @param quotes A list of `QuoteSpec` calls defining the quoting #' specification. #' @param comments A list of `CommentSpec` calls defining the commenting #' specification. sqlParseVariablesImpl <- function(sql, quotes, comments) { str_to_vec <- function(s) strsplit(s, "", fixed = TRUE)[[1L]] sql_arr <- c(str_to_vec(as.character(sql)), " ") # characters valid in variable names var_chars <- c(LETTERS, letters, 0:9, "_") # return values var_pos_start <- integer() var_pos_end <- integer() # internal helper variables quote_spec_offset <- 0L comment_spec_offset <- 0L sql_variable_start <- 0L # prepare comments & quotes for quicker comparisions for (c in seq_along(comments)) { comments[[c]][["start"]] <- str_to_vec(comments[[c]][["start"]]) comments[[c]][["end"]] <- str_to_vec(comments[[c]][["end"]]) } for (q in seq_along(quotes)) { quotes[[q]][["hasEscape"]] <- nchar(quotes[[q]][["escape"]]) > 0L } state <- "default" i <- 0L while (i < length(sql_arr)) { i <- i + 1L switch(state, default = { # variable if (sql_arr[[i]] == "?") { sql_variable_start <- i state <- "variable" next } # starting quoted area for (q in seq_along(quotes)) { if (identical(sql_arr[[i]], quotes[[q]][["start"]])) { quote_spec_offset <- q state <- "quote" break } } # we can abort here if the state has changed if (state != "default") next # starting comment for (c in seq_along(comments)) { comment_start_arr <- comments[[c]][["start"]] comment_start_length <- length(comment_start_arr) if (identical(sql_arr[i:(i + comment_start_length - 1L)], comment_start_arr)) { comment_spec_offset <- c i <- i + comment_start_length state <- "comment" break } } }, variable = { if (!(sql_arr[[i]] %in% var_chars)) { # append current variable offsets to return vectors var_pos_start <- c(var_pos_start, sql_variable_start) # we have already read too much, go back i <- i - 1L var_pos_end <- c(var_pos_end, i) state <- "default" } }, quote = { # if we see backslash-like escapes, ignore next character if (quotes[[quote_spec_offset]][["hasEscape"]] && identical(sql_arr[[i]], quotes[[quote_spec_offset]][[3]])) { i <- i + 1L next } # end quoted area if (identical(sql_arr[[i]], quotes[[quote_spec_offset]][["end"]])) { quote_spec_offset <- 0L state <- "default" } }, comment = { # end commented area comment_end_arr <- comments[[comment_spec_offset]][["end"]] comment_end_length <- length(comment_end_arr) if (identical(sql_arr[i:(i + comment_end_length - 1L)], comment_end_arr)) { i <- i + (comment_end_length - 1) comment_spec_offset <- 0L state <- "default" } } ) # } # if (quote_spec_offset > 0L) { stop("Unterminated literal") } if (comment_spec_offset > 0L && comments[[comment_spec_offset]][["endRequired"]]) { stop("Unterminated comment") } list(start = var_pos_start, end = var_pos_end) } DBI/R/dbGetInfo_DBIResultArrow.R0000644000176200001440000000036014602466070015731 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbGetInfo_DBIResultArrow <- function(dbObj, ...) { dbGetInfo(dbObj@result, ...) } #' @rdname hidden_aliases #' @export setMethod("dbGetInfo", signature("DBIResultArrow"), dbGetInfo_DBIResultArrow) DBI/R/sqlCreateTable.R0000644000176200001440000000344514602466070014102 0ustar liggesusers#' Compose query to create a simple table #' #' Exposes an interface to simple `CREATE TABLE` commands. The default #' method is ANSI SQL 99 compliant. #' This method is mostly useful for backend implementers. #' #' The `row.names` argument must be passed explicitly in order to avoid #' a compatibility warning. The default will be changed in a later release. #' #' @param con A database connection. #' @param table The table name, passed on to [dbQuoteIdentifier()]. Options are: #' - a character string with the unquoted DBMS table name, #' e.g. `"table_name"`, #' - a call to [Id()] with components to the fully qualified table name, #' e.g. `Id(schema = "my_schema", table = "table_name")` #' - a call to [SQL()] with the quoted and fully qualified table name #' given verbatim, e.g. `SQL('"my_schema"."table_name"')` #' @param fields Either a character vector or a data frame. #' #' A named character vector: Names are column names, values are types. #' Names are escaped with [dbQuoteIdentifier()]. #' Field types are unescaped. #' #' A data frame: field types are generated using #' [dbDataType()]. #' @param temporary If `TRUE`, will generate a temporary table. #' @inheritParams rownames #' @param ... Other arguments used by individual methods. #' #' @template methods #' @templateVar method_name sqlCreateTable #' #' @export #' @examples #' sqlCreateTable(ANSI(), "my-table", c(a = "integer", b = "text")) #' sqlCreateTable(ANSI(), "my-table", iris) #' #' # By default, character row names are converted to a row_names colum #' sqlCreateTable(ANSI(), "mtcars", mtcars[, 1:5]) #' sqlCreateTable(ANSI(), "mtcars", mtcars[, 1:5], row.names = FALSE) setGeneric("sqlCreateTable", def = function(con, table, fields, row.names = NA, temporary = FALSE, ...) standardGeneric("sqlCreateTable") ) DBI/R/24-dbSendQueryArrow.R0000644000176200001440000000421614602466070014667 0ustar liggesusers#' Execute a query on a given database connection for retrieval via Arrow #' #' @description #' `r lifecycle::badge('experimental')` #' #' The `dbSendQueryArrow()` method only submits and synchronously executes the #' SQL query to the database engine. #' It does \emph{not} extract any #' records --- for that you need to use the [dbFetchArrow()] method, and #' then you must call [dbClearResult()] when you finish fetching the #' records you need. #' For interactive use, you should almost always prefer [dbGetQueryArrow()]. #' Use [dbSendQuery()] or [dbGetQuery()] instead to retrieve the results #' as a data frame. #' #' @details #' This method is for `SELECT` queries only. Some backends may #' support data manipulation queries through this method for compatibility #' reasons. However, callers are strongly encouraged to use #' [dbSendStatement()] for data manipulation statements. #' #' @inheritSection dbBindArrow The data retrieval flow for Arrow streams #' #' @template methods #' @templateVar method_name dbSendQueryArrow #' #' @inherit DBItest::spec_arrow_send_query_arrow return #' @inheritSection DBItest::spec_arrow_send_query_arrow Failure modes #' @inheritSection DBItest::spec_arrow_send_query_arrow Additional arguments #' @inheritSection DBItest::spec_arrow_send_query_arrow Specification #' @inheritSection DBItest::spec_arrow_send_query_arrow Specification for the `immediate` argument #' #' @inheritParams dbGetQueryArrow #' @param statement a character string containing SQL. #' #' @family DBIConnection generics #' @family data retrieval generics #' @seealso For updates: [dbSendStatement()] and [dbExecute()]. #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE) #' # Retrieve data as arrow table #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' rs <- dbSendQueryArrow(con, "SELECT * FROM mtcars WHERE cyl = 4") #' dbFetchArrow(rs) #' dbClearResult(rs) #' #' dbDisconnect(con) setGeneric("dbSendQueryArrow", def = function(conn, statement, ...) { require_arrow() standardGeneric("dbSendQueryArrow") }, valueClass = "DBIResultArrow" ) DBI/R/summary_DBIObject.R0000644000176200001440000000063214350241735014503 0ustar liggesusers#' @usage NULL summary_DBIObject <- function(object, ...) { info <- dbGetInfo(dbObj = object, ...) cat(class(object), "\n") print_list_pairs(info) invisible(info) } setMethod("summary", "DBIObject", summary_DBIObject) print_list_pairs <- function(x, ...) { for (key in names(x)) { value <- format(x[[key]]) if (identical(value, "")) next cat(key, "=", value, "\n") } invisible(x) } DBI/R/dbIsValid_DBIResultArrowDefault.R0000644000176200001440000000040014602466070017231 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbIsValid_DBIResultArrowDefault <- function(dbObj, ...) { dbIsValid(dbObj@result) } #' @rdname hidden_aliases #' @export setMethod("dbIsValid", signature("DBIResultArrowDefault"), dbIsValid_DBIResultArrowDefault) DBI/R/dbDataType_DBIConnector.R0000644000176200001440000000036614350241735015557 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbDataType_DBIConnector <- function(dbObj, obj, ...) { dbDataType(dbObj@.drv, obj, ...) } #' @rdname hidden_aliases #' @export setMethod("dbDataType", signature("DBIConnector"), dbDataType_DBIConnector) DBI/R/25-dbBindArrow.R0000644000176200001440000000017314602466070013623 0ustar liggesusers#' @rdname dbBind #' @export setGeneric("dbBindArrow", def = function(res, params, ...) standardGeneric("dbBindArrow") ) DBI/R/deprecated.R0000644000176200001440000001050114602466070013276 0ustar liggesusersNULL ## produce legal SQL identifiers from strings in a character vector ## unique, in this function, means unique regardless of lower/upper case #' @rdname make.db.names #' @export make.db.names.default <- function(snames, keywords = .SQL92Keywords, unique = TRUE, allow.keywords = TRUE) { makeUnique <- function(x, sep = "_") { if (length(x) == 0) return(x) out <- x lc <- make.names(tolower(x), unique = FALSE) i <- duplicated(lc) lc <- make.names(lc, unique = TRUE) out[i] <- paste(out[i], substring(lc[i], first = nchar(out[i]) + 1), sep = sep) out } ## Note: SQL identifiers *can* be enclosed in double or single quotes ## when they are equal to reserverd keywords. fc <- substring(snames, 1, 1) lc <- substring(snames, nchar(snames)) i <- match(fc, c("'", '"'), 0) > 0 & match(lc, c("'", '"'), 0) > 0 snames[!i] <- make.names(snames[!i], unique = FALSE) if (unique) { snames[!i] <- makeUnique(snames[!i]) } if (!allow.keywords) { kwi <- match(keywords, toupper(snames), nomatch = 0L) snames[kwi] <- paste('"', snames[kwi], '"', sep = "") } gsub("\\.", "_", snames) } #' @rdname make.db.names #' @export isSQLKeyword.default <- function(name, keywords = .SQL92Keywords, case = c("lower", "upper", "any")[3]) { n <- pmatch(case, c("lower", "upper", "any"), nomatch = 0) if (n == 0) { stop('case must be one of "lower", "upper", or "any"') } kw <- switch(c("lower", "upper", "any")[n], lower = tolower(keywords), upper = toupper(keywords), any = toupper(keywords) ) if (n == 3) { name <- toupper(name) } match(name, keywords, nomatch = 0) > 0 } #' Keywords according to the SQL-92 standard #' #' A character vector of SQL-92 keywords, uppercase. #' #' @export #' @examples #' "SELECT" %in% .SQL92Keywords .SQL92Keywords <- c( "ABSOLUTE", "ADD", "ALL", "ALLOCATE", "ALTER", "AND", "ANY", "ARE", "AS", "ASC", "ASSERTION", "AT", "AUTHORIZATION", "AVG", "BEGIN", "BETWEEN", "BIT", "BIT_LENGTH", "BY", "CASCADE", "CASCADED", "CASE", "CAST", "CATALOG", "CHAR", "CHARACTER", "CHARACTER_LENGTH", "CHAR_LENGTH", "CHECK", "CLOSE", "COALESCE", "COLLATE", "COLLATION", "COLUMN", "COMMIT", "CONNECT", "CONNECTION", "CONSTRAINT", "CONSTRAINTS", "CONTINUE", "CONVERT", "CORRESPONDING", "COUNT", "CREATE", "CURRENT", "CURRENT_DATE", "CURRENT_TIMESTAMP", "CURRENT_TYPE", "CURSOR", "DATE", "DAY", "DEALLOCATE", "DEC", "DECIMAL", "DECLARE", "DEFAULT", "DEFERRABLE", "DEFERRED", "DELETE", "DESC", "DESCRIBE", "DESCRIPTOR", "DIAGNOSTICS", "DICONNECT", "DICTIONATRY", "DISPLACEMENT", "DISTINCT", "DOMAIN", "DOUBLE", "DROP", "ELSE", "END", "END-EXEC", "ESCAPE", "EXCEPT", "EXCEPTION", "EXEC", "EXECUTE", "EXISTS", "EXTERNAL", "EXTRACT", "FALSE", "FETCH", "FIRST", "FLOAT", "FOR", "FOREIGN", "FOUND", "FROM", "FULL", "GET", "GLOBAL", "GO", "GOTO", "GRANT", "GROUP", "HAVING", "HOUR", "IDENTITY", "IGNORE", "IMMEDIATE", "IN", "INCLUDE", "INDEX", "INDICATOR", "INITIALLY", "INNER", "INPUT", "INSENSITIVE", "INSERT", "INT", "INTEGER", "INTERSECT", "INTERVAL", "INTO", "IS", "ISOLATION", "JOIN", "KEY", "LANGUAGE", "LAST", "LEFT", "LEVEL", "LIKE", "LOCAL", "LOWER", "MATCH", "MAX", "MIN", "MINUTE", "MODULE", "MONTH", "NAMES", "NATIONAL", "NCHAR", "NEXT", "NOT", "NULL", "NULLIF", "NUMERIC", "OCTECT_LENGTH", "OF", "OFF", "ONLY", "OPEN", "OPTION", "OR", "ORDER", "OUTER", "OUTPUT", "OVERLAPS", "PARTIAL", "POSITION", "PRECISION", "PREPARE", "PRESERVE", "PRIMARY", "PRIOR", "PRIVILEGES", "PROCEDURE", "PUBLIC", "READ", "REAL", "REFERENCES", "RESTRICT", "REVOKE", "RIGHT", "ROLLBACK", "ROWS", "SCHEMA", "SCROLL", "SECOND", "SECTION", "SELECT", "SET", "SIZE", "SMALLINT", "SOME", "SQL", "SQLCA", "SQLCODE", "SQLERROR", "SQLSTATE", "SQLWARNING", "SUBSTRING", "SUM", "SYSTEM", "TABLE", "TEMPORARY", "THEN", "TIME", "TIMESTAMP", "TIMEZONE_HOUR", "TIMEZONE_MINUTE", "TO", "TRANSACTION", "TRANSLATE", "TRANSLATION", "TRUE", "UNION", "UNIQUE", "UNKNOWN", "UPDATE", "UPPER", "USAGE", "USER", "USING", "VALUE", "VALUES", "VARCHAR", "VARYING", "VIEW", "WHEN", "WHENEVER", "WHERE", "WITH", "WORK", "WRITE", "YEAR", "ZONE" ) #' Determine the current version of the package. #' #' @export #' @keywords internal dbGetDBIVersion <- function() { .Deprecated("packageVersion('DBI')") utils::packageVersion("DBI") } DBI/R/dbiDataType_Date.R0000644000176200001440000000016514350241735014331 0ustar liggesusers#' @usage NULL dbiDataType_Date <- function(x) "DATE" setMethod("dbiDataType", signature("Date"), dbiDataType_Date) DBI/R/dbAppendTableArrow_DBIConnection.R0000644000176200001440000000325714602466070017406 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbAppendTableArrow_DBIConnection <- function(conn, name, value, ...) { require_arrow() name <- dbQuoteIdentifier(conn, name) value <- nanoarrow::as_nanoarrow_array_stream(value) rows <- 0L while (TRUE) { # Append next batch (starting with the first or second, doesn't matter) tmp <- value$get_next() if (is.null(tmp)) { break } tmp_df <- as.data.frame(tmp) dbAppendTable(conn, name, stream_append_data(tmp_df), ...) rows <- rows + nrow(tmp_df) } value$release() rows } #' @rdname hidden_aliases #' @export setMethod("dbAppendTableArrow", signature("DBIConnection"), dbAppendTableArrow_DBIConnection) stream_append_data <- function(value) { value <- factor_to_string(value) value <- string_to_utf8(value) value } factor_to_string <- function(value, warn = FALSE) { is_factor <- vapply(value, is.factor, logical(1)) if (warn && any(is_factor)) { warning("Factors converted to character", call. = FALSE) } value[is_factor] <- lapply(value[is_factor], as.character) value } raw_to_string <- function(value) { is_raw <- vapply(value, is.raw, logical(1)) if (any(is_raw)) { warning("Creating a TEXT column from raw, use lists of raw to create BLOB columns", call. = FALSE) value[is_raw] <- lapply(value[is_raw], as.character) } value } quote_string <- function(value, conn) { is_character <- vapply(value, is.character, logical(1)) value[is_character] <- lapply(value[is_character], dbQuoteString, conn = conn) value } string_to_utf8 <- function(value) { is_char <- vapply(value, is.character, logical(1)) value[is_char] <- lapply(value[is_char], enc2utf8) value } DBI/R/dbGetConnectArgs_DBIConnector.R0000644000176200001440000000061414350241735016706 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbGetConnectArgs_DBIConnector <- function(drv, eval = TRUE, ...) { conn_args <- drv@.conn_args if (isTRUE(eval)) { conn_args <- lapply(conn_args, function(x) { if (is.function(x)) x() else x }) } conn_args } #' @rdname hidden_aliases #' @export setMethod("dbGetConnectArgs", signature("DBIConnector"), dbGetConnectArgs_DBIConnector) DBI/R/dbGetRowsAffected_DBIResultArrow.R0000644000176200001440000000041414602466070017412 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbGetRowsAffected_DBIResultArrow <- function(res, ...) { dbGetRowsAffected(res@result, ...) } #' @rdname hidden_aliases #' @export setMethod("dbGetRowsAffected", signature("DBIResultArrow"), dbGetRowsAffected_DBIResultArrow) DBI/R/sqlParseVariables_DBIConnection.R0000644000176200001440000000067414350241735017330 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL sqlParseVariables_DBIConnection <- function(conn, sql, ...) { sqlParseVariablesImpl( sql, list( sqlQuoteSpec('"', '"'), sqlQuoteSpec("'", "'") ), list( sqlCommentSpec("/*", "*/", TRUE), sqlCommentSpec("--", "\n", FALSE) ) ) } #' @rdname hidden_aliases #' @export setMethod("sqlParseVariables", signature("DBIConnection"), sqlParseVariables_DBIConnection) DBI/R/DBIConnector.R0000644000176200001440000000302614602466070013453 0ustar liggesusersNULL #' DBIConnector class #' #' Wraps objects of the [DBIDriver-class] class to include connection options. #' The purpose of this class is to store both the driver #' and the connection options. #' A database connection can be established #' with a call to [dbConnect()], passing only that object #' without additional arguments. #' #' To prevent leakage of passwords and other credentials, #' this class supports delayed evaluation. #' All arguments can optionally be a function (callable without arguments). #' In such a case, the function is evaluated transparently when connecting in #' [dbGetConnectArgs()]. #' # FIXME: Include this # Database backends can take advantage of this feature by returning an # instance of this class instead of `DBIDriver`. # See the implementation of [RSQLite::SQLite()] for an example. #' #' @docType class #' @name DBIConnector-class #' @family DBI classes #' @family DBIConnector generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' # Create a connector: #' cnr <- new("DBIConnector", #' .drv = RSQLite::SQLite(), #' .conn_args = list(dbname = ":memory:") #' ) #' cnr #' #' # Establish a connection through this connector: #' con <- dbConnect(cnr) #' con #' #' # Access the database through this connection: #' dbGetQuery(con, "SELECT 1 AS a") #' dbDisconnect(con) setClass("DBIConnector", slots = c(".drv" = "DBIDriver", ".conn_args" = "list"), contains = c("DBIObject") ) names2 <- function(x) { if (is.null(names(x))) { rep("", length(x)) } else { names(x) } } DBI/R/make.db.names_DBIObject_character.R0000644000176200001440000000057314350241735017431 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL make.db.names_DBIObject_character <- function(dbObj, snames, keywords, unique, allow.keywords, ...) { make.db.names.default(snames, keywords, unique, allow.keywords) } #' @rdname hidden_aliases setMethod("make.db.names", signature(dbObj = "DBIObject", snames = "character"), make.db.names_DBIObject_character, valueClass = "character") DBI/R/sqlParseVariables.R0000644000176200001440000000214014350241735014620 0ustar liggesusers#' Parse interpolated variables from SQL. #' #' If you're implementing a backend that uses non-ANSI quoting or commenting #' rules, you'll need to implement a method for `sqlParseVariables` that #' calls `sqlParseVariablesImpl` with the appropriate quote and #' comment specifications. #' #' #' @param start,end Start and end characters for quotes and comments #' @param endRequired Is the ending character of a comment required? #' @param doubleEscape Can quoting characters be escaped by doubling them? #' Defaults to `TRUE`. #' @param escape What character can be used to escape quoting characters? #' Defaults to `""`, i.e. nothing. #' @keywords internal #' @export #' @examples #' # Use [] for quoting and no comments #' sqlParseVariablesImpl("[?a]", #' list(sqlQuoteSpec("[", "]", "\\", FALSE)), #' list() #' ) #' #' # Standard quotes, use # for commenting #' sqlParseVariablesImpl("# ?a\n?b", #' list(sqlQuoteSpec("'", "'"), sqlQuoteSpec('"', '"')), #' list(sqlCommentSpec("#", "\n", FALSE)) #' ) setGeneric("sqlParseVariables", def = function(conn, sql, ...) standardGeneric("sqlParseVariables") ) DBI/R/sqlInterpolate.R0000644000176200001440000000607014350241735014211 0ustar liggesusers#' Safely interpolate values into an SQL string #' #' @description #' Accepts a query string with placeholders for values, and returns a string #' with the values embedded. #' The function is careful to quote all of its inputs with [dbQuoteLiteral()] #' to protect against SQL injection attacks. #' #' Placeholders can be specified with one of two syntaxes: #' #' - `?`: each occurrence of a standalone `?` is replaced with a value #' - `?name1`, `?name2`, ...: values are given as named arguments or a #' named list, the names are used to match the values #' #' Mixing `?` and `?name` syntaxes is an error. #' The number and names of values supplied must correspond to the placeholders #' used in the query. #' #' @section Backend authors: #' If you are implementing an SQL backend with non-ANSI quoting rules, you'll #' need to implement a method for [sqlParseVariables()]. Failure to #' do so does not expose you to SQL injection attacks, but will (rarely) result #' in errors matching supplied and interpolated variables. #' #' @inheritParams dbGetQuery #' @param sql A SQL string containing variables to interpolate. #' Variables must start with a question mark and can be any valid R #' identifier, i.e. it must start with a letter or `.`, and be followed #' by a letter, digit, `.` or `_`. #' @param ...,.dots Values (for `...`) or a list (for `.dots`) #' to interpolate into a string. #' Names are required if `sql` uses the `?name` syntax for placeholders. #' All values will be first escaped with [dbQuoteLiteral()] prior #' to interpolation to protect against SQL injection attacks. #' Arguments created by [SQL()] or [dbQuoteIdentifier()] remain unchanged. #' @return The `sql` query with the values from `...` and `.dots` safely #' embedded. #' #' @template methods #' @templateVar method_name sqlInterpolate #' #' @export #' @examples #' sql <- "SELECT * FROM X WHERE name = ?name" #' sqlInterpolate(ANSI(), sql, name = "Hadley") #' #' # This is safe because the single quote has been double escaped #' sqlInterpolate(ANSI(), sql, name = "H'); DROP TABLE--;") #' #' # Using paste0() could lead to dangerous SQL with carefully crafted inputs #' # (SQL injection) #' name <- "H'); DROP TABLE--;" #' paste0("SELECT * FROM X WHERE name = '", name, "'") #' #' # Use SQL() or dbQuoteIdentifier() to avoid escaping #' sql2 <- "SELECT * FROM ?table WHERE name in ?names" #' sqlInterpolate(ANSI(), sql2, #' table = dbQuoteIdentifier(ANSI(), "X"), #' names = SQL("('a', 'b')") #' ) #' #' # Don't use SQL() to escape identifiers to avoid SQL injection #' sqlInterpolate(ANSI(), sql2, #' table = SQL("X; DELETE FROM X; SELECT * FROM X"), #' names = SQL("('a', 'b')") #' ) #' #' # Use dbGetQuery() or dbExecute() to process these queries: #' if (requireNamespace("RSQLite", quietly = TRUE)) { #' con <- dbConnect(RSQLite::SQLite()) #' sql <- "SELECT ?value AS value" #' query <- sqlInterpolate(con, sql, value = 3) #' print(dbGetQuery(con, query)) #' dbDisconnect(con) #' } setGeneric("sqlInterpolate", def = function(conn, sql, ..., .dots = list()) standardGeneric("sqlInterpolate") ) DBI/R/dbReadTable_DBIConnection_character.R0000644000176200001440000000174114602466070020047 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbReadTable_DBIConnection_character <- function(conn, name, ..., row.names = FALSE, check.names = TRUE) { sql_name <- dbReadTable_toSqlName(conn, name, ...) if (!is.null(row.names)) { stopifnot(length(row.names) == 1L) stopifnot(is.logical(row.names) || is.character(row.names)) } stopifnot(length(check.names) == 1L) stopifnot(is.logical(check.names)) stopifnot(!is.na(check.names)) out <- dbGetQuery(conn, paste0("SELECT * FROM ", sql_name)) out <- sqlColumnToRownames(out, row.names) if (check.names) { names(out) <- make.names(names(out), unique = TRUE) } out } dbReadTable_toSqlName <- function(conn, name, ...) { sql_name <- dbQuoteIdentifier(conn, x = name, ...) if (length(sql_name) != 1L) { stop("Invalid name: ", format(name), call. = FALSE) } sql_name } #' @rdname hidden_aliases #' @export setMethod("dbReadTable", signature("DBIConnection", "character"), dbReadTable_DBIConnection_character) DBI/R/dbQuoteLiteral.R0000644000176200001440000000253714350241735014127 0ustar liggesusers#' Quote literal values #' #' @description #' Call these methods to generate a string that is suitable for #' use in a query as a literal value of the correct type, to make sure that you #' generate valid SQL and protect against SQL injection attacks. #' #' @inheritParams dbQuoteString #' @param x A vector to quote as string. #' #' @template methods #' @templateVar method_name dbQuoteLiteral #' #' @inherit DBItest::spec_sql_quote_literal return #' @inheritSection DBItest::spec_sql_quote_literal Failure modes #' @inheritSection DBItest::spec_sql_quote_literal Specification #' #' @family DBIResult generics #' @export #' @examples #' # Quoting ensures that arbitrary input is safe for use in a query #' name <- "Robert'); DROP TABLE Students;--" #' dbQuoteLiteral(ANSI(), name) #' #' # NAs become NULL #' dbQuoteLiteral(ANSI(), c(1:3, NA)) #' #' # Logicals become integers by default #' dbQuoteLiteral(ANSI(), c(TRUE, FALSE, NA)) #' #' # Raw vectors become hex strings by default #' dbQuoteLiteral(ANSI(), list(as.raw(1:3), NULL)) #' #' # SQL vectors are always passed through as is #' var_name <- SQL("select") #' var_name #' dbQuoteLiteral(ANSI(), var_name) #' #' # This mechanism is used to prevent double escaping #' dbQuoteLiteral(ANSI(), dbQuoteLiteral(ANSI(), name)) setGeneric("dbQuoteLiteral", def = function(conn, x, ...) standardGeneric("dbQuoteLiteral") ) DBI/R/22-dbCreateTableArrow.R0000644000176200001440000000274614602466070015127 0ustar liggesusers#' Create a table in the database based on an Arrow object #' #' @description #' `r lifecycle::badge('experimental')` #' #' The default `dbCreateTableArrow()` method determines the R data types #' of the Arrow schema associated with the Arrow object, #' and calls [dbCreateTable()]. #' Backends that implement [dbAppendTableArrow()] should typically #' also implement this generic. #' Use [dbCreateTable()] to create a table from the column types #' as defined in a data frame. #' #' @param value An object for which a schema can be determined via #' [nanoarrow::infer_nanoarrow_schema()]. #' @inheritParams dbReadTable #' @inheritParams sqlCreateTable #' #' @inherit DBItest::spec_arrow_create_table_arrow return #' @inheritSection DBItest::spec_arrow_create_table_arrow Failure modes #' @inheritSection DBItest::spec_arrow_create_table_arrow Additional arguments #' @inheritSection DBItest::spec_arrow_create_table_arrow Specification #' #' @template methods #' @templateVar method_name dbCreateTableArrow #' #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' ptype <- data.frame(a = numeric()) #' dbCreateTableArrow(con, "df", nanoarrow::infer_nanoarrow_schema(ptype)) #' dbReadTable(con, "df") #' dbDisconnect(con) setGeneric("dbCreateTableArrow", def = function(conn, name, value, ..., temporary = FALSE) standardGeneric("dbCreateTableArrow") ) DBI/R/07-DBIResultArrow.R0000644000176200001440000000145714602466070014244 0ustar liggesusers#' DBIResultArrow class #' #' @description #' `r lifecycle::badge('experimental')` #' #' This virtual class describes the result and state of execution of #' a DBMS statement (any statement, query or non-query) #' for returning data as an Arrow object. #' #' @section Implementation notes: #' Individual drivers are free to allow single or multiple #' active results per connection. #' #' The default show method displays a summary of the query using other #' DBI generics. #' #' @name DBIResultArrow-class #' @docType class #' @family DBI classes #' @family DBIResultArrow generics #' @export setClass("DBIResultArrow", contains = c("DBIObject", "VIRTUAL")) #' @rdname DBIResultArrow-class #' @export setClass("DBIResultArrowDefault", contains = "DBIResultArrow", slots = list( result = "DBIResult" ) ) DBI/R/dbHasCompleted.R0000644000176200001440000000215614602466070014063 0ustar liggesusers#' Completion status #' #' This method returns if the operation has completed. #' A `SELECT` query is completed if all rows have been fetched. #' A data manipulation statement is always completed. #' #' @inheritSection dbBind The data retrieval flow #' #' @template methods #' @templateVar method_name dbHasCompleted #' #' @inherit DBItest::spec_meta_has_completed return #' @inheritSection DBItest::spec_meta_has_completed Failure modes #' @inheritSection DBItest::spec_meta_has_completed Specification #' #' @inheritParams dbClearResult #' @family DBIResult generics #' @family DBIResultArrow generics #' @family data retrieval generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' rs <- dbSendQuery(con, "SELECT * FROM mtcars") #' #' dbHasCompleted(rs) #' ret1 <- dbFetch(rs, 10) #' dbHasCompleted(rs) #' ret2 <- dbFetch(rs) #' dbHasCompleted(rs) #' #' dbClearResult(rs) #' dbDisconnect(con) setGeneric("dbHasCompleted", def = function(res, ...) standardGeneric("dbHasCompleted"), valueClass = "logical" ) DBI/R/dbGetConnectArgs.R0000644000176200001440000000175414602466070014364 0ustar liggesusers#' Get connection arguments #' #' Returns the arguments stored in a [DBIConnector-class] object for inspection, #' optionally evaluating them. #' This function is called by [dbConnect()] #' and usually does not need to be called directly. #' #' @template methods #' @templateVar method_name dbGetConnectArgs #' #' @param drv A object inheriting from [DBIConnector-class]. #' @param eval Set to `FALSE` to return the functions that generate the argument #' instead of evaluating them. #' @param ... Other arguments passed on to methods. Not otherwise used. #' @family DBIConnector generics #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' cnr <- new("DBIConnector", #' .drv = RSQLite::SQLite(), #' .conn_args = list(dbname = ":memory:", password = function() "supersecret") #' ) #' dbGetConnectArgs(cnr) #' dbGetConnectArgs(cnr, eval = FALSE) #' @export setGeneric("dbGetConnectArgs", def = function(drv, eval = TRUE, ...) standardGeneric("dbGetConnectArgs"), valueClass = "list" ) DBI/R/dbiDataType.R0000644000176200001440000000012414350241735013367 0ustar liggesuserssetGeneric("dbiDataType", def = function(x, ...) standardGeneric("dbiDataType") ) DBI/R/12-dbCreateTable.R0000644000176200001440000000274014602466070014105 0ustar liggesusers#' Create a table in the database #' #' The default `dbCreateTable()` method calls [sqlCreateTable()] and #' [dbExecute()]. #' Use [dbCreateTableArrow()] to create a table from an Arrow schema. #' #' Backends compliant to ANSI SQL 99 don't need to override it. #' Backends with a different SQL syntax can override `sqlCreateTable()`, #' backends with entirely different ways to create tables need to #' override this method. #' #' The `row.names` argument is not supported by this method. #' Process the values with [sqlRownamesToColumn()] before calling this method. #' #' The argument order is different from the `sqlCreateTable()` method, the #' latter will be adapted in a later release of DBI. #' #' @inheritParams dbReadTable #' @param row.names Must be `NULL`. #' @inheritParams sqlCreateTable #' #' @inherit DBItest::spec_sql_create_table return #' @inheritSection DBItest::spec_sql_create_table Failure modes #' @inheritSection DBItest::spec_sql_create_table Additional arguments #' @inheritSection DBItest::spec_sql_create_table Specification #' #' @template methods #' @templateVar method_name dbCreateTable #' #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' dbCreateTable(con, "iris", iris) #' dbReadTable(con, "iris") #' dbDisconnect(con) setGeneric("dbCreateTable", def = function(conn, name, fields, ..., row.names = NULL, temporary = FALSE) standardGeneric("dbCreateTable") ) DBI/R/dbiDataType_difftime.R0000644000176200001440000000020114350241735015232 0ustar liggesusers#' @usage NULL dbiDataType_difftime <- function(x) "TIME" setMethod("dbiDataType", signature("difftime"), dbiDataType_difftime) DBI/R/DBI-package.R0000644000176200001440000000203014602466070013163 0ustar liggesusers#' @description #' DBI defines an interface for communication between R and relational database #' management systems. #' All classes in this package are virtual and need to be extended by #' the various R/DBMS implementations (so-called *DBI backends*). #' #' @inheritSection DBItest::spec_getting_started Definition #' @inheritSection DBItest::spec_compliance_methods DBI classes and methods #' @inheritSection DBItest::spec_driver_constructor Construction of the DBIDriver object #' #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' RSQLite::SQLite() #' @seealso #' Important generics: [dbConnect()], [dbGetQuery()], #' [dbReadTable()], [dbWriteTable()], [dbDisconnect()] #' #' Formal specification (currently work in progress and incomplete): #' `vignette("spec", package = "DBI")` "_PACKAGE" has_arrow <- function() { requireNamespace("nanoarrow", quietly = TRUE) } require_arrow <- function() { if (has_arrow()) { return(invisible(TRUE)) } stop("The nanoarrow package is required for this functionality.") } DBI/R/show_SQL.R0000644000176200001440000000033114350241735012674 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL show_SQL <- function(object) { cat(paste0(" ", object@.Data, collapse = "\n"), "\n", sep = "") } #' @rdname hidden_aliases #' @export setMethod("show", "SQL", show_SQL) DBI/R/dbDataType_DBIObject.R0000644000176200001440000000033514350241735015027 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbDataType_DBIObject <- function(dbObj, obj, ...) { dbiDataType(obj) } #' @rdname hidden_aliases #' @export setMethod("dbDataType", signature("DBIObject"), dbDataType_DBIObject) DBI/R/dbGetException.R0000644000176200001440000000073314350241735014107 0ustar liggesusers#' Get DBMS exceptions #' #' DEPRECATED. Backends should use R's condition system to signal errors and #' warnings. #' #' @inheritParams dbGetQuery #' @family DBIConnection generics #' @return a list with elements `errorNum` (an integer error number) and #' `errorMsg` (a character string) describing the last error in the #' connection `conn`. #' @export #' @keywords internal setGeneric("dbGetException", def = function(conn, ...) standardGeneric("dbGetException") ) DBI/R/dbCanConnect_DBIDriver.R0000644000176200001440000000062714350241735015360 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbCanConnect_DBIDriver <- function(drv, ...) { tryCatch( { con <- dbConnect(drv, ...) dbDisconnect(con) TRUE }, error = function(e) { structure( FALSE, reason = conditionMessage(e) ) } ) } #' @rdname hidden_aliases #' @export setMethod("dbCanConnect", signature("DBIDriver"), dbCanConnect_DBIDriver) DBI/R/00-Id.R0000644000176200001440000000414014607456777011773 0ustar liggesusersNULL #' @rdname Id setClass("Id", slots = list(name = "character")) #' Refer to a table nested in a hierarchy (e.g. within a schema) #' #' @description #' Objects of class `Id` have a single slot `name`, which is a character vector. #' The [dbQuoteIdentifier()] method converts `Id` objects to strings. #' Support for `Id` objects depends on the database backend. #' #' They can be used in the following methods as `name` or `table` argument: #' #' - [dbCreateTable()] #' - [dbAppendTable()] #' - [dbReadTable()] #' - [dbWriteTable()] #' - [dbExistsTable()] #' - [dbRemoveTable()] #' #' Objects of this class are also returned from [dbListObjects()]. #' #' @param ... Components of the hierarchy, e.g. `cluster`, #' `catalog`, `schema`, or `table`, depending on the database backend. For more #' on these concepts, see #' @export #' @examples #' # Identifies a table in a specific schema: #' Id("dbo", "Customer") #' # You can name the components if you want, but it's not needed #' Id(table = "Customer", schema = "dbo") #' #' # Create a SQL expression for an identifier: #' dbQuoteIdentifier(ANSI(), Id("nycflights13", "flights")) #' #' # Write a table in a specific schema: #' \dontrun{ #' dbWriteTable(con, Id("myschema", "mytable"), data.frame(a = 1)) #' } Id <- function(...) { components <- orderIdParams(...) if (!is.character(components)) { stop("All elements of `...` must be strings.", call. = FALSE) } new("Id", name = components) } #' @export toString.Id <- function(x, ...) { paste0(" ", dbQuoteIdentifier(ANSI(), x)) } dbQuoteIdentifier_DBIConnection_Id <- function(conn, x, ...) { SQL(paste0(dbQuoteIdentifier(conn, x@name), collapse = ".")) } orderIdParams <- function( ..., database = NULL, db = NULL, catalog = NULL, cluster = NULL, schema = NULL, table = NULL, column = NULL) { out <- c( database = database, db = db, cluster = cluster, catalog = catalog, schema = schema, ..., table = table, column = column ) if (all(names(out) == "")) { out <- unname(out) } out } DBI/R/dbDataType.R0000644000176200001440000000473114602466070013227 0ustar liggesusers#' Determine the SQL data type of an object #' #' Returns an SQL string that describes the SQL data type to be used for an #' object. #' The default implementation of this generic determines the SQL type of an #' R object according to the SQL 92 specification, which may serve as a starting #' point for driver implementations. DBI also provides an implementation #' for data.frame which will return a character vector giving the type for each #' column in the dataframe. #' #' The data types supported by databases are different than the data types in R, #' but the mapping between the primitive types is straightforward: #' - Any of the many fixed and varying length character types are mapped to #' character vectors #' - Fixed-precision (non-IEEE) numbers are mapped into either numeric or #' integer vectors. #' #' Notice that many DBMS do not follow IEEE arithmetic, so there are potential #' problems with under/overflows and loss of precision. #' #' @template methods #' @templateVar method_name dbDataType #' #' @inherit DBItest::spec_driver_data_type return #' @inheritSection DBItest::spec_driver_data_type Failure modes #' @inheritSection DBItest::spec_driver_data_type Specification #' @inheritSection DBItest::spec_result_create_table_with_data_type Specification #' #' @inheritParams dbListConnections #' @param dbObj A object inheriting from [DBIDriver-class] #' or [DBIConnection-class] #' @param obj An R object whose SQL type we want to determine. #' @family DBIDriver generics #' @family DBIConnection generics #' @family DBIConnector generics #' @examples #' dbDataType(ANSI(), 1:5) #' dbDataType(ANSI(), 1) #' dbDataType(ANSI(), TRUE) #' dbDataType(ANSI(), Sys.Date()) #' dbDataType(ANSI(), Sys.time()) #' dbDataType(ANSI(), Sys.time() - as.POSIXct(Sys.Date())) #' dbDataType(ANSI(), c("x", "abc")) #' dbDataType(ANSI(), list(raw(10), raw(20))) #' dbDataType(ANSI(), I(3)) #' #' dbDataType(ANSI(), iris) #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbDataType(con, 1:5) #' dbDataType(con, 1) #' dbDataType(con, TRUE) #' dbDataType(con, Sys.Date()) #' dbDataType(con, Sys.time()) #' dbDataType(con, Sys.time() - as.POSIXct(Sys.Date())) #' dbDataType(con, c("x", "abc")) #' dbDataType(con, list(raw(10), raw(20))) #' dbDataType(con, I(3)) #' #' dbDataType(con, iris) #' #' dbDisconnect(con) #' @export setGeneric("dbDataType", def = function(dbObj, obj, ...) standardGeneric("dbDataType"), valueClass = "character" ) DBI/R/dbFetchArrowChunk.R0000644000176200001440000000305114602466070014543 0ustar liggesusers#' Fetch the next batch of records from a previously executed query as an Arrow object #' #' @description #' `r lifecycle::badge('experimental')` #' #' Fetch the next chunk of the result set and return it as an Arrow object. #' The chunk size is implementation-specific. #' Use [dbFetchArrow()] to fetch all results. #' #' @inheritSection dbBind The data retrieval flow for Arrow streams #' #' @template methods #' @templateVar method_name dbFetchArrowChunk #' #' @inherit DBItest::spec_arrow_fetch_arrow_chunk return #' @inheritSection DBItest::spec_arrow_fetch_arrow_chunk Failure modes #' @inheritSection DBItest::spec_arrow_fetch_arrow_chunk Specification #' #' @param res An object inheriting from [DBIResultArrow-class], created by #' [dbSendQueryArrow()]. #' @param ... Other arguments passed on to methods. #' @seealso Close the result set with [dbClearResult()] as soon as you #' finish retrieving the records you want. #' @family DBIResultArrow generics #' @family data retrieval generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' #' # Fetch all results #' rs <- dbSendQueryArrow(con, "SELECT * FROM mtcars WHERE cyl = 4") #' dbHasCompleted(rs) #' as.data.frame(dbFetchArrowChunk(rs)) #' dbHasCompleted(rs) #' as.data.frame(dbFetchArrowChunk(rs)) #' dbClearResult(rs) #' #' dbDisconnect(con) setGeneric("dbFetchArrowChunk", def = function(res, ...) standardGeneric("dbFetchArrowChunk") ) DBI/R/dbClearResult_DBIResultArrow.R0000644000176200001440000000037414602466070016630 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbClearResult_DBIResultArrow <- function(res, ...) { dbClearResult(res@result, ...) } #' @rdname hidden_aliases #' @export setMethod("dbClearResult", signature("DBIResultArrow"), dbClearResult_DBIResultArrow) DBI/R/dbFetchArrowChunk_DBIResultArrow.R0000644000176200001440000000046214602466070017436 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbFetchArrowChunk_DBIResultArrow <- function(res, ...) { nanoarrow::as_nanoarrow_array( dbFetch(res@result, n = 256, ...) ) } #' @rdname hidden_aliases #' @export setMethod("dbFetchArrowChunk", signature("DBIResultArrow"), dbFetchArrowChunk_DBIResultArrow) DBI/R/dbHasCompleted_DBIResultArrow.R0000644000176200001440000000040014602466070016741 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbHasCompleted_DBIResultArrow <- function(res, ...) { dbHasCompleted(res@result, ...) } #' @rdname hidden_aliases #' @export setMethod("dbHasCompleted", signature("DBIResultArrow"), dbHasCompleted_DBIResultArrow) DBI/R/dbConnect_DBIConnector.R0000644000176200001440000000135514350241735015434 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbConnect_DBIConnector <- function(drv, ...) { dots_args <- list(...) has_name <- names2(dots_args) != "" # Unnamed dots come first (they are not picked up by modifyList()) unnamed_dots <- dots_args[!has_name] # Named dots come last, an extra drv argument is erased silently named_dots <- dots_args[has_name] named_dots$drv <- NULL # Named dots are supplemented with connector args extra_args <- utils::modifyList( dbGetConnectArgs(drv), named_dots ) all_args <- c( list(drv = drv@.drv), unnamed_dots, extra_args ) do.call(dbConnect, all_args) } #' @rdname hidden_aliases #' @export setMethod("dbConnect", signature("DBIConnector"), dbConnect_DBIConnector) DBI/R/dbSetDataMappings.R0000644000176200001440000000142214350241735014531 0ustar liggesusers#' Set data mappings between an DBMS and R. #' #' This generic is deprecated since no working implementation was ever produced. #' #' Sets one or more conversion functions to handle the translation of DBMS data #' types to R objects. This is only needed for non-primitive data, since all #' DBI drivers handle the common base types (integers, numeric, strings, etc.) #' #' The details on conversion functions (e.g., arguments, whether they can invoke #' initializers and/or destructors) have not been specified. #' #' @inheritParams dbClearResult #' @keywords internal #' @param flds a field description object as returned by `dbColumnInfo`. #' @export setGeneric("dbSetDataMappings", def = function(res, flds, ...) { .Deprecated() standardGeneric("dbSetDataMappings") } ) DBI/R/dbExistsTable.R0000644000176200001440000000137614602466070013745 0ustar liggesusers#' Does a table exist? #' #' Returns if a table given by name exists in the database. #' #' @template methods #' @templateVar method_name dbExistsTable #' #' @inherit DBItest::spec_sql_exists_table return #' @inheritSection DBItest::spec_sql_exists_table Failure modes #' @inheritSection DBItest::spec_sql_exists_table Specification #' #' @inheritParams dbReadTable #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbExistsTable(con, "iris") #' dbWriteTable(con, "iris", iris) #' dbExistsTable(con, "iris") #' #' dbDisconnect(con) setGeneric("dbExistsTable", def = function(conn, name, ...) standardGeneric("dbExistsTable"), valueClass = "logical" ) DBI/R/03-DBIConnection.R0000644000176200001440000000217614627140170014042 0ustar liggesusers#' DBIConnection class #' #' This virtual class encapsulates the connection to a DBMS, and it provides #' access to dynamic queries, result sets, DBMS session management #' (transactions), etc. #' #' @section Implementation note: #' Individual drivers are free to implement single or multiple simultaneous #' connections. #' #' @docType class #' @name DBIConnection-class #' @family DBI classes #' @family DBIConnection generics #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' con #' dbDisconnect(con) #' \dontrun{ #' con <- dbConnect(RPostgreSQL::PostgreSQL(), "username", "password") #' con #' dbDisconnect(con) #' } #' @export setClass("DBIConnection", contains = c("DBIObject", "VIRTUAL")) show_connection <- function(object) { cat("<", is(object)[1], ">\n", sep = "") if (!dbIsValid(object)) { cat(" DISCONNECTED\n") } } list_fields <- function(conn, name) { rs <- dbSendQuery( conn, paste( "SELECT * FROM ", dbQuoteIdentifier(conn, name), "LIMIT 0" ) ) on.exit(dbClearResult(rs)) names(dbFetch(rs, n = 0, row.names = FALSE)) } DBI/R/isSQLKeyword.R0000644000176200001440000000040514350241735013537 0ustar liggesusers#' @rdname make.db.names #' @export setGeneric("isSQLKeyword", def = function(dbObj, name, keywords = .SQL92Keywords, case = c("lower", "upper", "any")[3], ...) standardGeneric("isSQLKeyword"), signature = c("dbObj", "name"), valueClass = "logical" ) DBI/R/dbRemoveTable.R0000644000176200001440000000161314602466070013715 0ustar liggesusers#' Remove a table from the database #' #' Remove a remote table (e.g., created by [dbWriteTable()]) #' from the database. #' #' @template methods #' @templateVar method_name dbRemoveTable #' #' @inherit DBItest::spec_sql_remove_table return #' @inheritSection DBItest::spec_sql_remove_table Failure modes #' @inheritSection DBItest::spec_sql_remove_table Additional arguments #' @inheritSection DBItest::spec_sql_remove_table Specification #' #' @inheritParams dbReadTable #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbExistsTable(con, "iris") #' dbWriteTable(con, "iris", iris) #' dbExistsTable(con, "iris") #' dbRemoveTable(con, "iris") #' dbExistsTable(con, "iris") #' #' dbDisconnect(con) setGeneric("dbRemoveTable", def = function(conn, name, ...) standardGeneric("dbRemoveTable") ) DBI/R/dbBind_DBIResultArrow.R0000644000176200001440000000041214602466070015250 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbBind_DBIResultArrow <- function(res, params, ...) { dbBind(res@result, params = params, ...) invisible(res) } #' @rdname hidden_aliases #' @export setMethod("dbBind", signature("DBIResultArrow"), dbBind_DBIResultArrow) DBI/R/dbiDataType_default.R0000644000176200001440000000040114602466070015072 0ustar liggesusersdbiDataType_default <- function(x) { if (inherits(x, c("blob", "arrow_binary"))) { return("BLOB") } stop("SQL type unknown for objects of class ", paste(class(x), collapse = "/")) } setMethod("dbiDataType", signature("ANY"), dbiDataType_default) DBI/R/dbGetQueryArrow.R0000644000176200001440000000447614602466070014302 0ustar liggesusers#' Retrieve results from a query as an Arrow object #' #' @description #' `r lifecycle::badge('experimental')` #' #' Returns the result of a query as an Arrow object. #' `dbGetQueryArrow()` comes with a default implementation #' (which should work with most backends) that calls #' [dbSendQueryArrow()], then [dbFetchArrow()], ensuring that #' the result is always freed by [dbClearResult()]. #' For passing query parameters, #' see [dbSendQueryArrow()], in particular #' the "The data retrieval flow for Arrow streams" section. #' For retrieving results as a data frame, see [dbGetQuery()]. #' #' @details #' This method is for `SELECT` queries only #' (incl. other SQL statements that return a `SELECT`-alike result, #' e.g., execution of a stored procedure or data manipulation queries #' like `INSERT INTO ... RETURNING ...`). #' To execute a stored procedure that does not return a result set, #' use [dbExecute()]. #' #' Some backends may #' support data manipulation statements through this method. #' However, callers are strongly advised to use #' [dbExecute()] for data manipulation statements. #' #' @template methods #' @templateVar method_name dbGetQueryArrow #' #' @inherit DBItest::spec_arrow_get_query_arrow return #' @inheritSection DBItest::spec_arrow_get_query_arrow Failure modes #' @inheritSection DBItest::spec_arrow_get_query_arrow Additional arguments #' @inheritSection DBItest::spec_arrow_get_query_arrow Specification for the `immediate` argument #' #' @section Implementation notes: #' Subclasses should override this method only if they provide some sort of #' performance optimization. #' #' @param conn A [DBIConnection-class] object, as returned by #' [dbConnect()]. #' @param statement a character string containing SQL. #' @param ... Other parameters passed on to methods. #' @family DBIConnection generics #' @family data retrieval generics #' @seealso For updates: [dbSendStatement()] and [dbExecute()]. #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE) #' # Retrieve data as arrow table #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' dbGetQueryArrow(con, "SELECT * FROM mtcars") #' #' dbDisconnect(con) setGeneric("dbGetQueryArrow", def = function(conn, statement, ...) standardGeneric("dbGetQueryArrow") ) DBI/R/data.R0000644000176200001440000000162214350241735012112 0ustar liggesusersNULL # Coercion rules --------------------------------------------------------------- coerce <- function(sqlvar, from, to) { list(from = from, to = to) } sqlDate <- function() { coerce( function(x) as.integer(x), function(x) { stopifnot(is.integer(x)) structure(x, class = "Date") } ) } sqlDateTime <- function() { coerce( function(x) as.numeric(x), function(x) { stopifnot(is.numeric(x)) structure(x, class = c("POSIXct", "POSIXt"), tzone = "UTC") } ) } sqlSerialize <- function() { coerce( function(x) { lapply(x, serialize, connection = NULL) }, function(x) { lapply(x, unserialize) } ) } sqlBoolean <- function() { coerce( function(x) as.integer(x), function(x) as.logical(x) ) } sqlFactor <- function(levels) { coerce( function(x) as.integer(x), function(x) factor(x, levels = levels) ) } DBI/R/15-dbBind.R0000644000176200001440000002167714614477037012633 0ustar liggesusers#' Bind values to a parameterized/prepared statement #' #' @description #' For parametrized or prepared statements, #' the [dbSendQuery()], [dbSendQueryArrow()], and [dbSendStatement()] functions #' can be called with statements that contain placeholders for values. #' The `dbBind()` and `dbBindArrow()` functions bind these placeholders #' to actual values, #' and are intended to be called on the result set #' before calling [dbFetch()] or [dbFetchArrow()]. #' The values are passed to `dbBind()` as lists or data frames, #' and to `dbBindArrow()` as a stream #' created by [nanoarrow::as_nanoarrow_array_stream()]. #' #' `r lifecycle::badge('experimental')` #' #' `dbBindArrow()` is experimental, as are the other `*Arrow` functions. #' `dbSendQuery()` is compatible with `dbBindArrow()`, and `dbSendQueryArrow()` #' is compatible with `dbBind()`. #' #' @details #' \pkg{DBI} supports parametrized (or prepared) queries and statements #' via the `dbBind()` and `dbBindArrow()` generics. #' Parametrized queries are different from normal queries #' in that they allow an arbitrary number of placeholders, #' which are later substituted by actual values. #' Parametrized queries (and statements) serve two purposes: #' #' - The same query can be executed more than once with different values. #' The DBMS may cache intermediate information for the query, #' such as the execution plan, and execute it faster. #' - Separation of query syntax and parameters protects against SQL injection. #' #' The placeholder format is currently not specified by \pkg{DBI}; #' in the future, a uniform placeholder syntax may be supported. #' Consult the backend documentation for the supported formats. #' For automated testing, backend authors specify the placeholder syntax with #' the `placeholder_pattern` tweak. #' Known examples are: #' #' - `?` (positional matching in order of appearance) in \pkg{RMariaDB} and \pkg{RSQLite} #' - `$1` (positional matching by index) in \pkg{RPostgres} and \pkg{RSQLite} #' - `:name` and `$name` (named matching) in \pkg{RSQLite} #' #' @section The data retrieval flow: #' #' This section gives a complete overview over the flow #' for the execution of queries that return tabular data as data frames. #' #' Most of this flow, except repeated calling of [dbBind()] or [dbBindArrow()], #' is implemented by [dbGetQuery()], which should be sufficient #' unless you want to access the results in a paged way #' or you have a parameterized query that you want to reuse. #' This flow requires an active connection established by [dbConnect()]. #' See also `vignette("dbi-advanced")` for a walkthrough. #' #' 1. Use [dbSendQuery()] to create a result set object of class #' [DBIResult-class]. #' 1. Optionally, bind query parameters with [dbBind()] or [dbBindArrow()]. #' This is required only if the query contains placeholders #' such as `?` or `$1`, depending on the database backend. #' 1. Optionally, use [dbColumnInfo()] to retrieve the structure of the result set #' without retrieving actual data. #' 1. Use [dbFetch()] to get the entire result set, a page of results, #' or the remaining rows. #' Fetching zero rows is also possible to retrieve the structure of the result set #' as a data frame. #' This step can be called multiple times. #' Only forward paging is supported, you need to cache previous pages #' if you need to navigate backwards. #' 1. Use [dbHasCompleted()] to tell when you're done. #' This method returns `TRUE` if no more rows are available for fetching. #' 1. Repeat the last four steps as necessary. #' 1. Use [dbClearResult()] to clean up the result set object. #' This step is mandatory even if no rows have been fetched #' or if an error has occurred during the processing. #' It is good practice to use [on.exit()] or [withr::defer()] #' to ensure that this step is always executed. #' #' @section The data retrieval flow for Arrow streams: #' #' This section gives a complete overview over the flow #' for the execution of queries that return tabular data as an Arrow stream. #' #' Most of this flow, except repeated calling of [dbBindArrow()] or [dbBind()], #' is implemented by [dbGetQueryArrow()], #' which should be sufficient #' unless you have a parameterized query that you want to reuse. #' This flow requires an active connection established by [dbConnect()]. #' See also `vignette("dbi-advanced")` for a walkthrough. #' #' 1. Use [dbSendQueryArrow()] to create a result set object of class #' [DBIResultArrow-class]. #' 1. Optionally, bind query parameters with [dbBindArrow()] or [dbBind()]. #' This is required only if the query contains placeholders #' such as `?` or `$1`, depending on the database backend. #' 1. Use [dbFetchArrow()] to get a data stream. #' 1. Repeat the last two steps as necessary. #' 1. Use [dbClearResult()] to clean up the result set object. #' This step is mandatory even if no rows have been fetched #' or if an error has occurred during the processing. #' It is good practice to use [on.exit()] or [withr::defer()] #' to ensure that this step is always executed. #' #' @section The command execution flow: #' #' This section gives a complete overview over the flow #' for the execution of SQL statements that have side effects #' such as stored procedures, inserting or deleting data, #' or setting database or connection options. #' Most of this flow, except repeated calling of [dbBindArrow()], #' is implemented by [dbExecute()], which should be sufficient #' for non-parameterized queries. #' This flow requires an active connection established by [dbConnect()]. #' See also `vignette("dbi-advanced")` for a walkthrough. #' #' 1. Use [dbSendStatement()] to create a result set object of class #' [DBIResult-class]. #' For some queries you need to pass `immediate = TRUE`. #' 1. Optionally, bind query parameters with[dbBind()] or [dbBindArrow()]. #' This is required only if the query contains placeholders #' such as `?` or `$1`, depending on the database backend. #' 1. Optionally, use [dbGetRowsAffected()] to retrieve the number #' of rows affected by the query. #' 1. Repeat the last two steps as necessary. #' 1. Use [dbClearResult()] to clean up the result set object. #' This step is mandatory even if no rows have been fetched #' or if an error has occurred during the processing. #' It is good practice to use [on.exit()] or [withr::defer()] #' to ensure that this step is always executed. #' #' @template methods #' @templateVar method_name dbBind #' #' @inherit DBItest::spec_meta_bind return #' @inheritSection DBItest::spec_meta_bind Failure modes #' @inheritSection DBItest::spec_meta_bind Specification #' #' @inheritParams dbClearResult #' @param params For `dbBind()`, a list of values, named or unnamed, #' or a data frame, with one element/column per query parameter. #' For `dbBindArrow()`, values as a nanoarrow stream, #' with one column per query parameter. #' @family DBIResult generics #' @family DBIResultArrow generics #' @family data retrieval generics #' @family command execution generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' # Data frame flow: #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "iris", iris) #' #' # Using the same query for different values #' iris_result <- dbSendQuery(con, "SELECT * FROM iris WHERE [Petal.Width] > ?") #' dbBind(iris_result, list(2.3)) #' dbFetch(iris_result) #' dbBind(iris_result, list(3)) #' dbFetch(iris_result) #' dbClearResult(iris_result) #' #' # Executing the same statement with different values at once #' iris_result <- dbSendStatement(con, "DELETE FROM iris WHERE [Species] = $species") #' dbBind(iris_result, list(species = c("setosa", "versicolor", "unknown"))) #' dbGetRowsAffected(iris_result) #' dbClearResult(iris_result) #' #' nrow(dbReadTable(con, "iris")) #' #' dbDisconnect(con) #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE) #' #' # Arrow flow: #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "iris", iris) #' #' # Using the same query for different values #' iris_result <- dbSendQueryArrow(con, "SELECT * FROM iris WHERE [Petal.Width] > ?") #' dbBindArrow( #' iris_result, #' nanoarrow::as_nanoarrow_array_stream(data.frame(2.3, fix.empty.names = FALSE)) #' ) #' as.data.frame(dbFetchArrow(iris_result)) #' dbBindArrow( #' iris_result, #' nanoarrow::as_nanoarrow_array_stream(data.frame(3, fix.empty.names = FALSE)) #' ) #' as.data.frame(dbFetchArrow(iris_result)) #' dbClearResult(iris_result) #' #' # Executing the same statement with different values at once #' iris_result <- dbSendStatement(con, "DELETE FROM iris WHERE [Species] = $species") #' dbBindArrow(iris_result, nanoarrow::as_nanoarrow_array_stream(data.frame( #' species = c("setosa", "versicolor", "unknown") #' ))) #' dbGetRowsAffected(iris_result) #' dbClearResult(iris_result) #' #' nrow(dbReadTable(con, "iris")) #' #' dbDisconnect(con) setGeneric("dbBind", def = function(res, params, ...) standardGeneric("dbBind") ) DBI/R/04-DBIResult.R0000644000176200001440000000270714602466070013225 0ustar liggesusersNULL #' DBIResult class #' #' This virtual class describes the result and state of execution of #' a DBMS statement (any statement, query or non-query). The result set #' keeps track of whether the statement produces output how many rows were #' affected by the operation, how many rows have been fetched (if statement is #' a query), whether there are more rows to fetch, etc. #' #' @section Implementation notes: #' Individual drivers are free to allow single or multiple #' active results per connection. #' #' The default show method displays a summary of the query using other #' DBI generics. #' #' @name DBIResult-class #' @docType class #' @family DBI classes #' @family DBIResult generics #' @export setClass("DBIResult", contains = c("DBIObject", "VIRTUAL")) show_result <- function(object) { cat("<", is(object)[1], ">\n", sep = "") if (!dbIsValid(object)) { cat("EXPIRED\n") } else { cat(" SQL ", dbGetStatement(object), "\n", sep = "") done <- if (dbHasCompleted(object)) "complete" else "incomplete" cat(" ROWS Fetched: ", dbGetRowCount(object), " [", done, "]\n", sep = "") cat(" Changed: ", dbGetRowsAffected(object), "\n", sep = "") } } #' @name dbGetInfo #' @section Implementation notes: #' The default implementation for `DBIResult objects` #' constructs such a list from the return values of the corresponding methods, #' [dbGetStatement()], [dbGetRowCount()], #' [dbGetRowsAffected()], and [dbHasCompleted()]. NULL DBI/R/dbGetRowCount_DBIResultArrow.R0000644000176200001440000000037414602466070016623 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbGetRowCount_DBIResultArrow <- function(res, ...) { dbGetRowCount(res@result, ...) } #' @rdname hidden_aliases #' @export setMethod("dbGetRowCount", signature("DBIResultArrow"), dbGetRowCount_DBIResultArrow) DBI/R/13-dbWriteTable.R0000644000176200001440000000364514602466070014002 0ustar liggesusers#' Copy data frames to database tables #' #' Writes, overwrites or appends a data frame to a database table, optionally #' converting row names to a column and specifying SQL data types for fields. #' #' @details #' This function expects a data frame. #' Use [dbWriteTableArrow()] to write an Arrow object. #' #' This function is useful if you want to create and load a table at the same time. #' Use [dbAppendTable()] or [dbAppendTableArrow()] for appending data to an existing #' table, [dbCreateTable()] or [dbCreateTableArrow()] for creating a table, #' and [dbExistsTable()] and [dbRemoveTable()] for overwriting tables. #' #' DBI only standardizes writing data frames with `dbWriteTable()`. #' Some backends might implement methods that can consume CSV files #' or other data formats. #' For details, see the documentation for the individual methods. #' #' @template methods #' @templateVar method_name dbWriteTable #' #' @inherit DBItest::spec_sql_write_table return #' @inheritSection DBItest::spec_sql_write_table Failure modes #' @inheritSection DBItest::spec_sql_write_table Additional arguments #' @inheritSection DBItest::spec_sql_write_table Specification #' #' @inheritParams dbGetQuery #' @inheritParams dbReadTable #' @param value A [data.frame] (or coercible to data.frame). #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars[1:5, ]) #' dbReadTable(con, "mtcars") #' #' dbWriteTable(con, "mtcars", mtcars[6:10, ], append = TRUE) #' dbReadTable(con, "mtcars") #' #' dbWriteTable(con, "mtcars", mtcars[1:10, ], overwrite = TRUE) #' dbReadTable(con, "mtcars") #' #' # No row names #' dbWriteTable(con, "mtcars", mtcars[1:10, ], overwrite = TRUE, row.names = FALSE) #' dbReadTable(con, "mtcars") setGeneric("dbWriteTable", def = function(conn, name, value, ...) standardGeneric("dbWriteTable") ) DBI/R/21-dbAppendTableArrow.R0000644000176200001440000000240014602466070015115 0ustar liggesusers#' Insert rows into a table from an Arrow stream #' #' @description #' `r lifecycle::badge('experimental')` #' #' The `dbAppendTableArrow()` method assumes that the table has been created #' beforehand, e.g. with [dbCreateTableArrow()]. #' The default implementation calls [dbAppendTable()] for each chunk #' of the stream. #' Use [dbAppendTable()] to append data from a data.frame. #' #' @inheritParams dbReadTable #' @param value An object coercible with [nanoarrow::as_nanoarrow_array_stream()]. #' @inheritParams sqlAppendTableTemplate #' #' @template methods #' @templateVar method_name dbAppendTableArrow #' #' @inherit DBItest::spec_arrow_append_table_arrow return #' @inheritSection DBItest::spec_arrow_append_table_arrow Failure modes #' @inheritSection DBItest::spec_arrow_append_table_arrow Specification #' #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' dbCreateTableArrow(con, "iris", iris[0, ]) #' dbAppendTableArrow(con, "iris", iris[1:5, ]) #' dbReadTable(con, "iris") #' dbDisconnect(con) setGeneric("dbAppendTableArrow", def = function(conn, name, value, ...) standardGeneric("dbAppendTableArrow") ) DBI/R/dbGetRowCount.R0000644000176200001440000000162014602466070013726 0ustar liggesusers#' The number of rows fetched so far #' #' Returns the total number of rows actually fetched with calls to [dbFetch()] #' for this result set. #' #' @template methods #' @templateVar method_name dbGetRowCount #' #' @inherit DBItest::spec_meta_get_row_count return #' @inheritSection DBItest::spec_meta_get_row_count Failure modes #' #' @inheritParams dbClearResult #' @family DBIResult generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' rs <- dbSendQuery(con, "SELECT * FROM mtcars") #' #' dbGetRowCount(rs) #' ret1 <- dbFetch(rs, 10) #' dbGetRowCount(rs) #' ret2 <- dbFetch(rs) #' dbGetRowCount(rs) #' nrow(ret1) + nrow(ret2) #' #' dbClearResult(rs) #' dbDisconnect(con) setGeneric("dbGetRowCount", def = function(res, ...) standardGeneric("dbGetRowCount"), valueClass = "numeric" ) DBI/R/sqlCreateTable_DBIConnection.R0000644000176200001440000000166014350241735016574 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL sqlCreateTable_DBIConnection <- function(con, table, fields, row.names = NA, temporary = FALSE, ...) { if (missing(row.names)) { warning("Do not rely on the default value of the row.names argument for sqlCreateTable(), it will change in the future.", call. = FALSE ) } table <- dbQuoteIdentifier(con, table) if (is.data.frame(fields)) { fields <- sqlRownamesToColumn(fields, row.names) fields <- vapply(fields, function(x) DBI::dbDataType(con, x), character(1)) } field_names <- dbQuoteIdentifier(con, names(fields)) field_types <- unname(fields) fields <- paste0(field_names, " ", field_types) SQL(paste0( "CREATE ", if (temporary) "TEMPORARY ", "TABLE ", table, " (\n", " ", paste(fields, collapse = ",\n "), "\n)\n" )) } #' @rdname hidden_aliases #' @export setMethod("sqlCreateTable", signature("DBIConnection"), sqlCreateTable_DBIConnection) DBI/R/dbWriteTableArrow_DBIConnection.R0000644000176200001440000000205514602466070017264 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbWriteTableArrow_DBIConnection <- function(conn, name, value, append = FALSE, overwrite = FALSE, ..., temporary = FALSE) { require_arrow() stopifnot(is.logical(append)) stopifnot(length(append) == 1) stopifnot(!is.na(append)) stopifnot(is.logical(overwrite)) stopifnot(length(overwrite) == 1) stopifnot(!is.na(overwrite)) stopifnot(is.logical(temporary)) stopifnot(length(temporary) == 1) stopifnot(!is.na(temporary)) name <- dbQuoteIdentifier(conn, name) value <- nanoarrow::as_nanoarrow_array_stream(value) if (overwrite && append) { stop("overwrite and append cannot both be TRUE") } exists <- dbExistsTable(conn, name) if (overwrite && exists) { dbRemoveTable(conn, name) } if (overwrite || !append || !exists) { dbCreateTableArrow(conn, name, value, temporary = temporary) } dbAppendTableArrow(conn, name, value) invisible(TRUE) } #' @rdname hidden_aliases #' @export setMethod("dbWriteTableArrow", signature("DBIConnection"), dbWriteTableArrow_DBIConnection) DBI/R/hms.R0000644000176200001440000000401014350241735011762 0ustar liggesusers# from hms format_hms <- function(x) { units(x) <- "secs" xx <- decompose(x) ifelse(is.na(x), NA_character_, paste0( ifelse(xx$sign, "-", ""), format_hours(xx$hours), ":", format_two_digits(xx$minute_of_hour), ":", format_two_digits(xx$second_of_minute), format_tics(xx$tics))) } format_hours <- function(x) { # Difference to hms: don't justify here format_two_digits(x) } format_two_digits <- function(x) { formatC(x, format = "f", digits = 0, width = 2, flag = "0") } format_tics <- function(x) { x <- x / TICS_PER_SECOND out <- format(x, scientific = FALSE, digits = SPLIT_SECOND_DIGITS + 1L) digits <- max(min(max(nchar(out) - 2), SPLIT_SECOND_DIGITS), 0) out <- formatC(x, format = "f", digits = digits) gsub("^0", "", out) } SPLIT_SECOND_DIGITS <- 6L TICS_PER_SECOND <- 10^SPLIT_SECOND_DIGITS SECONDS_PER_MINUTE <- 60 MINUTES_PER_HOUR <- 60 HOURS_PER_DAY <- 24 TICS_PER_MINUTE <- SECONDS_PER_MINUTE * TICS_PER_SECOND TICS_PER_HOUR <- MINUTES_PER_HOUR * TICS_PER_MINUTE TICS_PER_DAY <- HOURS_PER_DAY * TICS_PER_HOUR days <- function(x) { trunc(x / TICS_PER_DAY) } hours <- function(x) { trunc(x / TICS_PER_HOUR) } hour_of_day <- function(x) { abs(hours(x) - days(x) * HOURS_PER_DAY) } minutes <- function(x) { trunc(x / TICS_PER_MINUTE) } minute_of_hour <- function(x) { abs(minutes(x) - hours(x) * MINUTES_PER_HOUR) } seconds <- function(x) { trunc(x / TICS_PER_SECOND) } second_of_minute <- function(x) { abs(seconds(x) - minutes(x) * SECONDS_PER_MINUTE) } tics <- function(x) { x } tic_of_second <- function(x) { abs(tics(x) - seconds(x) * TICS_PER_SECOND) } decompose <- function(x) { x <- unclass(x) * TICS_PER_SECOND # #140 xr <- round(x) out <- list( sign = xr < 0 & !is.na(xr), hours = abs(hours(xr)), minute_of_hour = minute_of_hour(xr), second_of_minute = second_of_minute(xr), tics = tic_of_second(xr) ) # #140: Make sure zeros are printed fake_zero <- (out$tics == 0) & (xr != x) out$tics[fake_zero] <- 0.25 out } DBI/R/show_DBIResult.R0000644000176200001440000000060514350241735014036 0ustar liggesusers#' @rdname hidden_aliases #' @param object Object to display #' @usage NULL show_DBIResult <- function(object) { # to protect drivers that fail to implement the required methods (e.g., # RPostgreSQL) tryCatch( show_result(object), error = function(e) NULL ) invisible(NULL) } #' @rdname hidden_aliases #' @export setMethod("show", signature("DBIResult"), show_DBIResult) DBI/R/dbQuoteIdentifier.R0000644000176200001440000000263414602466070014614 0ustar liggesusers#' Quote identifiers #' #' Call this method to generate a string that is suitable for #' use in a query as a column or table name, to make sure that you #' generate valid SQL and protect against SQL injection attacks. The inverse #' operation is [dbUnquoteIdentifier()]. #' #' @inheritParams dbGetQuery #' @param x A character vector, [SQL] or [Id] object to quote as identifier. #' @param ... Other arguments passed on to methods. #' #' @template methods #' @templateVar method_name dbQuoteIdentifier #' #' @inherit DBItest::spec_sql_quote_identifier return #' @inheritSection DBItest::spec_sql_quote_identifier Failure modes #' @inheritSection DBItest::spec_sql_quote_identifier Specification #' #' @family DBIConnection generics #' @export #' @examples #' # Quoting ensures that arbitrary input is safe for use in a query #' name <- "Robert'); DROP TABLE Students;--" #' dbQuoteIdentifier(ANSI(), name) #' #' # Use Id() to specify other components such as the schema #' id_name <- Id(schema = "schema_name", table = "table_name") #' id_name #' dbQuoteIdentifier(ANSI(), id_name) #' #' # SQL vectors are always passed through as is #' var_name <- SQL("select") #' var_name #' dbQuoteIdentifier(ANSI(), var_name) #' #' # This mechanism is used to prevent double escaping #' dbQuoteIdentifier(ANSI(), dbQuoteIdentifier(ANSI(), name)) setGeneric("dbQuoteIdentifier", def = function(conn, x, ...) standardGeneric("dbQuoteIdentifier") ) DBI/R/sqlInterpolate_DBIConnection.R0000644000176200001440000000244714350241735016713 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL sqlInterpolate_DBIConnection <- function(conn, sql, ..., .dots = list()) { pos <- sqlParseVariables(conn, sql) if (length(pos$start) == 0) { return(SQL(sql)) } vars <- substring(sql, pos$start + 1, pos$end) positional_vars <- pos$start == pos$end if (all(positional_vars) != any(positional_vars)) { stop("Can't mix positional (?) and named (?asdf) variables", call. = FALSE) } values <- c(list(...), .dots) if (all(positional_vars)) { if (length(vars) != length(values)) { stop("Supplied values don't match positional vars to interpolate", call. = FALSE) } if (any(names(values) != "")) { stop("Positional variables don't take named arguments") } } else { if (!setequal(vars, names(values))) { stop("Supplied values don't match named vars to interpolate", call. = FALSE) } values <- values[vars] } safe_values <- vapply(values, function(x) dbQuoteLiteral(conn, x), character(1)) for (i in rev(seq_along(vars))) { sql <- paste0( substring(sql, 0, pos$start[i] - 1), safe_values[i], substring(sql, pos$end[i] + 1, nchar(sql)) ) } SQL(sql) } #' @rdname hidden_aliases #' @export setMethod("sqlInterpolate", signature("DBIConnection"), sqlInterpolate_DBIConnection) DBI/R/dbListConnections.R0000644000176200001440000000072414350241735014627 0ustar liggesusers#' List currently open connections #' #' DEPRECATED, drivers are no longer required to implement this method. #' Keep track of the connections you opened if you require a list. #' #' @param drv A object inheriting from [DBIDriver-class] #' @param ... Other arguments passed on to methods. #' @family DBIDriver generics #' @keywords internal #' @export #' @return a list setGeneric("dbListConnections", def = function(drv, ...) standardGeneric("dbListConnections") ) DBI/R/sqlData.R0000644000176200001440000000206014602466070012570 0ustar liggesusers#' Convert a data frame into form suitable for upload to an SQL database #' #' This is a generic method that coerces R objects into vectors suitable for #' upload to the database. The output will vary a little from method to #' method depending on whether the main upload device is through a single #' SQL string or multiple parameterized queries. #' This method is mostly useful for backend implementers. #' #' The default method: #' #' - Converts factors to characters #' - Quotes all strings with [dbQuoteIdentifier()] #' - Converts all columns to strings with [dbQuoteLiteral()] #' - Replaces NA with NULL #' #' @inheritParams sqlCreateTable #' @inheritParams rownames #' @param value A data frame #' #' @template methods #' @templateVar method_name sqlData #' #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' sqlData(con, head(iris)) #' sqlData(con, head(mtcars)) #' #' dbDisconnect(con) setGeneric("sqlData", def = function(con, value, row.names = NA, ...) standardGeneric("sqlData") ) DBI/R/14-dbSendQuery.R0000644000176200001440000000530014602466070013646 0ustar liggesusers#' Execute a query on a given database connection #' #' The `dbSendQuery()` method only submits and synchronously executes the #' SQL query to the database engine. It does \emph{not} extract any #' records --- for that you need to use the [dbFetch()] method, and #' then you must call [dbClearResult()] when you finish fetching the #' records you need. #' For interactive use, you should almost always prefer [dbGetQuery()]. #' Use [dbSendQueryArrow()] or [dbGetQueryArrow()] instead to retrieve the results #' as an Arrow object. #' #' This method is for `SELECT` queries only. Some backends may #' support data manipulation queries through this method for compatibility #' reasons. However, callers are strongly encouraged to use #' [dbSendStatement()] for data manipulation statements. #' #' The query is submitted to the database server and the DBMS executes it, #' possibly generating vast amounts of data. Where these data live #' is driver-specific: some drivers may choose to leave the output on the server #' and transfer them piecemeal to R, others may transfer all the data to the #' client -- but not necessarily to the memory that R manages. See individual #' drivers' `dbSendQuery()` documentation for details. #' #' @inheritSection dbBind The data retrieval flow #' #' @template methods #' @templateVar method_name dbSendQuery #' #' @inherit DBItest::spec_result_send_query return #' @inheritSection DBItest::spec_result_send_query Failure modes #' @inheritSection DBItest::spec_result_send_query Additional arguments #' @inheritSection DBItest::spec_result_send_query Specification #' @inheritSection DBItest::spec_result_send_query Specification for the `immediate` argument #' #' @inheritParams dbGetQuery #' @param statement a character string containing SQL. #' #' @family DBIConnection generics #' @family data retrieval generics #' @seealso For updates: [dbSendStatement()] and [dbExecute()]. #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") #' dbFetch(rs) #' dbClearResult(rs) #' #' # Pass one set of values with the param argument: #' rs <- dbSendQuery( #' con, #' "SELECT * FROM mtcars WHERE cyl = ?", #' params = list(4L) #' ) #' dbFetch(rs) #' dbClearResult(rs) #' #' # Pass multiple sets of values with dbBind(): #' rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = ?") #' dbBind(rs, list(6L)) #' dbFetch(rs) #' dbBind(rs, list(8L)) #' dbFetch(rs) #' dbClearResult(rs) #' #' dbDisconnect(con) #' @export setGeneric("dbSendQuery", def = function(conn, statement, ...) standardGeneric("dbSendQuery"), valueClass = "DBIResult" ) DBI/R/dbListResults.R0000644000176200001440000000100614350241735014000 0ustar liggesusers#' A list of all pending results #' #' DEPRECATED. DBI currenty supports only one open result set per connection, #' you need to keep track of the result sets you open if you need this #' functionality. #' #' @inheritParams dbGetQuery #' @family DBIConnection generics #' @return a list. If no results are active, an empty list. If only #' a single result is active, a list with one element. #' @export #' @keywords internal setGeneric("dbListResults", def = function(conn, ...) standardGeneric("dbListResults") ) DBI/R/SQLKeywords_missing.R0000644000176200001440000000033414350241735015120 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL SQLKeywords_missing <- function(dbObj, ...) .SQL92Keywords #' @rdname hidden_aliases setMethod("SQLKeywords", signature("missing"), SQLKeywords_missing, valueClass = "character") DBI/R/show_AnsiConnection.R0000644000176200001440000000032014350241735015145 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL show_AnsiConnection <- function(object) { cat("\n") } #' @rdname hidden_aliases #' @export setMethod("show", "AnsiConnection", show_AnsiConnection) DBI/R/isSQLKeyword_DBIObject_character.R0000644000176200001440000000050714350241735017363 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL isSQLKeyword_DBIObject_character <- function(dbObj, name, keywords, case, ...) isSQLKeyword.default(name, keywords, case) #' @rdname hidden_aliases setMethod("isSQLKeyword", signature(dbObj = "DBIObject", name = "character"), isSQLKeyword_DBIObject_character, valueClass = "logical") DBI/R/dbListFields.R0000644000176200001440000000146714602466070013561 0ustar liggesusers#' List field names of a remote table #' #' Returns the field names of a remote table as a character vector. #' #' @inheritParams dbReadTable #' #' @template methods #' @templateVar method_name dbListFields #' #' @inherit DBItest::spec_sql_list_fields return #' @inheritSection DBItest::spec_sql_list_fields Failure modes #' @inheritSection DBItest::spec_sql_list_fields Specification #' #' @family DBIConnection generics #' @seealso [dbColumnInfo()] to get the type of the fields. #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' dbListFields(con, "mtcars") #' #' dbDisconnect(con) setGeneric("dbListFields", def = function(conn, name, ...) standardGeneric("dbListFields"), valueClass = "character" ) DBI/R/dbListObjects_DBIConnection_ANY.R0000644000176200001440000000072214350241735017141 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbListObjects_DBIConnection_ANY <- function(conn, prefix = NULL, ...) { names <- dbListTables(conn) tables <- lapply(names, function(x) Id(table = x)) ret <- data.frame( table = I(unname(tables)), stringsAsFactors = FALSE ) ret$is_prefix <- rep_len(FALSE, nrow(ret)) ret } #' @rdname hidden_aliases #' @export setMethod("dbListObjects", signature("DBIConnection", "ANY"), dbListObjects_DBIConnection_ANY) DBI/R/dbUnloadDriver.R0000644000176200001440000000034714350241735014110 0ustar liggesusers#' @description #' `dbUnloadDriver()` is not implemented for modern backends. #' @rdname dbDriver #' @family DBIDriver generics #' @export setGeneric("dbUnloadDriver", def = function(drv, ...) standardGeneric("dbUnloadDriver") ) DBI/R/dbGetRowsAffected.R0000644000176200001440000000164514602466070014531 0ustar liggesusers#' The number of rows affected #' #' This method returns the number of rows that were added, deleted, or updated #' by a data manipulation statement. #' #' @inheritSection dbBind The command execution flow #' #' @template methods #' @templateVar method_name dbGetRowsAffected #' #' @inherit DBItest::spec_meta_get_rows_affected return #' @inheritSection DBItest::spec_meta_get_rows_affected Failure modes #' #' @inheritParams dbClearResult #' @family DBIResult generics #' @family command execution generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' rs <- dbSendStatement(con, "DELETE FROM mtcars") #' dbGetRowsAffected(rs) #' nrow(mtcars) #' #' dbClearResult(rs) #' dbDisconnect(con) setGeneric("dbGetRowsAffected", def = function(res, ...) standardGeneric("dbGetRowsAffected"), valueClass = "numeric" ) DBI/R/dbAppendTable_DBIConnection.R0000644000176200001440000000114114602466070016361 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbAppendTable_DBIConnection <- function(conn, name, value, ..., row.names = NULL) { if (!is.null(row.names)) { stop("Can't pass `row.names` to `dbAppendTable()`", call. = FALSE) } stopifnot(is.data.frame(value)) query <- sqlAppendTableTemplate( con = conn, table = name, values = value, row.names = row.names, prefix = "?", pattern = "", ... ) dbExecute(conn, query, params = unname(as.list(value))) } #' @rdname hidden_aliases #' @export setMethod("dbAppendTable", signature("DBIConnection"), dbAppendTable_DBIConnection) DBI/R/sqlAppendTable.R0000644000176200001440000000213514350241735014100 0ustar liggesusers#' Compose query to insert rows into a table #' #' `sqlAppendTable()` generates a single SQL string that inserts a #' data frame into an existing table. `sqlAppendTableTemplate()` generates #' a template suitable for use with [dbBind()]. #' The default methods are ANSI SQL 99 compliant. #' These methods are mostly useful for backend implementers. #' #' The `row.names` argument must be passed explicitly in order to avoid #' a compatibility warning. The default will be changed in a later release. #' #' @inheritParams sqlCreateTable #' @inheritParams rownames #' @param values A data frame. Factors will be converted to character vectors. #' Character vectors will be escaped with [dbQuoteString()]. #' #' @template methods #' @templateVar method_name sqlAppendTable #' #' @family SQL generation #' @export #' @examples #' sqlAppendTable(ANSI(), "iris", head(iris)) #' #' sqlAppendTable(ANSI(), "mtcars", head(mtcars)) #' sqlAppendTable(ANSI(), "mtcars", head(mtcars), row.names = FALSE) setGeneric("sqlAppendTable", def = function(con, table, values, row.names = NA, ...) standardGeneric("sqlAppendTable") ) DBI/R/show_Id.R0000644000176200001440000000035114537352607012603 0ustar liggesusers#' @rdname hidden_aliases #' @param object Table object to print #' @usage NULL show_Id <- function(object) { cat(toString(object), "\n", sep = "") } #' @rdname hidden_aliases #' @export setMethod("show", signature("Id"), show_Id) DBI/R/dbiDataType_numeric.R0000644000176200001440000000020014350241735015104 0ustar liggesusers#' @usage NULL dbiDataType_numeric <- function(x) "DOUBLE" setMethod("dbiDataType", signature("numeric"), dbiDataType_numeric) DBI/R/dbiDataType_data.frame.R0000644000176200001440000000027214350241735015455 0ustar liggesusersdbiDataType_data.frame <- function(x) { vapply(x, dbiDataType, FUN.VALUE = character(1), USE.NAMES = TRUE) } setMethod("dbiDataType", signature("data.frame"), dbiDataType_data.frame) DBI/R/dbReadTable_DBIConnection_Id.R0000644000176200001440000000043514350241735016445 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbReadTable_DBIConnection_Id <- function(conn, name, ...) { dbReadTable(conn, dbQuoteIdentifier(conn, name), ...) } #' @rdname hidden_aliases #' @export setMethod("dbReadTable", signature("DBIConnection", "Id"), dbReadTable_DBIConnection_Id) DBI/R/sqlAppendTable_DBIConnection.R0000644000176200001440000000155514350241735016603 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL sqlAppendTable_DBIConnection <- function(con, table, values, row.names = NA, ...) { stopifnot(is.list(values)) if (missing(row.names)) { warning("Do not rely on the default value of the row.names argument for sqlAppendTable(), it will change in the future.", call. = FALSE ) } sql_values <- sqlData(con, values, row.names) table <- dbQuoteIdentifier(con, table) fields <- dbQuoteIdentifier(con, names(sql_values)) # Convert fields into a character matrix rows <- do.call(paste, c(unname(sql_values), sep = ", ")) SQL(paste0( "INSERT INTO ", table, "\n", " (", paste(fields, collapse = ", "), ")\n", "VALUES\n", paste0(" (", rows, ")", collapse = ",\n") )) } #' @rdname hidden_aliases #' @export setMethod("sqlAppendTable", signature("DBIConnection"), sqlAppendTable_DBIConnection) DBI/R/make.db.names.R0000644000176200001440000000571614350241735013614 0ustar liggesusers#' Make R identifiers into legal SQL identifiers #' #' These methods are DEPRECATED. Please use [dbQuoteIdentifier()] #' (or possibly [dbQuoteString()]) instead. #' #' The algorithm in `make.db.names` first invokes `make.names` and #' then replaces each occurrence of a dot `.` by an underscore `_`. If #' `allow.keywords` is `FALSE` and identifiers collide with SQL #' keywords, a small integer is appended to the identifier in the form of #' `"_n"`. #' #' The set of SQL keywords is stored in the character vector #' `.SQL92Keywords` and reflects the SQL ANSI/ISO standard as documented #' in "X/Open SQL and RDA", 1994, ISBN 1-872630-68-8. Users can easily #' override or update this vector. #' #' @section Bugs: #' The current mapping is not guaranteed to be fully reversible: some SQL #' identifiers that get mapped into R identifiers with `make.names` and #' then back to SQL with [make.db.names()] will not be equal to the #' original SQL identifiers (e.g., compound SQL identifiers of the form #' `username.tablename` will loose the dot ``.''). #' #' @references The set of SQL keywords is stored in the character vector #' `.SQL92Keywords` and reflects the SQL ANSI/ISO standard as documented #' in "X/Open SQL and RDA", 1994, ISBN 1-872630-68-8. Users can easily #' override or update this vector. #' @aliases #' make.db.names #' SQLKeywords #' isSQLKeyword #' @param dbObj any DBI object (e.g., `DBIDriver`). #' @param snames a character vector of R identifiers (symbols) from which we #' need to make SQL identifiers. #' @param name a character vector with database identifier candidates we need #' to determine whether they are legal SQL identifiers or not. #' @param unique logical describing whether the resulting set of SQL names #' should be unique. Its default is `TRUE`. Following the SQL 92 #' standard, uniqueness of SQL identifiers is determined regardless of whether #' letters are upper or lower case. #' @param allow.keywords logical describing whether SQL keywords should be #' allowed in the resulting set of SQL names. Its default is `TRUE` #' @param keywords a character vector with SQL keywords, by default it's #' `.SQL92Keywords` defined by the DBI. #' @param case a character string specifying whether to make the comparison as #' lower case, upper case, or any of the two. it defaults to `any`. #' @param \dots any other argument are passed to the driver implementation. #' @return `make.db.names` returns a character vector of legal SQL #' identifiers corresponding to its `snames` argument. #' #' `SQLKeywords` returns a character vector of all known keywords for the #' database-engine associated with `dbObj`. #' #' `isSQLKeyword` returns a logical vector parallel to `name`. #' @export #' @keywords internal setGeneric("make.db.names", def = function(dbObj, snames, keywords = .SQL92Keywords, unique = TRUE, allow.keywords = TRUE, ...) standardGeneric("make.db.names"), signature = c("dbObj", "snames"), valueClass = "character" ) DBI/R/SQLKeywords_DBIObject.R0000644000176200001440000000034214350241735015173 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL SQLKeywords_DBIObject <- function(dbObj, ...) .SQL92Keywords #' @rdname hidden_aliases setMethod("SQLKeywords", signature("DBIObject"), SQLKeywords_DBIObject, valueClass = "character") DBI/R/SQLKeywords.R0000644000176200001440000000040014350241735013361 0ustar liggesusers## SQL ANSI 92 (plus ISO's) keywords --- all 220 of them! ## (See pp. 22 and 23 in X/Open SQL and RDA, 1994, isbn 1-872630-68-8) #' @export setGeneric("SQLKeywords", def = function(dbObj, ...) standardGeneric("SQLKeywords"), valueClass = "character" ) DBI/R/fetch.R0000644000176200001440000000021514350241735012267 0ustar liggesusers#' @rdname dbFetch #' @export setGeneric("fetch", def = function(res, n = -1, ...) standardGeneric("fetch"), valueClass = "data.frame" ) DBI/R/dbFetchArrow.R0000644000176200001440000000255014602466070013555 0ustar liggesusers#' Fetch records from a previously executed query as an Arrow object #' #' @description #' `r lifecycle::badge('experimental')` #' #' Fetch the result set and return it as an Arrow object. #' Use [dbFetchArrowChunk()] to fetch results in chunks. #' #' @inheritSection dbBind The data retrieval flow for Arrow streams #' #' @template methods #' @templateVar method_name dbFetchArrow #' #' @inherit DBItest::spec_arrow_fetch_arrow return #' @inheritSection DBItest::spec_arrow_fetch_arrow Failure modes #' @inheritSection DBItest::spec_arrow_fetch_arrow Specification #' #' @param res An object inheriting from [DBIResultArrow-class], created by #' [dbSendQueryArrow()]. #' @param ... Other arguments passed on to methods. #' @seealso Close the result set with [dbClearResult()] as soon as you #' finish retrieving the records you want. #' @family DBIResultArrow generics #' @family data retrieval generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' #' # Fetch all results #' rs <- dbSendQueryArrow(con, "SELECT * FROM mtcars WHERE cyl = 4") #' as.data.frame(dbFetchArrow(rs)) #' dbClearResult(rs) #' #' dbDisconnect(con) setGeneric("dbFetchArrow", def = function(res, ...) standardGeneric("dbFetchArrow") ) DBI/R/dbUnquoteIdentifier.R0000644000176200001440000000243214602466070015153 0ustar liggesusers#' Unquote identifiers #' #' Call this method to convert a [SQL] object created by [dbQuoteIdentifier()] #' back to a list of [Id] objects. #' #' @inheritParams dbGetQuery #' @param x An [SQL] or [Id] object. #' @param ... Other arguments passed on to methods. #' #' @template methods #' @templateVar method_name dbUnquoteIdentifier #' #' @inherit DBItest::spec_sql_unquote_identifier return #' @inheritSection DBItest::spec_sql_unquote_identifier Failure modes #' @inheritSection DBItest::spec_sql_unquote_identifier Specification #' #' @family DBIConnection generics #' @export #' @examples #' # Unquoting allows to understand the structure of a #' # possibly complex quoted identifier #' dbUnquoteIdentifier( #' ANSI(), #' SQL(c('"Catalog"."Schema"."Table"', '"Schema"."Table"', '"UnqualifiedTable"')) #' ) #' #' # The returned object is always a list, #' # also for Id objects #' dbUnquoteIdentifier(ANSI(), Id("Catalog", "Schema", "Table")) #' #' # Quoting and unquoting are inverses #' dbQuoteIdentifier( #' ANSI(), #' dbUnquoteIdentifier(ANSI(), SQL("UnqualifiedTable"))[[1]] #' ) #' #' dbQuoteIdentifier( #' ANSI(), #' dbUnquoteIdentifier(ANSI(), Id("Schema", "Table"))[[1]] #' ) setGeneric("dbUnquoteIdentifier", def = function(conn, x, ...) standardGeneric("dbUnquoteIdentifier") ) DBI/R/sqlAppendTableTemplate.R0000644000176200001440000000275614602466070015606 0ustar liggesusers#' @rdname sqlAppendTable #' @inheritParams sqlCreateTable #' @inheritParams rownames #' @param prefix Parameter prefix to use for placeholders. #' @param pattern Parameter pattern to use for placeholders: #' - `""`: no pattern #' - `"1"`: position #' - anything else: field name #' @export #' @examples #' sqlAppendTableTemplate(ANSI(), "iris", iris) #' #' sqlAppendTableTemplate(ANSI(), "mtcars", mtcars) #' sqlAppendTableTemplate(ANSI(), "mtcars", mtcars, row.names = FALSE) sqlAppendTableTemplate <- function(con, table, values, row.names = NA, prefix = "?", ..., pattern = "") { if (missing(row.names)) { warning("Do not rely on the default value of the `row.names` argument to `sqlAppendTableTemplate()`, it will change in the future.", call. = FALSE ) } if (length(values) == 0) { stop("Must pass at least one column in `values`", call. = FALSE) } table <- dbQuoteIdentifier(con, table) if (length(table) != 1) { stop("Must pass one table name", call. = FALSE) } values <- sqlRownamesToColumn(values[0, , drop = FALSE], row.names) fields <- dbQuoteIdentifier(con, names(values)) if (pattern == "") { suffix <- rep("", length(fields)) } else if (pattern == "1") { suffix <- as.character(seq_along(fields)) } else { suffix <- names(fields) } placeholders <- lapply(paste0(prefix, suffix), SQL) names(placeholders) <- names(values) sqlAppendTable( con = con, table = table, values = placeholders, row.names = row.names ) } DBI/R/dbWithTransaction.R0000644000176200001440000000464514627140170014636 0ustar liggesusers#' Self-contained SQL transactions #' #' Given that \link{transactions} are implemented, this function #' allows you to pass in code that is run in a transaction. #' The default method of `dbWithTransaction()` calls [dbBegin()] #' before executing the code, #' and [dbCommit()] after successful completion, #' or [dbRollback()] in case of an error. #' The advantage is #' that you don't have to remember to do `dbBegin()` and `dbCommit()` or #' `dbRollback()` -- that is all taken care of. #' The special function `dbBreak()` allows an early exit with rollback, #' it can be called only inside `dbWithTransaction()`. #' #' DBI implements `dbWithTransaction()`, backends should need to override this #' generic only if they implement specialized handling. #' #' @template methods #' @templateVar method_name dbWithTransaction #' #' @inherit DBItest::spec_transaction_with_transaction return #' @inheritSection DBItest::spec_transaction_with_transaction Failure modes #' @inheritSection DBItest::spec_transaction_with_transaction Specification #' #' @inheritParams dbGetQuery #' @param code An arbitrary block of R code. #' #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "cash", data.frame(amount = 100)) #' dbWriteTable(con, "account", data.frame(amount = 2000)) #' #' # All operations are carried out as logical unit: #' dbWithTransaction( #' con, #' { #' withdrawal <- 300 #' dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) #' dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) #' } #' ) #' #' # The code is executed as if in the current environment: #' withdrawal #' #' # The changes are committed to the database after successful execution: #' dbReadTable(con, "cash") #' dbReadTable(con, "account") #' #' # Rolling back with dbBreak(): #' dbWithTransaction( #' con, #' { #' withdrawal <- 5000 #' dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) #' dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) #' if (dbReadTable(con, "account")$amount < 0) { #' dbBreak() #' } #' } #' ) #' #' # These changes were not committed to the database: #' dbReadTable(con, "cash") #' dbReadTable(con, "account") #' #' dbDisconnect(con) setGeneric("dbWithTransaction", def = function(conn, code, ...) standardGeneric("dbWithTransaction") ) DBI/R/dbReadTableArrow_DBIConnection.R0000644000176200001440000000053114602466070017042 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbReadTableArrow_DBIConnection <- function(conn, name, ...) { sql_name <- dbReadTable_toSqlName(conn, name, ...) dbGetQueryArrow(conn, paste0("SELECT * FROM ", sql_name)) } #' @rdname hidden_aliases #' @export setMethod("dbReadTableArrow", signature("DBIConnection"), dbReadTableArrow_DBIConnection) DBI/R/dbGetQuery.R0000644000176200001440000000503314602466070013255 0ustar liggesusers#' Retrieve results from a query #' #' Returns the result of a query as a data frame. #' `dbGetQuery()` comes with a default implementation #' (which should work with most backends) that calls #' [dbSendQuery()], then [dbFetch()], ensuring that #' the result is always freed by [dbClearResult()]. #' For retrieving chunked/paged results or for passing query parameters, #' see [dbSendQuery()], in particular the "The data retrieval flow" section. #' For retrieving results as an Arrow object, see [dbGetQueryArrow()]. #' #' This method is for `SELECT` queries only #' (incl. other SQL statements that return a `SELECT`-alike result, #' e.g., execution of a stored procedure or data manipulation queries #' like `INSERT INTO ... RETURNING ...`). #' To execute a stored procedure that does not return a result set, #' use [dbExecute()]. #' #' Some backends may #' support data manipulation statements through this method for compatibility #' reasons. However, callers are strongly advised to use #' [dbExecute()] for data manipulation statements. #' #' @template methods #' @templateVar method_name dbGetQuery #' #' @inherit DBItest::spec_result_get_query return #' @inheritSection DBItest::spec_result_get_query Failure modes #' @inheritSection DBItest::spec_result_get_query Additional arguments #' @inheritSection DBItest::spec_result_get_query Specification #' @inheritSection DBItest::spec_result_get_query Specification for the `immediate` argument #' #' @section Implementation notes: #' Subclasses should override this method only if they provide some sort of #' performance optimization. #' #' @param conn A [DBIConnection-class] object, as returned by #' [dbConnect()]. #' @param statement a character string containing SQL. #' @param ... Other parameters passed on to methods. #' @family DBIConnection generics #' @family data retrieval generics #' @seealso For updates: [dbSendStatement()] and [dbExecute()]. #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' dbGetQuery(con, "SELECT * FROM mtcars") #' dbGetQuery(con, "SELECT * FROM mtcars", n = 6) #' #' # Pass values using the param argument: #' # (This query runs eight times, once for each different #' # parameter. The resulting rows are combined into a single #' # data frame.) #' dbGetQuery( #' con, #' "SELECT COUNT(*) FROM mtcars WHERE cyl = ?", #' params = list(1:8) #' ) #' #' dbDisconnect(con) setGeneric("dbGetQuery", def = function(conn, statement, ...) standardGeneric("dbGetQuery") ) DBI/R/dbQuoteIdentifier_DBIConnection.R0000644000176200001440000000253014602466070017305 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbQuoteIdentifier_DBIConnection <- function(conn, x, ...) { # Don't support lists, auto-vectorization violates type stability if (is(x, "SQL")) return(x) if (!is.character(x)) stop("x must be character or SQL", call. = FALSE) if (any(is.na(x))) { stop("Cannot pass NA to dbQuoteIdentifier()", call. = FALSE) } # Avoid fixed = TRUE due to https://github.com/r-dbi/DBItest/issues/156 x <- gsub('"', '""', enc2utf8(x)) if (length(x) == 0L) { SQL(character(), names = names(x)) } else { # Not calling encodeString() here to keep things simple SQL(paste('"', x, '"', sep = ""), names = names(x)) } } #' @rdname hidden_aliases #' @export setMethod("dbQuoteIdentifier", signature("DBIConnection"), dbQuoteIdentifier_DBIConnection) # Need to keep other method declarations around for now, because clients might # use getMethod(), see e.g. https://github.com/r-dbi/odbc/pull/149 #' @rdname hidden_aliases #' @export setMethod("dbQuoteIdentifier", signature("DBIConnection", "character"), dbQuoteIdentifier_DBIConnection) #' @rdname hidden_aliases #' @export setMethod("dbQuoteIdentifier", signature("DBIConnection", "SQL"), dbQuoteIdentifier_DBIConnection) #' @rdname hidden_aliases #' @export setMethod("dbQuoteIdentifier", signature("DBIConnection", "Id"), dbQuoteIdentifier_DBIConnection_Id) DBI/R/summary.R0000644000176200001440000000002614350241735012673 0ustar liggesuserssetGeneric("summary") DBI/R/dbIsReadOnly_DBIConnector.R0000644000176200001440000000035114350241735016047 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbIsReadOnly_DBIConnector <- function(dbObj, ...) { dbIsReadOnly(dbObj@.drv, ...) } #' @rdname hidden_aliases setMethod("dbIsReadOnly", signature("DBIConnector"), dbIsReadOnly_DBIConnector) DBI/R/dbiDataType_ANY.R0000644000176200001440000000035214602466070014102 0ustar liggesusersdbiDataType_ANY <- function(x) { if (inherits(x, "blob")) { return("BLOB") } stop("Unknown SQL data type for object of class ", paste(class(x), collapse = "/")) } setMethod("dbiDataType", signature("ANY"), dbiDataType_ANY) DBI/R/dbiDataType_AsIs.R0000644000176200001440000000022514350241735014310 0ustar liggesusersdbiDataType_AsIs <- function(x) { oldClass(x) <- oldClass(x)[-1] dbiDataType(x) } setMethod("dbiDataType", signature("AsIs"), dbiDataType_AsIs) DBI/R/dbReadTable.R0000644000176200001440000000276314602466070013342 0ustar liggesusers#' Read database tables as data frames #' #' Reads a database table to a data frame, optionally converting #' a column to row names and converting the column names to valid #' R identifiers. #' Use [dbReadTableArrow()] instead to obtain an Arrow object. #' #' @details #' This function returns a data frame. #' Use [dbReadTableArrow()] to obtain an Arrow object. #' #' @template methods #' @templateVar method_name dbReadTable #' #' @inherit DBItest::spec_sql_read_table return #' @inheritSection DBItest::spec_sql_read_table Failure modes #' @inheritSection DBItest::spec_sql_read_table Additional arguments #' @inheritSection DBItest::spec_sql_read_table Specification #' #' @inheritParams dbGetQuery #' @param name The table name, passed on to [dbQuoteIdentifier()]. Options are: #' - a character string with the unquoted DBMS table name, #' e.g. `"table_name"`, #' - a call to [Id()] with components to the fully qualified table name, #' e.g. `Id(schema = "my_schema", table = "table_name")` #' - a call to [SQL()] with the quoted and fully qualified table name #' given verbatim, e.g. `SQL('"my_schema"."table_name"')` #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars[1:10, ]) #' dbReadTable(con, "mtcars") #' #' dbDisconnect(con) setGeneric("dbReadTable", def = function(conn, name, ...) standardGeneric("dbReadTable"), valueClass = "data.frame" ) DBI/R/methods_as_rd.R0000644000176200001440000000413214542471013014010 0ustar liggesusersmethods_as_rd <- function(method) { if (method == "transactions") { method <- c("dbBegin", "dbCommit", "dbRollback") } if (identical(Sys.getenv("IN_PKGDOWN"), "true") && file.exists("DESCRIPTION")) { packages <- strsplit(read.dcf("DESCRIPTION")[, "Config/Needs/website"], ",( |\n)*", perl = TRUE)[[1]] packages <- grep("/", packages, invert = TRUE, value = TRUE) for (package in packages) { stopifnot(requireNamespace(package, quietly = TRUE)) } } methods <- unlist(lapply(method, methods::findMethods), recursive = FALSE) # Extracted from roxygen2::object_topic.s4method s4_topic <- function(x) { sig <- paste0(x@defined, collapse = ",") sig_text <- paste0('"', x@defined, '"', collapse = ", ") package <- unname(tryCatch( getNamespaceName(environment(x@.Data)), error = function(e) NA )) if (is.na(package) || package == "DBI") { return(data.frame()) } topic <- paste0(x@generic, ",", sig, "-method") call <- paste0(package, "::", x@generic, "(", sig_text, ")") if (identical(Sys.getenv("IN_PKGDOWN"), "true")) { url <- downlit::autolink_url(paste0("?", package, "::`", topic, "`")) } else { url <- NA } data.frame(package, topic, call, url, stringsAsFactors = FALSE) } item_list <- lapply(methods@.Data, s4_topic) items <- do.call(rbind, item_list) if (is.null(items) || ncol(items) == 0) { return("") } items <- items[order(items$call), ] if (identical(Sys.getenv("IN_PKGDOWN"), "true")) { linked <- ifelse(is.na(items$url), items$call, paste0("\\href{", items$url, "}{", items$call, "}")) item_text <- paste0("\\code{", linked, "}") } else { item_text <- paste0("\\code{\\link[=", items$topic, "]{", items$call, "}}") } paste0( "\\subsection{Methods in other packages}{\n\n", "This documentation page describes the generics. ", "Refer to the documentation pages linked below for the documentation for the methods that are implemented in various backend packages.", "\\itemize{\n", paste0("\\item ", item_text, "\n", collapse = ""), "}}\n" ) } DBI/R/dbGetQuery_DBIConnection_character.R0000644000176200001440000000062714350241735017772 0ustar liggesusers#' @rdname hidden_aliases #' @param n Number of rows to fetch, default -1 #' @usage NULL dbGetQuery_DBIConnection_character <- function(conn, statement, ..., n = -1L) { rs <- dbSendQuery(conn, statement, ...) on.exit(dbClearResult(rs)) dbFetch(rs, n = n, ...) } #' @rdname hidden_aliases #' @export setMethod("dbGetQuery", signature("DBIConnection", "character"), dbGetQuery_DBIConnection_character) DBI/R/dbConnect.R0000644000176200001440000000346014602466070013103 0ustar liggesusers#' Create a connection to a DBMS #' #' Connect to a DBMS going through the appropriate authentication procedure. #' Some implementations may allow you to have multiple connections open, so you #' may invoke this function repeatedly assigning its output to different #' objects. #' The authentication mechanism is left unspecified, so check the #' documentation of individual drivers for details. #' Use [dbCanConnect()] to check if a connection can be established. #' #' @template methods #' @templateVar method_name dbConnect #' #' @inherit DBItest::spec_driver_connect return #' @inheritSection DBItest::spec_driver_connect Specification #' #' @param drv an object that inherits from [DBIDriver-class], #' or an existing [DBIConnection-class] #' object (in order to clone an existing connection). #' @param ... authentication arguments needed by the DBMS instance; these #' typically include `user`, `password`, `host`, `port`, `dbname`, etc. #' For details see the appropriate `DBIDriver`. #' @seealso [dbDisconnect()] to disconnect from a database. #' @family DBIDriver generics #' @family DBIConnector generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' # SQLite only needs a path to the database. (Here, ":memory:" is a special #' # path that creates an in-memory database.) Other database drivers #' # will require more details (like user, password, host, port, etc.) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' con #' #' dbListTables(con) #' #' dbDisconnect(con) #' #' # Bad, for subtle reasons: #' # This code fails when RSQLite isn't loaded yet, #' # because dbConnect() doesn't know yet about RSQLite. #' dbListTables(con <- dbConnect(RSQLite::SQLite(), ":memory:")) setGeneric("dbConnect", def = function(drv, ...) standardGeneric("dbConnect"), valueClass = "DBIConnection" ) DBI/R/dbGetQueryArrow_DBIConnection.R0000644000176200001440000000054314602466070016767 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbGetQueryArrow_DBIConnection_character <- function(conn, statement, ...) { rs <- dbSendQueryArrow(conn, statement, ...) on.exit(dbClearResult(rs)) dbFetchArrow(rs, ...) } #' @rdname hidden_aliases #' @export setMethod("dbGetQueryArrow", signature("DBIConnection"), dbGetQueryArrow_DBIConnection_character) DBI/R/dbWriteTable_DBIConnection_Id_ANY.R0000644000176200001440000000047614350241735017400 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbWriteTable_DBIConnection_Id_ANY <- function(conn, name, value, ...) { dbWriteTable(conn, dbQuoteIdentifier(conn, name), value, ...) } #' @rdname hidden_aliases #' @export setMethod("dbWriteTable", signature("DBIConnection", "Id", "ANY"), dbWriteTable_DBIConnection_Id_ANY) DBI/R/data-types.R0000644000176200001440000000005514350241735013253 0ustar liggesuserssetOldClass("difftime") setOldClass("AsIs") DBI/R/dbQuoteString_DBIConnection.R0000644000176200001440000000215514350241735016473 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbQuoteString_DBIConnection <- function(conn, x, ...) { if (is(x, "SQL")) return(x) if (!is.character(x)) stop("x must be character or SQL", call. = FALSE) # Avoid fixed = TRUE due to https://github.com/r-dbi/DBItest/issues/156 x <- gsub("'", "''", enc2utf8(x)) if (length(x) == 0L) { SQL(character()) } else { # Not calling encodeString() here, see also https://stackoverflow.com/a/549244/946850 # and especially the comment by Álvaro González str <- paste("'", x, "'", sep = "") str[is.na(x)] <- "NULL" SQL(str) } } # Need to keep other method declarations around for now, because clients might # use getMethod(), see e.g. https://github.com/r-dbi/odbc/pull/149 #' @rdname hidden_aliases #' @export setMethod("dbQuoteString", signature("DBIConnection"), dbQuoteString_DBIConnection) #' @rdname hidden_aliases #' @export setMethod("dbQuoteString", signature("DBIConnection", "character"), dbQuoteString_DBIConnection) #' @rdname hidden_aliases #' @export setMethod("dbQuoteString", signature("DBIConnection", "SQL"), dbQuoteString_DBIConnection) DBI/R/dbFetch.R0000644000176200001440000000361514602466070012545 0ustar liggesusers#' Fetch records from a previously executed query #' #' Fetch the next `n` elements (rows) from the result set and return them #' as a data.frame. #' #' `fetch()` is provided for compatibility with older DBI clients - for all #' new code you are strongly encouraged to use `dbFetch()`. The default #' implementation for `dbFetch()` calls `fetch()` so that it is compatible with #' existing code. Modern backends should implement for `dbFetch()` only. #' #' @inheritSection dbBind The data retrieval flow #' #' @template methods #' @templateVar method_name dbFetch #' #' @inherit DBItest::spec_result_fetch return #' @inheritSection DBItest::spec_result_fetch Failure modes #' @inheritSection DBItest::spec_result_fetch Specification #' @inheritSection DBItest::spec_result_roundtrip Specification #' #' @param res An object inheriting from [DBIResult-class], created by #' [dbSendQuery()]. #' @param n maximum number of records to retrieve per fetch. Use `n = -1` #' or `n = Inf` #' to retrieve all pending records. Some implementations may recognize other #' special values. #' @param ... Other arguments passed on to methods. #' @seealso Close the result set with [dbClearResult()] as soon as you #' finish retrieving the records you want. #' @family DBIResult generics #' @family data retrieval generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' #' # Fetch all results #' rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4") #' dbFetch(rs) #' dbClearResult(rs) #' #' # Fetch in chunks #' rs <- dbSendQuery(con, "SELECT * FROM mtcars") #' while (!dbHasCompleted(rs)) { #' chunk <- dbFetch(rs, 10) #' print(nrow(chunk)) #' } #' #' dbClearResult(rs) #' dbDisconnect(con) setGeneric("dbFetch", def = function(res, n = -1, ...) standardGeneric("dbFetch"), valueClass = "data.frame" ) DBI/R/dbGetStatement.R0000644000176200001440000000143114602466070014112 0ustar liggesusers#' Get the statement associated with a result set #' #' Returns the statement that was passed to [dbSendQuery()] #' or [dbSendStatement()]. #' #' @template methods #' @templateVar method_name dbGetStatement #' #' @inherit DBItest::spec_meta_get_statement return #' @inheritSection DBItest::spec_meta_get_statement Failure modes #' #' @inheritParams dbClearResult #' @family DBIResult generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "mtcars", mtcars) #' rs <- dbSendQuery(con, "SELECT * FROM mtcars") #' dbGetStatement(rs) #' #' dbClearResult(rs) #' dbDisconnect(con) setGeneric("dbGetStatement", def = function(res, ...) standardGeneric("dbGetStatement"), valueClass = "character" ) DBI/R/02-DBIDriver.R0000644000176200001440000000273414602466070013200 0ustar liggesusersNULL #' DBIDriver class #' #' Base class for all DBMS drivers (e.g., RSQLite, MySQL, PostgreSQL). #' The virtual class `DBIDriver` defines the operations for creating #' connections and defining data type mappings. Actual driver classes, for #' instance `RPostgres`, `RMariaDB`, etc. implement these operations in a #' DBMS-specific manner. #' #' @docType class #' @name DBIDriver-class #' @family DBI classes #' @family DBIDriver generics #' @export setClass("DBIDriver", contains = c("DBIObject", "VIRTUAL")) show_driver <- function(object) { cat("<", is(object)[1], ">\n", sep = "") } findDriver <- function(drvName) { # If it exists in the global environment, use that d <- get2(drvName, globalenv()) if (!is.null(d)) return(d) # Otherwise, see if the appropriately named package is available if (is_attached(drvName)) { d <- get2(drvName, asNamespace(drvName)) if (!is.null(d)) return(d) } pkgName <- paste0("R", drvName) # First, see if package with name R + drvName is available if (is_attached(pkgName)) { d <- get2(drvName, asNamespace(pkgName)) if (!is.null(d)) return(d) } # Can't find it: stop( "Couldn't find driver ", drvName, ". Looked in:\n", "* global namespace\n", "* in package called ", drvName, "\n", "* in package called ", pkgName, call. = FALSE ) } get2 <- function(x, env) { if (!exists(x, envir = env)) return(NULL) get(x, envir = env) } is_attached <- function(x) { x %in% loadedNamespaces() } DBI/R/dbBindArrow_DBIResult.R0000644000176200001440000000065214602466070015256 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbBindArrow_DBIResult <- function(res, params, ...) { dbBind(res, params = param_stream_to_list(params), ...) } #' @rdname hidden_aliases #' @export setMethod("dbBindArrow", signature("DBIResult"), dbBindArrow_DBIResult) param_stream_to_list <- function(params) { params <- as.list(as.data.frame(params)) if (all(names(params) == "")) { names(params) <- NULL } params } DBI/R/dbClearResult.R0000644000176200001440000000215714602466070013741 0ustar liggesusers#' Clear a result set #' #' Frees all resources (local and remote) associated with a result set. #' This step is mandatory for all objects obtained by calling #' [dbSendQuery()] or [dbSendStatement()]. #' #' @inheritSection dbBind The data retrieval flow #' @inheritSection dbBind The command execution flow #' #' @template methods #' @templateVar method_name dbClearResult #' #' @inherit DBItest::spec_result_clear_result return #' @inheritSection DBItest::spec_result_clear_result Failure modes #' @inheritSection DBItest::spec_result_clear_result Specification #' #' @param res An object inheriting from [DBIResult-class]. #' @param ... Other arguments passed on to methods. #' @family DBIResult generics #' @family DBIResultArrow generics #' @family data retrieval generics #' @family command execution generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' rs <- dbSendQuery(con, "SELECT 1") #' print(dbFetch(rs)) #' #' dbClearResult(rs) #' dbDisconnect(con) setGeneric("dbClearResult", def = function(res, ...) standardGeneric("dbClearResult") ) DBI/R/dbCreateTable_DBIConnection.R0000644000176200001440000000105014350241735016353 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbCreateTable_DBIConnection <- function(conn, name, fields, ..., row.names = NULL, temporary = FALSE) { stopifnot(is.null(row.names)) stopifnot(is.logical(temporary), length(temporary) == 1L) query <- sqlCreateTable( con = conn, table = name, fields = fields, row.names = row.names, temporary = temporary, ... ) dbExecute(conn, query) invisible(TRUE) } #' @rdname hidden_aliases #' @export setMethod("dbCreateTable", signature("DBIConnection"), dbCreateTable_DBIConnection) DBI/R/sqlData_DBIConnection.R0000644000176200001440000000133314350241735015267 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL sqlData_DBIConnection <- function(con, value, row.names = NA, ...) { value <- sqlRownamesToColumn(value, row.names) # Convert factors to strings is_factor <- vapply(value, is.factor, logical(1)) value[is_factor] <- lapply(value[is_factor], as.character) # Quote all strings is_char <- vapply(value, is.character, logical(1)) value[is_char] <- lapply(value[is_char], function(x) { enc2utf8(dbQuoteString(con, x)) }) # Convert everything to character and turn NAs into NULL value[!is_char] <- lapply(value[!is_char], dbQuoteLiteral, conn = con) value } #' @rdname hidden_aliases #' @export setMethod("sqlData", signature("DBIConnection"), sqlData_DBIConnection) DBI/R/dbQuoteString.R0000644000176200001440000000225414350241735013775 0ustar liggesusers#' Quote literal strings #' #' Call this method to generate a string that is suitable for #' use in a query as a string literal, to make sure that you #' generate valid SQL and protect against SQL injection attacks. #' #' @inheritParams dbGetQuery #' @param x A character vector to quote as string. #' @param ... Other arguments passed on to methods. #' #' @template methods #' @templateVar method_name dbQuoteString #' #' @inherit DBItest::spec_sql_quote_string return #' @inheritSection DBItest::spec_sql_quote_string Failure modes #' @inheritSection DBItest::spec_sql_quote_string Specification #' #' @family DBIResult generics #' @export #' @examples #' # Quoting ensures that arbitrary input is safe for use in a query #' name <- "Robert'); DROP TABLE Students;--" #' dbQuoteString(ANSI(), name) #' #' # NAs become NULL #' dbQuoteString(ANSI(), c("x", NA)) #' #' # SQL vectors are always passed through as is #' var_name <- SQL("select") #' var_name #' dbQuoteString(ANSI(), var_name) #' #' # This mechanism is used to prevent double escaping #' dbQuoteString(ANSI(), dbQuoteString(ANSI(), name)) setGeneric("dbQuoteString", def = function(conn, x, ...) standardGeneric("dbQuoteString") ) DBI/R/dbCreateTableArrow_DBIConnection.R0000644000176200001440000000106014602466070017370 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbCreateTableArrow_DBIConnection <- function(conn, name, value, ..., temporary = FALSE) { require_arrow() # https://github.com/apache/arrow-nanoarrow/issues/347 if (!inherits(value, "nanoarrow_schema")) { value <- nanoarrow::infer_nanoarrow_schema(value) } ptype <- nanoarrow::infer_nanoarrow_ptype(value) dbCreateTable(conn, name, ptype, ..., temporary = temporary) } #' @rdname hidden_aliases #' @export setMethod("dbCreateTableArrow", signature("DBIConnection"), dbCreateTableArrow_DBIConnection) DBI/R/dbIsValid.R0000644000176200001440000000152114602466070013041 0ustar liggesusers#' Is this DBMS object still valid? #' #' This generic tests whether a database object is still valid (i.e. it hasn't #' been disconnected or cleared). #' #' @template methods #' @templateVar method_name dbIsValid #' #' @inherit DBItest::spec_meta_is_valid return #' #' @inheritParams dbGetInfo #' @family DBIDriver generics #' @family DBIConnection generics #' @family DBIResult generics #' @family DBIResultArrow generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' dbIsValid(RSQLite::SQLite()) #' #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' dbIsValid(con) #' #' rs <- dbSendQuery(con, "SELECT 1") #' dbIsValid(rs) #' #' dbClearResult(rs) #' dbIsValid(rs) #' #' dbDisconnect(con) #' dbIsValid(con) setGeneric("dbIsValid", def = function(dbObj, ...) standardGeneric("dbIsValid"), valueClass = "logical" ) DBI/R/dbRemoveTable_DBIConnection_Id.R0000644000176200001440000000044514350241735017030 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbRemoveTable_DBIConnection_Id <- function(conn, name, ...) { dbRemoveTable(conn, dbQuoteIdentifier(conn, name), ...) } #' @rdname hidden_aliases #' @export setMethod("dbRemoveTable", signature("DBIConnection", "Id"), dbRemoveTable_DBIConnection_Id) DBI/R/dbListObjects.R0000644000176200001440000000271214602466070013736 0ustar liggesusers#' List remote objects #' #' Returns the names of remote objects accessible through this connection #' as a data frame. #' This should include temporary objects, but not all database backends #' (in particular \pkg{RMariaDB} and \pkg{RMySQL}) support this. #' Compared to [dbListTables()], this method also enumerates tables and views #' in schemas, and returns fully qualified identifiers to access these objects. #' This allows exploration of all database objects available to the current #' user, including those that can only be accessed by giving the full #' namespace. #' #' @template methods #' @templateVar method_name dbListObjects #' #' @inherit DBItest::spec_sql_list_objects return #' @inheritSection DBItest::spec_sql_list_objects Failure modes #' @inheritSection DBItest::spec_sql_list_objects Specification #' #' @inheritParams dbGetQuery #' @param prefix A fully qualified path in the database's namespace, or `NULL`. #' This argument will be processed with [dbUnquoteIdentifier()]. #' If given the method will return all objects accessible through this prefix. #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbListObjects(con) #' dbWriteTable(con, "mtcars", mtcars) #' dbListObjects(con) #' #' dbDisconnect(con) setGeneric("dbListObjects", def = function(conn, prefix = NULL, ...) standardGeneric("dbListObjects"), valueClass = "data.frame" ) DBI/R/06-ANSI.R0000644000176200001440000000067214602466070012163 0ustar liggesuserssetClass("AnsiConnection", contains = "DBIConnection") #' A dummy DBI connector that simulates ANSI-SQL compliance #' #' @export #' @keywords internal #' @examples #' ANSI() ANSI <- function() { new("AnsiConnection") } #' Internal page for hidden aliases #' #' For S4 methods that require a documentation entry but only clutter the index. #' #' @usage NULL #' @format NULL #' @keywords internal #' @docType methods hidden_aliases <- NULL DBI/R/dbiDataType_logical.R0000644000176200001440000000020214350241735015056 0ustar liggesusers#' @usage NULL dbiDataType_logical <- function(x) "SMALLINT" setMethod("dbiDataType", signature("logical"), dbiDataType_logical) DBI/R/dbExecute_DBIConnection_character.R0000644000176200001440000000053414350241735017624 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbExecute_DBIConnection_character <- function(conn, statement, ...) { rs <- dbSendStatement(conn, statement, ...) on.exit(dbClearResult(rs)) dbGetRowsAffected(rs) } #' @rdname hidden_aliases #' @export setMethod("dbExecute", signature("DBIConnection", "character"), dbExecute_DBIConnection_character) DBI/R/dbBegin.R0000644000176200001440000000016214350241735012531 0ustar liggesusers#' @export #' @rdname transactions setGeneric("dbBegin", def = function(conn, ...) standardGeneric("dbBegin") ) DBI/R/dbCallProc.R0000644000176200001440000000076014350241735013210 0ustar liggesusers#' Call an SQL stored procedure #' #' **Deprecated since 2014** #' #' The recommended way of calling a stored procedure is now #' #' \enumerate{ #' \item{\code{\link{dbGetQuery}} if a result set is returned} #' \item{\code{\link{dbExecute}} for data manipulation and other cases where no result set is returned} #' } #' #' @inheritParams dbGetQuery #' @keywords internal #' @export setGeneric("dbCallProc", def = function(conn, ...) { .Deprecated() standardGeneric("dbCallProc") } ) DBI/R/dbiDataType_integer.R0000644000176200001440000000017514350241735015112 0ustar liggesusers#' @usage NULL dbiDataType_integer <- function(x) "INT" setMethod("dbiDataType", signature("integer"), dbiDataType_integer) DBI/R/dbBindArrow_DBIResultArrowDefault.R0000644000176200001440000000050414602466070017572 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbBindArrow_DBIResultArrowDefault <- function(res, params, ...) { dbBind(res@result, params = param_stream_to_list(params), ...) invisible(res) } #' @rdname hidden_aliases #' @export setMethod("dbBindArrow", signature("DBIResultArrowDefault"), dbBindArrow_DBIResultArrowDefault) DBI/R/23-dbWriteTableArrow.R0000644000176200001440000000317314602466070015012 0ustar liggesusers#' Copy Arrow objects to database tables #' #' @description #' `r lifecycle::badge('experimental')` #' #' Writes, overwrites or appends an Arrow object to a database table. #' #' @details #' This function expects an Arrow object. #' Convert a data frame to an Arrow object with [nanoarrow::as_nanoarrow_array_stream()] or #' use [dbWriteTable()] to write a data frame. #' #' This function is useful if you want to create and load a table at the same time. #' Use [dbAppendTableArrow()] for appending data to an existing #' table, [dbCreateTableArrow()] for creating a table and specifying field types, #' and [dbRemoveTable()] for overwriting tables. #' #' @template methods #' @templateVar method_name dbWriteTableArrow #' #' @inherit DBItest::spec_arrow_write_table_arrow return #' @inheritSection DBItest::spec_arrow_write_table_arrow Failure modes #' @inheritSection DBItest::spec_arrow_write_table_arrow Additional arguments #' @inheritSection DBItest::spec_arrow_write_table_arrow Specification #' #' @inheritParams dbGetQuery #' @inheritParams dbReadTable #' @param value An nanoarray stream, or an object coercible to a nanoarray stream with #' [nanoarrow::as_nanoarrow_array_stream()]. #' @family DBIConnection generics #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) && requireNamespace("nanoarrow", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTableArrow(con, "mtcars", nanoarrow::as_nanoarrow_array_stream(mtcars[1:5, ])) #' dbReadTable(con, "mtcars") #' #' dbDisconnect(con) setGeneric("dbWriteTableArrow", def = function(conn, name, value, ...) standardGeneric("dbWriteTableArrow") ) DBI/R/dbGetStatement_DBIResultArrow.R0000644000176200001440000000040014602466070016775 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbGetStatement_DBIResultArrow <- function(res, ...) { dbGetStatement(res@result, ...) } #' @rdname hidden_aliases #' @export setMethod("dbGetStatement", signature("DBIResultArrow"), dbGetStatement_DBIResultArrow) DBI/R/dbExecute.R0000644000176200001440000000426014602466070013113 0ustar liggesusers#' Change database state #' #' Executes a statement and returns the number of rows affected. #' `dbExecute()` comes with a default implementation #' (which should work with most backends) that calls #' [dbSendStatement()], then [dbGetRowsAffected()], ensuring that #' the result is always freed by [dbClearResult()]. #' For passing query parameters, see [dbBind()], in particular #' the "The command execution flow" section. #' #' You can also use `dbExecute()` to call a stored procedure #' that performs data manipulation or other actions that do not return a result set. #' To execute a stored procedure that returns a result set, #' or a data manipulation query that also returns a result set #' such as `INSERT INTO ... RETURNING ...`, use [dbGetQuery()] instead. #' #' @template methods #' @templateVar method_name dbExecute #' #' @section Implementation notes: #' Subclasses should override this method only if they provide some sort of #' performance optimization. #' #' @inherit DBItest::spec_result_execute return #' @inheritSection DBItest::spec_result_execute Failure modes #' @inheritSection DBItest::spec_result_execute Additional arguments #' @inheritSection DBItest::spec_result_execute Specification #' @inheritSection DBItest::spec_result_execute Specification for the `immediate` argument #' #' @inheritParams dbGetQuery #' @param statement a character string containing SQL. #' @family DBIConnection generics #' @family command execution generics #' @seealso For queries: [dbSendQuery()] and [dbGetQuery()]. #' @export #' @examplesIf requireNamespace("RSQLite", quietly = TRUE) #' con <- dbConnect(RSQLite::SQLite(), ":memory:") #' #' dbWriteTable(con, "cars", head(cars, 3)) #' dbReadTable(con, "cars") # there are 3 rows #' dbExecute( #' con, #' "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)" #' ) #' dbReadTable(con, "cars") # there are now 6 rows #' #' # Pass values using the param argument: #' dbExecute( #' con, #' "INSERT INTO cars (speed, dist) VALUES (?, ?)", #' params = list(4:7, 5:8) #' ) #' dbReadTable(con, "cars") # there are now 10 rows #' #' dbDisconnect(con) setGeneric("dbExecute", def = function(conn, statement, ...) standardGeneric("dbExecute") ) DBI/R/dbQuoteLiteral_DBIConnection.R0000644000176200001440000000250314627152377016630 0ustar liggesusers#' @rdname hidden_aliases #' @usage NULL dbQuoteLiteral_DBIConnection <- function(conn, x, ...) { # Switchpatching to avoid ambiguous S4 dispatch, so that our method # is used only if no alternatives are available. if (is(x, "SQL")) { return(x) } if (is.factor(x)) { return(dbQuoteString(conn, as.character(x))) } if (is.character(x)) { return(dbQuoteString(conn, x)) } if (inherits(x, "POSIXt")) { return(dbQuoteString( conn, strftime(as.POSIXct(x), "%Y-%m-%d %H-%M-%S%z") )) } if (inherits(x, "Date")) { return(dbQuoteString(conn, as.character(x))) } if (inherits(x, "difftime")) { return(dbQuoteString(conn, format_hms(x))) } if (is.list(x)) { blob_data <- vapply( x, function(x) { if (is.null(x)) { "NULL" } else if (is.raw(x)) { paste0("X'", paste(format(x), collapse = ""), "'") } else { stop("Lists must contain raw vectors or NULL", call. = FALSE) } }, character(1) ) return(SQL(blob_data, names = names(x))) } if (is.logical(x)) { x <- as.numeric(x) } x <- as.character(x) x[is.na(x)] <- "NULL" SQL(x, names = names(x)) } #' @rdname hidden_aliases #' @export setMethod("dbQuoteLiteral", signature("DBIConnection"), dbQuoteLiteral_DBIConnection) DBI/R/dbRollback.R0000644000176200001440000000017014350241735013235 0ustar liggesusers#' @export #' @rdname transactions setGeneric("dbRollback", def = function(conn, ...) standardGeneric("dbRollback") ) DBI/R/dbIsReadOnly.R0000644000176200001440000000075014350241735013521 0ustar liggesusers#' Is this DBMS object read only? #' #' This generic tests whether a database object is read only. #' #' @inheritParams dbGetInfo #' #' @template methods #' @templateVar method_name dbIsReadOnly #' #' @family DBIDriver generics #' @family DBIConnection generics #' @family DBIResult generics #' @family DBIConnector generics #' @export #' @examples #' dbIsReadOnly(ANSI()) setGeneric("dbIsReadOnly", def = function(dbObj, ...) standardGeneric("dbIsReadOnly"), valueClass = "logical") DBI/R/dbCommit.R0000644000176200001440000000016414350241735012737 0ustar liggesusers#' @export #' @rdname transactions setGeneric("dbCommit", def = function(conn, ...) standardGeneric("dbCommit") ) DBI/R/SQL.R0000644000176200001440000000403614350241735011642 0ustar liggesusers#' SQL quoting #' #' This set of classes and generics make it possible to flexibly deal with SQL #' escaping needs. By default, any user supplied input to a query should be #' escaped using either [dbQuoteIdentifier()] or [dbQuoteString()] #' depending on whether it refers to a table or variable name, or is a literal #' string. #' These functions may return an object of the `SQL` class, #' which tells DBI functions that a character string does not need to be escaped #' anymore, to prevent double escaping. #' The `SQL` class has associated the `SQL()` constructor function. #' #' @section Implementation notes: #' #' DBI provides default generics for SQL-92 compatible quoting. If the database #' uses a different convention, you will need to provide your own methods. #' Note that because of the way that S4 dispatch finds methods and because #' SQL inherits from character, if you implement (e.g.) a method for #' `dbQuoteString(MyConnection, character)`, you will also need to #' implement `dbQuoteString(MyConnection, SQL)` - this should simply #' return `x` unchanged. #' #' @param x A character vector to label as being escaped SQL. #' @param ... Other arguments passed on to methods. Not otherwise used. #' @param names Names for the returned object, must have the same length as `x`. #' @return An object of class `SQL`. #' @export #' @examples #' dbQuoteIdentifier(ANSI(), "SELECT") #' dbQuoteString(ANSI(), "SELECT") #' #' # SQL vectors are always passed through as is #' var_name <- SQL("SELECT") #' var_name #' #' dbQuoteIdentifier(ANSI(), var_name) #' dbQuoteString(ANSI(), var_name) #' #' # This mechanism is used to prevent double escaping #' dbQuoteString(ANSI(), dbQuoteString(ANSI(), "SELECT")) SQL <- function(x, ..., names = NULL) { if (!is.null(names)) { stopifnot(length(x) == length(names)) } names(x) <- names new("SQL", x) } #' @rdname SQL #' @export #' @aliases #' SQL-class setClass("SQL", contains = "character") #' @export `[.SQL` <- function(x, ...) SQL(NextMethod()) #' @export `[[.SQL` <- function(x, ...) SQL(NextMethod()) DBI/NEWS.md0000644000176200001440000005117214627152467011772 0ustar liggesusers # DBI 1.2.3 (2024-06-02) ## Bug fixes - `dbQuoteLiteral()` uses the format `"%Y-%m-%d %H-%M-%S%z"` which is understood by more databases (#467, #474). ## Documentation - Use relational-data.org as a replacement for relational.fit.cvut.cz. - Set BS version explicitly for now (@maelle, #478). - Include `dbGetInfo()` in the spec (#477). - Fix typos (@salim-b, #469, @MichaelChirico, #482). # DBI 1.2.2 (2024-02-09) ## Bug fixes - `Id()` does not assign empty names to the components if all arguments are unnamed (#464). - Add spec to version control to avoid weird pandoc errors on CRAN (#465). # DBI 1.2.1 (2024-01-12) ## Bug fixes - Fix `dbWriteTableArrow()` according to spec (#457). - Fix type inference in default method for `dbCreateTableArrow()` (#450). ## Features - `dbAppendTableArrow()` returns number of rows (#454). - Add `temporary` argument to `dbCreateTableArrow()` (#453). - Avoid coercing `params` in default implementation for `dbSendQueryArrow()` (#447). - Use `nanoarrow::infer_nanoarrow_schema()` in the default method for `dbCreateTable()` (#445). ## Chore - Add badge to `DBIResultArrow` class (#452). - Change maintainer e-mail. ## Documentation - Finalize Arrow vignette (#451, #455). - Document new Arrow generics (#444, #449). - Use dbitemplate (@maelle, #442). # DBI 1.2.0 (2023-12-20) ## Breaking changes - `dbUnquoteIdentifier()` creates `Id()` objects without component names and allows non-`NA` character input (#421, #422). ## Features - New generics `dbSendQueryArrow()`, `dbFetchArrow()`, `dbGetQueryArrow()`, `dbReadTableArrow()`, `dbWriteTableArrow()` (@nbenn, #390), `dbCreateTableArrow()`, `dbAppendTableArrow()` (#396), `dbBindArrow()` (#415) and `dbFetchArrowChunk()` (#424), with default implementations via nanoarrow (#414). - `Id()` now accepts unnamed components (#417). If names are provided, the components are arranged in SQL order (@eauleaf, #427). - New `dbIsValid()` method for `"DBIResultArrowDefault"` objects implemented by DBI (#425). - Implement `dbiDataType()` for objects of class `"blob"`. ## Documentation - Update pkgdown template (@maelle, #428, #438, #437). - Clarify repeated parameter binding (#430). - Deal with sundown of `https://relational.fit.cvut.cz` (#423). - Correct vignette titles (#419). - Harmonize table documentation (#400). - Tweak typo, add families for data retrieval and command execution. ## Testing - Enable BLOB tests for arrow \>= 10.0.0 (#395). - Run DBItest for SQLite as part of the checks here (#431). - Fix checks without suggested packages (#420). - Fix Windows tests on GHA (#406). - `testthat::use_testthat(3)` (#416). # DBI 1.1.3 (2022-06-18) ## Features - `dbAppendTable()` accepts `Id` (#381, @renkun-ken). ## Documentation - `?dbSendQuery` and related methods gain a section "The data retrieval flow" (#386). - `?dbSendStatement` and related methods gain a section "The command execution flow" (#386). # DBI 1.1.2 (2021-12-19) ## Features - Use `dbQuoteLiteral()` in default method for `sqlData()` (#362, #371). - Update specification with changes from DBItest 1.7.2 (#367). ## Documentation - The pkgdown documentation for DBI generics (e.g. `?dbConnect`) contains clickable links to all known backends (except ROracle), and an explanatory sentence (#360). - `?Id` gains better examples (#295, #370). - Elaborate on status of `dbWriteTable()` in the documentation (#352, #372). - Make method definition more similar to S3. All `setMethod()` calls refer to top-level functions (#368). - `?dbReadTable` and other pages gain pointers to `Id()` and `SQL()` (#359). # DBI 1.1.1 (2021-01-04) ## Documentation - Expand "Get started" vignette to two tutorials, basic and advanced (#332, @jawond). ## Bug fixes - `dbAppendTable()` now allows columns named `sep` (#336). - `dbAppendTable()` shows a better error message if the input has zero columns (#313). - `sqlInterpolate()` now correctly interprets consecutive comments (#329, @rnorberg). - `dbQuoteLiteral()` works for difftime objects (#325). - `dbQuoteLiteral()` quotes dates as `YYYY-MM-DD` without time zone (#331). ## Internal - Switch to GitHub Actions (#326). - Update URL in `DESCRIPTION`. # DBI 1.1.0 (2019-12-15) ## New features - New `DBIConnector` class (#280). - Specify `immediate` argument to `dbSendQuery()`, `dbGetQuery()`, `dbSendStatement()` and `dbExecute()` (#268). - Use specification for `dbGetInfo()` (#271). - `dbUnquoteIdentifier()` now supports `Id()` objects with `catalog` members (#266, @raffscallion). It also handles unquoted identifiers of the form `table`, `schema.table` or `catalog.schema.table`, for compatibility with dbplyr. ## Documentation - New DBI intro article (#286, @cutterkom). - Add pkgdown reference index (#288). - DBI specification on https://dbi.r-dbi.org/dev/articles/spec now comes with a table of contents and code formatting. - Update examples to refer to `params` instead of `param` (#235). - Improved documentation for `sqlInterpolate()` (#100). Add usage of `SQL()` to `sqlInterpolate()` examples (#259, @renkun-ken). - Improve documentation for `Id`. ## Internal - Add tests for `dbUnquoteIdentifier()` (#279, @baileych). - `sqlInterpolate()` uses `dbQuoteLiteral()` instead of checking the type of the input. - Avoid partial argument match in `dbWriteTable()` (#246, @richfitz). # DBI 1.0.0 (2018-05-02) ## New generics - New `dbAppendTable()` that by default calls `sqlAppendTableTemplate()` and then `dbExecute()` with a `param` argument, without support for `row.names` argument (#74). - New `dbCreateTable()` that by default calls `sqlCreateTable()` and then `dbExecute()`, without support for `row.names` argument (#74). - New `dbCanConnect()` generic with default implementation (#87). - New `dbIsReadOnly()` generic with default implementation (#190, @anhqle). ## Changes - `sqlAppendTable()` now accepts lists for the `values` argument, to support lists of `SQL` objects in R 3.1. - Add default implementation for `dbListFields(DBIConnection, Id)`, this relies on `dbQuoteIdentifier(DBIConnection, Id)` (#75). ## Documentation updates - The DBI specification vignette is rendered correctly from the installed package (#234). - Update docs on how to cope with stored procedures (#242, @aryoda). - Add "Additional arguments" sections and more examples for `dbGetQuery()`, `dbSendQuery()`, `dbExecute()` and `dbSendStatement()`. - The `dbColumnInfo()` method is now fully specified (#75). - The `dbListFields()` method is now fully specified (#75). - The dynamic list of methods in help pages doesn't contain methods in DBI anymore. ## Bug fixes - Pass missing `value` argument to secondary `dbWriteTable()` call (#737, @jimhester). - The `Id` class now uses `` and not `` when printing. - The default `dbUnquoteIdentifier()` implementation now complies to the spec. # DBI 0.8 (2018-02-24) Breaking changes ---------------- - `SQL()` now strips the names from the output if the `names` argument is unset. - The `dbReadTable()`, `dbWriteTable()`, `dbExistsTable()`, `dbRemoveTable()`, and `dbListFields()` generics now specialize over the first two arguments to support implementations with the `Id` S4 class as type for the second argument. Some packages may need to update their documentation to satisfy R CMD check again. New generics ------------ - Schema support: Export `Id()`, new generics `dbListObjects()` and `dbUnquoteIdentifier()`, methods for `Id` that call `dbQuoteIdentifier()` and then forward (#220). - New `dbQuoteLiteral()` generic. The default implementation uses switchpatch to avoid dispatch ambiguities, and forwards to `dbQuoteString()` for character vectors. Backends may override methods that also dispatch on the second argument, but in this case also an override for the `"SQL"` class is necessary (#172). Default implementations ----------------------- - Default implementations of `dbQuoteIdentifier()` and `dbQuoteLiteral()` preserve names, default implementation of `dbQuoteString()` strips names (#173). - Specialized methods for `dbQuoteString()` and `dbQuoteIdentifier()` are available again, for compatibility with clients that use `getMethod()` to access them (#218). - Add default implementation of `dbListFields()`. - The default implementation of `dbReadTable()` now has `row.names = FALSE` as default and also supports `row.names = NULL` (#186). API changes ----------- - The `SQL()` function gains an optional `names` argument which can be used to assign names to SQL strings. Deprecated generics ------------------- - `dbListConnections()` is soft-deprecated by documentation. - `dbListResults()` is deprecated by documentation (#58). - `dbGetException()` is soft-deprecated by documentation (#51). - The deprecated `print.list.pairs()` has been removed. Bug fixes --------- - Fix `dbDataType()` for `AsIs` object (#198, @yutannihilation). - Fix `dbQuoteString()` and `dbQuoteIdentifier()` to ignore invalid UTF-8 strings (r-dbi/DBItest#156). Documentation ------------- - Help pages for generics now contain a dynamic list of methods implemented by DBI backends (#162). - `sqlInterpolate()` now supports both named and positional variables (#216, @hannesmuehleisen). - Point to db.rstudio.com (@wibeasley, #209). - Reflect new 'r-dbi' organization in `DESCRIPTION` (@wibeasley, #207). Internal -------- - Using switchpatch on the second argument for default implementations of `dbQuoteString()` and `dbQuoteIdentifier()`. # DBI 0.7 (2017-06-17) - Import updated specs from `DBItest`. - The default implementation of `dbGetQuery()` now accepts an `n` argument and forwards it to `dbFetch()`. No warning about pending rows is issued anymore (#76). - Require R >= 3.0.0 (for `slots` argument of `setClass()`) (#169, @mvkorpel). # DBI 0.6-1 (2017-04-01) - Fix `dbReadTable()` for backends that do not provide their own implementation (#171). # DBI 0.6 (2017-03-08) - Interface changes - Deprecated `dbDriver()` and `dbUnloadDriver()` by documentation (#21). - Renamed arguments to `sqlInterpolate()` and `sqlParseVariables()` to be more consistent with the rest of the interface, and added `.dots` argument to `sqlParseVariables`. DBI drivers are now expected to implement `sqlParseVariables(conn, sql, ..., .dots)` and `sqlInterpolate(conn, sql, ...)` (#147). - Interface enhancements - Removed `valueClass = "logical"` for those generics where the return value is meaningless, to allow backends to return invisibly (#135). - Avoiding using braces in the definitions of generics if possible, so that standard generics can be detected (#146). - Added default implementation for `dbReadTable()`. - All standard generics are required to have an ellipsis (with test), for future extensibility. - Improved default implementation of `dbQuoteString()` and `dbQuoteIdentifier()` (#77). - Removed `tryCatch()` call in `dbGetQuery()` (#113). - Documentation improvements - Finalized first draft of DBI specification, now in a vignette. - Most methods now draw documentation from `DBItest`, only those where the behavior is not finally decided don't do this yet yet. - Removed `max.connections` requirement from documentation (#56). - Improved `dbBind()` documentation and example (#136). - Change `omegahat.org` URL to `omegahat.net`, the particular document still doesn't exist below the new domain. - Internal - Use roxygen2 inheritance to copy DBI specification to this package. - Use `tic` package for building documentation. - Use markdown in documentation. # DBI 0.5-1 (2016-09-09) - Documentation and example updates. # DBI 0.5 (2016-08-11, CRAN release) - Interface changes - `dbDataType()` maps `character` values to `"TEXT"` by default (#102). - The default implementation of `dbQuoteString()` doesn't call `encodeString()` anymore: Neither SQLite nor Postgres understand e.g. `\n` in a string literal, and all of SQLite, Postgres, and MySQL accept an embedded newline (#121). - Interface enhancements - New `dbSendStatement()` generic, forwards to `dbSendQuery()` by default (#20, #132). - New `dbExecute()`, calls `dbSendStatement()` by default (#109, @bborgesr). - New `dbWithTransaction()` that calls `dbBegin()` and `dbCommit()`, and `dbRollback()` on failure (#110, @bborgesr). - New `dbBreak()` function which allows aborting from within `dbWithTransaction()` (#115, #133). - Export `dbFetch()` and `dbQuoteString()` methods. - Documentation improvements: - One example per function (except functions scheduled for deprecation) (#67). - Consistent layout and identifier naming. - Better documentation of generics by adding links to the class and related generics in the "See also" section under "Other DBI... generics" (#130). S4 documentation is directed to a hidden page to unclutter documentation index (#59). - Fix two minor vignette typos (#124, @mdsumner). - Add package documentation. - Remove misleading parts in `dbConnect()` documentation (#118). - Remove misleading link in `dbDataType()` documentation. - Remove full stop from documentation titles. - New help topic "DBIspec" that contains the full DBI specification (currently work in progress) (#129). - HTML documentation generated by `staticdocs` is now uploaded to https://rstats-db.github.io/DBI for each build of the "production" branch (#131). - Further minor changes and fixes. - Internal - Use `contains` argument instead of `representation()` to denote base classes (#93). - Remove redundant declaration of transaction methods (#110, @bborgesr). # DBI 0.4-1 (2016-05-07, CRAN release) - The default `show()` implementations silently ignore all errors. Some DBI drivers (e.g., RPostgreSQL) might fail to implement `dbIsValid()` or the other methods used. # DBI 0.4 (2016-04-30) * New package maintainer: Kirill Müller. * `dbGetInfo()` gains a default method that extracts the information from `dbGetStatement()`, `dbGetRowsAffected()`, `dbHasCompleted()`, and `dbGetRowCount()`. This means that most drivers should no longer need to implement `dbGetInfo()` (which may be deprecated anyway at some point) (#55). * `dbDataType()` and `dbQuoteString()` are now properly exported. * The default implementation for `dbDataType()` (powered by `dbiDataType()`) now also supports `difftime` and `AsIs` objects and lists of `raw` (#70). * Default `dbGetQuery()` method now always calls `dbFetch()`, in a `tryCatch()` block. * New generic `dbBind()` for binding values to a parameterised query. * DBI gains a number of SQL generation functions. These make it easier to write backends by implementing common operations that are slightly tricky to do absolutely correctly. * `sqlCreateTable()` and `sqlAppendTable()` create tables from a data frame and insert rows into an existing table. These will power most implementations of `dbWriteTable()`. `sqlAppendTable()` is useful for databases that support parameterised queries. * `sqlRownamesToColumn()` and `sqlColumnToRownames()` provide a standard way of translating row names to and from the database. * `sqlInterpolate()` and `sqlParseVariables()` allows databases without native parameterised queries to use parameterised queries to avoid SQL injection attacks. * `sqlData()` is a new generic that converts a data frame into a data frame suitable for sending to the database. This is used to (e.g.) ensure all character vectors are encoded as UTF-8, or to convert R varible types (like factor) to types supported by the database. * The `sqlParseVariablesImpl()` is now implemented purely in R, with full test coverage (#83, @hannesmuehleisen). * `dbiCheckCompliance()` has been removed, the functionality is now available in the `DBItest` package (#80). * Added default `show()` methods for driver, connection and results. * New concrete `ANSIConnection` class and `ANSI()` function to generate a dummy ANSI compliant connection useful for testing. * Default `dbQuoteString()` and `dbQuoteIdentifer()` methods now use `encodeString()` so that special characters like `\n` are correctly escaped. `dbQuoteString()` converts `NA` to (unquoted) NULL. * The initial DBI proposal and DBI version 1 specification are now included as a vignette. These are there mostly for historical interest. * The new `DBItest` package is described in the vignette. * Deprecated `print.list.pairs()`. * Removed unused `dbi_dep()`. # Version 0.3.1 * Actually export `dbIsValid()` :/ * `dbGetQuery()` uses `dbFetch()` in the default implementation. # Version 0.3.0 ## New and enhanced generics * `dbIsValid()` returns a logical value describing whether a connection or result set (or other object) is still valid. (#12). * `dbQuoteString()` and `dbQuoteIdentifier()` to implement database specific quoting mechanisms. * `dbFetch()` added as alias to `fetch()` to provide consistent name. Implementers should define methods for both `fetch()` and `dbFetch()` until `fetch()` is deprecated in 2015. For now, the default method for `dbFetch()` calls `fetch()`. * `dbBegin()` begins a transaction (#17). If not supported, DB specific methods should throw an error (as should `dbCommit()` and `dbRollback()`). ## New default methods * `dbGetStatement()`, `dbGetRowsAffected()`, `dbHasCompleted()`, and `dbGetRowCount()` gain default methods that extract the appropriate elements from `dbGetInfo()`. This means that most drivers should no longer need to implement these methods (#13). * `dbGetQuery()` gains a default method for `DBIConnection` which uses `dbSendQuery()`, `fetch()` and `dbClearResult()`. ## Deprecated features * The following functions are soft-deprecated. They are going away, and developers who use the DBI should begin preparing. The formal deprecation process will begin in July 2015, where these function will emit warnings on use. * `fetch()` is replaced by `dbFetch()`. * `make.db.names()`, `isSQLKeyword()` and `SQLKeywords()`: a black list based approach is fundamentally flawed; instead quote strings and identifiers with `dbQuoteIdentifier()` and `dbQuoteString()`. * `dbGetDBIVersion()` is deprecated since it's now just a thin wrapper around `packageVersion("DBI")`. * `dbSetDataMappings()` (#9) and `dbCallProc()` (#7) are deprecated as no implementations were ever provided. ## Other improvements * `dbiCheckCompliance()` makes it easier for implementors to check that their package is in compliance with the DBI specification. * All examples now use the RSQLite package so that you can easily try out the code samples (#4). * `dbDriver()` gains a more effective search mechanism that doesn't rely on packages being loaded (#1). * DBI has been converted to use roxygen2 for documentation, and now most functions have their own documentation files. I would love your feedback on how we could make the documentation better! # Version 0.2-7 * Trivial changes (updated package fields, daj) # Version 0.2-6 * Removed deprecated \synopsis in some Rd files (thanks to Prof. Ripley) # Version 0.2-5 * Code cleanups contributed by Matthias Burger: avoid partial argument name matching and use TRUE/FALSE, not T/F. * Change behavior of make.db.names.default to quote SQL keywords if allow.keywords is FALSE. Previously, SQL keywords would be name mangled with underscores and a digit. Now they are quoted using '"'. # Version 0.2-4 * Changed license from GPL to LPGL * Fixed a trivial typo in documentation # Version 0.1-10 * Fixed documentation typos. # Version 0.1-9 * Trivial changes. # Version 0.1-8 * A trivial change due to package.description() being deprecated in 1.9.0. # Version 0.1-7 * Had to do a substantial re-formatting of the documentation due to incompatibilities introduced in 1.8.0 S4 method documentation. The contents were not changed (modulo fixing a few typos). Thanks to Kurt Hornik and John Chambers for their help. # Version 0.1-6 * Trivial documentation changes (for R CMD check's sake) # Version 0.1-5 * Removed duplicated setGeneric("dbSetDataMappings") # Version 0.1-4 * Removed the "valueClass" from some generic functions, namely, dbListConnections, dbListResults, dbGetException, dbGetQuery, and dbGetInfo. The reason is that methods for these generics could potentially return different classes of objects (e.g., the call dbGetInfo(res) could return a list of name-value pairs, while dbGetInfo(res, "statement") could be a character vector). * Added 00Index to inst/doc * Added dbGetDBIVersion() (simple wrapper to package.description). # Version 0.1-3 * ??? Minor changes? # Version 0.1-2 * An implementation based on version 4 classes and methods. * Incorporated (mostly Tim Keitt's) comments. DBI/MD50000644000176200001440000004051314627164412011172 0ustar liggesusers8d78e5913a69e729e1718c2d672a55d6 *DESCRIPTION 261c3e3ddc96347b5a8e3f19c299cc5d *NAMESPACE 417237e632e929e4d4516164219ac728 *NEWS.md c2218355e09634686d8efa8d6be3ed40 *R/00-Id.R df6668faefa1a555a8f9e95afeb70904 *R/01-DBIObject.R 7a3a1ecc4caadf1711bcfba9986958b1 *R/02-DBIDriver.R 12d9b4d8127b015ad982b471b9e08b27 *R/03-DBIConnection.R b56706702384fe74719397d7d086f585 *R/04-DBIResult.R 3ac82a661c763fbfae79e7333bd33d18 *R/06-ANSI.R 09cbb7db46c57202c3da61e0d5884d49 *R/07-DBIResultArrow.R 4fc9f615f5906a28c7d6066310f8996a *R/11-dbAppendTable.R 961227f4bbdf9bfde456d892fdd2a265 *R/12-dbCreateTable.R cf34cbfa5168be4ad5eb444630878ea7 *R/13-dbWriteTable.R d5ead71c91f1a898b1eed2344b2a10fd *R/14-dbSendQuery.R 100f6e4f58f047b5ddb8c2fcfe94c44b *R/15-dbBind.R a5a820218b1037f6007c9f8e8cd0f7fc *R/21-dbAppendTableArrow.R af59ea8e692671b4a3999209d4f1879a *R/22-dbCreateTableArrow.R 0b880d74411eed131a9493aae28a179f *R/23-dbWriteTableArrow.R 6d4afc3ecf8f2f30704a9818c61d9c48 *R/24-dbSendQueryArrow.R cf3c78c6dd40ff0543cf9c0d9ac12bf8 *R/25-dbBindArrow.R 05042a2430f0550883d5dbdc8a1e7260 *R/DBI-package.R cdd8f252d119dd2440952a829a91d81e *R/DBIConnector.R b2f768366db7da783ad65fca06d8012f *R/SQL.R caeed8e6b8e2eb866e8d2adee097cffb *R/SQLKeywords.R 2e3f7c99fc5daf79625510e2639a5243 *R/SQLKeywords_DBIObject.R cc8c512231d31031200e31d760ad008b *R/SQLKeywords_missing.R 4d9aa53c1ba51a9cdc12438530a86b64 *R/data-types.R 19cd20ad37a89a7fd9046bd159252be1 *R/data.R d7f9de677c0017d6e0c5b544ffeada99 *R/dbAppendTableArrow_DBIConnection.R 98300895840f652eb932b566fcba37ba *R/dbAppendTable_DBIConnection.R e900a6ce7e29178aa307ca2169433da4 *R/dbBegin.R 4ec90f1ff24745365a46f8182e9f5577 *R/dbBindArrow_DBIResult.R 37fee62a4e0f1ce0b4922ca436a44978 *R/dbBindArrow_DBIResultArrowDefault.R 9641bb6f1784fab5dfe4950f42f97098 *R/dbBind_DBIResultArrow.R 4d18b71c11b50a6c736046aa8c6b5e81 *R/dbCallProc.R 9ee1e1b8b67059460420430807f368e1 *R/dbCanConnect.R 8e74ceea09e2d78e7578dec900608289 *R/dbCanConnect_DBIDriver.R 6c42dfe37ae152191e0448ccb141403a *R/dbClearResult.R 83046f3ed56c119a9e877c5b3111177b *R/dbClearResult_DBIResultArrow.R c49c0c4039f2de60588674d638adce9d *R/dbColumnInfo.R 1dabdc46053a1f642277624017c1450b *R/dbCommit.R 5e5870604695bc0349a5cb88fabc0a15 *R/dbConnect.R 2650c8652de8a83756fedc456a03d476 *R/dbConnect_DBIConnector.R f776b9958ed3b36bcb20cb14e332ef43 *R/dbCreateTableArrow_DBIConnection.R b4ca03a0e43bed3b3cb9727f60ce8972 *R/dbCreateTable_DBIConnection.R be8236ab5a53269ffba3547a24250615 *R/dbDataType.R e86feef168b8c012513dd50b015fcd9e *R/dbDataType_DBIConnector.R 0c75124e20e8fb03d107b30a27c19760 *R/dbDataType_DBIObject.R 3f01d06b2390c76fcaf31fc84ab494a1 *R/dbDisconnect.R d66a755c1bf2907a0b0e50056d145311 *R/dbDriver.R 77006a92266de53743b1b27dc2166e52 *R/dbDriver_character.R fed6e5a93011a01cfd9d15fdfc326208 *R/dbExecute.R 0ccf1a45aeaa32d7d277395b2d7c012d *R/dbExecute_DBIConnection_character.R e58fcaa3742162f31d3d29d3dfa69a48 *R/dbExistsTable.R f5c1fa86bf5c8090e849d85127669ba1 *R/dbExistsTable_DBIConnection_Id.R 9b836fc3ce8672aa6ed07e2e5a44c6c6 *R/dbFetch.R c164207c1e7f72f3140dabaa871fdd4f *R/dbFetchArrow.R 9e6952bfb89b6c7b441a8ad9a2c790ea *R/dbFetchArrowChunk.R a66560bf24f18549eeeb285777a072ad *R/dbFetchArrowChunk_DBIResultArrow.R 3b578aad710e05a8af21dd41d71bbd28 *R/dbFetchArrow_DBIResultArrow.R e98adbf9e505b36bceaaea8f3c935573 *R/dbFetch_DBIResult.R 7ade7dc6b29c0c94dff74dd8088df3f5 *R/dbFetch_DBIResultArrow.R 85a9f801cce4583dfde1b9cc8383145f *R/dbGetConnectArgs.R 115ea9a3b433f0f7e040f4eba201111e *R/dbGetConnectArgs_DBIConnector.R 2982ccce2dd23ab15b2a6b3d4e0697a3 *R/dbGetException.R d3e2adf3f9e1723da8246344d1bcb7b9 *R/dbGetInfo.R 2fd40282c5a9b312901ecc629586f37f *R/dbGetInfo_DBIResult.R bb4fcd50d16319130582914d62557e6f *R/dbGetInfo_DBIResultArrow.R 52227dda89977b4528636ff0acba45da *R/dbGetQuery.R 38f9d19bbe2bd106ae3ed459602ef465 *R/dbGetQueryArrow.R 41cdbf853f51ca8e8b309e3c86b84052 *R/dbGetQueryArrow_DBIConnection.R 68ae362dc37aa0d769441a1938e027e8 *R/dbGetQuery_DBIConnection_character.R 959c58cd89928b6a16f11bd9c33a027c *R/dbGetRowCount.R f3a524cf2d7e3ac9ca18ad4ec0c75ddf *R/dbGetRowCount_DBIResultArrow.R 287337484b5f094245e8980da9160737 *R/dbGetRowsAffected.R ffd293243ac1b8a5c63d5df808d47e0a *R/dbGetRowsAffected_DBIResultArrow.R 402ef1dc8c406dce2f87eddbde82d789 *R/dbGetStatement.R 13db35076155e485b92abfb02a6f8f76 *R/dbGetStatement_DBIResultArrow.R 0a5c00c7c9812cfe4c96c2d376fa2946 *R/dbHasCompleted.R a42df80d60c38958cb8b93247baccfd0 *R/dbHasCompleted_DBIResultArrow.R f5547a131754975a92f3879f86c80ed5 *R/dbIsReadOnly.R 20c1c442df9885b1dde2a79b4d5fdc52 *R/dbIsReadOnly_DBIConnector.R 083f467fd264c59ccafacef611d3429d *R/dbIsReadOnly_DBIObject.R a186bdf6d0c8d3e0b78c6a1094f26fd4 *R/dbIsValid.R 13ee3657325cf77ac02feac607cef513 *R/dbIsValid_DBIResultArrowDefault.R 0b8b92d0d78cebc2b88ba17b3ebe8574 *R/dbListConnections.R 6f1d641a9ec46c4d5e1b32be18ce1247 *R/dbListFields.R fc143f42ee66f163a2029905c0d0376f *R/dbListFields_DBIConnection_Id.R 7c220952130574853a9892960a784d1b *R/dbListFields_DBIConnection_character.R b2e22417ac3d8436b2f56fc10455dc68 *R/dbListObjects.R e2cdc2847371073a478df43ff17b5c9d *R/dbListObjects_DBIConnection_ANY.R a465bb1c64e72d5e7fc3c60e39bcacaf *R/dbListResults.R d463a14ae7878452e5f3f72001ee7e35 *R/dbListTables.R 862474d590c6846daaeb12d65ab32c45 *R/dbQuoteIdentifier.R d80f59eecd7a572ea44a7997694d939a *R/dbQuoteIdentifier_DBIConnection.R 1c63676069d58c4bf193742e2d7113b8 *R/dbQuoteLiteral.R 10952ff6add847a3be873313ad3a0d9e *R/dbQuoteLiteral_DBIConnection.R 7d0c587f2e3894ba81e292c1b5d6a5d6 *R/dbQuoteString.R 0974935ea604879e4367f367d0d94bad *R/dbQuoteString_DBIConnection.R 84e13a6ada4e00a661369339993b0dc2 *R/dbReadTable.R 24a6fab62a93fa7e824ef64401a85194 *R/dbReadTableArrow.R e5ea480546bbac115d297a13e4f74177 *R/dbReadTableArrow_DBIConnection.R 1be9fdeeea4c0bfcb3321b534b80097d *R/dbReadTable_DBIConnection_Id.R 61f6bb0784e687f75a2515bd128ce84e *R/dbReadTable_DBIConnection_character.R 1c4995f9f8d32e3e5fd465739a44546f *R/dbRemoveTable.R f8b15fec3e7da5e74551779fb36d315b *R/dbRemoveTable_DBIConnection_Id.R d1bb64bedf72456c277d755dc3019bd7 *R/dbRollback.R a2445ca996660aea9a1ffd2122b85fd2 *R/dbSendQueryArrow_DBIConnection.R 252842841b9de691f29c87e3066be2d1 *R/dbSendStatement.R f6e93624dcaae0b79400b2dbd19eeff6 *R/dbSendStatement_DBIConnection_character.R ffd26e8de2efd581f655c68e19430651 *R/dbSetDataMappings.R e673e520bbf8d0c8b7635474872211f9 *R/dbUnloadDriver.R 2afffa399bf9ae54e659699187b54241 *R/dbUnquoteIdentifier.R 59d10e6057e53b02202ee69d158272cc *R/dbUnquoteIdentifier_DBIConnection.R 2f73eb7f5a51b5a0d2ed7b6cb456eee7 *R/dbWithTransaction.R e5c2e8bbef965ec03de7a4b7d4ee783a *R/dbWithTransaction_DBIConnection.R ace89ef65de9cb028919c13f92a71c77 *R/dbWriteTableArrow_DBIConnection.R 09a5767589db14c3c3ba73553030ed23 *R/dbWriteTable_DBIConnection_Id_ANY.R 8277fb3db3b97aa958d0c4061de85f30 *R/dbiDataType.R 650d9ed6004ebf09774427ee668ed4a9 *R/dbiDataType_ANY.R 65e5f21c95d37a35f6c8e9bf26af4924 *R/dbiDataType_AsIs.R e14fcdbe5bd13075c2193fa6ffaf5725 *R/dbiDataType_Date.R ac198cf63328dbe7fd1711cb184b8676 *R/dbiDataType_POSIXct.R 94c34b67f3b9c2182a76f58b514294b9 *R/dbiDataType_character.R c83e452b5b55e1fa6a4db75c846ed422 *R/dbiDataType_data.frame.R 13b50d36a649b4b9a31210bd60334a22 *R/dbiDataType_default.R 450179c1d1f5a291ff0356d162a16dd3 *R/dbiDataType_difftime.R 6b84efab5913fff83c08e4395add3887 *R/dbiDataType_integer.R 5b77a56457bb158205ed0ba49cf09422 *R/dbiDataType_list.R 2ef2c7e953c5fe370c087dc1a47cb8cd *R/dbiDataType_logical.R 5212cee8aa1f93cb8858891aa051cd6f *R/dbiDataType_numeric.R 7b11396db0584f8dcfb58a6204ca8c4d *R/deprecated.R 1287ce9bc9bb3a7d8a6c5107427daa38 *R/fetch.R 5651cd8a666eb10359ab0a1796e3436c *R/hms.R 91b19c51abe58a6d1de6a45579350694 *R/interpolate.R 4126e52937f6f393db327b732c514ae6 *R/isSQLKeyword.R 0a88ed941faa636132ad3d52f73af8cf *R/isSQLKeyword_DBIObject_character.R c86571daef158f70da25b27202a5d650 *R/make.db.names.R b41c1f90d364dcc59258aba6b8655a11 *R/make.db.names_DBIObject_character.R d299a8067c3c4c3f324ce07324b41030 *R/methods_as_rd.R 475c479c78008458508ab9ab9100c4a5 *R/rownames.R d0f80664d65f61b3333651242759530d *R/show_AnsiConnection.R 3517272e0ee5248cb2cda618e5725e06 *R/show_DBIConnection.R 44656888881609c3aaaba36d118bd00b *R/show_DBIConnector.R c56d4e1596bc44c0b69148d3a8e75668 *R/show_DBIDriver.R ea4f9428ed80facc11f600319d096efb *R/show_DBIResult.R c55be6c2418396a61394653ab4d667aa *R/show_Id.R 5b47c215dc77c4743a76852e264e67ce *R/show_SQL.R 0571b97a57ef2f373003f52a416f0d36 *R/sqlAppendTable.R db577eb92c0f9e9e5d2b1a845f78218d *R/sqlAppendTableTemplate.R b6e559aa5ede9ec6945a695e7dab0600 *R/sqlAppendTable_DBIConnection.R fea1511aa6ef8a5b4e87572c425d60e3 *R/sqlCreateTable.R c04a2ea0203342e3790c5cd77a4ffa75 *R/sqlCreateTable_DBIConnection.R 900d01b72095344950f5854679dd84ba *R/sqlData.R 24f1bf8225b3cd27b652ecd726b0b7bf *R/sqlData_DBIConnection.R 2764379e7293fd7e2ecaa15cc11341d6 *R/sqlInterpolate.R 89177ca946708c77672ede3dc9b2d2ad *R/sqlInterpolate_DBIConnection.R f25218d24f247f5d5b8b70a3d878e082 *R/sqlParseVariables.R a0349cfd6f9eab18042640fae7fcf5c2 *R/sqlParseVariables_DBIConnection.R 42f3ac8f9e3bf2c02205e18b7be385f3 *R/summary.R 85cab3f8e3af768d579592639c24a40c *R/summary_DBIObject.R c2e81afb106abc23851775e46d795000 *R/transactions.R 1b7c83688dd5adabc765f44ab64e4b43 *README.md 7d62f690f8554c8b823ae1979c9b8d68 *build/DBI.pdf 9d6a4d445adf5552296d27aba398fd0d *build/stage23.rdb 8ea4ad2697c04c40902287d4aa6e0ea6 *build/vignette.rds 4f23fe94e7b1c0e0f5d07dbe298645bf *inst/doc/DBI-1.Rmd 611b4cde1385bed160c18fa881b77f16 *inst/doc/DBI-1.html 0a4b21c573eb29759a98b169595c61b3 *inst/doc/DBI-advanced.R 27d7c839fcf5e4f1bff2f05f58280958 *inst/doc/DBI-advanced.Rmd 7e20ccc37f976a6b62402be65f40a8bb *inst/doc/DBI-advanced.html 95fb12f4306c5310eb1f2031de5e8a4a *inst/doc/DBI-arrow.R 75540b51f9123b5f2d12716079a4900e *inst/doc/DBI-arrow.Rmd 55698281e871393cceed25188aa964e4 *inst/doc/DBI-arrow.html 0cb90dc5f9e5b0a9b289f70dfe997079 *inst/doc/DBI-history.Rmd a08e730c0c2f3c4f7bb370540800f70f *inst/doc/DBI-history.html 1d63a9a39439cf84d18d2ef16ad8c30f *inst/doc/DBI-proposal.Rmd 2a3245bfc9423a379175736fa58d4f89 *inst/doc/DBI-proposal.html 0eda7529fb158411edd38d0b2b40364f *inst/doc/DBI.R 943db4a0995e4173aafff67996c974c9 *inst/doc/DBI.Rmd 3666c665f24e544d414859c710df0825 *inst/doc/DBI.html 9c78777c778e752aa9c7b00e0276d7ed *inst/doc/backend.R 079397ec63b690111df65842436e40ad *inst/doc/backend.Rmd 9faff0018e87a7a07c7bd58e906ba2ac *inst/doc/backend.html 79a10903a9332c71d8092d7859073f1f *inst/doc/spec.R 55510128b0e7e531f19c4229874cfd0e *inst/doc/spec.Rmd cf279a1d4178c92eb22c3eb76e608182 *inst/doc/spec.html 3414b76d8057e97cfd58968b7a7ac837 *man/ANSI.Rd ca1f4924bbe96b29d4232c3d5790bc3e *man/DBI-package.Rd 35ce42649da0851e2b89b03a73e7da18 *man/DBIConnection-class.Rd fbbc951da774063bd0e2136b46142a29 *man/DBIConnector-class.Rd d6bab15f03567bc5047491d1b1de9ac2 *man/DBIDriver-class.Rd 95b414ddf62b52d5e3991ebde2bb9bd8 *man/DBIObject-class.Rd 73f7e24e72271377afe15a0d32772fe5 *man/DBIResult-class.Rd 410ef6f7cebf63c23f1c529abfed78b2 *man/DBIResultArrow-class.Rd 3a90727203cd716586e82c69e8af3717 *man/Id.Rd 0abe5e81e5b910eb92f501e0d12102f5 *man/SQL.Rd 9ca08a779d4dc555682b818c64a72ea6 *man/dbAppendTable.Rd 83eb878e2fda73b7043893a138810ee1 *man/dbAppendTableArrow.Rd 2eaa98dab4e8be541a985e72602c5bc5 *man/dbBind.Rd f087a3da11250b3d4671313d3218da0c *man/dbCallProc.Rd d51f7887d3d93354845348e6c0d41ae0 *man/dbCanConnect.Rd b1ea834f9c6f30ac454ce3930a15d8e1 *man/dbClearResult.Rd 6157b5cd052c01835626b0016c64e6c0 *man/dbColumnInfo.Rd 0b5b91df5d762f6c66217df381c006f8 *man/dbConnect.Rd 202feaea29c6ac07bcf18011c60908d2 *man/dbCreateTable.Rd 98e3fea5a3ef7c02fa03ed9d6a8c59d2 *man/dbCreateTableArrow.Rd 49ca842dac22bb37338ae741b3aa5818 *man/dbDataType.Rd fb3321ad91dcc7da798bc54b8adbd975 *man/dbDisconnect.Rd 39cfe00271b1b9bf943383c9effcad85 *man/dbDriver.Rd 07a25413e45b3b7a016b52f438f653c7 *man/dbExecute.Rd 3413e28ba265fb4b5a2e9bf5323bc3a6 *man/dbExistsTable.Rd d02037c658f96627c641234d81f0ae34 *man/dbFetch.Rd 9f6a96f8af9adad24e217e89d57fddee *man/dbFetchArrow.Rd ff966e7324f57067bde27f3d35805a80 *man/dbFetchArrowChunk.Rd 05ffd824319d21145d084e7c150fd5f6 *man/dbGetConnectArgs.Rd 600709b1318e882e99b98e90fa8ba7e7 *man/dbGetDBIVersion.Rd 5407452897fa0a555cd2a693f45bbf87 *man/dbGetException.Rd 1725cae3fa87bd2adb8245924c18b0e7 *man/dbGetInfo.Rd 9787f179ba0245776c5dc761cadc0b03 *man/dbGetQuery.Rd dfe041c29e196dc1dc419c872cd9ef0d *man/dbGetQueryArrow.Rd 04dfeaa19769335d9a1888a04e9fd6c5 *man/dbGetRowCount.Rd 67fef2da3f284238891678ba8ef1bd56 *man/dbGetRowsAffected.Rd 7d3e5a17a2e866bae80b132757c77495 *man/dbGetStatement.Rd 727c185eb22964a87c01a20833bb56c2 *man/dbHasCompleted.Rd 12718205b9dd838dfcea973df6a99197 *man/dbIsReadOnly.Rd 7ec84eb5a3c6199b606f93eaf5b67b85 *man/dbIsValid.Rd 45195aabed941c5835837ef3944a48f6 *man/dbListConnections.Rd cea3c825675995991fe650cbffc35310 *man/dbListFields.Rd 01ced763517ec2131d1a3856276969ca *man/dbListObjects.Rd 58732b4fa70cf51a2770513b2ad54e8f *man/dbListResults.Rd ade0fee9405cf8a697bb7d38ad8b1656 *man/dbListTables.Rd be7f0c0ff7401f6eb68a22b08cfe1fb9 *man/dbQuoteIdentifier.Rd 2df8574f499bb96b4175811d03c2ac11 *man/dbQuoteLiteral.Rd abf1f4b79010ac0f23838b9defac307d *man/dbQuoteString.Rd 5d71a9b592d439f4f3e5643c41fad49c *man/dbReadTable.Rd 008c622b6c04ad85d9677d19318f3197 *man/dbReadTableArrow.Rd 12ed8873608e8406cf034334cebe950a *man/dbRemoveTable.Rd 1bada4d64269c510237c9d21ae689a98 *man/dbSendQuery.Rd 041e7bd404116507511fe5d540dd9cfe *man/dbSendQueryArrow.Rd 944d7e3df0fb8502b2d22d4c42c4ce08 *man/dbSendStatement.Rd 62847b9c4d0251dd8ba14ab4d1f2005f *man/dbSetDataMappings.Rd e2c6e3ec488402badefce8f72fd70e3c *man/dbUnquoteIdentifier.Rd 83c8e970db9c56981b24d60b996fdbbe *man/dbWithTransaction.Rd 9996f068a8772f32f8d962938541767c *man/dbWriteTable.Rd 2b0c3b2302f6d9770fb31b350cb50779 *man/dbWriteTableArrow.Rd eeb064c9b0e28e5263755b8b2b8fbf13 *man/dot-SQL92Keywords.Rd a1cbaf3f328e8d74e747faacf640c7fc *man/figures/lifecycle-archived.svg 6f521fb1819410630e279d1abf88685a *man/figures/lifecycle-defunct.svg 391f696f961e28914508628a7af31b74 *man/figures/lifecycle-deprecated.svg 691b1eb2aec9e1bec96b79d11ba5e631 *man/figures/lifecycle-experimental.svg 405e252e54a79b33522e9699e4e9051c *man/figures/lifecycle-maturing.svg f41ed996be135fb35afe00641621da61 *man/figures/lifecycle-questioning.svg 306bef67d1c636f209024cf2403846fd *man/figures/lifecycle-soft-deprecated.svg ed42e3fbd7cc30bc6ca8fa9b658e24a8 *man/figures/lifecycle-stable.svg bf2f1ad432ecccee3400afe533404113 *man/figures/lifecycle-superseded.svg 3bbccfce9273099763a85541a3f653d5 *man/hidden_aliases.Rd ffba08bcb57becb6455b5165b6ef441d *man/make.db.names.Rd 4a7f8a265551b2f3dea24c3692721638 *man/rownames.Rd 5a453dec45fc5446ff0f2fe79c2c8e47 *man/sqlAppendTable.Rd 68107961a34d4649f3a65a98ffaed1da *man/sqlCreateTable.Rd 8e60c9fd9089f329a66109bcb33762a6 *man/sqlData.Rd 7ffb373db05e03d2408935888800d8d3 *man/sqlInterpolate.Rd f0d18acb231943d6f25691e6d1558492 *man/sqlParseVariables.Rd 0304b917fc8a3c45937ba0a85adc9515 *man/transactions.Rd bf33e807cc16ea1b4376f48ebde12861 *tests/testthat.R 72e4e900b434270afacf30c871276669 *tests/testthat/_snaps/00-Id.md a607e1deab234336d12e88ad2b80fd80 *tests/testthat/helper-dummy.R 6d7152ea22dc498b844cb6d912b1c771 *tests/testthat/setup.R 513ea56d219dfe4e417f9eb46e2ad904 *tests/testthat/test-00-Id.R 436a55ac43f7f5c5a5f915cad09056bd *tests/testthat/test-DBItest.R 4c1320f3b7ceeb77d067450f0421991f *tests/testthat/test-arrow.R c85afd831e2fdf9e4cbb9a8ebb73671e *tests/testthat/test-data-type.R 3f714565f149898283b4521d6363c4e9 *tests/testthat/test-dbUnquoteIdentifier_DBIConnection.R a715746851715628777aa126e248c956 *tests/testthat/test-interpolate.R 7413bb46ce0b157be435b7fe17523d59 *tests/testthat/test-methods.R e701a57076d59ecf60767f3a61bba1c2 *tests/testthat/test-quote.R 0c6dc973642147f079d15e0477aa63d4 *tests/testthat/test-quoting.R 7895ec58f5c8d1e39634cbe839439283 *tests/testthat/test-rownames.R d6fd2ea45be6ac9ebf2643f2ea29dcdf *tests/testthat/test-sql-df.R bda1a87eaadd2fa466b451a36be1bf7a *tests/testthat/test-table-insert.R 4f23fe94e7b1c0e0f5d07dbe298645bf *vignettes/DBI-1.Rmd 27d7c839fcf5e4f1bff2f05f58280958 *vignettes/DBI-advanced.Rmd 75540b51f9123b5f2d12716079a4900e *vignettes/DBI-arrow.Rmd 0cb90dc5f9e5b0a9b289f70dfe997079 *vignettes/DBI-history.Rmd 1d63a9a39439cf84d18d2ef16ad8c30f *vignettes/DBI-proposal.Rmd 943db4a0995e4173aafff67996c974c9 *vignettes/DBI.Rmd 079397ec63b690111df65842436e40ad *vignettes/backend.Rmd 67cca7009a40f5c6bab58418607deb57 *vignettes/biblio.bib 16facd043de5250ab88f5b3badef9ab0 *vignettes/hierarchy.png 55510128b0e7e531f19c4229874cfd0e *vignettes/spec.Rmd 6cb2e47d8eabb1ca65e3cade03449d3d *vignettes/spec.md DBI/inst/0000755000176200001440000000000014627152535011637 5ustar liggesusersDBI/inst/doc/0000755000176200001440000000000014627152535012404 5ustar liggesusersDBI/inst/doc/DBI-advanced.R0000644000176200001440000001227414627152530014671 0ustar liggesusers## ----setup, include=FALSE----------------------------------------------------- library(knitr) opts_chunk$set( echo = TRUE, error = Sys.getenv("IN_PKGDOWN") != "true" || (getRversion() < "3.5") ) knit_print.data.frame <- function(x, ...) { print(head(x, 3)) if (nrow(x) > 3) { cat("Showing 3 out of", nrow(x), "rows.\n") } invisible(x) } registerS3method("knit_print", "data.frame", "knit_print.data.frame") ## ----------------------------------------------------------------------------- library(DBI) con <- dbConnect( RMariaDB::MariaDB(), host = "db.relational-data.org", port = 3306, username = "guest", password = "relational", dbname = "sakila" ) res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = 'G'") df <- dbFetch(res, n = 3) dbClearResult(res) head(df, 3) ## ----------------------------------------------------------------------------- res <- dbSendQuery(con, "SELECT * FROM film") while (!dbHasCompleted(res)) { chunk <- dbFetch(res, n = 300) print(nrow(chunk)) } dbClearResult(res) ## ----quote-------------------------------------------------------------------- safe_id <- dbQuoteIdentifier(con, "rating") safe_param <- dbQuoteLiteral(con, "G") query <- paste0("SELECT title, ", safe_id, " FROM film WHERE ", safe_id, " = ", safe_param) query res <- dbSendQuery(con, query) dbFetch(res) dbClearResult(res) ## ----------------------------------------------------------------------------- id <- "rating" param <- "G" query <- glue::glue_sql("SELECT title, {`id`} FROM film WHERE {`id`} = {param}", .con = con) df <- dbGetQuery(con, query) head(df, 3) ## ----params------------------------------------------------------------------- params <- list("G") safe_id <- dbQuoteIdentifier(con, "rating") query <- paste0("SELECT * FROM film WHERE ", safe_id, " = ?") query res <- dbSendQuery(con, query, params = params) dbFetch(res, n = 3) dbClearResult(res) ## ----multi-param-------------------------------------------------------------- q_params <- list("G", 90) query <- "SELECT title, rating, length FROM film WHERE rating = ? AND length >= ?" res <- dbSendQuery(con, query, params = q_params) dbFetch(res, n = 3) dbClearResult(res) ## ----dbbind------------------------------------------------------------------- res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = ?") dbBind(res, list("G")) dbFetch(res, n = 3) dbBind(res, list("PG")) dbFetch(res, n = 3) dbClearResult(res) ## ----bind_quotestring--------------------------------------------------------- res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = ?") dbBind(res, list(c("G", "PG"))) dbFetch(res, n = 3) dbClearResult(res) ## ----bind-multi-param--------------------------------------------------------- q_params <- list(c("G", "PG"), c(90, 120)) query <- "SELECT title, rating, length FROM film WHERE rating = ? AND length >= ?" res <- dbSendQuery(con, query, params = q_params) dbFetch(res, n = 3) dbClearResult(res) ## ----disconnect--------------------------------------------------------------- dbDisconnect(con) ## ----------------------------------------------------------------------------- library(DBI) con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cars", head(cars, 3)) dbExecute( con, "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)" ) rs <- dbSendStatement( con, "INSERT INTO cars (speed, dist) VALUES (4, 4), (5, 5), (6, 6)" ) dbGetRowsAffected(rs) dbClearResult(rs) dbReadTable(con, "cars") ## ----------------------------------------------------------------------------- dbDisconnect(con) ## ----------------------------------------------------------------------------- con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cash", data.frame(amount = 100)) dbWriteTable(con, "account", data.frame(amount = 2000)) withdraw <- function(amount) { # All operations must be carried out as logical unit: dbExecute(con, "UPDATE cash SET amount = amount + ?", list(amount)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(amount)) } withdraw_transacted <- function(amount) { # Ensure atomicity dbBegin(con) # Perform operation withdraw(amount) # Persist results dbCommit(con) } withdraw_transacted(300) ## ----------------------------------------------------------------------------- dbReadTable(con, "cash") dbReadTable(con, "account") ## ----------------------------------------------------------------------------- withdraw_if_funds <- function(amount) { dbBegin(con) withdraw(amount) # Rolling back after detecting negative value on account: if (dbReadTable(con, "account")$amount >= 0) { dbCommit(con) TRUE } else { message("Insufficient funds") dbRollback(con) FALSE } } withdraw_if_funds(5000) dbReadTable(con, "cash") dbReadTable(con, "account") ## ----error = TRUE------------------------------------------------------------- withdraw_safely <- function(amount) { dbWithTransaction(con, { withdraw(amount) if (dbReadTable(con, "account")$amount < 0) { stop("Error: insufficient funds", call. = FALSE) } }) } withdraw_safely(5000) dbReadTable(con, "cash") dbReadTable(con, "account") ## ----------------------------------------------------------------------------- dbDisconnect(con) DBI/inst/doc/backend.html0000644000176200001440000007315014627152534014666 0ustar liggesusersImplementing a new backend

Implementing a new backend

Hadley Wickham, Kirill Müller

The goal of this document is to help you implement a new backend for DBI.

If you are writing a package that connects a database to R, I highly recommend that you make it DBI compatible because it makes your life easier by spelling out exactly what you need to do. The consistent interface provided by DBI makes it easier for you to implement the package (because you have fewer arbitrary choices to make), and easier for your users (because it follows a familiar pattern). In addition, the DBItest package provides test cases which you can easily incorporate in your package.

I’ll illustrate the process using a fictional database called Kazam.

Getting started

Start by creating a package. It’s up to you what to call the package, but following the existing pattern of RSQLite, RMySQL, RPostgres and ROracle will make it easier for people to find it. For this example, I’ll call my package RKazam.

A ready-to-use template package is available at https://github.com/r-dbi/RKazam/. You can start by creating a new GitHub repository from this template, or by copying the package code. Rename “Kazam” to your desired name everywhere. The template package already contains dummy implementations for all classes and methods.

If you chose to create the package manually, make sure to include in your DESCRIPTION:

Imports:
  DBI (>= 0.3.0),
  methods
Suggests:
  DBItest, testthat

Importing DBI is fine, because your users are not supposed to attach your package anyway; the preferred method is to attach DBI and use explicit qualification via :: to access the driver in your package (which needs to be done only once).

Testing

Why testing at this early stage? Because testing should be an integral part of the software development cycle. Test right from the start, add automated tests as you go, finish faster (because tests are automated) while maintaining superb code quality (because tests also check corner cases that you might not be aware of). Don’t worry: if some test cases are difficult or impossible to satisfy, or take too long to run, you can just turn them off.

Take the time now to head over to the DBItest vignette at vignette("test", package = "DBItest"). You will find a vast amount of ready-to-use test cases that will help you in the process of implementing your new DBI backend.

Add custom tests that are not covered by DBItest at your discretion, or enhance DBItest and file a pull request if the test is generic enough to be useful for many DBI backends.

Driver

Start by making a driver class which inherits from DBIDriver. This class doesn’t need to do anything, it’s just used to dispatch other generics to the right method. Users don’t need to know about this, so you can remove it from the default help listing with @keywords internal:

#' Driver for Kazam database.
#'
#' @keywords internal
#' @export
#' @import DBI
#' @import methods
setClass("KazamDriver", contains = "DBIDriver")

The driver class was more important in older versions of DBI, so you should also provide a dummy dbUnloadDriver() method.

#' @export
#' @rdname Kazam-class
setMethod("dbUnloadDriver", "KazamDriver", function(drv, ...) {
  TRUE
})

If your package needs global setup or tear down, do this in the .onLoad() and .onUnload() functions.

You might also want to add a show method so the object prints nicely:

setMethod("show", "KazamDriver", function(object) {
  cat("<KazamDriver>\n")
})

Next create Kazam() which instantiates this class.

#' @export
Kazam <- function() {
  new("KazamDriver")
}

Kazam()
#> <KazamDriver>

Connection

Next create a connection class that inherits from DBIConnection. This should store all the information needed to connect to the database. If you’re talking to a C api, this will include a slot that holds an external pointer.

#' Kazam connection class.
#'
#' @export
#' @keywords internal
setClass("KazamConnection",
  contains = "DBIConnection",
  slots = list(
    host = "character",
    username = "character",
    # and so on
    ptr = "externalptr"
  )
)

Now you have some of the boilerplate out of the way, you can start work on the connection. The most important method here is dbConnect() which allows you to connect to a specified instance of the database. Note the use of @rdname Kazam. This ensures that Kazam() and the connect method are documented together.

#' @param drv An object created by \code{Kazam()}
#' @rdname Kazam
#' @export
#' @examples
#' \dontrun{
#' db <- dbConnect(RKazam::Kazam())
#' dbWriteTable(db, "mtcars", mtcars)
#' dbGetQuery(db, "SELECT * FROM mtcars WHERE cyl == 4")
#' }
setMethod("dbConnect", "KazamDriver", function(drv, ...) {
  # ...

  new("KazamConnection", host = host, ...)
})

  • Replace ... with the arguments needed to connect to your database. You’ll always need to include ... in the arguments, even if you don’t use it, for compatibility with the generic.

  • This is likely to be where people first come for help, so the examples should show how to connect to the database, and how to query it. (Obviously these examples won’t work yet.) Ideally, include examples that can be run right away (perhaps relying on a publicly hosted database), but failing that surround in \dontrun{} so people can at least see the code.

Next, implement show() and dbDisconnect() methods.

Results

Finally, you’re ready to implement the meat of the system: fetching results of a query into a data frame. First define a results class:

#' Kazam results class.
#'
#' @keywords internal
#' @export
setClass("KazamResult",
  contains = "DBIResult",
  slots = list(ptr = "externalptr")
)

Then write a dbSendQuery() method. This takes a connection and SQL string as arguments, and returns a result object. Again ... is needed for compatibility with the generic, but you can add other arguments if you need them.

#' Send a query to Kazam.
#'
#' @export
#' @examples
#' # This is another good place to put examples
setMethod("dbSendQuery", "KazamConnection", function(conn, statement, ...) {
  # some code
  new("KazamResult", ...)
})

Next, implement dbClearResult(), which should close the result set and free all resources associated with it:

#' @export
setMethod("dbClearResult", "KazamResult", function(res, ...) {
  # free resources
  TRUE
})

The hardest part of every DBI package is writing the dbFetch() method. This needs to take a result set and (optionally) number of records to return, and create a dataframe. Mapping R’s data types to those of your database may require a custom implementation of the dbDataType() method for your connection class:

#' Retrieve records from Kazam query
#' @export
setMethod("dbFetch", "KazamResult", function(res, n = -1, ...) {
  ...
})

# (optionally)

#' Find the database data type associated with an R object
#' @export
setMethod("dbDataType", "KazamConnection", function(dbObj, obj, ...) {
  ...
})

Next, implement dbHasCompleted() which should return a logical indicating if there are any rows remaining to be fetched.

#' @export
setMethod("dbHasCompleted", "KazamResult", function(res, ...) {

})

With these four methods in place, you can now use the default dbGetQuery() to send a query to the database, retrieve results if available and then clean up. Spend some time now making sure this works with an existing database, or relax and let the DBItest package do the work for you.

SQL methods

You’re now on the home stretch, and can make your wrapper substantially more useful by implementing methods that wrap around variations in SQL across databases:

  • dbQuoteString() and dbQuoteIdentifer() are used to safely quote strings and identifiers to avoid SQL injection attacks. Note that the former must be vectorized, but not the latter.

  • dbWriteTable() creates a database table given an R dataframe. I’d recommend using the functions prefixed with sql in this package to generate the SQL. These functions are still a work in progress so please let me know if you have problems.

  • dbReadTable(): a simple wrapper around SELECT * FROM table. Use dbQuoteIdentifer() to safely quote the table name and prevent mismatches between the names allowed by R and the database.

  • dbListTables() and dbExistsTable() let you determine what tables are available. If not provided by your database’s API, you may need to generate sql that inspects the system tables.

  • dbListFields() shows which fields are available in a given table.

  • dbRemoveTable() wraps around DROP TABLE. Start with SQL::sqlTableDrop().

  • dbBegin(), dbCommit() and dbRollback(): implement these three functions to provide basic transaction support. This functionality is currently not tested in the DBItest package.

Metadata methods

There are a lot of extra metadata methods for result sets (and one for the connection) that you might want to implement. They are described in the following.

  • dbIsValid() returns if a connection or a result set is open (TRUE) or closed (FALSE). All further methods in this section are valid for result sets only.

  • dbGetStatement() returns the issued query as a character value.

  • dbColumnInfo() lists the names and types of the result set’s columns.

  • dbGetRowCount() and dbGetRowsAffected() returns the number of rows returned or altered in a SELECT or INSERT/UPDATE query, respectively.

  • dbBind() allows using parametrised queries. Take a look at sqlInterpolate() and sqlParseVariables() if your SQL engine doesn’t offer native parametrised queries.

Full DBI compliance

By now, your package should implement all methods defined in the DBI specification. If you want to walk the extra mile, offer a read-only mode that allows your users to be sure that their valuable data doesn’t get destroyed inadvertently.

DBI/inst/doc/DBI.R0000644000176200001440000000357014627152534013131 0ustar liggesusers## ----setup, include=FALSE----------------------------------------------------- knitr::opts_chunk$set( echo = TRUE, error = Sys.getenv("IN_PKGDOWN") != "true" || (getRversion() < "3.5") ) ## ----------------------------------------------------------------------------- library(DBI) con <- dbConnect( RMariaDB::MariaDB(), host = "db.relational-data.org", port = 3306, username = "guest", password = "relational", dbname = "sakila" ) dbListTables(con) dbDisconnect(con) ## ----eval = FALSE------------------------------------------------------------- # con <- dbConnect( # RMariaDB::MariaDB(), # host = "db.relational-data.org", # port = 3306, # username = "guest", # password = keyring::key_get("db.relational-data.org", "guest"), # dbname = "sakila" # ) ## ----------------------------------------------------------------------------- con <- dbConnect(RMariaDB::MariaDB(), username = "guest", password = "relational", host = "db.relational-data.org", port = 3306, dbname = "sakila") dbListFields(con, "film") ## ----------------------------------------------------------------------------- df <- dbReadTable(con, "film") head(df, 3) ## ----------------------------------------------------------------------------- df <- dbGetQuery(con, "SELECT film_id, title, description FROM film WHERE release_year = 2006") head(df, 3) ## ----------------------------------------------------------------------------- df <- dbGetQuery(con, "SELECT film_id, title, description FROM film WHERE release_year = 2006 AND rating = 'G'") head(df, 3) ## ----message=FALSE------------------------------------------------------------ library(dplyr) lazy_df <- tbl(con, "film") %>% filter(release_year == 2006 & rating == "G") %>% select(film_id, title, description) head(lazy_df, 3) ## ----------------------------------------------------------------------------- dbDisconnect(con) DBI/inst/doc/DBI-1.Rmd0000644000176200001440000006004014602466070013577 0ustar liggesusers--- title: "A Common Database Interface (DBI)" author: "R-Databases Special Interest Group" date: "16 June 2003" output: rmarkdown::html_vignette bibliography: biblio.bib vignette: > %\VignetteIndexEntry{A Common Database Interface (DBI)} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- This document describes a common interface between the S language (in its R and S-Plus implementations) and database management systems (DBMS). The interface defines a small set of classes and methods similar in spirit to Perl’s DBI, Java’s JDBC, Python’s DB-API, and Microsoft’s ODBC. # Version {#sec:version} This document describes version 0.1-6 of the database interface API (application programming interface). # Introduction {#sec:intro} The database interface (DBI) separates the connectivity to the DBMS into a “front-end” and a “back-end”. Applications use only the exposed “front-end” API. The facilities that communicate with specific DBMS (Oracle, PostgreSQL, etc.) are provided by “device drivers” that get invoked automatically by the S language evaluator. The following example illustrates some of the DBI capabilities: ```R ## Choose the proper DBMS driver and connect to the server drv <- dbDriver("ODBC") con <- dbConnect(drv, "dsn", "usr", "pwd") ## The interface can work at a higher level importing tables ## as data.frames and exporting data.frames as DBMS tables. dbListTables(con) dbListFields(con, "quakes") if(dbExistsTable(con, "new_results")) dbRemoveTable(con, "new_results") dbWriteTable(con, "new_results", new.output) ## The interface allows lower-level interface to the DBMS res <- dbSendQuery(con, paste( "SELECT g.id, g.mirror, g.diam, e.voltage", "FROM geom_table as g, elec_measures as e", "WHERE g.id = e.id and g.mirrortype = 'inside'", "ORDER BY g.diam")) out <- NULL while(!dbHasCompleted(res)){ chunk <- fetch(res, n = 10000) out <- c(out, doit(chunk)) } ## Free up resources dbClearResult(res) dbDisconnect(con) dbUnloadDriver(drv) ``` (only the first 2 expressions are DBMS-specific – all others are independent of the database engine itself). Individual DBI drivers need not implement all the features we list below (we indicate those that are optional). Furthermore, drivers may extend the core DBI facilities, but we suggest to have these extensions clearly indicated and documented. The following are the elements of the DBI: 1. A set of classes and methods (Section [sec:DBIClasses]) that defines what operations are possible and how they are defined, e.g.: - connect/disconnect to the DBMS - create and execute statements in the DBMS - extract results/output from statements - error/exception handling - information (meta-data) from database objects - transaction management (optional) Some things are left explicitly unspecified, e.g., authentication and even the query language, although it is hard to avoid references to SQL and relational database management systems (RDBMS). 2. Drivers Drivers are collection of functions that implement the functionality defined above in the context of specific DBMS, e.g., mSQL, Informix. 3. Data type mappings (Section [sec:data-mappings].) Mappings and conversions between DBMS data types and R/S objects. All drivers should implement the “basic” primitives (see below), but may chose to add user-defined conversion function to handle more generic objects (e.g., factors, ordered factors, time series, arrays, images). 4. Utilities (Section [sec:utilities].) These facilities help with details such as mapping of identifiers between S and DBMS (e.g., `_` is illegal in R/S names, and `.` is used for constructing compound SQL identifiers), etc. # DBI Classes and Methods {#sec:DBIClasses} The following are the main DBI classes. They need to be extended by individual database back-ends (Sybase, Oracle, etc.) Individual drivers need to provide methods for the generic functions listed here (those methods that are optional are so indicated). *Note: Although R releases prior to 1.4 do not have a formal concept of classes, we will use the syntax of the S Version 4 classes and methods (available in R releases 1.4 and later as library `methods`) to convey precisely the DBI class hierarchy, its methods, and intended behavior.* The DBI classes are `DBIObject`, `DBIDriver`, `DBIConnection` and `DBIResult`. All these are *virtual* classes. Drivers define new classes that extend these, e.g., `PgSQLDriver`, `PgSQLConnection`, and so on. ![Class hierarchy for the DBI. The top two layers are comprised of virtual classes and each lower layer represents a set of driver-specific implementation classes that provide the functionality defined by the virtual classes above.](hierarchy.png) `DBIObject`: : Virtual class[^1] that groups all other DBI classes. `DBIDriver`: : Virtual class that groups all DBMS drivers. Each DBMS driver extends this class. Typically generator functions instantiate the actual driver objects, e.g., `PgSQL`, `HDF5`, `BerkeleyDB`. `DBIConnection`: : Virtual class that encapsulates connections to DBMS. `DBIResult`: : Virtual class that describes the result of a DBMS query or statement. [Q: Should we distinguish between a simple result of DBMS statements e.g., as `delete` from DBMS queries (i.e., those that generate data).] The methods `format`, `print`, `show`, `dbGetInfo`, and `summary` are defined (and *implemented* in the `DBI` package) for the `DBIObject` base class, thus available to all implementations; individual drivers, however, are free to override them as they see fit. `format(x, ...)`: : produces a concise character representation (label) for the `DBIObject` `x`. `print(x, ...)`/`show(x)`: : prints a one-line identification of the object `x`. `summary(object, ...)`: : produces a concise description of the object. The default method for `DBIObject` simply invokes `dbGetInfo(dbObj)` and prints the name-value pairs one per line. Individual implementations may tailor this appropriately. `dbGetInfo(dbObj, ...)`: : extracts information (meta-data) relevant for the `DBIObject` `dbObj`. It may return a list of key/value pairs, individual meta-data if supplied in the call, or `NULL` if the requested meta-data is not available. *Hint:* Driver implementations may choose to allow an argument `what` to specify individual meta-data, e.g., `dbGetInfo(drv, what = max.connections)`. In the next few sub-sections we describe in detail each of these classes and their methods. ## Class `DBIObject` {#sec:DBIObject} This class simply groups all DBI classes, and thus all extend it. ## Class `DBIDriver` {#sec:DBIDriver} This class identifies the database management system. It needs to be extended by individual back-ends (Oracle, PostgreSQL, etc.) The DBI provides the generator `dbDriver(driverName)` which simply invokes the function `driverName`, which in turn instantiates the corresponding driver object. The `DBIDriver` class defines the following methods: `driverName`: : [meth:driverName] initializes the driver code. The name `driverName` refers to the actual generator function for the DBMS, e.g., `RPgSQL`, `RODBC`, `HDF5`. The driver instance object is used with `dbConnect` (see page ) for opening one or possibly more connections to one or more DBMS. `dbListConnections(drv, ...)`: : list of current connections being handled by the `drv` driver. May be `NULL` if there are no open connections. Drivers that do not support multiple connections may return the one open connection. `dbGetInfo(dbObj, ...)`: : returns a list of name-value pairs of information about the driver. *Hint:* Useful entries could include `name`: : the driver name (e.g., `RODBC`, `RPgSQL`); `driver.version`: : version of the driver; `DBI.version`: : the version of the DBI that the driver implements, e.g., `0.1-2`; `client.version`: : of the client DBMS libraries (e.g., version of the `libpq` library in the case of `RPgSQL`); `max.connections`: : maximum number of simultaneous connections; plus any other relevant information about the implementation, for instance, how the driver handles upper/lower case in identifiers. `dbUnloadDriver(driverName)` (optional): : frees all resources (local and remote) used by the driver. Returns a logical to indicate if it succeeded or not. ## Class `DBIConnection` {#sec:DBIConnection} This virtual class encapsulates the connection to a DBMS, and it provides access to dynamic queries, result sets, DBMS session management (transactions), etc. *Note:* Individual drivers are free to implement single or multiple simultaneous connections. The methods defined by the `DBIConnection` class include: `dbConnect(drv, ...)`: : [meth:dbConnect] creates and opens a connection to the database implemented by the driver `drv` (see Section [sec:DBIDriver]). Each driver will define what other arguments are required, e.g., `dbname` or `dsn` for the database name, `user`, and `password`. It returns an object that extends `DBIConnection` in a driver-specific manner (e.g., the MySQL implementation could create an object of class `MySQLConnection` that extends `DBIConnection`). `dbDisconnect(conn, ...)`: : closes the connection, discards all pending work, and frees resources (e.g., memory, sockets). Returns a logical indicating whether it succeeded or not. `dbSendQuery(conn, statement, ...)`: : submits one statement to the DBMS. It returns a `DBIResult` object. This object is needed for fetching data in case the statement generates output (see `fetch` on page ), and it may be used for querying the state of the operation; see `dbGetInfo` and other meta-data methods on page . `dbGetQuery(conn, statement, ...)`: : submit, execute, and extract output in one operation. The resulting object may be a `data.frame` if the `statement` generates output. Otherwise the return value should be a logical indicating whether the query succeeded or not. `dbGetException(conn, ...)`: : returns a list with elements `errNum` and `errMsg` with the status of the last DBMS statement sent on a given connection (this information may also be provided by the `dbGetInfo` meta-data function on the `conn` object. *Hint:* The ANSI SQL-92 defines both a status code and an status message that could be return as members of the list. `dbGetInfo(dbObj, ...)`: : returns a list of name-value pairs describing the state of the connection; it may return one or more meta-data, the actual driver method allows to specify individual pieces of meta-data (e.g., maximum number of open results/cursors). *Hint:* Useful entries could include `dbname`: : the name of the database in use; `db.version`: : the DBMS server version (e.g., “Oracle 8.1.7 on Solaris”; `host`: : host where the database server resides; `user`: : user name; `password`: : password (is this safe?); plus any other arguments related to the connection (e.g., thread id, socket or TCP connection type). `dbListResults(conn, ...)`: : list of `DBIResult` objects currently active on the connection `conn`. May be `NULL` if no result set is active on `conn`. Drivers that implement only one result set per connection could return that one object (no need to wrap it in a list). *Note: The following are convenience methods that simplify the import/export of (mainly) data.frames. The first five methods implement the core methods needed to `attach` remote DBMS to the S search path. (For details, see @data-management:1991 [@database-classes:1999].)* *Hint:* For relational DBMS these methods may be easily implemented using the core DBI methods `dbConnect`, `dbSendQuery`, and `fetch`, due to SQL reflectance (i.e., one easily gets this meta-data by querying the appropriate tables on the RDBMS). `dbListTables(conn, ...)`: : returns a character vector (possibly of zero-length) of object (table) names available on the `conn` connection. `dbReadTable(conn, name, ...)`: : imports the data stored remotely in the table `name` on connection `conn`. Use the field `row.names` as the `row.names` attribute of the output data.frame. Returns a `data.frame`. [Q: should we spell out how row.names should be created? E.g., use a field (with unique values) as row.names? Also, should `dbReadTable` reproduce a data.frame exported with `dbWriteTable`?] `dbWriteTable(conn, name, value, ...)`: : write the object `value` (perhaps after coercing it to data.frame) into the remote object `name` in connection `conn`. Returns a logical indicating whether the operation succeeded or not. `dbExistsTable(conn, name, ...)`: : does remote object `name` exist on `conn`? Returns a logical. `dbRemoveTable(conn, name, ...)`: : removes remote object `name` on connection `conn`. Returns a logical indicating whether the operation succeeded or not. `dbListFields(conn, name, ...)`: : returns a character vector listing the field names of the remote table `name` on connection `conn` (see `dbColumnInfo()` for extracting data type on a table). *Note: The following methods deal with transactions and stored procedures. All these functions are optional.* `dbCommit(conn, ...)`(optional): : commits pending transaction on the connection and returns `TRUE` or `FALSE` depending on whether the operation succeeded or not. `dbRollback(conn, ...)`(optional): : undoes current transaction on the connection and returns `TRUE` or `FALSE` depending on whether the operation succeeded or not. `dbCallProc(conn, storedProc, ...)`(optional): : invokes a stored procedure in the DBMS and returns a `DBIResult` object. [Stored procedures are *not* part of the ANSI SQL-92 standard and vary substantially from one RDBMS to another.] **Deprecated since 2014:** The recommended way of calling a stored procedure is now - `dbGetQuery` if a result set is returned and - `dbExecute` for data manipulation and other cases that do not return a result set. ## Class `DBIResult` {#sec:DBIResult} This virtual class describes the result and state of execution of a DBMS statement (any statement, query or non-query). The result set `res` keeps track of whether the statement produces output for R/S, how many rows were affected by the operation, how many rows have been fetched (if statement is a query), whether there are more rows to fetch, etc. *Note: Individual drivers are free to allow single or multiple active results per connection.* [Q: Should we distinguish between results that return no data from those that return data?] The class `DBIResult` defines the following methods: `fetch(res, n, ...)`: : [meth:fetch] fetches the next `n` elements (rows) from the result set `res` and return them as a data.frame. A value of `n=-1` is interpreted as “return all elements/rows”. `dbClearResult(res, ...)`: : flushes any pending data and frees all resources (local and remote) used by the object `res` on both sides of the connection. Returns a logical indicating success or not. `dbGetInfo(dbObj, ...)`: : returns a name-value list with the state of the result set. *Hint:* Useful entries could include `statement`: : a character string representation of the statement being executed; `rows.affected`: : number of affected records (changed, deleted, inserted, or extracted); `row.count`: : number of rows fetched so far; `has.completed`: : has the statement (query) finished? `is.select`: : a logical describing whether or not the statement generates output; plus any other relevant driver-specific meta-data. `dbColumnInfo(res, ...)`: : produces a data.frame that describes the output of a query. The data.frame should have as many rows as there are output fields in the result set, and each column in the data.frame should describe an aspect of the result set field (field name, type, etc.) *Hint:* The data.frame columns could include `field.name`: : DBMS field label; `field.type`: : DBMS field type (implementation-specific); `data.type`: : corresponding R/S data type, e.g., `integer`; `precision`/`scale`: : (as in ODBC terminology), display width and number of decimal digits, respectively; `nullable`: : whether the corresponding field may contain (DBMS) `NULL` values; plus other driver-specific information. `dbSetDataMappings(flds, ...)`(optional): : defines a conversion between internal DBMS data types and R/S classes. We expect the default mappings (see Section [sec:data-mappings]) to be by far the most common ones, but users that need more control may specify a class generator for individual fields in the result set. [This topic needs further discussion.] *Note: The following are convenience methods that extract information from the result object (they may be implemented by invoking `dbGetInfo` with appropriate arguments).* `dbGetStatement(res, ...)`(optional): : returns the DBMS statement (as a character string) associated with the result `res`. `dbGetRowsAffected(res, ...)`(optional): : returns the number of rows affected by the executed statement (number of records deleted, modified, extracted, etc.) `dbHasCompleted(res, ...)`(optional): : returns a logical that indicates whether the operation has been completed (e.g., are there more records to be fetched?). `dbGetRowCount(res, ...)`(optional): : returns the number of rows fetched so far. # Data Type Mappings {#sec:data-mappings} The data types supported by databases are different than the data types in R and S, but the mapping between the “primitive” types is straightforward: Any of the many fixed and varying length character types are mapped to R/S `character`. Fixed-precision (non-IEEE) numbers are mapped into either doubles (`numeric`) or long (`integer`). Notice that many DBMS do not follow the so-called IEEE arithmetic, so there are potential problems with under/overflows and loss of precision, but given the R/S primitive types we cannot do too much but identify these situations and warn the application (how?). By default dates and date-time objects are mapped to character using the appropriate `TO_CHAR` function in the DBMS (which should take care of any locale information). Some RDBMS support the type `CURRENCY` or `MONEY` which should be mapped to `numeric` (again with potential round off errors). Large objects (character, binary, file, etc.) also need to be mapped. User-defined functions may be specified to do the actual conversion (as has been done in other inter-systems packages [^2]). Specifying user-defined conversion functions still needs to be defined. # Utilities {#sec:utilities} The core DBI implementation should make available to all drivers some common basic utilities. For instance: `dbGetDBIVersion`: : returns the version of the currently attached DBI as a string. `dbDataType(dbObj, obj, ...)`: : returns a string with the (approximately) appropriate data type for the R/S object `obj`. The DBI can implement this following the ANSI-92 standard, but individual drivers may want/need to extend it to make use of DBMS-specific types. `make.db.names(dbObj, snames, ...)`: : maps R/S names (identifiers) to SQL identifiers replacing illegal characters (as `.`) by the legal SQL `_`. `SQLKeywords(dbObj, ...)`: : returns a character vector of SQL keywords (reserved words). The default method returns the list of `.SQL92Keywords`, but drivers should update this vector with the DBMS-specific additional reserved words. `isSQLKeyword(dbObj, name, ...)`: : for each element in the character vector `name` determine whether or not it is an SQL keyword, as reported by the generic function `SQLKeywords`. Returns a logical vector parallel to the input object `name`. # Open Issues and Limitations {#sec:open-issues} There are a number of issues and limitations that the current DBI conscientiously does not address on the interest of simplicity. We do list here the most important ones. Non-SQL: : Is it realistic to attempt to encompass non-relational databases, like HDF5, Berkeley DB, etc.? Security: : allowing users to specify their passwords on R/S scripts may be unacceptable for some applications. We need to consider alternatives where users could store authentication on files (perhaps similar to ODBC’s `odbc.ini`) with more stringent permissions. Exceptions: : the exception mechanism is a bit too simple, and it does not provide for information when problems stem from the DBMS interface itself. For instance, under/overflow or loss of precision as we move numeric data from DBMS to the more limited primitives in R/S. Asynchronous communication: : most DBMS support both synchronous and asynchronous communications, allowing applications to submit a query and proceed while the database server process the query. The application is then notified (or it may need to poll the server) when the query has completed. For large computations, this could be very useful, but the DBI would need to specify how to interrupt the server (if necessary) plus other details. Also, some DBMS require applications to use threads to implement asynchronous communication, something that neither R nor S-Plus currently addresses. SQL scripts: : the DBI only defines how to execute one SQL statement at a time, forcing users to split SQL scripts into individual statements. We need a mechanism by which users can submit SQL scripts that could possibly generate multiple result sets; in this case we may need to introduce new methods to loop over multiple results (similar to Python’s `nextResultSet`). BLOBS/CLOBS: : large objects (both character and binary) present some challenges both to R and S-Plus. It is becoming more common to store images, sounds, and other data types as binary objects in DBMS, some of which can be in principle quite large. The SQL-92 ANSI standard allows up to 2 gigabytes for some of these objects. We need to carefully plan how to deal with binary objects. Transactions: : transaction management is not fully described. Additional methods: : Do we need any additional methods? (e.g., `dbListDatabases(conn)`, `dbListTableIndices(conn, name)`, how do we list all available drivers?) Bind variables: : the interface is heavily biased towards queries, as opposed to general purpose database development. In particular we made no attempt to define “bind variables”; this is a mechanism by which the contents of R/S objects are implicitly moved to the database during SQL execution. For instance, the following embedded SQL statement /* SQL */ SELECT * from emp_table where emp_id = :sampleEmployee would take the vector `sampleEmployee` and iterate over each of its elements to get the result. Perhaps the DBI could at some point in the future implement this feature. # Resources {#sec:resources} The idea of a common interface to databases has been successfully implemented in various environments, for instance: Java’s Database Connectivity (JDBC) ([www.javasoft.com](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/)). In C through the Open Database Connectivity (ODBC) ([www.unixodbc.org](https://www.unixodbc.org/)). Python’s Database Application Programming Interface ([www.python.org](https://wiki.python.org/moin/DatabaseProgramming)). Perl’s Database Interface ([dbi.perl.org](https://dbi.perl.org)). [^1]: A virtual class allows us to group classes that share some common characteristics, even if their implementations are radically different. [^2]: Duncan Temple Lang has volunteered to port the data conversion code found in R-Java, R-Perl, and R-Python packages to the DBI DBI/inst/doc/DBI-arrow.html0000644000176200001440000006164614627152531015031 0ustar liggesusersUsing DBI with Arrow

Using DBI with Arrow

Kirill Müller

25/12/2023

Who this tutorial is for

This tutorial is for you if you want to leverage Apache Arrow for accessing and manipulating data on databases. See vignette("DBI", package = "DBI") and vignette("DBI-advanced", package = "DBI") for tutorials on accessing data using R’s data frames instead of Arrow’s structures.

Rationale

Apache Arrow is

a cross-language development platform for in-memory analytics,

suitable for large and huge data, with support for out-of-memory operation. Arrow is also a data exchange format, the data types covered by Arrow align well with the data types supported by SQL databases.

DBI 1.2.0 introduced support for Arrow as a format for exchanging data between R and databases. The aim is to:

  • accelerate data retrieval and loading, by using fewer costly data conversions;
  • better support reading and summarizing data from a database that is larger than memory;
  • provide better type fidelity with workflows centered around Arrow.

This allows existing code to be used with Arrow, and it allows new code to be written that is more efficient and more flexible than code that uses R’s data frames.

The interface is built around the {nanoarrow} R package, with nanoarrow::as_nanoarrow_array and nanoarrow::as_nanoarrow_array_stream as fundamental data structures.

New classes and generics

DBI 1.2.0 introduces new classes and generics for working with Arrow data:

  • dbReadTableArrow()
  • dbWriteTableArrow()
  • dbCreateTableArrow()
  • dbAppendTableArrow()
  • dbGetQueryArrow()
  • dbSendQueryArrow()
  • dbBindArrow()
  • dbFetchArrow()
  • dbFetchArrowChunk()
  • DBIResultArrow-class
  • DBIResultArrowDefault-class

Compatibility is important for DBI, and implementing new generics and classes greatly reduces the risk of breaking existing code. The DBI package comes with a fully functional fallback implementation for all existing DBI backends. The fallback is not improving performance, but it allows existing code to be used with Arrow before switching to a backend with native Arrow support. Backends with native support, like the adbi package, implement the new generics and classes for direct support and improved performance.

In the remainder of this tutorial, we will demonstrate the new generics and classes using the RSQLite package. SQLite is an in-memory database, this code does not need a database server to be installed and running.

Prepare

We start by setting up a database connection and creating a table with some data, using the original dbWriteTable() method.

library(DBI)

con <- dbConnect(RSQLite::SQLite())

data <- data.frame(
  a = 1:3,
  b = 4.5,
  c = "five"
)

dbWriteTable(con, "tbl", data)

Read all rows from a table

The dbReadTableArrow() method reads all rows from a table into an Arrow stream, similarly to dbReadTable(). Arrow objects implement the as.data.frame() method, so we can convert the stream to a data frame.

stream <- dbReadTableArrow(con, "tbl")
stream
## <nanoarrow_array_stream struct<a: int32, b: double, c: string>>
##  $ get_schema:function ()  
##  $ get_next  :function (schema = x$get_schema(), validate = TRUE)  
##  $ release   :function ()
as.data.frame(stream)
##   a   b    c
## 1 1 4.5 five
## 2 2 4.5 five
## 3 3 4.5 five

Run queries

The dbGetQueryArrow() method runs a query and returns the result as an Arrow stream. This stream can be turned into an arrow::RecordBatchReader object and processed further, without bringing it into R.

stream <- dbGetQueryArrow(con, "SELECT COUNT(*) AS n FROM tbl WHERE a < 3")
stream
## <nanoarrow_array_stream struct<n: int32>>
##  $ get_schema:function ()  
##  $ get_next  :function (schema = x$get_schema(), validate = TRUE)  
##  $ release   :function ()
path <- tempfile(fileext = ".parquet")
arrow::write_parquet(arrow::as_record_batch_reader(stream), path)
arrow::read_parquet(path)
##   n
## 1 2

Prepared queries

The dbGetQueryArrow() method supports prepared queries, using the params argument which accepts a data frame or a list.

params <- data.frame(a = 3L)
stream <- dbGetQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a", params = params)
as.data.frame(stream)
##   batch a   b    c
## 1     3 1 4.5 five
## 2     3 2 4.5 five
params <- data.frame(a = c(2L, 4L))
# Equivalent to dbBind()
stream <- dbGetQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a", params = params)
as.data.frame(stream)
##   batch a   b    c
## 1     2 1 4.5 five
## 2     4 1 4.5 five
## 3     4 2 4.5 five
## 4     4 3 4.5 five

Manual flow

For the manual flow, use dbSendQueryArrow() to send a query to the database, and dbFetchArrow() to fetch the result. This also allows using the new dbBindArrow() method to bind data in Arrow format to a prepared query. Result objects must be cleared with dbClearResult().

rs <- dbSendQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a")

in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 1L))
dbBindArrow(rs, in_arrow)
as.data.frame(dbFetchArrow(rs))
## [1] batch a     b     c    
## <0 rows> (or 0-length row.names)
in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 2L))
dbBindArrow(rs, in_arrow)
as.data.frame(dbFetchArrow(rs))
##   batch a   b    c
## 1     2 1 4.5 five
in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 3L))
dbBindArrow(rs, in_arrow)
as.data.frame(dbFetchArrow(rs))
##   batch a   b    c
## 1     3 1 4.5 five
## 2     3 2 4.5 five
in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 1:4L))
dbBindArrow(rs, in_arrow)
as.data.frame(dbFetchArrow(rs))
##   batch a   b    c
## 1     2 1 4.5 five
## 2     3 1 4.5 five
## 3     3 2 4.5 five
## 4     4 1 4.5 five
## 5     4 2 4.5 five
## 6     4 3 4.5 five
dbClearResult(rs)

Writing data

Streams returned by dbGetQueryArrow() and dbReadTableArrow() can be written to a table using dbWriteTableArrow().

stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a < 3")
dbWriteTableArrow(con, "tbl_new", stream)
dbReadTable(con, "tbl_new")
##   a   b    c
## 1 1 4.5 five
## 2 2 4.5 five

Appending data

For more control over the writing process, use dbCreateTableArrow() and dbAppendTableArrow().

stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a < 3")
dbCreateTableArrow(con, "tbl_split", stream)
dbAppendTableArrow(con, "tbl_split", stream)
## [1] 2
stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a >= 3")
dbAppendTableArrow(con, "tbl_split", stream)
## [1] 1
dbReadTable(con, "tbl_split")
##   a   b    c
## 1 1 4.5 five
## 2 2 4.5 five
## 3 3 4.5 five

Conclusion

Do not forget to disconnect from the database when done.

dbDisconnect(con)

That concludes the major features of DBI’s new Arrow interface. For more details on the library functions covered in this tutorial see the DBI specification at vignette("spec", package = "DBI"). See the adbi package for a backend with native Arrow support, and nanoarrow and arrow for packages to work with the Arrow format.

DBI/inst/doc/spec.html0000644000176200001440000057756614627152535014256 0ustar liggesusersDBI specification

DBI specification

Kirill Müller

Abstract

The DBI package defines the generic DataBase Interface for R. The connection to individual DBMS is provided by other packages that import DBI (so-called DBI backends). This document formalizes the behavior expected by the methods declared in DBI and implemented by the individual backends. To ensure maximum portability and exchangeability, and to reduce the effort for implementing a new DBI backend, the DBItest package defines a comprehensive set of test cases that test conformance to the DBI specification. This document is derived from comments in the test definitions of the DBItest package. Any extensions or updates to the tests will be reflected in this document.

DBI: R Database Interface

DBI defines an interface for communication between R and relational database management systems. All classes in this package are virtual and need to be extended by the various R/DBMS implementations (so-called DBI backends).

Definition

A DBI backend is an R package which imports the DBI and methods packages. For better or worse, the names of many existing backends start with ‘R’, e.g., RSQLite, RMySQL, RSQLServer; it is up to the backend author to adopt this convention or not.

DBI classes and methods

A backend defines three classes, which are subclasses of DBIDriver, DBIConnection, and DBIResult. The backend provides implementation for all methods of these base classes that are defined but not implemented by DBI. All methods defined in DBI are reexported (so that the package can be used without having to attach DBI), and have an ellipsis ... in their formals for extensibility.

Construction of the DBIDriver object

The backend must support creation of an instance of its DBIDriver subclass with a constructor function. By default, its name is the package name without the leading ‘R’ (if it exists), e.g., SQLite for the RSQLite package. However, backend authors may choose a different name. The constructor must be exported, and it must be a function that is callable without arguments. DBI recommends to define a constructor with an empty argument list.

Examples

RSQLite::SQLite()

Determine the SQL data type of an object

This section describes the behavior of the following method:

dbDataType(dbObj, obj, ...)

Description

Returns an SQL string that describes the SQL data type to be used for an object. The default implementation of this generic determines the SQL type of an R object according to the SQL 92 specification, which may serve as a starting point for driver implementations. DBI also provides an implementation for data.frame which will return a character vector giving the type for each column in the dataframe.

Arguments

dbObj A object inheriting from DBIDriver or DBIConnection
obj An R object whose SQL type we want to determine.
... Other arguments passed on to methods.

Details

The data types supported by databases are different than the data types in R, but the mapping between the primitive types is straightforward:

  • Any of the many fixed and varying length character types are mapped to character vectors

  • Fixed-precision (non-IEEE) numbers are mapped into either numeric or integer vectors.

Notice that many DBMS do not follow IEEE arithmetic, so there are potential problems with under/overflows and loss of precision.

Value

dbDataType() returns the SQL type that corresponds to the obj argument as a non-empty character string. For data frames, a character vector with one element per column is returned.

Failure modes

An error is raised for invalid values for the obj argument such as a NULL value.

Specification

The backend can override the dbDataType() generic for its driver class.

This generic expects an arbitrary object as second argument. To query the values returned by the default implementation, run example(dbDataType, package = "DBI"). If the backend needs to override this generic, it must accept all basic R data types as its second argument, namely logical, integer, numeric, character, dates (see Dates), date-time (see DateTimeClasses), and difftime. If the database supports blobs, this method also must accept lists of raw vectors, and blob::blob objects. As-is objects (i.e., wrapped by I()) must be supported and return the same results as their unwrapped counterparts. The SQL data type for factor and ordered is the same as for character. The behavior for other object types is not specified.

All data types returned by dbDataType() are usable in an SQL statement of the form "CREATE TABLE test (a ...)".

Examples

dbDataType(ANSI(), 1:5)
dbDataType(ANSI(), 1)
dbDataType(ANSI(), TRUE)
dbDataType(ANSI(), Sys.Date())
dbDataType(ANSI(), Sys.time())
dbDataType(ANSI(), Sys.time() - as.POSIXct(Sys.Date()))
dbDataType(ANSI(), c("x", "abc"))
dbDataType(ANSI(), list(raw(10), raw(20)))
dbDataType(ANSI(), I(3))

dbDataType(ANSI(), iris)


con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbDataType(con, 1:5)
dbDataType(con, 1)
dbDataType(con, TRUE)
dbDataType(con, Sys.Date())
dbDataType(con, Sys.time())
dbDataType(con, Sys.time() - as.POSIXct(Sys.Date()))
dbDataType(con, c("x", "abc"))
dbDataType(con, list(raw(10), raw(20)))
dbDataType(con, I(3))

dbDataType(con, iris)

dbDisconnect(con)

Create a connection to a DBMS

This section describes the behavior of the following method:

dbConnect(drv, ...)

Description

Connect to a DBMS going through the appropriate authentication procedure. Some implementations may allow you to have multiple connections open, so you may invoke this function repeatedly assigning its output to different objects. The authentication mechanism is left unspecified, so check the documentation of individual drivers for details. Use dbCanConnect() to check if a connection can be established.

Arguments

drv an object that inherits from DBIDriver, or an existing DBIConnection object (in order to clone an existing connection).
... authentication arguments needed by the DBMS instance; these typically include user, password, host, port, dbname, etc. For details see the appropriate DBIDriver.

Value

dbConnect() returns an S4 object that inherits from DBIConnection. This object is used to communicate with the database engine.

A format() method is defined for the connection object. It returns a string that consists of a single line of text.

Specification

DBI recommends using the following argument names for authentication parameters, with NULL default:

  • user for the user name (default: current user)

  • password for the password

  • host for the host name (default: local connection)

  • port for the port number (default: local connection)

  • dbname for the name of the database on the host, or the database file name

The defaults should provide reasonable behavior, in particular a local connection for host = NULL. For some DBMS (e.g., PostgreSQL), this is different to a TCP/IP connection to localhost.

In addition, DBI supports the bigint argument that governs how 64-bit integer data is returned. The following values are supported:

  • "integer": always return as integer, silently overflow

  • "numeric": always return as numeric, silently round

  • "character": always return the decimal representation as character

  • "integer64": return as a data type that can be coerced using as.integer() (with warning on overflow), as.numeric() and as.character()

Examples

# SQLite only needs a path to the database. (Here, ":memory:" is a special
# path that creates an in-memory database.) Other database drivers
# will require more details (like user, password, host, port, etc.)
con <- dbConnect(RSQLite::SQLite(), ":memory:")
con

dbListTables(con)

dbDisconnect(con)

# Bad, for subtle reasons:
# This code fails when RSQLite isn't loaded yet,
# because dbConnect() doesn't know yet about RSQLite.
dbListTables(con <- dbConnect(RSQLite::SQLite(), ":memory:"))

Disconnect (close) a connection

This section describes the behavior of the following method:

dbDisconnect(conn, ...)

Description

This closes the connection, discards all pending work, and frees resources (e.g., memory, sockets).

Arguments

conn A DBIConnection object, as returned by dbConnect().
... Other parameters passed on to methods.

Value

dbDisconnect() returns TRUE, invisibly.

Failure modes

A warning is issued on garbage collection when a connection has been released without calling dbDisconnect(), but this cannot be tested automatically. At least one warning is issued immediately when calling dbDisconnect() on an already disconnected or invalid connection.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")
dbDisconnect(con)

Execute a query on a given database connection

This section describes the behavior of the following method:

dbSendQuery(conn, statement, ...)

Description

The dbSendQuery() method only submits and synchronously executes the SQL query to the database engine. It does not extract any records — for that you need to use the dbFetch() method, and then you must call dbClearResult() when you finish fetching the records you need. For interactive use, you should almost always prefer dbGetQuery(). Use dbSendQueryArrow() or dbGetQueryArrow() instead to retrieve the results as an Arrow object.

Arguments

conn A DBIConnection object, as returned by dbConnect().
statement a character string containing SQL.
... Other parameters passed on to methods.

Additional arguments

The following arguments are not part of the dbSendQuery() generic (to improve compatibility across backends) but are part of the DBI specification:

  • params (default: NULL)

  • immediate (default: NULL)

They must be provided as named arguments. See the “Specification” sections for details on their usage.

Specification

No warnings occur under normal conditions. When done, the DBIResult object must be cleared with a call to dbClearResult(). Failure to clear the result set leads to a warning when the connection is closed.

If the backend supports only one open result set per connection, issuing a second query invalidates an already open result set and raises a warning. The newly opened result set is valid and must be cleared with dbClearResult().

The param argument allows passing query parameters, see dbBind() for details.

Specification for the immediate argument

The immediate argument supports distinguishing between “direct” and “prepared” APIs offered by many database drivers. Passing immediate = TRUE leads to immediate execution of the query or statement, via the “direct” API (if supported by the driver). The default NULL means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct immediate argument. Examples for possible behaviors:

  1. DBI backend defaults to immediate = TRUE internally

    1. A query without parameters is passed: query is executed

    2. A query with parameters is passed:

      1. params not given: rejected immediately by the database because of a syntax error in the query, the backend tries immediate = FALSE (and gives a message)

      2. params given: query is executed using immediate = FALSE

  2. DBI backend defaults to immediate = FALSE internally

    1. A query without parameters is passed:

      1. simple query: query is executed

      2. “special” query (such as setting a config options): fails, the backend tries immediate = TRUE (and gives a message)

    2. A query with parameters is passed:

      1. params not given: waiting for parameters via dbBind()

      2. params given: query is executed

Details

This method is for SELECT queries only. Some backends may support data manipulation queries through this method for compatibility reasons. However, callers are strongly encouraged to use dbSendStatement() for data manipulation statements.

The query is submitted to the database server and the DBMS executes it, possibly generating vast amounts of data. Where these data live is driver-specific: some drivers may choose to leave the output on the server and transfer them piecemeal to R, others may transfer all the data to the client – but not necessarily to the memory that R manages. See individual drivers’ dbSendQuery() documentation for details.

Value

dbSendQuery() returns an S4 object that inherits from DBIResult. The result set can be used with dbFetch() to extract records. Once you have finished using a result, make sure to clear it with dbClearResult().

The data retrieval flow

This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames.

Most of this flow, except repeated calling of dbBind() or dbBindArrow(), is implemented by dbGetQuery(), which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendQuery() to create a result set object of class DBIResult.

  2. Optionally, bind query parameters with dbBind() or dbBindArrow(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Optionally, use dbColumnInfo() to retrieve the structure of the result set without retrieving actual data.

  4. Use dbFetch() to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards.

  5. Use dbHasCompleted() to tell when you’re done. This method returns TRUE if no more rows are available for fetching.

  6. Repeat the last four steps as necessary.

  7. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

Failure modes

An error is raised when issuing a query over a closed or invalid connection, or if the query is not a non-NA string. An error is also raised if the syntax of the query is invalid and all query parameters are given (by passing the params argument) or the immediate argument is set to TRUE.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "mtcars", mtcars)
rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4")
dbFetch(rs)
dbClearResult(rs)

# Pass one set of values with the param argument:
rs <- dbSendQuery(
  con,
  "SELECT * FROM mtcars WHERE cyl = ?",
  params = list(4L)
)
dbFetch(rs)
dbClearResult(rs)

# Pass multiple sets of values with dbBind():
rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = ?")
dbBind(rs, list(6L))
dbFetch(rs)
dbBind(rs, list(8L))
dbFetch(rs)
dbClearResult(rs)

dbDisconnect(con)

Fetch records from a previously executed query

This section describes the behavior of the following methods:

dbFetch(res, n = -1, ...)

fetch(res, n = -1, ...)

Description

Fetch the next n elements (rows) from the result set and return them as a data.frame.

Arguments

res An object inheriting from DBIResult, created by dbSendQuery().
n maximum number of records to retrieve per fetch. Use n = -1 or n = Inf to retrieve all pending records. Some implementations may recognize other special values.
... Other arguments passed on to methods.

Details

fetch() is provided for compatibility with older DBI clients - for all new code you are strongly encouraged to use dbFetch(). The default implementation for dbFetch() calls fetch() so that it is compatible with existing code. Modern backends should implement for dbFetch() only.

Value

dbFetch() always returns a data.frame with as many rows as records were fetched and as many columns as fields in the result set, even if the result is a single value or has one or zero rows. Passing n = NA is supported and returns an arbitrary number of rows (at least one) as specified by the driver, but at most the remaining rows in the result set.

The data retrieval flow

This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames.

Most of this flow, except repeated calling of dbBind() or dbBindArrow(), is implemented by dbGetQuery(), which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendQuery() to create a result set object of class DBIResult.

  2. Optionally, bind query parameters with dbBind() or dbBindArrow(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Optionally, use dbColumnInfo() to retrieve the structure of the result set without retrieving actual data.

  4. Use dbFetch() to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards.

  5. Use dbHasCompleted() to tell when you’re done. This method returns TRUE if no more rows are available for fetching.

  6. Repeat the last four steps as necessary.

  7. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

Failure modes

An attempt to fetch from a closed result set raises an error. If the n argument is not an atomic whole number greater or equal to -1 or Inf, an error is raised, but a subsequent call to dbFetch() with proper n argument succeeds.

Calling dbFetch() on a result set from a data manipulation query created by dbSendStatement() can be fetched and return an empty data frame, with a warning.

Specification

Fetching multi-row queries with one or more columns by default returns the entire result. Multi-row queries can also be fetched progressively by passing a whole number (integer or numeric) as the n argument. A value of Inf for the n argument is supported and also returns the full result. If more rows than available are fetched, the result is returned in full without warning. If fewer rows than requested are returned, further fetches will return a data frame with zero rows. If zero rows are fetched, the columns of the data frame are still fully typed. Fetching fewer rows than available is permitted, no warning is issued when clearing the result set.

A column named row_names is treated like any other column.

The column types of the returned data frame depend on the data returned:

  • integer (or coercible to an integer) for integer values between -2^31 and 2^31 - 1, with NA for SQL NULL values

  • numeric for numbers with a fractional component, with NA for SQL NULL values

  • logical for Boolean values (some backends may return an integer); with NA for SQL NULL values

  • character for text, with NA for SQL NULL values

  • lists of raw for blobs with NULL entries for SQL NULL values

  • coercible using as.Date() for dates, with NA for SQL NULL values (also applies to the return value of the SQL function current_date)

  • coercible using hms::as_hms() for times, with NA for SQL NULL values (also applies to the return value of the SQL function current_time)

  • coercible using as.POSIXct() for timestamps, with NA for SQL NULL values (also applies to the return value of the SQL function current_timestamp)

If dates and timestamps are supported by the backend, the following R types are used:

  • Date for dates (also applies to the return value of the SQL function current_date)

  • POSIXct for timestamps (also applies to the return value of the SQL function current_timestamp)

R has no built-in type with lossless support for the full range of 64-bit or larger integers. If 64-bit integers are returned from a query, the following rules apply:

  • Values are returned in a container with support for the full range of valid 64-bit values (such as the integer64 class of the bit64 package)

  • Coercion to numeric always returns a number that is as close as possible to the true value

  • Loss of precision when converting to numeric gives a warning

  • Conversion to character always returns a lossless decimal representation of the data

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "mtcars", mtcars)

# Fetch all results
rs <- dbSendQuery(con, "SELECT * FROM mtcars WHERE cyl = 4")
dbFetch(rs)
dbClearResult(rs)

# Fetch in chunks
rs <- dbSendQuery(con, "SELECT * FROM mtcars")
while (!dbHasCompleted(rs)) {
  chunk <- dbFetch(rs, 10)
  print(nrow(chunk))
}

dbClearResult(rs)
dbDisconnect(con)

Clear a result set

This section describes the behavior of the following method:

dbClearResult(res, ...)

Description

Frees all resources (local and remote) associated with a result set. This step is mandatory for all objects obtained by calling dbSendQuery() or dbSendStatement().

Arguments

res An object inheriting from DBIResult.
... Other arguments passed on to methods.

Value

dbClearResult() returns TRUE, invisibly, for result sets obtained from dbSendQuery(), dbSendStatement(), or dbSendQueryArrow(),

The data retrieval flow

This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames.

Most of this flow, except repeated calling of dbBind() or dbBindArrow(), is implemented by dbGetQuery(), which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendQuery() to create a result set object of class DBIResult.

  2. Optionally, bind query parameters with dbBind() or dbBindArrow(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Optionally, use dbColumnInfo() to retrieve the structure of the result set without retrieving actual data.

  4. Use dbFetch() to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards.

  5. Use dbHasCompleted() to tell when you’re done. This method returns TRUE if no more rows are available for fetching.

  6. Repeat the last four steps as necessary.

  7. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

The command execution flow

This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of dbBindArrow(), is implemented by dbExecute(), which should be sufficient for non-parameterized queries. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendStatement() to create a result set object of class DBIResult. For some queries you need to pass immediate = TRUE.

  2. Optionally, bind query parameters withdbBind() or dbBindArrow(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Optionally, use dbGetRowsAffected() to retrieve the number of rows affected by the query.

  4. Repeat the last two steps as necessary.

  5. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

Failure modes

An attempt to close an already closed result set issues a warning for dbSendQuery(), dbSendStatement(), and dbSendQueryArrow(),

Specification

dbClearResult() frees all resources associated with retrieving the result of a query or update operation. The DBI backend can expect a call to dbClearResult() for each dbSendQuery() or dbSendStatement() call.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

rs <- dbSendQuery(con, "SELECT 1")
print(dbFetch(rs))

dbClearResult(rs)
dbDisconnect(con)

Bind values to a parameterized/prepared statement

This section describes the behavior of the following methods:

dbBind(res, params, ...)

dbBindArrow(res, params, ...)

Description

For parametrized or prepared statements, the dbSendQuery(), dbSendQueryArrow(), and dbSendStatement() functions can be called with statements that contain placeholders for values. The dbBind() and dbBindArrow() functions bind these placeholders to actual values, and are intended to be called on the result set before calling dbFetch() or dbFetchArrow(). The values are passed to dbBind() as lists or data frames, and to dbBindArrow() as a stream created by nanoarrow::as_nanoarrow_array_stream().

lifecycle: experimental lifecycle experimental

dbBindArrow() is experimental, as are the other ⁠*Arrow⁠ functions. dbSendQuery() is compatible with dbBindArrow(), and dbSendQueryArrow() is compatible with dbBind().

Arguments

res An object inheriting from DBIResult.
params For dbBind(), a list of values, named or unnamed, or a data frame, with one element/column per query parameter. For dbBindArrow(), values as a nanoarrow stream, with one column per query parameter.
... Other arguments passed on to methods.

Details

DBI supports parametrized (or prepared) queries and statements via the dbBind() and dbBindArrow() generics. Parametrized queries are different from normal queries in that they allow an arbitrary number of placeholders, which are later substituted by actual values. Parametrized queries (and statements) serve two purposes:

  • The same query can be executed more than once with different values. The DBMS may cache intermediate information for the query, such as the execution plan, and execute it faster.

  • Separation of query syntax and parameters protects against SQL injection.

The placeholder format is currently not specified by DBI; in the future, a uniform placeholder syntax may be supported. Consult the backend documentation for the supported formats. For automated testing, backend authors specify the placeholder syntax with the placeholder_pattern tweak. Known examples are:

  • ⁠?⁠ (positional matching in order of appearance) in RMariaDB and RSQLite

  • ⁠\$1⁠ (positional matching by index) in RPostgres and RSQLite

  • ⁠:name⁠ and ⁠\$name⁠ (named matching) in RSQLite

Value

dbBind() returns the result set, invisibly, for queries issued by dbSendQuery() or dbSendQueryArrow() and also for data manipulation statements issued by dbSendStatement().

The data retrieval flow

This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames.

Most of this flow, except repeated calling of dbBind() or dbBindArrow(), is implemented by dbGetQuery(), which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendQuery() to create a result set object of class DBIResult.

  2. Optionally, bind query parameters with dbBind() or dbBindArrow(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Optionally, use dbColumnInfo() to retrieve the structure of the result set without retrieving actual data.

  4. Use dbFetch() to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards.

  5. Use dbHasCompleted() to tell when you’re done. This method returns TRUE if no more rows are available for fetching.

  6. Repeat the last four steps as necessary.

  7. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

The data retrieval flow for Arrow streams

This section gives a complete overview over the flow for the execution of queries that return tabular data as an Arrow stream.

Most of this flow, except repeated calling of dbBindArrow() or dbBind(), is implemented by dbGetQueryArrow(), which should be sufficient unless you have a parameterized query that you want to reuse. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendQueryArrow() to create a result set object of class DBIResultArrow.

  2. Optionally, bind query parameters with dbBindArrow() or dbBind(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Use dbFetchArrow() to get a data stream.

  4. Repeat the last two steps as necessary.

  5. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

The command execution flow

This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of dbBindArrow(), is implemented by dbExecute(), which should be sufficient for non-parameterized queries. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendStatement() to create a result set object of class DBIResult. For some queries you need to pass immediate = TRUE.

  2. Optionally, bind query parameters withdbBind() or dbBindArrow(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Optionally, use dbGetRowsAffected() to retrieve the number of rows affected by the query.

  4. Repeat the last two steps as necessary.

  5. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

Failure modes

Calling dbBind() for a query without parameters raises an error.

Binding too many or not enough values, or parameters with wrong names or unequal length, also raises an error. If the placeholders in the query are named, all parameter values must have names (which must not be empty or NA), and vice versa, otherwise an error is raised. The behavior for mixing placeholders of different types (in particular mixing positional and named placeholders) is not specified.

Calling dbBind() on a result set already cleared by dbClearResult() also raises an error.

Specification

DBI clients execute parametrized statements as follows:

  1. Call dbSendQuery(), dbSendQueryArrow() or dbSendStatement() with a query or statement that contains placeholders, store the returned DBIResult object in a variable. Mixing placeholders (in particular, named and unnamed ones) is not recommended. It is good practice to register a call to dbClearResult() via on.exit() right after calling dbSendQuery() or dbSendStatement() (see the last enumeration item). Until dbBind() or dbBindArrow() have been called, the returned result set object has the following behavior:

    • dbFetch() raises an error (for dbSendQuery() and dbSendQueryArrow())

    • dbGetRowCount() returns zero (for dbSendQuery() and dbSendQueryArrow())

    • dbGetRowsAffected() returns an integer NA (for dbSendStatement())

    • dbIsValid() returns TRUE

    • dbHasCompleted() returns FALSE

  2. Call dbBind() or dbBindArrow():

    • For dbBind(), the params argument must be a list where all elements have the same lengths and contain values supported by the backend. A data.frame is internally stored as such a list.

    • For dbBindArrow(), the params argument must be a nanoarrow array stream, with one column per query parameter.

  3. Retrieve the data or the number of affected rows from the DBIResult object.

    • For queries issued by dbSendQuery() or dbSendQueryArrow(), call dbFetch().

    • For statements issued by dbSendStatements(), call dbGetRowsAffected(). (Execution begins immediately after the dbBind() call, the statement is processed entirely before the function returns.)

  4. Repeat 2. and 3. as necessary.

  5. Close the result set via dbClearResult().

The elements of the params argument do not need to be scalars, vectors of arbitrary length (including length 0) are supported. For queries, calling dbFetch() binding such parameters returns concatenated results, equivalent to binding and fetching for each set of values and connecting via rbind(). For data manipulation statements, dbGetRowsAffected() returns the total number of rows affected if binding non-scalar parameters. dbBind() also accepts repeated calls on the same result set for both queries and data manipulation statements, even if no results are fetched between calls to dbBind(), for both queries and data manipulation statements.

If the placeholders in the query are named, their order in the params argument is not important.

At least the following data types are accepted on input (including NA):

  • integer

  • numeric

  • logical for Boolean values

  • character (also with special characters such as spaces, newlines, quotes, and backslashes)

  • factor (bound as character, with warning)

  • Date (also when stored internally as integer)

  • POSIXct timestamps

  • POSIXlt timestamps

  • difftime values (also with units other than seconds and with the value stored as integer)

  • lists of raw for blobs (with NULL entries for SQL NULL values)

  • objects of type blob::blob

Examples

# Data frame flow:
con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "iris", iris)

# Using the same query for different values
iris_result <- dbSendQuery(con, "SELECT * FROM iris WHERE [Petal.Width] > ?")
dbBind(iris_result, list(2.3))
dbFetch(iris_result)
dbBind(iris_result, list(3))
dbFetch(iris_result)
dbClearResult(iris_result)

# Executing the same statement with different values at once
iris_result <- dbSendStatement(con, "DELETE FROM iris WHERE [Species] = \$species")
dbBind(iris_result, list(species = c("setosa", "versicolor", "unknown")))
dbGetRowsAffected(iris_result)
dbClearResult(iris_result)

nrow(dbReadTable(con, "iris"))

dbDisconnect(con)



# Arrow flow:
con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "iris", iris)

# Using the same query for different values
iris_result <- dbSendQueryArrow(con, "SELECT * FROM iris WHERE [Petal.Width] > ?")
dbBindArrow(
  iris_result,
  nanoarrow::as_nanoarrow_array_stream(data.frame(2.3, fix.empty.names = FALSE))
)
as.data.frame(dbFetchArrow(iris_result))
dbBindArrow(
  iris_result,
  nanoarrow::as_nanoarrow_array_stream(data.frame(3, fix.empty.names = FALSE))
)
as.data.frame(dbFetchArrow(iris_result))
dbClearResult(iris_result)

# Executing the same statement with different values at once
iris_result <- dbSendStatement(con, "DELETE FROM iris WHERE [Species] = \$species")
dbBindArrow(iris_result, nanoarrow::as_nanoarrow_array_stream(data.frame(
  species = c("setosa", "versicolor", "unknown")
)))
dbGetRowsAffected(iris_result)
dbClearResult(iris_result)

nrow(dbReadTable(con, "iris"))

dbDisconnect(con)

Retrieve results from a query

This section describes the behavior of the following method:

dbGetQuery(conn, statement, ...)

Description

Returns the result of a query as a data frame. dbGetQuery() comes with a default implementation (which should work with most backends) that calls dbSendQuery(), then dbFetch(), ensuring that the result is always freed by dbClearResult(). For retrieving chunked/paged results or for passing query parameters, see dbSendQuery(), in particular the “The data retrieval flow” section. For retrieving results as an Arrow object, see dbGetQueryArrow().

Arguments

conn A DBIConnection object, as returned by dbConnect().
statement a character string containing SQL.
... Other parameters passed on to methods.

Additional arguments

The following arguments are not part of the dbGetQuery() generic (to improve compatibility across backends) but are part of the DBI specification:

  • n (default: -1)

  • params (default: NULL)

  • immediate (default: NULL)

They must be provided as named arguments. See the “Specification” and “Value” sections for details on their usage.

Specification

A column named row_names is treated like any other column.

The n argument specifies the number of rows to be fetched. If omitted, fetching multi-row queries with one or more columns returns the entire result. A value of Inf for the n argument is supported and also returns the full result. If more rows than available are fetched (by passing a too large value for n), the result is returned in full without warning. If zero rows are requested, the columns of the data frame are still fully typed. Fetching fewer rows than available is permitted, no warning is issued.

The param argument allows passing query parameters, see dbBind() for details.

Specification for the immediate argument

The immediate argument supports distinguishing between “direct” and “prepared” APIs offered by many database drivers. Passing immediate = TRUE leads to immediate execution of the query or statement, via the “direct” API (if supported by the driver). The default NULL means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct immediate argument. Examples for possible behaviors:

  1. DBI backend defaults to immediate = TRUE internally

    1. A query without parameters is passed: query is executed

    2. A query with parameters is passed:

      1. params not given: rejected immediately by the database because of a syntax error in the query, the backend tries immediate = FALSE (and gives a message)

      2. params given: query is executed using immediate = FALSE

  2. DBI backend defaults to immediate = FALSE internally

    1. A query without parameters is passed:

      1. simple query: query is executed

      2. “special” query (such as setting a config options): fails, the backend tries immediate = TRUE (and gives a message)

    2. A query with parameters is passed:

      1. params not given: waiting for parameters via dbBind()

      2. params given: query is executed

Details

This method is for SELECT queries only (incl. other SQL statements that return a SELECT-alike result, e.g., execution of a stored procedure or data manipulation queries like ⁠INSERT INTO ... RETURNING ...⁠). To execute a stored procedure that does not return a result set, use dbExecute().

Some backends may support data manipulation statements through this method for compatibility reasons. However, callers are strongly advised to use dbExecute() for data manipulation statements.

Value

dbGetQuery() always returns a data.frame, with as many rows as records were fetched and as many columns as fields in the result set, even if the result is a single value or has one or zero rows.

Implementation notes

Subclasses should override this method only if they provide some sort of performance optimization.

Failure modes

An error is raised when issuing a query over a closed or invalid connection, if the syntax of the query is invalid, or if the query is not a non-NA string. If the n argument is not an atomic whole number greater or equal to -1 or Inf, an error is raised, but a subsequent call to dbGetQuery() with proper n argument succeeds.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "mtcars", mtcars)
dbGetQuery(con, "SELECT * FROM mtcars")
dbGetQuery(con, "SELECT * FROM mtcars", n = 6)

# Pass values using the param argument:
# (This query runs eight times, once for each different
# parameter. The resulting rows are combined into a single
# data frame.)
dbGetQuery(
  con,
  "SELECT COUNT(*) FROM mtcars WHERE cyl = ?",
  params = list(1:8)
)

dbDisconnect(con)

Execute a data manipulation statement on a given database connection

This section describes the behavior of the following method:

dbSendStatement(conn, statement, ...)

Description

The dbSendStatement() method only submits and synchronously executes the SQL data manipulation statement (e.g., UPDATE, DELETE, ⁠INSERT INTO⁠, ⁠DROP TABLE⁠, …) to the database engine. To query the number of affected rows, call dbGetRowsAffected() on the returned result object. You must also call dbClearResult() after that. For interactive use, you should almost always prefer dbExecute().

Arguments

conn A DBIConnection object, as returned by dbConnect().
statement a character string containing SQL.
... Other parameters passed on to methods.

Additional arguments

The following arguments are not part of the dbSendStatement() generic (to improve compatibility across backends) but are part of the DBI specification:

  • params (default: NULL)

  • immediate (default: NULL)

They must be provided as named arguments. See the “Specification” sections for details on their usage.

Specification

No warnings occur under normal conditions. When done, the DBIResult object must be cleared with a call to dbClearResult(). Failure to clear the result set leads to a warning when the connection is closed. If the backend supports only one open result set per connection, issuing a second query invalidates an already open result set and raises a warning. The newly opened result set is valid and must be cleared with dbClearResult().

The param argument allows passing query parameters, see dbBind() for details.

Specification for the immediate argument

The immediate argument supports distinguishing between “direct” and “prepared” APIs offered by many database drivers. Passing immediate = TRUE leads to immediate execution of the query or statement, via the “direct” API (if supported by the driver). The default NULL means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct immediate argument. Examples for possible behaviors:

  1. DBI backend defaults to immediate = TRUE internally

    1. A query without parameters is passed: query is executed

    2. A query with parameters is passed:

      1. params not given: rejected immediately by the database because of a syntax error in the query, the backend tries immediate = FALSE (and gives a message)

      2. params given: query is executed using immediate = FALSE

  2. DBI backend defaults to immediate = FALSE internally

    1. A query without parameters is passed:

      1. simple query: query is executed

      2. “special” query (such as setting a config options): fails, the backend tries immediate = TRUE (and gives a message)

    2. A query with parameters is passed:

      1. params not given: waiting for parameters via dbBind()

      2. params given: query is executed

Details

dbSendStatement() comes with a default implementation that simply forwards to dbSendQuery(), to support backends that only implement the latter.

Value

dbSendStatement() returns an S4 object that inherits from DBIResult. The result set can be used with dbGetRowsAffected() to determine the number of rows affected by the query. Once you have finished using a result, make sure to clear it with dbClearResult().

The command execution flow

This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of dbBindArrow(), is implemented by dbExecute(), which should be sufficient for non-parameterized queries. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendStatement() to create a result set object of class DBIResult. For some queries you need to pass immediate = TRUE.

  2. Optionally, bind query parameters withdbBind() or dbBindArrow(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Optionally, use dbGetRowsAffected() to retrieve the number of rows affected by the query.

  4. Repeat the last two steps as necessary.

  5. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

Failure modes

An error is raised when issuing a statement over a closed or invalid connection, or if the statement is not a non-NA string. An error is also raised if the syntax of the query is invalid and all query parameters are given (by passing the params argument) or the immediate argument is set to TRUE.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "cars", head(cars, 3))

rs <- dbSendStatement(
  con,
  "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)"
)
dbHasCompleted(rs)
dbGetRowsAffected(rs)
dbClearResult(rs)
dbReadTable(con, "cars")   # there are now 6 rows

# Pass one set of values directly using the param argument:
rs <- dbSendStatement(
  con,
  "INSERT INTO cars (speed, dist) VALUES (?, ?)",
  params = list(4L, 5L)
)
dbClearResult(rs)

# Pass multiple sets of values using dbBind():
rs <- dbSendStatement(
  con,
  "INSERT INTO cars (speed, dist) VALUES (?, ?)"
)
dbBind(rs, list(5:6, 6:7))
dbBind(rs, list(7L, 8L))
dbClearResult(rs)
dbReadTable(con, "cars")   # there are now 10 rows

dbDisconnect(con)

Change database state

This section describes the behavior of the following method:

dbExecute(conn, statement, ...)

Description

Executes a statement and returns the number of rows affected. dbExecute() comes with a default implementation (which should work with most backends) that calls dbSendStatement(), then dbGetRowsAffected(), ensuring that the result is always freed by dbClearResult(). For passing query parameters, see dbBind(), in particular the “The command execution flow” section.

Arguments

conn A DBIConnection object, as returned by dbConnect().
statement a character string containing SQL.
... Other parameters passed on to methods.

Additional arguments

The following arguments are not part of the dbExecute() generic (to improve compatibility across backends) but are part of the DBI specification:

  • params (default: NULL)

  • immediate (default: NULL)

They must be provided as named arguments. See the “Specification” sections for details on their usage.

Specification

The param argument allows passing query parameters, see dbBind() for details.

Specification for the immediate argument

The immediate argument supports distinguishing between “direct” and “prepared” APIs offered by many database drivers. Passing immediate = TRUE leads to immediate execution of the query or statement, via the “direct” API (if supported by the driver). The default NULL means that the backend should choose whatever API makes the most sense for the database, and (if relevant) tries the other API if the first attempt fails. A successful second attempt should result in a message that suggests passing the correct immediate argument. Examples for possible behaviors:

  1. DBI backend defaults to immediate = TRUE internally

    1. A query without parameters is passed: query is executed

    2. A query with parameters is passed:

      1. params not given: rejected immediately by the database because of a syntax error in the query, the backend tries immediate = FALSE (and gives a message)

      2. params given: query is executed using immediate = FALSE

  2. DBI backend defaults to immediate = FALSE internally

    1. A query without parameters is passed:

      1. simple query: query is executed

      2. “special” query (such as setting a config options): fails, the backend tries immediate = TRUE (and gives a message)

    2. A query with parameters is passed:

      1. params not given: waiting for parameters via dbBind()

      2. params given: query is executed

Details

You can also use dbExecute() to call a stored procedure that performs data manipulation or other actions that do not return a result set. To execute a stored procedure that returns a result set, or a data manipulation query that also returns a result set such as ⁠INSERT INTO ... RETURNING ...⁠, use dbGetQuery() instead.

Value

dbExecute() always returns a scalar numeric that specifies the number of rows affected by the statement.

Implementation notes

Subclasses should override this method only if they provide some sort of performance optimization.

Failure modes

An error is raised when issuing a statement over a closed or invalid connection, if the syntax of the statement is invalid, or if the statement is not a non-NA string.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "cars", head(cars, 3))
dbReadTable(con, "cars")   # there are 3 rows
dbExecute(
  con,
  "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)"
)
dbReadTable(con, "cars")   # there are now 6 rows

# Pass values using the param argument:
dbExecute(
  con,
  "INSERT INTO cars (speed, dist) VALUES (?, ?)",
  params = list(4:7, 5:8)
)
dbReadTable(con, "cars")   # there are now 10 rows

dbDisconnect(con)

Quote literal strings

This section describes the behavior of the following method:

dbQuoteString(conn, x, ...)

Description

Call this method to generate a string that is suitable for use in a query as a string literal, to make sure that you generate valid SQL and protect against SQL injection attacks.

Arguments

conn A DBIConnection object, as returned by dbConnect().
x A character vector to quote as string.
... Other arguments passed on to methods.

Value

dbQuoteString() returns an object that can be coerced to character, of the same length as the input. For an empty character vector this function returns a length-0 object.

When passing the returned object again to dbQuoteString() as x argument, it is returned unchanged. Passing objects of class SQL should also return them unchanged. (For backends it may be most convenient to return SQL objects to achieve this behavior, but this is not required.)

Failure modes

Passing a numeric, integer, logical, or raw vector, or a list for the x argument raises an error.

Specification

The returned expression can be used in a ⁠SELECT ...⁠ query, and for any scalar character x the value of dbGetQuery(paste0("SELECT ", dbQuoteString(x)))[[1]] must be identical to x, even if x contains spaces, tabs, quotes (single or double), backticks, or newlines (in any combination) or is itself the result of a dbQuoteString() call coerced back to character (even repeatedly). If x is NA, the result must merely satisfy is.na(). The strings "NA" or "NULL" are not treated specially.

NA should be translated to an unquoted SQL NULL, so that the query ⁠SELECT * FROM (SELECT 1) a WHERE ... IS NULL⁠ returns one row.

Examples

# Quoting ensures that arbitrary input is safe for use in a query
name <- "Robert'); DROP TABLE Students;--"
dbQuoteString(ANSI(), name)

# NAs become NULL
dbQuoteString(ANSI(), c("x", NA))

# SQL vectors are always passed through as is
var_name <- SQL("select")
var_name
dbQuoteString(ANSI(), var_name)

# This mechanism is used to prevent double escaping
dbQuoteString(ANSI(), dbQuoteString(ANSI(), name))

Quote identifiers

This section describes the behavior of the following method:

dbQuoteIdentifier(conn, x, ...)

Description

Call this method to generate a string that is suitable for use in a query as a column or table name, to make sure that you generate valid SQL and protect against SQL injection attacks. The inverse operation is dbUnquoteIdentifier().

Arguments

conn A DBIConnection object, as returned by dbConnect().
x A character vector, SQL or Id object to quote as identifier.
... Other arguments passed on to methods.

Value

dbQuoteIdentifier() returns an object that can be coerced to character, of the same length as the input. For an empty character vector this function returns a length-0 object. The names of the input argument are preserved in the output. When passing the returned object again to dbQuoteIdentifier() as x argument, it is returned unchanged. Passing objects of class SQL should also return them unchanged. (For backends it may be most convenient to return SQL objects to achieve this behavior, but this is not required.)

Failure modes

An error is raised if the input contains NA, but not for an empty string.

Specification

Calling dbGetQuery() for a query of the format ⁠SELECT 1 AS ...⁠ returns a data frame with the identifier, unquoted, as column name. Quoted identifiers can be used as table and column names in SQL queries, in particular in queries like ⁠SELECT 1 AS ...⁠ and ⁠SELECT * FROM (SELECT 1) ...⁠. The method must use a quoting mechanism that is unambiguously different from the quoting mechanism used for strings, so that a query like ⁠SELECT ... FROM (SELECT 1 AS ...)⁠ throws an error if the column names do not match.

The method can quote column names that contain special characters such as a space, a dot, a comma, or quotes used to mark strings or identifiers, if the database supports this. In any case, checking the validity of the identifier should be performed only when executing a query, and not by dbQuoteIdentifier().

Examples

# Quoting ensures that arbitrary input is safe for use in a query
name <- "Robert'); DROP TABLE Students;--"
dbQuoteIdentifier(ANSI(), name)

# Use Id() to specify other components such as the schema
id_name <- Id(schema = "schema_name", table = "table_name")
id_name
dbQuoteIdentifier(ANSI(), id_name)

# SQL vectors are always passed through as is
var_name <- SQL("select")
var_name
dbQuoteIdentifier(ANSI(), var_name)

# This mechanism is used to prevent double escaping
dbQuoteIdentifier(ANSI(), dbQuoteIdentifier(ANSI(), name))

Read database tables as data frames

This section describes the behavior of the following method:

dbReadTable(conn, name, ...)

Description

Reads a database table to a data frame, optionally converting a column to row names and converting the column names to valid R identifiers. Use dbReadTableArrow() instead to obtain an Arrow object.

Arguments

conn

A DBIConnection object, as returned by dbConnect().

name

The table name, passed on to dbQuoteIdentifier(). Options are:

  • a character string with the unquoted DBMS table name, e.g. “table_name”,

  • a call to Id() with components to the fully qualified table name, e.g. Id(schema = “my_schema”, table = “table_name”)

  • a call to SQL() with the quoted and fully qualified table name given verbatim, e.g. SQL(‘“my_schema”.”table_name”’)

…

Other parameters passed on to methods.

Additional arguments

The following arguments are not part of the dbReadTable() generic (to improve compatibility across backends) but are part of the DBI specification:

  • row.names (default: FALSE)

  • check.names

They must be provided as named arguments. See the “Value” section for details on their usage.

Specification

The name argument is processed as follows, to support databases that allow non-syntactic names for their objects:

  • If an unquoted table name as string: dbReadTable() will do the quoting, perhaps by calling dbQuoteIdentifier(conn, x = name)

  • If the result of a call to dbQuoteIdentifier(): no more quoting is done

Details

This function returns a data frame. Use dbReadTableArrow() to obtain an Arrow object.

Value

dbReadTable() returns a data frame that contains the complete data from the remote table, effectively the result of calling dbGetQuery() with ⁠SELECT * FROM <name>⁠.

An empty table is returned as a data frame with zero rows.

The presence of rownames depends on the row.names argument, see sqlColumnToRownames() for details:

  • If FALSE or NULL, the returned data frame doesn’t have row names.

  • If TRUE, a column named “row_names” is converted to row names.

  • If NA, a column named “row_names” is converted to row names if it exists, otherwise no translation occurs.

  • If a string, this specifies the name of the column in the remote table that contains the row names.

The default is row.names = FALSE.

If the database supports identifiers with special characters, the columns in the returned data frame are converted to valid R identifiers if the check.names argument is TRUE, If check.names = FALSE, the returned table has non-syntactic column names without quotes.

Failure modes

An error is raised if the table does not exist.

An error is raised if row.names is TRUE and no “row_names” column exists,

An error is raised if row.names is set to a string and no corresponding column exists.

An error is raised when calling this method for a closed or invalid connection. An error is raised if name cannot be processed with dbQuoteIdentifier() or if this results in a non-scalar. Unsupported values for row.names and check.names (non-scalars, unsupported data types, NA for check.names) also raise an error.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "mtcars", mtcars[1:10, ])
dbReadTable(con, "mtcars")

dbDisconnect(con)

Copy data frames to database tables

This section describes the behavior of the following method:

dbWriteTable(conn, name, value, ...)

Description

Writes, overwrites or appends a data frame to a database table, optionally converting row names to a column and specifying SQL data types for fields.

Arguments

conn

A DBIConnection object, as returned by dbConnect().

name

The table name, passed on to dbQuoteIdentifier(). Options are:

  • a character string with the unquoted DBMS table name, e.g. “table_name”,

  • a call to Id() with components to the fully qualified table name, e.g. Id(schema = “my_schema”, table = “table_name”)

  • a call to SQL() with the quoted and fully qualified table name given verbatim, e.g. SQL(‘“my_schema”.”table_name”’)

value

A data.frame (or coercible to data.frame).

…

Other parameters passed on to methods.

Additional arguments

The following arguments are not part of the dbWriteTable() generic (to improve compatibility across backends) but are part of the DBI specification:

  • row.names (default: FALSE)

  • overwrite (default: FALSE)

  • append (default: FALSE)

  • field.types (default: NULL)

  • temporary (default: FALSE)

They must be provided as named arguments. See the “Specification” and “Value” sections for details on their usage.

Specification

The name argument is processed as follows, to support databases that allow non-syntactic names for their objects:

  • If an unquoted table name as string: dbWriteTable() will do the quoting, perhaps by calling dbQuoteIdentifier(conn, x = name)

  • If the result of a call to dbQuoteIdentifier(): no more quoting is done

The value argument must be a data frame with a subset of the columns of the existing table if append = TRUE. The order of the columns does not matter with append = TRUE.

If the overwrite argument is TRUE, an existing table of the same name will be overwritten. This argument doesn’t change behavior if the table does not exist yet.

If the append argument is TRUE, the rows in an existing table are preserved, and the new data are appended. If the table doesn’t exist yet, it is created.

If the temporary argument is TRUE, the table is not available in a second connection and is gone after reconnecting. Not all backends support this argument. A regular, non-temporary table is visible in a second connection, in a pre-existing connection, and after reconnecting to the database.

SQL keywords can be used freely in table names, column names, and data. Quotes, commas, spaces, and other special characters such as newlines and tabs, can also be used in the data, and, if the database supports non-syntactic identifiers, also for table names and column names.

The following data types must be supported at least, and be read identically with dbReadTable():

  • integer

  • numeric (the behavior for Inf and NaN is not specified)

  • logical

  • NA as NULL

  • 64-bit values (using "bigint" as field type); the result can be

    • converted to a numeric, which may lose precision,

    • converted a character vector, which gives the full decimal representation

    • written to another table and read again unchanged

  • character (in both UTF-8 and native encodings), supporting empty strings before and after a non-empty string

  • factor (returned as character)

  • list of raw (if supported by the database)

  • objects of type blob::blob (if supported by the database)

  • date (if supported by the database; returned as Date), also for dates prior to 1970 or 1900 or after 2038

  • time (if supported by the database; returned as objects that inherit from difftime)

  • timestamp (if supported by the database; returned as POSIXct respecting the time zone but not necessarily preserving the input time zone), also for timestamps prior to 1970 or 1900 or after 2038 respecting the time zone but not necessarily preserving the input time zone)

Mixing column types in the same table is supported.

The field.types argument must be a named character vector with at most one entry for each column. It indicates the SQL data type to be used for a new column. If a column is missed from field.types, the type is inferred from the input data with dbDataType().

The interpretation of rownames depends on the row.names argument, see sqlRownamesToColumn() for details:

  • If FALSE or NULL, row names are ignored.

  • If TRUE, row names are converted to a column named “row_names”, even if the input data frame only has natural row names from 1 to nrow(...).

  • If NA, a column named “row_names” is created if the data has custom row names, no extra column is created in the case of natural row names.

  • If a string, this specifies the name of the column in the remote table that contains the row names, even if the input data frame only has natural row names.

The default is row.names = FALSE.

Details

This function expects a data frame. Use dbWriteTableArrow() to write an Arrow object.

This function is useful if you want to create and load a table at the same time. Use dbAppendTable() or dbAppendTableArrow() for appending data to an existing table, dbCreateTable() or dbCreateTableArrow() for creating a table, and dbExistsTable() and dbRemoveTable() for overwriting tables.

DBI only standardizes writing data frames with dbWriteTable(). Some backends might implement methods that can consume CSV files or other data formats. For details, see the documentation for the individual methods.

Value

dbWriteTable() returns TRUE, invisibly.

Failure modes

If the table exists, and both append and overwrite arguments are unset, or append = TRUE and the data frame with the new data has different column names, an error is raised; the remote table remains unchanged.

An error is raised when calling this method for a closed or invalid connection. An error is also raised if name cannot be processed with dbQuoteIdentifier() or if this results in a non-scalar. Invalid values for the additional arguments row.names, overwrite, append, field.types, and temporary (non-scalars, unsupported data types, NA, incompatible values, duplicate or missing names, incompatible columns) also raise an error.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "mtcars", mtcars[1:5, ])
dbReadTable(con, "mtcars")

dbWriteTable(con, "mtcars", mtcars[6:10, ], append = TRUE)
dbReadTable(con, "mtcars")

dbWriteTable(con, "mtcars", mtcars[1:10, ], overwrite = TRUE)
dbReadTable(con, "mtcars")

# No row names
dbWriteTable(con, "mtcars", mtcars[1:10, ], overwrite = TRUE, row.names = FALSE)
dbReadTable(con, "mtcars")

List remote tables

This section describes the behavior of the following method:

dbListTables(conn, ...)

Description

Returns the unquoted names of remote tables accessible through this connection. This should include views and temporary objects, but not all database backends (in particular RMariaDB and RMySQL) support this.

Arguments

conn A DBIConnection object, as returned by dbConnect().
... Other parameters passed on to methods.

Value

dbListTables() returns a character vector that enumerates all tables and views in the database. Tables added with dbWriteTable() are part of the list. As soon a table is removed from the database, it is also removed from the list of database tables.

The same applies to temporary tables if supported by the database.

The returned names are suitable for quoting with dbQuoteIdentifier().

Failure modes

An error is raised when calling this method for a closed or invalid connection.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbListTables(con)
dbWriteTable(con, "mtcars", mtcars)
dbListTables(con)

dbDisconnect(con)

Does a table exist?

This section describes the behavior of the following method:

dbExistsTable(conn, name, ...)

Description

Returns if a table given by name exists in the database.

Arguments

conn

A DBIConnection object, as returned by dbConnect().

name

The table name, passed on to dbQuoteIdentifier(). Options are:

  • a character string with the unquoted DBMS table name, e.g. “table_name”,

  • a call to Id() with components to the fully qualified table name, e.g. Id(schema = “my_schema”, table = “table_name”)

  • a call to SQL() with the quoted and fully qualified table name given verbatim, e.g. SQL(‘“my_schema”.”table_name”’)

…

Other parameters passed on to methods.

Value

dbExistsTable() returns a logical scalar, TRUE if the table or view specified by the name argument exists, FALSE otherwise.

This includes temporary tables if supported by the database.

Failure modes

An error is raised when calling this method for a closed or invalid connection. An error is also raised if name cannot be processed with dbQuoteIdentifier() or if this results in a non-scalar.

Specification

The name argument is processed as follows, to support databases that allow non-syntactic names for their objects:

  • If an unquoted table name as string: dbExistsTable() will do the quoting, perhaps by calling dbQuoteIdentifier(conn, x = name)

  • If the result of a call to dbQuoteIdentifier(): no more quoting is done

For all tables listed by dbListTables(), dbExistsTable() returns TRUE.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbExistsTable(con, "iris")
dbWriteTable(con, "iris", iris)
dbExistsTable(con, "iris")

dbDisconnect(con)

Remove a table from the database

This section describes the behavior of the following method:

dbRemoveTable(conn, name, ...)

Description

Remove a remote table (e.g., created by dbWriteTable()) from the database.

Arguments

conn

A DBIConnection object, as returned by dbConnect().

name

The table name, passed on to dbQuoteIdentifier(). Options are:

  • a character string with the unquoted DBMS table name, e.g. “table_name”,

  • a call to Id() with components to the fully qualified table name, e.g. Id(schema = “my_schema”, table = “table_name”)

  • a call to SQL() with the quoted and fully qualified table name given verbatim, e.g. SQL(‘“my_schema”.”table_name”’)

…

Other parameters passed on to methods.

Additional arguments

The following arguments are not part of the dbRemoveTable() generic (to improve compatibility across backends) but are part of the DBI specification:

  • temporary (default: FALSE)

  • fail_if_missing (default: TRUE)

These arguments must be provided as named arguments.

If temporary is TRUE, the call to dbRemoveTable() will consider only temporary tables. Not all backends support this argument. In particular, permanent tables of the same name are left untouched.

If fail_if_missing is FALSE, the call to dbRemoveTable() succeeds if the table does not exist.

Specification

A table removed by dbRemoveTable() doesn’t appear in the list of tables returned by dbListTables(), and dbExistsTable() returns FALSE. The removal propagates immediately to other connections to the same database. This function can also be used to remove a temporary table.

The name argument is processed as follows, to support databases that allow non-syntactic names for their objects:

  • If an unquoted table name as string: dbRemoveTable() will do the quoting, perhaps by calling dbQuoteIdentifier(conn, x = name)

  • If the result of a call to dbQuoteIdentifier(): no more quoting is done

Value

dbRemoveTable() returns TRUE, invisibly.

Failure modes

If the table does not exist, an error is raised. An attempt to remove a view with this function may result in an error.

An error is raised when calling this method for a closed or invalid connection. An error is also raised if name cannot be processed with dbQuoteIdentifier() or if this results in a non-scalar.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbExistsTable(con, "iris")
dbWriteTable(con, "iris", iris)
dbExistsTable(con, "iris")
dbRemoveTable(con, "iris")
dbExistsTable(con, "iris")

dbDisconnect(con)

List field names of a remote table

This section describes the behavior of the following method:

dbListFields(conn, name, ...)

Description

Returns the field names of a remote table as a character vector.

Arguments

conn

A DBIConnection object, as returned by dbConnect().

name

The table name, passed on to dbQuoteIdentifier(). Options are:

  • a character string with the unquoted DBMS table name, e.g. “table_name”,

  • a call to Id() with components to the fully qualified table name, e.g. Id(schema = “my_schema”, table = “table_name”)

  • a call to SQL() with the quoted and fully qualified table name given verbatim, e.g. SQL(‘“my_schema”.”table_name”’)

…

Other parameters passed on to methods.

Value

dbListFields() returns a character vector that enumerates all fields in the table in the correct order. This also works for temporary tables if supported by the database. The returned names are suitable for quoting with dbQuoteIdentifier().

Failure modes

If the table does not exist, an error is raised. Invalid types for the name argument (e.g., character of length not equal to one, or numeric) lead to an error. An error is also raised when calling this method for a closed or invalid connection.

Specification

The name argument can be

  • a string

  • the return value of dbQuoteIdentifier()

  • a value from the table column from the return value of dbListObjects() where is_prefix is FALSE

A column named row_names is treated like any other column.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "mtcars", mtcars)
dbListFields(con, "mtcars")

dbDisconnect(con)

Is this DBMS object still valid?

This section describes the behavior of the following method:

dbIsValid(dbObj, ...)

Description

This generic tests whether a database object is still valid (i.e. it hasn’t been disconnected or cleared).

Arguments

dbObj An object inheriting from DBIObject, i.e. DBIDriver, DBIConnection, or a DBIResult
... Other arguments to methods.

Value

dbIsValid() returns a logical scalar, TRUE if the object specified by dbObj is valid, FALSE otherwise. A DBIConnection object is initially valid, and becomes invalid after disconnecting with dbDisconnect(). For an invalid connection object (e.g., for some drivers if the object is saved to a file and then restored), the method also returns FALSE. A DBIResult object is valid after a call to dbSendQuery(), and stays valid even after all rows have been fetched; only clearing it with dbClearResult() invalidates it. A DBIResult object is also valid after a call to dbSendStatement(), and stays valid after querying the number of rows affected; only clearing it with dbClearResult() invalidates it. If the connection to the database system is dropped (e.g., due to connectivity problems, server failure, etc.), dbIsValid() should return FALSE. This is not tested automatically.

Examples

dbIsValid(RSQLite::SQLite())

con <- dbConnect(RSQLite::SQLite(), ":memory:")
dbIsValid(con)

rs <- dbSendQuery(con, "SELECT 1")
dbIsValid(rs)

dbClearResult(rs)
dbIsValid(rs)

dbDisconnect(con)
dbIsValid(con)

Completion status

This section describes the behavior of the following method:

dbHasCompleted(res, ...)

Description

This method returns if the operation has completed. A SELECT query is completed if all rows have been fetched. A data manipulation statement is always completed.

Arguments

res An object inheriting from DBIResult.
... Other arguments passed on to methods.

Value

dbHasCompleted() returns a logical scalar. For a query initiated by dbSendQuery() with non-empty result set, dbHasCompleted() returns FALSE initially and TRUE after calling dbFetch() without limit. For a query initiated by dbSendStatement(), dbHasCompleted() always returns TRUE.

The data retrieval flow

This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames.

Most of this flow, except repeated calling of dbBind() or dbBindArrow(), is implemented by dbGetQuery(), which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendQuery() to create a result set object of class DBIResult.

  2. Optionally, bind query parameters with dbBind() or dbBindArrow(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Optionally, use dbColumnInfo() to retrieve the structure of the result set without retrieving actual data.

  4. Use dbFetch() to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards.

  5. Use dbHasCompleted() to tell when you’re done. This method returns TRUE if no more rows are available for fetching.

  6. Repeat the last four steps as necessary.

  7. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

Failure modes

Attempting to query completion status for a result set cleared with dbClearResult() gives an error.

Specification

The completion status for a query is only guaranteed to be set to FALSE after attempting to fetch past the end of the entire result. Therefore, for a query with an empty result set, the initial return value is unspecified, but the result value is TRUE after trying to fetch only one row.

Similarly, for a query with a result set of length n, the return value is unspecified after fetching n rows, but the result value is TRUE after trying to fetch only one more row.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "mtcars", mtcars)
rs <- dbSendQuery(con, "SELECT * FROM mtcars")

dbHasCompleted(rs)
ret1 <- dbFetch(rs, 10)
dbHasCompleted(rs)
ret2 <- dbFetch(rs)
dbHasCompleted(rs)

dbClearResult(rs)
dbDisconnect(con)

Get the statement associated with a result set

This section describes the behavior of the following method:

dbGetStatement(res, ...)

Description

Returns the statement that was passed to dbSendQuery() or dbSendStatement().

Arguments

res An object inheriting from DBIResult.
... Other arguments passed on to methods.

Value

dbGetStatement() returns a string, the query used in either dbSendQuery() or dbSendStatement().

Failure modes

Attempting to query the statement for a result set cleared with dbClearResult() gives an error.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "mtcars", mtcars)
rs <- dbSendQuery(con, "SELECT * FROM mtcars")
dbGetStatement(rs)

dbClearResult(rs)
dbDisconnect(con)

The number of rows fetched so far

This section describes the behavior of the following method:

dbGetRowCount(res, ...)

Description

Returns the total number of rows actually fetched with calls to dbFetch() for this result set.

Arguments

res An object inheriting from DBIResult.
... Other arguments passed on to methods.

Value

dbGetRowCount() returns a scalar number (integer or numeric), the number of rows fetched so far. After calling dbSendQuery(), the row count is initially zero. After a call to dbFetch() without limit, the row count matches the total number of rows returned. Fetching a limited number of rows increases the number of rows by the number of rows returned, even if fetching past the end of the result set. For queries with an empty result set, zero is returned even after fetching. For data manipulation statements issued with dbSendStatement(), zero is returned before and after calling dbFetch().

Failure modes

Attempting to get the row count for a result set cleared with dbClearResult() gives an error.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "mtcars", mtcars)
rs <- dbSendQuery(con, "SELECT * FROM mtcars")

dbGetRowCount(rs)
ret1 <- dbFetch(rs, 10)
dbGetRowCount(rs)
ret2 <- dbFetch(rs)
dbGetRowCount(rs)
nrow(ret1) + nrow(ret2)

dbClearResult(rs)
dbDisconnect(con)

The number of rows affected

This section describes the behavior of the following method:

dbGetRowsAffected(res, ...)

Description

This method returns the number of rows that were added, deleted, or updated by a data manipulation statement.

Arguments

res An object inheriting from DBIResult.
... Other arguments passed on to methods.

Value

dbGetRowsAffected() returns a scalar number (integer or numeric), the number of rows affected by a data manipulation statement issued with dbSendStatement(). The value is available directly after the call and does not change after calling dbFetch(). NA_integer_ or NA_numeric_ are allowed if the number of rows affected is not known.

For queries issued with dbSendQuery(), zero is returned before and after the call to dbFetch(). NA values are not allowed.

The command execution flow

This section gives a complete overview over the flow for the execution of SQL statements that have side effects such as stored procedures, inserting or deleting data, or setting database or connection options. Most of this flow, except repeated calling of dbBindArrow(), is implemented by dbExecute(), which should be sufficient for non-parameterized queries. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendStatement() to create a result set object of class DBIResult. For some queries you need to pass immediate = TRUE.

  2. Optionally, bind query parameters withdbBind() or dbBindArrow(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Optionally, use dbGetRowsAffected() to retrieve the number of rows affected by the query.

  4. Repeat the last two steps as necessary.

  5. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

Failure modes

Attempting to get the rows affected for a result set cleared with dbClearResult() gives an error.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "mtcars", mtcars)
rs <- dbSendStatement(con, "DELETE FROM mtcars")
dbGetRowsAffected(rs)
nrow(mtcars)

dbClearResult(rs)
dbDisconnect(con)

Information about result types

This section describes the behavior of the following method:

dbColumnInfo(res, ...)

Description

Produces a data.frame that describes the output of a query. The data.frame should have as many rows as there are output fields in the result set, and each column in the data.frame describes an aspect of the result set field (field name, type, etc.)

Arguments

res An object inheriting from DBIResult.
... Other arguments passed on to methods.

Value

dbColumnInfo() returns a data frame with at least two columns "name" and "type" (in that order) (and optional columns that start with a dot). The "name" and "type" columns contain the names and types of the R columns of the data frame that is returned from dbFetch(). The "type" column is of type character and only for information. Do not compute on the "type" column, instead use dbFetch(res, n = 0) to create a zero-row data frame initialized with the correct data types.

The data retrieval flow

This section gives a complete overview over the flow for the execution of queries that return tabular data as data frames.

Most of this flow, except repeated calling of dbBind() or dbBindArrow(), is implemented by dbGetQuery(), which should be sufficient unless you want to access the results in a paged way or you have a parameterized query that you want to reuse. This flow requires an active connection established by dbConnect(). See also vignette("dbi-advanced") for a walkthrough.

  1. Use dbSendQuery() to create a result set object of class DBIResult.

  2. Optionally, bind query parameters with dbBind() or dbBindArrow(). This is required only if the query contains placeholders such as ⁠?⁠ or ⁠\$1⁠, depending on the database backend.

  3. Optionally, use dbColumnInfo() to retrieve the structure of the result set without retrieving actual data.

  4. Use dbFetch() to get the entire result set, a page of results, or the remaining rows. Fetching zero rows is also possible to retrieve the structure of the result set as a data frame. This step can be called multiple times. Only forward paging is supported, you need to cache previous pages if you need to navigate backwards.

  5. Use dbHasCompleted() to tell when you’re done. This method returns TRUE if no more rows are available for fetching.

  6. Repeat the last four steps as necessary.

  7. Use dbClearResult() to clean up the result set object. This step is mandatory even if no rows have been fetched or if an error has occurred during the processing. It is good practice to use on.exit() or withr::defer() to ensure that this step is always executed.

Failure modes

An attempt to query columns for a closed result set raises an error.

Specification

A column named row_names is treated like any other column.

The column names are always consistent with the data returned by dbFetch().

If the query returns unnamed columns, non-empty and non-NA names are assigned.

Column names that correspond to SQL or R keywords are left unchanged.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

rs <- dbSendQuery(con, "SELECT 1 AS a, 2 AS b")
dbColumnInfo(rs)
dbFetch(rs)

dbClearResult(rs)
dbDisconnect(con)

Begin/commit/rollback SQL transactions

This section describes the behavior of the following methods:

dbBegin(conn, ...)

dbCommit(conn, ...)

dbRollback(conn, ...)

Description

A transaction encapsulates several SQL statements in an atomic unit. It is initiated with dbBegin() and either made persistent with dbCommit() or undone with dbRollback(). In any case, the DBMS guarantees that either all or none of the statements have a permanent effect. This helps ensuring consistency of write operations to multiple tables.

Arguments

conn A DBIConnection object, as returned by dbConnect().
... Other parameters passed on to methods.

Details

Not all database engines implement transaction management, in which case these methods should not be implemented for the specific DBIConnection subclass.

Value

dbBegin(), dbCommit() and dbRollback() return TRUE, invisibly.

Failure modes

The implementations are expected to raise an error in case of failure, but this is not tested. In any way, all generics throw an error with a closed or invalid connection. In addition, a call to dbCommit() or dbRollback() without a prior call to dbBegin() raises an error. Nested transactions are not supported by DBI, an attempt to call dbBegin() twice yields an error.

Specification

Actual support for transactions may vary between backends. A transaction is initiated by a call to dbBegin() and committed by a call to dbCommit(). Data written in a transaction must persist after the transaction is committed. For example, a record that is missing when the transaction is started but is created during the transaction must exist both during and after the transaction, and also in a new connection.

A transaction can also be aborted with dbRollback(). All data written in such a transaction must be removed after the transaction is rolled back. For example, a record that is missing when the transaction is started but is created during the transaction must not exist anymore after the rollback.

Disconnection from a connection with an open transaction effectively rolls back the transaction. All data written in such a transaction must be removed after the transaction is rolled back.

The behavior is not specified if other arguments are passed to these functions. In particular, RSQLite issues named transactions with support for nesting if the name argument is set.

The transaction isolation level is not specified by DBI.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "cash", data.frame(amount = 100))
dbWriteTable(con, "account", data.frame(amount = 2000))

# All operations are carried out as logical unit:
dbBegin(con)
withdrawal <- 300
dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal))
dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal))
dbCommit(con)

dbReadTable(con, "cash")
dbReadTable(con, "account")

# Rolling back after detecting negative value on account:
dbBegin(con)
withdrawal <- 5000
dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal))
dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal))
if (dbReadTable(con, "account")\$amount >= 0) {
  dbCommit(con)
} else {
  dbRollback(con)
}

dbReadTable(con, "cash")
dbReadTable(con, "account")

dbDisconnect(con)

Self-contained SQL transactions

This section describes the behavior of the following methods:

dbWithTransaction(conn, code, ...)

dbBreak()

Description

Given that transactions are implemented, this function allows you to pass in code that is run in a transaction. The default method of dbWithTransaction() calls dbBegin() before executing the code, and dbCommit() after successful completion, or dbRollback() in case of an error. The advantage is that you don’t have to remember to do dbBegin() and dbCommit() or dbRollback() – that is all taken care of. The special function dbBreak() allows an early exit with rollback, it can be called only inside dbWithTransaction().

Arguments

conn A DBIConnection object, as returned by dbConnect().
code An arbitrary block of R code.
... Other parameters passed on to methods.

Details

DBI implements dbWithTransaction(), backends should need to override this generic only if they implement specialized handling.

Value

dbWithTransaction() returns the value of the executed code.

Failure modes

Failure to initiate the transaction (e.g., if the connection is closed or invalid of if dbBegin() has been called already) gives an error.

Specification

dbWithTransaction() initiates a transaction with dbBegin(), executes the code given in the code argument, and commits the transaction with dbCommit(). If the code raises an error, the transaction is instead aborted with dbRollback(), and the error is propagated. If the code calls dbBreak(), execution of the code stops and the transaction is silently aborted. All side effects caused by the code (such as the creation of new variables) propagate to the calling environment.

Examples

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "cash", data.frame(amount = 100))
dbWriteTable(con, "account", data.frame(amount = 2000))

# All operations are carried out as logical unit:
dbWithTransaction(
  con,
  {
    withdrawal <- 300
    dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal))
    dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal))
  }
)

# The code is executed as if in the current environment:
withdrawal

# The changes are committed to the database after successful execution:
dbReadTable(con, "cash")
dbReadTable(con, "account")

# Rolling back with dbBreak():
dbWithTransaction(
  con,
  {
    withdrawal <- 5000
    dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal))
    dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal))
    if (dbReadTable(con, "account")\$amount < 0) {
      dbBreak()
    }
  }
)

# These changes were not committed to the database:
dbReadTable(con, "cash")
dbReadTable(con, "account")

dbDisconnect(con)

Get DBMS metadata

This section describes the behavior of the following method:

dbGetInfo(dbObj, ...)

Description

Retrieves information on objects of class DBIDriver, DBIConnection or DBIResult.

Arguments

dbObj An object inheriting from DBIObject, i.e. DBIDriver, DBIConnection, or a DBIResult
... Other arguments to methods.

Value

For objects of class DBIDriver, dbGetInfo() returns a named list that contains at least the following components:

  • driver.version: the package version of the DBI backend,

  • client.version: the version of the DBMS client library.

For objects of class DBIConnection, dbGetInfo() returns a named list that contains at least the following components:

  • db.version: version of the database server,

  • dbname: database name,

  • username: username to connect to the database,

  • host: hostname of the database server,

  • port: port on the database server. It must not contain a password component. Components that are not applicable should be set to NA.

For objects of class DBIResult, dbGetInfo() returns a named list that contains at least the following components:

  • statatment: the statement used with dbSendQuery() or dbExecute(), as returned by dbGetStatement(),

  • row.count: the number of rows fetched so far (for queries), as returned by dbGetRowCount(),

  • rows.affected: the number of rows affected (for statements), as returned by dbGetRowsAffected()

  • has.completed: a logical that indicates if the query or statement has completed, as returned by dbHasCompleted().

Implementation notes

The default implementation for ⁠DBIResult objects⁠ constructs such a list from the return values of the corresponding methods, dbGetStatement(), dbGetRowCount(), dbGetRowsAffected(), and dbHasCompleted().

Examples

dbGetInfo(RSQLite::SQLite())
DBI/inst/doc/DBI-advanced.Rmd0000644000176200001440000002647114627140067015220 0ustar liggesusers--- title: "Advanced DBI Usage" author: "James Wondrasek, Kirill Müller" date: "17/03/2020" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Advanced DBI Usage} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} library(knitr) opts_chunk$set( echo = TRUE, error = Sys.getenv("IN_PKGDOWN") != "true" || (getRversion() < "3.5") ) knit_print.data.frame <- function(x, ...) { print(head(x, 3)) if (nrow(x) > 3) { cat("Showing 3 out of", nrow(x), "rows.\n") } invisible(x) } registerS3method("knit_print", "data.frame", "knit_print.data.frame") ``` ## Who this tutorial is for This tutorial is for you if you need to use a richer set of SQL features such as data manipulation queries, parameterized queries and queries performed using SQL's transaction features. See `vignette("DBI", package = "DBI")` for a more basic tutorial covering connecting to DBMS and executing simple queries. ## How to run more complex queries using DBI `dbGetQuery()` works by calling a number of functions behind the scenes. If you need more control you can manually build your own query, retrieve results at your selected rate, and release the resources involved by calling the same functions. These functions are: - `dbSendQuery()` sends the SQL query to the DBMS and returns a `result` object. The query is limited to `SELECT` statements. If you want to send other statements, such as `INSERT`, `UPDATE`, `DELETE`, etc, use `dbSendStatement()`. - `dbFetch()` is called with the `result` object returned by `dbSendQuery()`. It also accepts an argument specifying the number of rows to be returned, e.g. `n = 200`. If you want to fetch all the rows, use `n = -1`. - `dbClearResult()` is called when you have finished retrieving data. It releases the resources associated with the `result` object. ```{r} library(DBI) con <- dbConnect( RMariaDB::MariaDB(), host = "db.relational-data.org", port = 3306, username = "guest", password = "relational", dbname = "sakila" ) res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = 'G'") df <- dbFetch(res, n = 3) dbClearResult(res) head(df, 3) ``` ## How to read part of a table from a database If your dataset is large you may want to fetch a limited number of rows at a time. As demonstrated below, this can be accomplished by using a while loop where the function `dbHasCompleted()` is used to check for ongoing rows, and `dbFetch()` is used with the `n = X` argument, specifying how many rows to return on each iteration. Again, we call `dbClearResult()` at the end to release resources. ```{r} res <- dbSendQuery(con, "SELECT * FROM film") while (!dbHasCompleted(res)) { chunk <- dbFetch(res, n = 300) print(nrow(chunk)) } dbClearResult(res) ``` ## How to use parameters (safely) in SQL queries `dbSendQuery()` can be used with parameterized SQL queries. DBI supports two ways to avoid SQL injection attacks from user-supplied parameters: quoting and parameterized queries. ### Quoting Quoting of parameter values is performed using the function `dbQuoteLiteral()`, which supports many R data types, including date and time.[^quote-string] [^quote-string]: An older method, `dbQuoteString()`, was used to quote string values only. The `dbQuoteLiteral()` method forwards to `dbQuoteString()` for character vectors. Users do not need to distinguish between these two cases. In cases where users may be supplying table or column names to use in the query for data retrieval, those names or identifiers must also be escaped. As there may be DBMS-specific rules for escaping these identifiers, DBI provides the function `dbQuoteIdentifier()` to generate a safe string representation. ```{r quote} safe_id <- dbQuoteIdentifier(con, "rating") safe_param <- dbQuoteLiteral(con, "G") query <- paste0("SELECT title, ", safe_id, " FROM film WHERE ", safe_id, " = ", safe_param) query res <- dbSendQuery(con, query) dbFetch(res) dbClearResult(res) ``` The same result can be had by using `glue::glue_sql()`. It performs the same safe quoting on any variable or R statement appearing between braces within the query string. ```{r} id <- "rating" param <- "G" query <- glue::glue_sql("SELECT title, {`id`} FROM film WHERE {`id`} = {param}", .con = con) df <- dbGetQuery(con, query) head(df, 3) ``` ### Parameterized queries Rather than performing the parameter substitution ourselves, we can push it to the DBMS by including placeholders in the query. Different DBMS use different placeholder schemes, DBI passes through the SQL expression unchanged. MariaDB uses a question mark (?) as placeholder and expects an unnamed list of parameter values. Other DBMS may use named parameters. We recommend consulting the documentation for the DBMS you are using. As an example, a web search for "mariadb parameterized queries" leads to the documentation for the [`PREPARE` statement](https://mariadb.com/kb/en/prepare-statement/) which mentions: > Within the statement, "?" characters can be used as parameter markers to indicate where data values are to be bound to the query later when you execute it. Currently there is no list of which placeholder scheme a particular DBMS supports. Placeholders only work for literal values. Other parts of the query, e.g. table or column identifiers, still need to be quoted with `dbQuoteIdentifier()`. For a single set of parameters, the `params` argument to `dbSendQuery()` or `dbGetQuery()` can be used. It takes a list and its members are substituted in order for the placeholders within the query. ```{r params} params <- list("G") safe_id <- dbQuoteIdentifier(con, "rating") query <- paste0("SELECT * FROM film WHERE ", safe_id, " = ?") query res <- dbSendQuery(con, query, params = params) dbFetch(res, n = 3) dbClearResult(res) ``` Below is an example query using multiple placeholders with the MariaDB driver. The placeholders are supplied as a list of values ordered to match the position of the placeholders in the query. ```{r multi-param} q_params <- list("G", 90) query <- "SELECT title, rating, length FROM film WHERE rating = ? AND length >= ?" res <- dbSendQuery(con, query, params = q_params) dbFetch(res, n = 3) dbClearResult(res) ``` When you wish to perform the same query with different sets of parameter values, `dbBind()` is used. There are two ways to use `dbBind()`. Firstly, it can be used multiple times with same query. ```{r dbbind} res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = ?") dbBind(res, list("G")) dbFetch(res, n = 3) dbBind(res, list("PG")) dbFetch(res, n = 3) dbClearResult(res) ``` Secondly, `dbBind()` can be used to execute the same statement with multiple values at once. ```{r bind_quotestring} res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = ?") dbBind(res, list(c("G", "PG"))) dbFetch(res, n = 3) dbClearResult(res) ``` Use a list of vectors if your query has multiple parameters: ```{r bind-multi-param} q_params <- list(c("G", "PG"), c(90, 120)) query <- "SELECT title, rating, length FROM film WHERE rating = ? AND length >= ?" res <- dbSendQuery(con, query, params = q_params) dbFetch(res, n = 3) dbClearResult(res) ``` Always disconnect from the database when done. ```{r disconnect} dbDisconnect(con) ``` ## SQL data manipulation - UPDATE, DELETE and friends For SQL queries that affect the underlying database, such as UPDATE, DELETE, INSERT INTO, and DROP TABLE, DBI provides two functions. `dbExecute()` passes the SQL statement to the DBMS for execution and returns the number of rows affected. `dbSendStatement()` performs in the same manner, but returns a result object. Call `dbGetRowsAffected()` with the result object to get the count of the affected rows. You then need to call `dbClearResult()` with the result object afterwards to release resources. In actuality, `dbExecute()` is a convenience function that calls `dbSendStatement()`, `dbGetRowsAffected()`, and `dbClearResult()`. You can use these functions if you need more control over the query process. The subsequent examples use an in-memory SQL database provided by `RSQLite::SQLite()`, because the remote database used in above examples does not allow writing. ```{r} library(DBI) con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cars", head(cars, 3)) dbExecute( con, "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)" ) rs <- dbSendStatement( con, "INSERT INTO cars (speed, dist) VALUES (4, 4), (5, 5), (6, 6)" ) dbGetRowsAffected(rs) dbClearResult(rs) dbReadTable(con, "cars") ``` Do not forget to disconnect from the database at the end. ```{r} dbDisconnect(con) ``` ## SQL transactions with DBI DBI allows you to group multiple queries into a single atomic transaction. Transactions are initiated with `dbBegin()` and either made persistent with `dbCommit()` or undone with `dbRollback()`. The example below updates two tables and ensures that either both tables are updated, or no changes are persisted to the database and an error is thrown. ```{r} con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cash", data.frame(amount = 100)) dbWriteTable(con, "account", data.frame(amount = 2000)) withdraw <- function(amount) { # All operations must be carried out as logical unit: dbExecute(con, "UPDATE cash SET amount = amount + ?", list(amount)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(amount)) } withdraw_transacted <- function(amount) { # Ensure atomicity dbBegin(con) # Perform operation withdraw(amount) # Persist results dbCommit(con) } withdraw_transacted(300) ``` After withdrawing 300 credits, the cash is increased and the account is decreased by this amount. The transaction ensures that either both operations succeed, or no change occurs. ```{r} dbReadTable(con, "cash") dbReadTable(con, "account") ``` We can roll back changes manually if necessary. Do not forget to call `dbRollback()` in case of error, otherwise the transaction remains open indefinitely. ```{r} withdraw_if_funds <- function(amount) { dbBegin(con) withdraw(amount) # Rolling back after detecting negative value on account: if (dbReadTable(con, "account")$amount >= 0) { dbCommit(con) TRUE } else { message("Insufficient funds") dbRollback(con) FALSE } } withdraw_if_funds(5000) dbReadTable(con, "cash") dbReadTable(con, "account") ``` `dbWithTransaction()` simplifies using transactions. Pass it a connection and the code you want to run as a transaction. It will execute the code and call `dbCommit()` on success and call `dbRollback()` if an error is thrown. ```{r error = TRUE} withdraw_safely <- function(amount) { dbWithTransaction(con, { withdraw(amount) if (dbReadTable(con, "account")$amount < 0) { stop("Error: insufficient funds", call. = FALSE) } }) } withdraw_safely(5000) dbReadTable(con, "cash") dbReadTable(con, "account") ``` As usual, do not forget to disconnect from the database when done. ```{r} dbDisconnect(con) ``` ## Conclusion That concludes the major features of DBI. For more details on the library functions covered in this tutorial and the `vignette("DBI", package = "DBI")` introductory tutorial see the DBI specification at `vignette("spec", package = "DBI")`. If you are after a data manipulation library that works at a higher level of abstraction, check out [dplyr](https://dplyr.tidyverse.org). It is a grammar of data manipulation that can work with local dataframes and remote databases and uses DBI under the hood. DBI/inst/doc/DBI-1.html0000644000176200001440000042557114627152526014044 0ustar liggesusers A Common Database Interface (DBI)

A Common Database Interface (DBI)

R-Databases Special Interest Group

16 June 2003

This document describes a common interface between the S language (in its R and S-Plus implementations) and database management systems (DBMS). The interface defines a small set of classes and methods similar in spirit to Perl’s DBI, Java’s JDBC, Python’s DB-API, and Microsoft’s ODBC.

Version

This document describes version 0.1-6 of the database interface API (application programming interface).

Introduction

The database interface (DBI) separates the connectivity to the DBMS into a “front-end” and a “back-end”. Applications use only the exposed “front-end” API. The facilities that communicate with specific DBMS (Oracle, PostgreSQL, etc.) are provided by “device drivers” that get invoked automatically by the S language evaluator. The following example illustrates some of the DBI capabilities:

## Choose the proper DBMS driver and connect to the server

drv <- dbDriver("ODBC")
con <- dbConnect(drv, "dsn", "usr", "pwd")

## The interface can work at a higher level importing tables
## as data.frames and exporting data.frames as DBMS tables.

dbListTables(con)
dbListFields(con, "quakes")
if(dbExistsTable(con, "new_results"))
   dbRemoveTable(con, "new_results")
dbWriteTable(con, "new_results", new.output)

## The interface allows lower-level interface to the DBMS
res <- dbSendQuery(con, paste(
            "SELECT g.id, g.mirror, g.diam, e.voltage",
            "FROM geom_table as g, elec_measures as e",
            "WHERE g.id = e.id and g.mirrortype = 'inside'",
            "ORDER BY g.diam"))
out <- NULL
while(!dbHasCompleted(res)){
   chunk <- fetch(res, n = 10000)
   out <- c(out, doit(chunk))
}

## Free up resources
dbClearResult(res)
dbDisconnect(con)
dbUnloadDriver(drv)

(only the first 2 expressions are DBMS-specific – all others are independent of the database engine itself).

Individual DBI drivers need not implement all the features we list below (we indicate those that are optional). Furthermore, drivers may extend the core DBI facilities, but we suggest to have these extensions clearly indicated and documented.

The following are the elements of the DBI:

  1. A set of classes and methods (Section [sec:DBIClasses]) that defines what operations are possible and how they are defined, e.g.:

    • connect/disconnect to the DBMS

    • create and execute statements in the DBMS

    • extract results/output from statements

    • error/exception handling

    • information (meta-data) from database objects

    • transaction management (optional)

    Some things are left explicitly unspecified, e.g., authentication and even the query language, although it is hard to avoid references to SQL and relational database management systems (RDBMS).

  2. Drivers

    Drivers are collection of functions that implement the functionality defined above in the context of specific DBMS, e.g., mSQL, Informix.

  3. Data type mappings (Section [sec:data-mappings].)

    Mappings and conversions between DBMS data types and R/S objects. All drivers should implement the “basic” primitives (see below), but may chose to add user-defined conversion function to handle more generic objects (e.g., factors, ordered factors, time series, arrays, images).

  4. Utilities (Section [sec:utilities].)

    These facilities help with details such as mapping of identifiers between S and DBMS (e.g., _ is illegal in R/S names, and . is used for constructing compound SQL identifiers), etc.

DBI Classes and Methods

The following are the main DBI classes. They need to be extended by individual database back-ends (Sybase, Oracle, etc.) Individual drivers need to provide methods for the generic functions listed here (those methods that are optional are so indicated).

Note: Although R releases prior to 1.4 do not have a formal concept of classes, we will use the syntax of the S Version 4 classes and methods (available in R releases 1.4 and later as library methods) to convey precisely the DBI class hierarchy, its methods, and intended behavior.

The DBI classes are DBIObject, DBIDriver, DBIConnection and DBIResult. All these are virtual classes. Drivers define new classes that extend these, e.g., PgSQLDriver, PgSQLConnection, and so on.

Class hierarchy for the DBI. The top two layers are comprised of virtual classes and each lower layer represents a set of driver-specific implementation classes that provide the functionality defined by the virtual classes above.
Class hierarchy for the DBI. The top two layers are comprised of virtual classes and each lower layer represents a set of driver-specific implementation classes that provide the functionality defined by the virtual classes above.
DBIObject:

Virtual class1 that groups all other DBI classes.

DBIDriver:

Virtual class that groups all DBMS drivers. Each DBMS driver extends this class. Typically generator functions instantiate the actual driver objects, e.g., PgSQL, HDF5, BerkeleyDB.

DBIConnection:

Virtual class that encapsulates connections to DBMS.

DBIResult:

Virtual class that describes the result of a DBMS query or statement.

[Q: Should we distinguish between a simple result of DBMS statements e.g., as delete from DBMS queries (i.e., those that generate data).]

The methods format, print, show, dbGetInfo, and summary are defined (and implemented in the DBI package) for the DBIObject base class, thus available to all implementations; individual drivers, however, are free to override them as they see fit.

format(x, ...):

produces a concise character representation (label) for the DBIObject x.

print(x, ...)/show(x):

prints a one-line identification of the object x.

summary(object, ...):

produces a concise description of the object. The default method for DBIObject simply invokes dbGetInfo(dbObj) and prints the name-value pairs one per line. Individual implementations may tailor this appropriately.

dbGetInfo(dbObj, ...):

extracts information (meta-data) relevant for the DBIObject dbObj. It may return a list of key/value pairs, individual meta-data if supplied in the call, or NULL if the requested meta-data is not available.

Hint: Driver implementations may choose to allow an argument what to specify individual meta-data, e.g., dbGetInfo(drv, what = max.connections).

In the next few sub-sections we describe in detail each of these classes and their methods.

Class DBIObject

This class simply groups all DBI classes, and thus all extend it.

Class DBIDriver

This class identifies the database management system. It needs to be extended by individual back-ends (Oracle, PostgreSQL, etc.)

The DBI provides the generator dbDriver(driverName) which simply invokes the function driverName, which in turn instantiates the corresponding driver object.

The DBIDriver class defines the following methods:

driverName:

[meth:driverName] initializes the driver code. The name driverName refers to the actual generator function for the DBMS, e.g., RPgSQL, RODBC, HDF5. The driver instance object is used with dbConnect (see page ) for opening one or possibly more connections to one or more DBMS.

dbListConnections(drv, ...):

list of current connections being handled by the drv driver. May be NULL if there are no open connections. Drivers that do not support multiple connections may return the one open connection.

dbGetInfo(dbObj, ...):

returns a list of name-value pairs of information about the driver.

Hint: Useful entries could include

name:

the driver name (e.g., RODBC, RPgSQL);

driver.version:

version of the driver;

DBI.version:

the version of the DBI that the driver implements, e.g., 0.1-2;

client.version:

of the client DBMS libraries (e.g., version of the libpq library in the case of RPgSQL);

max.connections:

maximum number of simultaneous connections;

plus any other relevant information about the implementation, for instance, how the driver handles upper/lower case in identifiers.

dbUnloadDriver(driverName) (optional):

frees all resources (local and remote) used by the driver. Returns a logical to indicate if it succeeded or not.

Class DBIConnection

This virtual class encapsulates the connection to a DBMS, and it provides access to dynamic queries, result sets, DBMS session management (transactions), etc.

Note: Individual drivers are free to implement single or multiple simultaneous connections.

The methods defined by the DBIConnection class include:

dbConnect(drv, ...):

[meth:dbConnect] creates and opens a connection to the database implemented by the driver drv (see Section [sec:DBIDriver]). Each driver will define what other arguments are required, e.g., dbname or dsn for the database name, user, and password. It returns an object that extends DBIConnection in a driver-specific manner (e.g., the MySQL implementation could create an object of class MySQLConnection that extends DBIConnection).

dbDisconnect(conn, ...):

closes the connection, discards all pending work, and frees resources (e.g., memory, sockets). Returns a logical indicating whether it succeeded or not.

dbSendQuery(conn, statement, ...):

submits one statement to the DBMS. It returns a DBIResult object. This object is needed for fetching data in case the statement generates output (see fetch on page ), and it may be used for querying the state of the operation; see dbGetInfo and other meta-data methods on page .

dbGetQuery(conn, statement, ...):

submit, execute, and extract output in one operation. The resulting object may be a data.frame if the statement generates output. Otherwise the return value should be a logical indicating whether the query succeeded or not.

dbGetException(conn, ...):

returns a list with elements errNum and errMsg with the status of the last DBMS statement sent on a given connection (this information may also be provided by the dbGetInfo meta-data function on the conn object.

Hint: The ANSI SQL-92 defines both a status code and an status message that could be return as members of the list.

dbGetInfo(dbObj, ...):

returns a list of name-value pairs describing the state of the connection; it may return one or more meta-data, the actual driver method allows to specify individual pieces of meta-data (e.g., maximum number of open results/cursors).

Hint: Useful entries could include

dbname:

the name of the database in use;

db.version:

the DBMS server version (e.g., “Oracle 8.1.7 on Solaris”;

host:

host where the database server resides;

user:

user name;

password:

password (is this safe?);

plus any other arguments related to the connection (e.g., thread id, socket or TCP connection type).

dbListResults(conn, ...):

list of DBIResult objects currently active on the connection conn. May be NULL if no result set is active on conn. Drivers that implement only one result set per connection could return that one object (no need to wrap it in a list).

Note: The following are convenience methods that simplify the import/export of (mainly) data.frames. The first five methods implement the core methods needed to attach remote DBMS to the S search path. (For details, see Chambers (1991, 1998).)

Hint: For relational DBMS these methods may be easily implemented using the core DBI methods dbConnect, dbSendQuery, and fetch, due to SQL reflectance (i.e., one easily gets this meta-data by querying the appropriate tables on the RDBMS).

dbListTables(conn, ...):

returns a character vector (possibly of zero-length) of object (table) names available on the conn connection.

dbReadTable(conn, name, ...):

imports the data stored remotely in the table name on connection conn. Use the field row.names as the row.names attribute of the output data.frame. Returns a data.frame.

[Q: should we spell out how row.names should be created? E.g., use a field (with unique values) as row.names? Also, should dbReadTable reproduce a data.frame exported with dbWriteTable?]

dbWriteTable(conn, name, value, ...):

write the object value (perhaps after coercing it to data.frame) into the remote object name in connection conn. Returns a logical indicating whether the operation succeeded or not.

dbExistsTable(conn, name, ...):

does remote object name exist on conn? Returns a logical.

dbRemoveTable(conn, name, ...):

removes remote object name on connection conn. Returns a logical indicating whether the operation succeeded or not.

dbListFields(conn, name, ...):

returns a character vector listing the field names of the remote table name on connection conn (see dbColumnInfo() for extracting data type on a table).

Note: The following methods deal with transactions and stored procedures. All these functions are optional.

dbCommit(conn, ...)(optional):

commits pending transaction on the connection and returns TRUE or FALSE depending on whether the operation succeeded or not.

dbRollback(conn, ...)(optional):

undoes current transaction on the connection and returns TRUE or FALSE depending on whether the operation succeeded or not.

dbCallProc(conn, storedProc, ...)(optional):

invokes a stored procedure in the DBMS and returns a DBIResult object.

[Stored procedures are not part of the ANSI SQL-92 standard and vary substantially from one RDBMS to another.]

Deprecated since 2014:

The recommended way of calling a stored procedure is now

  • dbGetQuery if a result set is returned and
  • dbExecute for data manipulation and other cases that do not return a result set.

Class DBIResult

This virtual class describes the result and state of execution of a DBMS statement (any statement, query or non-query). The result set res keeps track of whether the statement produces output for R/S, how many rows were affected by the operation, how many rows have been fetched (if statement is a query), whether there are more rows to fetch, etc.

Note: Individual drivers are free to allow single or multiple active results per connection.

[Q: Should we distinguish between results that return no data from those that return data?]

The class DBIResult defines the following methods:

fetch(res, n, ...):

[meth:fetch] fetches the next n elements (rows) from the result set res and return them as a data.frame. A value of n=-1 is interpreted as “return all elements/rows”.

dbClearResult(res, ...):

flushes any pending data and frees all resources (local and remote) used by the object res on both sides of the connection. Returns a logical indicating success or not.

dbGetInfo(dbObj, ...):

returns a name-value list with the state of the result set.

Hint: Useful entries could include

statement:

a character string representation of the statement being executed;

rows.affected:

number of affected records (changed, deleted, inserted, or extracted);

row.count:

number of rows fetched so far;

has.completed:

has the statement (query) finished?

is.select:

a logical describing whether or not the statement generates output;

plus any other relevant driver-specific meta-data.

dbColumnInfo(res, ...):

produces a data.frame that describes the output of a query. The data.frame should have as many rows as there are output fields in the result set, and each column in the data.frame should describe an aspect of the result set field (field name, type, etc.)

Hint: The data.frame columns could include

field.name:

DBMS field label;

field.type:

DBMS field type (implementation-specific);

data.type:

corresponding R/S data type, e.g., integer;

precision/scale:

(as in ODBC terminology), display width and number of decimal digits, respectively;

nullable:

whether the corresponding field may contain (DBMS) NULL values;

plus other driver-specific information.

dbSetDataMappings(flds, ...)(optional):

defines a conversion between internal DBMS data types and R/S classes. We expect the default mappings (see Section [sec:data-mappings]) to be by far the most common ones, but users that need more control may specify a class generator for individual fields in the result set. [This topic needs further discussion.]

Note: The following are convenience methods that extract information from the result object (they may be implemented by invoking dbGetInfo with appropriate arguments).

dbGetStatement(res, ...)(optional):

returns the DBMS statement (as a character string) associated with the result res.

dbGetRowsAffected(res, ...)(optional):

returns the number of rows affected by the executed statement (number of records deleted, modified, extracted, etc.)

dbHasCompleted(res, ...)(optional):

returns a logical that indicates whether the operation has been completed (e.g., are there more records to be fetched?).

dbGetRowCount(res, ...)(optional):

returns the number of rows fetched so far.

Data Type Mappings

The data types supported by databases are different than the data types in R and S, but the mapping between the “primitive” types is straightforward: Any of the many fixed and varying length character types are mapped to R/S character. Fixed-precision (non-IEEE) numbers are mapped into either doubles (numeric) or long (integer). Notice that many DBMS do not follow the so-called IEEE arithmetic, so there are potential problems with under/overflows and loss of precision, but given the R/S primitive types we cannot do too much but identify these situations and warn the application (how?).

By default dates and date-time objects are mapped to character using the appropriate TO_CHAR function in the DBMS (which should take care of any locale information). Some RDBMS support the type CURRENCY or MONEY which should be mapped to numeric (again with potential round off errors). Large objects (character, binary, file, etc.) also need to be mapped. User-defined functions may be specified to do the actual conversion (as has been done in other inter-systems packages 2).

Specifying user-defined conversion functions still needs to be defined.

Utilities

The core DBI implementation should make available to all drivers some common basic utilities. For instance:

dbGetDBIVersion:

returns the version of the currently attached DBI as a string.

dbDataType(dbObj, obj, ...):

returns a string with the (approximately) appropriate data type for the R/S object obj. The DBI can implement this following the ANSI-92 standard, but individual drivers may want/need to extend it to make use of DBMS-specific types.

make.db.names(dbObj, snames, ...):

maps R/S names (identifiers) to SQL identifiers replacing illegal characters (as .) by the legal SQL _.

SQLKeywords(dbObj, ...):

returns a character vector of SQL keywords (reserved words). The default method returns the list of .SQL92Keywords, but drivers should update this vector with the DBMS-specific additional reserved words.

isSQLKeyword(dbObj, name, ...):

for each element in the character vector name determine whether or not it is an SQL keyword, as reported by the generic function SQLKeywords. Returns a logical vector parallel to the input object name.

Open Issues and Limitations

There are a number of issues and limitations that the current DBI conscientiously does not address on the interest of simplicity. We do list here the most important ones.

Non-SQL:

Is it realistic to attempt to encompass non-relational databases, like HDF5, Berkeley DB, etc.?

Security:

allowing users to specify their passwords on R/S scripts may be unacceptable for some applications. We need to consider alternatives where users could store authentication on files (perhaps similar to ODBC’s odbc.ini) with more stringent permissions.

Exceptions:

the exception mechanism is a bit too simple, and it does not provide for information when problems stem from the DBMS interface itself. For instance, under/overflow or loss of precision as we move numeric data from DBMS to the more limited primitives in R/S.

Asynchronous communication:

most DBMS support both synchronous and asynchronous communications, allowing applications to submit a query and proceed while the database server process the query. The application is then notified (or it may need to poll the server) when the query has completed. For large computations, this could be very useful, but the DBI would need to specify how to interrupt the server (if necessary) plus other details. Also, some DBMS require applications to use threads to implement asynchronous communication, something that neither R nor S-Plus currently addresses.

SQL scripts:

the DBI only defines how to execute one SQL statement at a time, forcing users to split SQL scripts into individual statements. We need a mechanism by which users can submit SQL scripts that could possibly generate multiple result sets; in this case we may need to introduce new methods to loop over multiple results (similar to Python’s nextResultSet).

BLOBS/CLOBS:

large objects (both character and binary) present some challenges both to R and S-Plus. It is becoming more common to store images, sounds, and other data types as binary objects in DBMS, some of which can be in principle quite large. The SQL-92 ANSI standard allows up to 2 gigabytes for some of these objects. We need to carefully plan how to deal with binary objects.

Transactions:

transaction management is not fully described.

Additional methods:

Do we need any additional methods? (e.g., dbListDatabases(conn), dbListTableIndices(conn, name), how do we list all available drivers?)

Bind variables:

the interface is heavily biased towards queries, as opposed to general purpose database development. In particular we made no attempt to define “bind variables”; this is a mechanism by which the contents of R/S objects are implicitly moved to the database during SQL execution. For instance, the following embedded SQL statement

  /* SQL */
  SELECT * from emp_table where emp_id = :sampleEmployee

would take the vector sampleEmployee and iterate over each of its elements to get the result. Perhaps the DBI could at some point in the future implement this feature.

Resources

The idea of a common interface to databases has been successfully implemented in various environments, for instance:

Java’s Database Connectivity (JDBC) (www.javasoft.com).

In C through the Open Database Connectivity (ODBC) (www.unixodbc.org).

Python’s Database Application Programming Interface (www.python.org).

Perl’s Database Interface (dbi.perl.org).

Chambers, John M. 1991. “Data Management in S.” Bell Labs, Lucent Technologies.
———. 1998. “Database Classes.” Bell Labs, Lucent Technologies.

  1. A virtual class allows us to group classes that share some common characteristics, even if their implementations are radically different.↩︎

  2. Duncan Temple Lang has volunteered to port the data conversion code found in R-Java, R-Perl, and R-Python packages to the DBI↩︎

DBI/inst/doc/DBI-proposal.Rmd0000644000176200001440000006640614602466070015312 0ustar liggesusers--- title: "A Common Interface to Relational Databases from R and S -- A Proposal" author: "David James" date: "March 16, 2000" output: rmarkdown::html_vignette bibliography: biblio.bib vignette: > %\VignetteIndexEntry{A Common Interface to Relational Databases from R and S -- A Proposal} %\VignetteEngine{knitr::rmarkdown} --- For too long S and similar data analysis environments have lacked good interfaces to relational database systems (RDBMS). For the last twenty years or so these RDBMS have evolved into highly optimized client-server systems for data storage and manipulation, and currently they serve as repositories for most of the business, industrial, and research “raw” data that analysts work with. Other analysis packages, such as SAS, have traditionally provided good data connectivity, but S and GNU R have relied on intermediate text files as means of importing data (but see @R.imp-exp and @R-dbms.) Although this simple approach works well for relatively modest amounts of mostly static data, it does not scale up to larger amounts of data distributed over machines and locations, nor does it scale up to data that is highly dynamic – situations that are becoming increasingly common. We want to propose a common interface between R/S and RDBMS that would allow users to access data stored on database servers in a uniform and predictable manner irrespective of the database engine. The interface defines a small set of classes and methods similar in spirit to Python’s DB-API, Java’s JDBC, Microsoft’s ODBC, Perl’s DBI, etc., but it conforms to the “whole-object” philosophy so natural in S and R. # Computing with Distributed Data {#sec:distr} As data analysts, we are increasingly faced with the challenge of larger data sources distributed over machines and locations; most of these data sources reside in relational database management systems (RDBMS). These relational databases represent a mature client-server distributed technology that we as analysts could be exploiting more that we’ve done in the past. The relational technology provides a well-defined standard, the ANSI SQL-92 @sql92, both for defining and manipulating data in a highly optimized fashion from virtually any application. In contrast, S and Splus have provided somewhat limited tools for coping with the challenges of larger and distributed data sets (Splus does provide an `import` function to import from databases, but it is quite limited in terms of SQL facilities). The R community has been more resourceful and has developed a number of good libraries for connecting to mSQL, MySQL, PostgreSQL, and ODBC; each library, however, has defined its own interface to each database engine a bit differently. We think it would be to everybody’s advantage to coordinate the definition of a common interface, an effort not unlike those taken in the Python and Perl communities. The goal of a common, seamless access to distributed data is a modest one in our evolution towards a fully distributed computing environment. We recognize the greater goal of distributed computing as the means to fully integrate diverse systems – not just databases – into a truly flexible analysis environment. Good connectivity to databases, however, is of immediate necessity both in practical terms and as a means to help us transition from monolithic, self-contained systems to those in which computations, not only the data, can be carried out in parallel over a wide number of computers and/or systems @duncan2000. Issues of reliability, security, location transparency, persistence, etc., will be new to most of us and working with distributed data may provide a more gradual change to ease in the ultimate goal of full distributed computing. # A Common Interface {#sec:rs-dbi} We believe that a common interface to databases can help users easily access data stored in RDBMS. A common interface would describe, in a uniform way, how to connect to RDBMS, extract meta-data (such as list of available databases, tables, etc.) as well as a uniform way to execute SQL statements and import their output into R and S. The current emphasis is on querying databases and not so much in a full low-level interface for database development as in JDBC or ODBC, but unlike these, we want to approach the interface from the “whole-object” perspective @S4 so natural to R/S and Python – for instance, by fetching all fields and records simultaneously into a single object. The basic idea is to split the interface into a front-end consisting of a few classes and generic functions that users invoke and a back-end set of database-specific classes and methods that implement the actual communication. (This is a very well-known pattern in software engineering, and another good verbatim is the device-independent graphics in R/S where graphics functions produce similar output on a variety of different devices, such X displays, Postscript, etc.) The following verbatim shows the front-end: ``` > mgr <- dbManager("Oracle") > con <- dbConnect(mgr, user = "user", passwd = "passwd") > rs <- dbExecStatement(con, "select fld1, fld2, fld3 from MY_TABLE") > tbls <- fetch(rs, n = 100) > hasCompleted(rs) [1] T > close(rs) > rs <- dbExecStatement(con, "select id_name, q25, q50 from liv2") > res <- fetch(rs) > getRowCount(rs) [1] 73 > close(con) ``` Such scripts should work with other RDBMS (say, MySQL) by replacing the first line with ``` > mgr <- dbManager("MySQL") ``` ## Interface Classes {#sec:rs-dbi-classes} The following are the main RS-DBI classes. They need to be extended by individual database back-ends (MySQL, Oracle, etc.) `dbManager` : Virtual class[^2] extended by actual database managers, e.g., Oracle, MySQL, Informix. `dbConnection` : Virtual class that captures a connection to a database instance[^3]. `dbResult` : Virtual class that describes the result of an SQL statement. `dbResultSet` : Virtual class, extends `dbResult` to fully describe the output of those statements that produce output records, i.e., `SELECT` (or `SELECT`-like) SQL statement. All these classes should implement the methods `show`, `describe`, and `getInfo`: `show` : (`print` in R) prints a one-line identification of the object. `describe` : prints a short summary of the meta-data of the specified object (like `summary` in R/S). `getInfo` : takes an object of one of the above classes and a string specifying a meta-data item, and it returns the corresponding information (`NULL` if unavailable). > mgr <- dbManager("MySQL") > getInfo(mgr, "version") > con <- dbConnect(mgr, ...) > getInfo(con, "type") The reason we implement the meta-data through `getInfo` in this way is to simplify the writing of database back-ends. We don’t want to overwhelm the developers of drivers (ourselves, most likely) with hundreds of methods as in the case of JDBC. In addition, the following methods should also be implemented: `getDatabases` : lists all available databases known to the `dbManager`. `getTables` : lists tables in a database. `getTableFields` : lists the fields in a table in a database. `getTableIndices` : lists the indices defined for a table in a database. These methods may be implemented using the appropriate `getInfo` method above. In the next few sections we describe in detail each of these classes and their methods. ### Class `dbManager` {#sec:dbManager} This class identifies the relational database management system. It needs to be extended by individual back-ends (Oracle, PostgreSQL, etc.) The `dbManager` class defines the following methods: `load` : initializes the driver code. We suggest having the generator, `dbManager(driver)`, automatically load the driver. `unload` : releases whatever resources the driver is using. `getVersion` : returns the version of the RS-DBI currently implemented, plus any other relevant information about the implementation itself and the RDBMS being used. ### Class `dbConnection` {#sec:dbConnection} This virtual class captures a connection to a RDBMS, and it provides access to dynamic SQL, result sets, RDBMS session management (transactions), etc. Note that the `dbManager` may or may not allow multiple simultaneous connections. The methods it defines include: `dbConnect` : opens a connection to the database `dbname`. Other likely arguments include `host`, `user`, and `password`. It returns an object that extends `dbConnection` in a driver-specific manner (e.g., the MySQL implementation creates a connection of class `MySQLConnection` that extends `dbConnection`). Note that we could separate the steps of connecting to a RDBMS and opening a database there (i.e., opening an *instance*). For simplicity we do the 2 steps in this method. If the user needs to open another instance in the same RDBMS, just open a new connection. `close` : closes the connection and discards all pending work. `dbExecStatement` : submits one SQL statement. It returns a `dbResult` object, and in the case of a `SELECT` statement, the object also inherits from `dbResultSet`. This `dbResultSet` object is needed for fetching the output rows of `SELECT` statements. The result of a non-`SELECT` statement (e.g., `UPDATE, DELETE, CREATE, ALTER`, ...) is defined as the number of rows affected (this seems to be common among RDBMS). `commit` : commits pending transaction (optional). `rollback` : undoes current transaction (optional). `callProc` : invokes a stored procedure in the RDBMS (tentative). Stored procedures are *not* part of the ANSI SQL-92 standard and possibly vary substantially from one RDBMS to another. For instance, Oracle seems to have a fairly decent implementation of stored procedures, but MySQL currently does not support them. `dbExec` : submit an SQL “script” (multiple statements). May be implemented by looping with `dbExecStatement`. `dbNextResultSet` : When running SQL scripts (multiple statements), it closes the current result set in the `dbConnection`, executes the next statement and returns its result set. ### Class `dbResult` {#sec:dbResult} This virtual class describes the result of an SQL statement (any statement) and the state of the operation. Non-query statements (e.g., `CREATE`, `UPDATE`, `DELETE`) set the “completed” state to 1, while `SELECT` statements to 0. Error conditions set this slot to a negative number. The `dbResult` class defines the following methods: `getStatement` : returns the SQL statement associated with the result set. `getDBConnection` : returns the `dbConnection` associated with the result set. `getRowsAffected` : returns the number of rows affected by the operation. `hasCompleted` : was the operation completed? `SELECT`’s, for instance, are not completed until their output rows are all fetched. `getException` : returns the status of the last SQL statement on a given connection as a list with two members, status code and status description. ### Class `dbResultSet` {#sec:dbResultSet} This virtual class extends `dbResult`, and it describes additional information from the result of a `SELECT` statement and the state of the operation. The `completed` state is set to 0 so long as there are pending rows to fetch. The `dbResultSet` class defines the following additional methods: `getRowCount` : returns the number of rows fetched so far. `getNullOk` : returns a logical vector with as many elements as there are fields in the result set, each element describing whether the corresponding field accepts `NULL` values. `getFields` : describes the `SELECT`ed fields. The description includes field names, RDBMS internal data types, internal length, internal precision and scale, null flag (i.e., column allows `NULL`’s), and corresponding S classes (which can be over-ridden with user-provided classes). The current MySQL and Oracle implementations define a `dbResultSet` as a named list with the following elements: `connection`: : the connection object associated with this result set; `statement`: : a string with the SQL statement being processed; `description`: : a field description `data.frame` with as many rows as there are fields in the `SELECT` output, and columns specifying the `name`, `type`, `length`, `precision`, `scale`, `Sclass` of the corresponding output field. `rowsAffected`: : the number of rows that were affected; `rowCount`: : the number of rows so far fetched; `completed`: : a logical value describing whether the operation has completed or not. `nullOk`: : a logical vector specifying whether the corresponding column may take NULL values. The methods above are implemented as accessor functions to this list in the obvious way. `setDataMappings` : defines a conversion between internal RDBMS data types and R/S classes. We expect the default mappings to be by far the most common ones, but users that need more control may specify a class generator for individual fields in the result set. (See Section [sec:mappings] for details.) `close` : closes the result set and frees resources both in R/S and the RDBMS. `fetch` : extracts the next `max.rec` records (-1 means all). ## Data Type Mappings {#sec:mappings} The data types supported by databases are slightly different than the data types in R and S, but the mapping between them is straightforward: Any of the many fixed and varying length character types are mapped to R/S `character`. Fixed-precision (non-IEEE) numbers are mapped into either doubles (`numeric`) or long (`integer`). Dates are mapped to character using the appropriate `TO_CHAR` function in the RDBMS (which should take care of any locale information). Some RDBMS support the type `CURRENCY` or `MONEY` which should be mapped to `numeric`. Large objects (character, binary, file, etc.) also need to be mapped. User-defined functions may be specified to do the actual conversion as follows: 1. run the query (either with `dbExec` or `dbExecStatement`): > rs <- dbExecStatement(con, "select whatever-You-need") 2. extract the output field definitions > flds <- getFields(rs) 3. replace the class generator in the, say 3rd field, by the user own generator: > flds[3, "Sclass"] # default mapping [1] "character" by > flds[3, "Sclass"] <- "myOwnGeneratorFunction" 4. set the new data mapping prior to fetching > setDataMappings(resutlSet, flds) 5. fetch the rows and store in a `data.frame` > data <- fetch(resultSet) ## Open Issues {#sec:open-issues} We may need to provide some additional utilities, for instance to convert dates, to escape characters such as quotes and slashes in query strings, to strip excessive blanks from some character fields, etc. We need to decide whether we provide hooks so these conversions are done at the C level, or do all the post-processing in R or S. Another issue is what kind of data object is the output of an SQL query. Currently the MySQL and Oracle implementations return data as a `data.frame`; data frames have the slight inconvenience that they automatically re-label the fields according to R/S syntax, changing the actual RDBMS labels of the variables; the issue of non-numeric data being coerced into factors automatically “at the drop of a hat” (as someone in s-news wrote) is also annoying. The execution of SQL scripts is not fully described. The method that executes scripts could run individual statements without returning until it encounters a query (`SELECT`-like) statement. At that point it could return that one result set. The application is then responsible for fetching these rows, and then for invoking `dbNextResultSet` on the opened `dbConnection` object to repeat the `dbExec`/`fetch` loop until it encounters the next `dbResultSet`. And so on. Another (potentially very expensive) alternative would be to run all statements sequentially and return a list of `data.frame`s, each element of the list storing the result of each statement. Binary objects and large objects present some challenges both to R and S. It is becoming more common to store images, sounds, and other data types as binary objects in RDBMS, some of which can be in principle quite large. The SQL-92 ANSI standard allows up to 2 gigabytes for some of these objects. We need to carefully plan how to deal with binary objects – perhaps tentatively not in full generality. Large objects could be fetched by repeatedly invoking a specified R/S function that takes as argument chunks of a specified number of raw bytes. In the case of S4 (and Splus5.x) the RS-DBI implementation can write into an opened connection for which the user has defined a reader (but can we guarantee that we won’t overflow the connection?). In the case of R it is not clear what data type binary large objects (BLOB) should be mapped into. ## Limitations {#sec:limitations} These are some of the limitations of the current interface definition: - we only allow one SQL statement at a time, forcing users to split SQL scripts into individual statements; - transaction management is not fully described; - the interface is heavily biased towards queries, as opposed to general purpose database development. In particular we made no attempt to define “bind variables”; this is a mechanism by which the contents of S objects are implicitly moved to the database during SQL execution. For instance, the following embedded SQL statement /* SQL */ SELECT * from emp_table where emp_id = :sampleEmployee would take the vector `sampleEmployee` and iterate over each of its elements to get the result. Perhaps RS-DBI could at some point in the future implement this feature. # Other Approaches The high-level, front-end description of RS-DBI is the more critical aspect of the interface. Details on how to actually implement this interface may change over time. The approach described in this document based on one back-end driver per RDBMS is reasonable, but not the only approach – we simply felt that a simpler approach based on well-understood and self-contained tools (R, S, and C API’s) would be a better start. Nevertheless we want to briefly mention a few alternatives that we considered and tentatively decided against, but may quite possibly re-visit in the near future. ## Open Database Connectivity (ODBC) {#sec:odbc} The ODBC protocol was developed by Microsoft to allow connectivity among C/C++ applications and RDBMS. As you would expect, originally implementations of the ODBC were only available under Windows environments. There are various effort to create a Unix implementation (see [the Unix ODBC](https://www.unixodbc.org/) web-site and @odbc.lj). This approach looks promising because it allows us to write only one back-end, instead of one per RDBMS. Since most RDBMS already provide ODBC drivers, this could greatly simplify development. Unfortunately, the Unix implementation of ODBC was not mature enough at the time we looked at it, a situation we expect will change in the next year or so. At that point we will need to re-evaluate it to make sure that such an ODBC interface does not penalize the interface in terms of performance, ease of use, portability among the various Unix versions, etc. ## Java Database Connectivity (JDBC) {#sec:jdbc} Another protocol, the Java database connectivity, is very well-done and supported by just about every RDBMS. The issue with JDBC is that as of today neither S nor R (which are written in C) interfaces cleanly with Java. There are several efforts (some in a quite fairly advanced state) to allow S and R to invoke Java methods. Once this interface is widely available in Splus5x and R we will need to re-visit this issue again and study the performance, usability, etc., of JDBC as a common back-end to the RS-DBI. ## CORBA and a 3-tier Architecture {#sec:corba} Yet another approach is to move the interface to RDBMS out of R and S altogether into a separate system or server that would serve as a proxy between R/S and databases. The communication to this middle-layer proxy could be done through CORBA [@s-corba.98, @corba:siegel.96], Java’s RMI, or some other similar technology. Such a design could be very flexible, but the CORBA facilities both in R and S are not widely available yet, and we do not know whether this will be made available to Splus5 users from MathSoft. Also, my experience with this technology is rather limited. On the other hand, this 3-tier architecture seem to offer the most flexibility to cope with very large distributed databases, not necessarily relational. # Resources {#sec:resources} The latest documentation and software on the RS-DBI was available at www.omegahat.net (link dead now: `https://www.omegahat.net/contrib/RS-DBI/index.html`). The R community has developed interfaces to some databases: [RmSQL](https://cran.r-project.org/src/contrib/Archive/RmSQL/) is an interface to the [mSQL](https://www.hughes.com.au/) database written by Torsten Hothorn; [RPgSQL](https://sites.cns.utexas.edu/keittlab/software-0) is an interface to [PostgreSQL](https://www.postgreSQL.org) and was written by Timothy H. Keitt; [RODBC](https://www.stats.ox.ac.uk/pub/bdr/) is an interface to ODBC, and it was written by [Michael Lapsley](mailto:mlapsley@sthelier.sghms.ac.uk). (For more details on all these see @R.imp-exp.) The are R and S-Plus interfaces to [MySQL](https://dev.mysql.com/) that follow the propose RS-DBI API described here; also, there’s an S-Plus interface SOracle @RS-Oracle to Oracle (we expect to have an R implementation soon.) The idea of a common interface to databases has been successfully implemented in Java’s Database Connectivity (JDBC) ([www.javasoft.com](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/)), in C through the Open Database Connectivity (ODBC) ([www.unixodbc.org](https://www.unixodbc.org/)), in Python’s Database Application Programming Interface ([www.python.org](https://www.python.org)), and in Perl’s Database Interface ([www.cpan.org](https://www.cpan.org)). # Acknowledgements The R/S database interface came about from suggestions, comments, and discussions with [John M. Chambers](mailto:jmc@research.bell-labs.com) and [Duncan Temple Lang](mailto:duncan@research.bell-labs.com) in the context of the Omega Project for Statistical Computing. [Doug Bates](mailto:bates@stat.wisc.edu) and [Saikat DebRoy](mailto:saikat@stat.wisc.edu) ported (and greatly improved) the first MySQL implementation to R. # The S Version 4 Definitions The following code is meant to serve as a detailed description of the R/S to database interface. We decided to use S4 (instead of R or S version 3) because its clean syntax help us to describe easily the classes and methods that form the RS-DBI, and also to convey the inter-class relationships. ```R ## Define all the classes and methods to be used by an ## implementation of the RS-DataBase Interface. Mostly, ## these classes are virtual and each driver should extend ## them to provide the actual implementation. ## Class: dbManager ## This class identifies the DataBase Management System ## (Oracle, MySQL, Informix, PostgreSQL, etc.) setClass("dbManager", VIRTUAL) setGeneric("load", def = function(dbMgr,...) standardGeneric("load") ) setGeneric("unload", def = function(dbMgr,...) standardGeneric("unload") ) setGeneric("getVersion", def = function(dbMgr,...) standardGeneric("getVersion") ) ## Class: dbConnections ## This class captures a connection to a database instance. setClass("dbConnection", VIRTUAL) setGeneric("dbConnection", def = function(dbMgr, ...) standardGeneric("dbConnection") ) setGeneric("dbConnect", def = function(dbMgr, ...) standardGeneric("dbConnect") ) setGeneric("dbExecStatement", def = function(con, statement, ...) standardGeneric("dbExecStatement") ) setGeneric("dbExec", def = function(con, statement, ...) standardGeneric("dbExec") ) setGeneric("getResultSet", def = function(con, ..) standardGeneric("getResultSet") ) setGeneric("commit", def = function(con, ...) standardGeneric("commit") ) setGeneric("rollback", def = function(con, ...) standardGeneric("rollback") ) setGeneric("callProc", def = function(con, ...) standardGeneric("callProc") ) setMethod("close", signature = list(con="dbConnection", type="missing"), def = function(con, type) NULL ) ## Class: dbResult ## This is a base class for arbitrary results from the RDBMS ## (INSERT, UPDATE, DELETE). SELECTs (and SELECT-like) ## statements produce "dbResultSet" objects, which extend ## dbResult. setClass("dbResult", VIRTUAL) setMethod("close", signature = list(con="dbResult", type="missing"), def = function(con, type) NULL ) ## Class: dbResultSet ## Note that we define a resultSet as the result of a ## SELECT SQL statement. setClass("dbResultSet", "dbResult") setGeneric("fetch", def = function(resultSet,n,...) standardGeneric("fetch") ) setGeneric("hasCompleted", def = function(object, ...) standardGeneric("hasCompleted") ) setGeneric("getException", def = function(object, ...) standardGeneric("getException") ) setGeneric("getDBconnection", def = function(object, ...) standardGeneric("getDBconnection") ) setGeneric("setDataMappings", def = function(resultSet, ...) standardGeneric("setDataMappings") ) setGeneric("getFields", def = function(object, table, dbname, ...) standardGeneric("getFields") ) setGeneric("getStatement", def = function(object, ...) standardGeneric("getStatement") ) setGeneric("getRowsAffected", def = function(object, ...) standardGeneric("getRowsAffected") ) setGeneric("getRowCount", def = function(object, ...) standardGeneric("getRowCount") ) setGeneric("getNullOk", def = function(object, ...) standardGeneric("getNullOk") ) ## Meta-data: setGeneric("getInfo", def = function(object, ...) standardGeneric("getInfo") ) setGeneric("describe", def = function(object, verbose=F, ...) standardGeneric("describe") ) setGeneric("getCurrentDatabase", def = function(object, ...) standardGeneric("getCurrentDatabase") ) setGeneric("getDatabases", def = function(object, ...) standardGeneric("getDatabases") ) setGeneric("getTables", def = function(object, dbname, ...) standardGeneric("getTables") ) setGeneric("getTableFields", def = function(object, table, dbname, ...) standardGeneric("getTableFields") ) setGeneric("getTableIndices", def = function(object, table, dbname, ...) standardGeneric("getTableIndices") ) ``` [^2]: A virtual class allows us to group classes that share some common functionality, e.g., the virtual class “`dbConnection`” groups all the connection implementations by Informix, Ingres, DB/2, Oracle, etc. Although the details will vary from one RDBMS to another, the defining characteristic of these objects is what a virtual class captures. R and S version 3 do not explicitly define virtual classes, but they can easily implement the idea through inheritance. [^3]: The term “database” is sometimes (confusingly) used both to denote the RDBMS, such as Oracle, MySQL, and also to denote a particular database instance under a RDBMS, such as “opto” or “sales” databases under the same RDBMS. DBI/inst/doc/DBI-arrow.Rmd0000644000176200001440000001517214602466070014577 0ustar liggesusers--- title: "Using DBI with Arrow" author: "Kirill Müller" date: "25/12/2023" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Using DBI with Arrow} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} library(knitr) opts_chunk$set(echo = TRUE) knitr::opts_chunk$set(error = Sys.getenv("IN_PKGDOWN") != "true" || (getRversion() < "3.5")) knit_print.data.frame <- function(x, ...) { print(head(x, 6)) if (nrow(x) > 6) { cat("Showing 6 out of", nrow(x), "rows.\n") } invisible(x) } registerS3method("knit_print", "data.frame", "knit_print.data.frame") ``` ## Who this tutorial is for This tutorial is for you if you want to leverage [Apache Arrow](https://arrow.apache.org/) for accessing and manipulating data on databases. See `vignette("DBI", package = "DBI")` and `vignette("DBI-advanced", package = "DBI")` for tutorials on accessing data using R's data frames instead of Arrow's structures. ## Rationale Apache Arrow is > a cross-language development platform for in-memory analytics, suitable for large and huge data, with support for out-of-memory operation. Arrow is also a data exchange format, the data types covered by Arrow align well with the data types supported by SQL databases. DBI 1.2.0 introduced support for Arrow as a format for exchanging data between R and databases. The aim is to: - accelerate data retrieval and loading, by using fewer costly data conversions; - better support reading and summarizing data from a database that is larger than memory; - provide better type fidelity with workflows centered around Arrow. This allows existing code to be used with Arrow, and it allows new code to be written that is more efficient and more flexible than code that uses R's data frames. The interface is built around the {nanoarrow} R package, with `nanoarrow::as_nanoarrow_array` and `nanoarrow::as_nanoarrow_array_stream` as fundamental data structures. ## New classes and generics DBI 1.2.0 introduces new classes and generics for working with Arrow data: - `dbReadTableArrow()` - `dbWriteTableArrow()` - `dbCreateTableArrow()` - `dbAppendTableArrow()` - `dbGetQueryArrow()` - `dbSendQueryArrow()` - `dbBindArrow()` - `dbFetchArrow()` - `dbFetchArrowChunk()` - `DBIResultArrow-class` - `DBIResultArrowDefault-class` Compatibility is important for DBI, and implementing new generics and classes greatly reduces the risk of breaking existing code. The DBI package comes with a fully functional fallback implementation for all existing DBI backends. The fallback is not improving performance, but it allows existing code to be used with Arrow before switching to a backend with native Arrow support. Backends with native support, like the [adbi](https://adbi.r-dbi.org/) package, implement the new generics and classes for direct support and improved performance. In the remainder of this tutorial, we will demonstrate the new generics and classes using the RSQLite package. SQLite is an in-memory database, this code does not need a database server to be installed and running. ## Prepare We start by setting up a database connection and creating a table with some data, using the original `dbWriteTable()` method. ```{r} library(DBI) con <- dbConnect(RSQLite::SQLite()) data <- data.frame( a = 1:3, b = 4.5, c = "five" ) dbWriteTable(con, "tbl", data) ``` ## Read all rows from a table The `dbReadTableArrow()` method reads all rows from a table into an Arrow stream, similarly to `dbReadTable()`. Arrow objects implement the `as.data.frame()` method, so we can convert the stream to a data frame. ```{r} stream <- dbReadTableArrow(con, "tbl") stream as.data.frame(stream) ``` ## Run queries The `dbGetQueryArrow()` method runs a query and returns the result as an Arrow stream. This stream can be turned into an `arrow::RecordBatchReader` object and processed further, without bringing it into R. ```{r} stream <- dbGetQueryArrow(con, "SELECT COUNT(*) AS n FROM tbl WHERE a < 3") stream path <- tempfile(fileext = ".parquet") arrow::write_parquet(arrow::as_record_batch_reader(stream), path) arrow::read_parquet(path) ``` ## Prepared queries The `dbGetQueryArrow()` method supports prepared queries, using the `params` argument which accepts a data frame or a list. ```{r} params <- data.frame(a = 3L) stream <- dbGetQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a", params = params) as.data.frame(stream) params <- data.frame(a = c(2L, 4L)) # Equivalent to dbBind() stream <- dbGetQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a", params = params) as.data.frame(stream) ``` ## Manual flow For the manual flow, use `dbSendQueryArrow()` to send a query to the database, and `dbFetchArrow()` to fetch the result. This also allows using the new `dbBindArrow()` method to bind data in Arrow format to a prepared query. Result objects must be cleared with `dbClearResult()`. ```{r} rs <- dbSendQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a") in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 1L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 2L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 3L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 1:4L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) dbClearResult(rs) ``` ## Writing data Streams returned by `dbGetQueryArrow()` and `dbReadTableArrow()` can be written to a table using `dbWriteTableArrow()`. ```{r} stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a < 3") dbWriteTableArrow(con, "tbl_new", stream) dbReadTable(con, "tbl_new") ``` ## Appending data For more control over the writing process, use `dbCreateTableArrow()` and `dbAppendTableArrow()`. ```{r} stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a < 3") dbCreateTableArrow(con, "tbl_split", stream) dbAppendTableArrow(con, "tbl_split", stream) stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a >= 3") dbAppendTableArrow(con, "tbl_split", stream) dbReadTable(con, "tbl_split") ``` ## Conclusion Do not forget to disconnect from the database when done. ```{r} dbDisconnect(con) ``` That concludes the major features of DBI's new Arrow interface. For more details on the library functions covered in this tutorial see the DBI specification at `vignette("spec", package = "DBI")`. See the [adbi](https://adbi.r-dbi.org/) package for a backend with native Arrow support, and [nanoarrow](https://github.com/apache/arrow-nanoarrow) and [arrow](https://arrow.apache.org/docs/r/) for packages to work with the Arrow format. DBI/inst/doc/backend.Rmd0000644000176200001440000002414014350241735014432 0ustar liggesusers --- title: "Implementing a new backend" author: "Hadley Wickham, Kirill Müller" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Implementing a new backend} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- ```{r, echo = FALSE} library(DBI) knitr::opts_chunk$set(collapse = TRUE, comment = "#>") ``` The goal of this document is to help you implement a new backend for DBI. If you are writing a package that connects a database to R, I highly recommend that you make it DBI compatible because it makes your life easier by spelling out exactly what you need to do. The consistent interface provided by DBI makes it easier for you to implement the package (because you have fewer arbitrary choices to make), and easier for your users (because it follows a familiar pattern). In addition, the `DBItest` package provides test cases which you can easily incorporate in your package. I'll illustrate the process using a fictional database called Kazam. ## Getting started Start by creating a package. It's up to you what to call the package, but following the existing pattern of `RSQLite`, `RMySQL`, `RPostgres` and `ROracle` will make it easier for people to find it. For this example, I'll call my package `RKazam`. A ready-to-use template package is available at https://github.com/r-dbi/RKazam/. You can start by creating a new GitHub repository from this template, or by copying the package code. Rename "Kazam" to your desired name everywhere. The template package already contains dummy implementations for all classes and methods. If you chose to create the package manually, make sure to include in your `DESCRIPTION`: ```yaml Imports: DBI (>= 0.3.0), methods Suggests: DBItest, testthat ``` Importing `DBI` is fine, because your users are not supposed to *attach* your package anyway; the preferred method is to attach `DBI` and use explicit qualification via `::` to access the driver in your package (which needs to be done only once). ## Testing Why testing at this early stage? Because testing should be an integral part of the software development cycle. Test right from the start, add automated tests as you go, finish faster (because tests are automated) while maintaining superb code quality (because tests also check corner cases that you might not be aware of). Don't worry: if some test cases are difficult or impossible to satisfy, or take too long to run, you can just turn them off. Take the time now to head over to the `DBItest` vignette at `vignette("test", package = "DBItest")`. You will find a vast amount of ready-to-use test cases that will help you in the process of implementing your new DBI backend. Add custom tests that are not covered by `DBItest` at your discretion, or enhance `DBItest` and file a pull request if the test is generic enough to be useful for many DBI backends. ## Driver Start by making a driver class which inherits from `DBIDriver`. This class doesn't need to do anything, it's just used to dispatch other generics to the right method. Users don't need to know about this, so you can remove it from the default help listing with `@keywords internal`: ```{r} #' Driver for Kazam database. #' #' @keywords internal #' @export #' @import DBI #' @import methods setClass("KazamDriver", contains = "DBIDriver") ``` The driver class was more important in older versions of DBI, so you should also provide a dummy `dbUnloadDriver()` method. ```{r} #' @export #' @rdname Kazam-class setMethod("dbUnloadDriver", "KazamDriver", function(drv, ...) { TRUE }) ``` If your package needs global setup or tear down, do this in the `.onLoad()` and `.onUnload()` functions. You might also want to add a show method so the object prints nicely: ```{r} setMethod("show", "KazamDriver", function(object) { cat("\n") }) ``` Next create `Kazam()` which instantiates this class. ```{r} #' @export Kazam <- function() { new("KazamDriver") } Kazam() ``` ## Connection Next create a connection class that inherits from `DBIConnection`. This should store all the information needed to connect to the database. If you're talking to a C api, this will include a slot that holds an external pointer. ```{r} #' Kazam connection class. #' #' @export #' @keywords internal setClass("KazamConnection", contains = "DBIConnection", slots = list( host = "character", username = "character", # and so on ptr = "externalptr" ) ) ``` Now you have some of the boilerplate out of the way, you can start work on the connection. The most important method here is `dbConnect()` which allows you to connect to a specified instance of the database. Note the use of `@rdname Kazam`. This ensures that `Kazam()` and the connect method are documented together. ```{r} #' @param drv An object created by \code{Kazam()} #' @rdname Kazam #' @export #' @examples #' \dontrun{ #' db <- dbConnect(RKazam::Kazam()) #' dbWriteTable(db, "mtcars", mtcars) #' dbGetQuery(db, "SELECT * FROM mtcars WHERE cyl == 4") #' } setMethod("dbConnect", "KazamDriver", function(drv, ...) { # ... new("KazamConnection", host = host, ...) }) ``` * Replace `...` with the arguments needed to connect to your database. You'll always need to include `...` in the arguments, even if you don't use it, for compatibility with the generic. * This is likely to be where people first come for help, so the examples should show how to connect to the database, and how to query it. (Obviously these examples won't work yet.) Ideally, include examples that can be run right away (perhaps relying on a publicly hosted database), but failing that surround in `\dontrun{}` so people can at least see the code. Next, implement `show()` and `dbDisconnect()` methods. ## Results Finally, you're ready to implement the meat of the system: fetching results of a query into a data frame. First define a results class: ```{r} #' Kazam results class. #' #' @keywords internal #' @export setClass("KazamResult", contains = "DBIResult", slots = list(ptr = "externalptr") ) ``` Then write a `dbSendQuery()` method. This takes a connection and SQL string as arguments, and returns a result object. Again `...` is needed for compatibility with the generic, but you can add other arguments if you need them. ```{r} #' Send a query to Kazam. #' #' @export #' @examples #' # This is another good place to put examples setMethod("dbSendQuery", "KazamConnection", function(conn, statement, ...) { # some code new("KazamResult", ...) }) ``` Next, implement `dbClearResult()`, which should close the result set and free all resources associated with it: ```{r} #' @export setMethod("dbClearResult", "KazamResult", function(res, ...) { # free resources TRUE }) ``` The hardest part of every DBI package is writing the `dbFetch()` method. This needs to take a result set and (optionally) number of records to return, and create a dataframe. Mapping R's data types to those of your database may require a custom implementation of the `dbDataType()` method for your connection class: ```{r} #' Retrieve records from Kazam query #' @export setMethod("dbFetch", "KazamResult", function(res, n = -1, ...) { ... }) # (optionally) #' Find the database data type associated with an R object #' @export setMethod("dbDataType", "KazamConnection", function(dbObj, obj, ...) { ... }) ``` Next, implement `dbHasCompleted()` which should return a `logical` indicating if there are any rows remaining to be fetched. ```{r} #' @export setMethod("dbHasCompleted", "KazamResult", function(res, ...) { }) ``` With these four methods in place, you can now use the default `dbGetQuery()` to send a query to the database, retrieve results if available and then clean up. Spend some time now making sure this works with an existing database, or relax and let the `DBItest` package do the work for you. ## SQL methods You're now on the home stretch, and can make your wrapper substantially more useful by implementing methods that wrap around variations in SQL across databases: * `dbQuoteString()` and `dbQuoteIdentifer()` are used to safely quote strings and identifiers to avoid SQL injection attacks. Note that the former must be vectorized, but not the latter. * `dbWriteTable()` creates a database table given an R dataframe. I'd recommend using the functions prefixed with `sql` in this package to generate the SQL. These functions are still a work in progress so please let me know if you have problems. * `dbReadTable()`: a simple wrapper around `SELECT * FROM table`. Use `dbQuoteIdentifer()` to safely quote the table name and prevent mismatches between the names allowed by R and the database. * `dbListTables()` and `dbExistsTable()` let you determine what tables are available. If not provided by your database's API, you may need to generate sql that inspects the system tables. * `dbListFields()` shows which fields are available in a given table. * `dbRemoveTable()` wraps around `DROP TABLE`. Start with `SQL::sqlTableDrop()`. * `dbBegin()`, `dbCommit()` and `dbRollback()`: implement these three functions to provide basic transaction support. This functionality is currently not tested in the `DBItest` package. ## Metadata methods There are a lot of extra metadata methods for result sets (and one for the connection) that you might want to implement. They are described in the following. * `dbIsValid()` returns if a connection or a result set is open (`TRUE`) or closed (`FALSE`). All further methods in this section are valid for result sets only. * `dbGetStatement()` returns the issued query as a character value. * `dbColumnInfo()` lists the names and types of the result set's columns. * `dbGetRowCount()` and `dbGetRowsAffected()` returns the number of rows returned or altered in a `SELECT` or `INSERT`/`UPDATE` query, respectively. * `dbBind()` allows using parametrised queries. Take a look at `sqlInterpolate()` and `sqlParseVariables()` if your SQL engine doesn't offer native parametrised queries. ## Full DBI compliance By now, your package should implement all methods defined in the DBI specification. If you want to walk the extra mile, offer a read-only mode that allows your users to be sure that their valuable data doesn't get destroyed inadvertently. DBI/inst/doc/DBI-advanced.html0000644000176200001440000013466414627152530015444 0ustar liggesusers Advanced DBI Usage

Advanced DBI Usage

James Wondrasek, Kirill Müller

17/03/2020

Who this tutorial is for

This tutorial is for you if you need to use a richer set of SQL features such as data manipulation queries, parameterized queries and queries performed using SQL’s transaction features. See vignette("DBI", package = "DBI") for a more basic tutorial covering connecting to DBMS and executing simple queries.

How to run more complex queries using DBI

dbGetQuery() works by calling a number of functions behind the scenes. If you need more control you can manually build your own query, retrieve results at your selected rate, and release the resources involved by calling the same functions.

These functions are:

  • dbSendQuery() sends the SQL query to the DBMS and returns a result object. The query is limited to SELECT statements. If you want to send other statements, such as INSERT, UPDATE, DELETE, etc, use dbSendStatement().
  • dbFetch() is called with the result object returned by dbSendQuery(). It also accepts an argument specifying the number of rows to be returned, e.g. n = 200. If you want to fetch all the rows, use n = -1.
  • dbClearResult() is called when you have finished retrieving data. It releases the resources associated with the result object.
library(DBI)

con <- dbConnect(
  RMariaDB::MariaDB(),
  host = "db.relational-data.org",
  port = 3306,
  username = "guest",
  password = "relational",
  dbname = "sakila"
)

res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = 'G'")
df <- dbFetch(res, n = 3)
dbClearResult(res)

head(df, 3)
##   film_id            title
## 1       2   ACE GOLDFINGER
## 2       4 AFFAIR PREJUDICE
## 3       5      AFRICAN EGG
##                                                                                                             description
## 1                  A Astounding Epistle of a Database Administrator And a Explorer who must Find a Car in Ancient China
## 2                          A Fanciful Documentary of a Frisbee And a Lumberjack who must Chase a Monkey in A Shark Tank
## 3 A Fast-Paced Documentary of a Pastry Chef And a Dentist who must Pursue a Forensic Psychologist in The Gulf of Mexico
##   release_year language_id original_language_id rental_duration rental_rate
## 1         2006           1                   NA               3        4.99
## 2         2006           1                   NA               5        2.99
## 3         2006           1                   NA               6        2.99
##   length replacement_cost rating               special_features
## 1     48            12.99      G        Trailers,Deleted Scenes
## 2    117            26.99      G Commentaries,Behind the Scenes
## 3    130            22.99      G                 Deleted Scenes
##           last_update
## 1 2006-02-15 04:03:42
## 2 2006-02-15 04:03:42
## 3 2006-02-15 04:03:42

How to read part of a table from a database

If your dataset is large you may want to fetch a limited number of rows at a time. As demonstrated below, this can be accomplished by using a while loop where the function dbHasCompleted() is used to check for ongoing rows, and dbFetch() is used with the n = X argument, specifying how many rows to return on each iteration. Again, we call dbClearResult() at the end to release resources.

res <- dbSendQuery(con, "SELECT * FROM film")
while (!dbHasCompleted(res)) {
  chunk <- dbFetch(res, n = 300)
  print(nrow(chunk))
}
## [1] 300
## [1] 300
## [1] 300
## [1] 100
dbClearResult(res)

How to use parameters (safely) in SQL queries

dbSendQuery() can be used with parameterized SQL queries. DBI supports two ways to avoid SQL injection attacks from user-supplied parameters: quoting and parameterized queries.

Quoting

Quoting of parameter values is performed using the function dbQuoteLiteral(), which supports many R data types, including date and time.1

In cases where users may be supplying table or column names to use in the query for data retrieval, those names or identifiers must also be escaped. As there may be DBMS-specific rules for escaping these identifiers, DBI provides the function dbQuoteIdentifier() to generate a safe string representation.

safe_id <- dbQuoteIdentifier(con, "rating")
safe_param <- dbQuoteLiteral(con, "G")

query <- paste0("SELECT title, ", safe_id, " FROM film WHERE ", safe_id, " = ", safe_param)
query
## [1] "SELECT title, `rating` FROM film WHERE `rating` = 'G'"
res <- dbSendQuery(con, query)
dbFetch(res)
##              title rating
## 1   ACE GOLDFINGER      G
## 2 AFFAIR PREJUDICE      G
## 3      AFRICAN EGG      G
## Showing 3 out of 178 rows.
dbClearResult(res)

The same result can be had by using glue::glue_sql(). It performs the same safe quoting on any variable or R statement appearing between braces within the query string.

id <- "rating"
param <- "G"
query <- glue::glue_sql("SELECT title, {`id`} FROM film WHERE {`id`} = {param}", .con = con)

df <- dbGetQuery(con, query)
head(df, 3)
##              title rating
## 1   ACE GOLDFINGER      G
## 2 AFFAIR PREJUDICE      G
## 3      AFRICAN EGG      G

Parameterized queries

Rather than performing the parameter substitution ourselves, we can push it to the DBMS by including placeholders in the query. Different DBMS use different placeholder schemes, DBI passes through the SQL expression unchanged.

MariaDB uses a question mark (?) as placeholder and expects an unnamed list of parameter values. Other DBMS may use named parameters. We recommend consulting the documentation for the DBMS you are using. As an example, a web search for “mariadb parameterized queries” leads to the documentation for the PREPARE statement which mentions:

Within the statement, “?” characters can be used as parameter markers to indicate where data values are to be bound to the query later when you execute it.

Currently there is no list of which placeholder scheme a particular DBMS supports.

Placeholders only work for literal values. Other parts of the query, e.g. table or column identifiers, still need to be quoted with dbQuoteIdentifier().

For a single set of parameters, the params argument to dbSendQuery() or dbGetQuery() can be used. It takes a list and its members are substituted in order for the placeholders within the query.

params <- list("G")
safe_id <- dbQuoteIdentifier(con, "rating")

query <- paste0("SELECT * FROM film WHERE ", safe_id, " = ?")
query
## [1] "SELECT * FROM film WHERE `rating` = ?"
res <- dbSendQuery(con, query, params = params)
dbFetch(res, n = 3)
##   film_id            title
## 1       2   ACE GOLDFINGER
## 2       4 AFFAIR PREJUDICE
## 3       5      AFRICAN EGG
##                                                                                                             description
## 1                  A Astounding Epistle of a Database Administrator And a Explorer who must Find a Car in Ancient China
## 2                          A Fanciful Documentary of a Frisbee And a Lumberjack who must Chase a Monkey in A Shark Tank
## 3 A Fast-Paced Documentary of a Pastry Chef And a Dentist who must Pursue a Forensic Psychologist in The Gulf of Mexico
##   release_year language_id original_language_id rental_duration rental_rate
## 1         2006           1                   NA               3        4.99
## 2         2006           1                   NA               5        2.99
## 3         2006           1                   NA               6        2.99
##   length replacement_cost rating               special_features
## 1     48            12.99      G        Trailers,Deleted Scenes
## 2    117            26.99      G Commentaries,Behind the Scenes
## 3    130            22.99      G                 Deleted Scenes
##           last_update
## 1 2006-02-15 04:03:42
## 2 2006-02-15 04:03:42
## 3 2006-02-15 04:03:42
dbClearResult(res)

Below is an example query using multiple placeholders with the MariaDB driver. The placeholders are supplied as a list of values ordered to match the position of the placeholders in the query.

q_params <- list("G", 90)
query <- "SELECT title, rating, length FROM film WHERE rating = ? AND length >= ?"

res <- dbSendQuery(con, query, params = q_params)
dbFetch(res, n = 3)
##              title rating length
## 1 AFFAIR PREJUDICE      G    117
## 2      AFRICAN EGG      G    130
## 3  ALAMO VIDEOTAPE      G    126
dbClearResult(res)

When you wish to perform the same query with different sets of parameter values, dbBind() is used. There are two ways to use dbBind(). Firstly, it can be used multiple times with same query.

res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = ?")
dbBind(res, list("G"))
dbFetch(res, n = 3)
##   film_id            title
## 1       2   ACE GOLDFINGER
## 2       4 AFFAIR PREJUDICE
## 3       5      AFRICAN EGG
##                                                                                                             description
## 1                  A Astounding Epistle of a Database Administrator And a Explorer who must Find a Car in Ancient China
## 2                          A Fanciful Documentary of a Frisbee And a Lumberjack who must Chase a Monkey in A Shark Tank
## 3 A Fast-Paced Documentary of a Pastry Chef And a Dentist who must Pursue a Forensic Psychologist in The Gulf of Mexico
##   release_year language_id original_language_id rental_duration rental_rate
## 1         2006           1                   NA               3        4.99
## 2         2006           1                   NA               5        2.99
## 3         2006           1                   NA               6        2.99
##   length replacement_cost rating               special_features
## 1     48            12.99      G        Trailers,Deleted Scenes
## 2    117            26.99      G Commentaries,Behind the Scenes
## 3    130            22.99      G                 Deleted Scenes
##           last_update
## 1 2006-02-15 04:03:42
## 2 2006-02-15 04:03:42
## 3 2006-02-15 04:03:42
dbBind(res, list("PG"))
dbFetch(res, n = 3)
##   film_id            title
## 1       1 ACADEMY DINOSAUR
## 2       6     AGENT TRUMAN
## 3      12   ALASKA PHANTOM
##                                                                                        description
## 1 A Epic Drama of a Feminist And a Mad Scientist who must Battle a Teacher in The Canadian Rockies
## 2        A Intrepid Panorama of a Robot And a Boy who must Escape a Sumo Wrestler in Ancient China
## 3               A Fanciful Saga of a Hunter And a Pastry Chef who must Vanquish a Boy in Australia
##   release_year language_id original_language_id rental_duration rental_rate
## 1         2006           1                   NA               6        0.99
## 2         2006           1                   NA               3        2.99
## 3         2006           1                   NA               6        0.99
##   length replacement_cost rating                 special_features
## 1     86            20.99     PG Deleted Scenes,Behind the Scenes
## 2    169            17.99     PG                   Deleted Scenes
## 3    136            22.99     PG      Commentaries,Deleted Scenes
##           last_update
## 1 2006-02-15 04:03:42
## 2 2006-02-15 04:03:42
## 3 2006-02-15 04:03:42
dbClearResult(res)

Secondly, dbBind() can be used to execute the same statement with multiple values at once.

res <- dbSendQuery(con, "SELECT * FROM film WHERE rating = ?")
dbBind(res, list(c("G", "PG")))
dbFetch(res, n = 3)
##   film_id            title
## 1       2   ACE GOLDFINGER
## 2       4 AFFAIR PREJUDICE
## 3       5      AFRICAN EGG
##                                                                                                             description
## 1                  A Astounding Epistle of a Database Administrator And a Explorer who must Find a Car in Ancient China
## 2                          A Fanciful Documentary of a Frisbee And a Lumberjack who must Chase a Monkey in A Shark Tank
## 3 A Fast-Paced Documentary of a Pastry Chef And a Dentist who must Pursue a Forensic Psychologist in The Gulf of Mexico
##   release_year language_id original_language_id rental_duration rental_rate
## 1         2006           1                   NA               3        4.99
## 2         2006           1                   NA               5        2.99
## 3         2006           1                   NA               6        2.99
##   length replacement_cost rating               special_features
## 1     48            12.99      G        Trailers,Deleted Scenes
## 2    117            26.99      G Commentaries,Behind the Scenes
## 3    130            22.99      G                 Deleted Scenes
##           last_update
## 1 2006-02-15 04:03:42
## 2 2006-02-15 04:03:42
## 3 2006-02-15 04:03:42
dbClearResult(res)

Use a list of vectors if your query has multiple parameters:

q_params <- list(c("G", "PG"), c(90, 120))
query <- "SELECT title, rating, length FROM film WHERE rating = ? AND length >= ?"

res <- dbSendQuery(con, query, params = q_params)
dbFetch(res, n = 3)
##              title rating length
## 1 AFFAIR PREJUDICE      G    117
## 2      AFRICAN EGG      G    130
## 3  ALAMO VIDEOTAPE      G    126
dbClearResult(res)

Always disconnect from the database when done.

dbDisconnect(con)

SQL data manipulation - UPDATE, DELETE and friends

For SQL queries that affect the underlying database, such as UPDATE, DELETE, INSERT INTO, and DROP TABLE, DBI provides two functions. dbExecute() passes the SQL statement to the DBMS for execution and returns the number of rows affected. dbSendStatement() performs in the same manner, but returns a result object. Call dbGetRowsAffected() with the result object to get the count of the affected rows. You then need to call dbClearResult() with the result object afterwards to release resources.

In actuality, dbExecute() is a convenience function that calls dbSendStatement(), dbGetRowsAffected(), and dbClearResult(). You can use these functions if you need more control over the query process.

The subsequent examples use an in-memory SQL database provided by RSQLite::SQLite(), because the remote database used in above examples does not allow writing.

library(DBI)
con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "cars", head(cars, 3))

dbExecute(
  con,
  "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)"
)
## [1] 3
rs <- dbSendStatement(
  con,
  "INSERT INTO cars (speed, dist) VALUES (4, 4), (5, 5), (6, 6)"
)
dbGetRowsAffected(rs)
## [1] 3
dbClearResult(rs)

dbReadTable(con, "cars")
##   speed dist
## 1     4    2
## 2     4   10
## 3     7    4
## Showing 3 out of 9 rows.

Do not forget to disconnect from the database at the end.

dbDisconnect(con)

SQL transactions with DBI

DBI allows you to group multiple queries into a single atomic transaction. Transactions are initiated with dbBegin() and either made persistent with dbCommit() or undone with dbRollback(). The example below updates two tables and ensures that either both tables are updated, or no changes are persisted to the database and an error is thrown.

con <- dbConnect(RSQLite::SQLite(), ":memory:")

dbWriteTable(con, "cash", data.frame(amount = 100))
dbWriteTable(con, "account", data.frame(amount = 2000))

withdraw <- function(amount) {
  # All operations must be carried out as logical unit:
  dbExecute(con, "UPDATE cash SET amount = amount + ?", list(amount))
  dbExecute(con, "UPDATE account SET amount = amount - ?", list(amount))
}

withdraw_transacted <- function(amount) {
  # Ensure atomicity
  dbBegin(con)

  # Perform operation
  withdraw(amount)

  # Persist results
  dbCommit(con)
}

withdraw_transacted(300)

After withdrawing 300 credits, the cash is increased and the account is decreased by this amount. The transaction ensures that either both operations succeed, or no change occurs.

dbReadTable(con, "cash")
##   amount
## 1    400
dbReadTable(con, "account")
##   amount
## 1   1700

We can roll back changes manually if necessary. Do not forget to call dbRollback() in case of error, otherwise the transaction remains open indefinitely.

withdraw_if_funds <- function(amount) {
  dbBegin(con)
  withdraw(amount)
  # Rolling back after detecting negative value on account:
  if (dbReadTable(con, "account")$amount >= 0) {
    dbCommit(con)
    TRUE
  } else {
    message("Insufficient funds")
    dbRollback(con)
    FALSE
  }
}

withdraw_if_funds(5000)
## Insufficient funds
## [1] FALSE
dbReadTable(con, "cash")
##   amount
## 1    400
dbReadTable(con, "account")
##   amount
## 1   1700

dbWithTransaction() simplifies using transactions. Pass it a connection and the code you want to run as a transaction. It will execute the code and call dbCommit() on success and call dbRollback() if an error is thrown.

withdraw_safely <- function(amount) {
  dbWithTransaction(con, {
    withdraw(amount)
    if (dbReadTable(con, "account")$amount < 0) {
      stop("Error: insufficient funds", call. = FALSE)
    }
  })
}

withdraw_safely(5000)
## Error: Error: insufficient funds
dbReadTable(con, "cash")
##   amount
## 1    400
dbReadTable(con, "account")
##   amount
## 1   1700

As usual, do not forget to disconnect from the database when done.

dbDisconnect(con)

Conclusion

That concludes the major features of DBI. For more details on the library functions covered in this tutorial and the vignette("DBI", package = "DBI") introductory tutorial see the DBI specification at vignette("spec", package = "DBI"). If you are after a data manipulation library that works at a higher level of abstraction, check out dplyr. It is a grammar of data manipulation that can work with local dataframes and remote databases and uses DBI under the hood.

  1. An older method, dbQuoteString(), was used to quote string values only. The dbQuoteLiteral() method forwards to dbQuoteString() for character vectors. Users do not need to distinguish between these two cases.↩︎

DBI/inst/doc/DBI.html0000644000176200001440000006277014627152534013703 0ustar liggesusers Introduction to DBI

Introduction to DBI

James Wondrasek, Katharina Brunner, Kirill Müller

27 February 2020

Who this tutorial is for

This tutorial is for you if you want to access or manipulate data in a database that may be on your machine or on a different computer on the internet, and you have found libraries that use a higher level of abstraction, such as dbplyr, are not suitable for your purpose. Depending on what you want to achieve, you may find it useful to have an understanding of SQL before using DBI.

The DBI (DataBase Interface) package provides a simple, consistent interface between R and database management systems (DBMS). Each supported DBMS is supported by its own R package that implements the DBI specification in vignette("spec", package = "DBI").

DBI currently supports about 30 DBMS, including:

For a more complete list of supported DBMS visit https://github.com/r-dbi/backends. You may need to install the package specific to your DBMS.

The functionality currently supported for each of these DBMS’s includes:

  • manage a connection to a database
  • list the tables in a database
  • list the column names in a table
  • read a table into a data frame

For more advanced features, such as parameterized queries, transactions, and more see vignette("DBI-advanced", package = "DBI").

How to connect to a database using DBI

The following code establishes a connection to the Sakila database hosted by the Relational Dataset Repository at https://relational-data.org/dataset/Sakila, lists all tables on the database, and closes the connection. The database represents a fictional movie rental business and includes tables describing films, actors, customers, stores, etc.:

library(DBI)

con <- dbConnect(
  RMariaDB::MariaDB(),
  host = "db.relational-data.org",
  port = 3306,
  username = "guest",
  password = "relational",
  dbname = "sakila"
)

dbListTables(con)
##  [1] "actor"         "address"       "category"      "city"         
##  [5] "country"       "customer"      "film"          "film_actor"   
##  [9] "film_category" "film_text"     "inventory"     "language"     
## [13] "payment"       "rental"        "staff"         "store"
dbDisconnect(con)

Connections to databases are created using the dbConnect() function. The first argument to the function is the driver for the DBMS you are connecting to. In the example above we are connecting to a MariaDB instance, so we use the RMariaDB::MariaDB() driver. The other arguments depend on the authentication required by the DBMS. In the example host, port, username, password, and dbname are required. See the documentation for the DBMS driver package that you are using for specifics.

The function dbListTables() takes a database connection as its only argument and returns a character vector with all table and view names in the database.

After completing a session with a DBMS, always release the connection with a call to dbDisconnect().

Secure password storage

The above example contains the password in the code, which should be avoided for databases with secured access. One way to use the credentials securely is to store it in your system’s credential store and then query it with the keyring package. The code to connect to the database could then look like this:

con <- dbConnect(
  RMariaDB::MariaDB(),
  host = "db.relational-data.org",
  port = 3306,
  username = "guest",
  password = keyring::key_get("db.relational-data.org", "guest"),
  dbname = "sakila"
)

How to retrieve column names for a table

We can list the column names for a table with the function dbListFields(). It takes as arguments a database connection and a table name and returns a character vector of the column names in order.

con <- dbConnect(RMariaDB::MariaDB(), username = "guest", password = "relational", host = "db.relational-data.org", port = 3306, dbname = "sakila")
dbListFields(con, "film")
##  [1] "film_id"              "title"                "description"         
##  [4] "release_year"         "language_id"          "original_language_id"
##  [7] "rental_duration"      "rental_rate"          "length"              
## [10] "replacement_cost"     "rating"               "special_features"    
## [13] "last_update"

Read a table into a data frame

The function dbReadTable() reads an entire table and returns it as a data frame. It is equivalent to the SQL query SELECT * FROM <name>. The columns of the returned data frame share the same names as the columns in the table. DBI and the database backends do their best to coerce data to equivalent R data types.

df <- dbReadTable(con, "film")
head(df, 3)
##   film_id            title
## 1       1 ACADEMY DINOSAUR
## 2       2   ACE GOLDFINGER
## 3       3 ADAPTATION HOLES
##                                                                                            description
## 1     A Epic Drama of a Feminist And a Mad Scientist who must Battle a Teacher in The Canadian Rockies
## 2 A Astounding Epistle of a Database Administrator And a Explorer who must Find a Car in Ancient China
## 3     A Astounding Reflection of a Lumberjack And a Car who must Sink a Lumberjack in A Baloon Factory
##   release_year language_id original_language_id rental_duration rental_rate
## 1         2006           1                   NA               6        0.99
## 2         2006           1                   NA               3        4.99
## 3         2006           1                   NA               7        2.99
##   length replacement_cost rating                 special_features
## 1     86            20.99     PG Deleted Scenes,Behind the Scenes
## 2     48            12.99      G          Trailers,Deleted Scenes
## 3     50            18.99  NC-17          Trailers,Deleted Scenes
##           last_update
## 1 2006-02-15 04:03:42
## 2 2006-02-15 04:03:42
## 3 2006-02-15 04:03:42

Read only selected rows and columns into a data frame

To read a subset of the data in a table into a data frame, DBI provides functions to run custom SQL queries and manage the results. For small datasets where you do not need to manage the number of results being returned, the function dbGetQuery() takes a SQL SELECT query to execute and returns a data frame. Below is a basic query that specifies the columns we require (film_id, title and description) and which rows (records) we are interested in. Here we retrieve films released in the year 2006.

df <- dbGetQuery(con, "SELECT film_id, title, description FROM film WHERE release_year = 2006")
head(df, 3)
##   film_id            title
## 1       1 ACADEMY DINOSAUR
## 2       2   ACE GOLDFINGER
## 3       3 ADAPTATION HOLES
##                                                                                            description
## 1     A Epic Drama of a Feminist And a Mad Scientist who must Battle a Teacher in The Canadian Rockies
## 2 A Astounding Epistle of a Database Administrator And a Explorer who must Find a Car in Ancient China
## 3     A Astounding Reflection of a Lumberjack And a Car who must Sink a Lumberjack in A Baloon Factory

We could also retrieve movies released in 2006 that are rated “G”. Note that character strings must be quoted. As the query itself is contained within double quotes, we use single quotes around the rating. See dbQuoteLiteral() for programmatically converting arbitrary R values to SQL. This is covered in more detail in vignette("DBI-advanced", package = "DBI").

df <- dbGetQuery(con, "SELECT film_id, title, description FROM film WHERE release_year = 2006 AND rating = 'G'")
head(df, 3)
##   film_id            title
## 1       2   ACE GOLDFINGER
## 2       4 AFFAIR PREJUDICE
## 3       5      AFRICAN EGG
##                                                                                                             description
## 1                  A Astounding Epistle of a Database Administrator And a Explorer who must Find a Car in Ancient China
## 2                          A Fanciful Documentary of a Frisbee And a Lumberjack who must Chase a Monkey in A Shark Tank
## 3 A Fast-Paced Documentary of a Pastry Chef And a Dentist who must Pursue a Forensic Psychologist in The Gulf of Mexico

The equivalent operation using dplyr reconstructs the SQL query using three functions to specify the table (tbl()), the subset of the rows (filter()), and the columns we require (select()). Note that dplyr takes care of the quoting.

library(dplyr)

lazy_df <-
  tbl(con, "film") %>%
  filter(release_year == 2006 & rating == "G") %>%
  select(film_id, title, description)
head(lazy_df, 3)
## # Source:   SQL [3 x 3]
## # Database: mysql  [guest@db.relational-data.org:NA/sakila]
##   film_id title            description                                          
##     <int> <chr>            <chr>                                                
## 1       2 ACE GOLDFINGER   A Astounding Epistle of a Database Administrator And…
## 2       4 AFFAIR PREJUDICE A Fanciful Documentary of a Frisbee And a Lumberjack…
## 3       5 AFRICAN EGG      A Fast-Paced Documentary of a Pastry Chef And a Dent…

If you want to perform other data manipulation queries such as UPDATEs and DELETEs, see dbSendStatement() in vignette("DBI-advanced", package = "DBI").

How to end a DBMS session

When finished accessing the DBMS, always close the connection using dbDisconnect().

dbDisconnect(con)

Conclusion

This tutorial has given you the basic techniques for accessing data in any supported DBMS. If you need to work with databases that will not fit in memory, or want to run more complex queries, including parameterized queries, please see vignette("DBI-advanced", package = "DBI").

Further Reading

DBI/inst/doc/backend.R0000644000176200001440000000550214627152534014117 0ustar liggesusers## ----echo = FALSE------------------------------------------------------------- library(DBI) knitr::opts_chunk$set(collapse = TRUE, comment = "#>") ## ----------------------------------------------------------------------------- #' Driver for Kazam database. #' #' @keywords internal #' @export #' @import DBI #' @import methods setClass("KazamDriver", contains = "DBIDriver") ## ----------------------------------------------------------------------------- #' @export #' @rdname Kazam-class setMethod("dbUnloadDriver", "KazamDriver", function(drv, ...) { TRUE }) ## ----------------------------------------------------------------------------- setMethod("show", "KazamDriver", function(object) { cat("\n") }) ## ----------------------------------------------------------------------------- #' @export Kazam <- function() { new("KazamDriver") } Kazam() ## ----------------------------------------------------------------------------- #' Kazam connection class. #' #' @export #' @keywords internal setClass("KazamConnection", contains = "DBIConnection", slots = list( host = "character", username = "character", # and so on ptr = "externalptr" ) ) ## ----------------------------------------------------------------------------- #' @param drv An object created by \code{Kazam()} #' @rdname Kazam #' @export #' @examples #' \dontrun{ #' db <- dbConnect(RKazam::Kazam()) #' dbWriteTable(db, "mtcars", mtcars) #' dbGetQuery(db, "SELECT * FROM mtcars WHERE cyl == 4") #' } setMethod("dbConnect", "KazamDriver", function(drv, ...) { # ... new("KazamConnection", host = host, ...) }) ## ----------------------------------------------------------------------------- #' Kazam results class. #' #' @keywords internal #' @export setClass("KazamResult", contains = "DBIResult", slots = list(ptr = "externalptr") ) ## ----------------------------------------------------------------------------- #' Send a query to Kazam. #' #' @export #' @examples #' # This is another good place to put examples setMethod("dbSendQuery", "KazamConnection", function(conn, statement, ...) { # some code new("KazamResult", ...) }) ## ----------------------------------------------------------------------------- #' @export setMethod("dbClearResult", "KazamResult", function(res, ...) { # free resources TRUE }) ## ----------------------------------------------------------------------------- #' Retrieve records from Kazam query #' @export setMethod("dbFetch", "KazamResult", function(res, n = -1, ...) { ... }) # (optionally) #' Find the database data type associated with an R object #' @export setMethod("dbDataType", "KazamConnection", function(dbObj, obj, ...) { ... }) ## ----------------------------------------------------------------------------- #' @export setMethod("dbHasCompleted", "KazamResult", function(res, ...) { }) DBI/inst/doc/spec.R0000644000176200001440000000022314627152534013455 0ustar liggesusers## ----echo = FALSE------------------------------------------------------------- knitr::asis_output(paste(readLines("spec.md"), collapse = "\n")) DBI/inst/doc/DBI-arrow.R0000644000176200001440000000547114627152531014260 0ustar liggesusers## ----setup, include=FALSE----------------------------------------------------- library(knitr) opts_chunk$set(echo = TRUE) knitr::opts_chunk$set(error = Sys.getenv("IN_PKGDOWN") != "true" || (getRversion() < "3.5")) knit_print.data.frame <- function(x, ...) { print(head(x, 6)) if (nrow(x) > 6) { cat("Showing 6 out of", nrow(x), "rows.\n") } invisible(x) } registerS3method("knit_print", "data.frame", "knit_print.data.frame") ## ----------------------------------------------------------------------------- library(DBI) con <- dbConnect(RSQLite::SQLite()) data <- data.frame( a = 1:3, b = 4.5, c = "five" ) dbWriteTable(con, "tbl", data) ## ----------------------------------------------------------------------------- stream <- dbReadTableArrow(con, "tbl") stream as.data.frame(stream) ## ----------------------------------------------------------------------------- stream <- dbGetQueryArrow(con, "SELECT COUNT(*) AS n FROM tbl WHERE a < 3") stream path <- tempfile(fileext = ".parquet") arrow::write_parquet(arrow::as_record_batch_reader(stream), path) arrow::read_parquet(path) ## ----------------------------------------------------------------------------- params <- data.frame(a = 3L) stream <- dbGetQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a", params = params) as.data.frame(stream) params <- data.frame(a = c(2L, 4L)) # Equivalent to dbBind() stream <- dbGetQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a", params = params) as.data.frame(stream) ## ----------------------------------------------------------------------------- rs <- dbSendQueryArrow(con, "SELECT $a AS batch, * FROM tbl WHERE a < $a") in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 1L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 2L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 3L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) in_arrow <- nanoarrow::as_nanoarrow_array(data.frame(a = 1:4L)) dbBindArrow(rs, in_arrow) as.data.frame(dbFetchArrow(rs)) dbClearResult(rs) ## ----------------------------------------------------------------------------- stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a < 3") dbWriteTableArrow(con, "tbl_new", stream) dbReadTable(con, "tbl_new") ## ----------------------------------------------------------------------------- stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a < 3") dbCreateTableArrow(con, "tbl_split", stream) dbAppendTableArrow(con, "tbl_split", stream) stream <- dbGetQueryArrow(con, "SELECT * FROM tbl WHERE a >= 3") dbAppendTableArrow(con, "tbl_split", stream) dbReadTable(con, "tbl_split") ## ----------------------------------------------------------------------------- dbDisconnect(con) DBI/inst/doc/spec.Rmd0000644000176200001440000000177114607456777014025 0ustar liggesusers--- title: "DBI specification" author: "Kirill Müller" output: rmarkdown::html_vignette abstract: > The DBI package defines the generic DataBase Interface for R. The connection to individual DBMS is provided by other packages that import DBI (so-called *DBI backends*). This document formalizes the behavior expected by the methods declared in DBI and implemented by the individual backends. To ensure maximum portability and exchangeability, and to reduce the effort for implementing a new DBI backend, the DBItest package defines a comprehensive set of test cases that test conformance to the DBI specification. This document is derived from comments in the test definitions of the DBItest package. Any extensions or updates to the tests will be reflected in this document. vignette: > %\VignetteIndexEntry{DBI specification} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r echo = FALSE} knitr::asis_output(paste(readLines("spec.md"), collapse = "\n")) ``` DBI/inst/doc/DBI-proposal.html0000644000176200001440000016232414627152531015531 0ustar liggesusers A Common Interface to Relational Databases from R and S – A Proposal

A Common Interface to Relational Databases from R and S – A Proposal

David James

March 16, 2000

For too long S and similar data analysis environments have lacked good interfaces to relational database systems (RDBMS). For the last twenty years or so these RDBMS have evolved into highly optimized client-server systems for data storage and manipulation, and currently they serve as repositories for most of the business, industrial, and research “raw” data that analysts work with. Other analysis packages, such as SAS, have traditionally provided good data connectivity, but S and GNU R have relied on intermediate text files as means of importing data (but see R Data Import/Export (2001) and Using Relational Database Systems with R (2000).) Although this simple approach works well for relatively modest amounts of mostly static data, it does not scale up to larger amounts of data distributed over machines and locations, nor does it scale up to data that is highly dynamic – situations that are becoming increasingly common.

We want to propose a common interface between R/S and RDBMS that would allow users to access data stored on database servers in a uniform and predictable manner irrespective of the database engine. The interface defines a small set of classes and methods similar in spirit to Python’s DB-API, Java’s JDBC, Microsoft’s ODBC, Perl’s DBI, etc., but it conforms to the “whole-object” philosophy so natural in S and R.

Computing with Distributed Data

As data analysts, we are increasingly faced with the challenge of larger data sources distributed over machines and locations; most of these data sources reside in relational database management systems (RDBMS). These relational databases represent a mature client-server distributed technology that we as analysts could be exploiting more that we’ve done in the past. The relational technology provides a well-defined standard, the ANSI SQL-92 X/Open CAE Specification: SQL and RDA (1994), both for defining and manipulating data in a highly optimized fashion from virtually any application.

In contrast, S and Splus have provided somewhat limited tools for coping with the challenges of larger and distributed data sets (Splus does provide an import function to import from databases, but it is quite limited in terms of SQL facilities). The R community has been more resourceful and has developed a number of good libraries for connecting to mSQL, MySQL, PostgreSQL, and ODBC; each library, however, has defined its own interface to each database engine a bit differently. We think it would be to everybody’s advantage to coordinate the definition of a common interface, an effort not unlike those taken in the Python and Perl communities.

The goal of a common, seamless access to distributed data is a modest one in our evolution towards a fully distributed computing environment. We recognize the greater goal of distributed computing as the means to fully integrate diverse systems – not just databases – into a truly flexible analysis environment. Good connectivity to databases, however, is of immediate necessity both in practical terms and as a means to help us transition from monolithic, self-contained systems to those in which computations, not only the data, can be carried out in parallel over a wide number of computers and/or systems Temple Lang (2000). Issues of reliability, security, location transparency, persistence, etc., will be new to most of us and working with distributed data may provide a more gradual change to ease in the ultimate goal of full distributed computing.

A Common Interface

We believe that a common interface to databases can help users easily access data stored in RDBMS. A common interface would describe, in a uniform way, how to connect to RDBMS, extract meta-data (such as list of available databases, tables, etc.) as well as a uniform way to execute SQL statements and import their output into R and S. The current emphasis is on querying databases and not so much in a full low-level interface for database development as in JDBC or ODBC, but unlike these, we want to approach the interface from the “whole-object” perspective J. M. Chambers (1998) so natural to R/S and Python – for instance, by fetching all fields and records simultaneously into a single object.

The basic idea is to split the interface into a front-end consisting of a few classes and generic functions that users invoke and a back-end set of database-specific classes and methods that implement the actual communication. (This is a very well-known pattern in software engineering, and another good verbatim is the device-independent graphics in R/S where graphics functions produce similar output on a variety of different devices, such X displays, Postscript, etc.)

The following verbatim shows the front-end:

> mgr <- dbManager("Oracle")
> con <- dbConnect(mgr, user = "user", passwd = "passwd")
> rs <- dbExecStatement(con,
          "select fld1, fld2, fld3 from MY_TABLE")
> tbls <- fetch(rs, n = 100)
> hasCompleted(rs)
[1] T
> close(rs)
> rs <- dbExecStatement(con,
          "select id_name, q25, q50 from liv2")
> res <- fetch(rs)
> getRowCount(rs)
[1] 73
> close(con)

Such scripts should work with other RDBMS (say, MySQL) by replacing the first line with

> mgr <- dbManager("MySQL")

Interface Classes

The following are the main RS-DBI classes. They need to be extended by individual database back-ends (MySQL, Oracle, etc.)

dbManager

Virtual class1 extended by actual database managers, e.g., Oracle, MySQL, Informix.

dbConnection

Virtual class that captures a connection to a database instance2.

dbResult

Virtual class that describes the result of an SQL statement.

dbResultSet

Virtual class, extends dbResult to fully describe the output of those statements that produce output records, i.e., SELECT (or SELECT-like) SQL statement.

All these classes should implement the methods show, describe, and getInfo:

show

(print in R) prints a one-line identification of the object.

describe

prints a short summary of the meta-data of the specified object (like summary in R/S).

getInfo

takes an object of one of the above classes and a string specifying a meta-data item, and it returns the corresponding information (NULL if unavailable).

> mgr <- dbManager("MySQL")
> getInfo(mgr, "version")
> con <- dbConnect(mgr, ...)
> getInfo(con, "type")

The reason we implement the meta-data through getInfo in this way is to simplify the writing of database back-ends. We don’t want to overwhelm the developers of drivers (ourselves, most likely) with hundreds of methods as in the case of JDBC.

In addition, the following methods should also be implemented:

getDatabases

lists all available databases known to the dbManager.

getTables

lists tables in a database.

getTableFields

lists the fields in a table in a database.

getTableIndices

lists the indices defined for a table in a database.

These methods may be implemented using the appropriate getInfo method above.

In the next few sections we describe in detail each of these classes and their methods.

Class dbManager

This class identifies the relational database management system. It needs to be extended by individual back-ends (Oracle, PostgreSQL, etc.) The dbManager class defines the following methods:

load

initializes the driver code. We suggest having the generator, dbManager(driver), automatically load the driver.

unload

releases whatever resources the driver is using.

getVersion

returns the version of the RS-DBI currently implemented, plus any other relevant information about the implementation itself and the RDBMS being used.

Class dbConnection

This virtual class captures a connection to a RDBMS, and it provides access to dynamic SQL, result sets, RDBMS session management (transactions), etc. Note that the dbManager may or may not allow multiple simultaneous connections. The methods it defines include:

dbConnect

opens a connection to the database dbname. Other likely arguments include host, user, and password. It returns an object that extends dbConnection in a driver-specific manner (e.g., the MySQL implementation creates a connection of class MySQLConnection that extends dbConnection). Note that we could separate the steps of connecting to a RDBMS and opening a database there (i.e., opening an instance). For simplicity we do the 2 steps in this method. If the user needs to open another instance in the same RDBMS, just open a new connection.

close

closes the connection and discards all pending work.

dbExecStatement

submits one SQL statement. It returns a dbResult object, and in the case of a SELECT statement, the object also inherits from dbResultSet. This dbResultSet object is needed for fetching the output rows of SELECT statements. The result of a non-SELECT statement (e.g., UPDATE, DELETE, CREATE, ALTER, …) is defined as the number of rows affected (this seems to be common among RDBMS).

commit

commits pending transaction (optional).

rollback

undoes current transaction (optional).

callProc

invokes a stored procedure in the RDBMS (tentative). Stored procedures are not part of the ANSI SQL-92 standard and possibly vary substantially from one RDBMS to another. For instance, Oracle seems to have a fairly decent implementation of stored procedures, but MySQL currently does not support them.

dbExec

submit an SQL “script” (multiple statements). May be implemented by looping with dbExecStatement.

dbNextResultSet

When running SQL scripts (multiple statements), it closes the current result set in the dbConnection, executes the next statement and returns its result set.

Class dbResult

This virtual class describes the result of an SQL statement (any statement) and the state of the operation. Non-query statements (e.g., CREATE, UPDATE, DELETE) set the “completed” state to 1, while SELECT statements to 0. Error conditions set this slot to a negative number. The dbResult class defines the following methods:

getStatement

returns the SQL statement associated with the result set.

getDBConnection

returns the dbConnection associated with the result set.

getRowsAffected

returns the number of rows affected by the operation.

hasCompleted

was the operation completed? SELECT’s, for instance, are not completed until their output rows are all fetched.

getException

returns the status of the last SQL statement on a given connection as a list with two members, status code and status description.

Class dbResultSet

This virtual class extends dbResult, and it describes additional information from the result of a SELECT statement and the state of the operation. The completed state is set to 0 so long as there are pending rows to fetch. The dbResultSet class defines the following additional methods:

getRowCount

returns the number of rows fetched so far.

getNullOk

returns a logical vector with as many elements as there are fields in the result set, each element describing whether the corresponding field accepts NULL values.

getFields

describes the SELECTed fields. The description includes field names, RDBMS internal data types, internal length, internal precision and scale, null flag (i.e., column allows NULL’s), and corresponding S classes (which can be over-ridden with user-provided classes). The current MySQL and Oracle implementations define a dbResultSet as a named list with the following elements:

connection:

the connection object associated with this result set;

statement:

a string with the SQL statement being processed;

description:

a field description data.frame with as many rows as there are fields in the SELECT output, and columns specifying the name, type, length, precision, scale, Sclass of the corresponding output field.

rowsAffected:

the number of rows that were affected;

rowCount:

the number of rows so far fetched;

completed:

a logical value describing whether the operation has completed or not.

nullOk:

a logical vector specifying whether the corresponding column may take NULL values.

The methods above are implemented as accessor functions to this list in the obvious way.

setDataMappings

defines a conversion between internal RDBMS data types and R/S classes. We expect the default mappings to be by far the most common ones, but users that need more control may specify a class generator for individual fields in the result set. (See Section [sec:mappings] for details.)

close

closes the result set and frees resources both in R/S and the RDBMS.

fetch

extracts the next max.rec records (-1 means all).

Data Type Mappings

The data types supported by databases are slightly different than the data types in R and S, but the mapping between them is straightforward: Any of the many fixed and varying length character types are mapped to R/S character. Fixed-precision (non-IEEE) numbers are mapped into either doubles (numeric) or long (integer). Dates are mapped to character using the appropriate TO_CHAR function in the RDBMS (which should take care of any locale information). Some RDBMS support the type CURRENCY or MONEY which should be mapped to numeric. Large objects (character, binary, file, etc.) also need to be mapped. User-defined functions may be specified to do the actual conversion as follows:

  1. run the query (either with dbExec or dbExecStatement):

    > rs <- dbExecStatement(con, "select whatever-You-need")

  2. extract the output field definitions

    > flds <- getFields(rs)

  3. replace the class generator in the, say 3rd field, by the user own generator:

    > flds[3, "Sclass"]            # default mapping
[1] "character"

    by

    > flds[3, "Sclass"] <- "myOwnGeneratorFunction"

  4. set the new data mapping prior to fetching

    > setDataMappings(resutlSet, flds)

  5. fetch the rows and store in a data.frame

    > data <- fetch(resultSet)

Open Issues

We may need to provide some additional utilities, for instance to convert dates, to escape characters such as quotes and slashes in query strings, to strip excessive blanks from some character fields, etc. We need to decide whether we provide hooks so these conversions are done at the C level, or do all the post-processing in R or S.

Another issue is what kind of data object is the output of an SQL query. Currently the MySQL and Oracle implementations return data as a data.frame; data frames have the slight inconvenience that they automatically re-label the fields according to R/S syntax, changing the actual RDBMS labels of the variables; the issue of non-numeric data being coerced into factors automatically “at the drop of a hat” (as someone in s-news wrote) is also annoying.

The execution of SQL scripts is not fully described. The method that executes scripts could run individual statements without returning until it encounters a query (SELECT-like) statement. At that point it could return that one result set. The application is then responsible for fetching these rows, and then for invoking dbNextResultSet on the opened dbConnection object to repeat the dbExec/fetch loop until it encounters the next dbResultSet. And so on. Another (potentially very expensive) alternative would be to run all statements sequentially and return a list of data.frames, each element of the list storing the result of each statement.

Binary objects and large objects present some challenges both to R and S. It is becoming more common to store images, sounds, and other data types as binary objects in RDBMS, some of which can be in principle quite large. The SQL-92 ANSI standard allows up to 2 gigabytes for some of these objects. We need to carefully plan how to deal with binary objects – perhaps tentatively not in full generality. Large objects could be fetched by repeatedly invoking a specified R/S function that takes as argument chunks of a specified number of raw bytes. In the case of S4 (and Splus5.x) the RS-DBI implementation can write into an opened connection for which the user has defined a reader (but can we guarantee that we won’t overflow the connection?). In the case of R it is not clear what data type binary large objects (BLOB) should be mapped into.

Limitations

These are some of the limitations of the current interface definition:

  • we only allow one SQL statement at a time, forcing users to split SQL scripts into individual statements;

  • transaction management is not fully described;

  • the interface is heavily biased towards queries, as opposed to general purpose database development. In particular we made no attempt to define “bind variables”; this is a mechanism by which the contents of S objects are implicitly moved to the database during SQL execution. For instance, the following embedded SQL statement

      /* SQL */
  SELECT * from emp_table where emp_id = :sampleEmployee

    would take the vector sampleEmployee and iterate over each of its elements to get the result. Perhaps RS-DBI could at some point in the future implement this feature.

Other Approaches

The high-level, front-end description of RS-DBI is the more critical aspect of the interface. Details on how to actually implement this interface may change over time. The approach described in this document based on one back-end driver per RDBMS is reasonable, but not the only approach – we simply felt that a simpler approach based on well-understood and self-contained tools (R, S, and C API’s) would be a better start. Nevertheless we want to briefly mention a few alternatives that we considered and tentatively decided against, but may quite possibly re-visit in the near future.

Open Database Connectivity (ODBC)

The ODBC protocol was developed by Microsoft to allow connectivity among C/C++ applications and RDBMS. As you would expect, originally implementations of the ODBC were only available under Windows environments. There are various effort to create a Unix implementation (see the Unix ODBC web-site and Harvey (1999)). This approach looks promising because it allows us to write only one back-end, instead of one per RDBMS. Since most RDBMS already provide ODBC drivers, this could greatly simplify development. Unfortunately, the Unix implementation of ODBC was not mature enough at the time we looked at it, a situation we expect will change in the next year or so. At that point we will need to re-evaluate it to make sure that such an ODBC interface does not penalize the interface in terms of performance, ease of use, portability among the various Unix versions, etc.

Java Database Connectivity (JDBC)

Another protocol, the Java database connectivity, is very well-done and supported by just about every RDBMS. The issue with JDBC is that as of today neither S nor R (which are written in C) interfaces cleanly with Java. There are several efforts (some in a quite fairly advanced state) to allow S and R to invoke Java methods. Once this interface is widely available in Splus5x and R we will need to re-visit this issue again and study the performance, usability, etc., of JDBC as a common back-end to the RS-DBI.

CORBA and a 3-tier Architecture

Yet another approach is to move the interface to RDBMS out of R and S altogether into a separate system or server that would serve as a proxy between R/S and databases. The communication to this middle-layer proxy could be done through CORBA Siegel (1996), Java’s RMI, or some other similar technology. Such a design could be very flexible, but the CORBA facilities both in R and S are not widely available yet, and we do not know whether this will be made available to Splus5 users from MathSoft. Also, my experience with this technology is rather limited.

On the other hand, this 3-tier architecture seem to offer the most flexibility to cope with very large distributed databases, not necessarily relational.

Resources

The latest documentation and software on the RS-DBI was available at www.omegahat.net (link dead now: https://www.omegahat.net/contrib/RS-DBI/index.html). The R community has developed interfaces to some databases: RmSQL is an interface to the mSQL database written by Torsten Hothorn; RPgSQL is an interface to PostgreSQL and was written by Timothy H. Keitt; RODBC is an interface to ODBC, and it was written by Michael Lapsley. (For more details on all these see R Data Import/Export (2001).)

The are R and S-Plus interfaces to MySQL that follow the propose RS-DBI API described here; also, there’s an S-Plus interface SOracle James (In preparation) to Oracle (we expect to have an R implementation soon.)

The idea of a common interface to databases has been successfully implemented in Java’s Database Connectivity (JDBC) (www.javasoft.com), in C through the Open Database Connectivity (ODBC) (www.unixodbc.org), in Python’s Database Application Programming Interface (www.python.org), and in Perl’s Database Interface (www.cpan.org).

Acknowledgements

The R/S database interface came about from suggestions, comments, and discussions with John M. Chambers and Duncan Temple Lang in the context of the Omega Project for Statistical Computing. Doug Bates and Saikat DebRoy ported (and greatly improved) the first MySQL implementation to R.

The S Version 4 Definitions

The following code is meant to serve as a detailed description of the R/S to database interface. We decided to use S4 (instead of R or S version 3) because its clean syntax help us to describe easily the classes and methods that form the RS-DBI, and also to convey the inter-class relationships.

## Define all the classes and methods to be used by an
## implementation of the RS-DataBase Interface.  Mostly,
## these classes are virtual and each driver should extend
## them to provide the actual implementation.

## Class: dbManager
## This class identifies the DataBase Management System
## (Oracle, MySQL, Informix, PostgreSQL, etc.)

setClass("dbManager", VIRTUAL)

setGeneric("load",
   def = function(dbMgr,...)
   standardGeneric("load")
   )
setGeneric("unload",
   def = function(dbMgr,...)
   standardGeneric("unload")
   )
setGeneric("getVersion",
   def = function(dbMgr,...)
   standardGeneric("getVersion")
   )

## Class: dbConnections
## This class captures a connection to a database instance.

setClass("dbConnection", VIRTUAL)

setGeneric("dbConnection",
   def = function(dbMgr, ...)
   standardGeneric("dbConnection")
   )
setGeneric("dbConnect",
   def = function(dbMgr, ...)
   standardGeneric("dbConnect")
   )
setGeneric("dbExecStatement",
   def = function(con, statement, ...)
   standardGeneric("dbExecStatement")
   )
setGeneric("dbExec",
   def = function(con, statement, ...)
   standardGeneric("dbExec")
   )
setGeneric("getResultSet",
   def = function(con, ..)
   standardGeneric("getResultSet")
   )
setGeneric("commit",
   def = function(con, ...)
   standardGeneric("commit")
   )
setGeneric("rollback",
   def = function(con, ...)
   standardGeneric("rollback")
   )
setGeneric("callProc",
   def = function(con, ...)
   standardGeneric("callProc")
   )
setMethod("close",
   signature = list(con="dbConnection", type="missing"),
   def = function(con, type) NULL
   )

## Class: dbResult
## This is a base class for arbitrary results from the RDBMS
## (INSERT, UPDATE, DELETE).  SELECTs (and SELECT-like)
## statements produce "dbResultSet" objects, which extend
## dbResult.

setClass("dbResult", VIRTUAL)

setMethod("close",
   signature = list(con="dbResult", type="missing"),
   def = function(con, type) NULL
   )

## Class: dbResultSet
## Note that we define a resultSet as the result of a
## SELECT  SQL statement.

setClass("dbResultSet", "dbResult")

setGeneric("fetch",
   def = function(resultSet,n,...)
   standardGeneric("fetch")
   )
setGeneric("hasCompleted",
   def = function(object, ...)
   standardGeneric("hasCompleted")
   )
setGeneric("getException",
   def = function(object, ...)
   standardGeneric("getException")
   )
setGeneric("getDBconnection",
   def = function(object, ...)
   standardGeneric("getDBconnection")
   )
setGeneric("setDataMappings",
   def = function(resultSet, ...)
   standardGeneric("setDataMappings")
   )
setGeneric("getFields",
   def = function(object, table, dbname,  ...)
   standardGeneric("getFields")
   )
setGeneric("getStatement",
   def = function(object, ...)
   standardGeneric("getStatement")
   )
setGeneric("getRowsAffected",
   def = function(object, ...)
   standardGeneric("getRowsAffected")
   )
setGeneric("getRowCount",
   def = function(object, ...)
   standardGeneric("getRowCount")
   )
setGeneric("getNullOk",
   def = function(object, ...)
   standardGeneric("getNullOk")
   )

## Meta-data:
setGeneric("getInfo",
   def = function(object, ...)
   standardGeneric("getInfo")
   )
setGeneric("describe",
   def = function(object, verbose=F, ...)
   standardGeneric("describe")
   )
setGeneric("getCurrentDatabase",
   def = function(object, ...)
   standardGeneric("getCurrentDatabase")
   )
setGeneric("getDatabases",
   def = function(object, ...)
   standardGeneric("getDatabases")
   )
setGeneric("getTables",
   def = function(object, dbname, ...)
   standardGeneric("getTables")
   )
setGeneric("getTableFields",
   def = function(object, table, dbname, ...)
   standardGeneric("getTableFields")
   )
setGeneric("getTableIndices",
   def = function(object, table, dbname, ...)
   standardGeneric("getTableIndices")
   )
Chambers, J. M. 1998. Programming with Data: A Guide to the s Language. New York: Springer.
Chambers, John M., Mark H. Hansen, David A. James, and Duncan Temple Lang. 1998. “Distributed Computing with Data: A CORBA-Based Approach.” In Computing Science and Statistics. Inteface Foundation of North America.
Harvey, Peter. 1999. “Open Database Connectivity.” Linux Journal Nov. (67): 68–72.
James, David A. In preparation. “An R/S Interface to the Oracle Database.” www.omegahat.org: Bell Labs, Lucent Technologies.
R Data Import/Export. 2001. R-Development Core Team.
Siegel, Jon. 1996. CORBA Fundamentals and Programming. New York: Wiley.
Temple Lang, Duncan. 2000. “The Omegahat Environment: New Possibilities for Statistical Computing.” Journal of Computational and Graphical Statistics to appear.
Using Relational Database Systems with R. 2000. R-Developemt Core Team.
X/Open CAE Specification: SQL and RDA. 1994. Reading, UK: X/Open Company Ltd.

  1. A virtual class allows us to group classes that share some common functionality, e.g., the virtual class “dbConnection” groups all the connection implementations by Informix, Ingres, DB/2, Oracle, etc. Although the details will vary from one RDBMS to another, the defining characteristic of these objects is what a virtual class captures. R and S version 3 do not explicitly define virtual classes, but they can easily implement the idea through inheritance.↩︎

  2. The term “database” is sometimes (confusingly) used both to denote the RDBMS, such as Oracle, MySQL, and also to denote a particular database instance under a RDBMS, such as “opto” or “sales” databases under the same RDBMS.↩︎

DBI/inst/doc/DBI-history.Rmd0000644000176200001440000001221414602466070015140 0ustar liggesusers--- title: "History of DBI" author: "David James" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{History of DBI} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- The following history of DBI was contributed by David James, the driving force behind the development of DBI, and many of the packages that implement it. The idea/work of interfacing S (originally S3 and S4) to RDBMS goes back to the mid- and late 1990's in Bell Labs. The first toy interface I did was to implement John Chamber's early concept of "Data Management in S" (1991). The implementation followed that interface pretty closely and immediately showed some of the limitations when dealing with very large databases; if my memory serves me, the issue was the instance-based of the language back then, e.g., if you attached an RDBMS to the `search()` path and then needed to resolve a symbol "foo", you effectively had to bring all the objects in the database to check their mode/class, i.e., the instance object had the metadata in itself as attributes. The experiment showed that the S3 implementation of "data management" was not really suitable to large external RDBMS (probably it was never intended to do that anyway). (Note however, that since then, John and Duncan Temple Lang generalized the data management in S4 a lot, including Duncan's implementation in his RObjectTables package where he considered a lot of synchronization/caching issues relevant to DBI and, more generally, to most external interfaces). Back then we were working very closely with Lucent's microelectronics manufacturing --- our colleagues there had huge Oracle (mostly) databases that we needed to constantly query via [SQL*Plus](https://en.wikipedia.org/wiki/SQL*Plus). My colleague Jake Luciani was developing advanced applications in C and SQL, and the two of us came up with the first implementation of S3 directly connecting with Oracle. What I remember is that the Linux [PRO*C](https://en.wikipedia.org/wiki/Pro*C) pre-compiler (that embedded SQL in C code) was very buggy --- we spent a lot of time looking for workarounds and tricks until we got the C interface running. At the time, other projects within Bell Labs began using MySQL, and we moved to MySQL (with the help of Doug Bates' student Saikat DebRoy, then a summer intern) with no intentions of looking back at the very difficult Oracle interface. It was at this time that I moved all the code from S3 methods to S4 classes and methods and begun reaching out to the S/R community for suggestions, ideas, etc. All (most) of this work was on Bell Labs versions of S3 and S4, but I made sure it worked with S-Plus. At some point around 2000 (I don't remember exactly when), I ported all the code to R regressing to S3 methods, and later on (once S4 classes and methods were available in R) I re-implemented everything back to S4 classes and methods in R (a painful back-and-forth). It was at this point that I decided to drop S-Plus altogether. Around that time, I came across a very early implementation of SQLite and I was quite interested and thought it was a very nice RDBMS that could be used for all kinds of experimentation, etc., so it was pretty easy to implement on top of the DBI. Within the R community, there were quite a number of people that showed interest on defining a common interface to databases, but only a few folks actually provided code/suggestions/etc. (Tim Keitt was most active with the dbi/PostgreSQL packages --- he also was considering what he called "proxy" objects, which was reminiscent of what Duncan had been doing). Kurt Hornick, Vincent Carey, Robert Gentleman, and others provided suggestions/comments/support for the DBI definition. By around 2003, the DBI was more or less implemented as it is today. I'm sure I'll forget some (most should be in the THANKS sections of the various packages), but the names that come to my mind at this moment are Jake Luciani (ROracle), Don MacQueen and other early ROracle users (super helpful), Doug Bates and his student Saikat DebRoy for RMySQL, Fei Chen (at the time a student of Prof. Ripley) also contributed to RMySQL, Tim Keitt (working on an early S3 interface to PostgrSQL), Torsten Hothorn (worked with mSQL and also MySQL), Prof. Ripley working/extending the RODBC package, in addition to John Chambers and Duncan Temple-Lang who provided very important comments and suggestions. Actually, the real impetus behind the DBI was always to do distributed statistical computing --- *not* to provide a yet-another import/export mechanism --- and this perspective was driven by John and Duncan's vision and work on inter-system computing, COM, CORBA, etc. I'm not sure many of us really appreciated (even now) the full extent of those ideas and concepts. Just like in other languages (C's ODBC, Java's JDBC, Perl's DBI/DBD, Python dbapi), R/S DBI was meant to unify the interfacing to RDBMS so that R/S applications could be developed on top of the DBI and not be hard coded to any one relation database. The interface I tried to follow the closest was the Python's DBAPI --- I haven't worked on this topic for a while, but I still feel Python's DBAPI is the cleanest and most relevant for the S language. DBI/inst/doc/DBI.Rmd0000644000176200001440000001621514627140067013450 0ustar liggesusers--- title: "Introduction to DBI" author: "James Wondrasek, Katharina Brunner, Kirill Müller" date: "27 February 2020" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to DBI} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set( echo = TRUE, error = Sys.getenv("IN_PKGDOWN") != "true" || (getRversion() < "3.5") ) ``` ## Who this tutorial is for This tutorial is for you if you want to access or manipulate data in a database that may be on your machine or on a different computer on the internet, and you have found libraries that use a higher level of abstraction, such as [dbplyr](https://dbplyr.tidyverse.org/), are not suitable for your purpose. Depending on what you want to achieve, you may find it useful to have an understanding of SQL before using DBI. The DBI (**D**ata**B**ase **I**nterface) package provides a simple, consistent interface between R and database management systems (DBMS). Each supported DBMS is supported by its own R package that implements the DBI specification in `vignette("spec", package = "DBI")`. DBI currently supports about 30 DBMS, including: * MySQL, using the R-package [RMySQL](https://github.com/r-dbi/RMySQL) * MariaDB, using the R-package [RMariaDB](https://github.com/r-dbi/RMariaDB) * Postgres, using the R-package [RPostgres](https://github.com/r-dbi/RPostgres) * SQLite, using the R-package [RSQLite](https://github.com/r-dbi/RSQLite) For a more complete list of supported DBMS visit [https://github.com/r-dbi/backends](https://github.com/r-dbi/backends#readme). You may need to install the package specific to your DBMS. The functionality currently supported for each of these DBMS's includes: - manage a connection to a database - list the tables in a database - list the column names in a table - read a table into a data frame For more advanced features, such as parameterized queries, transactions, and more see `vignette("DBI-advanced", package = "DBI")`. ## How to connect to a database using DBI The following code establishes a connection to the Sakila database hosted by the Relational Dataset Repository at `https://relational-data.org/dataset/Sakila`, lists all tables on the database, and closes the connection. The database represents a fictional movie rental business and includes tables describing films, actors, customers, stores, etc.: ```{r} library(DBI) con <- dbConnect( RMariaDB::MariaDB(), host = "db.relational-data.org", port = 3306, username = "guest", password = "relational", dbname = "sakila" ) dbListTables(con) dbDisconnect(con) ``` Connections to databases are created using the `dbConnect()` function. The first argument to the function is the driver for the DBMS you are connecting to. In the example above we are connecting to a MariaDB instance, so we use the `RMariaDB::MariaDB()` driver. The other arguments depend on the authentication required by the DBMS. In the example host, port, username, password, and dbname are required. See the documentation for the DBMS driver package that you are using for specifics. The function `dbListTables()` takes a database connection as its only argument and returns a character vector with all table and view names in the database. After completing a session with a DBMS, always release the connection with a call to `dbDisconnect()`. ### Secure password storage The above example contains the password in the code, which should be avoided for databases with secured access. One way to use the credentials securely is to store it in your system's credential store and then query it with the [keyring](https://github.com/r-lib/keyring#readme) package. The code to connect to the database could then look like this: ```{r eval = FALSE} con <- dbConnect( RMariaDB::MariaDB(), host = "db.relational-data.org", port = 3306, username = "guest", password = keyring::key_get("db.relational-data.org", "guest"), dbname = "sakila" ) ``` ## How to retrieve column names for a table We can list the column names for a table with the function `dbListFields()`. It takes as arguments a database connection and a table name and returns a character vector of the column names in order. ```{r} con <- dbConnect(RMariaDB::MariaDB(), username = "guest", password = "relational", host = "db.relational-data.org", port = 3306, dbname = "sakila") dbListFields(con, "film") ``` ## Read a table into a data frame The function `dbReadTable()` reads an entire table and returns it as a data frame. It is equivalent to the SQL query `SELECT * FROM `. The columns of the returned data frame share the same names as the columns in the table. DBI and the database backends do their best to coerce data to equivalent R data types. ```{r} df <- dbReadTable(con, "film") head(df, 3) ``` ## Read only selected rows and columns into a data frame To read a subset of the data in a table into a data frame, DBI provides functions to run custom SQL queries and manage the results. For small datasets where you do not need to manage the number of results being returned, the function `dbGetQuery()` takes a SQL `SELECT` query to execute and returns a data frame. Below is a basic query that specifies the columns we require (`film_id`, `title` and `description`) and which rows (records) we are interested in. Here we retrieve films released in the year 2006. ```{r} df <- dbGetQuery(con, "SELECT film_id, title, description FROM film WHERE release_year = 2006") head(df, 3) ``` We could also retrieve movies released in 2006 that are rated "G". Note that character strings must be quoted. As the query itself is contained within double quotes, we use single quotes around the rating. See `dbQuoteLiteral()` for programmatically converting arbitrary R values to SQL. This is covered in more detail in `vignette("DBI-advanced", package = "DBI")`. ```{r} df <- dbGetQuery(con, "SELECT film_id, title, description FROM film WHERE release_year = 2006 AND rating = 'G'") head(df, 3) ``` The equivalent operation using `dplyr` reconstructs the SQL query using three functions to specify the table (`tbl()`), the subset of the rows (`filter()`), and the columns we require (`select()`). Note that dplyr takes care of the quoting. ```{r message=FALSE} library(dplyr) lazy_df <- tbl(con, "film") %>% filter(release_year == 2006 & rating == "G") %>% select(film_id, title, description) head(lazy_df, 3) ``` If you want to perform other data manipulation queries such as `UPDATE`s and `DELETE`s, see `dbSendStatement()` in `vignette("DBI-advanced", package = "DBI")`. ## How to end a DBMS session When finished accessing the DBMS, always close the connection using `dbDisconnect()`. ```{r} dbDisconnect(con) ``` ## Conclusion This tutorial has given you the basic techniques for accessing data in any supported DBMS. If you need to work with databases that will not fit in memory, or want to run more complex queries, including parameterized queries, please see `vignette("DBI-advanced", package = "DBI")`. ## Further Reading * An overview on [working with databases in R on Rstudio.com](https://db.rstudio.com/) * The DBI specification: `vignette("spec", package = "DBI")` * [List of supported DBMS](https://github.com/r-dbi/backends#readme) DBI/inst/doc/DBI-history.html0000644000176200001440000002332514627152531015370 0ustar liggesusers History of DBI

History of DBI

David James

The following history of DBI was contributed by David James, the driving force behind the development of DBI, and many of the packages that implement it.

The idea/work of interfacing S (originally S3 and S4) to RDBMS goes back to the mid- and late 1990’s in Bell Labs. The first toy interface I did was to implement John Chamber’s early concept of “Data Management in S” (1991). The implementation followed that interface pretty closely and immediately showed some of the limitations when dealing with very large databases; if my memory serves me, the issue was the instance-based of the language back then, e.g., if you attached an RDBMS to the search() path and then needed to resolve a symbol “foo”, you effectively had to bring all the objects in the database to check their mode/class, i.e., the instance object had the metadata in itself as attributes. The experiment showed that the S3 implementation of “data management” was not really suitable to large external RDBMS (probably it was never intended to do that anyway). (Note however, that since then, John and Duncan Temple Lang generalized the data management in S4 a lot, including Duncan’s implementation in his RObjectTables package where he considered a lot of synchronization/caching issues relevant to DBI and, more generally, to most external interfaces).

Back then we were working very closely with Lucent’s microelectronics manufacturing — our colleagues there had huge Oracle (mostly) databases that we needed to constantly query via SQL*Plus. My colleague Jake Luciani was developing advanced applications in C and SQL, and the two of us came up with the first implementation of S3 directly connecting with Oracle. What I remember is that the Linux PRO*C pre-compiler (that embedded SQL in C code) was very buggy — we spent a lot of time looking for workarounds and tricks until we got the C interface running. At the time, other projects within Bell Labs began using MySQL, and we moved to MySQL (with the help of Doug Bates’ student Saikat DebRoy, then a summer intern) with no intentions of looking back at the very difficult Oracle interface. It was at this time that I moved all the code from S3 methods to S4 classes and methods and begun reaching out to the S/R community for suggestions, ideas, etc. All (most) of this work was on Bell Labs versions of S3 and S4, but I made sure it worked with S-Plus. At some point around 2000 (I don’t remember exactly when), I ported all the code to R regressing to S3 methods, and later on (once S4 classes and methods were available in R) I re-implemented everything back to S4 classes and methods in R (a painful back-and-forth). It was at this point that I decided to drop S-Plus altogether. Around that time, I came across a very early implementation of SQLite and I was quite interested and thought it was a very nice RDBMS that could be used for all kinds of experimentation, etc., so it was pretty easy to implement on top of the DBI.

Within the R community, there were quite a number of people that showed interest on defining a common interface to databases, but only a few folks actually provided code/suggestions/etc. (Tim Keitt was most active with the dbi/PostgreSQL packages — he also was considering what he called “proxy” objects, which was reminiscent of what Duncan had been doing). Kurt Hornick, Vincent Carey, Robert Gentleman, and others provided suggestions/comments/support for the DBI definition. By around 2003, the DBI was more or less implemented as it is today.

I’m sure I’ll forget some (most should be in the THANKS sections of the various packages), but the names that come to my mind at this moment are Jake Luciani (ROracle), Don MacQueen and other early ROracle users (super helpful), Doug Bates and his student Saikat DebRoy for RMySQL, Fei Chen (at the time a student of Prof. Ripley) also contributed to RMySQL, Tim Keitt (working on an early S3 interface to PostgrSQL), Torsten Hothorn (worked with mSQL and also MySQL), Prof. Ripley working/extending the RODBC package, in addition to John Chambers and Duncan Temple-Lang who provided very important comments and suggestions.

Actually, the real impetus behind the DBI was always to do distributed statistical computing — not to provide a yet-another import/export mechanism — and this perspective was driven by John and Duncan’s vision and work on inter-system computing, COM, CORBA, etc. I’m not sure many of us really appreciated (even now) the full extent of those ideas and concepts. Just like in other languages (C’s ODBC, Java’s JDBC, Perl’s DBI/DBD, Python dbapi), R/S DBI was meant to unify the interfacing to RDBMS so that R/S applications could be developed on top of the DBI and not be hard coded to any one relation database. The interface I tried to follow the closest was the Python’s DBAPI — I haven’t worked on this topic for a while, but I still feel Python’s DBAPI is the cleanest and most relevant for the S language.