1#' Database and SQL generics.
2#'
3#' The `sql_` generics are used to build the different types of SQL queries.
4#' The default implementations in dbplyr generates ANSI 92 compliant SQL.
5#' The `db_` generics execute actions on the database. The default
6#' implementations in dbplyr typically just call the standard DBI S4
7#' method.
8#'
9#' A few backend methods do not call the standard DBI S4 methods including
10#'
11#' * `db_data_type()`: Calls [DBI::dbDataType()] for every field
12#'   (e.g. data frame column) and returns a vector of corresponding SQL data
13#'   types
14#'
15#' * `db_save_query()`: Builds and executes a
16#'   `CREATE [TEMPORARY] TABLE <table> ...` SQL command.
17#'
18#' * `db_create_index()`: Builds and executes a
19#'   `CREATE INDEX <name> ON <table>` SQL command.
20#'
21#' * `db_drop_table()`: Builds and executes a
22#'   `DROP TABLE [IF EXISTS]  <table>` SQL command.
23#'
24#' * `db_analyze()`: Builds and executes an
25#'   `ANALYZE <table>` SQL command.
26#'
27#' Currently, [copy_to()] is the only user of `db_begin()`, `db_commit()`,
28#' `db_rollback()`, `db_write_table()`, `db_create_indexes()`, `db_drop_table()` and
29#' `db_analyze()`. If you find yourself overriding many of these
30#' functions it may suggest that you should just override `copy_to()`
31#' instead.
32#'
33#' `db_create_table()` and `db_insert_into()` have been deprecated
34#' in favour of `db_write_table()`.
35#'
36#' @return Usually a logical value indicating success. Most failures should generate
37#'  an error. However, `db_has_table()` should return `NA` if
38#'  temporary tables cannot be listed with [DBI::dbListTables()] (due to backend
39#'  API limitations for example). As a result, you methods will rely on the
40#'  backend to throw an error if a table exists when it shouldn't.
41#' @name backend_dbplyr
42#' @param con A database connection.
43#' @keywords internal
44NULL
45
46#' @name backend_dbplyr
47#' @export
48db_desc <- function(x) UseMethod("db_desc")
49
50#' @name backend_dbplyr
51#' @export
52sql_translate_env <- function(con) UseMethod("sql_translate_env")
53
54#' @name backend_dbplyr
55#' @export
56db_list_tables <- function(con) UseMethod("db_list_tables")
57
58#' @name backend_dbplyr
59#' @export
60#' @param table A string, the table name.
61db_has_table <- function(con, table) UseMethod("db_has_table")
62
63#' @name backend_dbplyr
64#' @export
65#' @param fields A list of fields, as in a data frame.
66db_data_type <- function(con, fields) UseMethod("db_data_type")
67#' @export
68
69#' @name backend_dbplyr
70#' @export
71db_save_query <- function(con, sql, name, temporary = TRUE, ...) {
72  UseMethod("db_save_query")
73}
74
75#' @name backend_dbplyr
76#' @export
77db_begin <- function(con, ...) UseMethod("db_begin")
78
79#' @name backend_dbplyr
80#' @export
81db_commit <- function(con, ...) UseMethod("db_commit")
82
83#' @name backend_dbplyr
84#' @export
85db_rollback <- function(con, ...) UseMethod("db_rollback")
86
87#' @name backend_dbplyr
88#' @export
89db_write_table <- function(con, table, types, values, temporary = FALSE, ...) {
90  UseMethod("db_write_table")
91}
92
93#' @name backend_dbplyr
94#' @export
95db_create_table <- function(con, table, types, temporary = FALSE, ...) {
96  UseMethod("db_create_table")
97}
98
99#' @name backend_dbplyr
100#' @export
101db_insert_into <- function(con, table, values, ...) {
102  UseMethod("db_insert_into")
103}
104
105#' @name backend_dbplyr
106#' @export
107db_create_indexes <- function(con, table, indexes = NULL, unique = FALSE, ...) {
108  UseMethod("db_create_indexes")
109}
110
111#' @name backend_dbplyr
112#' @export
113db_create_index <- function(con, table, columns, name = NULL, unique = FALSE,
114                            ...) {
115  UseMethod("db_create_index")
116}
117
118#' @name backend_dbplyr
119#' @export
120db_drop_table <- function(con, table, force = FALSE, ...) {
121  UseMethod("db_drop_table")
122}
123
124#' @name backend_dbplyr
125#' @export
126db_analyze <- function(con, table, ...) UseMethod("db_analyze")
127
128#' @export
129#' @rdname backend_dbplyr
130db_explain <- function(con, sql, ...) {
131  UseMethod("db_explain")
132}
133
134#' @rdname backend_dbplyr
135#' @export
136db_query_fields <- function(con, sql, ...) {
137  UseMethod("db_query_fields")
138}
139
140#' @rdname backend_dbplyr
141#' @export
142db_query_rows <- function(con, sql, ...) {
143  UseMethod("db_query_rows")
144}
145
146#' @rdname backend_dbplyr
147#' @export
148sql_select <- function(con, select, from, where = NULL, group_by = NULL,
149                       having = NULL, order_by = NULL, limit = NULL,
150                       distinct = FALSE, ...) {
151  UseMethod("sql_select")
152}
153
154#' @export
155#' @rdname backend_dbplyr
156sql_subquery <- function(con, from, name = random_table_name(), ...) {
157  UseMethod("sql_subquery")
158}
159
160#' @rdname backend_dbplyr
161#' @export
162sql_join <- function(con, x, y, vars, type = "inner", by = NULL, ...) {
163  UseMethod("sql_join")
164}
165
166#' @rdname backend_dbplyr
167#' @export
168sql_semi_join <- function(con, x, y, anti = FALSE, by = NULL, ...) {
169  UseMethod("sql_semi_join")
170}
171
172#' @rdname backend_dbplyr
173#' @export
174sql_set_op <- function(con, x, y, method) {
175  UseMethod("sql_set_op")
176}
177
178#' @rdname backend_dbplyr
179#' @export
180sql_escape_string <- function(con, x) UseMethod("sql_escape_string")
181
182#' @rdname backend_dbplyr
183#' @export
184sql_escape_ident <- function(con, x) UseMethod("sql_escape_ident")
185