backupccl: add deprecation notice for BACKUP TO

Informs: #78153

Release note (sql change): The `BACKUP TO` syntax
to take backups is deprecated, and will be removed in a future
release. Users are recommended to create a backup collection
using the `BACKUP INTO` syntax in our docs.

pkg/ccl/backupccl/backup_planning.go

@@ -45,6 +45,7 @@ import (
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/tabledesc"
 	"github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgcode"
 	"github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgerror"
+	"github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgnotice"
 	"github.com/cockroachdb/cockroach/pkg/sql/privilege"
 	"github.com/cockroachdb/cockroach/pkg/sql/sem/tree"
 	"github.com/cockroachdb/cockroach/pkg/util/hlc"
@@ -592,6 +593,16 @@ func backupPlanHook(
 		return nil, nil, nil, false, err
 	}
 
+	// Deprecation notice for `BACKUP TO` syntax. Remove this once the syntax is
+	// deleted in 22.2.
+	if !backupStmt.Nested {
+		p.BufferClientNotice(ctx,
+			pgnotice.Newf("The `BACKUP TO` syntax will be removed in a future release, please"+
+				" switch over to using `BACKUP INTO` to create a backup collection: %s. "+
+				"Backups created using the `BACKUP TO` syntax may not be restoreable in the next major version release.",
+				"https://www.cockroachlabs.com/docs/stable/backup.html#considerations"))
+	}
+
 	var err error
 	subdirFn := func() (string, error) { return "", nil }
 	if backupStmt.Subdir != nil {

pkg/ccl/backupccl/testdata/backup-restore/backup-permissions

@@ -11,14 +11,14 @@ INSERT INTO d.t VALUES (1), (2), (3);
 
 # BACKUP is not allowed in a batch-statement.
 exec-sql
-BACKUP TO 'nodelocal://0/test-root/';
+BACKUP INTO 'nodelocal://0/test-root/';
 SELECT 1;
 ----
 pq: BACKUP cannot be used inside a multi-statement transaction without DETACHED option
 
 # Cluster backup should succeed as a root user.
 exec-sql
-BACKUP TO 'nodelocal://0/test-root/'
+BACKUP INTO 'nodelocal://0/test-root/'
 ----
 
 # Backups should succeed as a non-root user with admin role.
@@ -28,15 +28,15 @@ GRANT ADMIN TO testuser;
 ----
 
 exec-sql user=testuser
-BACKUP TO 'nodelocal://0/test-nonroot-cluster';
+BACKUP INTO 'nodelocal://0/test-nonroot-cluster';
 ----
 
 exec-sql user=testuser
-BACKUP DATABASE d TO 'nodelocal://0/test-nonroot-db';
+BACKUP DATABASE d INTO 'nodelocal://0/test-nonroot-db';
 ----
 
 exec-sql user=testuser
-BACKUP TABLE d.t TO 'nodelocal://0/test-nonroot-table';
+BACKUP TABLE d.t INTO 'nodelocal://0/test-nonroot-table';
 ----
 
 # Start a new cluster with the same IO dir.
@@ -75,7 +75,7 @@ GRANT CONNECT ON DATABASE d2 TO testuser;
 
 # Table backup as a non-admin user should have SELECT privileges.
 exec-sql user=testuser
-BACKUP TABLE d2.t TO 'nodelocal://0/d2-table'
+BACKUP TABLE d2.t INTO 'nodelocal://0/d2-table'
 ----
 pq: user testuser does not have SELECT privilege on relation t
 
@@ -90,7 +90,7 @@ CREATE SCHEMA sc2;
 
 # Schema backup as a non-admin user should have USAGE privileges.
 exec-sql user=testuser
-BACKUP DATABASE d2 TO 'nodelocal://0/d2-schema';
+BACKUP DATABASE d2 INTO 'nodelocal://0/d2-schema';
 ----
 pq: user testuser does not have USAGE privilege on schema sc2
 
@@ -108,7 +108,7 @@ REVOKE USAGE ON TYPE d2.greeting FROM public;
 
 # Type backup as a non-admin user should have USAGE privileges.
 exec-sql user=testuser
-BACKUP DATABASE d2 TO 'nodelocal://0/d2-schema';
+BACKUP DATABASE d2 INTO 'nodelocal://0/d2-schema';
 ----
 pq: user testuser does not have USAGE privilege on type greeting
 
@@ -118,11 +118,11 @@ GRANT USAGE ON TYPE d2.greeting TO testuser;
 
 # testuser should now have all the required privileges.
 exec-sql server=s2 user=testuser
-BACKUP DATABASE d2 TO 'nodelocal://0/d2';
+BACKUP DATABASE d2 INTO 'nodelocal://0/d2';
 ----
 
 exec-sql server=s2 user=testuser
-BACKUP TABLE d2.t TO 'nodelocal://0/d2-table';
+BACKUP TABLE d2.t INTO 'nodelocal://0/d2-table';
 ----
 
 exec-sql server=s2 user=testuser
@@ -147,7 +147,7 @@ SHOW BACKUP 'http://COCKROACH_TEST_HTTP_SERVER/'
 pq: only users with the admin role are allowed to SHOW BACKUP from the specified http URI
 
 exec-sql user=testuser
-BACKUP DATABASE d TO 'nodelocal://0/test3'
+BACKUP DATABASE d INTO 'nodelocal://0/test3'
 ----
 pq: only users with the admin role are allowed to BACKUP to the specified nodelocal URI
 

pkg/ccl/backupccl/testdata/backup-restore/column-families

@@ -29,7 +29,7 @@ SET CLUSTER SETTING bulkio.backup.merge_file_buffer_size = '1MiB';
 ----
 
 exec-sql
-BACKUP cfs TO 'nodelocal://1/foo';
+BACKUP cfs INTO 'nodelocal://1/foo';
 ----
 
 exec-sql

pkg/ccl/backupccl/testdata/backup-restore/descriptor-broadening

@@ -11,19 +11,19 @@ CREATE TABLE db1.t (a INT);
 ----
 
 exec-sql
-BACKUP DATABASE db1 TO 'nodelocal://1/backup';
+BACKUP DATABASE db1 INTO 'nodelocal://1/backup';
 ----
 
 exec-sql
-BACKUP DATABASE db1,db2 TO 'nodelocal://1/backup';
+BACKUP DATABASE db1,db2 INTO LATEST IN 'nodelocal://1/backup';
 ----
 pq: previous backup does not contain the complete database "db2"
 
 exec-sql
-BACKUP db1.t TO 'nodelocal://1/backup_2';
+BACKUP db1.t INTO 'nodelocal://1/backup_2';
 ----
 
 exec-sql
-BACKUP DATABASE db1 TO 'nodelocal://1/backup_2';
+BACKUP DATABASE db1 INTO LATEST IN 'nodelocal://1/backup_2';
 ----
 pq: previous backup does not contain the complete database "db1"

pkg/ccl/backupccl/testdata/backup-restore/feature-flags

@@ -13,7 +13,7 @@ SET CLUSTER SETTING feature.backup.enabled = FALSE;
 ----
 
 exec-sql
-BACKUP TO 'nodelocal://0/test-root/';
+BACKUP INTO 'nodelocal://0/test-root/';
 ----
 pq: feature BACKUP was disabled by the database administrator
 
@@ -23,7 +23,7 @@ SET CLUSTER SETTING feature.backup.enabled = TRUE;
 ----
 
 exec-sql
-BACKUP TO 'nodelocal://0/test-root/';
+BACKUP INTO 'nodelocal://0/test-root/';
 ----
 
 exec-sql

pkg/ccl/backupccl/testdata/backup-restore/max-row-size

@@ -23,7 +23,7 @@ INSERT INTO maxrow VALUES (2, repeat('x', 20000))
 pq: row larger than max row size: table 109 family 0 primary key /Table/109/1/2/0 size 20013
 
 exec-sql
-BACKUP maxrow TO 'nodelocal://1/maxrow';
+BACKUP maxrow INTO 'nodelocal://1/maxrow';
 ----
 
 exec-sql

pkg/ccl/backupccl/testdata/backup-restore/multiregion

@@ -15,11 +15,11 @@ us-east-1
 us-west-1
 
 exec-sql
-BACKUP DATABASE d TO 'nodelocal://1/database_backup/';
+BACKUP DATABASE d INTO 'nodelocal://1/database_backup/';
 ----
 
 exec-sql
-BACKUP TO 'nodelocal://1/full_cluster_backup/';
+BACKUP INTO 'nodelocal://1/full_cluster_backup/';
 ----
 
 # A new cluster with the same locality settings.
@@ -77,11 +77,11 @@ INSERT INTO no_region_db_2.t VALUES (1), (2), (3);
 ----
 
 exec-sql
-BACKUP DATABASE no_region_db TO 'nodelocal://1/no_region_database_backup/';
+BACKUP DATABASE no_region_db INTO 'nodelocal://1/no_region_database_backup/';
 ----
 
 exec-sql
-BACKUP TO 'nodelocal://1/no_region_cluster_backup/';
+BACKUP INTO 'nodelocal://1/no_region_cluster_backup/';
 ----
 
 exec-sql
@@ -136,7 +136,7 @@ INSERT INTO eu_central_db.t VALUES (1), (2), (3);
 NOTICE: setting eu-central-1 as the PRIMARY REGION as no PRIMARY REGION was specified
 
 exec-sql
-BACKUP DATABASE eu_central_db TO 'nodelocal://1/eu_central_database_backup/';
+BACKUP DATABASE eu_central_db INTO 'nodelocal://1/eu_central_database_backup/';
 ----
 
 # New cluster for a cluster backup.

pkg/ccl/backupccl/testdata/backup-restore/restore-grants

@@ -130,7 +130,7 @@ testdb sc othertable admin ALL true
 
 
 exec-sql
-BACKUP TO 'nodelocal://0/test/'
+BACKUP INTO 'nodelocal://0/test/'
 ----
 
 # Ensure that testuser is indeed the owner of the type, but dropping it.

pkg/ccl/backupccl/testdata/backup-restore/restore-permissions

@@ -9,7 +9,7 @@ INSERT INTO d.t VALUES (1), (2), (3);
 ----
 
 exec-sql
-BACKUP TO 'nodelocal://0/test/'
+BACKUP INTO 'nodelocal://0/test/'
 ----
 
 # Restores should succeed as a non-root user with admin role.

pkg/ccl/backupccl/testdata/backup-restore/row_level_ttl

@@ -8,11 +8,11 @@ CREATE TABLE t (id INT PRIMARY KEY) WITH (ttl_expire_after = '10 minutes')
 ----
 
 exec-sql
-BACKUP DATABASE d TO 'nodelocal://1/database_backup/'
+BACKUP DATABASE d INTO 'nodelocal://1/database_backup/'
 ----
 
 exec-sql
-BACKUP TO 'nodelocal://1/full_cluster_backup/'
+BACKUP INTO 'nodelocal://1/full_cluster_backup/'
 ----
 
 new-server name=s2 share-io-dir=s1 allow-implicit-access

pkg/ccl/backupccl/testdata/backup-restore/temp-tables

@@ -33,24 +33,24 @@ pg_temp
 public
 
 exec-sql
-BACKUP TABLE temp_table TO 'nodelocal://0/temp_table_backup'
+BACKUP TABLE temp_table INTO 'nodelocal://0/temp_table_backup'
 ----
 pq: failed to resolve targets specified in the BACKUP stmt: table "temp_table" does not exist, or invalid RESTORE timestamp: supplied backups do not cover requested time
 
 exec-sql
-BACKUP DATABASE d1 TO 'nodelocal://0/d1_backup/'
+BACKUP DATABASE d1 INTO 'nodelocal://0/d1_backup/'
 ----
 
 exec-sql
-BACKUP d1.* TO 'nodelocal://0/d1_star_backup/'
+BACKUP d1.* INTO 'nodelocal://0/d1_star_backup/'
 ----
 
 exec-sql
 COMMENT ON TABLE temp_table IS 'should not show up in restore';
 ----
 
 exec-sql
-BACKUP TO 'nodelocal://0/full_cluster_backup/';
+BACKUP INTO 'nodelocal://0/full_cluster_backup/';
 ----
 
 exec-sql

pkg/ccl/backupccl/testdata/backup-restore/user-defined-types

@@ -20,7 +20,7 @@ INSERT INTO d2.t2 VALUES (ARRAY['bye']), (ARRAY['cya']);
 ----
 
 exec-sql
-BACKUP TO 'nodelocal://0/test/'
+BACKUP INTO 'nodelocal://0/test/'
 ----
 
 # Start a new cluster with the same IO dir.
@@ -129,7 +129,7 @@ CREATE TABLE d.expr (
 
 # Backup the database now.
 exec-sql
-BACKUP DATABASE d TO 'nodelocal://0/test/'
+BACKUP DATABASE d INTO LATEST IN 'nodelocal://0/test/'
 ----
 
 exec-sql

pkg/ccl/backupccl/testdata/backup-restore/virtual-columns

@@ -18,7 +18,7 @@ INSERT INTO tab VALUES (1,1,1), (2,2,2), (3,3,3)
 ----
 
 exec-sql
-BACKUP TO 'nodelocal://0/test/'
+BACKUP INTO 'nodelocal://0/test/'
 ----
 
 # Start a new cluster with the same IO dir.