Hive Schema Tool

Hive Schema Tool은 메타스토어 데이터베이스와 Hive 시스템 스키마(system schema)를 초기화하고 업그레이드하는 데 사용하는 도구예요. 새 Hive를 설치하거나 기존 Hive의 메타스토어 스키마 버전을 올릴 때 꼭 필요한 도구입니다.

출처: 문서

본문

소개 (About)

스키마 도구는 메타스토어 데이터베이스와 Hive 시스템 스키마를 초기화하고 업그레이드하는 데 도움을 줍니다.

메타스토어 스키마 검증 (Metastore Schema Verification)

Hive 0.12.0에서 도입되었습니다. (HIVE-3764 참조)

Hive는 메타스토어 데이터베이스에 스키마 버전을 기록하고, 메타스토어에 접근할 Hive 바이너리와 메타스토어 스키마 버전이 호환되는지 검증합니다. 스키마를 암시적으로 생성하거나 변경하는 Hive 속성은 기본적으로 비활성화되어 있습니다. Hive는 메타스토어 스키마를 암시적으로 변경하려 하지 않습니다. 오래된 스키마에 대해 Hive 쿼리를 실행하면 메타스토어에 접근하지 못하고 실패합니다:

$ build/dist/bin/hive -e "show tables"
FAILED: Execution Error, return code 1 from org.apache.hadoop.hive.ql.exec.DDLTask. java.lang.RuntimeException: Unable to instantiate org.apache.hadoop.hive.metastore.HiveMetaStoreClient

...
Caused by: MetaException(message:Version information not found in metastore. )
...

메타스토어에 대한 일반적인 정보는 Hive Metastore Administration 문서를 참고하세요.

Hive Schema Tool

Hive 0.12.0에서 도입되었습니다. (HIVE-5301 참조, 버그 수정은 HIVE-5449 참조)

Hive 배포판에는 이제 Hive 메타스토어 스키마를 조작하기 위한 오프라인 도구가 포함되어 있습니다. 이 도구는 현재 Hive 버전에 맞게 메타스토어 스키마를 초기화하는 데 사용할 수 있습니다. 또한 스키마를 이전 버전에서 현재 버전으로 업그레이드하는 것도 처리할 수 있습니다. 메타스토어에서 현재 스키마를 찾을 수 있다면 그 스키마를 찾으려고 시도합니다. 이는 0.12.0에서 0.13.0으로의 향후 업그레이드에도 적용됩니다. 0.7.0이나 0.10.0 같은 이전 릴리스에서 업그레이드하는 경우에는 기존 메타스토어의 스키마 버전을 명령줄 옵션으로 도구에 지정할 수 있습니다.

schematool은 스키마를 초기화하거나 업그레이드하는 데 필요한 SQL 스크립트를 찾아내고, 그 스크립트들을 백엔드 데이터베이스에 대해 실행합니다. JDBC URL, JDBC 드라이버, DB 자격 증명 같은 메타스토어 DB 연결 정보는 Hive 설정에서 추출됩니다. 필요한 경우 대체 DB 자격 증명을 제공할 수 있습니다.

경고 (Warning): 메타스토어 스키마를 항상 먼저 초기화하고 Hive 스키마를 그 다음에 초기화해야 합니다. Hive 스키마 초기화는 메타스토어 데이터베이스 스키마를 검사하며, 초기화되지 않았다면 Hive 스키마가 실행 중인지 확인하기 위해 메타스토어 데이터베이스에도 일부 객체를 넣습니다. 또한 Hive 스키마 초기화 후에 메타스토어 스키마 초기화를 실행하려 하면, 이미 일부 객체를 포함한 데이터베이스를 발견하므로 실패한다는 의미이기도 합니다.

`schematool` 명령 (The schematool Command)

schematool 명령은 다음 옵션으로 Hive 스키마 도구를 호출합니다:

usage: schemaTool
 -alterCatalog <arg>                Alter a catalog, requires
                                    --catalogLocation and/or
                                    --catalogDescription parameter as well
 -catalogDescription <arg>          Description of new catalog
 -catalogLocation <arg>             Location of new catalog, required when
                                    adding a catalog
 -createCatalog <arg>               Create a catalog, requires
                                    --catalogLocation parameter as well
 -createLogsTable <arg>             Create table for Hive
                                    warehouse/compute logs
 -createUser                        Create the Hive user, set hiveUser to
                                    the db admin user and the hive
                                    password to the db admin password with
                                    this
 -dbOpts <databaseOpts>             Backend DB specific options
 -dbType <databaseType>             Metastore database type
 -driver <driver>                   driver name for connection
 -dropAllDatabases                  Drop all Hive databases (with
                                    CASCADE). This will remove all managed
                                    data!
 -dryRun                            list SQL scripts (no execute)
 -fromCatalog <arg>                 Catalog a moving database or table is
                                    coming from.  This is required if you
                                    are moving a database or table.
 -fromDatabase <arg>                Database a moving table is coming
                                    from.  This is required if you are
                                    moving a table.
 -help                              print this message
 -hiveDb <arg>                      Hive database (for use with
                                    createUser)
 -hivePassword <arg>                Hive password (for use with
                                    createUser)
 -hiveUser <arg>                    Hive user (for use with createUser)
 -ifNotExists                       If passed then it is not an error to
                                    create an existing catalog
 -info                              Show config and schema details
 -initOrUpgradeSchema               Initialize or upgrade schema to latest
                                    version
 -initSchema                        Schema initialization
 -initSchemaTo <initTo>             Schema initialization to a version
 -mergeCatalog <arg>                Merge databases from a catalog into
                                    other, Argument is the source catalog
                                    name Requires --toCatalog to indicate
                                    the destination catalog
 -metaDbType <metaDatabaseType>     Used only if upgrading the system
                                    catalog for hive
 -moveDatabase <arg>                Move a database between catalogs.
                                    Argument is the database name.
                                    Requires --fromCatalog and --toCatalog
                                    parameters as well
 -moveTable <arg>                   Move a table to a different database.
                                    Argument is the table name. Requires
                                    --fromCatalog, --toCatalog,
                                    --fromDatabase, and --toDatabase
                                    parameters as well.
 -passWord <password>               Override config file password
 -retentionPeriod <arg>             Specify logs table retention period
 -servers <serverList>              a comma-separated list of servers used
                                    in location validation in the format
                                    of scheme://authority (e.g.
                                    hdfs://localhost:8000)
 -toCatalog <arg>                   Catalog a moving database or table is
                                    going to.  This is required if you are
                                    moving a database or table.
 -toDatabase <arg>                  Database a moving table is going to.
                                    This is required if you are moving a
                                    table.
 -upgradeSchema                     Schema upgrade
 -upgradeSchemaFrom <upgradeFrom>   Schema upgrade from a version
 -url <url>                         connection url to the database
 -userName <user>                   Override config file user name
 -validate                          Validate the database
 -verbose                           only print SQL statements
 -yes                               Don't ask for confirmation when using
                                    -dropAllDatabases.

derby|mysql|postgres|oracle|mssql|hive

참고: dbType=hive는 Hive 시스템 스키마에만 사용할 수 있습니다. 나머지는 메타스토어 DB 타입이며, dbType=hive의 경우에는 metaDbType도 반드시 설정해야 합니다. 즉:

schematool -dbType derby -initSchema
schematool -dbType hive -initSchema -metaDbType derby

새 Hive 구성을 위해 현재 스키마로 초기화하기:

$ schematool -dbType derby -initSchema

Initializing the schema to: 4.2.0
2025-10-14 16:21:20,427 INFO schematool.HiveSchemaHelper: Metastore connection URL:	 jdbc:derby:metastore_db;create=true
Metastore connection URL:	 jdbc:derby:metastore_db;create=true
2025-10-14 16:21:20,427 INFO schematool.HiveSchemaHelper: Metastore connection Driver :	 org.apache.derby.iapi.jdbc.AutoloadedDriver
Metastore connection Driver :	 org.apache.derby.iapi.jdbc.AutoloadedDriver
2025-10-14 16:21:20,427 INFO schematool.HiveSchemaHelper: Metastore connection User:	 APP
Metastore connection User:	 APP
Starting metastore schema initialization to 4.2.0
Initialization script hive-schema-4.2.0.derby.sql
...
Initialization script completed

$ schematool -dbType derby -info

2025-10-14 16:29:13,116 INFO schematool.HiveSchemaHelper: Metastore connection URL:	 jdbc:derby:metastore_db;create=true
Metastore connection URL:	 jdbc:derby:metastore_db;create=true
2025-10-14 16:29:13,116 INFO schematool.HiveSchemaHelper: Metastore connection Driver :	 org.apache.derby.iapi.jdbc.AutoloadedDriver
Metastore connection Driver :	 org.apache.derby.iapi.jdbc.AutoloadedDriver
2025-10-14 16:29:13,116 INFO schematool.HiveSchemaHelper: Metastore connection User:	 APP
Metastore connection User:	 APP
Hive distribution version:	 4.2.0
Metastore schema version:	 4.2.0

$ schematool -dbType derby -initSchemaTo 3.1.0

2025-10-14 16:37:11,089 INFO schematool.HiveSchemaHelper: Metastore connection URL:	 jdbc:derby:metastore_db;create=true
Metastore connection URL:	 jdbc:derby:metastore_db;create=true
2025-10-14 16:37:11,089 INFO schematool.HiveSchemaHelper: Metastore connection Driver :	 org.apache.derby.iapi.jdbc.AutoloadedDriver
Metastore connection Driver :	 org.apache.derby.iapi.jdbc.AutoloadedDriver
2025-10-14 16:37:11,089 INFO schematool.HiveSchemaHelper: Metastore connection User:	 APP
Metastore connection User:	 APP
Starting metastore schema initialization to 3.1.0
Initialization script hive-schema-3.1.0.derby.sql
...
Initialization script completed

$ schematool -dbType derby -upgradeSchemaFrom 3.1.0

Upgrading from the user input version 3.1.0
2025-10-14 16:41:04,018 INFO schematool.HiveSchemaHelper: Metastore connection URL:	 jdbc:derby:metastore_db;create=true
Metastore connection URL:	 jdbc:derby:metastore_db;create=true
2025-10-14 16:41:04,018 INFO schematool.HiveSchemaHelper: Metastore connection Driver :	 org.apache.derby.iapi.jdbc.AutoloadedDriver
Metastore connection Driver :	 org.apache.derby.iapi.jdbc.AutoloadedDriver
2025-10-14 16:41:04,018 INFO schematool.HiveSchemaHelper: Metastore connection User:	 APP
Metastore connection User:	 APP
Starting upgrade metastore schema from version 3.1.0 to 4.2.0
Upgrade script upgrade-3.1.0-to-3.2.0.derby.sql
2025-10-14 16:41:04,142 INFO conf.HiveConf: Found configuration file file:/Users/raghav/Desktop/setup/hive/conf/hive-site.xml
2025-10-14 16:41:04,143 INFO conf.HiveConf: Found configuration file null
2025-10-14 16:41:04,143 INFO conf.HiveConf: Found configuration file null
2025-10-14 16:41:04,143 INFO conf.HiveConf: Found configuration file null
2025-10-14 16:41:04,173 WARN util.NativeCodeLoader: Unable to load native-hadoop library for your platform... using builtin-java classes where applicable
Completed upgrade-3.1.0-to-3.2.0.derby.sql
Upgrade script upgrade-3.2.0-to-4.0.0-alpha-1.derby.sql
Completed upgrade-3.2.0-to-4.0.0-alpha-1.derby.sql
Upgrade script upgrade-4.0.0-alpha-1-to-4.0.0-alpha-2.derby.sql
Completed upgrade-4.0.0-alpha-1-to-4.0.0-alpha-2.derby.sql
Upgrade script upgrade-4.0.0-alpha-2-to-4.0.0-beta-1.derby.sql
Completed upgrade-4.0.0-alpha-2-to-4.0.0-beta-1.derby.sql
Upgrade script upgrade-4.0.0-beta-1-to-4.0.0.derby.sql
Completed upgrade-4.0.0-beta-1-to-4.0.0.derby.sql
Upgrade script upgrade-4.0.0-to-4.1.0.derby.sql
Completed upgrade-4.0.0-to-4.1.0.derby.sql
Upgrade script upgrade-4.1.0-to-4.2.0.derby.sql
Completed upgrade-4.1.0-to-4.2.0.derby.sql

$ schematool -dbType derby -upgradeSchemaFrom 3.1.0 -dryRun

Upgrading from the user input version 3.1.0
2025-10-14 16:43:16,211 INFO schematool.HiveSchemaHelper: Metastore connection URL:	 jdbc:derby:metastore_db;create=true
Metastore connection URL:	 jdbc:derby:metastore_db;create=true
2025-10-14 16:43:16,211 INFO schematool.HiveSchemaHelper: Metastore connection Driver :	 org.apache.derby.iapi.jdbc.AutoloadedDriver
Metastore connection Driver :	 org.apache.derby.iapi.jdbc.AutoloadedDriver
2025-10-14 16:43:16,211 INFO schematool.HiveSchemaHelper: Metastore connection User:	 APP
Metastore connection User:	 APP
Starting upgrade metastore schema from version 3.1.0 to 4.2.0
Upgrade script upgrade-3.1.0-to-3.2.0.derby.sql
Upgrade script upgrade-3.2.0-to-4.0.0-alpha-1.derby.sql
Upgrade script upgrade-4.0.0-alpha-1-to-4.0.0-alpha-2.derby.sql
Upgrade script upgrade-4.0.0-alpha-2-to-4.0.0-beta-1.derby.sql
Upgrade script upgrade-4.0.0-beta-1-to-4.0.0.derby.sql
Upgrade script upgrade-4.0.0-to-4.1.0.derby.sql
Upgrade script upgrade-4.1.0-to-4.2.0.derby.sql

기본 Hive 카탈로그에서 사용자 지정 spark 카탈로그로 데이터베이스와 그 아래 테이블을 이동하기:

build/dist/bin/schematool -moveDatabase db1 -fromCatalog hive -toCatalog spark

# Create the desired target database in spark catalog if it doesn't already exist.
beeline ... -e "create database if not exists newdb";
schematool -moveDatabase newdb -fromCatalog hive -toCatalog spark

# Now move the table to target db under the spark catalog.
schematool -moveTable table1 -fromCatalog hive -toCatalog spark  -fromDatabase db1 -toDatabase newdb

더 알아보기 (Learn more)

메타스토어 스키마는 초기화→업그레이드 순서로 관리해요. -dryRun 옵션으로 실제 실행 없이 필요한 SQL 스크립트 목록만 확인할 수 있어요. 카탈로그(catalog) 간 데이터베이스·테이블 이동은 -moveDatabase/-moveTable로 처리합니다.

Hive Schema Tool

Hive Schema Tool

본문

소개 (About)

메타스토어 스키마 검증 (Metastore Schema Verification)

Hive Schema Tool

schematool 명령 (The schematool Command)

더 알아보기 (Learn more)

`schematool` 명령 (The schematool Command)