% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sql-glue.R
\name{sql_glue}
\alias{sql_glue}
\alias{sql_glue2}
\title{Build SQL strings with glue syntax}
\usage{
sql_glue(sql, envir = parent.frame())

sql_glue2(con, sql, envir = parent.frame())
}
\arguments{
\item{sql}{A string to interpolate.}

\item{envir}{Environment to evaluate \code{sql} in.}

\item{con}{A \link{sql_dialect} object or database connection. Connections are
supported for backward compatibility.}
}
\value{
An SQL string.
}
\description{
\code{sql_glue()} and \code{sql_glue2()} are designed to help dbplyr extenders
generate custom SQL. They differ only in whether or not they require
a connection. \code{sql_glue()} retrieves the ambient connection, making it
suitable for use inside \code{\link[=sql_translation]{sql_translation()}} methods; \code{sql_glue2()} requires
a connection, making it suitable for use inside all other \code{sql_} methods.

As the name suggests, these functions use \pkg{glue} syntax to make it
easy to mix fixed SQL with varying user inputs. The default glue syntax, \code{{x}},
will escape \code{x} using the database connection. If there are multiple values
in \code{x}, they'll be collapsed into a single string with \verb{,}. If you want them
to be wrapped in \verb{()}, use a \code{*} suffix, e.g. \verb{\{x*\}}.

You can also use type markers to control how the value is treated:
\itemize{
\item \verb{\{.sql x\}}: \code{x} is literal SQL that should be interpolated as
is, without additional escaping. \code{x} must be a string.
\item \verb{\{.tbl x\}}: \code{x} is a table identifier like a string, \code{I()}, or one of
the older forms like \code{DBI::Id()} or \code{in_schema()}.
\item \verb{\{.id x\}}: \code{x} is a generic identifier, e.g. for a column or index.
\code{x} must be a character vector
}
}
\examples{
con <- dialect_ansi()

tbl <- "my_table"
sql_glue2(con, "SELECT * FROM {.tbl tbl}")

# Values are properly escaped
name <- "Robert'); DROP TABLE students;--"
sql_glue2(con, "INSERT INTO students (name) VALUES ({name})")

# Control wrapping with *
x <- c("name", "age", "grade")
sql_glue2(con, "SELECT {.id x} FROM students")
sql_glue2(con, "SELECT * WHERE variable IN {x*}")
}
