{"id":50771453,"url":"https://github.com/jasonlyle88/sqlcl-utilities","last_synced_at":"2026-06-11T19:01:40.398Z","repository":{"id":206726058,"uuid":"717560353","full_name":"jasonlyle88/sqlcl-utilities","owner":"jasonlyle88","description":"Generate shell aliases for TNS and LDAP connections","archived":false,"fork":false,"pushed_at":"2026-06-03T20:27:18.000Z","size":64,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-03T22:03:36.616Z","etag":null,"topics":["bash","bash-plugin","oracle","sqlcl","zsh","zsh-plugin"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jasonlyle88.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-11-11T20:53:14.000Z","updated_at":"2026-06-03T20:27:22.000Z","dependencies_parsed_at":"2023-11-27T23:30:49.817Z","dependency_job_id":"5890cfdd-7c61-436a-9ce6-9982af130a6d","html_url":"https://github.com/jasonlyle88/sqlcl-utilities","commit_stats":null,"previous_names":["jasonlyle88/sqlcl-connection-alias-generators","jasonlyle88/sqlcl-utilities"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jasonlyle88/sqlcl-utilities","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonlyle88%2Fsqlcl-utilities","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonlyle88%2Fsqlcl-utilities/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonlyle88%2Fsqlcl-utilities/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonlyle88%2Fsqlcl-utilities/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jasonlyle88","download_url":"https://codeload.github.com/jasonlyle88/sqlcl-utilities/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasonlyle88%2Fsqlcl-utilities/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34213179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bash-plugin","oracle","sqlcl","zsh","zsh-plugin"],"created_at":"2026-06-11T19:01:39.687Z","updated_at":"2026-06-11T19:01:40.385Z","avatar_url":"https://github.com/jasonlyle88.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SQLcl Utilities\n\n## Purpose\nThis plugin provides different utility functions to help you interact with [Oracle SQLcl](https://www.oracle.com/database/sqldeveloper/technologies/sqlcl/).\n\nOne function, `sqlclUpdater` helps you install and update SQLcl.\n\nAnother function, `sqlclConnectHelper` wraps a script around SQLcl to allow for unix style parameters to be passed to SQLcl.\n\n`sqlclGenerateTNSAliases` and `sqlclGenerateOIDAliases` generate BASH/ZSH shell aliases for connecting via SQLcl to Oracle databases defined in TNS files or OID LDAP servers.\n\nBy default, the generated aliases take the format of `sql.database_name`. However, the alias name is completely customizable via a prefix parameter or an alias name format function (or both!).\n\n### Utility Functions\n\n#### sqlclUpdater\n\u003cdetails\u003e\nThis function will download the latest version of Oracle SQLcl and unzip it into a given directory. The specific version of SQLcl downloaded is unzipped into a child directory or the given directory with the name of the SQLcl version. It additionally creates a symlink called 'latest' that points to the most recently downloaded version of SQLcl. You can also specify to create a symlink called 'live' that points to the most recently downloaded version of SQLcl as well as specify the number of versions of SQLcl to keep.\n\nIf you do not specify the directory to use for SQLcl downloads, `/opt/sqlcl` will be used. The `/opt` directory usually requires root permissions. Best practice would be to create the `/opt/sqlcl` directory and set the group permissions to allow for write and make sure you are a member of the group. Then you can work on SQLcl versions (update symlinks, download new versions, etc) without needing to use `sudo`.\n\u003c/details\u003e\n\n#### sqlclConnectHelper\n\u003cdetails\u003e\nThis function is a wrapper around the SQLcl CLI program. SQLcl uses the same connection syntax as SQLPlus, which is not super friendly to scripting. So, the `sqlclConnectHelper` function provides a unix-style parameter driven command line experience and then calls SQLcl with the provided information converted to a format that SQLcl understands.\n\nFor instance, a SQLcl connection may look like this:\n```shell\nsql -L -noupdates my_user/my_password@my_database\n```\n\nHowever, with the `sqlclConnectHelper` function, instead the connection could be made in any of the following ways:\n```shell\nsqlclConnectHelper -Lzu my_user -p my_password -i my_database\nsqlclConnectHelper -L -z -u my_user -p my_password -i my_database\nsqlclConnectHelper -zLi my_database -u my_user -p my_password\n```\n\nWhich allows information to be given in any order.\n\nThis wrapper script is used by the aliases generated by the `sqlclGenerateOIDAliases` and `sqlclGenerateTNSAliases` functions. This is necessary because the aliases are for known database connect identifiers, but the username is not specified until the user invokes the alias. Because this is backwards from the format expected by SQLcl (`user@database`), the helper script is used.\n\nThe wrapper script provides all the same functionality as the base SQLcl CLI program, though it uses all single letter options, so it is not an exact mapping. To see all the options for the `sqlclConnectHelper` function, simply run:\n```shell\nsqlclConnectHelper -h\n```\n\u003c/details\u003e\n\n#### sqlclGenerateOIDAliases\n\u003cdetails\u003e\nThis function outputs aliases for database connections collected from a provided OID LDAP server along with an additional header about the parameters used to generate the aliases.\n\nThe function accepts various information about the OID LDAP server to query as well as optional parameters of the SQLcl binary to use, the name of a custom function that prints to standard output additional aliases based on each database, as well as the name of a custom function that prints to standard output the alias to use for a given database connection alias.\n\nGiven that some LDAP servers limit the number of entities returned by the anonymous user, this function does not attempt to query all the available information in a single query call. Instead, it will first query all of the contexts (how databases are organized in an OID LDAP server). Then, the function will query each context individually for all the databases in that context. The function does the database queries in the background so they all may be done in parallel in order to improve performance. However, depending on the number of contexts and databases, this function may still take a little bit of time to run. With approximately 1100 databases spread across 80 contexts, the function takes approximately 50 seconds to run.\n\nAdditionally, the generated aliases set the `LDAPCON` variable that SQLcl uses for LDAP lookups for the specific connection. This way, if you have multiple LDAP servers, you do not have to manually update the `LDAPCON` variable when trying to connect to a database in a different LDAP.\n\u003c/details\u003e\n\n#### sqlclGenerateTNSAliases\n\u003cdetails\u003e\nThis function outputs aliases for database connections collected from a provided TNS names file or cloud wallet along wtih an additional header about the parameters used to generate the aliases.\n\nThe function accepts either a tnsnames.ora file in the standard oracle location, a file path pointing to a TNS names file, or a file path pointing to a cloud wallet zip file. It also optionally accepts parameters for the SQLcl binary to use, the name of a custom function that prints to standard output additional aliases based on each database, as well as the name of a custom function that prints to standard output the alias to use for a given database connection alias.\n\u003c/details\u003e\n\n## Requirements\n- A ZSH or BASH shell\n- SQLcl\n\n## Installation\n\n### Manual installation (ZSH)\n```shell\ngit clone 'https://github.com/jasonlyle88/sqlcl-utilities' \"${XDG_CONFIG_HOME:-${HOME}}/sqlcl-utilities\"\necho 'source \"${XDG_CONFIG_HOME:-${HOME}}/sqlcl-utilities/sqlcl-utilities.plugin.zsh\"' \u003e\u003e \"${HOME}/.zshrc\"\nsource \"${XDG_CONFIG_HOME:-${HOME}}/sqlcl-utilities/sqlcl-utilities.plugin.zsh\"\n```\n\n### Manual installation (BASH)\n```shell\ngit clone 'https://github.com/jasonlyle88/sqlcl-utilities' \"${XDG_CONFIG_HOME:-${HOME}}/sqlcl-utilities\"\necho 'source \"${XDG_CONFIG_HOME:-${HOME}}/sqlcl-utilities/sqlcl-utilities.plugin.bash\"' \u003e\u003e \"${HOME}/.bashrc\"\nsource \"${XDG_CONFIG_HOME:-${HOME}}/sqlcl-utilities/sqlcl-utilities.plugin.bash\"\n```\n\n### Installation with ZSH package managers\n\n#### [Antidote](https://getantidote.github.io/)\nAdd `jasonlyle88/sqlcl-utilities` to your plugins file (default is `~/.zsh_plugins.txt`)\n\n#### [Oh-My-Zsh](https://ohmyz.sh/)\n```shell\ngit clone 'https://github.com/jasonlyle88/sqlcl-utilities' \"${ZSH_CUSTOM:-${HOME}/.oh-my-zsh/custom}/plugins/sqlcl-utilities\"\nomz plugin enable sqlcl-utilities\n```\n\n#### Others\nThis should be compatible with other ZSH frameworks/package managers, but I have not tested them. If you have tested this plugin with another package manager, feel free to create a merge request and add the instructions here!\n\n## Usage\n\n### Additional alias generation functions\nIf you want to generate additional aliases, both the `sqlclGenerateOIDAliases` and `sqlclGenerateTNSAliases` functions accept function names that will be called for every database that is processed. The `sqlclGenerateOIDAliases` and `sqlclGenerateTNSAliases` both accept the function name through the `-a` parameter, but both provide slightly different information to your function. Below is the information provided by the functions:\n\n- `sqlclGenerateOIDAliases`\n    - Alias prefix (from the `-p` parameter)\n    - Alias name (Default alias name or the result of the `-f` alias format function)\n    - LDAP Context (lowercase)\n    - Database name (lowercase)\n    - Database connect string\n- `sqlclGenerateTNSAliases`\n    - Alias prefix (from the `-p` parameter)\n    - Alias name (Default alias name or the result of the `-f` alias format function)\n    - Net service name\n    - Cloud config zip file (absolute path) (if cloud config wallet)\n\nAn example where this is useful would be if you have APEX set up in each of the databases and want to be able to open the APEX builder in your browser of choice. This could be accomplished like the following example:\n\u003cdetails\u003e\n\n```shell\nfunction generateAPEXAliases() {\n    local prividedAliasPrefix=\"${1}\"\n    local providedAliasName=\"${2}\"\n    local netServiceName=\"${3}\"\n    local cloudConfigZip=\"${4}\"\n\n    local cloudConfigFilename=\"$(basename \"${cloudConfigZip}\" '.zip')\"\n    local apexUrl\n    local additionalAliasName\n    local browserBinary='/Applications/Firefox.app/Contents/MacOS/firefox'\n\n    # Figure out the base of the URL based on the wallet\n    if [[ \"${cloudConfigFilename}\" == 'Wallet_myatp1' ]]; then\n        apexUrl='https://g86c945163ece5c-myatp1.adb.us-ashburn-1.oraclecloudapps.com/ords/r/apex'\n    elif [[ \"${cloudConfigFilename}\" == 'Wallet_myatp2' ]]; then\n        apexUrl='https://g86c945163ece5c-myatp2.adb.us-ashburn-1.oraclecloudapps.com/ords/r/apex'\n    fi\n\n    # Replace \"sql.\" with \"apex.\" in the provided alias name\n    additionalAliasName=\"apex.${providedAliasName#\"sql.\"}\"\n\n    # Anything sent to standard out will be included with your generated alias file\n    printf 'alias %s=\"%s %s\"\\n' \\\n        \"${additionalAliasName}\" \\\n        \"${browserBinary}\" \\\n        \"${apexUrl}\"\n}\n\nsqlclGenerateTNSAliases \\\n    -p 'sql.myatp1.' \\\n    -a 'generateAPEXAliases' \\\n    -c \"${TNS_ADMIN}/wallets/Wallet_myatp1.zip\"\n\nsqlclGenerateTNSAliases \\\n    -p 'sql.myatp2.' \\\n    -a 'generateAPEXAliases' \\\n    -c \"${TNS_ADMIN}/wallets/Wallet_myatp2.zip\"\n```\n\n\u003c/details\u003e\n\n### Alias name formatting functions\nBy default, aliases are generated as `sql.database_name`, but this may not be your desired format. If you want just a static string before the `database_name` in the alias, then the `-p` parameter provides this functionality. Otherwise, the the `sqlclGenerateOIDAliases` and `sqlclGenerateTNSAliases` both accept the `-f` parameter that takes in a function that gives you complete control over how the alias is formatted. However, each plugin function provides slightly different information to your format function. Below is the information provided by the functions:\n\n- `sqlclGenerateOIDAliases`\n    - Alias prefix (from the `-p` parameter)\n    - LDAP Context (lowercase)\n    - Database name (lowercase)\n    - Database connect string\n- `sqlclGenerateTNSAliases`\n    - Alias prefix (from the `-p` parameter)\n    - Net service name\n    - Cloud config zip file (absolute path) (if cloud config wallet)\n\nExamples of where this is useful is if you are using a TNS names file you don't control or and LDAP server and you want to programattically change the names that are used for the databases. Here is an example:\n\u003cdetails\u003e\n\n```shell\nfunction formatLdapAliasNames() {\n    local aliasPrefix=\"${1}\"\n    local contextName=\"${2}\"\n    local databaseName=\"${3}\"\n    local databaseConnectIdentifier=\"${4}\"\n\n    local prefix='work_db_prefix'\n    local aliasName=\"${aliasPrefix}\"\n\n    # Add the database group (context) after the standard prefix\n    aliasName=\"${aliasName}${contextName}.\"\n\n    # Add the environment designator (DEV or QA) after the database group\n    # (context) and before the database name\n    if [[ \"${databaseName}\" == *'-dev' ]]; then\n        aliasName=\"${aliasName}dev.\"\n    elif [[ \"${databaseName}\" == *'-qa' ]]; then\n        aliasName=\"${aliasName}qa.\"\n    fi\n\n    # Add the database name without the environment designator (DEV or QA) to\n    # to the end of the alias name\n    if [[ \"${databaseName}\" == *'-dev' ]]; then\n        aliasName=\"${aliasName}${databaseName%????}\"\n    elif [[ \"${databaseName}\" == *'-qa' ]]; then\n        aliasName=\"${aliasName}${databaseName%???}\"\n    fi\n\n    # Output the alias name for the generation script to use\n    printf '%s\\n' \"${aliasName}\"\n}\n\nsqlclGenerateOIDAliases \\\n    -p 'sql.work.dev.' \\\n    -f 'formatLdapAliasNames' \\\n    -H 'ldap-dev.work.com' \\\n    -B 'dc=work,dc=com'\n\nsqlclGenerateOIDAliases \\\n    -p 'sql.work.qa.' \\\n    -f 'formatLdapAliasNames' \\\n    -H 'ldap-qa.work.com' \\\n    -B 'dc=work,dc=com'\n```\n\n\u003c/details\u003e\n\n### EVAL or SOURCE\nBecause the `sqlclGenerateOIDAliases` and `sqlclGenerateTNSAliases` functions output their information to standard output, the data must be captured and used. There are two general ways to do this:\n\n- Immediately run the output information with the `eval` command\n- Store the output information in a file and use the `source` command to load the contents of that file into your current session.\n\n#### EVAL\nUsing `eval` will immediately evaluate all the generated aliases, but those aliases are not saved for future terminals to use. This means that your aliases are the most up to date since they were parsed directly and added to your session; however it also means that the `sqlclGenerateOIDAliases` or `sqlclGenerateTNSAliases` functions must be run every time you start a new terminal session since the aliases are not saved anywhere.\n\nThis can generically be accomplished by doing the following:\n```shell\neval \"$([GENERATION_FUNCTION_INVOCATION])\"\n```\nWhere `[GENERATION_FUNCTION_INVOCATION]` is an invocation of `sqlclGenerateOIDAliases` or `sqlclGenerateTNSAliases` with parameters appropriate for what you want to generate.\n\nA specific example is:\n```shell\neval \"$(sqlclGenerateTNSAliases -T -p 'sql.tns.')\"\n```\nWhich will load aliases for a `tnsnames.ora` file in the standard location oracle expects with a prefix of `sql.tns.`.\n\n#### SOURCE\nUsing `source` requires you first save the aliases in a file that can then be loaded into your terminal session over and over again without having to run the `sqlclGenerateOIDAliases` or `sqlclGenerateTNSAliases` functions again. This allows for faster loading of your aliases since they don't need to be generated, but it also means that your aliases could be out of date if it has been a while since you ran the generation functions.\n\nThis can generically be accomplished by doing the following:\n```shell\n[GENERATION_FUNCTION_INVOCATION] \u003e ~/tnsnames_aliases.sh\nsource ~/tnsnames_aliases.sh\n```\n\nA specific example is:\n```shell\nsqlclGenerateTNSAliases -T -p 'sql.tns.' \u003e ~/tnsnames_aliases.sh\nsource ~/tnsnames_aliases.sh\n```\n\nThen, whenever you start a new terminal, you just need to run:\n```shell\nsource ~/tnsnames_aliases.sh\n```\nand all the generated aliases will be available to you again in your new terminal session.\n\n### Automatically adding aliases to your terminal session\nIf you want your aliases to be available as soon as your terminal loads, you can add code to your `.bashrc`, `.bash_profile`, `.zshrc`, or any file you run when your shell starts. This will be specific to your machine and which file to use is outside the scope of this document. There are tons of resources avialable if your google it though!\n\nUsing the `eval` method in such a file will provide the most up to date aliases but may slow down your terminal starting up. If you create and `eval` with a call to `sqlclGenerateOIDAliases` that takes 30 seconds, then you are adding 30 seconds to your shell startup before you are able to use your terminal.\n\nUsing the `source` method, you only need to put the `source` command in your startup file. This will be very fast, but your aliases may be out of date if the database inormation has changed. To update the information, the generation functions will need to be run again (in our example, `sqlclGenerateTNSAliases -T -p 'sql.tns.' \u003e ~/tnsnames_aliases.sh`).\n\n### My approach\nI personally use the source approach because my OID LDAP generation can take a while. In order to make updating the file containing the generated aliases easier, I create a function that generates the aliases for me. In order to accomplish this, I add the following to my `.zshrc` file:\n```shell\nexport SQLCL_ALIAS_FILE=\"${HOME}/.config/sqlclAliases.sh\"\n\nfunction generateSqlclAliases() {\n    sqlclGenerateTNSAliases -T \u003e \"${SQLCL_ALIAS_FILE}\"\n\n    sqlclGenerateTNSAliases -c \"${TNS_ADMIN}/wallets/Wallet_db1.zip\" -p 'sql.db1.' \u003e\u003e \"${SQLCL_ALIAS_FILE}\"\n\n    sqlclGenerateTNSAliases -c \"${TNS_ADMIN}/wallets/Wallet_db2.zip\" -p 'sql.db2.' \u003e\u003e \"${SQLCL_ALIAS_FILE}\"\n\n    sqlclGenerateOIDAliases -h \"${WORK_DATABASE_LDAP_HOST}\" -p 'sql.work.' \u003e\u003e \"${SQLCL_ALIAS_FILE}\"\n\n    source \"${SQLCL_ALIAS_FILE}\"\n}\n\nif [[ -f \"${SQLCL_ALIAS_FILE}\" ]]; then\n    source \"${SQLCL_ALIAS_FILE}\"\nfi\n```\n\nThis allows all my new terminal sessions to automatically have all my SQLcl aliases loaded from the last time they were generated. And any time I need to refresh the alias generation, I just run the `generateSqlclAliases` function.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonlyle88%2Fsqlcl-utilities","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjasonlyle88%2Fsqlcl-utilities","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonlyle88%2Fsqlcl-utilities/lists"}